cc-context-stats 1.5.1 → 1.6.0

package/docs/DEPLOYMENT.md

@@ -0,0 +1,60 @@
+# Deployment
+
+## Distribution Channels
+
+cc-context-stats is distributed through three channels:
+
+| Channel      | Package Name      | Command                              |
+| ------------ | ----------------- | ------------------------------------ |
+| Shell script | N/A               | `curl -fsSL .../install.sh \| bash`  |
+| PyPI         | `cc-context-stats`| `pip install cc-context-stats`       |
+| npm          | `cc-context-stats`| `npm install -g cc-context-stats`    |
+
+## Publishing to PyPI
+
+```bash
+# Ensure clean build
+rm -rf dist/ build/
+
+# Build
+python -m build
+
+# Check package
+twine check dist/*
+
+# Upload to PyPI
+twine upload dist/*
+```
+
+## Publishing to npm
+
+```bash
+# Verify package.json
+npm pack --dry-run
+
+# Publish
+npm publish
+```
+
+## Release Workflow
+
+The project uses GitHub Actions for automated releases (`.github/workflows/release.yml`):
+
+1. Create and push a version tag: `git tag v1.x.x && git push --tags`
+2. The release workflow automatically:
+   - Runs the full test suite
+   - Builds Python and npm packages
+   - Creates a GitHub Release with release notes
+
+## Version Management
+
+Versions must be updated in sync across:
+
+- `pyproject.toml` - `[project] version`
+- `package.json` - `version`
+- `CHANGELOG.md` - New version entry
+- `RELEASE_NOTES.md` - Current release notes
+
+## Install Script
+
+The `install.sh` script is fetched directly from the `main` branch on GitHub. Changes to the installer take effect immediately for new users running the curl one-liner.

package/docs/DEVELOPMENT.md

@@ -0,0 +1,125 @@
+# Development Guide
+
+## Prerequisites
+
+- **Git** - Version control
+- **jq** - JSON processor (for bash scripts)
+- **Python 3.9+** - For Python package and testing
+- **Node.js 18+** - For Node.js script and testing
+- **Bats** - Bash Automated Testing System (optional, for bash tests)
+
+## Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/luongnv89/cc-context-stats.git
+cd cc-context-stats
+
+# Python setup
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements-dev.txt
+pip install -e ".[dev]"
+
+# Node.js setup
+npm install
+
+# Install pre-commit hooks
+pre-commit install
+```
+
+## Project Layout
+
+```
+cc-context-stats/
+├── src/claude_statusline/    # Python package source
+├── scripts/                  # Standalone scripts (sh/py/js)
+├── tests/
+│   ├── bash/                 # Bats tests
+│   ├── python/               # Pytest tests
+│   └── node/                 # Jest tests
+├── config/                   # Configuration examples
+├── docs/                     # Documentation
+├── .github/workflows/        # CI/CD
+├── pyproject.toml            # Python build config
+└── package.json              # Node.js config
+```
+
+## Running Tests
+
+```bash
+# All tests
+npm test && pytest && bats tests/bash/*.bats
+
+# Individual suites
+pytest tests/python/ -v                          # Python
+pytest tests/python/ -v --cov=scripts --cov-report=html  # Python + coverage
+npm test                                          # Node.js (Jest)
+npm run test:coverage                             # Node.js + coverage
+bats tests/bash/*.bats                           # Bash
+```
+
+## Linting & Formatting
+
+```bash
+# Run all checks via pre-commit
+pre-commit run --all-files
+
+# Individual tools
+ruff check src/ scripts/statusline.py            # Python lint
+ruff format src/ scripts/statusline.py           # Python format
+npx eslint scripts/statusline.js                 # JavaScript lint
+npx prettier --write scripts/statusline.js       # JavaScript format
+shellcheck scripts/*.sh install.sh               # Bash lint
+```
+
+## Manual Testing
+
+```bash
+# Test statusline scripts with mock input
+echo '{"model":{"display_name":"Test"},"cwd":"/test","session_id":"abc123","context":{"tokens_remaining":64000,"context_window":200000}}' | python3 scripts/statusline.py
+
+echo '{"model":{"display_name":"Test"}}' | node scripts/statusline.js
+
+echo '{"model":{"display_name":"Test"}}' | bash scripts/statusline-full.sh
+```
+
+## Building
+
+```bash
+# Python package
+python -m build
+
+# Verify package
+twine check dist/*
+```
+
+## Cross-Script Consistency
+
+All three implementations (bash, Python, Node.js) must produce identical output for the same input. When modifying status line behavior:
+
+1. Update all three script variants
+2. Run integration tests to verify parity
+3. Test on multiple platforms if possible
+
+## Debugging
+
+### State files
+
+```bash
+# View current state files
+ls -la ~/.claude/statusline/statusline.*.state
+
+# Inspect state content
+cat ~/.claude/statusline/statusline.<session_id>.state
+```
+
+### Verbose testing
+
+```bash
+# Python with verbose output
+pytest tests/python/ -v -s
+
+# Node.js with verbose output
+npx jest --verbose
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-context-stats",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Monitor your Claude Code session context in real-time - track token usage and never run out of context",
   "main": "scripts/statusline.js",
   "scripts": {
@@ -32,7 +32,7 @@
   "devDependencies": {
     "eslint": "^8.56.0",
     "jest": "^29.7.0",
-    "prettier": "^3.2.0"
+    "prettier": "^3.8.1"
   },
   "engines": {
     "node": ">=18"

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cc-context-stats"
-version = "1.5.1"
+version = "1.6.0"
 description = "Monitor your Claude Code session context in real-time - track token usage and never run out of context"
 readme = "README.md"
 license = { text = "MIT" }

package/scripts/statusline-full.sh

@@ -178,7 +178,7 @@ cost_usd=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
 lines_added=$(echo "$input" | jq -r '.cost.total_lines_added // 0')
 lines_removed=$(echo "$input" | jq -r '.cost.total_lines_removed // 0')
 model_id=$(echo "$input" | jq -r '.model.id // ""')
-workspace_project_dir=$(echo "$input" | jq -r '.workspace.project_dir // ""')
+workspace_project_dir=$(echo "$input" | jq -r '.workspace.project_dir // ""' | tr ',' '_')
 
 if [[ "$total_size" -gt 0 && "$current_usage" != "null" ]]; then
     # Get tokens from current_usage (includes cache)

package/scripts/statusline.js

@@ -28,10 +28,50 @@
  */
 
 const { execSync } = require('child_process');
+const crypto = require('crypto');
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
 
+const ROTATION_THRESHOLD = 10000;
+const ROTATION_KEEP = 5000;
+
+/**
+ * Rotate a state file if it exceeds ROTATION_THRESHOLD lines.
+ * Keeps the most recent ROTATION_KEEP lines via atomic temp-file + rename.
+ */
+function maybeRotateStateFile(stateFile) {
+    try {
+        if (!fs.existsSync(stateFile)) {
+            return;
+        }
+        const content = fs.readFileSync(stateFile, 'utf8');
+        const lines = content.split('\n');
+        // Remove trailing empty element from split if file ends with newline
+        if (lines.length > 0 && lines[lines.length - 1] === '') {
+            lines.pop();
+        }
+        if (lines.length <= ROTATION_THRESHOLD) {
+            return;
+        }
+        const keep = lines.slice(-ROTATION_KEEP);
+        const tmpFile = stateFile + '.' + crypto.randomBytes(6).toString('hex') + '.tmp';
+        try {
+            fs.writeFileSync(tmpFile, keep.join('\n') + '\n');
+            fs.renameSync(tmpFile, stateFile);
+        } catch (e) {
+            try {
+                fs.unlinkSync(tmpFile);
+            } catch {
+                /* cleanup best-effort */
+            }
+            throw e;
+        }
+    } catch (e) {
+        process.stderr.write(`[statusline] warning: failed to rotate state file: ${e.message}\n`);
+    }
+}
+
 // ANSI Colors
 const BLUE = '\x1b[0;34m';
 const MAGENTA = '\x1b[0;35m';
@@ -97,6 +137,7 @@ function getGitInfo(projectDir) {
             cwd: projectDir,
             encoding: 'utf8',
             stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 5000,
         }).trim();
 
         if (!branch) {
@@ -108,6 +149,7 @@ function getGitInfo(projectDir) {
             cwd: projectDir,
             encoding: 'utf8',
             stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 5000,
         });
         const changes = status.split('\n').filter(l => l.trim()).length;
 
@@ -152,8 +194,8 @@ show_delta=true
 show_session=true
 `;
             fs.writeFileSync(configPath, defaultConfig);
-        } catch {
-            // Ignore errors creating config
+        } catch (e) {
+            process.stderr.write(`[statusline] warning: failed to create config: ${e.message}\n`);
         }
         return config;
     }
@@ -182,8 +224,8 @@ show_session=true
                 config.reducedMotion = valueTrimmed !== 'false';
             }
         }
-    } catch {
-        // Ignore errors
+    } catch (e) {
+        process.stderr.write(`[statusline] warning: failed to read config: ${e.message}\n`);
     }
     return config;
 }
@@ -339,7 +381,10 @@ process.stdin.on('end', () => {
                         prevTokens = parseInt(lastLine, 10) || 0;
                     }
                 }
-            } catch {
+            } catch (e) {
+                process.stderr.write(
+                    `[statusline] warning: failed to read state file: ${e.message}\n`
+                );
                 prevTokens = 0;
             }
             // Calculate delta (difference in context window usage)
@@ -373,12 +418,15 @@ process.stdin.on('end', () => {
                         linesRemoved,
                         sessionId || '',
                         modelId,
-                        workspaceProjectDir,
+                        workspaceProjectDir.replace(/,/g, '_'),
                         totalSize,
                     ].join(',');
                     fs.appendFileSync(stateFile, `${stateData}\n`);
-                } catch {
-                    // Ignore errors
+                    maybeRotateStateFile(stateFile);
+                } catch (e) {
+                    process.stderr.write(
+                        `[statusline] warning: failed to write state file: ${e.message}\n`
+                    );
                 }
             }
         }
@@ -395,3 +443,8 @@ process.stdin.on('end', () => {
     const parts = [base, gitInfo, contextInfo, deltaInfo, acInfo, sessionInfo];
     console.log(fitToWidth(parts, maxWidth));
 });
+
+// Export for testing
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = { maybeRotateStateFile, ROTATION_THRESHOLD, ROTATION_KEEP };
+}

package/scripts/statusline.py

@@ -159,8 +159,8 @@ show_delta=true
 show_session=true
 """
                 )
-        except Exception:
-            pass  # Ignore errors creating config
+        except Exception as e:
+            sys.stderr.write(f"[statusline] warning: failed to create config: {e}\n")
         return config
 
     try:
@@ -182,8 +182,8 @@ show_session=true
                     config["show_session"] = value != "false"
                 elif key == "show_io_tokens":
                     config["show_io_tokens"] = value != "false"
-    except Exception:
-        pass
+    except (OSError, UnicodeDecodeError) as e:
+        sys.stderr.write(f"[statusline] warning: failed to read config: {e}\n")
     return config
 
 
@@ -311,7 +311,8 @@ def main():
                                 prev_tokens = int(last_line.split(",")[1])
                             else:
                                 prev_tokens = int(last_line or 0)
-            except Exception:
+            except Exception as e:
+                sys.stderr.write(f"[statusline] warning: failed to read state file: {e}\n")
                 prev_tokens = 0
             # Calculate delta
             delta = used_tokens - prev_tokens
@@ -342,14 +343,14 @@ def main():
                         lines_removed,
                         session_id or "",
                         model_id,
-                        workspace_project_dir,
+                        workspace_project_dir.replace(",", "_"),
                         total_size,
                     ]
                 )
                 with open(state_file, "a") as f:
                     f.write(f"{state_data}\n")
-            except Exception:
-                pass
+            except Exception as e:
+                sys.stderr.write(f"[statusline] warning: failed to write state file: {e}\n")
 
     # Display session_id if enabled
     if show_session and session_id:

package/src/claude_statusline/__init__.py

@@ -3,7 +3,7 @@
 Never run out of context unexpectedly - monitor your session context in real-time.
 """
 
-__version__ = "1.5.1"
+__version__ = "1.6.0"
 
 from claude_statusline.core.config import Config
 from claude_statusline.core.state import StateFile

package/src/claude_statusline/cli/context_stats.py

@@ -10,6 +10,7 @@ Options:
     --type <cumulative|delta|io|both|all>  Graph type to display (default: both)
     --watch, -w [interval]                  Real-time monitoring mode (default: 2s)
     --no-color                              Disable color output
+    --version, -V                           Show version and exit
     --help                                  Show this help
 """
 
@@ -24,7 +25,7 @@ from pathlib import Path
 from claude_statusline import __version__
 from claude_statusline.core.colors import ColorManager
 from claude_statusline.core.config import Config
-from claude_statusline.core.state import StateFile
+from claude_statusline.core.state import StateFile, _validate_session_id
 from claude_statusline.graphs.renderer import GraphDimensions, GraphRenderer
 from claude_statusline.graphs.statistics import calculate_deltas
 from claude_statusline.ui.icons import get_activity_tier, get_tier_label
@@ -59,6 +60,7 @@ OPTIONS:
     -w [interval]  Set refresh interval in seconds (default: 2)
     --no-watch     Show graphs once and exit (disable live monitoring)
     --no-color     Disable color output
+    --version, -V  Show version and exit
     --help         Show this help message
 
 NOTE:
@@ -131,13 +133,30 @@ def parse_args() -> argparse.Namespace:
         action="store_true",
         help="Show help message",
     )
+    parser.add_argument(
+        "--version",
+        "-V",
+        action="store_true",
+        help="Show version and exit",
+    )
 
     args = parser.parse_args()
 
+    if args.version:
+        print(f"cc-context-stats {__version__}")
+        sys.exit(0)
+
     if args.help:
         show_help()
         sys.exit(0)
 
+    if args.session_id is not None:
+        try:
+            _validate_session_id(args.session_id)
+        except ValueError as e:
+            sys.stderr.write(f"Error: {e}\n")
+            sys.exit(1)
+
     return args
 
 

package/src/claude_statusline/core/config.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
@@ -63,8 +64,8 @@ show_session=true
 reduced_motion=false
 """
             )
-        except OSError:
-            pass  # Ignore errors creating config
+        except OSError as e:
+            sys.stderr.write(f"[statusline] warning: failed to create config {self._config_path}: {e}\n")
 
     def _read_config(self) -> None:
         """Read settings from config file."""
@@ -90,8 +91,8 @@ reduced_motion=false
                     self.show_io_tokens = value != "false"
                 elif key == "reduced_motion":
                     self.reduced_motion = value != "false"
-        except OSError:
-            pass  # Use defaults on read error
+        except (OSError, UnicodeDecodeError) as e:
+            sys.stderr.write(f"[statusline] warning: failed to read config {self._config_path}: {e}\n")
 
     def to_dict(self) -> dict[str, Any]:
         """Convert config to dictionary."""

package/src/claude_statusline/core/state.py

@@ -2,7 +2,10 @@
 
 from __future__ import annotations
 
+import os
 import shutil
+import sys
+import tempfile
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -115,7 +118,7 @@ class StateEntry:
                 self.lines_removed,
                 self.session_id,
                 self.model_id,
-                self.workspace_project_dir,
+                self.workspace_project_dir.replace(",", "_"),
                 self.context_window_size,
             ]
         )
@@ -131,11 +134,30 @@ class StateEntry:
         return self.current_input_tokens + self.cache_creation + self.cache_read
 
 
+def _validate_session_id(session_id: str) -> None:
+    """Validate that a session ID does not contain dangerous path characters.
+
+    Args:
+        session_id: Session ID to validate
+
+    Raises:
+        ValueError: If session_id contains '/', '\\', '..', or null bytes
+    """
+    for bad in ("/", "\\", "..", "\0"):
+        if bad in session_id:
+            raise ValueError(
+                f"Invalid session_id: contains '{bad}'. "
+                "Session IDs must not contain '/', '\\', '..', or null bytes."
+            )
+
+
 class StateFile:
     """Manage state files for token tracking."""
 
     STATE_DIR = Path.home() / ".claude" / "statusline"
     OLD_STATE_DIR = Path.home() / ".claude"
+    ROTATION_THRESHOLD = 10_000
+    ROTATION_KEEP = 5_000
 
     def __init__(self, session_id: str | None = None) -> None:
         """Initialize state file manager.
@@ -143,6 +165,8 @@ class StateFile:
         Args:
             session_id: Optional session ID. If not provided, uses latest session.
         """
+        if session_id is not None:
+            _validate_session_id(session_id)
         self.session_id = session_id
         self._ensure_state_dir()
         self._migrate_old_files()
@@ -211,8 +235,8 @@ class StateFile:
                     entry = StateEntry.from_csv_line(line)
                     if entry:
                         entries.append(entry)
-        except OSError:
-            pass
+        except OSError as e:
+            sys.stderr.write(f"[statusline] warning: failed to read state history {file_path}: {e}\n")
 
         return entries
 
@@ -233,8 +257,8 @@ class StateFile:
             for line in reversed(lines):
                 if line.strip():
                     return StateEntry.from_csv_line(line)
-        except OSError:
-            pass
+        except OSError as e:
+            sys.stderr.write(f"[statusline] warning: failed to read last entry {file_path}: {e}\n")
 
         return None
 
@@ -247,8 +271,41 @@ class StateFile:
         try:
             with open(self.file_path, "a") as f:
                 f.write(f"{entry.to_csv_line()}\n")
-        except OSError:
-            pass
+        except OSError as e:
+            sys.stderr.write(f"[statusline] warning: failed to write state {self.file_path}: {e}\n")
+            return
+        self._maybe_rotate()
+
+    def _maybe_rotate(self) -> None:
+        """Rotate state file if it exceeds the line threshold.
+
+        If the file has more than ROTATION_THRESHOLD lines, truncate to
+        the most recent ROTATION_KEEP lines via atomic temp-file + rename.
+        """
+        file_path = self.file_path
+        try:
+            if not file_path.exists():
+                return
+            lines = file_path.read_text().splitlines(keepends=True)
+            if len(lines) <= self.ROTATION_THRESHOLD:
+                return
+            keep = lines[-self.ROTATION_KEEP :]
+            fd = tempfile.NamedTemporaryFile(
+                dir=str(self.STATE_DIR), delete=False, mode="w", suffix=".tmp"
+            )
+            try:
+                fd.writelines(keep)
+                fd.close()
+                os.replace(fd.name, str(file_path))
+            except BaseException:
+                fd.close()
+                try:
+                    os.unlink(fd.name)
+                except OSError:
+                    pass
+                raise
+        except OSError as e:
+            sys.stderr.write(f"[statusline] warning: failed to rotate state file {file_path}: {e}\n")
 
     def list_sessions(self) -> list[str]:
         """List all available session IDs.