prae-cli 0.5.0 → 0.5.2

package/lib/bin.js

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

package/lib/{cli-ZfwhJKRw.js → cli-DfXHsQO7.js}

@@ -1,4 +1,4 @@
-import { t as evaluate } from "./evaluate-BilZez15.js";
+import { t as evaluate } from "./evaluate-DMyL3qM_.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";
@@ -970,7 +970,7 @@ async function scanFile(path, packPath, json) {
 * not come up inspecting nothing.
 */
 async function mcp(root, packPath, ledgerPath) {
-	const { serveMcp } = await import("./mcp-BH5I4Eyu.js");
+	const { serveMcp } = await import("./mcp-CEN48TpN.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;

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,130 @@
+# 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`.
+
+## 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-BilZez15.js → evaluate-DMyL3qM_.js}

@@ -266,6 +266,42 @@ function hostIn(host, list$1) {
 		return host === want;
 	});
 }
+/**
+* Argument names that conventionally carry a filesystem path, in the order
+* they are tried when a path rule names none.
+*
+* A path rule used to default to the single argument spelled `path`. DeepSeek
+* Harness's own `read`, `write` and `edit` tools pass `file_path`, so every
+* shipped path rule without an explicit `arg` — including the baseline's
+* "deny read ./.env" — matched nothing on the very harness it was written
+* for, while the ledger dutifully recorded every allowed read. A rule that
+* silently never fires is the worst way for policy to be wrong; defaulting
+* to the conventional set is the same call the dsh adapter already made for
+* path resolution, now made once, here, for matching too.
+*/
+const PATH_ARGS = [
+	"path",
+	"file_path",
+	"filePath",
+	"target",
+	"directory",
+	"cwd",
+	"file",
+	"dest",
+	"destination",
+	"source"
+];
+/** The first conventional path argument present, as a string, or undefined. */
+function pathArgOf(args, explicit) {
+	if (explicit !== void 0) {
+		const v = args[explicit];
+		return typeof v === "string" ? v : void 0;
+	}
+	for (const key of PATH_ARGS) {
+		const v = args[key];
+		if (typeof v === "string") return v;
+	}
+}
 
 //#endregion
 //#region ../kernel/src/rule.ts
@@ -319,7 +355,7 @@ function matches(when, facts) {
 		if (!commandMatches(when.command, raw)) return false;
 	}
 	if (when.path !== void 0) {
-		const raw = facts.args[when.path.arg ?? "path"];
+		const raw = pathArgOf(facts.args, when.path.arg);
 		if (typeof raw !== "string") return false;
 		if (when.path.inside !== void 0 && !withinAny(raw, when.path.inside)) return false;
 		if (when.path.outside !== void 0 && withinAny(raw, when.path.outside)) return false;

package/lib/index.js

@@ -1,5 +1,5 @@
-import "./evaluate-BilZez15.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-ZfwhJKRw.js";
+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 "./src-CXU0_W1P.js";
 import "./views-DalPkBZZ.js";
 

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

@@ -1,4 +1,4 @@
-import { t as evaluate } from "./evaluate-BilZez15.js";
+import { t as evaluate } from "./evaluate-DMyL3qM_.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

@@ -269,6 +269,42 @@
 			return host === want;
 		});
 	}
+	/**
+	* Argument names that conventionally carry a filesystem path, in the order
+	* they are tried when a path rule names none.
+	*
+	* A path rule used to default to the single argument spelled `path`. DeepSeek
+	* Harness's own `read`, `write` and `edit` tools pass `file_path`, so every
+	* shipped path rule without an explicit `arg` — including the baseline's
+	* "deny read ./.env" — matched nothing on the very harness it was written
+	* for, while the ledger dutifully recorded every allowed read. A rule that
+	* silently never fires is the worst way for policy to be wrong; defaulting
+	* to the conventional set is the same call the dsh adapter already made for
+	* path resolution, now made once, here, for matching too.
+	*/
+	const PATH_ARGS = [
+		"path",
+		"file_path",
+		"filePath",
+		"target",
+		"directory",
+		"cwd",
+		"file",
+		"dest",
+		"destination",
+		"source"
+	];
+	/** The first conventional path argument present, as a string, or undefined. */
+	function pathArgOf(args, explicit) {
+		if (explicit !== void 0) {
+			const v = args[explicit];
+			return typeof v === "string" ? v : void 0;
+		}
+		for (const key of PATH_ARGS) {
+			const v = args[key];
+			if (typeof v === "string") return v;
+		}
+	}
 
 //#endregion
 //#region ../kernel/src/rule.ts
@@ -322,7 +358,7 @@
 			if (!commandMatches(when.command, raw)) return false;
 		}
 		if (when.path !== void 0) {
-			const raw = facts.args[when.path.arg ?? "path"];
+			const raw = pathArgOf(facts.args, when.path.arg);
 			if (typeof raw !== "string") return false;
 			if (when.path.inside !== void 0 && !withinAny(raw, when.path.inside)) return false;
 			if (when.path.outside !== void 0 && withinAny(raw, when.path.outside)) return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prae-cli",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Operator policy for agent harnesses: validate packs, explain a decision, verify a decision log, and provision a governed DSH profile.",
   "keywords": [
     "dsh-plugin",