@kaptures/cli 0.0.2 → 0.0.4

package/README.md

@@ -4,30 +4,36 @@ 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.2 --help
-npx -y @kaptures/cli@0.0.2 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.2 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.2 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`
@@ -36,7 +42,7 @@ 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 \
+npx -y @kaptures/cli@0.0.4 report build \
   --input downloaded-kapture-report \
   --output trusted-kapture-report
 ```
@@ -48,41 +54,62 @@ or unreferenced files.
 
 ## GitHub
 
-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
+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.2 github verify \
+npx -y @kaptures/cli@0.0.4 github verify \
   --report .kapture/report/report.json
 
-npx -y @kaptures/cli@0.0.2 github report \
+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"
+  --report-url "https://github.com/OWNER/REPO/actions/runs/RUN_ID/artifacts/ARTIFACT_ID"
 
-npx -y @kaptures/cli@0.0.2 github approve
+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. 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.
+`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