stacktrace-cli 0.0.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

stacktrace_cli/cli.py

@@ -0,0 +1,470 @@
+"""The ``stacktrace`` command group.
+
+Two kinds of command live here (ADR-0021, `docs/adrs/0021-two-command-kinds.md`):
+
+- **Pass-through** — OpenACA's own Click command object, mounted under this
+  group. It declares no parameter of its own, ever, and nothing here parses its
+  arguments; Click dispatches them to OpenACA's parser. The object registered
+  under ``stacktrace scan`` *is* ``openaca scan``.
+- **Native** — a command this package implements, registered the ordinary way.
+  If it needs OpenACA it calls ``openaca.core`` (ADR-0020).
+
+`openaca.cli` is a supported import path published for exactly this use
+(ADR-0020, `docs/adrs/0020-openaca-consumption-boundary.md`).
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime, timedelta
+from importlib.metadata import version
+from pathlib import Path
+from typing import Final
+
+import click
+from openaca.cli import main as openaca_cli
+
+from . import __version__
+from .analysis import analyse, parse_since
+from .detector.cache import VerdictCache, default_directory
+from .detector.render import render_json as render_detections_json
+from .detector.render import render_text as render_detections_text
+from .detector.run import DEFAULT_BUDGET, DEFAULT_SAMPLE_BUDGET
+from .monitor.server import serve
+from .remote.cli import main as remote_cmd
+from .sessions.access import collect_sessions
+from .sessions.render import render_json, render_text
+
+PASSTHROUGH: Final = ("scan", "bom", "policy")
+
+HOMEPAGE = "https://stacktrace.ai"
+
+_SINCE_PATTERN = re.compile(r"^(\d+)d$")
+
+
+def _parse_since(value: str) -> datetime:
+    """`14d` -> an aware UTC cut-off."""
+    match = _SINCE_PATTERN.match(value.strip())
+    if not match:
+        raise click.BadParameter(f"expected a day count like '14d', got {value!r}")
+    return datetime.now(UTC) - timedelta(days=int(match.group(1)))
+
+
+def _window_start(ctx: click.Context, param: click.Parameter, value: str) -> datetime:
+    """`detect`'s window, resolved by this command's own parser.
+
+    The window otherwise reaches `analyse` as a string and is parsed there, by
+    the parser that also answers the upload path — whose value comes from a
+    config file rather than a shell, so it is more forgiving about the spelling
+    and stricter about the count. Applying it here as well would quietly change
+    what this command accepts, so the cutoff travels already resolved.
+    """
+    return _parse_since(value)
+
+
+def _day_count(ctx: click.Context, param: click.Parameter, value: str) -> str:
+    """Refuse here every `--since` the pipeline would refuse later.
+
+    The window reaches `analyse` as a string and is parsed there, once for every
+    caller. That parser also answers the upload path, whose value comes from a
+    config file rather than a shell, so it is the more forgiving of the two —
+    and the narrower spelling stays here, where a mistyped option is a usage
+    error with the usage line attached rather than a command that started,
+    read nothing and failed.
+    """
+    _parse_since(value)
+    try:
+        parse_since(value)
+    except ValueError as error:
+        raise click.BadParameter(str(error)) from error
+    return value
+
+
+def _show_version(ctx: click.Context, param: click.Parameter, value: bool) -> None:
+    # Click invokes an eager option's callback on every invocation of the
+    # group, with `value=False` when the flag was absent, so an unguarded
+    # callback would print the version and exit before any subcommand ran.
+    # click's own `version_option` callback opens with the same two guards.
+    if not value or ctx.resilient_parsing:
+        return
+    click.echo(f"stacktrace {__version__} (openaca {version('openaca')})")
+    ctx.exit()
+
+
+class SectionedGroup(click.Group):
+    """A group whose command listing is split into delegated and native sections.
+
+    Click has no notion of command sections and the distinction matters here: a
+    delegated command's own ``--help`` describes OpenACA and its options are
+    OpenACA's, which a flat alphabetical listing tells nobody. The partition is
+    derived from `PASSTHROUGH`, so registering a native command puts it in the
+    right section with no edit to this class.
+    """
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        commands: list[tuple[str, click.Command]] = []
+        for name in self.list_commands(ctx):
+            cmd = self.get_command(ctx, name)
+            if cmd is None or cmd.hidden:
+                continue
+            commands.append((name, cmd))
+        if not commands:
+            return
+
+        limit = formatter.width - 6 - max(len(name) for name, _ in commands)
+        delegated = [
+            (name, cmd.get_short_help_str(limit)) for name, cmd in commands if name in PASSTHROUGH
+        ]
+        native = [
+            (name, cmd.get_short_help_str(limit))
+            for name, cmd in commands
+            if name not in PASSTHROUGH
+        ]
+
+        for heading, rows in (("Analysis (OpenACA)", delegated), ("Stacktrace", native)):
+            if not rows:
+                continue
+            with formatter.section(heading):
+                formatter.write_dl(rows)
+
+
+@click.group(cls=SectionedGroup)
+@click.option(
+    "--version",
+    is_flag=True,
+    expose_value=False,
+    is_eager=True,
+    callback=_show_version,
+    help="Show the stacktrace and OpenACA versions and exit.",
+)
+def main() -> None:
+    """Stacktrace: agent composition analysis, detection and upload."""
+
+
+@click.command()
+@click.option(
+    "--agent-kind",
+    "agent_kinds",
+    multiple=True,
+    help="Only this agent kind. Repeatable. Default: every kind.",
+)
+@click.option("--since", default="14d", show_default=True, help="Window, as a day count.")
+@click.option(
+    "--include-content",
+    is_flag=True,
+    default=False,
+    help="Include prompts, tool arguments and results. Off by default: a rendered "
+    "document leaves the process, and the Correlator reads the model directly.",
+)
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    show_default=True,
+)
+@click.option(
+    "--detail",
+    is_flag=True,
+    default=False,
+    help="Show the session trail. Default: the summary alone.",
+)
+@click.option(
+    "--root",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Read agent transcripts from here instead of the default location.",
+)
+def sessions(
+    agent_kinds: tuple[str, ...],
+    since: str,
+    output_format: str,
+    include_content: bool,
+    detail: bool,
+    root: Path | None,
+) -> None:
+    """Print what the agents on this machine actually did."""
+    view = collect_sessions(list(agent_kinds) or None, _parse_since(since), root=root)
+    output = (
+        render_json(view, include_content)
+        if output_format == "json"
+        else render_text(view, include_content, detail)
+    )
+    click.echo(output, nl=not output.endswith("\n"))
+
+
+@click.command()
+@click.option("--agent-kind", "agent_kinds", multiple=True, help="Limit to these agent kinds.")
+@click.option(
+    "--since",
+    default="7d",
+    show_default=True,
+    callback=_window_start,
+    help="How far back to read.",
+)
+@click.option(
+    "--bom",
+    "bom_paths",
+    multiple=True,
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="Use this Agent BOM instead of scanning for its kind.",
+)
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    show_default=True,
+)
+@click.option(
+    "--detail",
+    is_flag=True,
+    default=False,
+    help="Show every detection and all of its evidence. Default: the summary alone.",
+)
+@click.option(
+    "--escalate/--no-escalate",
+    default=True,
+    show_default=True,
+    help="Send flagged sessions to the agent's own CLI for semantic analysis. On "
+    "by default, capped by --budget. It is the only stage that sends anything "
+    "session-derived off this machine, and it spends the developer's own "
+    "provider quota, so --no-escalate turns it off and the cap keeps a noisy "
+    "day bounded. It does not make the run offline: correlation runs first "
+    "either way and matches advisories by sending the package coordinates of "
+    "the components a session invoked to osv.dev.",
+)
+@click.option(
+    "--budget",
+    type=click.IntRange(min=1),
+    default=DEFAULT_BUDGET,
+    show_default=True,
+    help="How many sessions one run may send for inference.",
+)
+@click.option(
+    "--sample-budget",
+    type=click.IntRange(min=0),
+    default=DEFAULT_SAMPLE_BUDGET,
+    show_default=True,
+    help="Quiet sessions to analyse per run with no evidence behind them. Off "
+    "by default: it is the only route that spends inference with no evidence, "
+    "so it is asked for rather than assumed. Shares the --budget cap.",
+)
+@click.option(
+    "--cache/--no-cache",
+    default=True,
+    show_default=True,
+    help="Reuse a stored verdict for a session that has not changed. Holds rule "
+    "ids, grades and span identifiers only — never conversation (ADR-0011).",
+)
+@click.option(
+    "--project-map",
+    "project_map",
+    multiple=True,
+    metavar="OLD=NEW",
+    help="Where a project a session ran in lives now, for a directory that has "
+    "moved since. Applies to OLD and everything under it, only where OLD no "
+    "longer exists; repeatable, most specific wins. Every result is marked with "
+    "where it was mapped from.",
+)
+@click.option(
+    "--root",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Read agent transcripts from here instead of the default location.",
+)
+def detect(
+    agent_kinds: tuple[str, ...],
+    since: datetime,
+    bom_paths: tuple[Path, ...],
+    output_format: str,
+    detail: bool,
+    escalate: bool,
+    budget: int,
+    sample_budget: int,
+    cache: bool,
+    project_map: tuple[str, ...],
+    root: Path | None,
+) -> None:
+    """Find security and reliability findings in what agents did.
+
+    Four kinds of finding, under two families: a credential reaching an
+    outbound call and an injected instruction followed are security; a
+    vulnerable component actually reached is security with a vulnerability
+    behind it; a stalled loop and a hung call are reliability. The two
+    families carry their own severity ladders, because a stalled loop and a
+    leaked credential cannot share one (ADR-0010).
+
+    Two stages need no model or credential. The third sends flagged sessions to
+    the agent's own CLI: on by default and capped by --budget, with
+    --no-escalate to turn it off.
+
+    That third stage is the one that sends session content off this machine:
+    the agent's own CLI hands the prompts, arguments and results a rule needs
+    to the provider it is already authenticated against (ADR-0004 -- provider
+    affinity, so a transcript goes back to the vendor that produced it, and
+    there is no fallback to any other). --no-escalate leaves the two stages
+    that send nothing.
+
+    One network call happens before any of them regardless of --no-escalate:
+    correlation matches advisories by sending the package coordinates of the
+    components a session invoked to osv.dev. Coordinates only -- never a
+    prompt, an argument or a result.
+    """
+    try:
+        # One call, because the order it runs in is `analysis.py`'s to know:
+        # `monitor` and `sync detect` read the same pipeline and must not be
+        # able to disagree with this command about what it found.
+        analysis = analyse(
+            agent_kinds=agent_kinds,
+            since=since,
+            bom_paths=bom_paths,
+            project_map=project_map,
+            root=root,
+            escalate=escalate,
+            budget=budget,
+            sample_budget=sample_budget,
+            # Only ever consulted when stage 3 runs: there is nothing to reuse
+            # otherwise, and opening a directory to discover that is waste.
+            cache=VerdictCache(default_directory()) if cache and escalate else None,
+        )
+    except ValueError as error:
+        raise click.ClickException(str(error)) from error
+    result = analysis.run
+    output = (
+        render_detections_json(result)
+        if output_format == "json"
+        else render_detections_text(result, detail)
+    )
+    click.echo(output, nl=not output.endswith("\n"))
+
+
+@click.command()
+@click.option("--port", type=int, default=0, help="Serve on this port instead of an unused one.")
+@click.option(
+    "--host",
+    default="127.0.0.1",
+    show_default=True,
+    help="Loopback only. This page renders working directories and matched "
+    "values, so a non-loopback address is refused rather than warned about.",
+)
+@click.option(
+    "--interval",
+    # Above zero, not merely non-negative: the wait between passes is what
+    # makes this page free to leave open, and `Event.wait(0)` returns at once —
+    # a zero or negative interval walks the transcript tree in a hot loop.
+    type=click.FloatRange(min=0, min_open=True),
+    default=4.0,
+    show_default=True,
+    help="Seconds between checks for new agent activity. A pass is skipped "
+    "entirely when nothing on disk has changed.",
+)
+@click.option(
+    "--escalate/--no-escalate",
+    default=False,
+    show_default=True,
+    help="Let the page send one session to the agent's own CLI for semantic "
+    "analysis. Off by default: stage 3 spends your provider quota, and a page "
+    "left open is the wrong place for that to be implicit. Capped by --budget.",
+)
+@click.option(
+    "--budget",
+    type=click.IntRange(min=1),
+    default=DEFAULT_BUDGET,
+    show_default=True,
+    help="Escalations this monitor may spend in total, if --escalate is on.",
+)
+@click.option(
+    "--no-open", is_flag=True, default=False, help="Print the URL, do not open a browser."
+)
+@click.option("--agent-kind", "agent_kinds", multiple=True, help="Limit to these agent kinds.")
+@click.option(
+    "--since",
+    default="3d",
+    show_default=True,
+    callback=_day_count,
+    help="How far back to read. Shorter than `detect`'s week deliberately: the "
+    "whole window is collected and correlated before the page can render "
+    "anything — measured at ~2.5s for a day and ~6s for a week of a busy "
+    "machine — and a live view is about what is happening rather than what "
+    "happened. Widen it when you want the history.",
+)
+@click.option(
+    "--bom",
+    "bom_paths",
+    multiple=True,
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="Use this Agent BOM instead of scanning for its kind.",
+)
+@click.option(
+    "--project-map",
+    "project_map",
+    multiple=True,
+    metavar="OLD=NEW",
+    help="Where a project a session ran in lives now, for a directory that has moved.",
+)
+@click.option(
+    "--root",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Read agent transcripts from here instead of the default location.",
+)
+def monitor(
+    port: int,
+    host: str,
+    interval: float,
+    escalate: bool,
+    budget: int,
+    no_open: bool,
+    agent_kinds: tuple[str, ...],
+    since: str,
+    bom_paths: tuple[Path, ...],
+    project_map: tuple[str, ...],
+    root: Path | None,
+) -> None:
+    """Watch this machine's agents in a browser, live.
+
+    Serves a local page — a summary, what your agents are doing, and what the
+    detector makes of it — refreshing as they work. Everything on it is
+    computed in this process by the same code `stacktrace detect` runs; the
+    page renders and never judges.
+
+    Loopback only, and free to leave open: a pass is skipped when nothing has
+    changed, advisory lookups are asked once per component, and the two stages
+    that need no model are the only ones that run. --escalate adds a button
+    that spends your provider quota, off unless asked for.
+    """
+    try:
+        code = serve(
+            host=host,
+            port=port,
+            interval=interval,
+            escalate=escalate,
+            budget=budget,
+            open_browser=not no_open,
+            echo=click.echo,
+            agent_kinds=agent_kinds,
+            since=since,
+            bom_paths=bom_paths,
+            project_map=project_map,
+            root=root,
+        )
+    except (OSError, ValueError) as error:
+        raise click.ClickException(str(error)) from error
+    if code:
+        raise click.exceptions.Exit(code)
+
+
+# Named, never discovered: an upstream release must not be able to enlarge this
+# CLI. A missing name is a `KeyError` at import time, which names the command
+# and the line, and lands at upgrade time.
+for _name in PASSTHROUGH:
+    main.add_command(openaca_cli.commands[_name], _name)
+
+# Native, registered the ordinary way and after the loop, so a name collision
+# resolves in the native command's favour. The one recorded overlap is
+# openaca's own `remote`, which is never mounted here.
+main.add_command(remote_cmd, "remote")
+main.add_command(sessions)
+main.add_command(detect)
+main.add_command(monitor)

stacktrace_cli/correlate/__init__.py

@@ -0,0 +1 @@
+"""Correlation: the join between what an agent did and what it is built from."""