codereview-loop 0.13.0__py3-none-any.whl

codereview/crash.py

@@ -0,0 +1,247 @@
+"""Crash handling — release-gate row L17.
+
+An unexpected error must never reach the user as a raw traceback,
+and must never be mistaken for a verdict. `run_guarded` wraps the
+command-line entry point:
+
+  * any uncaught exception prints ONE line to stderr, writes a
+    redacted crash note next to the records, and exits 2 — the
+    same code as "inconclusive", so CI can never read a crash as
+    a PASS (0) or a plain block (1);
+  * `--debug` or CODEREVIEW_DEBUG=1 additionally prints the
+    redacted traceback;
+  * KeyboardInterrupt exits 130 with one line; a closed pipe
+    exits quietly (141);
+  * everything about reporting is best-effort: nothing in this
+    module can raise out of `run_guarded`, change a gate
+    outcome, or delay the exit beyond the short ping timeout.
+
+The crash note is a local file. It is redacted with the same
+`redact_secrets` the records use, and it never contains the
+environment. Sending anything anywhere is feedback.py's job, is
+opt-in, and is attempted only after the note is on disk.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import os
+import platform
+import sys
+import traceback
+
+from .core import VERSION, redact_secrets
+
+SCHEMA = "codereview.crash/1"
+EXIT_CRASH = 2
+EXIT_INTERRUPT = 130
+EXIT_BROKEN_PIPE = 141
+
+DOCS_POINTER = ("This is a bug; run 'codereview support-bundle' "
+                "and see SECURITY.md / CONTRIBUTING.md.")
+
+_SECRET_FLAG_WORDS = ("key", "token", "secret", "password", "passwd",
+                      "credential", "auth")
+_MAX_MESSAGE = 500
+_MAX_TRACEBACK = 20000
+
+# Callables the entry points register to run after a crash (for
+# example: mark a GitHub commit status pending). Best-effort.
+_crash_hooks = []
+
+
+def register_crash_hook(fn):
+    _crash_hooks.append(fn)
+
+
+def clear_crash_hooks():
+    del _crash_hooks[:]
+
+
+def build_identity():
+    """Version, and the git hash when the build stamped one
+    (src/codereview/_build_info.py with GIT_HASH, or the
+    CODEREVIEW_GIT_HASH variable)."""
+    git_hash = os.environ.get("CODEREVIEW_GIT_HASH", "").strip() \
+        or None
+    if git_hash is None:
+        try:
+            from . import _build_info  # type: ignore
+            git_hash = getattr(_build_info, "GIT_HASH", None)
+        except Exception:  # noqa: BLE001 — optional module
+            git_hash = None
+    return {"version": VERSION, "git_hash": git_hash}
+
+
+def redact_argv(argv):
+    """Redact a command line: secret-shaped text in any argument,
+    and the value after (or inside) a flag whose name looks like
+    it carries a credential."""
+    out = []
+    hide_next = False
+    for arg in argv or []:
+        arg = str(arg)
+        if hide_next:
+            out.append("[REDACTED]")
+            hide_next = False
+            continue
+        if arg.startswith("-"):
+            name, eq, _value = arg.partition("=")
+            if any(w in name.lower() for w in _SECRET_FLAG_WORDS):
+                if eq:
+                    out.append(name + "=[REDACTED]")
+                else:
+                    out.append(arg)
+                    hide_next = True
+                continue
+        out.append(redact_secrets(arg))
+    return out
+
+
+def _command_name(argv):
+    for arg in argv or []:
+        if not str(arg).startswith("-"):
+            return str(arg)[:40]
+        break
+    return "review"
+
+
+def _safe_text(text, limit):
+    try:
+        return redact_secrets(str(text))[:limit]
+    except Exception:  # noqa: BLE001
+        return "[unavailable]"
+
+
+def build_crash_note(exc, argv):
+    tb_text = "".join(traceback.format_exception(
+        type(exc), exc, exc.__traceback__))
+    note = {
+        "schema": SCHEMA,
+        "created_at": datetime.datetime.now(
+            datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        **build_identity(),
+        "python": platform.python_version(),
+        "platform": platform.system(),
+        "machine": platform.machine(),
+        "command": _command_name(argv),
+        "argv": redact_argv(argv),
+        "exception_type": type(exc).__name__,
+        "message": _safe_text(exc, _MAX_MESSAGE),
+        "traceback": _safe_text(tb_text, _MAX_TRACEBACK),
+    }
+    return note
+
+
+def _crash_dir(argv):
+    override = os.environ.get("CODEREVIEW_CRASH_DIR", "").strip()
+    if override:
+        return override
+    args = [str(a) for a in argv or []]
+    for i, arg in enumerate(args):
+        if arg == "--out" and i + 1 < len(args):
+            return args[i + 1]
+        if arg.startswith("--out="):
+            return arg[len("--out="):]
+    return "."
+
+
+def write_crash_note(note, argv):
+    """Write the note; return its path, or None when no directory
+    could be written (never raises)."""
+    stamp = note["created_at"].replace("-", "").replace(":", "")
+    name = f"codereview-crash-{stamp}-{os.getpid()}.json"
+    for directory in (_crash_dir(argv), "."):
+        try:
+            os.makedirs(directory, exist_ok=True)
+            path = os.path.join(directory, name)
+            fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+                         0o600)
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                json.dump(note, fh, indent=2, sort_keys=True)
+                fh.write("\n")
+            return path
+        except OSError:
+            continue
+    return None
+
+
+def _say(text):
+    try:
+        print(text, file=sys.stderr)
+    except Exception:  # noqa: BLE001 — stderr itself may be gone
+        pass
+
+
+def _split_debug(argv):
+    """-> (argv without --debug, debug_requested)."""
+    debug = os.environ.get("CODEREVIEW_DEBUG", "").strip() == "1"
+    clean = []
+    for arg in argv:
+        if arg == "--debug":
+            debug = True
+        else:
+            clean.append(arg)
+    return clean, debug
+
+
+def _handle_crash(exc, argv, debug):
+    try:
+        note = build_crash_note(exc, argv)
+        path = write_crash_note(note, argv)
+    except Exception:  # noqa: BLE001 — the handler must not crash
+        note, path = None, None
+    kind = type(exc).__name__
+    message = _safe_text(exc, 200).replace("\n", " ")
+    line = f"codereview: internal error ({kind}): {message}. " \
+           f"{DOCS_POINTER}"
+    if path:
+        line += f" Crash note: {path}"
+    _say(line)
+    if debug and note is not None:
+        _say(note["traceback"].rstrip())
+    for hook in list(_crash_hooks):
+        try:
+            hook()
+        except Exception:  # noqa: BLE001 — best effort only
+            pass
+    if note is not None:
+        try:
+            from . import feedback
+            feedback.maybe_send_crash_ping(note, exc)
+        except Exception:  # noqa: BLE001 — never affects the exit
+            pass
+
+
+def run_guarded(fn, argv=None):
+    """Run `fn(argv)` (the CLI main) under the crash policy and
+    return the process exit code."""
+    raw = list(sys.argv[1:] if argv is None else argv)
+    clean, debug = _split_debug(raw)
+    try:
+        rc = fn(clean)
+        return 0 if rc is None else rc
+    except SystemExit as exc:
+        code = exc.code
+        if code is None:
+            return 0
+        if isinstance(code, int):
+            return code
+        _say(str(code))
+        return 1
+    except KeyboardInterrupt:
+        _say("codereview: interrupted.")
+        return EXIT_INTERRUPT
+    except BrokenPipeError:
+        try:
+            devnull = os.open(os.devnull, os.O_WRONLY)
+            os.dup2(devnull, sys.stdout.fileno())
+        except Exception:  # noqa: BLE001
+            pass
+        return EXIT_BROKEN_PIPE
+    except Exception as exc:  # noqa: BLE001 — the point of this module
+        _handle_crash(exc, clean, debug)
+        return EXIT_CRASH
+    finally:
+        clear_crash_hooks()

codereview/discovery.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+"""codereview agent-CLI discovery — find the agent CLIs a user
+already has installed, so first-run setup can offer them as
+review seats (Epic K1).
+
+The audience: users who run subscription-authenticated agent
+CLIs (Claude Code, Codex, ...) and have no API keys. Agent seats
+have existed since v0.7.0, but the setup wizard never looked at
+the machine — a user had to know the agent:<name>:<command>
+syntax and type a correct non-interactive invocation from
+memory. Discovery closes that surface gap; it adds NO new
+execution capability: a discovered seat is an ordinary agent
+spec, executed, recorded, and probed exactly like a hand-typed
+one.
+
+Honesty rules (the reason this module is small):
+
+  * A CLI is reported only when its binary is actually found on
+    PATH (shutil.which semantics: present AND executable;
+    directories and non-executable files do not count).
+  * Each found binary gets a cheap `--version` probe. A failed
+    probe is reported as failed, in those words — never smoothed
+    over, never silently treated as working.
+  * A seat command is pre-filled ONLY where this repository
+    carries a verified non-interactive invocation (the spec's
+    U6 rule: templates enter the table as build-phase probes
+    verify them). Since Epic K2's U6 probe matrix, that is all
+    three entries, each with its provenance class recorded at
+    the entry: Claude Code (the shipped example wrapper,
+    examples/agent-seat-claude.sh), Codex (invocation form
+    verified live against codex-cli 0.164.0-alpha.9's own
+    --help plus one logged-out exec probe, stdout contract
+    from the official non-interactive docs), and Gemini CLI
+    (official docs only — not installed on the build VM, so
+    no live verification; the entry says so). A CLI whose
+    invocation were still UNVERIFIED would be reported as
+    found, with the reason it is not offerable; the user can
+    still seat one by typing an agent: spec with their own
+    command in the wizard's provider step, exactly as before
+    this module existed.
+  * Discovery reads the machine; it writes nothing. The wizard
+    saves only what the user confirms, through the existing
+    save path.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import threading
+
+from . import hardening
+
+PROBE_TIMEOUT = 5
+
+# Retained-output ceiling for one --version probe (P3-07):
+# a version string is one line; anything past this is a
+# spewing binary, and the parent must not buffer it.
+_PROBE_OUTPUT_CAP = 64 * 1024
+
+# The instruction the shipped example wrapper passes to Claude
+# Code (examples/agent-seat-claude.sh, verbatim): the seat's
+# brief arrives on stdin — command_agent pipes the prompt there
+# AND names the same content's file in $CODEREVIEW_PROMPT, so
+# the wrapper's `< "$CODEREVIEW_PROMPT"` redirect and this
+# direct command receive identical input.
+_CLAUDE_INSTRUCTION = (
+    "You are a reviewer seat in a multi-model code review. "
+    "The document on stdin is your complete brief: a diff plus "
+    "instructions. Follow the instructions exactly and output "
+    "ONLY the JSON verdict object they ask for — no prose, "
+    "no markdown fences.")
+
+# name        seat name (the agent:<name>:... the spec carries)
+# display     human name for the offer lines
+# binaries    candidate executable names, tried in order
+# family      the CLI vendor's family tag — used ONLY by the
+#             wizard's family-diversity warning. The gate tags
+#             every agent seat family 'agent' (cli._default_
+#             seat_meta) unless the operator overrides with
+#             --seat-meta; discovery does not change that.
+# command     the verified non-interactive invocation, or None
+#             when this repository carries none (see module
+#             docstring). Seat contract: the prompt arrives on
+#             stdin and in $CODEREVIEW_PROMPT; stdout is the
+#             response (providers.command_agent).
+KNOWN_CLIS = (
+    {
+        "name": "claude",
+        "display": "Claude Code",
+        "binaries": ("claude",),
+        "family": "anthropic",
+        "command": 'claude -p --tools "" "' + _CLAUDE_INSTRUCTION
+                   + '"',
+    },
+    {
+        # U6 provenance: VERIFIED-LIVE for the invocation form
+        # (`codex exec --help` on codex-cli 0.164.0-alpha.9,
+        # plus one logged-out exec probe on the build VM that
+        # consumed the piped prompt and attempted the call,
+        # exiting 1 on 401s) and VERIFIED-DOCS for the contract
+        # (developers.openai.com/codex/noninteractive: `-` /
+        # piped stdin is the full prompt; only the final agent
+        # message goes to stdout, progress to stderr; sandbox
+        # defaults to read-only). `-s read-only` is stated
+        # explicitly because a reviewer seat must never write;
+        # `--skip-git-repo-check` because the seat's cwd is a
+        # scratch dir, not a repo. An end-to-end SUCCESSFUL run
+        # was not live-verified (no Codex login on the build
+        # VM) — the form and failure behaviour are what U6
+        # verified.
+        "name": "codex",
+        "display": "Codex",
+        "binaries": ("codex",),
+        "family": "openai",
+        "command": "codex exec -s read-only "
+                   "--skip-git-repo-check -",
+    },
+    {
+        # U6 provenance: VERIFIED-DOCS only (Gemini CLI is not
+        # installed on the build VM; nothing here is live-
+        # verified). Official CLI reference (geminicli.com/
+        # docs/cli/cli-reference): `-p/--prompt` "Appended to
+        # stdin input if provided. Forces non-interactive
+        # mode" — so the brief rides stdin exactly as with
+        # Claude, and the -p text is the same seat instruction.
+        # Headless reference documents exit codes 0 (success),
+        # 1 (general/API failure), 42 (input error), 53 (turn
+        # limit exceeded).
+        "name": "gemini",
+        "display": "Gemini CLI",
+        "binaries": ("gemini",),
+        "family": "google",
+        "command": 'gemini -p "' + _CLAUDE_INSTRUCTION + '"',
+    },
+)
+
+_BY_NAME = {entry["name"]: entry for entry in KNOWN_CLIS}
+
+
+def seat_spec(entry):
+    """The ordinary agent spec a confirmed discovery pick saves
+    (agent:<name>:<command>). Only callable for entries with a
+    verified command — the wizard never offers the others."""
+    if not entry.get("command"):
+        raise ValueError(
+            f"no verified seat command for {entry['name']!r}")
+    return f"agent:{entry['name']}:{entry['command']}"
+
+
+def family_for_seat_name(name):
+    """Vendor family for an agent seat name, from the discovery
+    table (agent:claude:* -> 'anthropic'); None for names the
+    table does not know (a wrapper script, an echo stub, ...).
+    Used by the wizard's family warning only — never by the
+    gate: providers' agent-seat family derivation (P6-06)
+    reads the seat command's PROGRAM against the table, not
+    the seat name, because a name must not confer a family
+    the seat does not run (review-v11)."""
+    entry = _BY_NAME.get(str(name).strip().lower())
+    return entry["family"] if entry else None
+
+
+def default_probe(path):
+    """Cheap liveness probe: `<binary> --version`, bounded by
+    PROBE_TIMEOUT, output capped. Returns (ok, detail) and never
+    raises — a binary that cannot even answer --version is a
+    probe failure with the reason attached, not an exception in
+    the wizard."""
+    # P3-04 backstop: the probed binary is a direct child of
+    # this process (same /proc/$PPID/environ exposure as the
+    # evidence sandbox's env-only mode).
+    hardening.make_non_dumpable()
+    # P3-07: the probe NEVER raises — not OSError, not a
+    # timeout, not MemoryError from a spewing binary's
+    # unbounded output (the old subprocess.run capture had
+    # no cap, so the "never raises" contract was false).
+    try:
+        return _probe_version(path)
+    except Exception as exc:  # noqa: BLE001 — never raises
+        return False, f"could not run: {exc}"
+
+
+def _drain_capped(stream, sink, proc):
+    """Read `stream` into `sink` (a bytearray), retaining at
+    most _PROBE_OUTPUT_CAP bytes; once the cap is exceeded,
+    kill the child and keep draining (discarding) so the
+    pipe never blocks it on the way down."""
+    try:
+        while True:
+            chunk = stream.read(8192)
+            if not chunk:
+                return
+            room = _PROBE_OUTPUT_CAP - len(sink)
+            if room >= len(chunk):
+                sink.extend(chunk)
+                continue
+            if room > 0:
+                sink.extend(chunk[:room])
+            try:
+                proc.kill()
+            except OSError:
+                pass
+    except (OSError, ValueError):
+        return
+
+
+def _probe_version(path):
+    proc = subprocess.Popen(
+        [path, "--version"], stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE)
+    out_sink, err_sink = bytearray(), bytearray()
+    readers = [
+        threading.Thread(target=_drain_capped,
+                         args=(proc.stdout, out_sink, proc),
+                         daemon=True),
+        threading.Thread(target=_drain_capped,
+                         args=(proc.stderr, err_sink, proc),
+                         daemon=True),
+    ]
+    for reader in readers:
+        reader.start()
+    return _supervise_probe_run(proc, readers, out_sink,
+                                 err_sink)
+
+
+def _supervise_probe_run(proc, readers, out_sink, err_sink):
+    """The probe's supervised wait — the pairing the
+    subprocess-timeout guard accepts by name, as it does the
+    evidence sandbox's: every wait is deadline-bounded
+    (wait(timeout=...), bounded joins) and expiry kills the
+    child. It is a stronger bound than communicate(timeout=
+    ...), not a weaker one: communicate buffers the child's
+    output without bound, this wait drains it under the
+    P3-07 cap."""
+    try:
+        proc.wait(timeout=PROBE_TIMEOUT)
+    except subprocess.TimeoutExpired:
+        try:
+            proc.kill()
+        except OSError:
+            pass
+        proc.wait()
+        return False, (f"could not run: timed out after "
+                       f"{PROBE_TIMEOUT} seconds")
+    for reader in readers:
+        reader.join(timeout=2)
+    out = out_sink.decode("utf-8", "replace").strip() \
+        or err_sink.decode("utf-8", "replace").strip()
+    detail = out.splitlines()[0][:120] if out else ""
+    if proc.returncode != 0:
+        return False, (f"exited {proc.returncode}"
+                       + (f": {detail}" if detail else ""))
+    return True, detail
+
+
+def discover_clis(path_value=None, which_fn=None, probe_fn=None):
+    """Scan PATH for the known agent CLIs.
+
+    path_value: the PATH string to search (the wizard passes its
+    environ's PATH); None means the process's own PATH. which_fn
+    and probe_fn are injectable so tests fake the machine — no
+    test may depend on the real PATH contents. Returns one dict
+    per FOUND cli, in table order: the table entry plus 'path'
+    (the resolved executable), 'probe_ok', and 'probe_detail'."""
+    if which_fn is None:
+        def which_fn(binary):
+            return shutil.which(binary, path=path_value)
+    if probe_fn is None:
+        probe_fn = default_probe
+    found = []
+    for entry in KNOWN_CLIS:
+        resolved = None
+        for binary in entry["binaries"]:
+            resolved = which_fn(binary)
+            if resolved:
+                break
+        if not resolved:
+            continue
+        try:
+            ok, detail = probe_fn(resolved)
+        except Exception as exc:  # noqa: BLE001 — discovery
+            # never raises (P3-07): a probe that blows up is
+            # a failed probe with the reason attached.
+            ok, detail = False, f"could not run: {exc}"
+        found.append({**entry, "path": resolved,
+                      "probe_ok": bool(ok),
+                      "probe_detail": detail})
+    return found