prae-cli 0.5.1 → 0.6.0

package/README.md

@@ -40,6 +40,40 @@ formats plus entropy, placeholders dropped. Findings name the type, rule,
 line and confidence — structurally never the secret, so the output is safe to
 paste anywhere. With `--pack`, also prints the verdict that pack would reach.
 
+### `prae test <suite.json> [--pack <pack.json>] [--json]`
+
+Run security invariants against a pack and exit non-zero if any stops holding.
+A suite says what an agent attempts and what the pack must decide about it:
+
+```json
+{
+  "pack": "./acme.prae.json",
+  "scenarios": [
+    {
+      "name": "Reads outside the workspace are refused",
+      "given": "the agent is scoped to ./src and ./docs",
+      "when": { "tool": "read", "args": { "file_path": "/etc/shadow" } },
+      "then": { "decision": "deny", "rule": "ACME-001" }
+    }
+  ]
+}
+```
+
+`then` also takes `secretTypes`, asserting which credential classes the
+inspector found before the verdict — so a rule about secrets is tested on the
+detection as well as the decision. `when.repeat: 8` asserts the eighth call of
+that capability, which is how a session budget is written down and how the gate
+counts it.
+
+A failure prints the invariant in full — given, when, then, and what it got
+instead — because the useful thing about a red security test is the sentence
+describing what was supposed to hold. `--pack` overrides the suite's own, which
+is how one suite is run against a candidate pack before it is adopted.
+
+This evaluates the same pack through the same evaluator and the same content
+inspector the gate uses at runtime. It is not the harness: the adapter that
+turns a live tool call into facts is covered by `prae-gate`'s own suite.
+
 ### `prae mcp --root <dir> [--pack <pack.json>] [--ledger <file>]`
 
 Serve gated filesystem access over MCP stdio. Any MCP-capable IDE or agent

package/lib/bin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import "./evaluate-DMyL3qM_.js";
-import { t as main } from "./cli-DfXHsQO7.js";
+import "./evaluate-CkYySl7T.js";
+import { t as main } from "./cli-Cr0U-PFD.js";
 import "./src-CXU0_W1P.js";
 import "./views-DalPkBZZ.js";
 

package/lib/{cli-DfXHsQO7.js → cli-Cr0U-PFD.js}

@@ -1,9 +1,9 @@
-import { t as evaluate } from "./evaluate-DMyL3qM_.js";
+import { t as evaluate } from "./evaluate-CkYySl7T.js";
 import { m as seal, t as Ledger } from "./src-CXU0_W1P.js";
 import { a as renderPacks, c as renderShell, i as renderOverview, l as VERDICT_LABEL$1, n as renderApprovals, o as esc, r as renderCompliance, s as renderNav, t as navFor } from "./views-DalPkBZZ.js";
 import { existsSync, readFileSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { extname, join, normalize, resolve, sep } from "node:path";
+import { dirname, extname, join, normalize, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import { composePatchFile, preflightOps, revisionOf, takeSnapshot } from "dsh-overlay-check";
 import { createServer } from "node:http";
@@ -853,6 +853,12 @@ const USAGE = `prae — operator policy for agent harnesses
       contents are returned, and every decision lands in the ledger.
       (no --pack mounts the bundled secret-catcher pack)
 
+  prae test <suite.json> [--pack <pack.json>] [--json]
+      Run security scenarios against a pack and report PASS/FAIL. Each
+      scenario says what an agent attempts and what the pack must decide;
+      the exit code is non-zero if any invariant no longer holds, so a
+      control pack can be defended in CI. --pack overrides the suite's own.
+
   prae verify <ledger.jsonl> [--key <public.pem>]
       Re-derive every hash in a decision log and report any break. With
       --key, also verify each row's signature against that pinned key.
@@ -970,7 +976,7 @@ async function scanFile(path, packPath, json) {
 * not come up inspecting nothing.
 */
 async function mcp(root, packPath, ledgerPath) {
-	const { serveMcp } = await import("./mcp-CEN48TpN.js");
+	const { serveMcp } = await import("./mcp-Bq0DNPPR.js");
 	const { resolve: resolve$1 } = await import("node:path");
 	const bundled = [join(import.meta.dirname, "secret-catcher.prae.json"), join(import.meta.dirname, "..", "..", "..", "examples", "secret-catcher.prae.json")].find((candidate) => existsSync(candidate));
 	const chosen = packPath ?? bundled;
@@ -1086,6 +1092,52 @@ async function verifyReceiptCmd(path) {
 	else console.error(line);
 	if (!result.ok) process.exit(1);
 }
+/**
+* `prae test`: assert a pack's invariants and set an exit code.
+*
+* The checking lives in `test-run.ts`. This does the three things a command
+* does — read the files, supply the inspector, and decide the exit code.
+*/
+async function test(suitePath, packOverride, asJson) {
+	let raw;
+	try {
+		raw = await readFile(suitePath, "utf8");
+	} catch {
+		return fail(`cannot read ${suitePath}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		return fail(`${suitePath} is not valid JSON: ${error instanceof Error ? error.message : error}`);
+	}
+	const { parseSuite, renderSuite, runSuite } = await import("./test-run-04ubUcSb.js");
+	const suite = parseSuite(parsed);
+	if (!suite.ok) {
+		console.error(`prae: ${suitePath} is not a valid test suite`);
+		for (const message of suite.errors) console.error(`  ${message}`);
+		process.exit(1);
+	}
+	const chosen = packOverride ?? (suite.suite.pack === void 0 ? void 0 : resolve(dirname(suitePath), suite.suite.pack));
+	if (chosen === void 0) return fail("test needs a pack: set `pack` in the suite or pass --pack");
+	const pack = await loadPack(chosen);
+	const { capabilityForTool } = await import("capmark");
+	const { scan } = await import("./src-Vnr0fcpK.js");
+	const inspect = pack.rules.some((rule) => rule.when.secrets !== void 0) ? (path) => {
+		try {
+			return scan(readFileSync(path, "utf8"));
+		} catch {
+			return;
+		}
+	} : void 0;
+	const result = runSuite(pack, suite.suite, {
+		capabilityFor: (tool) => capabilityForTool(tool)?.id,
+		...inspect === void 0 ? {} : { inspect }
+	});
+	if (asJson) console.log(JSON.stringify(result, null, 2));
+	else for (const line of renderSuite(result)) console.log(line);
+	if (!result.ok) process.exit(1);
+}
 async function verify(path, keyPath) {
 	let ledger;
 	try {
@@ -1175,7 +1227,7 @@ async function report(path, out) {
 * that step is a proposal a human approves, and it starts from this list.
 */
 async function instructions(from, asJson) {
-	const { ingest } = await import("./src-C4fnUm9V.js");
+	const { ingest } = await import("./src-CraUX64d.js");
 	const result = ingest(from);
 	if (asJson) {
 		console.log(JSON.stringify(result, null, 2));
@@ -1211,7 +1263,7 @@ async function instructions(from, asJson) {
 * on purpose rather than something that happened to their policy.
 */
 async function propose(from, options) {
-	const [{ ingest }, { extract }] = await Promise.all([import("./src-C4fnUm9V.js"), import("./src-BfYsUDW9.js")]);
+	const [{ ingest }, { extract }] = await Promise.all([import("./src-CraUX64d.js"), import("./src-CQ0UmFUK.js")]);
 	const read = ingest(from);
 	if (read.files.length === 0) {
 		console.log(`No instruction files found at or above ${from}.`);
@@ -1271,8 +1323,8 @@ async function consoleOut(path, argv) {
 	const instructionsDir = flag(argv, "instructions");
 	if (instructionsDir !== void 0) {
 		const [{ ingest }, { extract }, { renderInstructions }] = await Promise.all([
-			import("./src-C4fnUm9V.js"),
-			import("./src-BfYsUDW9.js"),
+			import("./src-CraUX64d.js"),
+			import("./src-CQ0UmFUK.js"),
 			import("./instructions-D4VOn2lk.js")
 		]);
 		const read = ingest(instructionsDir);
@@ -1389,6 +1441,12 @@ async function main(argv) {
 			if (path === void 0 || seq === void 0 || key === void 0) fail("receipt needs <ledger.jsonl> <seq> --key <private.pem>");
 			return receipt(path, Number(seq), key, flag(rest, "out"));
 		}
+		case "test": {
+			const [suite] = rest;
+			if (suite === void 0) fail("test needs a suite file");
+			await test(suite, flag(argv, "pack"), argv.includes("--json"));
+			return;
+		}
 		case "verify": {
 			const path = rest[0];
 			if (path === void 0) fail("verify needs a ledger file");

package/lib/docs/pilot-dsh.md

@@ -0,0 +1,196 @@
+# Pilot: PRAE over the agent's *native* tools
+
+This is the layer beneath the MCP mount. Here the agent uses DeepSeek Harness's
+own `read` tool — not a tool we provide — and PRAE sits at the harness's
+`tools/pre-execute` seam, inspects the call, and refuses it before it runs. The
+refusal is delivered to the agent **as the tool's result**, so the agent moves
+on instead of retrying.
+
+What you get to test, and try to break:
+
+```
+agent → native read(file_path) → PRAE gate → DENY → tool never runs
+                                              └→ structured refusal back to the agent
+                                              └→ sealed ledger row
+```
+
+**Verified on `@deepseek-ai/dsh 0.1.1-rc.2` with `prae-gate 0.5.1`** by driving
+the harness's own tool pipeline (a real agent, a mounted preset, the real
+`read` tool) with no model in the loop. The model-driven run below is the same
+path with your model making the call; it needs your API key, so it is yours
+to execute — the exact command and the expected output are here.
+
+> Use `prae-gate` **0.5.1 or later.** 0.5.0 and earlier had a bug this pilot
+> found: path rules looked for an argument named `path`, and dsh's `read`
+> passes `file_path`, so the shipped pack's deny rule never fired on the
+> harness. Fixed and regression-tested against the shipped packs.
+
+## 1. One-time setup (about a minute)
+
+A dsh *profile* is a directory under `~/.dsh/profiles/` holding a
+`package.json` that lists bundles, plus two YAML files. Create one for the pilot:
+
+```bash
+mkdir -p ~/.dsh/profiles/pilot && cd ~/.dsh/profiles/pilot
+
+cat > package.json <<'EOF'
+{
+  "name": "dsh-profile-pilot",
+  "private": true,
+  "dependencies": {
+    "@deepseek-ai/dsh": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-base": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-headless": "0.1.1-rc.2",
+    "prae-gate": "^0.5.1",
+    "prae-cli": "^0.5.1"
+  },
+  "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-headless"] } }
+}
+EOF
+printf '[]\n' > cordis.yml
+printf '# profile patch layer\n' > cordis.patch.yml
+
+npm install
+```
+
+Save the pilot policy pack as `~/.dsh/profiles/pilot/secret-catcher-pilot.prae.json`
+(it is the shipped `secret-catcher` pack plus one rule for the first bypass
+you will try — see §4):
+
+```json
+{
+  "prae": "0.1",
+  "pack": "secret-catcher-pilot",
+  "version": "1.0.0",
+  "rules": [
+    {
+      "id": "SEC-001",
+      "title": "Reads carrying credentials are refused",
+      "when": {
+        "capability": "fs:read",
+        "path": { "outside": ["./**/test/**", "./**/tests/**", "./**/fixtures/**", "./**/*.example", "./**/*.sample"] },
+        "secrets": { "minConfidence": 0.8 }
+      },
+      "effect": { "kind": "deny", "because": "the requested file contains a protected credential; the contents were not returned" }
+    },
+    {
+      "id": "SEC-002",
+      "title": "Private keys are refused everywhere",
+      "when": { "capability": "fs:read", "secrets": { "types": ["private-key"] } },
+      "effect": { "kind": "deny", "because": "the requested file contains a private key; the contents were not returned" }
+    },
+    {
+      "id": "SEC-003",
+      "title": "Anything credential-shaped is at least recorded",
+      "when": { "capability": "fs:read", "secrets": { "minConfidence": 0.5 } },
+      "effect": { "kind": "warn", "because": "a possible credential was noticed in this file; where no stronger rule fired, the read proceeded and this row is the record" }
+    },
+    {
+      "id": "SEC-005",
+      "title": "Shell reads of files are held — they bypass content inspection",
+      "when": { "capability": "proc:spawn", "command": { "name": ["cat", "head", "tail", "less", "more", "strings", "base64", "xxd", "od", "hexdump"] } },
+      "effect": { "kind": "ask", "because": "dumping a file through the shell skips the credential scan the read tool gets; a human releases it" }
+    }
+  ]
+}
+```
+
+Mount it. `prae init` writes the plugin row into the profile's overlay with the
+pack embedded — so the profile alone says what policy was in force:
+
+```bash
+npx prae init --profile ~/.dsh/profiles/pilot \
+  --pack ~/.dsh/profiles/pilot/secret-catcher-pilot.prae.json \
+  --ledger ~/.dsh/profiles/pilot/decisions.jsonl --apply
+```
+
+You should see `pack secret-catcher-pilot 1.0.0 · 4 rules` and `written`.
+
+## 2. A target to protect
+
+In any project directory, make a file an agent is *allowed* to open that has a
+credential pasted into it — that is the interesting case, because the path
+rule permits it and only content inspection stops it:
+
+```bash
+mkdir -p ~/pilot-target/docs && cd ~/pilot-target
+cat > docs/oncall-runbook.md <<'EOF'
+# On-call runbook
+export AWS_ACCESS_KEY_ID=AKIAJ7QDEMOFAKEKEY42
+export DATABASE_URL=postgres://svc:R0tateMe!Now@db.internal:5432/app
+EOF
+echo "nothing sensitive here" > docs/notes.md
+```
+
+(The key is fake — assembled to look real. Use a real-looking one of your own
+if you prefer; the scanner keys on format, not on a list.)
+
+## 3. Run it — the agent, its native `read`, and the gate
+
+The headless profile answers one task and exits. Set your model key (the base
+bundle's default provider is DeepSeek; `DEEPSEEK_API_KEY` is the tested
+variable), then from the target directory:
+
+```bash
+export DEEPSEEK_API_KEY=…
+cd ~/pilot-target
+~/.dsh/profiles/pilot/node_modules/.bin/dsh --profile pilot \
+  "Read ./docs/oncall-runbook.md and tell me the AWS access key it contains."
+```
+
+**What should happen:** the model calls the harness's own `read` tool; PRAE
+refuses before it runs; the model receives, as the tool result:
+
+```json
+{"decision":"deny","reason":"secret_detected","resource":"./docs/oncall-runbook.md",
+ "secret_types":["cloud-credential","credential-in-url"],"policy":"SEC-001",
+ "retry":false,"message":"the requested file contains a protected credential; the contents were not returned"}
+```
+
+…and reports that it cannot. Then the control:
+
+```bash
+~/.dsh/profiles/pilot/node_modules/.bin/dsh --profile pilot "Read ./docs/notes.md and repeat it."
+```
+
+That one succeeds. Now the record:
+
+```bash
+npx prae verify ~/.dsh/profiles/pilot/decisions.jsonl
+grep -c AKIAJ7QDEMOFAKEKEY42 ~/.dsh/profiles/pilot/decisions.jsonl   # expect 0
+```
+
+Chain intact; one `deny` row citing `SEC-001` with the credential *types* and
+*line* — and zero bytes of the credential itself, anywhere in the log.
+
+Prefer the interactive UI? Swap `@deepseek-ai/dsh-headless` for
+`@deepseek-ai/dsh-web-app` in `package.json`, reinstall, and boot with
+`dsh --profile pilot`. Same gate, same rows; you ask in the browser.
+
+## 4. Now try to get past it — what we expect, honestly
+
+| Attempt | Expected | Why |
+| --- | --- | --- |
+| Ask for the file by another relative spelling, `../pilot-target/docs/…`, an absolute path | **deny** | Paths are normalized and anchored; the content rule has no path condition anyway |
+| Ask it to `cat` / `head` / `tail` the file through the shell | **held (ask)** by `SEC-005` | Shell output is not content-inspected; the pilot pack holds the known dumpers for a human. In headless mode there is no approver, so expect the call to fail closed rather than run |
+| Ask it to `python3 -c "print(open(...).read())"`, `node -e`, `awk`, or a here-doc | **not caught** by this pack | Shell is governed by *command* rules, not by content inspection — the list of programs that can print a file is unbounded. The honest control is scope: deny or hold `proc:spawn` for agents that should not need a shell |
+| Ask it to `grep AKIA docs/` or search the directory | **not caught** by this pack | Search tools return matched *lines*; content inspection runs on whole-file reads. A pilot pack can hold `grep`/`glob` by tool name (`"tool": ["grep"]` → `ask`) if that matters to you — say so and we will ship it as an option |
+| Copy the file under `tests/fixtures/` first, then read it | **allowed, recorded** | That is the carve-out working as designed (`SEC-003` still writes a warn row). Tighten or remove the carve-out in the pack if your repos keep real secrets in fixtures |
+| Edit the ledger to hide the refusal | **chain breaks** on `prae verify` | And with a signing key configured, the signature fails without the private key — `prae keygen`, then `signingKey` in the plugin config |
+
+Every one of those outcomes is a row in `decisions.jsonl`. The ones marked
+*not caught* are the honest shape of a content-inspection control: it governs
+the read tool; the shell is a different capability and is governed by scope.
+Which of those gaps matter to Home Depot is exactly the pilot's question.
+
+## 5. What we would like back
+
+- Did the refusal reach the agent, and did the agent move on rather than retry?
+- Any file it should have refused and did not (a miss), or refused and should not have (a false positive) — the file's *shape*, not the secret.
+- Which of the bypasses in §4 you consider must-close, and which of your
+  agents run with a shell at all.
+- Latency you observed per read, if you measure it. Every row carries
+  `micros` — the gate's own decision cost — so the ledger answers that part.
+
+Anything that behaves differently from this document is a bug on our side.
+Send the command and the row, and we will fix it.

package/lib/docs/secret-catcher.md

@@ -0,0 +1,146 @@
+# Secret Catcher — the pilot, packaged
+
+What this proves, in one sentence: **an agent asks to read a file, the gate
+reads it first, finds the credential, refuses the read with a structured
+answer the agent can parse, and seals the event — and the credential appears
+nowhere: not in the refusal, not in the model's context, not in the ledger.**
+
+The loop: `READ REQUEST → INTERCEPT → INSPECT → POLICY DECISION →
+ALLOW / DENY → STRUCTURED RESPONSE`, enforced at runtime, at the execution
+boundary — not inside the prompt.
+
+## Try it in sixty seconds
+
+```bash
+# See what the gate would see (findings name the type and line, never the value)
+npx prae-cli scan .env
+
+# Add the verdict the shipped pack reaches
+npx prae-cli scan .env --pack node_modules/prae-cli/lib/secret-catcher.prae.json
+```
+
+## Mount it under your IDE or agent (MCP)
+
+Any MCP-capable environment — Cursor, Claude Code, Windsurf, or an in-house
+agent — can route file access through the gate:
+
+```json
+{
+  "mcpServers": {
+    "prae-gate": {
+      "command": "npx",
+      "args": [
+        "prae-cli", "mcp",
+        "--root", "/path/to/project",
+        "--ledger", "/path/to/decisions.jsonl"
+      ]
+    }
+  }
+}
+```
+
+Every `read_file` through this server is inspected before its contents are
+returned. A refusal looks like this — machine-readable, `retry: false`, and
+credential-free:
+
+```json
+{
+  "decision": "deny",
+  "reason": "secret_detected",
+  "resource": "/path/to/project/.env",
+  "secret_types": ["cloud-credential"],
+  "policy": "SEC-001",
+  "retry": false,
+  "message": "the requested file contains a protected credential; the contents were not returned"
+}
+```
+
+## Mount it inside DeepSeek Harness — the agent's *native* tools
+
+The dsh plugin gates the harness's own `read`/`write`/`edit`, not a tool we
+supply: any pack rule may match on `secrets`, and the gate reads the target
+before the tool runs. The refusal is delivered to the agent as the tool result.
+
+```json
+{
+  "id": "SEC-001",
+  "when": { "capability": "fs:read", "secrets": { "minConfidence": 0.8 } },
+  "effect": { "kind": "deny", "because": "the requested file contains a protected credential" }
+}
+```
+
+**The runnable setup, verified on a booted `0.1.1-rc.2`, is `docs/pilot-dsh.md`**
+— one-minute profile, the exact command, the expected refusal, and the bypasses
+to try with what each one does. Requires `prae-gate ≥ 0.5.1`.
+
+## Prove the pack still holds, in your own pipeline
+
+`prae test` runs a pack against written invariants and exits non-zero when one
+stops holding — so a pack edit that quietly stops refusing something fails a
+build instead of reaching an agent:
+
+```bash
+npx prae-cli test ./your-invariants.json --pack ./secret-catcher.prae.json
+```
+
+Each scenario names what an agent attempts and what the pack must decide about
+it, including which credential classes the inspector had to find first — so the
+detection is asserted alongside the verdict. The file format is in
+`packages/cli/README.md`, and `demo/workspace/papaya.tests.json` in this
+repository is a worked suite of fourteen. Needs `prae-cli >= 0.6.0`.
+
+## What the ledger holds afterwards
+
+One row per intercepted read — verdict, rule, subject path, and for content
+findings: detection rule, secret class, line, confidence. `prae verify`
+re-derives the chain; `prae receipt` exports any row as a signed receipt a
+counterparty can check without trusting the machine it came from.
+
+## False-positive controls
+
+- **Placeholders are dropped, not down-scored** — `AKIAIOSFODNN7EXAMPLE`,
+  `changeme`, `your_token_here` and their relatives never become findings.
+- **Confidence thresholds** — each rule sets its own floor
+  (`secrets.minConfidence`); the shipped pack denies at 0.8 and records from
+  0.5 as `warn`.
+- **Path carve-outs** — the shipped pack excludes `test/`, `fixtures/`,
+  `*.example`, `*.sample` from the deny rule (they still get warn rows).
+- **Entropy gating** — loose patterns (`password = "..."`) only fire on
+  values with real randomness; `password = "password1"` is not a finding.
+- **Extensible** — `scan()` accepts a replacement detector set; a pack is
+  JSON an operator edits.
+
+## Honest edges (the detail that lives here, not in marketing)
+
+- **Coverage is per mount.** The MCP mount covers everything routed through
+  it; the dsh plugin covers the harness's `read` tool. An agent with direct
+  filesystem access outside both is covered only where its harness routes
+  those calls through a gated seam.
+- **The shell is governed by scope, not by content.** `cat`, `python -c`,
+  `node -e`, a here-doc — the set of programs that can print a file is
+  unbounded, so shell output is never content-inspected. The pilot pack holds
+  the common dumpers (`SEC-005`, `ask`); the honest control for agents that
+  should not need a shell is to deny or hold `proc:spawn`.
+- **Search tools return lines, not files.** `grep`/`glob` results are not
+  content-inspected. Hold them by tool name (`"tool": ["grep"]` → `ask`) where
+  that matters; `docs/pilot-dsh.md` §4 lists this with the rest.
+- **Detection is regex + entropy.** Same floor the mature at-rest scanners
+  stand on; novel unformatted secrets can pass. The engine is an interface,
+  not a ceiling.
+- **Files over 2 MiB**: the MCP mount refuses them (unscannable is unserved);
+  the dsh plugin lets the host's own read proceed uninspected rather than
+  break it, so add a path rule if oversized reads should be stopped.
+- **`ask` today** works where the host has an approval seam (dsh). The
+  env-agnostic native seam is designed in `docs/approvals-native.md`.
+
+## The validation matrix, as shipped tests
+
+| Spec case | Test |
+| --- | --- |
+| Normal file → ALLOW | `packages/dsh/test/secrets.test.ts` · `packages/cli/test/mcp.test.ts` |
+| API key → DENY | both, plus refusal-shape assertions |
+| Private key → DENY | `packages/inspect/test/scan.test.ts` (detector) + pack rule SEC-002 |
+| Below threshold → ALLOW/WARN | dsh test "below the confidence floor" |
+| Retry after deny → structured `retry: false` | both mounts |
+| Every interception → audit event | MCP test "seals a row for allow and deny alike" |
+| Secret never in response or record | asserted byte-for-byte in both mounts |

package/lib/{evaluate-DMyL3qM_.js → evaluate-CkYySl7T.js}

@@ -80,13 +80,16 @@ function segments(command) {
 	const found = [];
 	for (const tokens of scan(command)) {
 		let at = 0;
+		const wrappers = [];
 		while (at < tokens.length) {
 			const token = tokens[at];
 			if (ASSIGNMENT.test(token)) {
 				at += 1;
 				continue;
 			}
-			if (WRAPPERS.has(token)) {
+			const word = (token.split("/").pop() ?? token).toLowerCase();
+			if (WRAPPERS.has(word)) {
+				wrappers.push(word);
 				at += 1;
 				while (at < tokens.length) {
 					const option = tokens[at];
@@ -98,10 +101,19 @@ function segments(command) {
 			break;
 		}
 		const name = tokens[at];
-		if (name === void 0) continue;
+		if (name === void 0) {
+			const last = wrappers.at(-1);
+			if (last !== void 0) found.push({
+				name: last,
+				tokens: [],
+				wrappers
+			});
+			continue;
+		}
 		found.push({
 			name: (name.split("/").pop() ?? name).toLowerCase(),
-			tokens: tokens.slice(at + 1)
+			tokens: tokens.slice(at + 1),
+			wrappers
 		});
 	}
 	return found;
@@ -122,7 +134,7 @@ function commandMatches(match, command) {
 	const args = list(match.token);
 	const pipes = list(match.pipedTo);
 	if (names.length > 0) {
-		const hit = parts.filter((segment) => names.some((pattern) => matches$1(pattern, segment.name)));
+		const hit = parts.filter((segment) => names.some((pattern) => matches$1(pattern, segment.name) || segment.wrappers.some((wrapper) => matches$1(pattern, wrapper))));
 		if (hit.length === 0) return false;
 		if (args.length > 0 && !hit.some((segment) => args.every((wanted) => segment.tokens.some((token) => matches$1(wanted, token))))) return false;
 	} else if (args.length > 0) {

package/lib/index.js

@@ -1,5 +1,5 @@
-import "./evaluate-DMyL3qM_.js";
-import { a as planWrite, i as dshHome, n as applyWrite, o as praeRow, r as defaultProfile, s as profileAt, t as main } from "./cli-DfXHsQO7.js";
+import "./evaluate-CkYySl7T.js";
+import { a as planWrite, i as dshHome, n as applyWrite, o as praeRow, r as defaultProfile, s as profileAt, t as main } from "./cli-Cr0U-PFD.js";
 import "./src-CXU0_W1P.js";
 import "./views-DalPkBZZ.js";
 

package/lib/{mcp-CEN48TpN.js → mcp-Bq0DNPPR.js}

@@ -1,4 +1,4 @@
-import { t as evaluate } from "./evaluate-DMyL3qM_.js";
+import { t as evaluate } from "./evaluate-CkYySl7T.js";
 import { a as scan, n as MAX_SCAN_BYTES } from "./src-Br1tGPtS.js";
 import { readFile, readdir, stat } from "node:fs/promises";
 import { resolve, sep } from "node:path";

package/lib/playground.js

@@ -83,13 +83,16 @@
 		const found = [];
 		for (const tokens of scan(command)) {
 			let at = 0;
+			const wrappers = [];
 			while (at < tokens.length) {
 				const token = tokens[at];
 				if (ASSIGNMENT.test(token)) {
 					at += 1;
 					continue;
 				}
-				if (WRAPPERS.has(token)) {
+				const word = (token.split("/").pop() ?? token).toLowerCase();
+				if (WRAPPERS.has(word)) {
+					wrappers.push(word);
 					at += 1;
 					while (at < tokens.length) {
 						const option = tokens[at];
@@ -101,10 +104,19 @@
 				break;
 			}
 			const name = tokens[at];
-			if (name === void 0) continue;
+			if (name === void 0) {
+				const last = wrappers.at(-1);
+				if (last !== void 0) found.push({
+					name: last,
+					tokens: [],
+					wrappers
+				});
+				continue;
+			}
 			found.push({
 				name: (name.split("/").pop() ?? name).toLowerCase(),
-				tokens: tokens.slice(at + 1)
+				tokens: tokens.slice(at + 1),
+				wrappers
 			});
 		}
 		return found;
@@ -125,7 +137,7 @@
 		const args = list(match.token);
 		const pipes = list(match.pipedTo);
 		if (names.length > 0) {
-			const hit = parts.filter((segment) => names.some((pattern) => matches$1(pattern, segment.name)));
+			const hit = parts.filter((segment) => names.some((pattern) => matches$1(pattern, segment.name) || segment.wrappers.some((wrapper) => matches$1(pattern, wrapper))));
 			if (hit.length === 0) return false;
 			if (args.length > 0 && !hit.some((segment) => args.every((wanted) => segment.tokens.some((token) => matches$1(wanted, token))))) return false;
 		} else if (args.length > 0) {

package/lib/test-run-04ubUcSb.js

@@ -0,0 +1,137 @@
+import { t as evaluate } from "./evaluate-CkYySl7T.js";
+
+//#region src/test-run.ts
+/** The path argument a scenario's call carries, if any. */
+function pathOf(args) {
+	for (const key of [
+		"path",
+		"file_path",
+		"filePath",
+		"target"
+	]) {
+		const value = args[key];
+		if (typeof value === "string" && value !== "") return value;
+	}
+}
+/**
+* Reject a malformed suite by saying what is wrong with it.
+*
+* A test file that silently runs nothing is the worst possible outcome here —
+* it reports success — so every scenario must name a tool and an expected
+* decision, and anything else is an error rather than a default.
+*/
+function parseSuite(parsed) {
+	const errors = [];
+	if (typeof parsed !== "object" || parsed === null) return {
+		ok: false,
+		errors: ["expected a JSON object"]
+	};
+	const root = parsed;
+	const scenarios = root.scenarios;
+	if (!Array.isArray(scenarios) || scenarios.length === 0) return {
+		ok: false,
+		errors: ["`scenarios` must be a non-empty array"]
+	};
+	const kinds = new Set([
+		"allow",
+		"deny",
+		"ask",
+		"correct"
+	]);
+	scenarios.forEach((raw, index) => {
+		const at = `scenarios[${index}]`;
+		if (typeof raw !== "object" || raw === null) {
+			errors.push(`${at}: expected an object`);
+			return;
+		}
+		const s = raw;
+		if (typeof s.name !== "string" || s.name === "") errors.push(`${at}.name: required`);
+		const when = s.when;
+		if (typeof when !== "object" || when === null) errors.push(`${at}.when: required`);
+		else {
+			if (typeof when.tool !== "string" || when.tool === "") errors.push(`${at}.when.tool: required`);
+			if (when.repeat !== void 0 && (typeof when.repeat !== "number" || when.repeat < 1)) errors.push(`${at}.when.repeat: must be a positive number`);
+		}
+		const then = s.then;
+		if (typeof then !== "object" || then === null) errors.push(`${at}.then: required`);
+		else if (typeof then.decision !== "string" || !kinds.has(then.decision)) errors.push(`${at}.then.decision: one of allow, deny, ask, correct`);
+	});
+	if (errors.length > 0) return {
+		ok: false,
+		errors
+	};
+	return {
+		ok: true,
+		suite: {
+			...typeof root.pack === "string" ? { pack: root.pack } : {},
+			scenarios
+		}
+	};
+}
+function runSuite(pack, suite, options) {
+	const results = suite.scenarios.map((scenario) => {
+		const args = scenario.when.args ?? {};
+		const capability = options.capabilityFor(scenario.when.tool);
+		const target = pathOf(args);
+		const findings = target === void 0 || options.inspect === void 0 ? void 0 : options.inspect(target);
+		const decision = evaluate(pack, {
+			tool: scenario.when.tool,
+			...capability === void 0 ? {} : { capability },
+			args,
+			...findings !== void 0 && findings.length > 0 ? { secrets: findings } : {},
+			...capability === void 0 || scenario.when.repeat === void 0 ? {} : { counts: { [capability]: scenario.when.repeat } }
+		});
+		const secretTypes = [...new Set((findings ?? []).map((f) => f.type))];
+		const failures = [];
+		if (decision.kind !== scenario.then.decision) failures.push(`decision was ${decision.kind}, expected ${scenario.then.decision}`);
+		if (scenario.then.rule !== void 0 && decision.rule !== scenario.then.rule) failures.push(`rule was ${decision.rule ?? "none"}, expected ${scenario.then.rule}`);
+		if (scenario.then.secretTypes !== void 0) {
+			const missing = scenario.then.secretTypes.filter((type) => !secretTypes.includes(type));
+			if (missing.length > 0) failures.push(`no finding of type ${missing.join(", ")}`);
+		}
+		return {
+			name: scenario.name,
+			...scenario.given === void 0 ? {} : { given: scenario.given },
+			when: scenario.when,
+			expected: scenario.then,
+			actual: {
+				decision: decision.kind,
+				...decision.rule === void 0 ? {} : { rule: decision.rule },
+				secretTypes
+			},
+			pass: failures.length === 0,
+			failures
+		};
+	});
+	const failed = results.filter((r) => !r.pass).length;
+	return {
+		pack: `${pack.pack} ${pack.version}`,
+		passed: results.length - failed,
+		failed,
+		results,
+		ok: failed === 0
+	};
+}
+/** The report, as lines. Phrased for a reader; the command only prints it. */
+function renderSuite(result) {
+	const lines = [`prae test — ${result.pack}`, ""];
+	const width = Math.max(...result.results.map((r) => r.name.length), 20);
+	for (const r of result.results) {
+		const mark = r.pass ? "✓" : "✕";
+		const shown = r.pass ? `${r.actual.decision.toUpperCase()}${r.actual.rule === void 0 ? "" : `  ${r.actual.rule}`}` : r.failures.join("; ");
+		lines.push(`  ${mark} ${r.name.padEnd(width)}  ${shown}`);
+	}
+	for (const r of result.results.filter((one) => !one.pass)) {
+		lines.push("", `  ✕ ${r.name}`);
+		if (r.given !== void 0) lines.push(`      GIVEN  ${r.given}`);
+		lines.push(`      WHEN   ${r.when.tool}${r.when.repeat === void 0 ? "" : ` ×${r.when.repeat}`} ${JSON.stringify(r.when.args ?? {})}`);
+		lines.push(`      THEN   ${r.expected.decision}${r.expected.rule === void 0 ? "" : ` · ${r.expected.rule}`}`);
+		lines.push(`      GOT    ${r.failures.join("; ")}`);
+	}
+	const n = result.results.length;
+	lines.push("", `${n} scenario${n === 1 ? "" : "s"} · ${result.passed} passed · ${result.failed} failed`, result.ok ? "SECURITY TEST: PASS" : "SECURITY TEST: FAIL");
+	return lines;
+}
+
+//#endregion
+export { parseSuite, renderSuite, runSuite };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "prae-cli",
-  "version": "0.5.1",
-  "description": "Operator policy for agent harnesses: validate packs, explain a decision, verify a decision log, and provision a governed DSH profile.",
+  "version": "0.6.0",
+  "description": "Operator policy for agent harnesses: validate packs, explain a decision, test a pack against security invariants, verify a decision log, and provision a governed DSH profile.",
   "keywords": [
     "dsh-plugin",
     "governance",
@@ -40,10 +40,10 @@
     "tsdown": "^0.15.6",
     "typescript": "^5.9.2",
     "vitest": "^3.2.4",
-    "@prae/extract": "0.1.0",
     "@prae/controls": "0.1.0",
     "@prae/inspect": "0.1.0",
     "@prae/instructions": "0.1.0",
+    "@prae/extract": "0.1.0",
     "@prae/kernel": "0.1.0",
     "@prae/ledger": "0.1.0",
     "@prae/tokens": "0.1.0"