diff --git a/STABILITY.md b/STABILITY.md index 1fabb4d6b..97523701a 100644 --- a/STABILITY.md +++ b/STABILITY.md @@ -187,6 +187,7 @@ Removed: `prism-code check [args]` with no holo, which ran `prismpm check` in th | `prism-code` | `src/volumes.mjs`: `createVolumes`, its `create`, `list`, `inspect` and `remove`, `attachVolume`, `refusalRecord`, `HOST_EFFECTS`, and the `capabilities.host-folder` and `capabilities.host-effects` checks of `CapabilityDeniedError`. Reached as `prism.volumes` on the client (#441) | [#445](https://github.com/UOR-Foundation/PrismPM/issues/445) | | `prism-code` | `prism.system` in `src/system.mjs`: `createSystem`, `createEventBus`, `info`, `version`, `df`, `prune` and `events`, their options, the `prism/system-info/1`, `prism/system-version/1`, `prism/system-df/1`, `prism/system-prune/1` and `prism/system-event/1` shapes, `EVENT_ACTIONS`, `EVENT_HISTORY` and `IMAGE_STORE`; `containers.list` and `containers.prune`, and the `onEvent` option of `createContainers` | [#446](https://github.com/UOR-Foundation/PrismPM/issues/446) | | `prism-code` | The client: `createPrism` exposing `images`, `containers`, `networks`, `volumes`, `system`, `auth`, `errors` and `verify`, its options, `MODULES` and `memoryCapabilityStore`; `Prism.fromEnv()` and `Prism.create` in `prism-code/node`; the `client.option`, `auth.unavailable` and `images.unavailable` codes | [#441](https://github.com/UOR-Foundation/PrismPM/issues/441) | +| `prism-code` | The CLI groups `prism-code ` in `src/cli/`: `images build`, `inspect`, `pull`, `push`, `verify` and `containers run`, `rm`, `inspect`, each the same as the flat verb it names, and `GROUPS`, `TOP_LEVEL` and `groupVerb` in `src/cli/index.mjs` | [#441](https://github.com/UOR-Foundation/PrismPM/issues/441) | | `prism-code` | `prism.errors` in `src/errors-namespace.mjs`: the error classes and functions of the package exports, `errors.codes` (the stable code of each class, by class name) and `errors.spec`; every code prism-code raises, each listed with its owning capability in model/sdk-diagnostics.toml and ERRORS.md. Reached as `prism.errors` on the client (#441) | [#448](https://github.com/UOR-Foundation/PrismPM/issues/448) | | `prism-code` | `PolicyParseError`, `PolicyEvaluationError`, `PolicyDeniedError` and their `code`s, and the `rego` option of `experimental_verify` | [#285](https://github.com/UOR-Foundation/PrismPM/issues/285) | | `@prism-code/verify` | `POLICIES`, `POLICY_INPUT_SCHEMA`, `parsePolicy`, `evaluatePolicy`, `policyInput`, `policy.rego`, the accepted Rego subset, and the `policy.parse` and `policy.evaluation` codes | [#285](https://github.com/UOR-Foundation/PrismPM/issues/285) | diff --git a/model/modules.toml b/model/modules.toml index 3b564d093..e4ad6cd32 100644 --- a/model/modules.toml +++ b/model/modules.toml @@ -364,6 +364,11 @@ module = "verify" path = "sdk/npm/prism-code/src/check.mjs" module = "verify" +# The `prism-code ` groups: the CLI composes the modules, as the client does. +[[owner]] +path = "sdk/npm/prism-code/src/cli/" +module = "client" + [[owner]] path = "sdk/npm/prism-code/src/closure.mjs" module = "images" diff --git a/scripts/product-sdk-check.test.mjs b/scripts/product-sdk-check.test.mjs index 2a23d52f2..ed77d8b02 100644 --- a/scripts/product-sdk-check.test.mjs +++ b/scripts/product-sdk-check.test.mjs @@ -143,7 +143,7 @@ test('actual deadline kills descendant process group and cannot hang on retained const before=Date.now();await assert.rejects(()=>command(process.execPath,['-e',source,pidFile],{timeout:1000}),/timed out/); assert(Date.now()-before<5000,'deadline must not wait for descendant pipe closure'); const pid=Number(readFileSync(pidFile,'utf8'));assert(Number.isSafeInteger(pid)&&pid>1); - const state=()=>{try{return readFileSync('/proc/'+pid+'/stat','utf8').split(') ')[1][0];}catch(error){if(error.code==='ENOENT')return null;throw error;}}; + const state=()=>{try{return readFileSync('/proc/'+pid+'/stat','utf8').split(') ')[1][0];}catch(error){if(error.code==='ENOENT'||error.code==='ESRCH')return null;throw error;}}; t.after(()=>{if(!['Z',null].includes(state()))try{process.kill(pid,'SIGKILL');}catch(error){if(error.code!=='ESRCH')throw error;}}); for(let attempt=0;attempt<30&&!['Z',null].includes(state());attempt++)await new Promise(resolve=>setTimeout(resolve,10)); assert(['Z',null].includes(state()),'timed-out descendant must not remain executing'); diff --git a/sdk/docs/cli.json b/sdk/docs/cli.json index dc7039380..071053029 100644 --- a/sdk/docs/cli.json +++ b/sdk/docs/cli.json @@ -47,6 +47,8 @@ { "name": "export", "usage": "prism-code export [--out ] [--tar ] [--project ] [--json]", "summary": "Write a release's six-file browser export or tarball, byte-checked against the build manifest, attestations beside." }, { "name": "generate", "usage": "prism-code generate --out [--lang ]", "summary": "Write bindings and a typed client (`--lang` js, the default, rust or python) from the holo's WIT world and model into ``, with a record of what they came from. A second run with the same inputs writes nothing." }, { "name": "check", "usage": "prism-code check [--policy ] [--replay ] [--key ] [--certificate-identity ] [--certificate-oidc-issuer ] [--trusted-root ] [--json]", "summary": "Judge the holo against a policy and print its verdict: the assurance level, whether the policy passed, and every reason. `--policy` takes a Rego file, the name of a shipped policy (`pure-only`, `provenance-only`) or a JSON file. Exit 1 when the policy denies, 2 when it cannot be parsed or evaluated. A holo that carries signed provenance and proof statements reaches P1 and P2 only when `--key`, or a certificate identity and issuer, names the signer that signed them. Without a holo it is a usage error that names `build --check`, the model check." }, + { "name": "images", "usage": "prism-code images ...", "summary": "The `images` module's verbs: `build`, `inspect`, `pull`, `push` and `verify`, each the same command as the flat verb it names (`verify` is `check`). `prism-code images --help` lists them." }, + { "name": "containers", "usage": "prism-code containers ...", "summary": "The `containers` module's verbs: `run`, `rm` and `inspect`, each the same command as the flat verb it names. `prism-code containers --help` lists them." }, { "name": "push", "usage": "prism-code push [--key ] [--keyless] [--no-attestations] [--signing-config ] [--store ] [--plain-http] [--json]", "summary": "Put the holo in an OCI registry or a local store as a deterministic manifest, each attestation a referrer. With `--key` or `--keyless`, also sign a statement naming the manifest, so `cosign verify-attestation` passes on the same reference." }, { "name": "pull", "usage": "prism-code pull [] [--policy ] [--key ] [--certificate-identity ] [--certificate-identity-regexp ] [--certificate-oidc-issuer ] [--type ] [--trusted-root ] [--entries ] [--timestamps ] [--store ] [--plain-http] [--json]", "summary": "Fetch a holo and write it only after its digests, archive, verdict and attestations pass; the signer flags are those of `verify-attestation`. A reference is `registry/repo:tag`, `@sha256:`, `@blake3:` or `dir://`." }, { "name": "dev", "usage": "prism-code dev [] [--port ] [--no-open] [--policy ] [--build ] [--image ]", "summary": "Watch the project, rebuild and re-check on every change, and serve the local studio at `http://localhost:4100`, with a Check tab and a Replay tab. The page loads nothing from outside the machine." }, diff --git a/sdk/npm/prism-code/CHANGELOG.md b/sdk/npm/prism-code/CHANGELOG.md index 07463922d..f33203a86 100644 --- a/sdk/npm/prism-code/CHANGELOG.md +++ b/sdk/npm/prism-code/CHANGELOG.md @@ -23,6 +23,7 @@ To move to 1.0, read the [migration guide](../../../docs/site/migration/to-1-0.m - `holo.verify()`, `holo.inspect()` and `prism-code check` give no verdict (`archive.table`) on any archive the Wire codec refuses (SPEC section 3), as the Rust verifier does: content blobs out of label order, an application manifest that is not the Wire template, a manifest reference that names no blob, a section kind or extension name out of place, or a row count other than eight (nine with the attestation row last). Such an archive used to get a failing verdict. ### Features Added +- `prism-code ` (#441): the command line has groups named after the modules. `images build|inspect|pull|push|verify` and `containers run|rm|inspect` are, for now, the same commands as the flat verbs they name, which stay. A module's verbs are listed once, in `src/cli/.mjs`; `prism-code images` alone is a usage error naming its verbs, and `prism-code images --help` prints them. - The developer surface is checked against the developer view's glossary (#347). The glossary is declared once, as the LexLean model `bindings/src/Foundation/Views/V1/Developer.lex.tex`, which renders [docs/developer-glossary.md](../../../docs/developer-glossary.md). `developer-surface.json` lists every verb and flag of the help, every namespace and method of the client, and the deprecated aliases; a test keeps it equal to the package, and `cargo xtask check-developer-view` refuses a name outside the glossary, a canonical term the view renames (`holo`, `history`, `instance`, `fingerprint`), a Docker verb taken before Prism has its behaviour (`ps`, `stop`, `logs`, `images`, `tag`, `rmi`), and an alias the model does not declare. - Trust in `verify`, signing in `auth` (#449, #447, experimental). `prism.verify.pullClosure` judges what a pull fetched, steps 4 to 8 of the push and pull design: the claims about the bytes, the attestation subjects, the verdict under the policy and, with a signer, a passing bundle; `images.pull` and `experimental_pull` now get their answer only from it, with the same checks and errors as before. Every signature goes through an `auth` identity: `auth.identities.from(options)` turns the flat signer options `attest`, `signStatements` and `push` take into one, and the signing code moves out of `attest.mjs` into `auth`'s own `signing.mjs`. `experimental_attest` and `experimental_signStatements` are unchanged in `prism-code/node`. A keyless failure before any token was read keeps its `cause` through `auth`, as it did through `attest`. - Every error code prism-code raises is registered (#448). model/sdk-diagnostics.toml now holds all 172: the code of each error class with its class, and every check code of a `PrismCodeError`, each owned by its module's capability (AL-07 verify, OC-11 images, SE-09 auth, DK-39 networks, DK-41 client, containers and system, CT-12 errors), and ERRORS.md lists them. test/fixtures/unregistered-codes.json is gone: the test fails on any code raised without a row, any code built from a variable, and any row no longer raised. The `export.*` refusals are raised as literal codes. diff --git a/sdk/npm/prism-code/bin/prism-code.mjs b/sdk/npm/prism-code/bin/prism-code.mjs index 54b051bfc..0b082e94c 100644 --- a/sdk/npm/prism-code/bin/prism-code.mjs +++ b/sdk/npm/prism-code/bin/prism-code.mjs @@ -77,6 +77,7 @@ import { inspect, formatInspection, select } from '../src/inspect.mjs'; import { manifestProviders } from '../src/manifest.mjs'; import { canonicalJson } from '../src/archive.mjs'; import { resolveAliases } from '../src/developer-view.mjs'; +import { GROUPS, TOP_LEVEL, groupUsage, groupVerb } from '../src/cli/index.mjs'; import { generate, WRITERS } from '../src/generate/index.mjs'; import { check, readPolicy, formatVerdict, verdictJson, exitCodeOf, EXIT as CHECK_EXIT } from '../src/check.mjs'; import { discover, errorHookMessages, listPlugins, pluginHelp, readMetadata, runPlugin } from '../src/plugins.mjs'; @@ -198,6 +199,7 @@ Usage: hand the sentence to the agent: a terminal running claude or codex (after Enter), Cursor's or VS Code's install link with the sentence on the clipboard, or the Claude or ChatGPT prompt URL +${groupUsage()} prism-code [args] run prism- from the PATH; a built-in verb always wins prism-code --version | --help @@ -290,7 +292,7 @@ Options for open: --dry-run print the files and commands; `; // The built-in verbs are the ones the usage text names and the delegated ones, so a new verb shadows a plugin of its name. -const BUILTINS = new Set([...[...USAGE.matchAll(/^ {2}prism-code ([a-z][a-z-]*)/gm)].map((m) => m[1]), ...Object.keys(DELEGATED), 'help', 'version']); +const BUILTINS = new Set([...[...USAGE.matchAll(/^ {2}prism-code ([a-z][a-z-]*)/gm)].map((m) => m[1]), ...Object.keys(DELEGATED), ...Object.keys(TOP_LEVEL), 'help', 'version']); function usage(message) { if (message) process.stderr.write(`${message}\n\n`); @@ -1132,6 +1134,15 @@ async function main(argv) { process.stdout.write(`${version}\n`); return 0; } + // `prism-code ` (#441): a module's verb, or the flat verb it names. + const group = groupVerb(command, rest); + if (group !== null) return group.verb.run ? group.verb.run(rest.slice(1)) : main([group.verb.flat, ...rest.slice(1)]); + // A top-level alias that is also a module (`images` for `images ls`) applies only when no group verb follows. + const helps = rest.includes('--help') || rest.includes('-h'); + if (Object.hasOwn(TOP_LEVEL, command) && !(Object.hasOwn(GROUPS, command) && helps)) return main([...TOP_LEVEL[command], ...rest]); + if (Object.hasOwn(GROUPS, command) && !helps) { + return usage(`${command} takes one of ${Object.keys(GROUPS[command]).join(', ')}`); + } // `--help` after a built-in verb prints that verb's usage and never reaches Docker or a lockfile. const own = rest.includes('--') ? rest.slice(0, rest.indexOf('--')) : rest; if (BUILTINS.has(command) && (own.includes('--help') || own.includes('-h'))) { diff --git a/sdk/npm/prism-code/developer-surface.json b/sdk/npm/prism-code/developer-surface.json index f6b117ad7..814b966ca 100644 --- a/sdk/npm/prism-code/developer-surface.json +++ b/sdk/npm/prism-code/developer-surface.json @@ -136,6 +136,46 @@ "place": "prism-code verify-attestation", "name": "verify-attestation" }, + { + "kind": "verb", + "place": "prism-code containers inspect", + "name": "inspect" + }, + { + "kind": "verb", + "place": "prism-code containers rm", + "name": "rm" + }, + { + "kind": "verb", + "place": "prism-code containers run", + "name": "run" + }, + { + "kind": "verb", + "place": "prism-code images build", + "name": "build" + }, + { + "kind": "verb", + "place": "prism-code images inspect", + "name": "inspect" + }, + { + "kind": "verb", + "place": "prism-code images pull", + "name": "pull" + }, + { + "kind": "verb", + "place": "prism-code images push", + "name": "push" + }, + { + "kind": "verb", + "place": "prism-code images verify", + "name": "verify" + }, { "kind": "flag", "place": "--agent", diff --git a/sdk/npm/prism-code/scripts/package-allowances/cli-module-groups.json b/sdk/npm/prism-code/scripts/package-allowances/cli-module-groups.json new file mode 100644 index 000000000..6a8a5d4e1 --- /dev/null +++ b/sdk/npm/prism-code/scripts/package-allowances/cli-module-groups.json @@ -0,0 +1,4 @@ +{ + "kib": 8, + "reason": "The CLI groups of the nine modules: src/cli/ with the dispatcher, the images and containers groups and their help lines (about 4.5 KiB), #441." +} diff --git a/sdk/npm/prism-code/skill/SKILL.md b/sdk/npm/prism-code/skill/SKILL.md index 07bc55c54..6d9ec27f5 100644 --- a/sdk/npm/prism-code/skill/SKILL.md +++ b/sdk/npm/prism-code/skill/SKILL.md @@ -57,6 +57,8 @@ Run `npx prism-code --help` for the list your installed version has. The command | `prism-code export [--out ] [--tar ] [--project ] [--json]` | Write a release's six-file browser export or tarball, byte-checked against the build manifest, attestations beside. | | `prism-code generate --out [--lang ]` | Write bindings and a typed client (`--lang` js, the default, rust or python) from the holo's WIT world and model into ``, with a record of what they came from. A second run with the same inputs writes nothing. | | `prism-code check [--policy ] [--replay ] [--key ] [--certificate-identity ] [--certificate-oidc-issuer ] [--trusted-root ] [--json]` | Judge the holo against a policy and print its verdict: the assurance level, whether the policy passed, and every reason. `--policy` takes a Rego file, the name of a shipped policy (`pure-only`, `provenance-only`) or a JSON file. Exit 1 when the policy denies, 2 when it cannot be parsed or evaluated. A holo that carries signed provenance and proof statements reaches P1 and P2 only when `--key`, or a certificate identity and issuer, names the signer that signed them. Without a holo it is a usage error that names `build --check`, the model check. | +| `prism-code images ...` | The `images` module's verbs: `build`, `inspect`, `pull`, `push` and `verify`, each the same command as the flat verb it names (`verify` is `check`). `prism-code images --help` lists them. | +| `prism-code containers ...` | The `containers` module's verbs: `run`, `rm` and `inspect`, each the same command as the flat verb it names. `prism-code containers --help` lists them. | | `prism-code push [--key ] [--keyless] [--no-attestations] [--signing-config ] [--store ] [--plain-http] [--json]` | Put the holo in an OCI registry or a local store as a deterministic manifest, each attestation a referrer. With `--key` or `--keyless`, also sign a statement naming the manifest, so `cosign verify-attestation` passes on the same reference. | | `prism-code pull [] [--policy ] [--key ] [--certificate-identity ] [--certificate-identity-regexp ] [--certificate-oidc-issuer ] [--type ] [--trusted-root ] [--entries ] [--timestamps ] [--store ] [--plain-http] [--json]` | Fetch a holo and write it only after its digests, archive, verdict and attestations pass; the signer flags are those of `verify-attestation`. A reference is `registry/repo:tag`, `@sha256:`, `@blake3:` or `dir://`. | | `prism-code dev [] [--port ] [--no-open] [--policy ] [--build ] [--image ]` | Watch the project, rebuild and re-check on every change, and serve the local studio at `http://localhost:4100`, with a Check tab and a Replay tab. The page loads nothing from outside the machine. | diff --git a/sdk/npm/prism-code/src/cli/containers.mjs b/sdk/npm/prism-code/src/cli/containers.mjs new file mode 100644 index 000000000..65af3c97e --- /dev/null +++ b/sdk/npm/prism-code/src/cli/containers.mjs @@ -0,0 +1,6 @@ +/** `prism-code containers ` (#443): the container verbs, under the module's name. */ +export const verbs = Object.freeze({ + inspect: Object.freeze({ flat: 'inspect', usage: ' [--json]', summary: 'the same as prism-code inspect' }), + rm: Object.freeze({ flat: 'rm', usage: '...', summary: 'the same as prism-code rm' }), + run: Object.freeze({ flat: 'run', usage: ' ...', summary: 'the same as prism-code run' }), +}); diff --git a/sdk/npm/prism-code/src/cli/images.mjs b/sdk/npm/prism-code/src/cli/images.mjs new file mode 100644 index 000000000..5a3d5df6a --- /dev/null +++ b/sdk/npm/prism-code/src/cli/images.mjs @@ -0,0 +1,8 @@ +/** `prism-code images ` (#442): the image verbs, under the module's name. */ +export const verbs = Object.freeze({ + build: Object.freeze({ flat: 'build', usage: '...', summary: 'the same as prism-code build' }), + inspect: Object.freeze({ flat: 'inspect', usage: ' [--json]', summary: 'the same as prism-code inspect' }), + pull: Object.freeze({ flat: 'pull', usage: ' []', summary: 'the same as prism-code pull' }), + push: Object.freeze({ flat: 'push', usage: ' ', summary: 'the same as prism-code push' }), + verify: Object.freeze({ flat: 'check', usage: ' [--policy ] [--json]', summary: 'the same as prism-code check' }), +}); diff --git a/sdk/npm/prism-code/src/cli/index.mjs b/sdk/npm/prism-code/src/cli/index.mjs new file mode 100644 index 000000000..4cafb7f65 --- /dev/null +++ b/sdk/npm/prism-code/src/cli/index.mjs @@ -0,0 +1,52 @@ +/** + * The CLI groups of the nine modules (#441): `prism-code `. + * + * Each module that has verbs gets one line here and one file beside this one. + * The file exports `verbs`, a frozen table from verb to one of + * - `{ flat, usage, summary }`, the same command as the flat verb `flat`; + * - `{ run, usage, summary }`, where `run(args)` resolves to the exit code; + * - a function `(args) => exitCode`, when the file also exports `help`, its + * usage lines verbatim. + * A file may export `aliases`, top-level verbs that mean one of its verbs + * (`login` for `auth login`). A group verb is used only when the word after the + * module is one of its verbs, so a flat verb that shares a module's name + * (`verify`) keeps working. + */ +import * as containers from './containers.mjs'; +import * as images from './images.mjs'; + +const FILES = Object.freeze({ containers, images }); + +const entry = (verb) => (typeof verb === 'function' ? Object.freeze({ run: verb }) : verb); + +/** Each module's verbs, as `{ flat }` or `{ run }` entries. */ +export const GROUPS = Object.freeze(Object.fromEntries(Object.entries(FILES).map(([module, file]) => + [module, Object.freeze(Object.fromEntries(Object.entries(file.verbs).map(([name, verb]) => [name, entry(verb)])))]))); + +/** Top-level verbs that mean a group verb: `login` is `auth login`. */ +export const TOP_LEVEL = Object.freeze(Object.fromEntries(Object.entries(FILES).flatMap(([module, file]) => + Object.entries(file.aliases ?? {}).map(([alias, name]) => [alias, Object.freeze([module, name])])))); + +/** The group verb `args` names, or null when `args` is not a group command. */ +export function groupVerb(module, args) { + const verbs = Object.hasOwn(GROUPS, module) ? GROUPS[module] : null; + const name = args[0]; + if (verbs === null || typeof name !== 'string' || !Object.hasOwn(verbs, name)) return null; + return { module, name, verb: verbs[name] }; +} + +/** The usage lines of every group, in the layout of the flat verbs' lines. */ +export function groupUsage() { + const lines = []; + for (const [module, verbs] of Object.entries(GROUPS)) { + if (typeof FILES[module].help === 'string') { + lines.push(FILES[module].help.replace(/\n$/, '')); + continue; + } + for (const [name, { usage, summary }] of Object.entries(verbs)) { + const head = ` prism-code ${module} ${name}${usage ? ` ${usage}` : ''}`; + lines.push(head.length < 52 ? `${head.padEnd(52)}${summary}` : `${head}\n${' '.repeat(52)}${summary}`); + } + } + return lines.join('\n'); +} diff --git a/sdk/npm/prism-code/src/developer-view.mjs b/sdk/npm/prism-code/src/developer-view.mjs index 11946f9b0..c891b7ce3 100644 --- a/sdk/npm/prism-code/src/developer-view.mjs +++ b/sdk/npm/prism-code/src/developer-view.mjs @@ -92,13 +92,18 @@ function members(value, place, out) { * namespaces and methods, and the deprecated aliases, as `developer-surface.json` * holds it. */ -export function developerSurface({ usage, client, delegated = [] }) { - const verbs = sorted([...[...usage.matchAll(/^ {2}prism-code ([a-z][a-z-]*)/gm)].map((m) => m[1]), ...delegated]); +export function developerSurface({ usage, client, delegated = [], groups = [] }) { + // A module group's line, `prism-code `, names the verb; the module is a namespace (#441). + const lines = [...usage.matchAll(/^ {2}prism-code ([a-z][a-z-]*)(?: ([a-z][a-z-]*))?/gm)]; + const grouped = lines.filter((m) => groups.includes(m[1]) && m[2] !== undefined); + const verbs = sorted([...lines.filter((m) => !grouped.includes(m)).map((m) => m[1]), ...delegated]); + const groupVerbs = sorted(grouped.map((m) => `${m[1]} ${m[2]}`)); const flags = sorted([...usage.matchAll(/(? m[1])); return { schema: SURFACE_SCHEMA, names: [ ...verbs.map((name) => ({ kind: 'verb', place: `prism-code ${name}`, name })), + ...groupVerbs.map((place) => ({ kind: 'verb', place: `prism-code ${place}`, name: place.split(' ')[1] })), ...flags.map((name) => ({ kind: 'flag', place: `--${name}`, name })), ...members(client, 'prism', []), ], diff --git a/sdk/npm/prism-code/test/cli-groups.test.mjs b/sdk/npm/prism-code/test/cli-groups.test.mjs new file mode 100644 index 000000000..87d739fa4 --- /dev/null +++ b/sdk/npm/prism-code/test/cli-groups.test.mjs @@ -0,0 +1,54 @@ +// The CLI groups of the nine modules (#441): `prism-code ` is the +// module's verb, or the flat verb it names, and a group's file is the one place +// its verbs are listed. +import { test } from 'node:test'; +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { dirname } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { GROUPS, groupUsage, groupVerb } from '../src/cli/index.mjs'; + +const bin = fileURLToPath(new URL('../bin/prism-code.mjs', import.meta.url)); +const holo = fileURLToPath(new URL('../fixtures/Calculator.holo', import.meta.url)); +const cli = (...args) => spawnSync(process.execPath, [bin, ...args], { encoding: 'utf8', env: { PATH: dirname(process.execPath) } }); +const MODULES = ['client', 'images', 'containers', 'networks', 'volumes', 'system', 'auth', 'errors', 'verify']; + +test('every group is one of the nine modules, and every verb names a flat verb or runs itself', () => { + for (const [module, verbs] of Object.entries(GROUPS)) { + assert.ok(MODULES.includes(module), module); + assert.ok(Object.isFrozen(verbs), module); + for (const [name, verb] of Object.entries(verbs)) { + assert.match(name, /^[a-z][a-z-]*$/); + assert.ok((typeof verb.flat === 'string') !== (typeof verb.run === 'function'), `${module} ${name} is flat or runs, not both`); + } + } +}); + +test('a group verb is found only for a module and one of its verbs', () => { + assert.equal(groupVerb('images', ['inspect', holo]).verb.flat, 'inspect'); + assert.equal(groupVerb('images', ['nope']), null); + assert.equal(groupVerb('images', []), null); + assert.equal(groupVerb('verify', ['--lean']), null); + assert.equal(groupVerb('constructor', ['x']), null); +}); + +test('prism-code images inspect is prism-code inspect', () => { + const flat = cli('inspect', holo, '--json'); + const grouped = cli('images', 'inspect', holo, '--json'); + assert.equal(flat.status, 0, flat.stderr); + assert.equal(grouped.status, flat.status); + assert.equal(grouped.stdout, flat.stdout); +}); + +test('the help lists every group verb, and a module alone is a usage error naming its verbs', () => { + const help = cli('--help'); + assert.equal(help.status, 0); + for (const line of groupUsage().split('\n')) assert.ok(help.stdout.includes(line), line); + const bare = cli('images'); + assert.equal(bare.status, 64); + assert.match(bare.stderr, /^images takes one of build, inspect, pull, push, verify/); + const group = cli('images', '--help'); + assert.equal(group.status, 0); + assert.match(group.stdout, /^ {2}prism-code images push /m); + assert.doesNotMatch(group.stdout, /prism-code containers/); +}); diff --git a/sdk/npm/prism-code/test/developer-view.test.mjs b/sdk/npm/prism-code/test/developer-view.test.mjs index db7b4a20a..a7d954ac6 100644 --- a/sdk/npm/prism-code/test/developer-view.test.mjs +++ b/sdk/npm/prism-code/test/developer-view.test.mjs @@ -9,6 +9,7 @@ import { dirname } from 'node:path'; import { fileURLToPath } from 'node:url'; import { createPrism } from '../src/index.mjs'; import { DELEGATED } from '../src/docker.mjs'; +import { GROUPS } from '../src/cli/index.mjs'; import { ALIASES, SURFACE_SCHEMA, aliasWarning, developerSurface, resolveAliases } from '../src/developer-view.mjs'; const bin = fileURLToPath(new URL('../bin/prism-code.mjs', import.meta.url)); @@ -21,7 +22,7 @@ const help = () => { return r.stdout; }; -const surface = () => developerSurface({ usage: help(), client: createPrism(), delegated: Object.keys(DELEGATED) }); +const surface = () => developerSurface({ usage: help(), client: createPrism(), delegated: Object.keys(DELEGATED), groups: Object.keys(GROUPS) }); test('developer-surface.json is the CLI help, the delegated verbs and the client, as the glossary check reads them', () => { const text = `${JSON.stringify(surface(), null, 2)}\n`; diff --git a/sdk/npm/prism-code/test/fixtures/package-files.json b/sdk/npm/prism-code/test/fixtures/package-files.json index 02cbdee3c..af639e1b2 100644 --- a/sdk/npm/prism-code/test/fixtures/package-files.json +++ b/sdk/npm/prism-code/test/fixtures/package-files.json @@ -32,6 +32,9 @@ "src/canonical/index.js", "src/capabilities.mjs", "src/check.mjs", + "src/cli/containers.mjs", + "src/cli/images.mjs", + "src/cli/index.mjs", "src/closure.mjs", "src/containers.mjs", "src/core.mjs", diff --git a/skills/prism/SKILL.md b/skills/prism/SKILL.md index 07bc55c54..6d9ec27f5 100644 --- a/skills/prism/SKILL.md +++ b/skills/prism/SKILL.md @@ -57,6 +57,8 @@ Run `npx prism-code --help` for the list your installed version has. The command | `prism-code export [--out ] [--tar ] [--project ] [--json]` | Write a release's six-file browser export or tarball, byte-checked against the build manifest, attestations beside. | | `prism-code generate --out [--lang ]` | Write bindings and a typed client (`--lang` js, the default, rust or python) from the holo's WIT world and model into ``, with a record of what they came from. A second run with the same inputs writes nothing. | | `prism-code check [--policy ] [--replay ] [--key ] [--certificate-identity ] [--certificate-oidc-issuer ] [--trusted-root ] [--json]` | Judge the holo against a policy and print its verdict: the assurance level, whether the policy passed, and every reason. `--policy` takes a Rego file, the name of a shipped policy (`pure-only`, `provenance-only`) or a JSON file. Exit 1 when the policy denies, 2 when it cannot be parsed or evaluated. A holo that carries signed provenance and proof statements reaches P1 and P2 only when `--key`, or a certificate identity and issuer, names the signer that signed them. Without a holo it is a usage error that names `build --check`, the model check. | +| `prism-code images ...` | The `images` module's verbs: `build`, `inspect`, `pull`, `push` and `verify`, each the same command as the flat verb it names (`verify` is `check`). `prism-code images --help` lists them. | +| `prism-code containers ...` | The `containers` module's verbs: `run`, `rm` and `inspect`, each the same command as the flat verb it names. `prism-code containers --help` lists them. | | `prism-code push [--key ] [--keyless] [--no-attestations] [--signing-config ] [--store ] [--plain-http] [--json]` | Put the holo in an OCI registry or a local store as a deterministic manifest, each attestation a referrer. With `--key` or `--keyless`, also sign a statement naming the manifest, so `cosign verify-attestation` passes on the same reference. | | `prism-code pull [] [--policy ] [--key ] [--certificate-identity ] [--certificate-identity-regexp ] [--certificate-oidc-issuer ] [--type ] [--trusted-root ] [--entries ] [--timestamps ] [--store ] [--plain-http] [--json]` | Fetch a holo and write it only after its digests, archive, verdict and attestations pass; the signer flags are those of `verify-attestation`. A reference is `registry/repo:tag`, `@sha256:`, `@blake3:` or `dir://`. | | `prism-code dev [] [--port ] [--no-open] [--policy ] [--build ] [--image ]` | Watch the project, rebuild and re-check on every change, and serve the local studio at `http://localhost:4100`, with a Check tab and a Replay tab. The page loads nothing from outside the machine. |