Contributing Guide - cc-statusline

Learn more about Mintlify

Enter your email to receive updates about new features and product releases.

Quick Start
Development Workflow
1. Create a Feature Branch
2. Make Your Changes
3. Test Your Changes
4. Commit Your Changes
5. Push and Create Pull Request
Commit Message Format
Format
Types
Examples
Types of Contributions
Bug Reports
Feature Requests
Code Contributions
Code Standards
TypeScript
Code Style
File Structure
Testing Requirements
Manual Testing
Test Checklist
Adding Tests
Documentation Requirements
README Updates
Code Documentation
Pull Request Process
Before Submitting
Pull Request Template
Review Process
Community Guidelines
Be Respectful
Be Helpful
Keep It Simple
Recognition
Development Commands
Build Commands
Testing Commands
Getting Help
License
Next Steps

Thank you for your interest in contributing to cc-statusline! This guide provides everything you need to get started.

Quick Start

Fork the Repository

Clone Your Fork

git clone https://github.com/YOUR-USERNAME/cc-statusline.git
cd cc-statusline

Install Dependencies

npm install

Build the Project

npm run build

Test Your Changes

./dist/index.js --help
npx . init --no-install  # Test locally

Development Workflow

1. Create a Feature Branch

git checkout -b feature/amazing-feature

2. Make Your Changes

Follow our coding standards (see below) and make your improvements.

3. Test Your Changes

# Build the project
npm run build

# Test the CLI
./dist/index.js init --output ./test-statusline.sh --no-install

# Preview the generated statusline
./dist/index.js preview ./test-statusline.sh

4. Commit Your Changes

git add .
git commit -m "feat: add amazing feature"

See Commit Message Format below.

5. Push and Create Pull Request

git push origin feature/amazing-feature

Then open a pull request on GitHub.

Commit Message Format

We follow Conventional Commits specification:

Format

type: description

[optional body]

[optional footer]

Types

Type	Description	Example
`feat:`	New features	`feat: add support for Python runtime`
`fix:`	Bug fixes	`fix: resolve preview timeout issue`
`docs:`	Documentation changes	`docs: update README installation guide`
`style:`	Code style changes (formatting, etc.)	`style: fix indentation in generator`
`refactor:`	Code refactoring	`refactor: simplify JSON parsing logic`
`test:`	Adding tests	`test: add concurrent locking tests`
`chore:`	Maintenance tasks	`chore: update dependencies`

Examples

feat: add context window progress bar

Adds visual progress bar showing remaining context percentage.
Uses 10-character bar with dynamic colors based on usage.

Types of Contributions

Bug Reports

Report a Bug

Use GitHub Issues with the bug template

Include:

Steps to reproduce
Expected vs actual behavior
Sample statusline.sh if relevant
OS and Node.js version
jq version (if applicable)

Example:

**Environment:**
- OS: macOS 14.2
- Node.js: v20.10.0
- jq: 1.6
- cc-statusline: 1.4.0

**Steps to Reproduce:**
1. Run `cc-statusline init`
2. Select "context" feature
3. Preview shows "TBD" instead of percentage

**Expected:** Should show context percentage
**Actual:** Shows "TBD"

Feature Requests

Request a Feature

Use GitHub Issues with the feature template

Include:

Use case description
Expected behavior
Implementation complexity estimate
Alignment with “dead simple” philosophy

Example:

**Feature:** Add model temperature display

**Use Case:** 
Users want to see current temperature setting to track when using different configurations.

**Proposed Implementation:**
- Extract from JSON: `.model.temperature`
- Display as: 🌡️ 0.7
- Color: warm colors for high temp, cool for low

**Complexity:** Low (similar to model display)

Code Contributions

New Features
Bug Fixes
Documentation

Process:

Open an issue first to discuss the feature
Wait for maintainer approval
Implement following code standards
Add tests and documentation
Submit pull request

Best Practices:

Keep features simple and focused
Add graceful fallbacks
Consider performance impact
Update documentation

Code Standards

TypeScript

Strict Typing

All functions must have type hints:

// ✅ Good
export function generateBashStatusline(config: StatuslineConfig): string {
  const hasGit: boolean = config.features.includes('git')
  return script
}

// ❌ Bad
export function generateBashStatusline(config) {
  const hasGit = config.features.includes('git')
  return script
}

ESM Modules

Use import/export syntax with .js extensions:

// ✅ Good
import { StatuslineConfig } from '../cli/prompts.js'
import { generateColorBashCode } from '../features/colors.js'

// ❌ Bad
import { StatuslineConfig } from '../cli/prompts'
const colors = require('../features/colors')

Error Handling

Always handle errors gracefully:

// ✅ Good
try {
  const content = await fs.readFile(path, 'utf-8')
  return JSON.parse(content)
} catch (error) {
  console.error('Failed to read settings:', error.message)
  return defaultSettings
}

// ❌ Bad
const content = await fs.readFile(path, 'utf-8')
return JSON.parse(content)  // May crash

Code Style

Indentation: 2 spaces (no tabs) Semicolons: Not used (follows project style) Naming Conventions:

Functions: camelCase
Types/Interfaces: PascalCase
Constants: UPPER_SNAKE_CASE
Variables: camelCase

Comments:

Explain “why”, not “what”
Document complex algorithms
Add JSDoc for public APIs

Example:

// ✅ Good comment
// Use double escaping because TypeScript template literals need \\
// and bash needs \" for quotes in grep patterns
const pattern = `\\"\\ ${field}\\"`

// ❌ Bad comment
// Set the pattern variable
const pattern = `\\"\\ ${field}\\"`

File Structure

src/
├── cli/           # CLI commands and prompts
│   ├── commands.ts
│   └── prompts.ts
├── features/      # Feature-specific code
│   ├── colors.ts
│   ├── git.ts
│   └── usage.ts
├── generators/    # Script generators
│   └── bash-generator.ts
└── utils/         # Utilities
    ├── installer.ts
    ├── validator.ts
    └── tester.ts

Rules:

Keep related code together
One feature per file
Utilities in utils/
Generators in generators/

Testing Requirements

Manual Testing

Build

npm run build

Test CLI

./dist/index.js init --output ./test-statusline.sh --no-install

Test Preview

./dist/index.js preview ./test-statusline.sh

Test Different Configurations

Try various feature combinations, themes, and color settings

Test Checklist

With jq: All features work
Without jq: Graceful fallback
With colors: Proper ANSI codes
Without colors: Clean output (NO_COLOR=1)
In git repo: Git features work
Outside git: Git features skip
Different themes: minimal, compact, modern
Edge cases: Invalid JSON, empty input, missing fields
Performance: Execution time < 100ms

Adding Tests

When adding new features:

Update src/utils/tester.ts with mock data
Add test cases for new functionality
Test backwards compatibility
Verify error conditions

Documentation Requirements

README Updates

When adding features, update:

Features list
Example outputs
Configuration options
Troubleshooting section (if needed)

Code Documentation

Add JSDoc comments for public APIs:

/**
 * Generates a bash statusline script based on user configuration
 * 
 * @param config - User preferences for features, theme, and colors
 * @returns Complete bash script as string with shebang
 * 
 * @example
 * ```typescript
 * const script = generateBashStatusline({
 *   features: ['git', 'directory'],
 *   theme: 'compact',
 *   colors: true
 * })
 * ```
 */
export function generateBashStatusline(config: StatuslineConfig): string {
  // ...
}

Pull Request Process

Before Submitting

Pull Request Template

## Description
Brief description of changes and motivation

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Refactoring

## Testing
- [ ] Tested locally with `npm run build`
- [ ] Preview command works: `./dist/index.js preview`
- [ ] Tested with different configurations
- [ ] Updated tests if needed
- [ ] Documentation updated

## Screenshots/Examples
(If applicable, add screenshots or example output)

## Checklist
- [ ] Follows code style guidelines
- [ ] Self-review completed
- [ ] CHANGELOG.md updated (if user-facing change)
- [ ] No breaking changes (or documented if necessary)

Review Process

Maintainer review: Usually within 1-3 days
Feedback addressed: Make requested changes
Approval: Once approved, will be merged
Release: Included in next version

Community Guidelines

Be Respectful

Use welcoming and inclusive language
Respect different viewpoints and experiences
Accept constructive feedback gracefully
Focus on what is best for the community

Be Helpful

Help newcomers get started
Share knowledge and best practices
Collaborate openly and transparently
Provide constructive feedback

Keep It Simple

Follow the “dead simple” philosophy
Avoid over-engineering solutions
Prioritize user experience
Maintain fast execution times

Recognition

Contributors are recognized through:

CHANGELOG.md: Listed for their contributions
Release notes: Mentioned for significant features
README: Added to contributors section
Community: Welcomed and appreciated

Development Commands

Build Commands

# Production build
npm run build

# Watch mode for development
npm run dev

# Test the built CLI
npm run start

Testing Commands

# Test CLI locally
./dist/index.js init --no-install
./dist/index.js preview ./test-statusline.sh

# Test as if installed globally
npx . init

# Test with mock data
./test_debug.sh

# Run installation tests
./test/test-installation.sh

# Test concurrent locking
./test/test-concurrent-locking.sh

Getting Help

GitHub Issues

For bugs and feature requests

GitHub Discussions

For questions and ideas

Email: [email protected] for private matters

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for helping make cc-statusline better! 🚀

Next Steps

Architecture

Understand the codebase structure

Testing

Learn how to test your changes

Testing Guide

ccusage Integration

⌘I

Build docs developers (and LLMs) love

Get started for free Talk to us

Development

Integration

​Quick Start

​Development Workflow

​1. Create a Feature Branch

​2. Make Your Changes

​3. Test Your Changes

​4. Commit Your Changes

​5. Push and Create Pull Request

​Commit Message Format

​Format

​Types

​Examples

​Types of Contributions

​Bug Reports

Report a Bug

​Feature Requests

Request a Feature

​Code Contributions

​Code Standards

​TypeScript

​Code Style

​File Structure

​Testing Requirements

​Manual Testing

​Test Checklist

​Adding Tests

​Documentation Requirements

​README Updates

​Code Documentation

​Pull Request Process

​Before Submitting

​Pull Request Template

​Review Process

​Community Guidelines

​Be Respectful

​Be Helpful

​Keep It Simple

​Recognition

​Development Commands

​Build Commands

​Testing Commands

​Getting Help

GitHub Issues

GitHub Discussions

​License

​Next Steps

Architecture

Testing

Build docs developers (and LLMs) love

Quick Start

Development Workflow

1. Create a Feature Branch

2. Make Your Changes

3. Test Your Changes

4. Commit Your Changes

5. Push and Create Pull Request

Commit Message Format

Format

Types

Examples

Types of Contributions

Bug Reports

Feature Requests

Code Contributions

Code Standards

TypeScript

Code Style

File Structure

Testing Requirements

Manual Testing

Test Checklist

Adding Tests

Documentation Requirements

README Updates

Code Documentation

Pull Request Process

Before Submitting

Pull Request Template

Review Process

Community Guidelines

Be Respectful

Be Helpful

Keep It Simple

Recognition

Development Commands

Build Commands

Testing Commands

Getting Help

License

Next Steps