Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions STABILITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <module> <verb>` 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) |
Expand Down
5 changes: 5 additions & 0 deletions model/modules.toml
Original file line number Diff line number Diff line change
Expand Up @@ -364,6 +364,11 @@ module = "verify"
path = "sdk/npm/prism-code/src/check.mjs"
module = "verify"

# The `prism-code <module> <verb>` 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"
Expand Down
2 changes: 1 addition & 1 deletion scripts/product-sdk-check.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand Down
2 changes: 2 additions & 0 deletions sdk/docs/cli.json
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,8 @@
{ "name": "export", "usage": "prism-code export <name@sha256:digest> [--out <dir>] [--tar <file>] [--project <dir>] [--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 <app.holo> --out <dir> [--lang <language>]", "summary": "Write bindings and a typed client (`--lang` js, the default, rust or python) from the holo's WIT world and model into `<dir>`, with a record of what they came from. A second run with the same inputs writes nothing." },
{ "name": "check", "usage": "prism-code check <app.holo> [--policy <file>] [--replay <file>] [--key <file>] [--certificate-identity <id>] [--certificate-oidc-issuer <url>] [--trusted-root <file>] [--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 <verb> ...", "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 <verb> ...", "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 <app.holo> <reference> [--key <file>] [--keyless] [--no-attestations] [--signing-config <file>] [--store <dir>] [--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 <reference> [<out.holo>] [--policy <file>] [--key <file>] [--certificate-identity <id>] [--certificate-identity-regexp <re>] [--certificate-oidc-issuer <url>] [--type <uri>] [--trusted-root <file>] [--entries <n>] [--timestamps <n>] [--store <dir>] [--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 [<dir>] [--port <n>] [--no-open] [--policy <file>] [--build <command>] [--image <path>]", "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." },
Expand Down
1 change: 1 addition & 0 deletions sdk/npm/prism-code/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <module> <verb>` (#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/<module>.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.
Expand Down
13 changes: 12 additions & 1 deletion sdk/npm/prism-code/bin/prism-code.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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 <plugin> [args] run prism-<plugin> from the PATH; a built-in verb always wins
prism-code --version | --help

Expand Down Expand Up @@ -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`);
Expand Down Expand Up @@ -1132,6 +1134,15 @@ async function main(argv) {
process.stdout.write(`${version}\n`);
return 0;
}
// `prism-code <module> <verb>` (#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'))) {
Expand Down
40 changes: 40 additions & 0 deletions sdk/npm/prism-code/developer-surface.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
Original file line number Diff line number Diff line change
@@ -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."
}
2 changes: 2 additions & 0 deletions sdk/npm/prism-code/skill/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,8 @@ Run `npx prism-code --help` for the list your installed version has. The command
| `prism-code export <name@sha256:digest> [--out <dir>] [--tar <file>] [--project <dir>] [--json]` | Write a release's six-file browser export or tarball, byte-checked against the build manifest, attestations beside. |
| `prism-code generate <app.holo> --out <dir> [--lang <language>]` | Write bindings and a typed client (`--lang` js, the default, rust or python) from the holo's WIT world and model into `<dir>`, with a record of what they came from. A second run with the same inputs writes nothing. |
| `prism-code check <app.holo> [--policy <file>] [--replay <file>] [--key <file>] [--certificate-identity <id>] [--certificate-oidc-issuer <url>] [--trusted-root <file>] [--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 <verb> ...` | 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 <verb> ...` | 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 <app.holo> <reference> [--key <file>] [--keyless] [--no-attestations] [--signing-config <file>] [--store <dir>] [--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 <reference> [<out.holo>] [--policy <file>] [--key <file>] [--certificate-identity <id>] [--certificate-identity-regexp <re>] [--certificate-oidc-issuer <url>] [--type <uri>] [--trusted-root <file>] [--entries <n>] [--timestamps <n>] [--store <dir>] [--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 [<dir>] [--port <n>] [--no-open] [--policy <file>] [--build <command>] [--image <path>]` | 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. |
Expand Down
6 changes: 6 additions & 0 deletions sdk/npm/prism-code/src/cli/containers.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
/** `prism-code containers <verb>` (#443): the container verbs, under the module's name. */
export const verbs = Object.freeze({
inspect: Object.freeze({ flat: 'inspect', usage: '<container> [--json]', summary: 'the same as prism-code inspect' }),
rm: Object.freeze({ flat: 'rm', usage: '<container>...', summary: 'the same as prism-code rm' }),
run: Object.freeze({ flat: 'run', usage: '<app.holo> <input> ...', summary: 'the same as prism-code run' }),
});
8 changes: 8 additions & 0 deletions sdk/npm/prism-code/src/cli/images.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
/** `prism-code images <verb>` (#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: '<app.holo> [--json]', summary: 'the same as prism-code inspect' }),
pull: Object.freeze({ flat: 'pull', usage: '<reference> [<out.holo>]', summary: 'the same as prism-code pull' }),
push: Object.freeze({ flat: 'push', usage: '<app.holo> <reference>', summary: 'the same as prism-code push' }),
verify: Object.freeze({ flat: 'check', usage: '<app.holo> [--policy <file>] [--json]', summary: 'the same as prism-code check' }),
});
Loading
Loading