cc-context-stats 1.8.0 → 1.8.2

package/.github/workflows/release.yml

@@ -1,151 +0,0 @@
-name: Release
-
-on:
-  push:
-    tags:
-      - 'v*'
-  workflow_dispatch:
-    inputs:
-      version:
-        description: 'Version to release (e.g., 1.2.0)'
-        required: true
-        type: string
-
-permissions:
-  contents: write
-
-jobs:
-  validate:
-    name: Validate Release
-    runs-on: ubuntu-latest
-    outputs:
-      version: ${{ steps.version.outputs.version }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Determine version
-        id: version
-        run: |
-          if [[ "${{ github.event_name }}" == "push" ]]; then
-            VERSION="${GITHUB_REF#refs/tags/v}"
-          else
-            VERSION="${{ github.event.inputs.version }}"
-          fi
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
-          echo "Release version: $VERSION"
-
-      - name: Validate version format
-        run: |
-          VERSION="${{ steps.version.outputs.version }}"
-          if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9]+)?$ ]]; then
-            echo "Invalid version format: $VERSION"
-            echo "Expected format: X.Y.Z or X.Y.Z-suffix"
-            exit 1
-          fi
-
-  test:
-    name: Run Tests
-    needs: validate
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'npm'
-
-      - name: Install jq
-        run: sudo apt-get update && sudo apt-get install -y jq bats
-
-      - name: Install Python dependencies
-        run: |
-          pip install -r requirements-dev.txt
-          pip install -e .
-
-      - name: Install Node.js dependencies
-        run: npm ci
-
-      - name: Run Python tests
-        run: pytest tests/python/ -v
-
-      - name: Run Node.js tests
-        run: npm test
-
-      - name: Run Bash tests
-        run: bats tests/bash/*.bats
-
-  create-release:
-    name: Create GitHub Release
-    needs: [validate, test]
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Generate changelog
-        id: changelog
-        run: |
-          # Get commits since last tag
-          LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
-          if [ -n "$LAST_TAG" ]; then
-            COMMITS=$(git log --pretty=format:"- %s" "$LAST_TAG"..HEAD)
-          else
-            COMMITS=$(git log --pretty=format:"- %s")
-          fi
-
-          # Create changelog
-          {
-            echo 'changelog<<EOF'
-            echo "## What's Changed"
-            echo ""
-            echo "$COMMITS"
-            echo ""
-            echo "**Full Changelog**: https://github.com/${{ github.repository }}/compare/${LAST_TAG}...v${{ needs.validate.outputs.version }}"
-            echo 'EOF'
-          } >> $GITHUB_OUTPUT
-
-      - name: Create Release Archive
-        run: |
-          VERSION="${{ needs.validate.outputs.version }}"
-          mkdir -p dist
-
-          # Create tarball
-          tar -czf dist/claude-statusline-${VERSION}.tar.gz \
-            scripts/ \
-            config/ \
-            install.sh \
-            README.md
-
-          # Create zip
-          zip -r dist/claude-statusline-${VERSION}.zip \
-            scripts/ \
-            config/ \
-            install.sh \
-            README.md
-
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
-        with:
-          tag_name: v${{ needs.validate.outputs.version }}
-          name: Release v${{ needs.validate.outputs.version }}
-          body: ${{ steps.changelog.outputs.changelog }}
-          draft: false
-          prerelease: ${{ contains(needs.validate.outputs.version, '-') }}
-          files: |
-            dist/claude-statusline-*.tar.gz
-            dist/claude-statusline-*.zip
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.pre-commit-config.yaml

@@ -1,74 +0,0 @@
-# Pre-commit hooks for claude-statusline project
-# Install: pip install pre-commit && pre-commit install
-# Run all: pre-commit run --all-files
-
-default_language_version:
-  python: python3
-
-repos:
-  # General file checks
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
-    hooks:
-      - id: check-yaml
-      - id: check-json
-      - id: check-toml
-      - id: end-of-file-fixer
-      - id: trailing-whitespace
-      - id: mixed-line-ending
-        args: ['--fix=lf']
-      - id: check-executables-have-shebangs
-      - id: check-shebang-scripts-are-executable
-      - id: detect-private-key
-      - id: check-merge-conflict
-      - id: check-added-large-files
-        args: ['--maxkb=500']
-
-  # ShellCheck for bash scripts
-  - repo: https://github.com/shellcheck-py/shellcheck-py
-    rev: v0.9.0.6
-    hooks:
-      - id: shellcheck
-        args: ['--severity=warning']
-        files: \.(sh|bash)$
-
-  # Python: Ruff linter and formatter
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.14
-    hooks:
-      - id: ruff
-        args: ['--fix']
-        files: \.py$
-      - id: ruff-format
-        files: \.py$
-
-  # JavaScript: ESLint
-  - repo: https://github.com/pre-commit/mirrors-eslint
-    rev: v8.56.0
-    hooks:
-      - id: eslint
-        files: \.js$
-        types: [javascript]
-        additional_dependencies:
-          - eslint@8.56.0
-
-  # Prettier for JS, JSON, MD
-  - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v4.0.0-alpha.8
-    hooks:
-      - id: prettier
-        types_or: [javascript, json, markdown]
-        additional_dependencies:
-          - prettier@3.2.5
-
-  # Markdown lint
-  - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.39.0
-    hooks:
-      - id: markdownlint
-        args: ['--fix', '--disable', 'MD013', 'MD024', 'MD033', 'MD040', 'MD041', '--']
-
-ci:
-  autofix_prs: true
-  autofix_commit_msg: 'style: auto-fix pre-commit issues'
-  autoupdate_schedule: monthly

package/.prettierrc

@@ -1,33 +0,0 @@
-{
-  "printWidth": 100,
-  "tabWidth": 4,
-  "useTabs": false,
-  "semi": true,
-  "singleQuote": true,
-  "quoteProps": "as-needed",
-  "trailingComma": "es5",
-  "bracketSpacing": true,
-  "arrowParens": "avoid",
-  "endOfLine": "lf",
-  "overrides": [
-    {
-      "files": "*.json",
-      "options": {
-        "tabWidth": 2
-      }
-    },
-    {
-      "files": "*.md",
-      "options": {
-        "tabWidth": 2,
-        "proseWrap": "preserve"
-      }
-    },
-    {
-      "files": "*.{yml,yaml}",
-      "options": {
-        "tabWidth": 2
-      }
-    }
-  ]
-}

package/.shellcheckrc

@@ -1,10 +0,0 @@
-# ShellCheck configuration for claude-statusline project
-
-# Set default shell to bash
-shell=bash
-
-# Enable external sources for sourcing config files
-external-sources=true
-
-# Severity: error, warning, info, style
-severity=style

package/CHANGELOG.md

@@ -1,187 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [1.8.0] - 2026-03-15
-
-### Added
-
-- **Model Intelligence (MI) score** — Heuristic quality score estimating answer quality based on context utilization, cache efficiency, and output productivity. Inspired by the Michelangelo paper (arXiv:2409.12640). Displayed as `MI:X.XX` in the statusline with green/yellow/red color coding
-- **MI score in all implementations** — MI computation available across Python package, standalone Python, Node.js, and Bash (via `awk`) statusline scripts with full cross-implementation parity
-- **MI timeseries graph** — `context-stats --type mi` renders MI score trajectory over time as an ASCII graph with decimal Y-axis labels
-- **MI in session summary** — `context-stats` summary now shows MI score with sub-component breakdown (CPS, ES, PS) and interpretation text
-- **Shared test vectors** — `tests/fixtures/mi_test_vectors.json` with 6 vectors ensuring Python and Node.js produce identical MI scores within ±0.01 tolerance
-- **`label_fn` parameter for `render_timeseries()`** — Optional custom Y-axis label formatter, used by MI graph to display decimals instead of token counts
-- **Bash feature parity** — `statusline-full.sh` now supports custom color overrides, state file rotation, MI score display, and all config keys (`show_mi`, `mi_curve_beta`, `reduced_motion`, `show_io_tokens`)
-- **Config: `show_mi`** — Toggle MI score display (default: `true`)
-- **Config: `mi_curve_beta`** — Adjust MI degradation curve shape (default: `1.5`)
-
-### Changed
-
-- **Compact context display** — Removed "free" word from context info (`872,748 (87.3%)` instead of `872,748 free (87.3%)`) across all implementations
-- **Decoupled state reads from `show_delta`** — State file is now read when either `show_delta` or `show_mi` is enabled, allowing MI to work independently of delta display
-- **Node.js terminal width default** — Changed from `80` to `200` when no TTY is detected (matching Python behavior), preventing `fitToWidth` from dropping statusline parts in Claude Code's subprocess
-
-### Fixed
-
-- **Node.js terminal width** — Fixed `getTerminalWidth()` defaulting to 80 in Claude Code's subprocess, which caused MI, delta, AC, and session parts to be silently dropped
-
-## [1.7.0] - 2026-03-14
-
-### Added
-
-- **Configurable colors** - Custom color themes via `~/.claude/statusline.conf` using named colors (`bright_cyan`) or hex codes (`#7dcfff`). Six configurable slots: `color_green`, `color_yellow`, `color_red`, `color_blue`, `color_magenta`, `color_cyan`
-- **`context-stats explain` command** - Diagnostic dump that pretty-prints Claude Code's JSON context with derived values (free tokens, autocompact buffer, effective free), active config, vim/agent/output_style extensions, and raw JSON. Supports `--no-color` flag
-- **24-bit true color support** - Hex color codes (`#rrggbb`) are converted to ANSI 24-bit escape sequences for full RGB color customization
-- **Cross-implementation sync documentation** - Added sync points table to CLAUDE.md documenting triplicated logic across Python, Node.js, and Bash implementations
-
-### Changed
-
-- **ColorManager accepts overrides** - `ColorManager` now takes an optional `overrides` dict, allowing config-driven color customization throughout the package
-- **Git info uses configurable colors** - Branch and change count colors now respect user color overrides in all three implementations
-- **Config parsing preserves raw values** - Config reader now preserves case for color values while lowercasing only for boolean comparison
-
-## [1.6.2] - 2026-03-13
-
-### Fixed
-
-- **Delta calculation parity** - Python statusline now reads correct CSV indices (3+5+6) for context usage delta, matching Node.js behavior
-- **Missing duplicate-entry guard** - Python statusline now skips state file writes when token count is unchanged, preventing file bloat
-- **Missing state file rotation** - Python statusline now calls rotation after writes (10k/5k threshold), matching Node.js
-- **Missing git timeout** - Added 5-second timeout to git subprocess calls in standalone Python statusline script
-- **Broad exception handling** - Narrowed `except Exception` to `(OSError, ValueError)` for state reads and `OSError` for writes
-- **Stale CSV format comments** - Added missing `context_window_size` field to header comments in both Python and Node.js scripts
-
-### Added
-
-- **Delta parity tests** - 4 new bats tests verifying Python/Node.js produce identical deltas, handle first-run/decrease/dedup correctly
-
-## [1.6.1] - 2026-03-13
-
-### Fixed
-
-- **Footer version drift** - Corrected stale version `1.2.3` in bash script and `1.0.0` default in Python renderer to match actual release version
-- **Footer project name** - Renamed `claude-statusline` to `cc-context-stats` in the footer display across bash and Python implementations
-- **Install version embedding** - Install scripts now read version from `package.json` and embed it into the installed script, preventing future version drift
-
-## [1.6.0] - 2026-03-13
-
-### Added
-
-- **CLI `--version` flag** - `context-stats --version` / `-V` now prints the current version
-- **State file rotation** - Automatic rotation at 10,000 lines (keeps most recent 5,000) to prevent unbounded file growth
-- **Session ID validation** - Rejects path-traversal characters (`/`, `\`, `..`, null bytes) for security
-- **Git command timeout** - 5-second timeout on git operations in both Python and Node.js implementations
-- **Core data pipeline unit tests** - 51 tests across 6 classes covering config, state, formatters, graph, and CLI
-- **Cross-implementation parity test** - Ensures Python and Node.js statusline scripts produce consistent output
-- **Stderr warnings** - Critical error paths now emit warnings to stderr for debugging
-- **CSV format documentation** - Formal specification of the 14-field state file format
-- **Comma guard for workspace paths** - Commas in `workspace_project_dir` are replaced with underscores before CSV write
-- **Open-source standard files** - Added CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, and GitHub issue/PR templates
-- **NPM Package** - `cc-context-stats` now available on npm for JavaScript/Node.js environments
-
-### Changed
-
-- **Package Metadata** - Synchronized package descriptions across npm and PyPI for consistency
-- **Installation Section** - Moved shell script installation to the top of README as the recommended method
-
-### Dependencies
-
-- Bumped prettier from 3.7.4 to 3.8.0
-
-## [1.2.0] - 2025-01-08
-
-### Added
-
-- **Context Zones** - Status indicator based on context usage:
-  - 🟢 Smart Zone (< 40%): "You are in the smart zone"
-  - 🟡 Dumb Zone (40-80%): "You are in the dumb zone - Dex Horthy says so"
-  - 🔴 Wrap Up Zone (> 80%): "Better to wrap up and start a new session"
-- **Project name display** - Header now shows "Context Stats (project-name • session-id)"
-
-### Changed
-
-- **Watch mode enabled by default** - `context-stats` now runs in live monitoring mode (2s refresh)
-- **Delta graph by default** - Shows "Context Growth Per Interaction" instead of both graphs
-- Added `--no-watch` flag to show graphs once and exit
-- Simplified installer - no script selection, auto-overwrite existing files
-- Renamed graph labels to focus on context (e.g., "Context Usage Over Time")
-- Cleaned up session summary - removed clutter, highlighted status
-
-## [1.1.0] - 2025-01-08
-
-### Changed
-
-- **BREAKING**: Renamed package from `cc-statusline` to `cc-context-stats`
-- **BREAKING**: Renamed `token-graph` CLI command to `context-stats`
-- Pivoted project focus to real-time token monitoring and context tracking
-- Updated tagline: "Never run out of context unexpectedly"
-
-### Migration
-
-If upgrading from `cc-statusline`:
-
-```bash
-pip uninstall cc-statusline
-pip install cc-context-stats
-```
-
-The `claude-statusline` command still works. Replace `token-graph` with `context-stats`.
-
-## [1.0.2] - 2025-01-08
-
-### Fixed
-
-- Fixed remaining context showing negative values in context-stats by using `current_used_tokens` instead of cumulative `total_input_tokens + total_output_tokens`
-- Fixed ANSI escape codes not rendering properly in watch mode by using `sys.stdout.write()` instead of `print()` for cursor control sequences
-- Fixed color codes in summary statistics using ColorManager instead of raw ANSI constants
-
-## [1.0.1] - 2025-01-07
-
-### Added
-
-- pip/uv installable Python package (`cc-statusline` on PyPI)
-- `context_window_size` field to state file for tracking remaining context
-- Remaining context display in context-stats summary
-
-### Fixed
-
-- Restored executable permissions on script files
-- Fixed stdin detection in pipe mode using INTERACTIVE flag
-
-### Changed
-
-- Cleaned up unused `show_io_tokens` option
-- Fixed shellcheck warnings in shell scripts
-
-## [1.0.0] - 2025-01-06
-
-### Added
-
-- Comprehensive test suite with Bats (Bash), pytest (Python), and Jest (Node.js)
-- GitHub Actions CI/CD pipeline with multi-platform testing
-- Code quality tools: ShellCheck, Ruff, ESLint, Prettier
-- Pre-commit hooks for automated code quality checks
-- EditorConfig for consistent formatting across editors
-- CONTRIBUTING.md with development setup instructions
-- Dependabot configuration for automated dependency updates
-- Release automation workflow
-- Full-featured status line script (`statusline-full.sh`)
-- Git-aware status line script (`statusline-git.sh`)
-- Minimal status line script (`statusline-minimal.sh`)
-- Cross-platform Python implementation (`statusline.py`)
-- Cross-platform Node.js implementation (`statusline.js`)
-- Interactive installer script (`install.sh`)
-- Configuration examples for Claude Code
-- Autocompact (AC) buffer indicator
-- Context window usage with color-coded percentages
-- Git branch and uncommitted changes display
-
-## [0.x] - Pre-release
-
-Initial development versions with basic status line functionality.

package/CLAUDE.md

@@ -1,66 +0,0 @@
-# CLAUDE.md
-
-## Project Purpose
-
-cc-context-stats provides real-time context window monitoring for Claude Code sessions. It tracks token consumption over time and displays live ASCII graphs so users can see how much context remains.
-
-## Dual-Implementation Rationale
-
-The statusline is implemented in three languages (Bash, Python, Node.js) so users can choose whichever runtime they have available. Claude Code invokes the statusline script via stdin JSON pipe — any implementation that reads JSON from stdin and writes formatted text to stdout works. The Python and Node.js implementations also persist state to CSV files read by the `context-stats` CLI.
-
-## CSV Format Contract
-
-State files are append-only CSV at `~/.claude/statusline/statusline.<session_id>.state` with 14 comma-separated fields. See [docs/CSV_FORMAT.md](docs/CSV_FORMAT.md) for the full field specification. Key constraint: `workspace_project_dir` has commas replaced with underscores before writing.
-
-## Statusline Script Landscape
-
-| Script | Language | State writes | Notes |
-|---|---|---|---|
-| `scripts/statusline-full.sh` | Bash | No | Full display, requires `jq` |
-| `scripts/statusline-git.sh` | Bash | No | Git-focused variant |
-| `scripts/statusline-minimal.sh` | Bash | No | Minimal variant |
-| `scripts/statusline.py` | Python 3 | Yes | Pip-installable via package |
-| `scripts/statusline.js` | Node.js | Yes | Standalone script |
-
-## Test Commands
-
-```bash
-# Python tests
-source venv/bin/activate
-pytest tests/python/ -v
-
-# Node.js tests
-npm test
-
-# Bash integration tests
-bats tests/bash/*.bats
-
-# All tests
-pytest && npm test && bats tests/bash/*.bats
-```
-
-## Key Architectural Decisions
-
-- **Append-only CSV state files** with rotation at 10,000 lines (keeps most recent 5,000)
-- **No network requests** — all data stays local in `~/.claude/statusline/`
-- **Session ID validation** — rejects `/`, `\`, `..`, and null bytes for path-traversal defense
-- **5-second git command timeout** in both Python and Node.js implementations
-- **Config via `~/.claude/statusline.conf`** — simple key=value pairs
-
-## Cross-Implementation Sync Points
-
-The following logic is duplicated across three implementations and **must be kept in sync** when modified:
-
-| Logic | Package (`src/`) | Standalone Python (`scripts/statusline.py`) | Node.js (`scripts/statusline.js`) |
-|---|---|---|---|
-| Config parsing | `core/config.py` | `read_config()` | `readConfig()` |
-| Color name map | `core/colors.py:COLOR_NAMES` | `_COLOR_NAMES` | `COLOR_NAMES` |
-| Color parser | `core/colors.py:parse_color()` | `_parse_color()` | `parseColor()` |
-| Git info | `core/git.py:get_git_info()` | `get_git_info()` | `getGitInfo()` |
-| State rotation | `core/state.py` | `maybe_rotate_state_file()` | `maybeRotateStateFile()` |
-
-## Cross-References
-
-- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — system architecture and data flow
-- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) — setup, testing, and contribution guide
-- [docs/CSV_FORMAT.md](docs/CSV_FORMAT.md) — state file field specification

package/CODE_OF_CONDUCT.md

@@ -1,59 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, religion, or sexual identity
-and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes
-* Focusing on what is best for the overall community
-
-Examples of unacceptable behavior:
-
-* The use of sexualized language or imagery, and sexual attention or advances
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information without explicit permission
-* Other conduct which could reasonably be considered inappropriate
-
-## Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-luongnv89@gmail.com.
-
-All complaints will be reviewed and investigated promptly and fairly.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
-
-[homepage]: https://www.contributor-covenant.org