fleetproof 0.1.0__py3-none-any.whl

fleetproof/cli.py

@@ -0,0 +1,293 @@
+"""FleetProof command-line interface.
+
+Stdlib only (argparse) — a verification tool should add as little dependency
+surface as it can. Subcommands:
+
+    init      write a starter .fleetproof/checks.json
+    check     run the independent checker, record the verdict, exit non-zero on block
+    list      list recorded runs, newest first
+    show      show one run and its sub-invocations
+    report    render the self-contained HTML run report
+    cleanup   delete run records older than N days
+    stop-gate Stop-hook entry: emit a Claude Code block decision on a false "done"
+    record    PostToolUse-hook entry: append an evidence record from hook stdin
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+# The CLI must not record its own invocations.
+os.environ.setdefault("FLEETPROOF_NO_RECORD", "1")
+
+from . import __version__
+from .checker import format_report_text, run_checks, spec_drifted
+from .checks import (
+    CheckSpecError,
+    SPEC_DRIFT_NOTE,
+    STARTER_SPEC,
+    default_checks_path,
+    load_checks,
+    short_spec_hash,
+)
+from .hookgate import record_tool_main, stop_gate_main
+from .report import write_report
+from .runlog import (
+    PROJECT_MARKER,
+    SESSION_ID_ENV,
+    list_run_records,
+    load_run,
+    project_root,
+    runs_dir,
+)
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    path = Path(args.path) if args.path else default_checks_path()
+    if path.exists() and not args.force:
+        print(f"Refusing to overwrite existing {path} (use --force).", file=sys.stderr)
+        return 1
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(STARTER_SPEC, indent=2) + "\n", encoding="utf-8")
+    print(f"Wrote starter check spec to {path}")
+    print("Edit it to declare what 'done' means for this repo, then run `fleetproof check`.")
+    return 0
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    spec_path = Path(args.spec) if args.spec else None
+    try:
+        checks = load_checks(spec_path)
+    except CheckSpecError as e:
+        _emit_error("check_spec_error", str(e), args.format)
+        return 2
+    report = run_checks(checks, record_to_log=not args.no_record, spec_path=spec_path)
+
+    # Best-effort drift note: a bare CLI run usually has no session context (so
+    # baseline is unresolvable and nothing is flagged), but when it runs inside a
+    # Claude Code session the env carries the id and we can flag drift here too.
+    session_id = os.environ.get(SESSION_ID_ENV)
+    drifted, baseline = spec_drifted(report.spec_sha256, session_id)
+
+    if args.format == "json":
+        payload = report.to_dict()
+        payload["run_id"] = report.run_id
+        payload["spec_drift"] = drifted
+        payload["session_baseline_sha256"] = baseline
+        print(json.dumps(payload, indent=2))
+    else:
+        print(format_report_text(report))
+        if drifted:
+            print(SPEC_DRIFT_NOTE)
+            print(f"  session baseline: {short_spec_hash(baseline)}")
+    return 1 if report.verdict == "fail" else 0
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    records = list_run_records()
+    rows = []
+    for r in records:
+        failed = r.failed_count
+        if args.status == "ok" and failed > 0:
+            continue
+        if args.status == "fail" and failed == 0:
+            continue
+        rows.append(r)
+        if args.limit and len(rows) >= args.limit:
+            break
+    if args.format == "json":
+        print(json.dumps({
+            "runs": [
+                {
+                    "run_id": r.run_id,
+                    "root_tool": r.root_tool,
+                    "started_at": r.started_at,
+                    "session_id": r.session_id,
+                    "sub_count": len(r.sub_invocations),
+                    "failed_count": r.failed_count,
+                }
+                for r in rows
+            ]
+        }, indent=2))
+        return 0
+    if not rows:
+        print("No runs found.")
+        return 0
+    print(f"{'run_id':<24} {'root_tool':<16} {'started':<20} {'subs':>5} {'failed':>7} {'session':<14}")
+    for r in rows:
+        print(f"{r.run_id:<24} {(r.root_tool or '-'):<16} "
+              f"{(r.started_at or '-')[:19]:<20} {len(r.sub_invocations):>5} {r.failed_count:>7} "
+              f"{_short_session(r.session_id):<14}")
+    return 0
+
+
+def _short_session(session_id: str | None) -> str:
+    """A compact session id for the list column; '-' when a run has none."""
+    if not session_id:
+        return "-"
+    return session_id if len(session_id) <= 14 else session_id[:11] + "..."
+
+
+def _cmd_show(args: argparse.Namespace) -> int:
+    r = load_run(args.run_id)
+    if r is None:
+        _emit_error("run_not_found", f"No run record for {args.run_id!r}", args.format)
+        return 1
+    if args.format == "json":
+        print(json.dumps({
+            "run_id": r.run_id,
+            "root_tool": r.root_tool,
+            "started_at": r.started_at,
+            "session_id": r.session_id,
+            "sub_invocations": [
+                {
+                    "tool": s.tool,
+                    "subcmd": s.subcmd,
+                    "started_at": s.started_at,
+                    "exit_code": s.exit_code,
+                    "duration_ms": s.duration_ms,
+                    "exception_type": s.exception_type,
+                    "record_dir": str(s.record_dir),
+                }
+                for s in r.sub_invocations
+            ],
+        }, indent=2))
+        return 0
+    print(f"{r.run_id}  root_tool={r.root_tool or '-'}  started={(r.started_at or '-')[:19]}"
+          f"  session={r.session_id or '-'}")
+    for s in r.sub_invocations:
+        if s.exit_code is None:
+            badge = "?"
+        elif s.exit_code == 0 and not s.exception_type:
+            badge = "ok"
+        else:
+            badge = "fail"
+        dur = f"{s.duration_ms:.1f}ms" if s.duration_ms is not None else "?ms"
+        print(f"  [{badge}] {s.tool} {s.subcmd} ({dur})  {s.record_dir}")
+    return 0
+
+
+def _cmd_report(args: argparse.Namespace) -> int:
+    out = Path(args.output) if args.output else project_root() / PROJECT_MARKER / "fleetproof-report.html"
+    written = write_report(out)
+    print(f"Wrote report to {written}")
+    return 0
+
+
+def _cmd_cleanup(args: argparse.Namespace) -> int:
+    rd = runs_dir()
+    deleted, skipped = [], []
+    if rd.exists():
+        cutoff = datetime.now(timezone.utc) - timedelta(days=args.older_than_days)
+        for run_dir in sorted(rd.iterdir()):
+            if not run_dir.is_dir() or run_dir.name.startswith("."):
+                continue
+            started = _run_started_at(run_dir)
+            if started is None or started >= cutoff:
+                skipped.append(run_dir.name)
+                continue
+            if not args.dry_run:
+                shutil.rmtree(run_dir, ignore_errors=True)
+            deleted.append(run_dir.name)
+    prefix = "DRY RUN " if args.dry_run else ""
+    print(f"{prefix}Deleted {len(deleted)} runs, skipped {len(skipped)}.")
+    return 0
+
+
+def _run_started_at(run_dir: Path) -> datetime | None:
+    record = load_run(run_dir.name)
+    if record and record.started_at:
+        try:
+            return datetime.fromisoformat(record.started_at)
+        except ValueError:
+            pass
+    try:
+        return datetime.fromtimestamp(run_dir.stat().st_mtime, tz=timezone.utc)
+    except OSError:
+        return None
+
+
+def _cmd_stop_gate(args: argparse.Namespace) -> int:
+    return stop_gate_main()
+
+
+def _cmd_record(args: argparse.Namespace) -> int:
+    # PostToolUse recorder must be allowed to write records.
+    os.environ["FLEETPROOF_NO_RECORD"] = "0"
+    return record_tool_main()
+
+
+def _emit_error(code: str, message: str, fmt: str) -> None:
+    if fmt == "json":
+        print(json.dumps({"ok": False, "error_code": code, "message": message}), file=sys.stderr)
+    else:
+        print(f"error ({code}): {message}", file=sys.stderr)
+
+
+def _add_format(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--format", choices=["human", "json"], default="human",
+                   help="Output format. Use json for agent consumption.")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="fleetproof",
+        description="Independent, out-of-band verification for agent fleets.",
+    )
+    parser.add_argument("--version", action="version", version=f"fleetproof {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_init = sub.add_parser("init", help="Write a starter .fleetproof/checks.json.")
+    p_init.add_argument("--path", default=None, help="Where to write the spec.")
+    p_init.add_argument("--force", action="store_true", help="Overwrite an existing spec.")
+    p_init.set_defaults(func=_cmd_init)
+
+    p_check = sub.add_parser("check", help="Run the independent checker and record the verdict.")
+    p_check.add_argument("--spec", default=None, help="Path to a check spec (default: .fleetproof/checks.json).")
+    p_check.add_argument("--no-record", action="store_true", help="Do not write to the run log.")
+    _add_format(p_check)
+    p_check.set_defaults(func=_cmd_check)
+
+    p_list = sub.add_parser("list", help="List recorded runs, newest first.")
+    p_list.add_argument("--status", choices=["ok", "fail"], default=None)
+    p_list.add_argument("--limit", type=int, default=20)
+    _add_format(p_list)
+    p_list.set_defaults(func=_cmd_list)
+
+    p_show = sub.add_parser("show", help="Show a run and its sub-invocations.")
+    p_show.add_argument("run_id")
+    _add_format(p_show)
+    p_show.set_defaults(func=_cmd_show)
+
+    p_report = sub.add_parser("report", help="Render the self-contained HTML run report.")
+    p_report.add_argument("-o", "--output", default=None, help="Output HTML path.")
+    p_report.set_defaults(func=_cmd_report)
+
+    p_cleanup = sub.add_parser("cleanup", help="Delete run records older than N days.")
+    p_cleanup.add_argument("--older-than-days", type=int, required=True)
+    p_cleanup.add_argument("--dry-run", action="store_true")
+    p_cleanup.set_defaults(func=_cmd_cleanup)
+
+    p_stop = sub.add_parser("stop-gate", help="Stop-hook entry: emit a block decision on a false 'done'.")
+    p_stop.set_defaults(func=_cmd_stop_gate)
+
+    p_rec = sub.add_parser("record", help="PostToolUse-hook entry: record a tool call from hook stdin.")
+    p_rec.set_defaults(func=_cmd_record)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

fleetproof/hookgate.py

@@ -0,0 +1,166 @@
+"""Claude Code hook entry points.
+
+These functions are what the plugin's ``type: "command"`` hooks invoke. They are
+deterministic and run in a process separate from the agent whose "done" claim
+they are judging — which is the whole product.
+
+- :func:`stop_gate_main` — the Stop hook. Runs the independent checker and, if a
+  blocking check failed, emits ``{"decision": "block", "reason": ...}`` so Claude
+  Code refuses to let the agent stop on a false "done".
+- :func:`record_tool_main` — the PostToolUse hook. Appends an evidence record for
+  the tool call that just ran. Never blocks (the tool already happened).
+
+Both read the hook payload as JSON on stdin, per the Claude Code hooks contract.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+from .checker import run_checks, spec_drifted
+from .checks import SPEC_DRIFT_NOTE, CheckSpecError, load_checks, short_spec_hash
+from .runlog import SESSION_ID_ENV, record
+
+
+def _read_hook_input() -> dict[str, Any]:
+    try:
+        data = sys.stdin.read()
+    except Exception:
+        return {}
+    # Tolerate a UTF-8 BOM (some shells prepend one when piping) — silently
+    # losing the payload would silently lose session grouping and drift
+    # detection, which is exactly the quiet degradation this tool exists to avoid.
+    data = data.lstrip("\ufeff")
+    if not data.strip():
+        return {}
+    try:
+        parsed = json.loads(data)
+        return parsed if isinstance(parsed, dict) else {}
+    except json.JSONDecodeError:
+        return {}
+
+
+def _apply_session_id(payload: dict[str, Any]) -> None:
+    """Thread the Claude Code session id into the run log.
+
+    Every hook invocation receives a JSON payload on stdin whose ``session_id``
+    field identifies the session (see the "hook input" section of
+    https://code.claude.com/docs/en/hooks). Each hook fires as its own OS
+    process with a fresh run id, so without this the report shows one session as
+    several unrelated root runs. Carrying the id via env lets the root record
+    (written in this same process) group them back together.
+    """
+    sid = payload.get("session_id")
+    if isinstance(sid, str) and sid:
+        os.environ[SESSION_ID_ENV] = sid
+
+
+def stop_gate() -> tuple[dict[str, Any] | None, int]:
+    """Run the checker and decide whether Claude may stop.
+
+    Returns ``(decision_dict_or_None, exit_code)``. A None decision + exit 0 means
+    "let the agent stop"; a block decision + exit 0 means "you claimed done but the
+    independent checker disagrees — keep going."
+    """
+    try:
+        checks = load_checks()
+    except CheckSpecError:
+        # No spec (or a broken one) means nothing to enforce. Fail open, but visibly:
+        # a verification tool must never pretend it verified when it did not.
+        return None, 0
+
+    if not checks:
+        return None, 0
+
+    report = run_checks(checks)
+
+    # Spec-drift check: did the checks.json that just graded this verdict differ
+    # from the one the session's first verdict was graded against? An agent is
+    # allowed to author checks.json, so a failing agent could quietly weaken it to
+    # slip this gate. We don't block on drift alone (v0.1 policy) — we make it loud.
+    session_id = os.environ.get(SESSION_ID_ENV)
+    drifted, baseline = spec_drifted(report.spec_sha256, session_id)
+
+    if report.verdict == "pass":
+        if drifted:
+            # A pass with drift still passes, but must not pass *silently*.
+            return {
+                "hookSpecificOutput": {
+                    "hookEventName": "Stop",
+                    "additionalContext": _drift_context(report.spec_sha256, baseline),
+                },
+            }, 0
+        return None, 0
+
+    failing = report.blocking_failures
+    lines = [f"{r.id} ({r.detail})" for r in failing]
+    reason = (
+        f"FleetProof: {len(failing)}/{report.total} blocking check(s) failed — "
+        + "; ".join(lines)
+        + ". The agent reported done; the independent checker disagrees. "
+        "Fix the failures and let the checker re-run before stopping."
+    )
+    if drifted:
+        reason += " " + SPEC_DRIFT_NOTE
+    decision = {
+        "decision": "block",
+        "reason": reason,
+        "hookSpecificOutput": {
+            "hookEventName": "Stop",
+            "additionalContext": _evidence_context(report, drifted, baseline),
+        },
+    }
+    return decision, 0
+
+
+def _drift_context(current_hash: str | None, baseline_hash: str | None) -> str:
+    """The unmissable drift annotation, with both hashes for a reviewer to diff."""
+    return (
+        f"{SPEC_DRIFT_NOTE}\n"
+        f"- current spec hash:  {short_spec_hash(current_hash)}\n"
+        f"- session baseline:   {short_spec_hash(baseline_hash)}"
+    )
+
+
+def _evidence_context(report, drifted: bool = False, baseline_hash: str | None = None) -> str:
+    parts = []
+    if drifted:
+        parts.append(_drift_context(report.spec_sha256, baseline_hash))
+    for r in report.results:
+        status = "pass" if r.passed else ("FAIL" if r.blocking else "warn")
+        parts.append(f"- [{status}] {r.id}: {r.detail}")
+    parts.append(f"Spec hash: {short_spec_hash(report.spec_sha256)}")
+    if report.run_id:
+        parts.append(f"Evidence recorded under run {report.run_id} in .fleetproof/runs/.")
+    return "\n".join(parts)
+
+
+def stop_gate_main() -> int:
+    # Consume stdin per contract; the verdict is checker-driven, but the payload
+    # still carries the session id we group this run's evidence under.
+    _apply_session_id(_read_hook_input())
+    decision, code = stop_gate()
+    if decision is not None:
+        sys.stdout.write(json.dumps(decision))
+    return code
+
+
+def record_tool_main() -> int:
+    """PostToolUse recorder: accrete an evidence record. Always non-blocking."""
+    payload = _read_hook_input()
+    _apply_session_id(payload)
+    tool_name = str(payload.get("tool_name", "unknown"))
+    try:
+        with record("claude-tool", tool_name, {"tool_name": tool_name}) as handle:
+            handle.set_output({
+                "tool_name": tool_name,
+                "tool_input": payload.get("tool_input"),
+                "tool_response_present": "tool_response" in payload,
+            })
+    except Exception:
+        # An evidence-recorder that crashes must not break the agent's turn.
+        return 0
+    return 0