@runveric/cli 0.3.0 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@
 production runner image — without pushing anything or signing in.**
 
 ```sh
-npx @runveric/cli@0.3.0 init --id yourteam/restart-web-tier
+npx @runveric/cli@0.5.0 init --id yourteam/restart-web-tier
 ```
 
 ---
@@ -32,14 +32,15 @@ script outside the platform. Nothing in the product offered that. This does.
 
 ## Requirements
 
-- **Node.js 20 or newer** — for `init`, `check` and `publish`.
-- **Docker** — for `test` only.
+- **Node.js 22 or newer** — for `init`, `check`, `publish`, and `action init` / `action test`.
+- **Docker** — for `test` only (an action package's phase runs in the runner image). `action test` runs
+  an engine action's phase in-process, with no Docker.
 - An **Runveric account** — for `publish` only.
 
 ## Install
 
 ```sh
-npx @runveric/cli@0.3.0 <command>     # no install
+npx @runveric/cli@0.5.0 <command>     # no install
 npm install -g @runveric/cli          # or install the `runveric` bin
 ```
 
@@ -62,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.3.0 init restart-web-tier \
+$ npx @runveric/cli@0.5.0 init restart-web-tier \
     --id acme/restart-web-tier \
     --interpreter powershell \
     --yes
@@ -164,6 +165,65 @@ Publishing does not adopt. Nobody can run it until somebody chooses to.
 
 ---
 
+## Engine actions (`runveric action`)
+
+The four verbs above author an action **package** — a script an interpreter runs. An **engine
+action** is the other kind: TypeScript built into its own image, run by the engine one phase at a
+time through the action protocol, with handlers written against
+[`@runveric/action-sdk`](https://www.npmjs.com/package/@runveric/action-sdk). It has its own two
+commands, so the four verbs keep meaning what they mean.
+
+```sh
+npx @runveric/cli@0.5.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`
+npm test      # type-checks src/, builds dist/index.js, then validate, execute and rollback through `action test`
+```
+
+`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.
+
+`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 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
+```
+
+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.
+
+**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
+`az account get-access-token`, held in memory for that run: never an environment variable, an
+argument, a file or a line of output. It is **your** access, not the platform's minted, per-audience
+tokens.
+
+**This is a development loop, not the gate.** When the action runs in the platform, the engine judges
+every message again, and the catalog's release workflow verifies and signs the image before anything
+can run it. Neither happens here, and a local pass does not claim them.
+
+Publishing is a tag equal to `catalog.yaml`'s `version`: the workflow builds the image from the
+action runtime by digest and publishes the catalog artifact; the catalog's release workflow verifies
+and signs it.
+
+---
+
 ## Publishing first-party catalog artifacts (`runveric catalog`)
 
 Not part of authoring, and not something an author needs. The product's own catalog is pinned
@@ -172,21 +232,21 @@ publish and verify with these commands:
 
 ```sh
 # one action's manifest, verbatim — stdout: <key>=<repository>@<digest>
-npx @runveric/cli@0.3.0 catalog publish-action --manifest catalog.yaml \
+npx @runveric/cli@0.5.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.3.0 catalog publish-action --manifest catalog.yaml \
+npx @runveric/cli@0.5.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.3.0 catalog publish-release --from release.yaml --to ghcr.io/<org>/catalog
+npx @runveric/cli@0.5.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.3.0 catalog verify-image --from release.yaml
-npx @runveric/cli@0.3.0 catalog verify-image <repository>@<digest> --key <action key> --commit <sha>
+npx @runveric/cli@0.5.0 catalog verify-image --from release.yaml
+npx @runveric/cli@0.5.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