@prism-d1/cli 1.8.0 → 1.9.1

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())

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

@@ -0,0 +1,298 @@
+"""What the PRISM page shows, built from `prism-cli dashboard --json`. Stdlib only, no I/O
+except the small file reads named below, so it is unit-tested without Kiro Crew.
+
+Port of the editor extension's machine mode (editor-extension/src/panel-model.ts,
+machine.ts, text.ts). The page receives only the model; paths stay in the
+targets list, which the page addresses by index.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import os
+import re
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+COMMIT_LOOKUP_MAX = 30
+COMMIT_LOOKUP_CONCURRENCY = 4
+ROW_FINDINGS_MAX = 20
+MAX_TEXT = 2000
+REPORT_MAX_AGE_S = 24 * 3600
+USAGE_CACHE_SCHEMA = "prism.usage-cache.v1"
+RESULT_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$")
+REPORT_CSP = "default-src 'none'; style-src 'unsafe-inline'; img-src data:"
+
+# C0/C1 controls (except tab and newline) and bidi controls.
+_UNSAFE = re.compile("[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u200e\u200f\u202a-\u202e\u2066-\u2069]")
+
+
+def plain(s: Any, max_len: int = MAX_TEXT, one_line: bool = True) -> str:
+    t = "" if s is None else str(s)
+    t = _UNSAFE.sub("", t.replace("\r\n", "\n").replace("\r", "\n"))
+    if one_line:
+        t = re.sub(r"\s*\n\s*", " ", t)
+    return t if len(t) <= max_len else t[: max_len - 1] + "…"
+
+
+def money(n: Any, currency: str) -> str:
+    v = f"{float(n or 0):.2f}"
+    return f"${v}" if currency == "USD" else f"{v} {plain(currency, 8)}"
+
+
+def count(n: int, word: str) -> str:
+    return f"{n} {word}{'' if n == 1 else 's'}"
+
+
+def _time(iso: Any) -> Optional[float]:
+    if not isinstance(iso, str) or not iso:
+        return None
+    try:
+        return _dt.datetime.fromisoformat(iso.replace("Z", "+00:00")).timestamp()
+    except ValueError:
+        return None
+
+
+def base_name(s: Any) -> str:
+    parts = [p for p in re.split(r"[\\/]", str(s or "")) if p]
+    return plain(parts[-1] if parts else "", 120)
+
+
+# ---- usage cache -----------------------------------------------------------
+
+def usage_cached_today(home: Path, today: Optional[str] = None) -> bool:
+    """True when ~/.prism/cache/usage.json holds today's usage, so `dashboard --json` will not run a cold codeburn export."""
+    try:
+        c = json.loads((home / ".prism" / "cache" / "usage.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    today = today or _dt.date.today().isoformat()
+    return isinstance(c, dict) and c.get("schema") == USAGE_CACHE_SCHEMA and c.get("day") == today and isinstance(c.get("panel"), dict)
+
+
+# ---- repos -----------------------------------------------------------------
+
+def commit_lookup_paths(p: Dict[str, Any], max_n: int = COMMIT_LOOKUP_MAX) -> List[str]:
+    """Repos whose last commit is looked up: codewatch results only, newest review first, capped."""
+    repos = [r for r in p.get("repos") or [] if (r.get("codewatch") or {}).get("hasResults")]
+    repos.sort(key=lambda r: _time((r.get("codewatch") or {}).get("lastRunAt")) or 0, reverse=True)
+    return [r["path"] for r in repos[:max_n] if isinstance(r.get("path"), str)]
+
+
+def parse_last_commit(out: str) -> Optional[Dict[str, str]]:
+    """`git log -1 --format=%cI%x00%h%x00%s` output, or None."""
+    parts = out.rstrip("\n").split("\0")
+    if len(parts) < 2 or _time(parts[0]) is None or not parts[1]:
+        return None
+    return {"at": parts[0], "sha": parts[1], "subject": parts[2] if len(parts) > 2 else ""}
+
+
+def last_commit_args(repo: str) -> List[str]:
+    return ["git", "-C", repo, "log", "-1", "--format=%cI%x00%h%x00%s"]
+
+
+def machine_repos(p: Dict[str, Any], commits: Dict[str, Optional[Dict[str, str]]]) -> List[Dict[str, Any]]:
+    """'Repositories with codewatch', newest last commit first; no commit time: last review time; neither: last."""
+    by_path = {r.get("path"): r for r in p.get("repos") or []}
+    rows = []
+    for row in (p.get("overview") or {}).get("codewatch") or []:
+        repo = by_path.get(row.get("path"))
+        found = sorted((repo or {}).get("codewatch", {}).get("findings") or [], key=lambda f: _time(f.get("started_at")) or 0, reverse=True)
+        rows.append({"row": row, "repo": repo, "commit": commits.get(row.get("path")),
+                     "findings": found[:ROW_FINDINGS_MAX], "more": max(0, len(found) - ROW_FINDINGS_MAX)})
+
+    def key(m: Dict[str, Any]) -> float:
+        t = _time((m["commit"] or {}).get("at")) or _time(m["row"].get("lastRunAt"))
+        return t if t is not None else float("-inf")
+
+    rows.sort(key=key, reverse=True)
+    return rows
+
+
+def latest_review_of(repo: Optional[Dict[str, Any]]) -> Optional[Dict[str, Optional[str]]]:
+    """The branch and commit of the repo's latest review, for the --id fallback report."""
+    cw = (repo or {}).get("codewatch") or {}
+    rid = cw.get("lastReviewId")
+    if not rid:
+        return None
+    scan = next((s for s in cw.get("scans") or [] if s.get("id") == rid), None)
+    lb = next((b for b in cw.get("latestByBranch") or [] if scan and (b.get("review") or {}).get("started_at") == scan.get("started_at")), None)
+    return {"id": rid, "branch": (scan or {}).get("branch") or (lb or {}).get("branch"), "commit": ((lb or {}).get("review") or {}).get("commit")}
+
+
+def findings_badge(row: Dict[str, Any]) -> Dict[str, str]:
+    """The repo row's badge from its latest review; the row's left border uses the same tone."""
+    if not row.get("lastRunAt"):
+        return {"text": "no review", "tone": "none"}
+    high, med, low = (int(row.get(k) or 0) for k in ("high", "medium", "low"))
+    if high:
+        return {"text": f"{high} high", "tone": "error"}
+    if med:
+        return {"text": f"{med} med", "tone": "warn"}
+    if low:
+        return {"text": f"{low} low", "tone": "none"}
+    return {"text": "clean", "tone": "ok"}
+
+
+def hooks_text(status: Any) -> str:
+    """Codewatch hook status, shown as small muted text: it says the hooks run, not that the code is clean."""
+    s = plain(status or "unknown", 20)
+    return {"ok": "hooks on", "missing": "hooks off"}.get(s, "hooks " + s)
+
+
+def _check_item(i: Dict[str, Any]) -> Dict[str, str]:
+    help_text = (i.get("help") or {}).get("text")
+    return {"key": "m:" + plain(i.get("id"), 60), "label": plain(i.get("label"), 120), "status": plain(i.get("status"), 20),
+            "detail": plain(help_text or i.get("detail"), 500), "fix": plain(i.get("fix"), 500)}
+
+
+def build_model(p: Dict[str, Any], commits: Dict[str, Optional[Dict[str, str]]], version: str,
+                digest: Optional[Dict[str, Any]]) -> Tuple[Dict[str, Any], List[Dict[str, Any]]]:
+    """(model for the page, targets kept by the backend). The model holds no path; times stay ISO."""
+    u = p.get("usage") or {}
+    summary = p.get("summary") or {}
+    cur = u.get("currency") or (summary.get("spend") or {}).get("currency") or "USD"
+
+    def totals(title: str, t: Optional[Dict[str, Any]], extra: str = "") -> Dict[str, str]:
+        if not t:
+            return {"title": title, "value": "no data", "detail": ""}
+        return {"title": title, "value": money(t.get("cost"), cur),
+                "detail": f"{count(int(t.get('calls') or 0), 'call')} · {count(int(t.get('sessions') or 0), 'session')}{extra}"}
+
+    if u.get("status") == "ok":
+        m = u.get("month") or None
+        cards = [totals("AI spend today", u.get("today")),
+                 totals("AI spend this month", m, f" · {plain(m.get('from'), 10)} to {plain(m.get('to'), 10)}" if m else "")]
+    else:
+        cards = [{"title": "AI spend", "value": plain(u.get("status") or "unknown", 20), "detail": plain(u.get("message") or "", 300)}]
+    warn = summary.get("warnings") or {}
+    cards.append({"title": "Setup warnings", "value": str(int(warn.get("count") or 0)), "detail": plain(warn.get("first") or "nothing to fix", 300)})
+    cards.append({"title": "Sync mode", "value": plain(((p.get("machine") or {}).get("codeburnSync") or {}).get("mode") or "unknown", 20), "detail": "where codeburn usage goes"})
+
+    setup_of = {r.get("path"): r.get("status") for r in (p.get("overview") or {}).get("setup") or []}
+    rows: List[Dict[str, Any]] = []
+    targets: List[Dict[str, Any]] = []
+    for mr in machine_repos(p, commits):
+        r, c = mr["row"], mr["commit"]
+        name = plain(r.get("label") or r.get("name"), 120)
+        latest = latest_review_of(mr["repo"])
+        badge = findings_badge(r)
+        rows.append({
+            "name": name,
+            "review": f"{int(r.get('high') or 0)} high · {int(r.get('medium') or 0)} med · {int(r.get('low') or 0)} low" if r.get("lastRunAt") else "no review yet",
+            # Raw ISO times: the page shows them relative and re-renders them on its own clock.
+            "reviewAt": plain(r.get("lastRunAt") or "", 40),
+            "badge": badge,
+            "tone": badge["tone"],
+            "hooks": hooks_text(setup_of.get(r.get("path"))),
+            "commit": {"sha": plain(c["sha"], 12), "at": plain(c["at"], 40), "subject": plain(c["subject"], 80)} if c else None,
+            "findings": [{"severity": plain(f.get("severity"), 10),
+                          "location": plain(f.get("file"), 200) + (f":{f['line']}" if isinstance(f.get("line"), int) and not isinstance(f.get("line"), bool) else ""),
+                          "message": plain(f.get("message"), 300), "branch": plain(f.get("branch") or "(detached)", 80)} for f in mr["findings"]],
+            "more": f"{count(mr['more'], 'more finding')} not listed; open the report for all of them." if mr["more"] else "",
+            "hasReport": bool(latest),
+        })
+        targets.append({"path": r.get("path"), "name": name, "commit": c, "latest": latest})
+
+    counts = (p.get("overview") or {}).get("counts") or {}
+    model = {
+        "generatedAt": plain(p.get("generated_at"), 40),
+        "version": plain(version or "unknown", 40),
+        "usageUpdatedAt": plain(u.get("updatedAt") or "", 40),
+        "usageStale": bool(u.get("stale")),
+        "cards": cards,
+        "topModels": [{"name": plain(x.get("name"), 120), "value": f"{money(x.get('cost'), cur)} · {count(int(x.get('calls') or 0), 'call')}"} for x in u.get("topModels") or []],
+        "topProjects": [{"name": base_name(x.get("name")), "value": f"{money(x.get('cost'), cur)} · {count(int(x.get('sessions') or 0), 'session')}"} for x in u.get("topProjects") or []],
+        "checklist": [_check_item(i) for i in (p.get("machine") or {}).get("setup") or []],
+        "repos": rows,
+        "reposNote": f"{counts.get('codewatch', 0)} of {counts.get('repos', 0)} repos found under your home folder have codewatch. Newest commit first." if counts else "",
+        "digest": digest_view(digest),
+    }
+    return model, targets
+
+
+# ---- index resolution and report -------------------------------------------
+
+def parse_index(v: Any) -> Optional[int]:
+    """A non-negative integer from a query value, else None. No sign, no spaces, at most 6 digits."""
+    if isinstance(v, str) and re.fullmatch(r"\d{1,6}", v):
+        return int(v)
+    return None
+
+
+def target_for(targets: List[Dict[str, Any]], v: Any) -> Optional[Dict[str, Any]]:
+    """The backend's own target for a page-supplied index, or None when it is not an index into the last result."""
+    i = parse_index(v)
+    return targets[i] if i is not None and i < len(targets) else None
+
+
+def report_plan(target: Dict[str, Any], output: str) -> Dict[str, Any]:
+    """Primary: the review covering HEAD. Fallback: the latest review by id, with a note saying which branch and commit it covers."""
+    repo = target["path"]
+    primary = ["codewatch", "report", "--repo", repo, "--commit", "HEAD", "--format", "html", "--output", output]
+    c = target.get("commit")
+    head = f"commit {plain(c['sha'], 12)}" if c else "its last commit"
+    plan: Dict[str, Any] = {"primary": primary, "primaryNote": f"Review covering {plain(target['name'], 120)}'s last commit ({head}).", "fallback": None, "fallbackNote": ""}
+    latest = target.get("latest")
+    if latest and isinstance(latest.get("id"), str) and RESULT_ID.match(latest["id"]):
+        plan["fallback"] = ["codewatch", "report", "--repo", repo, "--id", latest["id"], "--format", "html", "--output", output]
+        commit = plain(latest.get("commit"), 40)[:12] if latest.get("commit") else "(unknown)"
+        plan["fallbackNote"] = (f"No review in {plain(target['name'], 120)} covers {head}. Showing the latest review instead: "
+                                f"branch {plain(latest.get('branch') or '(unknown)', 80)}, commit {commit}.")
+    return plan
+
+
+_META_REFRESH = re.compile(r"<meta\b[^>]*http-equiv\s*=\s*[\"']?\s*refresh[^>]*>", re.I)
+
+
+def with_report_csp(html: str) -> str:
+    """The report with a CSP meta tag (its inline styles only, no script, nothing remote) and no
+    meta refresh, which a CSP does not stop from navigating the frame."""
+    html = _META_REFRESH.sub("", html)
+    meta = f'<meta http-equiv="Content-Security-Policy" content="{REPORT_CSP}">'
+    m = re.search(r"<head(?:\s[^>]*)?>", html, re.I)  # not <header>
+    if m:
+        return html[: m.end()] + meta + html[m.end():]
+    return f"<!DOCTYPE html><html><head>{meta}</head><body>{html}</body></html>"
+
+
+def cleanup_reports(report_dir: Path, now: Optional[float] = None, max_age: int = REPORT_MAX_AGE_S) -> int:
+    """Delete this app's report files older than max_age. Only *.html directly in report_dir; links are left alone."""
+    now = time.time() if now is None else now
+    removed = 0
+    try:
+        entries = list(os.scandir(report_dir))
+    except OSError:
+        return 0
+    for e in entries:
+        try:
+            if e.name.endswith(".html") and e.is_file(follow_symlinks=False) and now - e.stat(follow_symlinks=False).st_mtime > max_age:
+                os.unlink(e.path)
+                removed += 1
+        except OSError:
+            continue
+    return removed
+
+
+# ---- digest ----------------------------------------------------------------
+
+def read_digest(data_dir: Path) -> Optional[Dict[str, Any]]:
+    """The digest cron's saved state (digest-state.json), or None when missing or unreadable."""
+    try:
+        d = json.loads((data_dir / "digest-state.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    return d if isinstance(d, dict) else None
+
+
+def digest_view(d: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """Raw digest fields; the page turns them into 'Not run yet' / 'Last run 3 h ago · ...'."""
+    if not d:
+        return {"recorded": False, "lastRunAt": "", "lastNotifiedAt": "", "lastMessage": ""}
+    return {
+        "recorded": True,
+        "lastRunAt": plain(d.get("lastRunAt") or "", 40),
+        "lastNotifiedAt": plain(d.get("lastNotifiedAt") or "", 40),
+        "lastMessage": plain(d.get("lastMessage") or "", 1500, one_line=False),
+    }