@runveric/cli 0.5.1 → 0.6.0

package/README.md

@@ -4,7 +4,7 @@
 production runner image — without pushing anything or signing in.**
 
 ```sh
-npx @runveric/cli@0.5.1 init --id yourteam/restart-web-tier
+npx @runveric/cli@0.6.0 init --id yourteam/restart-web-tier
 ```
 
 ---
@@ -40,7 +40,7 @@ script outside the platform. Nothing in the product offered that. This does.
 ## Install
 
 ```sh
-npx @runveric/cli@0.5.1 <command>     # no install
+npx @runveric/cli@0.6.0 <command>     # no install
 npm install -g @runveric/cli          # or install the `runveric` bin
 ```
 
@@ -63,7 +63,7 @@ Pin the version your Runveric deployment shows you on its Author page rather tha
 Scaffold a PowerShell action, look at what you got, validate it, and run it locally:
 
 ```sh
-$ npx @runveric/cli@0.5.1 init restart-web-tier \
+$ npx @runveric/cli@0.6.0 init restart-web-tier \
     --id acme/restart-web-tier \
     --interpreter powershell \
     --yes
@@ -174,39 +174,49 @@ time through the action protocol, with handlers written against
 commands, so the four verbs keep meaning what they mean.
 
 ```sh
-npx @runveric/cli@0.5.1 action init action-azure-disk-snapshot --key azure.disk.snapshot --name "Snapshot Disk"
+npx @runveric/cli@0.6.0 action init action-azure-disk-snapshot --key azure.disk.snapshot --name "Snapshot Disk"
 cd action-azure-disk-snapshot
 npm install   # writes package-lock.json — commit it; the publish workflow runs `npm ci --ignore-scripts`
-npm test      # type-checks src/, builds dist/index.js, then validate, execute and rollback through `action test`
+npm test           # type-checks src/, builds dist/index.js, runs the unit tests — no Azure, no network
+npm run test:live  # validate, then a dry-run execute, through `action test` with your own az login
 ```
 
 `action init` writes a repository that builds, tests and publishes with no hand step: `package.json`
-(the SDK pinned exactly to the version this CLI was built against; a `typecheck` that `npm test` runs
-first — esbuild strips types, so without it a type error would build and publish; a build that bundles
-`src/index.ts` and the SDK into the one file the runtime loads, `dist/index.js`), `tsconfig.json`
-(strict, against the installed SDK's types), `src/index.ts`
-(`defineAction({ validate, execute, rollback })`, whose `execute` makes a restore point durable
-before it acts), `catalog.yaml` (an engine `execution`, a beta version, an `azure/arm` target that
-depends on its resource group), a test, `README.md`, `.gitignore`, and the catalog's publish workflow
-— rendered from the same template, by the same function, as the catalog's own tooling plants it.
-The directory defaults to the repository name the key maps to. It never overwrites a file.
+(the SDK pinned exactly to the version this CLI was built against; `test` runs a `typecheck` first —
+esbuild strips types, so without it a type error would build and publish — then a build that bundles
+`src/index.ts` and the SDK into the one file the runtime loads, `dist/index.js`, then `test:unit`, the
+action's own vitest suite; `test:live` runs `action test` against Azure), `tsconfig.json` (strict,
+against the installed SDK's types), `src/index.ts` (`defineAction({ validate, execute, rollback })`,
+whose `execute` makes a restore point durable before it acts), `src/assess.ts` (the one pure function
+that turns what was read into checks) and its unit tests, `catalog.yaml` (an engine `execution`, a beta
+version, an `azure/arm` target that depends on its resource group, and the `checks:` it may raise — every
+refusal and decision code, each decision with the words a requester ticks), `README.md`, `.gitignore`,
+the catalog's publish workflow and a pull-request template with the promotion checklist — rendered from
+the same templates, by the same function, as the catalog's own tooling plants them. The directory
+defaults to the repository name the key maps to. It never overwrites a file.
 
 `action test` runs ONE phase of the built `dist/index.js` through the real action runtime and a
 **local engine**:
 
 ```sh
 runveric action test --phase validate --param resourceGroup=rg-example --param resource=example
-runveric action test --phase execute --params-file test/params.json [--dry-run]
+runveric action test --phase validate --params-file test/params.json --expect disk.unreadable
+runveric action test --phase execute --params-file test/params.json [--dry-run] [--decide disk.recentlyChanged]
 runveric action test --phase rollback --params-file test/params.json --prior-result test/prior-result.json
 runveric action test --phase execute --params-file test/params.json --azure-token-from-az
 ```
 
+Before anything runs, `catalog.yaml` is held to the rules the catalog refuses a manifest for — its
+`checks:` and its one target — by the very functions the platform uses, and every broken rule is named.
 The invocation is built from `catalog.yaml` and the parameters, with the platform's own functions for
 the parameter schema and the one target a run names. Every message the action sends is checked by the
-protocol's own parsers, every checkpoint is acknowledged, and an execute's success is held to the
-engine's rule that a destructive action records a restore point first. It prints the events, the
-checks and the outcome, and exits 1 on a protocol violation or a failed outcome. `--prior-result` is
-the record an execute prints: the restore point it made and its outcome.
+protocol's own parsers, every checkpoint is acknowledged, every code a validate raises must be one
+`catalog.yaml` declares, and an execute's success is held to the engine's rule that a destructive action
+records a restore point first. It prints the events, the checks and the outcome, and exits 1 on a
+protocol violation or a failed outcome. A validate exits 0 only when no check is still at error — or,
+with `--expect <code>` (repeatable), only when exactly those codes were raised — and says why.
+`--decide <code>` (repeatable) gives an execute or a rollback a requester's recorded decision.
+`--prior-result` is the record an execute prints: the restore point it made and its outcome.
 
 **Credentials:** none by default — the action's `ctx.azure` refuses with a sentence saying how to give
 one. `--azure-token-from-az` hands it ONE token for Azure Resource Manager from your own
@@ -219,8 +229,8 @@ every message again, and the catalog's release workflow verifies and signs the i
 can run it. Neither happens here, and a local pass does not claim them.
 
 Publishing is a tag equal to `catalog.yaml`'s `version`, in two jobs. `build`, which can write nothing,
-installs with `npm ci --ignore-scripts` (no dependency's install script runs), type-checks and builds
-`dist/index.js`. `publish`, which holds the package write, installs nothing: it builds the image from the
+installs with `npm ci --ignore-scripts` (no dependency's install script runs), type-checks, builds
+`dist/index.js` and runs `npm run test:unit`. `publish`, which holds the package write, installs nothing: it builds the image from the
 action runtime by digest, pushes it by digest and publishes the catalog artifact. The catalog's release
 workflow then verifies and signs it.
 
@@ -234,21 +244,21 @@ publish and verify with these commands:
 
 ```sh
 # one action's manifest, verbatim — stdout: <key>=<repository>@<digest>
-npx @runveric/cli@0.5.1 catalog publish-action --manifest catalog.yaml \
+npx @runveric/cli@0.6.0 catalog publish-action --manifest catalog.yaml \
     --to ghcr.io/<org>/action-azure-vm-stop
 
 # an ENGINE action: its manifest and the image its workflow pushed, by digest, to the same package
-npx @runveric/cli@0.5.1 catalog publish-action --manifest catalog.yaml \
+npx @runveric/cli@0.6.0 catalog publish-action --manifest catalog.yaml \
     --to ghcr.io/<org>/action-azure-publicip-delete-unattached \
     --image ghcr.io/<org>/action-azure-publicip-delete-unattached@sha256:<digest>
 
 # a release naming each action artifact by digest — stdout: <repository>@<digest>
-npx @runveric/cli@0.5.1 catalog publish-release --from release.yaml --to ghcr.io/<org>/catalog
+npx @runveric/cli@0.6.0 catalog publish-release --from release.yaml --to ghcr.io/<org>/catalog
 
 # what the release workflow may sign: each engine action's image, judged by the server's rule
 # — stdout: one <repository>@<digest> per image that passed
-npx @runveric/cli@0.5.1 catalog verify-image --from release.yaml
-npx @runveric/cli@0.5.1 catalog verify-image <repository>@<digest> --key <action key> --commit <sha>
+npx @runveric/cli@0.6.0 catalog verify-image --from release.yaml
+npx @runveric/cli@0.6.0 catalog verify-image <repository>@<digest> --key <action key> --commit <sha>
 ```
 
 An action's package must be named after its key (`azure.vm.stop` → `action-azure-vm-stop`); the