traceforge-toolkit 0.1.0__py3-none-any.whl

traceforge/cli/config_cmd.py

@@ -0,0 +1,130 @@
+"""Config command group — init, show, validate, dump."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import click
+import yaml
+
+from traceforge.config.defaults import DEFAULT_CONFIG_YAML
+
+
+_DEFAULT_CONFIG_PATH = Path.home() / ".traceforge" / "config.yaml"
+
+
+@click.group()
+def config() -> None:
+    """Manage traceforge configuration."""
+
+
+@config.command()
+@click.option("--force", is_flag=True, help="Overwrite existing config file.")
+def init(force: bool) -> None:
+    """Write default config to ~/.traceforge/config.yaml."""
+    if _DEFAULT_CONFIG_PATH.exists() and not force:
+        click.echo(f"Config already exists: {_DEFAULT_CONFIG_PATH}")
+        click.echo("Use --force to overwrite.")
+        sys.exit(1)
+
+    _DEFAULT_CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    _DEFAULT_CONFIG_PATH.write_text(DEFAULT_CONFIG_YAML, encoding="utf-8")
+    click.echo(f"Wrote default config to {_DEFAULT_CONFIG_PATH}")
+
+
+@config.command()
+@click.option("--config", "config_path", type=click.Path(exists=True), default=None)
+def show(config_path: str | None) -> None:
+    """Print the effective merged configuration."""
+    path = Path(config_path) if config_path else _resolve_config_path()
+    if path is None or not path.exists():
+        click.echo("No config file found. Run `traceforge config init` to create one.")
+        sys.exit(1)
+
+    content = path.read_text(encoding="utf-8")
+    click.echo(f"# Source: {path}\n")
+    click.echo(content)
+
+
+@config.command()
+@click.option("--config", "config_path", type=click.Path(exists=True), default=None)
+def validate(config_path: str | None) -> None:
+    """Validate config file without running."""
+    path = Path(config_path) if config_path else _resolve_config_path()
+    if path is None or not path.exists():
+        click.echo("No config file found.")
+        sys.exit(1)
+
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            raise ValueError("Config must be a YAML mapping")
+    except Exception as exc:
+        click.echo(f"✗ Config invalid: {exc}", err=True)
+        sys.exit(1)
+
+    # Emit the success line outside the try so a valid config is never
+    # misreported as invalid if the echo itself were to fail.
+    click.echo(f"✓ Config valid: {path}")
+
+
+@config.command()
+@click.option("--config", "config_path", type=click.Path(exists=True), default=None)
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["yaml", "json"]),
+    default="yaml",
+    help="Serialization format for the resolved config.",
+)
+def dump(config_path: str | None, output_format: str) -> None:
+    """Print the fully-resolved, effective configuration.
+
+    Unlike `show` (which prints the raw config file), `dump` runs the real
+    loader — applying the full precedence chain kwargs > env > project YAML >
+    user YAML > defaults — and serializes the typed `TraceforgeConfig` it
+    produces. With no config file present, the resolved defaults are dumped.
+    """
+    from traceforge.config.loader import load_config
+
+    if config_path:
+        # Point the real loader at the requested file via its runtime path
+        # override (TRACEFORGE_CONFIG), so the full precedence chain still
+        # applies — env vars and defaults still layer around the file.
+        previous = os.environ.get("TRACEFORGE_CONFIG")
+        os.environ["TRACEFORGE_CONFIG"] = str(Path(config_path))
+        try:
+            cfg = load_config()
+        finally:
+            if previous is None:
+                os.environ.pop("TRACEFORGE_CONFIG", None)
+            else:
+                os.environ["TRACEFORGE_CONFIG"] = previous
+    else:
+        cfg = load_config()
+
+    resolved = cfg.model_dump(mode="json")
+
+    if output_format == "json":
+        click.echo(json.dumps(resolved, indent=2))
+    else:
+        click.echo(yaml.safe_dump(resolved, sort_keys=False))
+
+
+def _resolve_config_path() -> Path | None:
+    """Find config file via env var, local, or default location."""
+    env = os.environ.get("TRACEFORGE_CONFIG")
+    if env:
+        return Path(env)
+
+    local = Path("traceforge.yaml")
+    if local.exists():
+        return local
+
+    if _DEFAULT_CONFIG_PATH.exists():
+        return _DEFAULT_CONFIG_PATH
+
+    return None

traceforge/cli/detect.py

@@ -0,0 +1,46 @@
+"""Detect command — discover installed AI coding agent frameworks."""
+
+from __future__ import annotations
+
+import json
+
+import click
+
+from traceforge.sources.auto_detect import detect_frameworks
+
+
+@click.command()
+@click.option("--json-output", "as_json", is_flag=True, help="Output as JSON array.")
+@click.option(
+    "--frameworks",
+    default=None,
+    help="Comma-separated list of frameworks to check (default: all).",
+)
+def detect(as_json: bool, frameworks: str | None) -> None:
+    """Discover installed AI coding agent frameworks."""
+    fw_list = [f.strip() for f in frameworks.split(",")] if frameworks else None
+    detected = detect_frameworks(fw_list)
+
+    if not detected:
+        if as_json:
+            click.echo("[]")
+        else:
+            click.echo("No frameworks detected.")
+        return
+
+    if as_json:
+        rows = [
+            {
+                "name": d.name,
+                "path": str(d.path),
+                "adapter": d.adapter,
+                "ingestion_mode": d.ingestion_mode,
+            }
+            for d in detected
+        ]
+        click.echo(json.dumps(rows, indent=2))
+    else:
+        click.echo(f"{'Framework':<12} {'Mode':<12} {'Path'}")
+        click.echo("─" * 60)
+        for d in detected:
+            click.echo(f"{d.name:<12} {d.ingestion_mode:<12} {d.path}")

traceforge/cli/download_cmd.py

@@ -0,0 +1,74 @@
+"""traceforge download-model — (re)fetch the titler weights.
+
+The titler weights ship in the separate ``traceforge-title-model`` package, which
+is a hard dependency of ``traceforge`` and so is normally installed automatically.
+This command is the repair/mirror fallback: it installs (or upgrades) that package
+into the current environment, from PyPI by default or from the GitHub-release
+mirror when PyPI is unavailable.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+import click
+
+#: Model wheel version to target for the GitHub-release mirror. PyPI installs
+#: resolve the newest compatible release, so this only pins the ``gh`` fallback.
+_MIRROR_VERSION = "0.2.0"
+_REPO = "dfinson/traceforge"
+
+
+def _gh_wheel_url(version: str) -> str:
+    whl = f"traceforge_title_model-{version}-py3-none-any.whl"
+    return f"https://github.com/{_REPO}/releases/download/title-model-v{version}/{whl}"
+
+
+@click.command("download-model")
+@click.option(
+    "--source",
+    type=click.Choice(["pypi", "gh"]),
+    default="pypi",
+    show_default=True,
+    help="Where to fetch the titler weights from. 'gh' uses the GitHub-release mirror.",
+)
+@click.option(
+    "--version",
+    "version",
+    default=_MIRROR_VERSION,
+    show_default=True,
+    help="Model version to fetch from the GitHub mirror (ignored for --source pypi).",
+)
+def download_model(source: str, version: str) -> None:
+    """Install the traceforge titler weights (``traceforge-title-model``).
+
+    The weights ship as a dependency and are normally already present; this
+    command exists to repair a broken install or fetch from the GitHub mirror
+    when PyPI is unreachable (``--source gh``).
+    """
+    target = "traceforge-title-model" if source == "pypi" else _gh_wheel_url(version)
+    # --force-reinstall so this reliably *repairs*: a plain --upgrade would no-op
+    # ("already satisfied") when the same version is installed but its files are
+    # missing/corrupt/LFS-pointer stubs -- exactly the state this command fixes.
+    cmd = [sys.executable, "-m", "pip", "install", "--force-reinstall", target]
+    click.echo(f"Installing titler weights from {source}: {target}")
+    try:
+        subprocess.run(cmd, check=True)
+    except FileNotFoundError:
+        raise click.ClickException(
+            "pip is not available in this environment. Install the weights with your "
+            "package manager instead, e.g.  uv pip install traceforge-title-model"
+        )
+    except subprocess.CalledProcessError as exc:
+        raise click.ClickException(f"install failed (exit {exc.returncode}). Target: {target}")
+
+    # Confirm the resolver now sees a complete head, so the message is truthful.
+    from traceforge.title._resolve import span_dir
+
+    if span_dir() is None:
+        raise click.ClickException(
+            "install completed but the span head is still not resolvable; the "
+            "environment may need to be restarted or the package is incomplete."
+        )
+    click.echo("Titler weights installed and resolvable.")

traceforge/cli/factory.py

@@ -0,0 +1,60 @@
+"""Factory for creating a fully-wired GovernancePipeline with default components."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from traceforge.governance.persistence import SystemStore
+from traceforge.governance.pipeline import GovernancePipeline
+
+if TYPE_CHECKING:
+    from traceforge.sdk.gate_policy import GatePolicy
+
+
+def create_default_pipeline(
+    store: SystemStore,
+    project_root: str | None = None,
+    policy: "GatePolicy | None" = None,
+) -> GovernancePipeline:
+    """Create a GovernancePipeline with all default components.
+
+    This is the standard way to instantiate a pipeline for CLI and Score API use.
+    """
+    from traceforge.classify.config import get_default_engine
+    from traceforge.governance.budget import BudgetTracker
+    from traceforge.governance.integrity import IntegrityVerifier
+    from traceforge.governance.labeler import GovernanceLabeler
+    from traceforge.governance.rules import parse_rules
+
+    # watch/score/replay run inside the target repo, so cwd is its identity. Defaulting
+    # here (rather than leaving project_root unset) gives per-event integrity a real repo
+    # key instead of "unknown", so a persistent system.db doesn't bucket every repo the
+    # user watches under one namespace and raise cross-repo false drift.
+    if project_root is None:
+        project_root = os.getcwd()
+
+    # Load default recommendation rules from bundled data
+    rules_path = (
+        Path(__file__).resolve().parent.parent / "classify" / "data" / "recommendation_rules.yaml"
+    )
+    rules = parse_rules(rules_path)
+
+    engine = get_default_engine()
+    # Content integrity is live by default on this primary CLI/Score path. The verifier
+    # is per-event: it derives the repo key from each event's ctx.project_root, so no
+    # construction-time repo is needed.
+    integrity_verifier = IntegrityVerifier(store)
+    labeler = GovernanceLabeler(integrity_verifier=integrity_verifier)
+    tracker = BudgetTracker()
+
+    return GovernancePipeline(
+        store=store,
+        labeler=labeler,
+        budget_tracker=tracker,
+        rules=rules,
+        engine=engine,
+        project_root=project_root,
+        policy=policy,
+    )

traceforge/cli/gate_cmd.py

@@ -0,0 +1,30 @@
+"""traceforge gate — CLI command for cross-process gating relay."""
+
+from __future__ import annotations
+
+import click
+
+
+@click.command("gate")
+@click.option("--stdin", "from_stdin", is_flag=True, help="Read event JSON from stdin.")
+@click.option(
+    "--format",
+    "output_format",
+    default="claude-code",
+    type=click.Choice(["claude-code", "json"]),
+    help="Output format for the verdict.",
+)
+def gate(from_stdin: bool, output_format: str) -> None:
+    """Relay a tool call event to the running Pipeline for gating.
+
+    Reads event JSON from stdin, looks up the Pipeline IPC server by session_id,
+    sends the event for scoring, and outputs the verdict in the specified format.
+
+    Typically invoked by agent hooks (e.g., Claude Code PreToolUse).
+    """
+    if not from_stdin:
+        raise click.UsageError("--stdin is required (only stdin mode is currently supported)")
+
+    from traceforge.gate.client import gate_from_stdin
+
+    gate_from_stdin(format=output_format)

traceforge/cli/init_cmd.py

@@ -0,0 +1,86 @@
+"""traceforge init — auto-inject hook configs for supported agents."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+
+@click.command("init")
+@click.argument("agent", type=click.Choice(["claude-code"]))
+@click.option("--project", "-p", default=".", help="Project root directory.")
+def init(agent: str, project: str) -> None:
+    """Auto-inject traceforge hook configuration for a supported agent.
+
+    Currently supported agents:
+      - claude-code: Writes PreToolUse hook to .claude/settings.json
+    """
+    project_root = Path(project).resolve()
+
+    if agent == "claude-code":
+        _init_claude_code(project_root)
+
+
+def _init_claude_code(project_root: Path) -> None:
+    """Write Claude Code PreToolUse hook config."""
+    settings_dir = project_root / ".claude"
+    settings_dir.mkdir(parents=True, exist_ok=True)
+    settings_file = settings_dir / "settings.json"
+
+    # Load existing or start fresh
+    if settings_file.exists():
+        try:
+            settings = json.loads(settings_file.read_text())
+        except (json.JSONDecodeError, OSError):
+            settings = {}
+    else:
+        settings = {}
+
+    # Determine the traceforge command
+    traceforge_cmd = _find_traceforge_command()
+
+    # Build hook config
+    hook_entry = {
+        "type": "command",
+        "command": f"{traceforge_cmd} gate --stdin",
+    }
+
+    # Insert into hooks.PreToolUse
+    hooks = settings.setdefault("hooks", {})
+    pre_tool_use = hooks.setdefault("PreToolUse", [])
+
+    # Check if traceforge hook already exists
+    for entry in pre_tool_use:
+        if isinstance(entry, dict):
+            hooks_list = entry.get("hooks", [])
+            for h in hooks_list:
+                if isinstance(h, dict) and "traceforge" in h.get("command", ""):
+                    click.echo("✓ traceforge hook already configured in .claude/settings.json")
+                    return
+
+    # Add a matcher for all tools with traceforge hook
+    pre_tool_use.append(
+        {
+            "matcher": ".*",
+            "hooks": [hook_entry],
+        }
+    )
+
+    settings_file.write_text(json.dumps(settings, indent=2) + "\n")
+    click.echo(f"✓ Wrote PreToolUse hook to {settings_file}")
+    click.echo(f"  Command: {traceforge_cmd} gate --stdin")
+
+
+def _find_traceforge_command() -> str:
+    """Find the traceforge executable path."""
+    # If running as installed package, use the entry point
+    import shutil
+
+    traceforge_path = shutil.which("traceforge")
+    if traceforge_path:
+        return traceforge_path
+    # Fallback: use python -m
+    return f"{sys.executable} -m traceforge"

traceforge/cli/replay.py

@@ -0,0 +1,130 @@
+"""Replay command — one-shot processing of captured session files."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from pathlib import Path
+
+import click
+
+logger = logging.getLogger(__name__)
+
+
+@click.command()
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--adapter", required=True, help="Adapter/mapping name (e.g., claude, codex, cline).")
+@click.option(
+    "--output",
+    "output_path",
+    type=click.Path(),
+    default=None,
+    help="Output file (JSONL). Default: console.",
+)
+@click.option(
+    "--log-level", default="INFO", type=click.Choice(["DEBUG", "INFO", "WARNING", "ERROR"])
+)
+def replay(path: str, adapter: str, output_path: str | None, log_level: str) -> None:
+    """Process a captured session file or directory through the governance pipeline."""
+    logging.basicConfig(
+        level=getattr(logging, log_level),
+        format="%(asctime)s %(levelname)-5s %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+    source = Path(path)
+    asyncio.run(_replay(source, adapter, output_path))
+
+
+async def _replay(source: Path, adapter_name: str, output_path: str | None) -> None:
+    from traceforge.adapters.mapped_json import MappedJsonAdapter
+    from traceforge.cli.factory import create_default_pipeline
+    from traceforge.cli.runner import load_mapping_path
+    from traceforge.enricher import Enricher
+    from traceforge.governance.persistence import SystemStore
+    from traceforge.pipeline import EventPipeline
+    from traceforge.sinks.callback import CallbackSink
+    from traceforge.sinks.console import ConsoleSink
+    from traceforge.sinks.jsonl import JsonlSink
+
+    # Initialize governance
+    db_path = Path.home() / ".traceforge" / "system.db"
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    store = SystemStore(db_path)
+    governance = create_default_pipeline(store)
+
+    # Load adapter
+    mapping_path = load_mapping_path(adapter_name)
+    adapter = MappedJsonAdapter.from_yaml(str(mapping_path), session_id="replay")
+
+    # Output sink
+    if output_path:
+        output_sink = JsonlSink(path=Path(output_path))
+    else:
+        output_sink = ConsoleSink(filter_actions=None, color=True)
+
+    # Count governed events as the unified pipeline stamps and emits them.
+    total_governed = 0
+
+    async def _count(event) -> None:
+        nonlocal total_governed
+        if event.metadata is not None and event.metadata.governance is not None:
+            total_governed += 1
+
+    # Unified pipeline: adapt -> enrich -> classify -> govern (stage) -> sinks, so
+    # governance is one stage and each emitted event carries metadata.governance.
+    event_pipeline = EventPipeline(
+        sinks=[output_sink, CallbackSink(on_event=_count)],
+        enricher=Enricher(),
+        governance=governance,
+    )
+
+    # Collect files to process
+    files: list[Path] = []
+    if source.is_dir():
+        files = sorted(source.rglob("*.jsonl")) + sorted(source.rglob("*.json"))
+    else:
+        files = [source]
+
+    total_events = 0
+
+    try:
+        for f in files:
+            click.echo(f"Processing: {f.name}")
+            content = f.read_text(encoding="utf-8")
+
+            # Handle JSONL (line-delimited) vs single JSON
+            if f.suffix == ".jsonl":
+                lines = [l.strip() for l in content.splitlines() if l.strip()]
+            else:
+                # Single JSON file — try as array or single object
+                try:
+                    parsed = json.loads(content)
+                    lines = (
+                        [json.dumps(item) for item in parsed]
+                        if isinstance(parsed, list)
+                        else [content]
+                    )
+                except json.JSONDecodeError:
+                    click.echo(f"  Skipping (invalid JSON): {f.name}", err=True)
+                    continue
+
+            for line in lines:
+                try:
+                    data = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+
+                for event in adapter.parse_dict(data):
+                    total_events += 1
+                    await event_pipeline.push(event)
+    finally:
+        # Flush buffered (unpaired tool-start) events and release resources even
+        # if processing raised, so the Enricher buffer is never silently dropped.
+        try:
+            await event_pipeline.close()
+        finally:
+            store.close()
+
+    click.echo(f"\nReplay complete: {total_events} events, {total_governed} governed")