@prism-d1/cli 1.8.0 → 1.9.1

package/README.md

@@ -0,0 +1,48 @@
+# prism-cli
+
+The command line for [PRISM D1 Velocity](https://github.com/aws-samples/sample-prism-d1-velocity): measure, secure and review AI-assisted development from your own machine. Codewatch git hooks, a local dashboard, an MCP server for AI agents, AWS Security Agent scans, read-only AWS account checks, and the setup helpers for a team's PRISM deployment.
+
+> Sample project, not production-ready. See [SECURITY.md](https://github.com/aws-samples/sample-prism-d1-velocity/blob/main/SECURITY.md).
+
+## Install
+
+Node.js 22 or later:
+
+```bash
+npm install -g @prism-d1/cli
+prism-cli version     # installed version, newer release on npm, other copies on PATH
+```
+
+## Quick start
+
+```bash
+prism-cli enable codewatch    # in a repo: secret scan on commit, AI review on push (report only)
+prism-cli dashboard           # local page on 127.0.0.1: results, AI usage, setup checklist
+prism-cli aws check           # read-only AWS account checks; then prism-cli aws recommend
+```
+
+Send AI usage to your team's PRISM with `prism-cli enable codeburn --url <OtelCollectorUrl>` (the URL comes from your platform team). Every command takes `--help`.
+
+## Documentation
+
+- [Using PRISM locally](https://github.com/aws-samples/sample-prism-d1-velocity/blob/main/USER_GUIDE.md#using-prism-locally): what each feature does and where it shows up (VS Code family editors, Kiro Crew, Claude Code)
+- [Command reference](https://github.com/aws-samples/sample-prism-d1-velocity/blob/main/docs/CLI-REFERENCE.md): every command and flag
+- [prism-cli Overview](https://github.com/aws-samples/sample-prism-d1-velocity/blob/main/docs/PRISM-CLI-OVERVIEW.md): what each command touches in AWS, its cost and its safety defaults
+- [User Guide](https://github.com/aws-samples/sample-prism-d1-velocity/blob/main/USER_GUIDE.md): deploying PRISM, CI workflows and eval gates
+
+## Develop
+
+From `cli/` in a clone:
+
+```bash
+npm ci
+npm run build       # tsc -> dist/, plus the bundled assets
+npm test            # type-checks the tests, then the node:test suite
+npm run docs        # regenerate docs/CLI-REFERENCE.md after changing a command or flag
+```
+
+Releases are published to npm by `.github/workflows/publish.yml` when a `v*` tag is pushed.
+
+## License
+
+MIT

package/dist/assets/github-workflows/prism-eval-gate-kiro.yml

@@ -282,49 +282,85 @@ jobs:
           # on long content. Use a minimal CLI arg prompt and let kiro read files itself.
           git diff "${BASE_SHA}..${HEAD_SHA}" -- ${FILES} > /tmp/pr-diff.patch
 
-          REVIEW_OUTPUT=$(kiro-cli chat --no-interactive \
-            --trust-all-tools \
-            --model auto \
-            "Review /tmp/pr-diff.patch for code quality. Read it, then output ONLY JSON: {\"findings\":[{\"file\":\"path\",\"line\":1,\"severity\":\"high|medium|low\",\"category\":\"str\",\"message\":\"str\"}],\"score\":0.0,\"summary\":\"str\"}") || true
-
-          # Strip ANSI escapes, then extract the LAST JSON object that parses and
-          # has a numeric score and a findings array. kiro-cli writes reasoning
-          # notes first, and they quote code with braces, so a greedy
-          # first-brace-to-last-brace match is not the verdict.
-          CLEANED=$(echo "${REVIEW_OUTPUT}" | sed 's/\x1b\[[0-9;?]*[a-zA-Z]//g' | tr -d '\r')
-          REVIEW_JSON=$(printf '%s' "${CLEANED}" | python3 -c 'if True:
-              import json, math, sys
-              text = sys.stdin.read()
-              dec = json.JSONDecoder(strict=False)
-              pos = text.rfind("{")
-              while pos != -1:
-                  try:
-                      obj = dec.raw_decode(text, pos)[0]
-                  except ValueError:
-                      obj = None
-                  score = obj.get("score") if isinstance(obj, dict) else None
-                  if (isinstance(score, (int, float)) and not isinstance(score, bool)
-                          and math.isfinite(score) and isinstance(obj.get("findings"), list)):
-                      print(json.dumps(obj))
-                      sys.exit(0)
-                  pos = text.rfind("{", 0, pos)
-              sys.exit(1)
-          ' || true)
-
-          if [ -z "${REVIEW_JSON}" ] || ! echo "${REVIEW_JSON}" | jq -e '.score' > /dev/null 2>&1; then
-            # FAIL CLOSED: a gate that can't evaluate must not pass
-            echo "::group::Debug: raw kiro-cli output (first 2000 chars)"
+          # One retry, only when the reply cannot be parsed. Attempt 2 re-runs the
+          # same review (same model, same diff file) with one sentence added that
+          # asks for a single JSON object. It does not hand the bad reply back
+          # for "repair": a broken reply is often truncated, and repairing it
+          # would make the model invent the missing findings. Each attempt reads
+          # the diff, so any accepted verdict comes from a real review. Nothing
+          # is repaired by regex; two unparseable replies still fail closed.
+          REVIEW_PROMPT="Review /tmp/pr-diff.patch for code quality. Read it, then output ONLY JSON: {\"findings\":[{\"file\":\"path\",\"line\":1,\"severity\":\"high|medium|low\",\"category\":\"str\",\"message\":\"str\"}],\"score\":0.0,\"summary\":\"str\"}"
+          RETRY_NOTE="Your previous reply was not valid JSON. Return exactly one JSON object matching that schema and nothing else: no prose, no code fences."
+          # Per-attempt cap. The retry gets the same budget as the first attempt.
+          REVIEW_TIMEOUT_SECS=600
+          REVIEW_JSON=""
+          REVIEW_ATTEMPT=""
+          for ATTEMPT in 1 2; do
+            PROMPT="${REVIEW_PROMPT}"
+            if [ "${ATTEMPT}" = "2" ]; then PROMPT="${REVIEW_PROMPT} ${RETRY_NOTE}"; fi
+            REVIEW_OUTPUT=$(timeout "${REVIEW_TIMEOUT_SECS}" kiro-cli chat --no-interactive \
+              --trust-all-tools \
+              --model auto \
+              "${PROMPT}") || true
+
+            # Strip ANSI escapes, then extract the LAST JSON object that parses and
+            # has a numeric score and a findings array. kiro-cli writes reasoning
+            # notes first, and they quote code with braces, so a greedy
+            # first-brace-to-last-brace match is not the verdict. Same rule as
+            # extractReviewJson in cli/src/codewatch/reviewers/types.ts; the copy
+            # in each eval-gate workflow is kept identical by cli/test/eval-gate-extract.test.ts.
+            CLEANED=$(echo "${REVIEW_OUTPUT}" | sed 's/\x1b\[[0-9;?]*[a-zA-Z]//g' | tr -d '\r')
+            REVIEW_JSON=$(printf '%s' "${CLEANED}" | python3 -c 'if True:
+                import json, math, sys
+                text = sys.stdin.read()
+                dec = json.JSONDecoder(strict=False)
+                pos = text.rfind("{")
+                while pos != -1:
+                    try:
+                        obj = dec.raw_decode(text, pos)[0]
+                    except ValueError:
+                        obj = None
+                    score = obj.get("score") if isinstance(obj, dict) else None
+                    if (isinstance(score, (int, float)) and not isinstance(score, bool)
+                            and math.isfinite(score) and isinstance(obj.get("findings"), list)):
+                        print(json.dumps(obj))
+                        sys.exit(0)
+                    pos = text.rfind("{", 0, pos)
+                sys.exit(1)
+            ' || true)
+
+            if [ -n "${REVIEW_JSON}" ] && echo "${REVIEW_JSON}" | jq -e '.score' > /dev/null 2>&1; then
+              REVIEW_ATTEMPT="${ATTEMPT}"
+              break
+            fi
+            REVIEW_JSON=""
+
+            # The reply is untrusted model output. Workflow commands are paused
+            # while it is printed, so a "::" line in it is shown, not executed.
+            STOP_TOKEN=$(od -An -N16 -tx1 /dev/urandom | tr -d ' \n')
+            echo "::group::Debug: attempt ${ATTEMPT} raw kiro-cli output (first 2000 chars)"
+            echo "::stop-commands::${STOP_TOKEN}"
             echo "${REVIEW_OUTPUT:-<empty>}" | head -c 2000
             echo ""
-            echo "::endgroup::"
-            echo "::group::Debug: cleaned output"
+            echo "--- cleaned ---"
             echo "${CLEANED:-<empty>}" | head -c 2000
             echo ""
+            echo "::${STOP_TOKEN}::"
             echo "::endgroup::"
-            echo "::error::Could not parse kiro-cli review output -- failing closed"
+            if [ "${ATTEMPT}" = "1" ]; then
+              echo "::warning::Attempt 1: could not parse kiro-cli review output -- retrying the review once"
+            fi
+          done
+
+          if [ -z "${REVIEW_JSON}" ]; then
+            # FAIL CLOSED: a gate that can't evaluate must not pass
+            echo "::error::Could not parse kiro-cli review output on either attempt (both unparseable) -- failing closed"
             echo "result=ERROR" >> "$GITHUB_OUTPUT"
+            echo "Eval gate review: both attempts returned unparseable output -- failed closed." >> "$GITHUB_STEP_SUMMARY"
             exit 0
           fi
+          echo "Review verdict parsed on attempt ${REVIEW_ATTEMPT} of 2"
+          echo "attempt=${REVIEW_ATTEMPT}" >> "$GITHUB_OUTPUT"
 
           SCORE=$(echo "${REVIEW_JSON}" | jq -r '.score')
           FINDINGS=$(echo "${REVIEW_JSON}" | jq '.findings | length')
@@ -343,10 +379,13 @@ jobs:
           # Determine pass/fail (awk instead of bc -- no extra package needed)
           PASS=$(awk -v s="${SCORE}" 'BEGIN { print (s >= 0.82) ? "true" : "false" }')
           if [ "${HIGH}" -gt 0 ] || [ "${PASS}" != "true" ]; then
-            echo "result=FAIL" >> "$GITHUB_OUTPUT"
+            RESULT=FAIL
           else
-            echo "result=PASS" >> "$GITHUB_OUTPUT"
+            RESULT=PASS
           fi
+          echo "result=${RESULT}" >> "$GITHUB_OUTPUT"
+          # Only numbers and fixed words here; no model text reaches the summary.
+          echo "Eval gate review: ${RESULT} (score ${SCORE}, ${HIGH} high), verdict parsed on attempt ${REVIEW_ATTEMPT} of 2." >> "$GITHUB_STEP_SUMMARY"
 
       - name: Post PR comment
         if: always()
@@ -372,7 +411,7 @@ jobs:
             if (result === 'SKIPPED') {
               body = '⚠️ **PRISM Eval Gate** -- Review skipped (no source files changed or no API key on fork PRs).';
             } else if (result === 'ERROR') {
-              body = '❌ **PRISM Eval Gate** -- Review output could not be parsed. Failing closed; re-run the workflow or review manually.';
+              body = '❌ **PRISM Eval Gate** -- Review output could not be parsed on either attempt (the review is retried once). Failing closed; re-run the workflow or review manually.';
             } else {
                 const score = process.env.REVIEW_SCORE || '?';
                 const findings = process.env.REVIEW_FINDINGS || '0';

package/dist/assets/gitlab-workflows/prism-eval-gate.yml

@@ -217,41 +217,67 @@ prism-eval-gate:
             # into HTTP headers, so let it read the patch off disk itself.
             git diff "${BASE_SHA}..${HEAD_SHA}" -- ${FILES} > /tmp/mr-diff.patch
 
-            set +e
-            REVIEW_OUTPUT=$(kiro-cli chat --no-interactive --trust-all-tools --model auto \
-              "Review /tmp/mr-diff.patch for code quality. Read it, then output ONLY JSON: {\"findings\":[{\"file\":\"path\",\"line\":1,\"severity\":\"high|medium|low\",\"category\":\"str\",\"message\":\"str\"}],\"score\":0.0,\"summary\":\"str\"}")
-            set -e
+            # One retry, only when the reply cannot be parsed. Attempt 2 re-runs
+            # the same review (same model, same diff file) with one sentence
+            # added that asks for a single JSON object. It does not hand the bad
+            # reply back for "repair": a broken reply is often truncated, and
+            # repairing it would make the model invent the missing findings.
+            # Nothing is repaired by regex; two unparseable replies fail closed.
+            REVIEW_PROMPT="Review /tmp/mr-diff.patch for code quality. Read it, then output ONLY JSON: {\"findings\":[{\"file\":\"path\",\"line\":1,\"severity\":\"high|medium|low\",\"category\":\"str\",\"message\":\"str\"}],\"score\":0.0,\"summary\":\"str\"}"
+            RETRY_NOTE="Your previous reply was not valid JSON. Return exactly one JSON object matching that schema and nothing else: no prose, no code fences."
+            # Per-attempt cap. The retry gets the same budget as the first attempt.
+            REVIEW_TIMEOUT_SECS=600
+            REVIEW_JSON=""
+            REVIEW_ATTEMPT=""
+            for ATTEMPT in 1 2; do
+              PROMPT="${REVIEW_PROMPT}"
+              if [ "${ATTEMPT}" = "2" ]; then PROMPT="${REVIEW_PROMPT} ${RETRY_NOTE}"; fi
+              set +e
+              REVIEW_OUTPUT=$(timeout "${REVIEW_TIMEOUT_SECS}" kiro-cli chat --no-interactive --trust-all-tools --model auto "${PROMPT}")
+              set -e
 
-            # Extract the LAST JSON object that parses and has a numeric score
-            # and a findings array. kiro-cli writes reasoning notes first, and
-            # they quote code with braces, so a greedy first-brace-to-last-brace
-            # match is not the verdict.
-            CLEANED=$(printf '%s' "${REVIEW_OUTPUT}" | sed 's/\x1b\[[0-9;?]*[a-zA-Z]//g' | tr -d '\r')
-            REVIEW_JSON=$(printf '%s' "${CLEANED}" | python3 -c 'if True:
-                import json, math, sys
-                text = sys.stdin.read()
-                dec = json.JSONDecoder(strict=False)
-                pos = text.rfind("{")
-                while pos != -1:
-                    try:
-                        obj = dec.raw_decode(text, pos)[0]
-                    except ValueError:
-                        obj = None
-                    score = obj.get("score") if isinstance(obj, dict) else None
-                    if (isinstance(score, (int, float)) and not isinstance(score, bool)
-                            and math.isfinite(score) and isinstance(obj.get("findings"), list)):
-                        print(json.dumps(obj))
-                        sys.exit(0)
-                    pos = text.rfind("{", 0, pos)
-                sys.exit(1)
-            ' || true)
+              # Extract the LAST JSON object that parses and has a numeric score
+              # and a findings array. kiro-cli writes reasoning notes first, and
+              # they quote code with braces, so a greedy first-brace-to-last-brace
+              # match is not the verdict.
+              CLEANED=$(printf '%s' "${REVIEW_OUTPUT}" | sed 's/\x1b\[[0-9;?]*[a-zA-Z]//g' | tr -d '\r')
+              REVIEW_JSON=$(printf '%s' "${CLEANED}" | python3 -c 'if True:
+                  import json, math, sys
+                  text = sys.stdin.read()
+                  dec = json.JSONDecoder(strict=False)
+                  pos = text.rfind("{")
+                  while pos != -1:
+                      try:
+                          obj = dec.raw_decode(text, pos)[0]
+                      except ValueError:
+                          obj = None
+                      score = obj.get("score") if isinstance(obj, dict) else None
+                      if (isinstance(score, (int, float)) and not isinstance(score, bool)
+                              and math.isfinite(score) and isinstance(obj.get("findings"), list)):
+                          print(json.dumps(obj))
+                          sys.exit(0)
+                      pos = text.rfind("{", 0, pos)
+                  sys.exit(1)
+              ' || true)
 
-            if [ -z "${REVIEW_JSON}" ] || ! printf '%s' "${REVIEW_JSON}" | jq -e '.score' >/dev/null 2>&1; then
-              echo "❌ Could not parse kiro-cli review output — failing closed."
+              if [ -n "${REVIEW_JSON}" ] && printf '%s' "${REVIEW_JSON}" | jq -e '.score' >/dev/null 2>&1; then
+                REVIEW_ATTEMPT="${ATTEMPT}"
+                break
+              fi
+              REVIEW_JSON=""
+              echo "⚠  Attempt ${ATTEMPT}: could not parse kiro-cli review output. Raw output (first 2000 chars):"
               printf '%s' "${REVIEW_OUTPUT:-<empty>}" | head -c 2000
               echo ""
+              if [ "${ATTEMPT}" = "1" ]; then
+                echo "Retrying the review once."
+              fi
+            done
+
+            if [ -z "${REVIEW_JSON}" ]; then
+              echo "❌ Could not parse kiro-cli review output on either attempt (both unparseable) — failing closed."
               REVIEW_RESULT="ERROR"
             else
+              echo "Review verdict parsed on attempt ${REVIEW_ATTEMPT} of 2."
               printf '%s' "${REVIEW_JSON}" > /tmp/kiro-review.json
               REVIEW_SCORE=$(jq -r '.score' /tmp/kiro-review.json)
               REVIEW_HIGH=$(jq '[.findings[] | select(.severity=="high")] | length' /tmp/kiro-review.json)

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

@@ -0,0 +1,234 @@
+# PRISM app for Kiro Crew
+
+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
+```
+
+What the command does, its `--status`, `--dry-run` and `--uninstall` options and the two steps
+that stay with you (trust the app, approve its API routes) are in the User Guide's
+[Kiro Crew app](../USER_GUIDE.md#kiro-crew-app) section; every flag is in the
+[command reference](../docs/CLI-REFERENCE.md#prism-cli-enable-kirocrew). It updates an app that
+was installed from another folder, such as a clone, too. It never installs Kiro Crew.
+
+### Install from a folder
+
+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
+
+![PRISM page in Kiro Crew with demo data: spend cards, top models and projects, four repos with codewatch, one expanded with its findings](../assets/images/prism-cli/kirocrew-app-page-light.png)
+
+*The PRISM page, rendered with made-up demo data.*
+
+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,96 @@
+{
+  "name": "prism",
+  "version": "0.2.3",
+  "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",
+  "screenshots": ["assets/screenshots/page-light.png", "assets/screenshots/report-light.png"],
+  "screenshotsDark": ["assets/screenshots/page-dark.png", "assets/screenshots/report-dark.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."
+        }
+      }
+    }
+  }
+}