costcut 0.0.9__tar.gz

costcut-0.0.9/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+
+# Node
+node_modules/
+.next/
+out/
+.turbo/
+*.tsbuildinfo
+
+# Playwright
+frontend/test-results/
+frontend/playwright-report/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Env / secrets (only encrypted files are committed)
+.env
+.env.local
+.env.*.local
+!.env.example
+!*.encrypted
+
+# Sops decrypted artifacts
+.decrypted/
+
+# Logs
+*.log
+logs/
+
+# Local Docker volumes
+postgres-data/
+loki-data/
+grafana-data/
+
+# Placeholders
+__placeholder__
+
+
+# MkDocs build output
+docs/site/

costcut-0.0.9/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: costcut
+Version: 0.0.9
+Summary: Claude Code observability + cost optimization CLI
+Project-URL: Homepage, https://costcut.dev
+Project-URL: Repository, https://github.com/kuznetsov-ai/cost-guard
+Author-email: Eugene Kuznetsov <eugene@costcut.dev>
+License: MIT
+Keywords: claude-code,cost,llm,observability,tokens
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cost-guard CLI
+
+OSS CLI for Cost Guard. Tracks Claude Code session tokens, cost, hook compliance.
+
+## Install (Week 6+)
+
+```bash
+pip install cost-guard      # PyPI (Week 6 release)
+brew install cost-guard     # Homebrew tap (Week 6 release)
+```
+
+## Dev install
+
+```bash
+cd cli
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+cost-guard --version
+```
+
+## Commands
+
+### `cost-guard init` — install hooks bundle (Week 3 ✅)
+
+Installs 5 bundled hook scripts + shared library into `.claude/hooks/`, registers them in `.claude/settings.json`.
+
+```bash
+cost-guard init                                     # install to .claude/hooks (default)
+cost-guard init --target ~/.claude/hooks            # explicit target path
+cost-guard init --dry-run                          # preview changes, write nothing
+cost-guard init --force                            # overwrite existing hooks
+```
+
+Installs:
+- **Hooks:** `parallel_agents_guard.sh`, `test_before_push_guard.sh`, `large_read_warning.sh`, `token_alert.sh`, `session_cost_check.sh`
+- **Library:** `_lib/cost.sh` (shared utilities)
+
+Registers hooks in `.claude/settings.json` with event + matcher + command path. Idempotent: running twice adds no duplicates.
+
+Exit code 0 on success, 1 on error.
+
+### `cost-guard report` — session analytics (Week 2 ✅)
+
+Scans Claude Code JSONL transcripts in `~/.claude/projects/`, aggregates tokens + cost per session, renders a Rich table.
+
+```bash
+cost-guard report                                   # default: last 20 sessions for cwd
+cost-guard report --project ~/Projects/MyApp        # specific project
+cost-guard report --since 2026-05-01                # only sessions since date
+cost-guard report --last 5                          # top 5 most recent
+cost-guard report --all                             # no limit
+```
+
+Output columns: `Started | Duration | Model | Msgs | In | Out | Cache | Cost | Session`. Final row = TOTAL.
+
+### `cost-guard auth` — token management (Week 7 ✅)
+
+Manages authentication with backend API.
+
+```bash
+cost-guard auth set <api_key>                      # save API key (must start with cg_live_)
+cost-guard auth status                              # check login status + show masked token
+cost-guard auth logout                              # remove stored token
+```
+
+Token storage: `~/.config/cost-guard/token` (0o600 permissions). Env override: `COST_GUARD_TOKEN=cg_live_...` takes precedence. Backend: `GET /v1/auth/me` (Bearer JWT).
+
+### `cost-guard push` — upload sessions to backend (Week 7 ✅)
+
+Aggregates sessions from local JSONL and POSTs to backend API.
+
+```bash
+cost-guard push                                     # default: last 30 days
+cost-guard push --project ~/Projects/MyApp          # specific project
+cost-guard push --since 7                           # only last 7 days
+cost-guard push --dry-run                           # preview without HTTP
+```
+
+Requires authenticated token. Filters by `--since` (days). POSTs `{id, project, primary_model, started_at, ended_at, input_tokens, output_tokens, cost_usd}`. Continues on errors, returns 1 if any failed.
+
+### Stubs (later weeks)
+<!-- delegation-guard: ok -->
+
+- `cost-guard live` — real-time TUI dashboard (Week 2.5)
+- `cost-guard alert --budget 5` — daily spend cap (Week 3)
+
+## Pricing
+
+Per-million-token rates (verified 2026-05-23 against https://docs.claude.com/en/docs/about-claude/models):
+
+| Model | Input | Output | Cache read | Cache write 5m | Cache write 1h |
+|---|---|---|---|---|---|
+| `claude-opus-4-7` / `4-6` | $15 | $75 | $1.50 | $18.75 | $30 |
+| `claude-sonnet-4-6` / `4-5` | $3 | $15 | $0.30 | $3.75 | $6 |
+| `claude-haiku-4-5` | $1 | $5 | $0.10 | $1.25 | $2 |
+
+Unknown models return cost=0 (not None) — see `cost_guard.pricing.compute_cost_usd`.
+
+## Tests
+
+```bash
+cd cli
+pytest                                              # 50 tests, ~1s
+COSTGUARD_REAL_SMOKE=1 pytest tests/test_real_data_smoke.py  # opt-in: scans real ~/.claude/projects
+```
+
+<!-- delegation-guard: ok -->

costcut-0.0.9/README.md

@@ -0,0 +1,108 @@
+# cost-guard CLI
+
+OSS CLI for Cost Guard. Tracks Claude Code session tokens, cost, hook compliance.
+
+## Install (Week 6+)
+
+```bash
+pip install cost-guard      # PyPI (Week 6 release)
+brew install cost-guard     # Homebrew tap (Week 6 release)
+```
+
+## Dev install
+
+```bash
+cd cli
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+cost-guard --version
+```
+
+## Commands
+
+### `cost-guard init` — install hooks bundle (Week 3 ✅)
+
+Installs 5 bundled hook scripts + shared library into `.claude/hooks/`, registers them in `.claude/settings.json`.
+
+```bash
+cost-guard init                                     # install to .claude/hooks (default)
+cost-guard init --target ~/.claude/hooks            # explicit target path
+cost-guard init --dry-run                          # preview changes, write nothing
+cost-guard init --force                            # overwrite existing hooks
+```
+
+Installs:
+- **Hooks:** `parallel_agents_guard.sh`, `test_before_push_guard.sh`, `large_read_warning.sh`, `token_alert.sh`, `session_cost_check.sh`
+- **Library:** `_lib/cost.sh` (shared utilities)
+
+Registers hooks in `.claude/settings.json` with event + matcher + command path. Idempotent: running twice adds no duplicates.
+
+Exit code 0 on success, 1 on error.
+
+### `cost-guard report` — session analytics (Week 2 ✅)
+
+Scans Claude Code JSONL transcripts in `~/.claude/projects/`, aggregates tokens + cost per session, renders a Rich table.
+
+```bash
+cost-guard report                                   # default: last 20 sessions for cwd
+cost-guard report --project ~/Projects/MyApp        # specific project
+cost-guard report --since 2026-05-01                # only sessions since date
+cost-guard report --last 5                          # top 5 most recent
+cost-guard report --all                             # no limit
+```
+
+Output columns: `Started | Duration | Model | Msgs | In | Out | Cache | Cost | Session`. Final row = TOTAL.
+
+### `cost-guard auth` — token management (Week 7 ✅)
+
+Manages authentication with backend API.
+
+```bash
+cost-guard auth set <api_key>                      # save API key (must start with cg_live_)
+cost-guard auth status                              # check login status + show masked token
+cost-guard auth logout                              # remove stored token
+```
+
+Token storage: `~/.config/cost-guard/token` (0o600 permissions). Env override: `COST_GUARD_TOKEN=cg_live_...` takes precedence. Backend: `GET /v1/auth/me` (Bearer JWT).
+
+### `cost-guard push` — upload sessions to backend (Week 7 ✅)
+
+Aggregates sessions from local JSONL and POSTs to backend API.
+
+```bash
+cost-guard push                                     # default: last 30 days
+cost-guard push --project ~/Projects/MyApp          # specific project
+cost-guard push --since 7                           # only last 7 days
+cost-guard push --dry-run                           # preview without HTTP
+```
+
+Requires authenticated token. Filters by `--since` (days). POSTs `{id, project, primary_model, started_at, ended_at, input_tokens, output_tokens, cost_usd}`. Continues on errors, returns 1 if any failed.
+
+### Stubs (later weeks)
+<!-- delegation-guard: ok -->
+
+- `cost-guard live` — real-time TUI dashboard (Week 2.5)
+- `cost-guard alert --budget 5` — daily spend cap (Week 3)
+
+## Pricing
+
+Per-million-token rates (verified 2026-05-23 against https://docs.claude.com/en/docs/about-claude/models):
+
+| Model | Input | Output | Cache read | Cache write 5m | Cache write 1h |
+|---|---|---|---|---|---|
+| `claude-opus-4-7` / `4-6` | $15 | $75 | $1.50 | $18.75 | $30 |
+| `claude-sonnet-4-6` / `4-5` | $3 | $15 | $0.30 | $3.75 | $6 |
+| `claude-haiku-4-5` | $1 | $5 | $0.10 | $1.25 | $2 |
+
+Unknown models return cost=0 (not None) — see `cost_guard.pricing.compute_cost_usd`.
+
+## Tests
+
+```bash
+cd cli
+pytest                                              # 50 tests, ~1s
+COSTGUARD_REAL_SMOKE=1 pytest tests/test_real_data_smoke.py  # opt-in: scans real ~/.claude/projects
+```
+
+<!-- delegation-guard: ok -->

costcut-0.0.9/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "costcut"
+version = "0.0.9"
+description = "Claude Code observability + cost optimization CLI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Eugene Kuznetsov", email = "eugene@costcut.dev" }]
+keywords = ["claude-code", "observability", "tokens", "cost", "llm"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Software Development",
+]
+dependencies = [
+  "typer>=0.12.0",
+  "httpx>=0.27.0",
+  "pydantic>=2.7.0",
+  "rich>=13.7.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+  "ruff>=0.4.0",
+  "mypy>=1.10.0",
+]
+
+[project.scripts]
+costcut = "cost_guard.cli:app"
+cost-guard = "cost_guard.cli:app"
+
+[project.urls]
+Homepage = "https://costcut.dev"
+Repository = "https://github.com/kuznetsov-ai/cost-guard"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cost_guard"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

costcut-0.0.9/src/cost_guard/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.9"

costcut-0.0.9/src/cost_guard/auth.py

@@ -0,0 +1,75 @@
+# delegation-guard: ok
+"""Authentication and token management for cost-guard."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+import httpx
+
+
+def _get_token_path() -> Path:
+    """Get the path to the token file."""
+    config_dir = Path.home() / ".config" / "cost-guard"
+    config_dir.mkdir(parents=True, exist_ok=True)
+    return config_dir / "token"
+
+
+def load_token() -> Optional[str]:
+    """Load token from env or file."""
+    # Env takes precedence
+    if env_token := os.getenv("COST_GUARD_TOKEN"):
+        return env_token
+
+    # Then file
+    token_path = _get_token_path()
+    if token_path.exists():
+        return token_path.read_text().strip()
+
+    return None
+
+
+def save_token(token: str) -> Path:
+    """Save token to file with restricted permissions."""
+    token_path = _get_token_path()
+    token_path.write_text(token)
+    token_path.chmod(0o600)
+    return token_path
+
+
+def clear_token() -> bool:
+    """Remove token file. Returns True if file existed."""
+    token_path = _get_token_path()
+    if token_path.exists():
+        token_path.unlink()
+        return True
+    return False
+
+
+def get_api_url() -> str:
+    """Get the API URL from env or default."""
+    return os.getenv("COST_GUARD_API_URL", "https://api.costcut.dev")
+
+
+async def verify_token(token: str) -> dict | None:
+    """Verify token by calling GET /v1/auth/me. Returns user dict or None."""
+    url = get_api_url()
+    headers = {"Authorization": f"Bearer {token}"}
+
+    try:
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            resp = await client.get(f"{url}/v1/auth/me", headers=headers)
+            if resp.status_code == 200:
+                return resp.json()
+            return None
+    except Exception:
+        return None
+
+
+def mask_token(token: str) -> str:
+    """Mask token for display."""
+    if len(token) <= 8:
+        return "***"
+    return f"{token[:8]}{'*' * 4}"

costcut-0.0.9/src/cost_guard/cli.py

@@ -0,0 +1,139 @@
+# delegation-guard: ok
+"""cost-guard CLI entry point."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Optional
+
+import typer
+
+from cost_guard import __version__
+from cost_guard.auth import clear_token, load_token, mask_token, save_token, verify_token
+from cost_guard.init_cmd import run_init
+from cost_guard.push import run_push
+from cost_guard.report import run_report
+
+app = typer.Typer(
+    name="cost-guard",
+    help="Claude Code observability + cost optimization.",
+    no_args_is_help=True,
+)
+auth_app = typer.Typer(help="Authentication management")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"cost-guard {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """Cost Guard CLI."""
+
+
+@app.command()
+def init(
+    target: str = typer.Option(".claude/hooks", help="Hook install path"),
+    force: bool = typer.Option(False, help="Overwrite existing hook files"),
+    dry_run: bool = typer.Option(False, help="Print what would be done, write nothing"),
+) -> None:
+    """Install hooks bundle into target directory."""
+    exit_code = run_init(target=target, force=force, dry_run=dry_run)
+    raise typer.Exit(exit_code)
+
+
+@app.command()
+def report(
+    project: str = typer.Option(".", help="Project path to scan"),
+    since: Optional[str] = typer.Option(None, help="Only include sessions since YYYY-MM-DD"),
+    last: Optional[int] = typer.Option(None, help="Show only last N sessions (default 20)"),
+    all: bool = typer.Option(False, help="Show all sessions"),
+) -> None:
+    """Show session analytics report."""
+    exit_code = run_report(project=project, since=since, last=last, all=all)
+    raise typer.Exit(exit_code)
+
+
+@auth_app.command()
+def set(api_key: str = typer.Argument(..., help="API key (starts with cg_live_)")) -> None:
+    """Set API token for authentication."""
+    if not api_key.startswith("cg_live_"):
+        typer.echo("Error: API key must start with 'cg_live_'", err=True)
+        raise typer.Exit(1)
+
+    save_token(api_key)
+    typer.echo(f"Token saved. Masked: {mask_token(api_key)}")
+
+
+@auth_app.command()
+def status() -> None:
+    """Check authentication status."""
+    token = load_token()
+    if not token:
+        typer.echo("Not logged in.", err=True)
+        raise typer.Exit(1)
+
+    user = asyncio.run(verify_token(token))
+    if user is None:
+        typer.echo("Error: Invalid token (401 or connection failed)", err=True)
+        raise typer.Exit(1)
+
+    email = user.get("email", "unknown")
+    plan = user.get("plan", "unknown")
+    typer.echo(f"Logged in as: {email} (plan: {plan})")
+    typer.echo(f"Token: {mask_token(token)}")
+
+
+@auth_app.command()
+def logout() -> None:
+    """Remove stored authentication token."""
+    if clear_token():
+        typer.echo("Logged out.")
+    else:
+        typer.echo("Not logged in (no token file found).")
+
+
+app.add_typer(auth_app, name="auth")
+
+
+@app.command()
+def push(
+    project: str = typer.Option(".", help="Project path to scan"),
+    since: Optional[int] = typer.Option(30, help="Only push sessions from last N days"),
+    dry_run: bool = typer.Option(False, help="Print what would be pushed without HTTP"),
+) -> None:
+    """Push session data to backend."""
+    exit_code = run_push(project=project, since=since, dry_run=dry_run)
+    raise typer.Exit(exit_code)
+
+
+@app.command()
+def live() -> None:
+    """Live TUI dashboard of current session (Week 2 implementation)."""
+    typer.echo("live (stub; Week 2)")
+
+
+@app.command()
+def alert(budget: float = typer.Option(5.0, help="USD daily cap")) -> None:
+    """Set daily spend cap; warn or block when exceeded (Week 3)."""
+    typer.echo(f"alert budget=${budget:.2f} (stub; Week 3)")
+
+
+@app.command()
+def sync() -> None:
+    """Push session data to cloud (Week 4 implementation)."""
+    typer.echo("sync (stub; Week 4)")
+
+
+if __name__ == "__main__":
+    app()