stacktrace-cli 0.5.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

stacktrace_cli/daemon/cli.py

@@ -4,34 +4,369 @@ from __future__ import annotations
 
 import json
 import os
+import sqlite3
 import sys
+import time
+from collections.abc import Callable
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TypeVar
 
 import click
 
+from .config import DaemonConfig
 from .paths import RuntimePaths
 from .presentation import render_finding
 from .store import FindingStore, SessionKey
 
+_T = TypeVar("_T")
+
 
 @click.group()
 def daemon() -> None:
     """Manage automatic session detection."""
 
 
-@daemon.command("run", hidden=True)
-def run_command() -> None:
+#: Bounds how long `status`/`stop` retry a control request against a daemon
+#: whose lock is held but that has not yet answered. The accept loop starts
+#: before composition startup, but the lock is taken earlier than that
+#: (version lookup, opening the store, binding the socket). A request in
+#: that gap would otherwise see its control timeout expire with nobody yet
+#: reading it. Comfortably larger than the gap so an ordinary start never
+#: surfaces as unresponsive.
+_STARTUP_GRACE_SECONDS = 10.0
+
+#: How long `stop` waits for the singleton lock once shutdown has been
+#: accepted. Its own budget, not shared with `_STARTUP_GRACE_SECONDS`:
+#: retrying during startup must not eat the time the in-progress tick needs.
+#: Accepting shutdown only sets the stop event. The tick — a scan, then
+#: Fleet drain and BOM upload — runs to completion before the loop notices,
+#: and the lock stays held through that work, the telemetry flush, and
+#: `compositions.close()`. Fleet's HTTP client allows 30s per attempt and
+#: three attempts (~95s for one call), and one tick can make several. A 10s
+#: budget expired during an ordinary pass, so `stop` reported failure and
+#: dropped the transition lock while the process was still shutting down;
+#: the next `start` then saw `ALREADY_RUNNING`. 600s covers several retried
+#: cloud calls plus the scan and the shutdown tail, and still gives up when
+#: the process is stuck.
+_STOP_TIMEOUT_SECONDS = 600.0
+
+
+def _retry_while_starting(
+    lock_path: Path, call: Callable[[], _T], errors: tuple[type[Exception], ...]
+) -> _T:
+    """Retry a lifecycle control request while the daemon lock is held.
+
+    Treats an early failure as evidence of the startup gap described above,
+    not as proof the daemon is actually unresponsive -- as long as the lock
+    is still held, that gap closes on its own within a few seconds.
+    """
+    from .lifecycle import daemon_lock_held
+
+    deadline = time.monotonic() + _STARTUP_GRACE_SECONDS
+    while True:
+        try:
+            return call()
+        except errors:
+            if not daemon_lock_held(lock_path) or time.monotonic() >= deadline:
+                raise
+            time.sleep(0.1)
+
+
+@daemon.command("run")
+# 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(
+    "--webhook-interval",
+    default=None,
+    help="How often to retry configured webhook delivery. 0 disables only the fallback;"
+    " new findings still wake delivery. Defaults to STACKTRACE_WEBHOOK_INTERVAL, then 1m.",
+)
+@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,
+    webhook_interval: str | None,
+    bom_interval: str | None,
+) -> None:
+    """Run the daemon in the foreground for a host supervisor."""
     _, _, 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,
+            webhook_interval=webhook_interval,
+            bom_interval=bom_interval,
+        )
+        _reject_unobservable_kinds(config)
+    except ValueError as error:
+        raise click.ClickException(str(error)) from error
+    from .lifecycle import DETACHED_ENV
+
+    status = run_daemon(
+        paths,
+        config,
+        own_std_streams=os.environ.get(DETACHED_ENV) == "1",
+    )
+    if status:
+        raise click.exceptions.Exit(status)
+
+
+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."""
-    daemon_is_running, _, _ = _runtime()
+    """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`).
+    """
+    from stacktrace_cli.build import version_label
+
+    from .client import ProtocolError, request_status
+    from .lifecycle import daemon_lock_held
+    from .runtime import last_error
+
     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.")
+    live = None
+    try:
+        live = _retry_while_starting(
+            paths.lock,
+            lambda: request_status(paths.socket),
+            (ConnectionError, OSError, ProtocolError),
+        )
+    except (ConnectionError, OSError, ProtocolError):
+        pass
+    if live is None and daemon_lock_held(paths.lock):
+        click.echo("running: unresponsive")
+    else:
+        click.echo(f"running: {'yes' if live is not None else 'no'}")
+    if live is not None:
+        click.echo(f"version: {live.build}")
+        click.echo(f"installed: {version_label()}")
+        click.echo(f"started: {live.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(live.config if live is not None else None)
+    except ValueError as exc:
+        # No live status 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(document: 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 document is not None:
+        return DaemonConfig.from_document(document)
+    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()
+def start() -> None:
+    """Start one detached daemon when no host service manager is available."""
+    _runtime()
+    from .lifecycle import StartOutcome, start_daemon, transition_lock
+
+    paths = RuntimePaths.from_environment()
+    try:
+        with transition_lock(paths.transition_lock):
+            outcome = start_daemon(paths)
+    except (OSError, RuntimeError) as error:
+        raise click.ClickException(f"could not start daemon: {error}") from error
+    if outcome is StartOutcome.ALREADY_RUNNING:
+        click.echo("Stacktrace daemon is already running.")
+    else:
+        click.echo("Stacktrace daemon started.")
+
+
+@daemon.command()
+def stop() -> None:
+    """Ask the running daemon to shut down cleanly."""
+    from .client import ProtocolError, request_shutdown
+    from .lifecycle import daemon_lock_held, transition_lock
+
+    paths = RuntimePaths.from_environment()
+    with transition_lock(paths.transition_lock):
+        if not daemon_lock_held(paths.lock):
+            click.echo("Stacktrace daemon is not running.")
+            return
+        try:
+            _retry_while_starting(
+                paths.lock,
+                lambda: request_shutdown(paths.socket),
+                (ConnectionError, OSError, ProtocolError),
+            )
+        except (ConnectionError, OSError, ProtocolError) as error:
+            if not daemon_lock_held(paths.lock):
+                click.echo("Stacktrace daemon stopped.")
+                return
+            raise click.ClickException(
+                "daemon is running but unresponsive; restart it through its host "
+                "supervisor or use OS process tools"
+            ) from error
+        deadline = time.monotonic() + _STOP_TIMEOUT_SECONDS
+        while time.monotonic() < deadline:
+            if not daemon_lock_held(paths.lock):
+                click.echo("Stacktrace daemon stopped.")
+                return
+            time.sleep(0.1)
+    raise click.ClickException(f"daemon did not stop; see {paths.log}")
 
 
 @daemon.command()
@@ -60,6 +395,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(
@@ -73,15 +476,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",
@@ -90,15 +492,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.")
+        click.echo(
+            "No Stacktrace findings for this session." if session_id else "No Stacktrace findings."
+        )
         return
-    for finding in stored:
+    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))