@prism-d1/cli 1.9.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

@@ -1,4 +1,4 @@
-# PRISM app for Kiro Crew (v0.2)
+# 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:
@@ -50,14 +50,13 @@ With prism-cli 1.9.0 or later, which bundles this app:
 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.
+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):
 
@@ -129,6 +128,10 @@ is kept across app updates unless a later version of the app changes the schedul
 
 ## 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

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

@@ -1,12 +1,14 @@
 {
   "name": "prism",
-  "version": "0.2.2",
+  "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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prism-d1/cli",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "description": "PRISM D1 Velocity CLI — AI development lifecycle assessment tool",
   "author": "andklee",
   "engines": {
@@ -24,6 +24,8 @@
   "scripts": {
     "build": "npx tsc && rm -rf dist/assets && mkdir -p dist/assets/infra dist/assets/coding-agent && cp -r ../bootstrapper/metric-hooks ../bootstrapper/eval-harness ../bootstrapper/github-workflows ../bootstrapper/gitlab-workflows dist/assets/ && cp -r ../infra/bin ../infra/lib ../infra/package.json ../infra/tsconfig.json ../infra/cdk.json dist/assets/infra/ && cp -r ../coding-agent/agent.py ../coding-agent/config.py ../coding-agent/system_prompt.py ../coding-agent/requirements.txt ../coding-agent/pyproject.toml ../coding-agent/README.md ../coding-agent/tools ../coding-agent/eval ../coding-agent/deploy dist/assets/coding-agent/ && mkdir -p dist/assets/coding-agent/fixtures && cp ../sample-app/.coding-agent/fixtures/*.json dist/assets/coding-agent/fixtures/ && find dist/assets/coding-agent -name __pycache__ -type d -prune -exec rm -rf {} + && cp -r src/commands/security/pentest-cdk dist/assets/pentest-cdk && cp -r ../kirocrew-app dist/assets/kirocrew-app && rm -rf dist/assets/kirocrew-app/tests dist/assets/kirocrew-app/data && find dist/assets/kirocrew-app \\( -name __pycache__ -o -name .pytest_cache \\) -type d -prune -exec rm -rf {} +",
     "test": "tsc -p tsconfig.test.json && node --import tsx --test test/*.test.ts",
+    "docs": "npm run build && node scripts/gen-cli-reference.mjs",
+    "docs:check": "node scripts/check-docs.mjs",
     "prepublishOnly": "npm run build",
     "start": "tsx bin/prism-cli.ts",
     "dev": "tsx bin/prism-cli.ts"