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

stacktrace_cli/__init__.py

@@ -1,3 +1,3 @@
 """Placeholder CLI package for Stacktrace.ai."""
 
-__version__ = "0.0.1"
+__version__ = "0.1.0"

stacktrace_cli/__main__.py

@@ -1,24 +1,16 @@
-"""Entry point for the ``stacktrace`` command."""
+"""Entry point for the ``stacktrace`` command.
 
-from __future__ import annotations
-
-import argparse
-
-from . import __version__
-
-HOMEPAGE = "https://stacktrace.ai"
+`[project.scripts]` still names `stacktrace_cli.__main__:main`, which now
+resolves to the Click group in `stacktrace_cli.cli`, so both the console script
+and `python -m stacktrace_cli` reach the same object and the published
+entry-point string does not change between releases.
+"""
 
+from __future__ import annotations
 
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(
-        prog="stacktrace",
-        description=f"Stacktrace.ai CLI (pre-alpha). See {HOMEPAGE}",
-    )
-    parser.add_argument("--version", action="version", version=f"stacktrace {__version__}")
-    parser.parse_args(argv)
-    print(f"stacktrace {__version__} — pre-alpha placeholder. See {HOMEPAGE}")
-    return 0
+from .cli import main
 
+__all__ = ["main"]
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    main()

stacktrace_cli/cli.py

@@ -0,0 +1,314 @@
+"""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 .correlate.orchestrate import acquire_correlated_view
+from .correlate.project_map import parse_mapping
+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, run_detector
+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 _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, 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: str,
+    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.
+    """
+    view = collect_sessions(list(agent_kinds) or None, _parse_since(since), root=root)
+    try:
+        acquired = acquire_correlated_view(
+            view, bom_paths=bom_paths, project_map=tuple(parse_mapping(m) for m in project_map)
+        )
+    except ValueError as error:
+        raise click.ClickException(str(error)) from error
+
+    result = run_detector(
+        acquired.view,
+        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,
+    )
+    output = (
+        render_detections_json(result)
+        if output_format == "json"
+        else render_detections_text(result, detail)
+    )
+    click.echo(output, nl=not output.endswith("\n"))
+
+
+# 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)

stacktrace_cli/correlate/__init__.py

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