@kaptures/cli 0.0.1 → 0.0.4

package/README.md

@@ -4,47 +4,112 @@ Kapture compares Storybook builds from an exact base commit and head commit in
 one explicit browser environment. It produces a self-contained visual report
 and can publish a SHA-bound review status to GitHub.
 
-Node.js 24 or later is required.
+Node.js 24 or later is required. Both Storybook builds must register the
+matching `@kaptures/storybook@0.0.4` preview adapter. Kapture does not fall back
+to Storybook private globals, legacy decorators, or Chromatic parameters.
 
 ```bash
-npx -y @kaptures/cli@0.0.1 --help
-npx -y @kaptures/cli@0.0.1 browser install
+npx -y @kaptures/cli@0.0.4 --help
+npx -y @kaptures/cli@0.0.4 browser install
 ```
 
 ## Compare Storybooks
 
 ```bash
-npx -y @kaptures/cli@0.0.1 test \
+npx -y @kaptures/cli@0.0.4 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.4 validate \
   --report .kapture/report/report.json
 ```
 
 Visual changes are a review result, not an execution failure. Capture and
 comparison errors exit with code 2.
 
+The default browser locale and time zone are `en-US` and `UTC`. Override them
+explicitly with `--locale <bcp47>` and `--timezone <iana-zone>` when the
+consumer Storybook requires another environment.
+
+## 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.4 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.
+Run every checkout, repository script, Storybook build, and browser capture in
+the read-only `pull_request` workflow without secrets. Pass only an immutable
+context artifact plus `report.json` and its referenced PNGs to the default
+branch's `workflow_run`; intermediate Storybook artifacts stay inside the
+read-only run.
+
+The `workflow_run` resolves exact artifact IDs from the triggering run and
+cross-checks their provenance, bounded archive size, full base/head SHAs, and
+current open pull request. The actual PR head SHA comes from the immutable
+context and live pull request; `workflow_run.head_sha` may be a synthetic merge
+commit and is not treated as the PR head. SHA-pinned `download-artifact@v8`
+fails closed on an archive digest mismatch, then validates entry paths and
+uncompressed limits before extraction. A job without write permission runs
+`github verify` and rebuilds the report from strict JSON and validated PNGs
+with the pinned CLI. A separate write job publishes only that trusted output.
+Neither job checks out PR code or executes artifact code. 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 \
-  --report-url "https://github.com/OWNER/REPO/actions/runs/RUN_ID"
+npx -y @kaptures/cli@0.0.4 github verify \
+  --report .kapture/report/report.json
 
-npx -y @kaptures/cli@0.0.1 github approve
+npx -y @kaptures/cli@0.0.4 github report \
+  --report trusted-kapture-report/report.json \
+  --report-url "https://github.com/OWNER/REPO/actions/runs/RUN_ID/artifacts/ARTIFACT_ID"
+
+npx -y @kaptures/cli@0.0.4 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` and `github report` require the normalized
+`kapture.schemaVersion: 1` event created by the trusted example workflow; do
+not pass GitHub's raw `workflow_run` payload because its `head_sha` may be a
+synthetic merge commit. `github approve` consumes the raw `issue_comment`
+event.
+`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. Version
+3 approval markers bind the base SHA, head SHA, full report structure, actual
+bytes of every referenced PNG, capture run ID and attempt, workflow ID, head
+repository ID, head branch, and report URL. Approval rechecks that marker's run
+is the latest successful capture run for the same PR head repository and branch.
+The current status for the PR head must also be the final approval-ready
+`pending` in the selected context and target the same report URL. The transient
+publishing status is not approvable. Therefore, a base-branch update, new head
+commit, changed report image, or failed rerun at the same SHA prevents an old
+marker and digest from restoring success.
+
+The default status context is `Kapture Visual Review`, and report and approval
+comments default to English. Consumers can set `--status-context <name>` and
+`--comment-language en|ko` on both `github report` and `github approve` without
+changing the verification boundary.
 
 ## License