@kaptures/cli 0.12.1 → 0.14.0

package/README.md

@@ -5,12 +5,13 @@ 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. Both Storybook builds must register the
-matching `@kaptures/storybook@0.2.0` preview adapter. Kapture does not fall back
+compatible `@kaptures/storybook` preview adapter. Kapture does not fall back
 to Storybook private globals, legacy decorators, or Chromatic parameters.
 
 ```bash
-npx -y @kaptures/cli@0.5.0 --help
-npx -y @kaptures/cli@0.5.0 browser install
+npm install --save-dev --save-exact @kaptures/cli @kaptures/storybook
+npm exec -- kapture --help
+npm exec -- kapture browser install
 ```
 
 ## Compare Storybooks
@@ -19,20 +20,19 @@ npx -y @kaptures/cli@0.5.0 browser install
 
 For a PR whose exact base manifest does not yet declare the adapter, generate
 workflows with `kapture ci --package-manager <npm|yarn|pnpm|bun>
---adapter-package-json <path> --allow-initial-adoption`. The exact head adapter
-must match the CLI version. Malformed manifests and version mismatches remain
+--adapter-package-json <path> --allow-initial-adoption`. The head must declare an adapter; capture validates its protocol and capture contract. Malformed manifests and incompatible capture contracts remain
 errors. Initial adoption needs no hosting hook, deployment credentials or status/comment write permissions.
 
 This mode uses `setup capture` to save PNGs and a separate `setup.json` artifact,
 and writes a bounded GitHub Job Summary with **Comparison not performed**.
 It does not publish a dashboard, PR comment, commit status or approval marker.
-Inspect each run's Summary and artifact for its result; capture errors fail the job. Once the base includes the matching adapter,
+Inspect each run's Summary and artifact for its result; capture errors fail the job. Once the base includes a compatible adapter,
 the same workflow automatically takes the normal comparison path.
 
 ### Normal comparison
 
 ```bash
-npx -y @kaptures/cli@0.5.0 test \
+npm exec -- kapture test \
   --base-dir .kapture/storybook/base \
   --head-dir .kapture/storybook/head \
   --base-revision "$BASE_SHA" \
@@ -41,7 +41,7 @@ npx -y @kaptures/cli@0.5.0 test \
   --install-browser \
   --output .kapture
 
-npx -y @kaptures/cli@0.5.0 validate \
+npm exec -- kapture validate \
   --report .kapture/report/report.json
 ```
 
@@ -105,7 +105,7 @@ of project-relative Git diff paths to select only stories whose base or head
 dependency graph is affected:
 
 ```bash
-npx -y @kaptures/cli@0.5.0 plan \
+npm exec -- kapture plan \
   --base-dir .kapture/storybook/base \
   --head-dir .kapture/storybook/head \
   --changed-files .kapture/changed-files.json \
@@ -126,7 +126,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.5.0 report build \
+npm exec -- kapture report build \
   --input downloaded-kapture-report \
   --output trusted-kapture-report
 ```
@@ -182,46 +182,46 @@ The raw branch ref remains report metadata; a separate collision-resistant
 `preview-alias` is used only where a DNS-safe hosting branch is required.
 
 ```bash
-npx -y @kaptures/cli@0.5.0 github reconcile-run \
+npm exec -- kapture github reconcile-run \
   --capture-workflow-path .github/workflows/visual-capture.yml \
   --base-branch main \
   --status-context "Kapture Visual Review"
 
-npx -y @kaptures/cli@0.5.0 github prepare-run \
+npm exec -- kapture github prepare-run \
   --capture-workflow-path .github/workflows/visual-capture.yml \
   --base-branch main \
   --output "$RUNNER_TEMP/kapture-trusted/report" \
   --receipt "$RUNNER_TEMP/kapture-trusted/receipt.json" \
   --storybook-url ./storybook/
 
-npx -y @kaptures/cli@0.5.0 github prepare-storybook-run \
+npm exec -- kapture github prepare-storybook-run \
   --capture-workflow-path .github/workflows/visual-capture.yml \
   --base-branch main \
   --receipt "$RUNNER_TEMP/kapture-trusted/receipt.json" \
   --output "$RUNNER_TEMP/kapture-trusted/report/storybook"
 
-npx -y @kaptures/cli@0.5.0 github publish-run \
+npm exec -- kapture github publish-run \
   --receipt "$RUNNER_TEMP/kapture-trusted/receipt.json" \
   --report "$RUNNER_TEMP/kapture-trusted/report/report.json" \
   --report-url "https://reports.example.com/builds/1a2b3c4d/" \
   --status-context "Kapture Visual Review"
 
-npx -y @kaptures/cli@0.5.0 github cleanup \
+npm exec -- kapture github cleanup \
   --receipt "$RUNNER_TEMP/kapture-trusted/receipt.json"
 
-npx -y @kaptures/cli@0.5.0 github finalize-run \
+npm exec -- kapture github finalize-run \
   --capture-workflow-path .github/workflows/visual-capture.yml \
   --base-branch main \
   --status-context "Kapture Visual Review"
 
-npx -y @kaptures/cli@0.5.0 github verify \
+npm exec -- kapture github verify \
   --report .kapture/report/report.json
 
-npx -y @kaptures/cli@0.5.0 github report \
+npm exec -- kapture github report \
   --report trusted-kapture-report/report.json \
   --report-url "https://reports.example.com/builds/1a2b3c4d/"
 
-npx -y @kaptures/cli@0.5.0 github approve
+npm exec -- kapture github approve
 ```
 
 GitHub commands read authentication and event data only from `GITHUB_TOKEN`
@@ -260,3 +260,10 @@ the verification boundary.
 ## License
 
 MIT © Danggeun Market Inc.
+
+
+For adapter upgrades, opt into `--allow-adapter-upgrade --adapter-package-json <path>` on `github context`, `github prepare-review`, and `github finalize-run` (or `ci` to generate all three). An exact stable base version strictly older than the head is eligible only when the head adapter matches the running CLI. Same-repository upgrades skip comparison; completed successful runs get the status description `Comparison skipped: adapter upgrade`. This is not visual validation or approval: review all visual changes manually and compare again after merge. Failed runs and invalid, ranged, prerelease, downgraded or mismatched versions remain errors. Trusted handlers revalidate live revisions and the latest run before writing status. Update the default-branch report/finalize workflow as well; older CLI releases cannot apply this policy.
+
+Only explicit comparison skipping requires the head adapter version to match the capture CLI. The trusted report CLI may still be the older default-branch version, so it verifies the live upgrade and successful capture run rather than requiring the head adapter to match itself.
+
+Normal comparison accepts different adapter package versions with supported wire and capture contracts. Both original builds run under the same CLI and browser. Capture engine/contract changes invalidate cached evidence; actual adapter versions are retained in capture manifests.