@prism-d1/cli 1.8.0 → 1.9.0

package/dist/assets/kirocrew-app/README.md

@@ -0,0 +1,231 @@
+# PRISM app for Kiro Crew (v0.2)
+
+A [Kiro Crew](https://github.com/kirodotdev/KiroCrew) app that brings your local PRISM data into
+Kiro Crew. It adds:
+
+- **Page `PRISM`** in the sidebar: spend today and this month, top models and projects, the
+  machine setup checklist, the repos with codewatch (newest commit first, with their findings), a
+  sandboxed view of each repo's scan report, and when the daily digest last ran and what it sent.
+  See [The page](#the-page).
+- **MCP server `prism`**: the tools `prism_status`, `prism_findings`, `prism_spend`, `prism_report`
+  and `prism_setup`. The app does not implement them. `scripts/prism_mcp.py` finds your
+  `prism-cli` and replaces itself with `prism-cli mcp` (an argv list, no shell). See
+  [MCP server](../USER_GUIDE.md#mcp-server-prism-cli-mcp) for what each tool returns.
+- **Skill `prism-fix-findings`**: before an agent finishes or pushes a code change in a repo with
+  codewatch, it calls `prism_findings`, fixes the real issues in at most 2 rounds, and then reports
+  what remains. It treats finding text as untrusted reviewer-model output. It never pushes, never
+  disables hooks and never edits `.prism/results/`. When a person asks, it only reports.
+- **Cron `prism-daily-digest`**: a script cron, so it makes no model call. It runs daily at 09:00
+  in the gateway machine's local time zone and notifies only when something changed (see
+  [How the digest decides to notify](#how-the-digest-decides-to-notify)).
+
+## Requirements
+
+- Kiro Crew 0.12.1 or later (`minKiroCrewVersion`; script crons in an app manifest and
+  `"timezone": "local"` were checked against 0.12.1). Linux or macOS.
+- `python3` on the gateway's PATH. The scripts use only the standard library.
+- [prism-cli](https://www.npmjs.com/package/@prism-d1/cli) 1.8.0 or later
+  (`npm install -g @prism-d1/cli`). The MCP server needs `prism-cli mcp`, which is new in 1.8.0.
+
+### Finding prism-cli
+
+The gateway and kiro-cli often start without nvm's folder on PATH. The app looks for `prism-cli`
+the same way the editor extension does, without running a shell, in this order:
+
+1. `cliPath` in the app's `data/config.json`. It must be an absolute path to an executable file.
+2. `PATH`. Relative entries are skipped.
+3. `$NVM_BIN`, then `~/.nvm/versions/node/*/bin`: the version that `~/.nvm/alias/default` names
+   first, then the newest.
+4. Volta (`$VOLTA_HOME/bin` or `~/.volta/bin`), `~/.local/bin`, `~/.npm-global/bin`, then
+   `$NPM_CONFIG_PREFIX/bin`.
+
+Before it runs `prism-cli`, the app puts that folder first on `PATH`, so the CLI's
+`#!/usr/bin/env node` line finds the `node` installed next to it.
+
+## Install
+
+With prism-cli 1.9.0 or later, which bundles this app:
+
+```bash
+npm i -g @prism-d1/cli && prism-cli enable kirocrew
+```
+
+`prism-cli enable kirocrew` prints its plan (install, update or already current, with the
+versions) and asks before it changes anything. It copies the bundled app to
+`~/.prism/kirocrew-app`, then runs `kirocrew app install`, or `kirocrew app update prism --source`
+when the app is already installed (also from another folder, such as a clone), and
+`kirocrew app enable prism` on a first install. It never installs Kiro Crew. `--dry-run` prints
+the plan only, `--status` shows the installed and bundled versions, the source folder, the API
+grants and the digest cron, and `--uninstall` removes the app. After a prism-cli upgrade,
+`prism-cli version` says when the bundled app is newer than the installed one.
+
+From a local folder instead (a clone, for development):
+
+```bash
+git clone https://github.com/aws-samples/sample-prism-d1-velocity.git
+kirocrew app install "$PWD/sample-prism-d1-velocity/kirocrew-app"
+kirocrew app enable prism
+```
+
+Kiro Crew copies the folder into its apps directory (`~/.kiro/crew/apps/prism/`). Later edits to
+the folder do nothing until you update the app. The app's data stays in
+`~/.kiro/crew/apps/prism/data/` across updates.
+
+Kiro Crew registers nothing from a third-party app until you trust it. If you enable the app from
+the dashboard's App Store, it asks you to trust this one app. `kirocrew app enable` refuses with
+`app_execution_denied` until you have trusted the app, either there or under
+**Settings → Security → Third-party apps**.
+
+What you are trusting. After you enable it, the app can:
+
+- run `python3 scripts/prism_mcp.py` as an MCP server in your agent sessions. That process runs
+  your `prism-cli mcp`, which reads the dashboard's local data under your home directory
+  (codewatch results in your repos, the codeburn usage cache and setup checks). It makes no
+  network or AWS calls. Kiro Crew asks you to approve each tool call, because the app
+  auto-approves none.
+- run `scripts/digest.py` once a day without a model. It runs `prism-cli dashboard --json`, which
+  scans git repos up to 3 levels under your home directory. It writes only
+  `digest-state.json` in the app's data folder, and it sends a Kiro Crew notification when
+  something changed.
+- give your agents the `prism-fix-findings` skill.
+- run `scripts/page_routes.py` inside the gateway process (`backend.hooks.routes`). These are the
+  page's two read-only routes. While the page is open, they run `prism-cli dashboard --json`,
+  `prism-cli --version`, `git log -1` in up to 30 repos, and `prism-cli codewatch report`. Each
+  report is written to `data/reports/` in the app's data folder and deleted as soon as it is read.
+  Any file older than a day that is left over is removed on the next report request. Like every
+  in-gateway app code, these routes run with the gateway's privileges.
+
+The manifest declares `cron`, `storage` and `api: ["/api/apps/prism/*"]` (the page may call only
+this app's own routes), and sets `network: false`. The app opens no port and runs no backend
+process. It has no install hooks, no `spawn` and no session control.
+
+### Updating from v0.1
+
+```bash
+kirocrew app update prism --source <path-to>/sample-prism-d1-velocity/kirocrew-app
+```
+
+v0.2 adds the `api` permission for the page. Per the App Kit, an update that adds an `api` entry
+keeps the app enabled but withholds the new entry until you approve it on the app's detail page
+(**Apps → PRISM**). Until you approve it, the page shows an API error. If the page answers 404 after
+the update, the gateway has not wired the new routes yet: disable and enable the app once, or
+restart the gateway.
+
+## Settings
+
+The app reads `~/.kiro/crew/apps/prism/data/config.json`, which is optional:
+
+```json
+{ "spendThreshold": 25, "cliPath": "/absolute/path/to/prism-cli" }
+```
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `spendThreshold` | off | Notify once a day when today's AI spend (codeburn, in its currency) is above this number. Remove the key, or set it to `null` or `0`, to turn it off. |
+| `cliPath` | not set | Use this `prism-cli` instead of searching for one. |
+
+To change the schedule, edit `prism-daily-digest` on the dashboard's **Schedule** page. Your edit
+is kept across app updates unless a later version of the app changes the schedule itself.
+
+## The page
+
+The **PRISM** sidebar page shows the same data as the editor extension's machine mode:
+
+- spend today and this month (calls, sessions), sync mode, prism-cli version, and when the data
+  and the usage cache were taken;
+- top models and top projects this month (project folder names only);
+- the machine setup checklist, with fix commands you can copy (the page never runs them);
+- the repos with codewatch, newest last commit first (`git log -1` in at most 30 repos, 4 at a
+  time; a repo whose commit is unknown sorts by its last review). Each repo shows a badge from its
+  latest review (red `N high`, amber `N med`, muted `N low`, green `clean`, or `no review`; the row's
+  left border uses the same color), whether its hooks are on, its last commit, the latest review's
+  counts and up to 20 findings, plus an "N more" line. Times on the page are relative ("3 h ago",
+  with the full local time as a tooltip) and update while the page is open;
+- **Open report**: the scan report of the review covering the repo's last commit, or the latest
+  review when none covers it. The page says which. You can also download the report;
+- **Last digest**: when the digest cron last ran and the last message it sent;
+- **Refresh**, plus an automatic refresh every 5 minutes while the page is visible.
+
+How it talks to its backend. The page is `ui/index.mjs`, an ES module that the dashboard loads.
+It calls `GET /api/apps/prism/data` and `GET /api/apps/prism/report?repoIndex=N` through the App
+SDK's `useAppApi()`, which allows only the paths in `permissions.api`. The gateway serves those
+routes from `scripts/page_routes.py` inside its own process. Its token middleware authenticates
+every request (a dashboard session, or an app token scoped to `permissions.api`; loopback is not
+exempt). Each handler then also requires the dashboard owner (`ctx.require_owner`), or this app's
+own token, and refuses everything else.
+
+Security:
+
+- The page sends only indexes. The backend resolves an index against its own last result and
+  refuses any value that is not a plain number inside that list.
+- Recorded text (repo names, commit subjects, finding messages written by a reviewer model) is
+  rendered only as React text, never as HTML.
+- The report HTML is untrusted. It is shown in an `<iframe sandbox="">` (no scripts, an opaque
+  origin, no forms or popups), and the backend adds a CSP that blocks script and every remote load.
+- Usage comes from the dashboard's 5-minute cache. When nothing is cached for today, the page does
+  not start a codeburn export. It says so and offers a **Load now** button that does. When the cache
+  is stale, the backend returns as soon as `dashboard --json` prints and lets the CLI's background
+  refresh finish on its own.
+
+## How the digest decides to notify
+
+Each run reads `prism-cli dashboard --json` (with no `--root`, so it scans your whole home
+directory) and compares it with the previous run's `data/digest-state.json`. It sends one message
+that lists the changes below, then saves the new state. If delivery fails, the state is not saved,
+so the next run reports the same changes again:
+
+- **New high findings.** For each repo, the high findings in the latest codewatch review of each
+  branch that were not there last time. A finding is identified by branch, file and rule, so the
+  same issue reviewed again on a later push is not counted as new. The message gives the repo name
+  (never its path), the count, and the review's short commit and branch. It also includes the first
+  finding's text, cut to 120 characters on one line. That text comes from a reviewer model and is
+  only displayed, never acted on.
+- **Spend.** Today's spend is above `spendThreshold`. This is sent at most once per day.
+- **Setup regressions.** A machine setup item, or a repo's codewatch setup, went from `ok` to
+  `warn` or `missing`.
+
+When nothing changed, the run is silent. The first run, and any run that finds the state file
+missing or unreadable, saves a baseline and sends nothing. If `prism-cli` cannot be found or fails,
+the run ends in an error, which the Schedule page shows, and the saved state is left as it was.
+
+To see what a run would send without Kiro Crew:
+
+```bash
+python3 kirocrew-app/scripts/digest.py --state-dir "$(mktemp -d)"   # prints the message, or why it was quiet
+```
+
+`--state-dir DIR` is required and keeps a manual run away from the cron's own state. `--payload FILE`
+reads a saved `dashboard --json` output instead of running `prism-cli`.
+
+## Uninstall
+
+```bash
+prism-cli enable kirocrew --uninstall   # kirocrew app uninstall prism, then removes ~/.prism/kirocrew-app
+```
+
+Or with Kiro Crew directly:
+
+```bash
+kirocrew app disable prism
+kirocrew app uninstall prism
+```
+
+Disabling the app removes its cron job, MCP server and skill. By default, uninstalling keeps
+`~/.kiro/crew/apps/prism/data/`. Delete that folder yourself if you want the state gone.
+
+## Development
+
+```bash
+python3 -m unittest discover -s kirocrew-app/tests
+node --test kirocrew-app/tests/page.test.mjs
+```
+
+The tests cover the digest's diff logic, the `prism-cli` lookup, the page model (sorting, caps,
+index checks, report arguments and fallback, digest state) and the page's rendering with fixture
+data. They also check `app.json` against the
+[App Kit manifest reference](https://github.com/kirodotdev/KiroCrew/blob/main/docs/app-kit/manifest-reference.md).
+When Kiro Crew is installed, they also run Kiro Crew's own manifest validator. CI runs them in
+`.github/workflows/kirocrew-app.yml`.
+
+Not in v0.2: Windows support (`os.execve` on an npm `.cmd` shim needs a shell), and delivery to a
+channel other than Kiro Crew's default notification.

package/dist/assets/kirocrew-app/app.json

@@ -0,0 +1,94 @@
+{
+  "name": "prism",
+  "version": "0.2.2",
+  "displayName": "PRISM",
+  "description": "Codewatch findings, AI spend and setup status from your local prism-cli for Kiro Crew agents, and a daily digest that speaks only when something changed.",
+  "author": "aws-samples",
+  "license": "MIT",
+  "minKiroCrewVersion": "0.12.1",
+  "iconPath": "assets/icon.png",
+  "tags": ["code-review", "developer-tools", "code-quality"],
+  "highlights": [
+    "PRISM page: spend, setup checklist, repos with codewatch newest commit first, their findings and a sandboxed scan report, all read-only",
+    "The prism MCP server: prism_status, prism_findings, prism_spend, prism_report and prism_setup, served by your own prism-cli mcp",
+    "Finds prism-cli installed with nvm or Volta even when Kiro Crew's PATH does not include it",
+    "prism-fix-findings skill: an agent checks the latest codewatch review before it finishes, fixes real issues in at most 2 rounds and reports the rest",
+    "prism-daily-digest: a script cron with no model call that notifies only on a new high finding, spend over your threshold, or a setup item that broke"
+  ],
+  "useCases": [
+    "When you start the day, open the PRISM page to see which repos got new codewatch findings since their last commit and open the scan report of the one that needs attention",
+    "When an agent finishes a code change in a repo with codewatch, the prism-fix-findings skill has it call prism_findings and fix the real high and medium findings before it reports done",
+    "When you want to know what codewatch flagged across your repos, ask a chat to call prism_findings or prism_status instead of opening the dashboard",
+    "When you want a heads-up without watching a page, let prism-daily-digest run at 09:00 and tell you only about new high findings, a setup regression, or spend over your threshold"
+  ],
+  "configuration": [
+    "Install with prism-cli 1.9.0 or later: npm install -g @prism-d1/cli && prism-cli enable kirocrew (or install this folder; see the README)",
+    "Trust the app when you enable it; Kiro Crew registers nothing from a third-party app until you do",
+    "Optional: set spendThreshold and cliPath in the app's data/config.json (see the README)"
+  ],
+  "links": [
+    { "label": "README", "url": "https://github.com/aws-samples/sample-prism-d1-velocity/blob/main/kirocrew-app/README.md" },
+    { "label": "PRISM user guide", "url": "https://github.com/aws-samples/sample-prism-d1-velocity/blob/main/USER_GUIDE.md" }
+  ],
+  "skills": ["skills/prism-fix-findings"],
+  "ui": {
+    "entry": "index.mjs",
+    "pages": [
+      { "route": "/apps/prism", "label": "PRISM", "icon": "ScanSearch" }
+    ]
+  },
+  "backend": {
+    "hooks": {
+      "routes": "scripts.page_routes:register_routes"
+    }
+  },
+  "mcpServers": {
+    "prism": {
+      "command": "python3",
+      "args": ["scripts/prism_mcp.py"]
+    }
+  },
+  "crons": [
+    {
+      "name": "prism-daily-digest",
+      "cron_expr": "0 9 * * *",
+      "timezone": "local",
+      "strict_schedule": true,
+      "script": "scripts/digest.py:run",
+      "message": "PRISM daily digest (script, no model call)",
+      "persistent_session": false,
+      "timeout": 120,
+      "timeout_secs": 130
+    }
+  ],
+  "permissions": {
+    "api": ["/api/apps/prism/*"],
+    "cron": true,
+    "storage": true,
+    "network": false
+  },
+  "dependencies": {
+    "commands": ["python3"],
+    "optionalCommands": ["prism-cli"]
+  },
+  "platform": {
+    "os": ["macos", "linux"]
+  },
+  "setup": {
+    "configSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "spendThreshold": {
+          "type": ["number", "null"],
+          "exclusiveMinimum": 0,
+          "description": "Notify once a day when today's AI spend (codeburn, in its currency) is above this. Unset or null: off."
+        },
+        "cliPath": {
+          "type": ["string", "null"],
+          "description": "Absolute path to prism-cli, when it is not found on PATH or in the nvm, Volta, ~/.local/bin or npm prefix folders."
+        }
+      }
+    }
+  }
+}

package/dist/assets/kirocrew-app/scripts/digest.py

@@ -0,0 +1,263 @@
+"""Daily PRISM digest: a script cron (no model call).
+
+Runs `prism-cli dashboard --json`, compares it with the state the previous
+run saved in the app's data folder, and notifies only when something changed:
+
+- a new high finding in a repo's latest codewatch review,
+- today's AI spend above `spendThreshold` (data/config.json; off by default),
+  at most once per day,
+- a setup item that went from ok to warn or missing.
+
+First run, or a state file that cannot be read: save a baseline, no message.
+Finding text is written by a reviewer model: it is shown shortened on one
+line and never acted on.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import os
+import re
+import subprocess
+import sys
+import threading
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from prism_cli_path import app_data_dir, cli_env, load_config, resolve_cli
+
+STATE_FILE = "digest-state.json"
+STATE_SCHEMA = 1
+DASHBOARD_TIMEOUT_S = 80  # until the document is printed; plus REFRESH_GRACE_S stays under the cron's 120 s timeout
+REFRESH_GRACE_S = 20  # time left for the CLI's codeburn refresh after it printed
+FINDING_CHARS = 120
+NAME_CHARS = 60
+SHORT_SHA = 7
+CURRENCY_CHARS = 8
+MAX_REPOS_LISTED = 10
+BAD_SETUP = ("warn", "missing")
+_CONTROL = re.compile(r"[\x00-\x1f\x7f-\x9f\u200b-\u200f\u2028-\u202e\u2066-\u2069]")
+
+
+def clean(text: Any, limit: int) -> str:
+    """One plain line: control and bidi characters dropped, whitespace collapsed, cut to `limit`."""
+    s = " ".join(_CONTROL.sub(" ", str(text or "")).split())
+    return s if len(s) <= limit else s[: limit - 1].rstrip() + "…"
+
+
+def _fingerprint(f: Dict[str, Any]) -> str:
+    # No commit or line: the same issue re-reviewed on a later push is not new.
+    return "|".join(str(f.get(k) or "") for k in ("branch", "file", "rule"))
+
+
+def _repo_name(repo: Dict[str, Any]) -> str:
+    # The dashboard's label is already unique: it adds a short parent path when two repos share a name.
+    return str(repo.get("label") or repo.get("name") or "")
+
+
+def snapshot(payload: Dict[str, Any]) -> Dict[str, Any]:
+    """The parts of the dashboard payload the digest compares."""
+    highs: Dict[str, List[str]] = {}
+    setup: Dict[str, str] = {}
+    for item in (payload.get("machine") or {}).get("setup") or []:
+        if item.get("id"):
+            setup["machine:" + str(item["id"])] = str(item.get("status") or "")
+    for repo in payload.get("repos") or []:
+        name = _repo_name(repo)
+        if not name:
+            continue
+        fps = sorted({_fingerprint(f) for f in (repo.get("codewatch") or {}).get("findings") or [] if f.get("severity") == "high"})
+        if fps:
+            highs[name] = fps
+        status = (repo.get("setup") or {}).get("status")
+        if status:
+            setup["repo:" + name] = str(status)
+    return {"highs": highs, "setup": setup}
+
+
+def _setup_label(key: str, payload: Dict[str, Any]) -> str:
+    kind, _, ident = key.partition(":")
+    if kind == "machine":
+        for item in (payload.get("machine") or {}).get("setup") or []:
+            if str(item.get("id")) == ident:
+                return clean(item.get("label") or ident, NAME_CHARS)
+        return clean(ident, NAME_CHARS)
+    return "codewatch in " + clean(ident, NAME_CHARS)
+
+
+def _new_high_lines(prev: Dict[str, List[str]], payload: Dict[str, Any]) -> List[str]:
+    lines: List[str] = []
+    for repo in payload.get("repos") or []:
+        name = _repo_name(repo)
+        if not name:
+            continue  # never stored in state, so it would look new on every run
+        seen = set(prev.get(name) or [])
+        # One line per branch: each branch's latest review has its own commit.
+        by_branch: Dict[str, Dict[str, Dict[str, Any]]] = {}
+        for f in (repo.get("codewatch") or {}).get("findings") or []:
+            if f.get("severity") == "high" and _fingerprint(f) not in seen:
+                by_branch.setdefault(str(f.get("branch") or "?"), {}).setdefault(_fingerprint(f), f)
+        for branch, new in sorted(by_branch.items()):
+            first = next(iter(new.values()))
+            commit = clean(first.get("commit") or "?", NAME_CHARS)[:SHORT_SHA]
+            n = len(new)
+            lines.append(
+                f"- {clean(name, NAME_CHARS)}: {n} new high finding{'s' if n != 1 else ''} "
+                f"(review of {commit} on {clean(branch, NAME_CHARS)}). First: {clean(first.get('message') or first.get('rule'), FINDING_CHARS)}"
+            )
+    if len(lines) > MAX_REPOS_LISTED:
+        lines = lines[:MAX_REPOS_LISTED] + [f"- and {len(lines) - MAX_REPOS_LISTED} more entries"]
+    return lines
+
+
+def evaluate(
+    prev: Optional[Dict[str, Any]],
+    payload: Dict[str, Any],
+    threshold: Optional[float],
+    today: str,
+) -> Tuple[Optional[str], Dict[str, Any]]:
+    """(message or None, state to save). `prev` None means first run or unreadable state: baseline only."""
+    snap = snapshot(payload)
+    state: Dict[str, Any] = {"schema": STATE_SCHEMA, **snap, "spendAlertDate": None,
+                             "lastNotifiedAt": None, "lastMessage": None}
+    if prev is None:
+        return None, state
+    state["spendAlertDate"] = prev.get("spendAlertDate")
+    # Shown on the app's page ("Last digest").
+    state["lastNotifiedAt"] = prev.get("lastNotifiedAt")
+    state["lastMessage"] = prev.get("lastMessage")
+
+    lines = _new_high_lines(prev.get("highs") or {}, payload)
+
+    usage = payload.get("usage") or {}
+    cost = (usage.get("today") or {}).get("cost") if usage.get("status") == "ok" else None
+    if threshold and isinstance(cost, (int, float)) and cost > threshold and prev.get("spendAlertDate") != today:
+        cur = clean(usage.get("currency") or "USD", CURRENCY_CHARS)
+        lines.append(f"- AI spend today is {cost:.2f} {cur}, above your threshold of {threshold:.2f} {cur}.")
+        state["spendAlertDate"] = today
+
+    prev_setup = prev.get("setup") or {}
+    for key, status in sorted(snap["setup"].items()):
+        if prev_setup.get(key) == "ok" and status in BAD_SETUP:
+            lines.append(f"- Setup: {_setup_label(key, payload)} went from ok to {status}.")
+
+    if not lines:
+        return None, state
+    return "PRISM daily digest\n" + "\n".join(lines), state
+
+
+def read_state(path: Path) -> Optional[Dict[str, Any]]:
+    """The saved state, or None when it is missing or not a state this version wrote."""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(data, dict) or data.get("schema") != STATE_SCHEMA:
+        return None
+    if not isinstance(data.get("highs"), dict) or not isinstance(data.get("setup"), dict):
+        return None
+    return data
+
+
+def write_state(path: Path, state: Dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(json.dumps(state, indent=1, sort_keys=True) + "\n", encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def spend_threshold(cfg: Dict[str, Any]) -> Optional[float]:
+    v = cfg.get("spendThreshold")
+    if isinstance(v, bool) or not isinstance(v, (int, float)) or v <= 0:
+        return None
+    return float(v)
+
+
+def run_dashboard(cfg: Dict[str, Any]) -> Dict[str, Any]:
+    setting = cfg.get("cliPath")
+    cli, reason = resolve_cli(setting if isinstance(setting, str) else None, os.environ)
+    if not cli:
+        raise RuntimeError(reason)
+    # No --root: the CLI scans the home directory, as the dashboard does.
+    # With a stale usage cache the CLI prints the document, then waits for its codeburn refresh;
+    # read only up to the closing line, give the refresh a moment, then stop the child, so that
+    # wait cannot push this run past the cron's timeout.
+    proc = subprocess.Popen([cli, "dashboard", "--json"], cwd=str(Path.home()), env=cli_env(cli, os.environ),
+                            stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
+    lines: List[bytes] = []
+
+    def read_doc() -> None:
+        assert proc.stdout is not None
+        for line in proc.stdout:
+            lines.append(line)
+            if line == b"}\n":  # the document is pretty-printed; this closes it
+                return
+
+    try:
+        reader = threading.Thread(target=read_doc, daemon=True)
+        reader.start()
+        reader.join(DASHBOARD_TIMEOUT_S)  # a deadline of our own, under the cron's 120 s kill
+        if not reader.is_alive():
+            try:
+                proc.wait(timeout=REFRESH_GRACE_S)
+            except subprocess.TimeoutExpired:
+                pass
+    finally:
+        if proc.poll() is None:
+            proc.kill()
+            proc.wait()
+    if not lines or lines[-1] != b"}\n":
+        raise RuntimeError(f"prism-cli dashboard --json gave no complete document (exit {proc.returncode})")
+    payload = json.loads(b"".join(lines).decode("utf-8"))
+    if not isinstance(payload, dict) or not str(payload.get("schema", "")).startswith("prism.dashboard."):
+        raise RuntimeError("prism-cli dashboard --json returned an unexpected document")
+    return payload
+
+
+def digest_once(
+    data_dir: Path,
+    payload: Optional[Dict[str, Any]] = None,
+    deliver: Optional[Callable[[str], Any]] = None,
+) -> Tuple[Optional[str], bool]:
+    """Run one digest. Returns (message or None, baseline_only).
+
+    The state is saved only after `deliver(msg)` returns, so a failed
+    delivery is retried on the next run instead of being lost.
+    """
+    cfg = load_config(data_dir)
+    if payload is None:
+        payload = run_dashboard(cfg)
+    path = data_dir / STATE_FILE
+    prev = read_state(path)
+    msg, state = evaluate(prev, payload, spend_threshold(cfg), _dt.date.today().isoformat())
+    stamp = _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds")
+    if msg and deliver:
+        deliver(msg)
+    state["lastRunAt"] = stamp
+    if msg:
+        state["lastNotifiedAt"], state["lastMessage"] = stamp, msg
+    write_state(path, state)
+    return msg, prev is None
+
+
+def run(ctx: Any) -> None:
+    """Cron entry point (app.json `scripts/digest.py:run`). ctx.notify raises when delivery fails."""
+    digest_once(app_data_dir(), deliver=ctx.notify)
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    ap = argparse.ArgumentParser(description="Run the PRISM digest once and print what it would send.")
+    # Required, so a manual run never advances the cron's own state with changes it did not deliver.
+    ap.add_argument("--state-dir", required=True, help="Folder for digest-state.json and config.json; use a scratch folder, not the app's data folder")
+    ap.add_argument("--payload", help="Read the dashboard JSON from this file instead of running prism-cli")
+    a = ap.parse_args(argv)
+    data_dir = Path(a.state_dir)
+    payload = json.loads(Path(a.payload).read_text(encoding="utf-8")) if a.payload else None
+    msg, baseline = digest_once(data_dir, payload)
+    print(msg if msg else ("baseline saved, no notification" if baseline else "no change, no notification"))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())