claude-code-status-line 1.2.10

# Development

Contributing, building from source, and development guidelines.

## 🤝 Contributing

We welcome contributions! Here's how to get started.

### Ways to Contribute

- 🐛 **Report bugs** - [Open an issue](https://github.com/ndave92/claude-code-status-line/issues)
- ✨ **Suggest features** - [Start a discussion](https://github.com/ndave92/claude-code-status-line/discussions)
- 📝 **Improve documentation** - Submit a PR for wiki or README updates
- 🎨 **Share themes** - Post your color schemes in discussions
- 💻 **Submit code** - Fix bugs or implement features

### Before Contributing

1. Check [existing issues](https://github.com/ndave92/claude-code-status-line/issues)
2. For major changes, open an issue or discussion first
3. Follow the code style (enforced by `rustfmt` and `clippy`)

---

## 🛠️ Development Setup

### Prerequisites

- **Rust** (stable toolchain)

  macOS / Linux:
  ```bash
  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  ```

  Windows: Download and run [rustup-init.exe](https://rustup.rs/)

- **Git**
- **Claude Code** (for testing)

### Clone and Build

```bash
# Clone the repository
git clone https://github.com/ndave92/claude-code-status-line.git
cd claude-code-status-line

# Build debug version
cargo build

# Build release version
cargo build --release

# Run tests
cargo test

# Check formatting
cargo fmt --all -- --check

# Run linter
cargo clippy --all-targets --all-features -- -D warnings
```

### Development Workflow

```bash
# Create a feature branch
git checkout -b feature/my-feature

# Make changes and test
cargo build
cargo test

# Format code
cargo fmt --all

# Check for issues
cargo clippy --all-targets --all-features

# Run validation script
bash scripts/validate.sh

# Commit and push
git add .
git commit -m "Description of changes"
git push origin feature/my-feature
```

---

## 🏗️ Project Structure

```
claude-code-status-line/
├── src/
│   ├── main.rs           # Entry point
│   ├── lib.rs            # Library interface
│   ├── config.rs         # Configuration loading
│   ├── colors.rs         # Color definitions
│   ├── statusline.rs     # Main statusline logic
│   ├── render.rs         # Rendering functions
│   ├── context.rs        # Context usage handling
│   ├── quota.rs          # Quota API integration
│   ├── git.rs            # Git information
│   ├── types.rs          # Common types
│   └── utils.rs          # Utility functions
├── docs/
│   └── wiki/             # Wiki content
├── scripts/
│   ├── validate.sh       # Validation script
│   └── quick-check.sh    # Quick checks
├── .claude/
│   └── commands/         # Claude Code commands
│       ├── manifest.json              # Command version tracking
│       ├── install-statusline.md
│       ├── customize-statusline.md
│       ├── update-statusline.md
│       └── uninstall-statusline.md
├── .github/
│   └── workflows/        # CI/CD workflows
│       ├── ci.yml
│       ├── release.yml
│       └── publish-crates.yml
├── Cargo.toml            # Dependencies and metadata
├── settings.json           # Example config
├── colors.json           # Example colors
└── README.md
```

### Module Overview

- **main.rs** - Reads JSON input from stdin, parses it, and renders the status line
- **config.rs** - Loads and validates `settings.json` and `colors.json`
- **statusline.rs** - Orchestrates section rendering and layout
- **render.rs** - ANSI escape code generation for colors and styling
- **quota.rs** - Quota formatting and OAuth usage-endpoint fallback (payload `rate_limits` is the primary source)
- **git.rs** - Detects git branch and status
- **context.rs** - Calculates context usage percentages
- **utils.rs** - Text truncation, width calculation, etc.

---

## 🧪 Testing

### Run Tests

```bash
# All tests
cargo test

# Specific test
cargo test test_name

# With output
cargo test -- --nocapture

# Documentation tests
cargo test --doc
```

### Manual Testing

Test with sample input:

```bash
# Build
cargo build

# Test with sample data
echo '{"workspace":{"current_dir":"/Users/test/project"},"model":{"display_name":"Sonnet 4.5"},"context_window":{"context_window_size":200000,"current_usage":{"input_tokens":15000}}}' | ./target/debug/claude-code-status-line
```

### Test with Claude Code

1. Build the binary
2. Update your `~/.claude/settings.json` to point to the debug binary:
   ```json
   {
     "statusLine": {
       "type": "command",
       "command": "/path/to/claude-code-status-line/target/debug/claude-code-status-line",
       "padding": 0
     }
   }
   ```
3. Restart Claude Code
4. Make changes and rebuild (`cargo build`)
5. Restart Claude Code to see changes

---

## 📋 Code Style

### Formatting

Use `rustfmt` for consistent formatting:

```bash
# Format all code
cargo fmt --all

# Check without modifying
cargo fmt --all -- --check
```

### Linting

Use `clippy` for best practices:

```bash
# Run clippy
cargo clippy --all-targets --all-features

# Deny warnings
cargo clippy --all-targets --all-features -- -D warnings
```

### Style Guidelines

- Use descriptive variable names
- Add comments for complex logic
- Keep functions focused and small
- Use Rust idioms (Result, Option, iterators)
- Prefer immutability when possible
- Handle errors gracefully

---

## 🔄 Validation Script

Run the full validation suite before committing:

**macOS / Linux:**
```bash
bash scripts/validate.sh
```

**Windows:**

Using Git Bash (recommended):
```bash
bash scripts/validate.sh
```

Or run manually in PowerShell:
```powershell
cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo build --release
```

This runs:
1. Code formatting (with auto-fix)
2. Clippy checks
3. All tests
4. Release build

---

## 📦 Release Process

### Version Bumping

1. Update version in `Cargo.toml`
2. Update version in `Cargo.lock`:
   ```bash
   cargo build
   ```
3. Commit changes:
   ```bash
   git add Cargo.toml Cargo.lock
   git commit -m "Bump version to X.Y.Z"
   ```

### Creating a Release

1. **Merge to master:**
   ```bash
   git checkout master
   git merge dev
   git push origin master
   ```

2. **Create GitHub release:**
   ```bash
   gh release create vX.Y.Z \
     --title "vX.Y.Z" \
     --notes "Release notes here"
   ```

3. **Automated workflows run:**
   - Build binaries for all platforms
   - Publish to crates.io
   - Attach binaries to GitHub release

### Release Checklist

- [ ] Version bumped in Cargo.toml
- [ ] Command versions updated (see below)
- [ ] CHANGELOG updated (if exists)
- [ ] All tests pass (`cargo test`)
- [ ] Validation script passes (`bash scripts/validate.sh`)
- [ ] Documentation updated
- [ ] Merged to master
- [ ] GitHub release created
- [ ] Binaries built and attached
- [ ] Published to crates.io

### Updating Command Versions

When releasing a new version, update command versions if any command files were modified:

1. **Update command frontmatter:**
   ```yaml
   ---
   description: Command description
   version: 1.2.3  # Match release version
   model: haiku
   ---
   ```

2. **Update manifest.json:**
   ```json
   {
     "version": "1.2.3",
     "commands": {
       "install-statusline.md": {
         "version": "1.2.3",  # Update if modified
         "description": "..."
       }
     }
   }
   ```

3. **Version guidelines:**
   - Match binary version if command was modified
   - Keep previous version if command unchanged
   - Update manifest's top-level `version` to match release

**Example:**
If releasing v1.2.4 and only `update-statusline.md` was modified:
- Update `update-statusline.md` frontmatter to `version: 1.2.4`
- Update manifest: `"update-statusline.md": {"version": "1.2.4", ...}`
- Update manifest: `"version": "1.2.4"`
- Keep other command versions unchanged

---

## 🐛 Debugging

### Debug Logging

Add debug output:

```rust
eprintln!("Debug: {:?}", some_value);
```

View in Claude Code logs or redirect stderr:

**macOS / Linux:**
```bash
echo '...' | ./target/debug/claude-code-status-line 2> debug.log
```

**Windows (PowerShell):**
```powershell
'...' | .\target\debug\claude-code-status-line.exe 2> debug.log
```

### Common Issues

**Build errors:**
```bash
# Clean and rebuild
cargo clean
cargo build
```

**Test failures:**
```bash
# Run specific test with output
cargo test test_name -- --nocapture
```

**Clippy warnings:**
```bash
# See all warnings
cargo clippy --all-targets --all-features
```

---

## 📝 Wiki Documentation

### Updating Wiki Pages

The project uses GitHub's wiki feature. Wiki content is stored in two locations:
- **Source of truth**: `docs/wiki/` (tracked in main repository)
- **Published wiki**: `wiki/` directory (separate git repository, ignored by main repo)

### Initial Setup

Clone the wiki repository once:
```bash
git clone https://github.com/ndave92/claude-code-status-line.wiki.git wiki
```

The `wiki/` directory is already in `.gitignore` and won't be tracked by the main repository.

### Syncing Wiki Changes

**Option 1: Using the sync script (Recommended)**

```bash
# Sync and commit in one command
./scripts/sync-wiki.sh "Your commit message"

# Or sync without committing (for manual review)
./scripts/sync-wiki.sh
```

The script:
- Copies all `.md` files from `docs/wiki/` to `wiki/`
- Shows changed files
- Optionally commits and pushes with provided message

**Option 2: Manual workflow**

```bash
# Copy updated files
cp docs/wiki/*.md wiki/

# Review changes
cd wiki
git status
git diff

# Commit and push
git add *.md
git commit -m "Update documentation"
git push origin master
```

### Workflow Summary

1. Edit wiki pages in `docs/wiki/` (main repository)
2. Commit to main repository (dev branch)
3. Run `./scripts/sync-wiki.sh "Update message"` to publish
4. Wiki changes are now live on GitHub

---

## 📚 Dependencies

Key dependencies used:

- **serde / serde_json** - JSON parsing and serialization
- **chrono** - Date/time handling for quota timers
- **keyring** - Secure token storage (cross-platform)
- **terminal_size** - Terminal width detection
- **unicode-width** - Text width calculation

### Adding Dependencies

```bash
# Add a new dependency
cargo add dependency-name

# Add a dev dependency
cargo add --dev dev-dependency-name
```

Update `Cargo.toml` and commit changes.

---

## 🤝 Pull Request Process

1. **Fork the repository**
2. **Create a feature branch** from `dev`
3. **Make your changes**
4. **Run validation:** `bash scripts/validate.sh`
5. **Commit with clear messages**
6. **Push to your fork**
7. **Open a Pull Request** against `dev` branch

### PR Guidelines

- Describe what your PR does
- Reference related issues (#123)
- Include test cases for new features
- Update documentation if needed
- Ensure CI passes

---

## 💬 Getting Help

- **Questions:** [GitHub Discussions](https://github.com/ndave92/claude-code-status-line/discussions)
- **Issues:** [GitHub Issues](https://github.com/ndave92/claude-code-status-line/issues)
- **Code Review:** Tag maintainers in your PR

---

## 📄 License

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