traceforge-toolkit 0.1.0__py3-none-any.whl

traceforge/cli/runner.py

@@ -0,0 +1,181 @@
+"""Pipeline runner — resolves detected frameworks into runnable pipelines and multiplexes sources."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import AsyncIterator
+
+from traceforge.config.models import (
+    ConsoleSinkConfig,
+    MappedJsonAdapterConfig,
+    SqliteSinkConfig,
+)
+from traceforge.sources.auto_detect import DetectedFramework
+
+logger = logging.getLogger(__name__)
+
+
+# ─── Mapping loader ──────────────────────────────────────────────────────────
+
+_BUNDLED_MAPPINGS_DIR = Path(__file__).resolve().parent.parent / "mappings"
+
+
+def load_mapping_path(name: str) -> Path:
+    """Resolve a mapping name to its YAML file path.
+
+    Searches bundled mappings directory. Raises FileNotFoundError if not found.
+    """
+    path = _BUNDLED_MAPPINGS_DIR / f"{name}.yaml"
+    if path.exists():
+        return path
+    raise FileNotFoundError(f"No mapping found for {name!r} (searched {_BUNDLED_MAPPINGS_DIR})")
+
+
+# ─── Adapter resolution ─────────────────────────────────────────────────────
+
+ADAPTER_MAP: dict[str, MappedJsonAdapterConfig] = {
+    "claude": MappedJsonAdapterConfig(type="mapped_json", mapping="claude"),
+    "codex": MappedJsonAdapterConfig(type="mapped_json", mapping="codex"),
+    "continue": MappedJsonAdapterConfig(type="mapped_json", mapping="continue_dev"),
+    "cline": MappedJsonAdapterConfig(type="mapped_json", mapping="cline"),
+    "goose": MappedJsonAdapterConfig(type="mapped_json", mapping="goose"),
+    "amazonq": MappedJsonAdapterConfig(type="mapped_json", mapping="amazonq"),
+    "aider_markdown": MappedJsonAdapterConfig(type="mapped_json", mapping="aider"),
+}
+
+
+# ─── Resolved pipeline config ───────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class ResolvedPipeline:
+    """A fully-resolved pipeline ready to run."""
+
+    name: str
+    source_path: Path
+    ingestion_mode: str
+    adapter: MappedJsonAdapterConfig
+    sinks: list = field(default_factory=list)
+
+
+def resolve_pipelines(
+    detected: list[DetectedFramework],
+    explicit_source_paths: set[str] | None = None,
+    default_sinks: list | None = None,
+) -> list[ResolvedPipeline]:
+    """Map detected frameworks to runnable pipeline configs.
+
+    Args:
+        detected: Frameworks found by auto-detection.
+        explicit_source_paths: Paths already covered by explicit pipeline configs.
+            Auto-detected frameworks at these paths are skipped (explicit wins).
+        default_sinks: Sink configs to attach when none specified.
+
+    Returns:
+        List of resolved pipelines ready to instantiate.
+    """
+    explicit = explicit_source_paths or set()
+    sinks = default_sinks if default_sinks is not None else _default_sinks()
+    pipelines: list[ResolvedPipeline] = []
+
+    for fw in detected:
+        path_key = str(fw.path)
+        if path_key in explicit:
+            logger.debug("Skipping auto-detected %s (explicit pipeline exists)", fw.name)
+            continue
+
+        adapter = ADAPTER_MAP.get(fw.adapter)
+        if adapter is None:
+            logger.warning("No adapter mapping for framework %r (adapter=%r)", fw.name, fw.adapter)
+            continue
+
+        pipelines.append(
+            ResolvedPipeline(
+                name=fw.name,
+                source_path=fw.path,
+                ingestion_mode=fw.ingestion_mode,
+                adapter=adapter,
+                sinks=sinks,
+            )
+        )
+
+    return pipelines
+
+
+def _default_sinks() -> list:
+    """Default sinks when user hasn't configured any."""
+    return [
+        SqliteSinkConfig(type="sqlite", path=Path.home() / ".traceforge" / "traceforge.db"),
+        ConsoleSinkConfig(type="console"),
+    ]
+
+
+# ─── Source multiplexer ──────────────────────────────────────────────────────
+
+
+async def watch_jsonl_file(path: Path, start_at: str = "end") -> AsyncIterator[str]:
+    """Watch a JSONL file for new lines using polling.
+
+    Yields raw JSON line strings as they appear.
+    """
+    if not path.exists():
+        logger.info("Waiting for file to appear: %s", path)
+        while not path.exists():
+            await asyncio.sleep(1.0)
+
+    offset = path.stat().st_size if start_at == "end" else 0
+
+    while True:
+        current_size = path.stat().st_size
+        if current_size > offset:
+            with open(path, "r", encoding="utf-8") as f:
+                f.seek(offset)
+                for line in f:
+                    stripped = line.strip()
+                    if stripped:
+                        yield stripped
+                offset = f.tell()
+        await asyncio.sleep(0.5)
+
+
+async def watch_directory(
+    directory: Path, pattern: str = "*.jsonl", start_at: str = "end"
+) -> AsyncIterator[tuple[Path, str]]:
+    """Watch a directory for new JSONL files and yield (path, line) tuples.
+
+    Monitors existing files for growth and picks up new files as they appear.
+    """
+    known_files: dict[Path, int] = {}
+
+    # Initial scan
+    if directory.exists():
+        for f in directory.rglob(pattern):
+            if f.is_file():
+                known_files[f] = f.stat().st_size if start_at == "end" else 0
+
+    while True:
+        # Check for new files
+        if directory.exists():
+            for f in directory.rglob(pattern):
+                if f.is_file() and f not in known_files:
+                    known_files[f] = 0
+                    logger.info("Discovered new file: %s", f)
+
+        # Read new content from all tracked files
+        for fpath, offset in list(known_files.items()):
+            if not fpath.exists():
+                continue
+            current_size = fpath.stat().st_size
+            if current_size > offset:
+                with open(fpath, "r", encoding="utf-8") as fh:
+                    fh.seek(offset)
+                    for line in fh:
+                        stripped = line.strip()
+                        if stripped:
+                            yield (fpath, stripped)
+                    known_files[fpath] = fh.tell()
+
+        await asyncio.sleep(1.0)

traceforge/cli/score.py

@@ -0,0 +1,217 @@
+"""Score API — lightweight HTTP server for preflight tool-call scoring."""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import TYPE_CHECKING
+
+import click
+
+if TYPE_CHECKING:
+    from traceforge.governance.pipeline import GovernancePipeline
+
+logger = logging.getLogger(__name__)
+
+
+class _ScoreHandler(BaseHTTPRequestHandler):
+    """HTTP handler for POST /score endpoint."""
+
+    pipeline: "GovernancePipeline"  # set on class before server starts
+
+    def do_POST(self) -> None:
+        if self.path != "/score":
+            self._respond(404, {"error": "not found"})
+            return
+
+        content_length = int(self.headers.get("Content-Length", 0))
+        if content_length == 0:
+            self._respond(400, {"error": "empty body"})
+            return
+
+        try:
+            body = json.loads(self.rfile.read(content_length))
+        except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+            self._respond(400, {"error": f"invalid JSON: {exc}"})
+            return
+
+        # Required fields
+        tool_name = body.get("tool_name")
+        arguments = body.get("arguments")
+        session_id = body.get("session_id", "anonymous")
+
+        if not tool_name:
+            self._respond(400, {"error": "missing required field: tool_name"})
+            return
+        if arguments is None:
+            self._respond(400, {"error": "missing required field: arguments"})
+            return
+
+        # Ensure arguments is a dict for tool_input
+        if isinstance(arguments, str):
+            try:
+                arguments = json.loads(arguments)
+            except json.JSONDecodeError:
+                arguments = {"raw": arguments}
+
+        # Build payload dict matching score_tool_call's expected shape
+        score_payload = {
+            "tool_name": tool_name,
+            "tool_input": arguments,
+            "session_id": session_id,
+        }
+        if body.get("server"):
+            score_payload["server"] = body["server"]
+        if body.get("effect"):
+            score_payload["effect"] = body["effect"]
+        if body.get("role"):
+            score_payload["role"] = body["role"]
+
+        try:
+            result = self.pipeline.score_tool_call(score_payload)
+            self._respond(200, _serialize_session_meta(result))
+        except Exception as exc:
+            logger.exception("Score API error")
+            self._respond(500, {"error": str(exc)})
+
+    def do_GET(self) -> None:
+        if self.path == "/health":
+            self._respond(200, {"status": "ok"})
+        else:
+            self._respond(404, {"error": "not found"})
+
+    def _respond(self, status: int, body: dict) -> None:
+        payload = json.dumps(body, default=str).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def log_message(self, format: str, *args) -> None:  # noqa: A002
+        logger.debug("ScoreAPI: %s", format % args)
+
+
+def _serialize_session_meta(meta) -> dict:
+    """Serialize SessionMeta or EventTrace to JSON-safe dict."""
+    from traceforge.governance.results import SessionMeta
+    from traceforge.trace import EventTrace
+
+    if isinstance(meta, EventTrace):
+        result: dict = {}
+        if meta.risk_score is not None:
+            result["risk_assessment"] = {
+                "score": meta.risk_score,
+                "level": meta.risk_band,
+            }
+        if meta.suggested_action is not None:
+            result["recommendation"] = {
+                "action": meta.suggested_action,
+                "reason_code": meta.reason,
+            }
+        if meta.mechanism or meta.effect:
+            result["evidence"] = {
+                "canonical_tool": meta.canonical_tool,
+                "mechanism": meta.mechanism,
+                "effect": meta.effect,
+                "scope": list(meta.scope) if meta.scope else [],
+                "role": list(meta.role) if meta.role else [],
+            }
+        result["stage"] = meta.stage
+        return result
+
+    if isinstance(meta, SessionMeta):
+        result = {}
+        if meta.risk_assessment is not None:
+            result["risk_assessment"] = {
+                "score": meta.risk_assessment.score,
+                "level": meta.risk_assessment.level,
+                "confidence": meta.risk_assessment.confidence,
+            }
+        if meta.recommendation is not None:
+            result["recommendation"] = {
+                "action": meta.recommendation.recommended_action.value,
+                "reason_code": meta.recommendation.reason_code,
+                "canonical_id": meta.recommendation.canonical_id,
+            }
+        if meta.evidence is not None:
+            e = meta.evidence
+            result["evidence"] = {
+                "canonical_id": e.canonical_id,
+                "mechanism": e.mechanism,
+                "effect": e.effect,
+                "scope": list(e.scope) if e.scope else [],
+                "role": list(e.role) if e.role else [],
+            }
+        return result
+    # Fallback
+    return {"raw": str(meta)}
+
+
+class ScoreServer:
+    """Wraps ThreadingHTTPServer for the Score API."""
+
+    def __init__(self, pipeline: "GovernancePipeline", listen: str = "localhost:7331") -> None:
+        self._pipeline = pipeline
+        host, _, port_str = listen.rpartition(":")
+        self._host = host or "localhost"
+        self._port = int(port_str) if port_str else 7331
+        self._server: ThreadingHTTPServer | None = None
+        self._thread: threading.Thread | None = None
+
+    def start_background(self) -> None:
+        """Start the Score API in a daemon thread."""
+        _ScoreHandler.pipeline = self._pipeline
+        self._server = ThreadingHTTPServer((self._host, self._port), _ScoreHandler)
+        self._thread = threading.Thread(
+            target=self._server.serve_forever,
+            name="traceforge-score-api",
+            daemon=True,
+        )
+        self._thread.start()
+        logger.info("Score API listening on %s:%d", self._host, self._port)
+
+    def stop(self) -> None:
+        """Shut down the Score API server."""
+        if self._server:
+            self._server.shutdown()
+            self._server = None
+        if self._thread:
+            self._thread.join(timeout=5.0)
+            self._thread = None
+
+
+# ─── CLI command ─────────────────────────────────────────────────────────────
+
+
+@click.command()
+@click.option(
+    "--listen", default="localhost:7331", help="Host:port to bind (default: localhost:7331)."
+)
+@click.option("--config", "config_path", type=click.Path(exists=True), default=None)
+def score(listen: str, config_path: str | None) -> None:
+    """Run the Score API server standalone (no file watching)."""
+    from pathlib import Path
+
+    from traceforge.cli.factory import create_default_pipeline
+    from traceforge.governance.persistence import SystemStore
+
+    db_path = Path.home() / ".traceforge" / "system.db"
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    store = SystemStore(db_path)
+
+    pipeline = create_default_pipeline(store)
+
+    server = ScoreServer(pipeline, listen=listen)
+    click.echo(f"Starting Score API on {listen} ...")
+    server.start_background()
+
+    try:
+        # Block until Ctrl+C
+        threading.Event().wait()
+    except KeyboardInterrupt:
+        click.echo("\nShutting down...")
+        server.stop()
+        store.close()

traceforge/cli/status.py

@@ -0,0 +1,65 @@
+"""Status command — show traceforge system state."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import sys
+from pathlib import Path
+
+import click
+
+
+_DB_PATH = Path.home() / ".traceforge" / "system.db"
+
+
+@click.command()
+@click.option("--json-output", "as_json", is_flag=True, help="Output as JSON.")
+@click.option("--db", "db_path", type=click.Path(), default=None, help="Override DB path.")
+def status(as_json: bool, db_path: str | None) -> None:
+    """Show traceforge system state from the governance database."""
+    path = Path(db_path) if db_path else _DB_PATH
+    if not path.exists():
+        click.echo("No system database found. Has traceforge run yet?")
+        sys.exit(1)
+
+    conn = sqlite3.connect(str(path), check_same_thread=False)
+    conn.execute("PRAGMA journal_mode = WAL")
+
+    stats: dict = {}
+
+    # Session count
+    row = conn.execute("SELECT COUNT(*) FROM session_state").fetchone()
+    stats["active_sessions"] = row[0] if row else 0
+
+    # Processed events
+    row = conn.execute("SELECT COUNT(*) FROM processed_events").fetchone()
+    stats["processed_events"] = row[0] if row else 0
+
+    # MCP tool profiles
+    row = conn.execute("SELECT COUNT(*) FROM mcp_profiles").fetchone()
+    stats["mcp_profiles"] = row[0] if row else 0
+
+    # Session summaries
+    row = conn.execute("SELECT COUNT(*) FROM session_summaries").fetchone()
+    stats["completed_sessions"] = row[0] if row else 0
+
+    # Recent recommendations breakdown
+    row = conn.execute(
+        "SELECT recommendation_counts_json FROM session_summaries ORDER BY ended_at DESC LIMIT 1"
+    ).fetchone()
+    stats["last_session_recommendations"] = json.loads(row[0]) if row and row[0] else None
+
+    conn.close()
+
+    if as_json:
+        click.echo(json.dumps(stats, indent=2))
+    else:
+        click.echo("Traceforge System Status")
+        click.echo("─" * 40)
+        click.echo(f"  Active sessions:    {stats['active_sessions']}")
+        click.echo(f"  Processed events:   {stats['processed_events']}")
+        click.echo(f"  MCP profiles:       {stats['mcp_profiles']}")
+        click.echo(f"  Completed sessions: {stats['completed_sessions']}")
+        if stats["last_session_recommendations"]:
+            click.echo(f"  Last session recs:  {stats['last_session_recommendations']}")