stacktrace-cli 0.4.1__py3-none-any.whl → 0.5.1__py3-none-any.whl

stacktrace_cli/__init__.py

@@ -1,3 +1,10 @@
 """The `stacktrace` command-line interface — detection and response for AI agents."""
 
-__version__ = "0.4.1"
+import logging as _logging
+
+__version__ = "0.5.1"
+
+# Only the daemon attaches a handler (ADR-0048). Without this one, a WARNING
+# logged in any other process would reach Python's last-resort handler and
+# print onto the user's terminal.
+_logging.getLogger(__name__).addHandler(_logging.NullHandler())

stacktrace_cli/daemon/activity_log.py

@@ -0,0 +1,94 @@
+"""The daemon's activity log: leveled, private and capped (ADR-0048).
+
+Every module logs to its own `logging.getLogger(__name__)`. Only the daemon
+attaches a file handler, to the `stacktrace_cli` package logger; everywhere
+else the package's `NullHandler` keeps those lines off the terminal.
+
+A line names kinds, counts, class names and event ids. It never carries a
+finding's title or body, an exception message, or anything from a transcript,
+and a peer-supplied session id is written with `%r`.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import time
+from collections.abc import Mapping
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+from stacktrace_cli.private_state import ensure_private_directory
+
+LEVEL_VARIABLE = "STACKTRACE_DAEMON_LOG_LEVEL"
+MAX_BYTES = 5 * 1024 * 1024
+BACKUP_COUNT = 1
+PACKAGE = "stacktrace_cli"
+
+
+def private_opener(path: str, flags: int) -> int:
+    return os.open(path, flags, 0o600)
+
+
+class _PrivateRotatingFileHandler(RotatingFileHandler):
+    def __init__(self, path: Path, *, max_bytes: int, own_std_streams: bool) -> None:
+        self._own_std_streams = own_std_streams
+        super().__init__(path, maxBytes=max_bytes, backupCount=BACKUP_COUNT, encoding="utf-8")
+
+    def _open(self):  # type: ignore[override]
+        stream = open(  # noqa: SIM115 - the handler owns and closes it
+            self.baseFilename,
+            self.mode,
+            encoding=self.encoding,
+            errors=self.errors,
+            opener=private_opener,
+        )
+        # The opener's mode applies only to a file it creates.
+        os.chmod(self.baseFilename, 0o600)
+        return stream
+
+    def doRollover(self) -> None:
+        super().doRollover()
+        # `ensure_daemon` pointed this process's stdout and stderr at the file
+        # just renamed away. Follow it, or a crash traceback lands in the
+        # backup and is deleted with it at the next rollover.
+        if self._own_std_streams and self.stream is not None:
+            sys.stdout.flush()
+            sys.stderr.flush()
+            os.dup2(self.stream.fileno(), 1)
+            os.dup2(self.stream.fileno(), 2)
+
+
+def level_from(environment: Mapping[str, str]) -> int:
+    name = environment.get(LEVEL_VARIABLE, "").strip().upper()
+    return logging.getLevelNamesMapping().get(name, logging.DEBUG)
+
+
+def configure(
+    path: Path,
+    *,
+    environ: Mapping[str, str] | None = None,
+    own_std_streams: bool = False,
+    max_bytes: int = MAX_BYTES,
+) -> logging.Handler:
+    ensure_private_directory(path.parent)
+    handler = _PrivateRotatingFileHandler(
+        path, max_bytes=max_bytes, own_std_streams=own_std_streams
+    )
+    formatter = logging.Formatter(
+        "%(asctime)s %(levelname)s %(name)s: %(message)s", datefmt="%Y-%m-%dT%H:%M:%SZ"
+    )
+    formatter.converter = time.gmtime
+    handler.setFormatter(formatter)
+    logger = logging.getLogger(PACKAGE)
+    logger.setLevel(level_from(os.environ if environ is None else environ))
+    logger.addHandler(handler)
+    return handler
+
+
+def release(handler: logging.Handler) -> None:
+    logger = logging.getLogger(PACKAGE)
+    logger.removeHandler(handler)
+    logger.setLevel(logging.NOTSET)
+    handler.close()

stacktrace_cli/daemon/bom.py

@@ -0,0 +1,56 @@
+"""The BOM job: `sync_endpoint()` on a timer.
+
+A full snapshot of what is installed, not an append stream — so there is nothing
+to cursor, and the spool already handles offline retry. It reads no part of the
+finding queue, and it must upload on a machine with a broken detector, an empty
+database, or no session ever scanned.
+
+**It re-collects rather than uploading the daemon's warm `CompositionSnapshots`.**
+`docs/specs/remote-sync.md`'s bar requires the payload be byte-identical to
+OpenACA's for the same endpoint state, and the snapshot is built for a different
+scope — `("claude-code", None)`, user scope with no project layering — by a
+different path than `_collect()`. Reusing it would be a payload change wearing
+the costume of a performance win.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from stacktrace_cli.remote.sync import SyncError, sync_endpoint
+
+
+@dataclass(frozen=True)
+class BomJobReport:
+    """What one run did, for a caller that has to tell the two zeros apart.
+
+    A machine with nothing installed and a machine that could not reach the
+    Cloud both upload nothing. The scheduled job does not care — it is due
+    again either way — but `stacktrace daemon sync-bom` is asked by a person,
+    and answering "0" to both is answering neither.
+    """
+
+    uploaded: int
+    failure: str | None = None
+
+
+def run_bom_job(*, report: Callable[[str], None]) -> BomJobReport:
+    """One `sync endpoint`, with its progress sent somewhere a daemon can write.
+
+    `drain_the_spool` and `allow_offline_cache` semantics are exactly as the CLI
+    has them: a machine that is offline caches its collection and the next run
+    replays it. `SyncError` is an outcome here rather than an exit code — there
+    is no process to exit — so it is reported and the job is simply due again.
+    """
+    try:
+        results = sync_endpoint(
+            project=None,
+            quiet=True,
+            allow_offline_cache=True,
+            reporter=report,
+        )
+    except SyncError as error:
+        report(f"bom sync: {error}")
+        return BomJobReport(uploaded=0, failure=str(error))
+    return BomJobReport(uploaded=len(results))

stacktrace_cli/daemon/cli.py

@@ -4,11 +4,15 @@ from __future__ import annotations
 
 import json
 import os
+import sqlite3
 import sys
+from datetime import UTC, datetime
 
 import click
 
+from .config import DaemonConfig
 from .paths import RuntimePaths
+from .presentation import render_finding
 from .store import FindingStore, SessionKey
 
 
@@ -18,19 +22,220 @@ def daemon() -> None:
 
 
 @daemon.command("run", hidden=True)
-def run_command() -> None:
+# No `envvar=` on any of these. Click resolves an environment variable *into*
+# the parameter, so a value that came from the environment would arrive here
+# indistinguishable from one typed on the command line — and `daemon status`
+# would report every forked daemon's settings as "(flag)", which is precisely
+# the drift the source label exists to expose. `DaemonConfig.resolve` reads the
+# environment itself, and knows which answer it gave.
+@click.option(
+    "--scan-interval",
+    default=None,
+    help="How often to enumerate and analyse changed sessions. 0 disables scanning."
+    " Defaults to STACKTRACE_SCAN_INTERVAL, then 5s.",
+)
+@click.option(
+    "--scan-since",
+    default=None,
+    help="Bootstrap horizon for the first scan only; later scans use the watermark."
+    " Defaults to STACKTRACE_SCAN_SINCE, then 3d.",
+)
+@click.option(
+    "--agent-kind",
+    "agent_kinds",
+    multiple=True,
+    help="Agent kind to observe. Repeatable. Defaults to STACKTRACE_AGENT_KIND, then claude-code.",
+)
+@click.option(
+    "--fleet-interval",
+    default=None,
+    help="How often to drain the finding queue to Fleet as a fallback poll. 0 disables only"
+    " that fallback: a finding still uploads immediately when the scan commits it."
+    " Defaults to STACKTRACE_FLEET_INTERVAL, then 5m.",
+)
+@click.option(
+    "--bom-interval",
+    default=None,
+    help="How often to upload endpoint composition. 0 disables it."
+    " Defaults to STACKTRACE_BOM_INTERVAL, then 6h.",
+)
+def run_command(
+    scan_interval: str | None,
+    scan_since: str | None,
+    agent_kinds: tuple[str, ...],
+    fleet_interval: str | None,
+    bom_interval: str | None,
+) -> None:
     _, _, run_daemon = _runtime()
-    run_daemon(RuntimePaths.from_environment())
+    paths = RuntimePaths.from_environment()
+    try:
+        config = DaemonConfig.resolve(
+            scan_interval=scan_interval,
+            scan_since=scan_since,
+            agent_kinds=agent_kinds,
+            fleet_interval=fleet_interval,
+            bom_interval=bom_interval,
+        )
+        _reject_unobservable_kinds(config)
+    except ValueError as error:
+        raise click.ClickException(str(error)) from error
+    # The real daemon process: its stdout and stderr are the log file
+    # (`ensure_daemon`), so they follow it across a rollover (ADR-0048).
+    run_daemon(paths, config, own_std_streams=True)
+
+
+def _reject_unobservable_kinds(config: DaemonConfig) -> None:
+    """A kind with no observer would scan nothing, silently.
+
+    Fails at startup rather than at the first tick: `cursor` and `codex` have
+    composition coverage but no runtime detection yet (`daemon-scanning.md`
+    § *Deferred*), and a daemon quietly finding nothing for one of them is the
+    failure this refusal exists to make loud.
+    """
+    from .runtime import OBSERVERS
+
+    unknown = [kind for kind in config.kinds if kind not in OBSERVERS]
+    if unknown:
+        known = ", ".join(sorted(OBSERVERS))
+        raise ValueError(
+            f"no session observer for {', '.join(unknown)}; this build observes {known}"
+        )
 
 
 @daemon.command()
 def status() -> None:
-    """Show whether the local Stacktrace daemon is running."""
+    """Report whether this endpoint is working, without reading a log.
+
+    Every row answers a question someone asks when a machine looks quiet: a
+    watermark hours old means the scanner has stopped; a queue that grows with
+    a reader attached means the reader is not draining; a database that only
+    grows means retention is not pruning; and a configuration without its source
+    makes fleet-wide drift undebuggable (`docs/specs/daemon-scanning.md`).
+    """
     daemon_is_running, _, _ = _runtime()
+    from .runtime import last_error, read_run_state
+
     paths = RuntimePaths.from_environment()
-    if not daemon_is_running(paths.socket):
-        raise click.ClickException("Stacktrace daemon is not running")
-    click.echo("Stacktrace daemon is running.")
+    running = daemon_is_running(paths.socket)
+    run_state = read_run_state(paths)
+
+    click.echo(f"running: {'yes' if running else 'no'}")
+    if isinstance(run_state, dict):
+        click.echo(f"pid: {run_state.get('pid')}")
+        click.echo(f"version: {run_state.get('version')}")
+        click.echo(f"started: {run_state.get('started_at')}")
+
+    try:
+        # One `_store()` call apiece, all against the same file: if the first
+        # (`_watermark_line`'s) open fails, every other one would fail
+        # identically, so one `try` around all five is enough, and none of
+        # them can print a partial line before that first failure.
+        click.echo(f"watermark: {_watermark_line(paths)}")
+        click.echo(f"queue depth: {_queue_line(paths)}")
+        click.echo(f"cursors: {_cursor_line(paths)}")
+        click.echo(f"parked: {_parked_line(paths)}")
+        click.echo(f"database: {_database_line(paths)}")
+    except (sqlite3.DatabaseError, ValueError) as exc:
+        # A corrupt file or a schema newer than this build reads raises here
+        # (`_check_version`'s own refusal) -- precisely the moment the daemon
+        # may have failed to start, so this diagnostic surface must report it
+        # rather than crash before reaching the log and configuration lines
+        # below, which need no store at all.
+        click.echo(f"database: unreadable — {exc}")
+    click.echo(f"last error: {last_error(paths.log) or 'none reported'}")
+
+    try:
+        config = _effective_config(run_state)
+    except ValueError as exc:
+        # No readable run-state means `resolve()`'s own environment fallback
+        # ran, and its validation is exactly what could be *why* the daemon
+        # never started -- the one diagnostic surface for that case must not
+        # itself crash on it. `from_document` above already never raises for
+        # this same reason; this matches it rather than adding a second rule.
+        click.echo(f"config: unresolvable — {exc}")
+    else:
+        click.echo("config:")
+        for name, entry in config.as_document().items():
+            click.echo(f"  {name}: {entry['value']} ({entry['source']})")
+
+
+def _effective_config(run_state: dict[str, object] | None) -> DaemonConfig:
+    """What the daemon resolved, when it is there to say so.
+
+    Falling back to this process's own environment is a worse answer and is
+    labelled as such by the sources it produces — it is still better than
+    printing nothing, because the common case for an operator running `status`
+    is a daemon that is not running at all.
+    """
+    if isinstance(run_state, dict) and isinstance(run_state.get("config"), dict):
+        return DaemonConfig.from_document(run_state["config"])  # type: ignore[arg-type]
+    return DaemonConfig.resolve()
+
+
+def _store(paths: RuntimePaths) -> FindingStore | None:
+    if not paths.state.exists():
+        return None
+    # A reader, so it neither sweeps nor writes: `read_only` is SQLite's own
+    # `mode=ro`, which is what keeps an inspection command from racing the
+    # daemon's first `connect()` through schema creation (`db.connect`).
+    return FindingStore(paths.state, prune_on_open=False, read_only=True)
+
+
+def _watermark_line(paths: RuntimePaths) -> str:
+    store = _store(paths)
+    if store is None:
+        return "never scanned (no database yet)"
+    moment = store.scan_watermark()
+    if moment is None:
+        return "never scanned"
+    age = datetime.now(UTC) - moment
+    return f"{moment.isoformat()} ({int(age.total_seconds())}s ago)"
+
+
+def _queue_line(paths: RuntimePaths) -> str:
+    store = _store(paths)
+    return "0 (no database yet)" if store is None else f"{store.queue_depth()} rows"
+
+
+def _cursor_line(paths: RuntimePaths) -> str:
+    """Where the Fleet drain has got to, per agent kind.
+
+    No row at all is the answer for an unconfigured endpoint, and it is the
+    right one: retention prunes below the cursor floor, so a subscriber that
+    cannot run must hold no cursor rather than one at zero.
+    """
+    store = _store(paths)
+    if store is None:
+        return "none (no database yet)"
+    cursors = store.cursors()
+    if not cursors:
+        return "none held (retention falls back to age alone)"
+    return ", ".join(f"{kind}@{seq}" for kind, seq in sorted(cursors.items()))
+
+
+def _parked_line(paths: RuntimePaths) -> str:
+    """Rows the far side rejected on their own merits, newest first.
+
+    Read from the table rather than from memory, so a rejection that happened
+    before the last restart is not silently forgotten.
+    """
+    store = _store(paths)
+    if store is None:
+        return "0"
+    newest = store.newest_park()
+    if newest is None:
+        return f"{store.parked_count()}"
+    return (
+        f"{store.parked_count()} (newest: seq {newest['seq']} {newest['kind']} "
+        f"at {newest['parked_at']} — {newest['reason']})"
+    )
+
+
+def _database_line(paths: RuntimePaths) -> str:
+    store = _store(paths)
+    if store is None:
+        return f"absent ({paths.state})"
+    return f"{store.database_size()} bytes ({paths.state})"
 
 
 @daemon.command()
@@ -59,6 +264,74 @@ def subscribe(agent_kind: str, session_id: str) -> None:
         raise click.ClickException(str(error)) from error
 
 
+@daemon.command()
+def flush() -> None:
+    """Upload what is queued now, without waiting for the next interval.
+
+    One drain pass, reported. A large backlog drains over several passes —
+    `_batches` splits by serialised size and the read is capped — so this
+    reports what one pass did rather than looping until the queue is empty.
+
+    There is no fallback to scanning. An endpoint with no daemon uploads by
+    re-collecting (`stacktrace remote sync detect`), and a command that
+    silently switched sources would make its output mean two different things.
+    """
+    daemon_is_running, _, _ = _runtime()
+    from .client import ProtocolError, request_flush
+
+    paths = RuntimePaths.from_environment()
+    if not daemon_is_running(paths.socket):
+        raise click.ClickException(
+            "no daemon is running, so there is no queue to drain; this endpoint "
+            "uploads by scanning instead — run `stacktrace remote sync detect`"
+        )
+    try:
+        result = request_flush(paths.socket)
+    except (OSError, ProtocolError) as error:
+        raise click.ClickException(f"flush failed: {error}") from error
+
+    click.echo(f"uploaded: {result.uploaded}")
+    click.echo(f"parked: {result.parked}")
+    click.echo(f"kinds: {', '.join(result.kinds) or 'none'}")
+    if result.stopped is not None:
+        # Not an echo: `flush && <something that ends the machine>` has to see
+        # a non-zero exit when nothing left.
+        raise click.ClickException(f"stopped: {result.stopped}")
+
+
+@daemon.command("sync-bom")
+def sync_bom() -> None:
+    """Upload the endpoint composition now, instead of on `--bom-interval`.
+
+    The same `sync_endpoint()` the scheduled job runs, serialised with it: two
+    runs share the spool directory and the config file the asset id is written
+    to. Progress still goes to the daemon log, and is echoed here as well so a
+    local run does not also require tailing it.
+
+    `stacktrace remote sync endpoint` does the same upload without a daemon.
+    This one exists to exercise the daemon's own path — the reporter, the
+    serialisation, and the composition the resident process is holding.
+    """
+    daemon_is_running, _, _ = _runtime()
+    from .client import ProtocolError, request_sync_bom
+
+    paths = RuntimePaths.from_environment()
+    if not daemon_is_running(paths.socket):
+        raise click.ClickException(
+            "no daemon is running; to upload without one, run `stacktrace remote sync endpoint`"
+        )
+    try:
+        result = request_sync_bom(paths.socket)
+    except (OSError, ProtocolError) as error:
+        raise click.ClickException(f"bom sync failed: {error}") from error
+
+    for line in result.report:
+        click.echo(line)
+    click.echo(f"uploaded: {result.uploaded}")
+    if result.failure is not None:
+        raise click.ClickException(result.failure)
+
+
 def _runtime():
     if os.name != "posix":
         raise click.ClickException(
@@ -72,15 +345,14 @@ def _runtime():
 @click.command()
 @click.option(
     "--agent-kind",
-    required=True,
-    help="Agent kind that owns the native session.",
+    default=None,
+    help="Only this agent kind. Every kind by default.",
 )
 @click.option(
     "--session",
     "session_id",
-    envvar="CLAUDE_CODE_SESSION_ID",
-    required=True,
-    help="Native session ID. Defaults to CLAUDE_CODE_SESSION_ID.",
+    default=None,
+    help="Only this native session ID. Every session by default.",
 )
 @click.option(
     "--format",
@@ -89,18 +361,47 @@ def _runtime():
     default="text",
     show_default=True,
 )
-def findings(agent_kind: str, session_id: str, output_format: str) -> None:
-    """Show Stacktrace findings for one native agent session."""
+def findings(agent_kind: str | None, session_id: str | None, output_format: str) -> None:
+    """Show what Stacktrace has found on this machine.
+
+    Neither key is required, and `--session` deliberately does **not** read
+    `CLAUDE_CODE_SESSION_ID`: the unqualified command would then be silently
+    scoped to one session inside an agent session, which is the one place an
+    operator is most likely to run it and least likely to notice.
+    """
     paths = RuntimePaths.from_environment()
-    stored = FindingStore(paths.state).findings(SessionKey(agent_kind, session_id))
+    # `_store()`, not a bare `FindingStore(...)`: a reader must not initialize
+    # the database as a side effect of reporting that there is none -- besides
+    # the surprise, two processes racing that (this command and a daemon's own
+    # first open) could both see an unversioned file and each try to insert
+    # the same schema_version row.
+    try:
+        store = _store(paths)
+    except (sqlite3.DatabaseError, ValueError) as exc:
+        # A corrupt file or a schema newer than this build reads raises here
+        # (`_check_version`'s own refusal) -- an inspection command must
+        # report that rather than exit on a traceback.
+        raise click.ClickException(f"database unreadable — {exc}") from exc
+    stored = () if store is None else store.recorded(agent_kind=agent_kind, session_id=session_id)
     if output_format == "json":
-        click.echo(json.dumps({"findings": stored}, indent=2))
+        # Additive, not a new envelope: `findings --format json` shipped in
+        # v0.4.0 as a list of findings, and a reader of `finding["rule_id"]`
+        # keeps working. The row's own columns win over any same-named key in
+        # the payload, because they are what the store filed it under.
+        document = [
+            {**finding, "agent_kind": session.agent_kind, "session_id": session.session_id}
+            for session, finding in stored
+        ]
+        click.echo(json.dumps({"findings": document}, indent=2))
         return
     if not stored:
-        click.echo("No Stacktrace findings for this session.")
-        return
-    for finding in stored:
         click.echo(
-            f"{str(finding.get('severity', 'unknown')).upper()} "
-            f"{finding.get('rule_id', 'unknown-rule')}: {finding.get('title', 'Finding')}"
+            "No Stacktrace findings for this session." if session_id else "No Stacktrace findings."
         )
+        return
+    for session, finding in stored:
+        # The session is named on every row, not grouped into a header: the
+        # list is read by eye and by grep, and a header is lost to both once
+        # the output is filtered.
+        click.echo(f"[{session.agent_kind}:{session.session_id}]")
+        click.echo(render_finding(finding))