codeframe-ai 0.9.0__py3-none-any.whl

codeframe/cli/stats_commands.py

@@ -0,0 +1,311 @@
+"""CLI stats commands for headless token/cost tracking.
+
+This module provides commands for viewing token usage and cost statistics
+directly from the local workspace database (no server required):
+
+- tokens: View workspace token usage summary
+- costs: View cost report with optional period filtering
+- export: Export usage data to CSV or JSON
+
+Usage:
+    cf stats tokens                    # Workspace token summary
+    cf stats tokens --task <id>        # Per-task breakdown
+    cf stats costs                     # All-time costs
+    cf stats costs --period month      # Last 30 days
+    cf stats export --format csv --output tokens.csv
+"""
+
+import logging
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.table import Table
+
+from codeframe.cli.helpers import console
+
+logger = logging.getLogger(__name__)
+
+stats_app = typer.Typer(
+    name="stats",
+    help="Token usage and cost statistics",
+    no_args_is_help=True,
+)
+
+
+def _get_db():
+    """Get database from current workspace.
+
+    Looks for .codeframe/state.db relative to the current directory.
+
+    Returns:
+        Initialized Database instance.
+
+    Raises:
+        typer.Exit: If no workspace is found.
+    """
+    from codeframe.platform_store.database import Database
+
+    db_path = Path(".codeframe/state.db")
+    if not db_path.exists():
+        console.print("[red]Error:[/red] No workspace found. Run 'cf init' first.")
+        raise typer.Exit(1)
+    db = Database(db_path)
+    db.initialize()
+    return db
+
+
+def _get_tracker(db):
+    """Create a MetricsTracker from a database instance.
+
+    Args:
+        db: Initialized Database instance.
+
+    Returns:
+        MetricsTracker instance.
+    """
+    from codeframe.lib.metrics_tracker import MetricsTracker
+
+    return MetricsTracker(db=db)
+
+
+def _format_number(n: int) -> str:
+    """Format number with thousands separator."""
+    return f"{n:,}"
+
+
+@stats_app.command()
+def tokens(
+    task: Optional[int] = typer.Option(
+        None, "--task", "-t", help="Filter by task ID for per-task breakdown"
+    ),
+):
+    """Show workspace token usage summary.
+
+    Displays total tokens used across all tasks, with input/output breakdown
+    and per-model statistics. Use --task to filter to a specific task.
+
+    Examples:
+        cf stats tokens                # Workspace summary
+        cf stats tokens --task 1       # Task 1 breakdown
+    """
+    db = _get_db()
+    try:
+        tracker = _get_tracker(db)
+
+        if task is not None:
+            # Per-task summary
+            summary = tracker.get_task_token_summary(task)
+
+            console.print(f"\n[bold]Token Usage for Task {task}[/bold]\n")
+
+            table = Table(show_header=True, title=None)
+            table.add_column("Metric", style="cyan")
+            table.add_column("Value", justify="right")
+
+            table.add_row("Total Tokens", _format_number(summary["total_tokens"]))
+            table.add_row("Input Tokens", _format_number(summary["total_input_tokens"]))
+            table.add_row("Output Tokens", _format_number(summary["total_output_tokens"]))
+            table.add_row("Total Cost", f"${summary['total_cost_usd']:.4f}")
+            table.add_row("LLM Calls", str(summary["call_count"]))
+
+            console.print(table)
+        else:
+            # Workspace-wide summary
+            records = db.get_workspace_token_usage()
+
+            total_input = 0
+            total_output = 0
+            total_cost = 0.0
+            model_stats: dict[str, dict] = {}
+
+            for record in records:
+                total_input += record["input_tokens"]
+                total_output += record["output_tokens"]
+                total_cost += record["estimated_cost_usd"]
+
+                model = record["model_name"]
+                if model not in model_stats:
+                    model_stats[model] = {
+                        "input_tokens": 0,
+                        "output_tokens": 0,
+                        "cost_usd": 0.0,
+                        "calls": 0,
+                    }
+                model_stats[model]["input_tokens"] += record["input_tokens"]
+                model_stats[model]["output_tokens"] += record["output_tokens"]
+                model_stats[model]["cost_usd"] += record["estimated_cost_usd"]
+                model_stats[model]["calls"] += 1
+
+            total_tokens = total_input + total_output
+
+            console.print("\n[bold]Workspace Token Usage Summary[/bold]\n")
+
+            summary_table = Table(show_header=True)
+            summary_table.add_column("Metric", style="cyan")
+            summary_table.add_column("Value", justify="right")
+
+            summary_table.add_row("Total Tokens", _format_number(total_tokens))
+            summary_table.add_row("Input Tokens", _format_number(total_input))
+            summary_table.add_row("Output Tokens", _format_number(total_output))
+            summary_table.add_row("Total Cost", f"${total_cost:.4f}")
+            summary_table.add_row("LLM Calls", str(len(records)))
+
+            console.print(summary_table)
+
+            if model_stats:
+                console.print("\n[bold]By Model:[/bold]")
+                model_table = Table(show_header=True)
+                model_table.add_column("Model", style="cyan")
+                model_table.add_column("Tokens", justify="right")
+                model_table.add_column("Cost", justify="right")
+                model_table.add_column("Calls", justify="right")
+
+                for model_name, stats in model_stats.items():
+                    model_table.add_row(
+                        model_name,
+                        _format_number(stats["input_tokens"] + stats["output_tokens"]),
+                        f"${stats['cost_usd']:.4f}",
+                        str(stats["calls"]),
+                    )
+
+                console.print(model_table)
+    finally:
+        db.close()
+
+
+@stats_app.command()
+def costs(
+    period: Optional[str] = typer.Option(
+        None,
+        "--period",
+        "-p",
+        help="Time period: 'day' (24h), 'week' (7d), 'month' (30d)",
+    ),
+):
+    """Show cost report.
+
+    Displays total costs and per-model breakdown. Use --period to filter
+    to a recent time window.
+
+    Examples:
+        cf stats costs                 # All-time costs
+        cf stats costs --period month  # Last 30 days
+        cf stats costs --period week   # Last 7 days
+        cf stats costs --period day    # Last 24 hours
+    """
+    db = _get_db()
+    try:
+        # Calculate date range from period
+        start_date = None
+        end_date = None
+        now = datetime.now(timezone.utc)
+
+        if period == "day":
+            start_date = now - timedelta(days=1)
+        elif period == "week":
+            start_date = now - timedelta(weeks=1)
+        elif period == "month":
+            start_date = now - timedelta(days=30)
+        elif period is not None:
+            console.print(
+                f"[red]Error:[/red] Unknown period '{period}'. Use 'day', 'week', or 'month'."
+            )
+            raise typer.Exit(1)
+
+        # Single fetch: get raw records and compute summary + per-model breakdown in one pass
+        records = db.get_workspace_token_usage(start_date=start_date, end_date=end_date)
+
+        total_cost = 0.0
+        total_tokens = 0
+        model_costs: dict[str, dict] = {}
+        for record in records:
+            cost = record["estimated_cost_usd"]
+            tokens = record["input_tokens"] + record["output_tokens"]
+            total_cost += cost
+            total_tokens += tokens
+
+            model = record["model_name"]
+            if model not in model_costs:
+                model_costs[model] = {"cost_usd": 0.0, "tokens": 0, "calls": 0}
+            model_costs[model]["cost_usd"] += cost
+            model_costs[model]["tokens"] += tokens
+            model_costs[model]["calls"] += 1
+
+        period_label = f" ({period})" if period else " (all time)"
+        console.print(f"\n[bold]Cost Report{period_label}[/bold]\n")
+
+        table = Table(show_header=True)
+        table.add_column("Metric", style="cyan")
+        table.add_column("Value", justify="right")
+
+        table.add_row("Total Cost", f"${total_cost:.4f}")
+        table.add_row("Total Tokens", _format_number(total_tokens))
+        table.add_row("LLM Calls", str(len(records)))
+
+        console.print(table)
+
+        if model_costs:
+            console.print("\n[bold]By Model:[/bold]")
+            model_table = Table(show_header=True)
+            model_table.add_column("Model", style="cyan")
+            model_table.add_column("Cost", justify="right")
+            model_table.add_column("Tokens", justify="right")
+            model_table.add_column("Calls", justify="right")
+
+            for model_name, stats in model_costs.items():
+                model_table.add_row(
+                    model_name,
+                    f"${stats['cost_usd']:.4f}",
+                    _format_number(stats["tokens"]),
+                    str(stats["calls"]),
+                )
+
+            console.print(model_table)
+    finally:
+        db.close()
+
+
+@stats_app.command("export")
+def export_data(
+    format: str = typer.Option(
+        "csv", "--format", "-f", help="Output format: csv or json"
+    ),
+    output: str = typer.Option(
+        ..., "--output", "-o", help="Output file path"
+    ),
+    task: Optional[int] = typer.Option(
+        None, "--task", "-t", help="Filter by task ID"
+    ),
+):
+    """Export usage data to CSV or JSON.
+
+    Exports raw token usage records to a file for external analysis.
+    Use --task to export records for a single task only.
+
+    Examples:
+        cf stats export --format csv --output tokens.csv
+        cf stats export --format json --output tokens.json
+        cf stats export --format csv --output task1.csv --task 1
+    """
+    from codeframe.lib.metrics_tracker import MetricsTracker
+
+    db = _get_db()
+    try:
+        if task is not None:
+            records = db.get_batch_token_usage(task_ids=[task])
+        else:
+            records = db.get_workspace_token_usage()
+
+        if format == "csv":
+            MetricsTracker.export_to_csv(records, output)
+        elif format == "json":
+            MetricsTracker.export_to_json(records, output)
+        else:
+            console.print(f"[red]Error:[/red] Unknown format '{format}'. Use 'csv' or 'json'.")
+            raise typer.Exit(1)
+
+        console.print(f"Exported {len(records)} records to {output}")
+    finally:
+        db.close()

codeframe/cli/telemetry_runtime.py

@@ -0,0 +1,153 @@
+"""Telemetry-aware CLI entry wrapper (issue #616).
+
+Wraps the Typer app to provide: the one-time opt-in prompt, command timing,
+success/failure capture, and crash reporting. Telemetry can never change the
+CLI's behavior — every telemetry step is best-effort and silent on failure,
+and the wrapped app's exit code / exception always propagates unchanged.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import time
+from typing import Optional
+
+import click
+import typer
+import typer.main
+from rich.console import Console
+
+from codeframe.core import telemetry
+
+logger = logging.getLogger(__name__)
+
+console = Console()
+
+# Bounded wait for the fire-and-forget send at process exit. Worst case this
+# adds 1s to an opted-in command; opted-out commands are unaffected.
+_SEND_JOIN_SECONDS = 1.0
+
+
+def _is_interactive() -> bool:
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def resolve_command_name(cli_app: typer.Typer, args: list[str]) -> Optional[str]:
+    """Map argv tokens to a registered command path ("work batch run").
+
+    Only names that exist in the command tree are ever returned — arbitrary
+    user tokens (file paths, task ids, typos) can never leak into telemetry.
+    Returns None when no command token is present (bare ``cf`` / ``--help``),
+    and "unknown" when the first token matches nothing.
+    """
+    group = typer.main.get_command(cli_app)
+    path: list[str] = []
+    for token in args:
+        if token.startswith("-"):
+            continue
+        if not isinstance(group, click.Group):
+            break
+        command = group.commands.get(token)
+        if command is None:
+            break
+        path.append(token)
+        group = command
+    if path:
+        return " ".join(path)
+    has_positional = any(not t.startswith("-") for t in args)
+    return "unknown" if has_positional else None
+
+
+def maybe_prompt_first_run(args: list[str]) -> None:
+    """One-time opt-in prompt (default No). Skipped when non-interactive, when
+    an env override is active, when already prompted, and during ``cf config``."""
+    try:
+        if not args or args[0].startswith("-") or args[0] == "config":
+            return
+        if telemetry.env_override() is not None:
+            return
+        if os.environ.get("DO_NOT_TRACK", "").strip().lower() not in ("", "0", "false"):
+            return
+        if not _is_interactive():
+            return
+        config = telemetry.load_config()
+        if config.prompted:
+            return
+        console.print(
+            "\n[bold]Help improve CodeFRAME?[/bold] Share anonymous usage events and "
+            "crash reports (command name, duration, version, OS — never code, "
+            "prompts, or file paths). Details: PRIVACY.md. "
+            "Change anytime: [cyan]cf config telemetry on|off[/cyan]"
+        )
+        answer = typer.confirm("Enable anonymous telemetry?", default=False)
+        config.enabled = answer
+        config.prompted = True
+        telemetry.save_config(config)
+        console.print()
+    except (click.Abort, KeyboardInterrupt):
+        raise
+    except Exception:
+        logger.debug("Telemetry first-run prompt failed", exc_info=True)
+
+
+def _coerce_exit_code(code: object) -> int:
+    if code is None:
+        return 0
+    if isinstance(code, int):
+        return code
+    return 1
+
+
+def _dispatch(
+    command: Optional[str],
+    start: float,
+    exit_code: int,
+    crash: Optional[BaseException] = None,
+) -> None:
+    """Build and send events for this invocation. Never raises."""
+    try:
+        if command is None or not telemetry.is_enabled():
+            return
+        config = telemetry.ensure_config()
+        duration_ms = int((time.monotonic() - start) * 1000)
+        events = [
+            telemetry.build_command_event(
+                command=command,
+                duration_ms=duration_ms,
+                exit_code=exit_code,
+                anonymous_id=config.anonymous_id,
+            )
+        ]
+        if crash is not None:
+            events.append(telemetry.build_crash_event(crash, config.anonymous_id))
+        thread = telemetry.send_events_background(events, telemetry.resolve_endpoint())
+        thread.join(_SEND_JOIN_SECONDS)
+    except Exception:
+        logger.debug("Telemetry dispatch failed", exc_info=True)
+
+
+def run(cli_app: typer.Typer) -> None:
+    """Run the Typer app with telemetry instrumentation around it."""
+    args = sys.argv[1:]
+    maybe_prompt_first_run(args)
+    command = resolve_command_name(cli_app, args)
+    start = time.monotonic()
+    try:
+        cli_app(prog_name="codeframe")
+    except SystemExit as e:
+        _dispatch(command, start, _coerce_exit_code(e.code))
+        raise
+    except (KeyboardInterrupt, click.Abort):
+        _dispatch(command, start, 130)
+        raise
+    except BaseException as e:
+        # Unhandled crash: record it, then let it propagate so Typer's
+        # excepthook still prints the traceback and the exit code is unchanged.
+        _dispatch(command, start, 1, crash=e)
+        raise
+    else:
+        # Click standalone mode normally exits via SystemExit; cover the
+        # non-standalone path for completeness.
+        _dispatch(command, start, 0)

codeframe/cli/validators.py

@@ -0,0 +1,123 @@
+"""CLI validation helpers for pre-command checks."""
+
+import os
+from pathlib import Path
+
+import typer
+from dotenv import load_dotenv
+from rich.console import Console
+
+console = Console()
+
+
+def require_anthropic_api_key() -> str:
+    """Ensure ANTHROPIC_API_KEY is available, loading from .env if needed.
+
+    Checks os.environ first. If not found, attempts to load from .env files
+    (~/.env as base, then cwd/.env with override). If found after loading,
+    sets in os.environ so subprocesses inherit it.
+
+    Returns:
+        The API key string.
+
+    Raises:
+        typer.Exit: If the key cannot be found anywhere.
+    """
+    key = os.getenv("ANTHROPIC_API_KEY")
+    if key:
+        return key
+
+    # Try loading from .env files (same priority as app.py)
+    cwd_env = Path.cwd() / ".env"
+    home_env = Path.home() / ".env"
+
+    if home_env.exists():
+        load_dotenv(home_env)
+    if cwd_env.exists():
+        load_dotenv(cwd_env, override=True)
+
+    key = os.getenv("ANTHROPIC_API_KEY")
+    if key:
+        os.environ["ANTHROPIC_API_KEY"] = key
+        return key
+
+    console.print(
+        "[red]Error:[/red] ANTHROPIC_API_KEY is not set. "
+        "Set it in your environment or add it to a .env file."
+    )
+    raise typer.Exit(1)
+
+
+def require_openai_api_key() -> str:
+    """Ensure OPENAI_API_KEY is available, loading from .env if needed.
+
+    Checks os.environ first. If not found, attempts to load from .env files
+    (~/.env as base, then cwd/.env with override). If found after loading,
+    sets in os.environ so subprocesses inherit it.
+
+    Returns:
+        The API key string.
+
+    Raises:
+        typer.Exit: If the key cannot be found anywhere.
+    """
+    key = os.getenv("OPENAI_API_KEY")
+    if key:
+        return key
+
+    cwd_env = Path.cwd() / ".env"
+    home_env = Path.home() / ".env"
+
+    if home_env.exists():
+        load_dotenv(home_env)
+    if cwd_env.exists():
+        load_dotenv(cwd_env, override=True)
+
+    key = os.getenv("OPENAI_API_KEY")
+    if key:
+        os.environ["OPENAI_API_KEY"] = key
+        return key
+
+    console.print(
+        "[red]Error:[/red] OPENAI_API_KEY is not set. "
+        "Set it in your environment or add it to a .env file."
+    )
+    raise typer.Exit(1)
+
+
+def require_e2b_api_key() -> str:
+    """Ensure E2B_API_KEY is available, loading from .env if needed.
+
+    Checks os.environ first. If not found, attempts to load from .env files
+    (~/.env as base, then cwd/.env with override). If found after loading,
+    sets in os.environ so subprocesses inherit it.
+
+    Returns:
+        The API key string.
+
+    Raises:
+        typer.Exit: If the key cannot be found anywhere.
+    """
+    key = os.getenv("E2B_API_KEY")
+    if key:
+        return key
+
+    cwd_env = Path.cwd() / ".env"
+    home_env = Path.home() / ".env"
+
+    if home_env.exists():
+        load_dotenv(home_env)
+    if cwd_env.exists():
+        load_dotenv(cwd_env, override=True)
+
+    key = os.getenv("E2B_API_KEY")
+    if key:
+        os.environ["E2B_API_KEY"] = key
+        return key
+
+    console.print(
+        "[red]Error:[/red] E2B_API_KEY is not set. "
+        "Set it in your environment or add it to a .env file. "
+        "Get your key at https://e2b.dev"
+    )
+    raise typer.Exit(1)