@kaptures/cli 0.0.1 → 0.0.2

package/README.md

@@ -7,44 +7,82 @@ and can publish a SHA-bound review status to GitHub.
 Node.js 24 or later is required.
 
 ```bash
-npx -y @kaptures/cli@0.0.1 --help
-npx -y @kaptures/cli@0.0.1 browser install
+npx -y @kaptures/cli@0.0.2 --help
+npx -y @kaptures/cli@0.0.2 browser install
 ```
 
 ## Compare Storybooks
 
 ```bash
-npx -y @kaptures/cli@0.0.1 test \
+npx -y @kaptures/cli@0.0.2 test \
   --base-dir .kapture/storybook/base \
   --head-dir .kapture/storybook/head \
   --base-revision "$BASE_SHA" \
   --head-revision "$HEAD_SHA" \
   --output .kapture
 
-npx -y @kaptures/cli@0.0.1 validate \
+npx -y @kaptures/cli@0.0.2 validate \
   --report .kapture/report/report.json
 ```
 
 Visual changes are a review result, not an execution failure. Capture and
 comparison errors exit with code 2.
 
+## Optional hosted report
+
+Kapture does not require a report deployment. The generated `index.html`
+remains self-contained and can be opened through a `file://` URL after the
+artifact is downloaded. To publish a browser URL from a privileged workflow,
+rebuild the untrusted artifact with the dashboard embedded in the pinned CLI:
+
+```bash
+npx -y @kaptures/cli@0.0.2 report build \
+  --input downloaded-kapture-report \
+  --output trusted-kapture-report
+```
+
+Deploy only `trusted-kapture-report/` with the repository's existing static
+hosting. The builder validates the strict report schema and referenced PNGs,
+and never executes or copies artifact HTML, JavaScript, CSS, fonts, symlinks,
+or unreferenced files.
+
 ## GitHub
 
-Use the three-workflow example in the repository: an unprivileged
-`pull_request` workflow captures the report, a trusted `workflow_run` validates
-that JSON and updates the PR, and an `issue_comment` workflow handles
-`/kapture approve <full-head-sha>` without checking out PR code.
+Use isolated jobs in the default branch's `workflow_run`. The base and head
+jobs may run repository code, but must have no write permission or secrets.
+The capture job does not check out the PR or run repository scripts; it runs
+the pinned CLI against the two static Storybook builds without write
+permission or secrets. Storybook JavaScript is evaluated only inside that
+unprivileged browser boundary.
+
+Before using deployment credentials, the report job performs a read-only
+preflight. It must not check out PR code or execute artifact code. It rebuilds
+the hosted report from strict JSON and validated PNGs with the pinned CLI, then
+updates the PR. The `issue_comment` workflow similarly handles
+`/kapture approve <full-head-sha> <report-digest>` without checking out PR
+code.
 
 ```bash
-npx -y @kaptures/cli@0.0.1 github report \
-  --report .kapture/report/report.json \
+npx -y @kaptures/cli@0.0.2 github verify \
+  --report .kapture/report/report.json
+
+npx -y @kaptures/cli@0.0.2 github report \
+  --report trusted-kapture-report/report.json \
   --report-url "https://github.com/OWNER/REPO/actions/runs/RUN_ID"
 
-npx -y @kaptures/cli@0.0.1 github approve
+npx -y @kaptures/cli@0.0.2 github approve
 ```
 
 GitHub commands read authentication and event data only from `GITHUB_TOKEN`
 and `GITHUB_EVENT_PATH`. Do not pass tokens as command-line arguments.
+`github verify` validates the strict report and its full base/head SHAs against
+the current pull request without writing a status or comment. Run it before
+deployment. A privileged report job must pass the output of `report build`;
+`github report` requires its image-bound `report.json` before writing. Approval
+markers bind the base SHA, head SHA, full report
+structure, and the actual bytes of every referenced PNG. The approval command
+must contain that exact report digest, so a base-branch update, new head commit,
+or changed report image requires a new comparison.
 
 ## License