@sleepy_panda_srl/portulan 0.2.0 → 0.4.0

package/cli/drills.mjs

@@ -13,10 +13,11 @@ import { isInside } from "./inside.mjs";
 import { recipeSet, resolverFor } from "./recipe-set.mjs";
 
 const RAIL_TIMEOUT_MS = 10 * 60 * 1000;
+const RAIL_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
 
 export const DRILL_SESSION_PREFIX = "portulan-drill";
 
-/** Hooks answer in their stdout JSON and exit 0 either way, so their drills judge by a tell read from stdout. */
+/** Hook drills judge stdout JSON: exit 0 carries either verdict. */
 export const NON_RECIPE_RAILS = [
     {
         id: "stop-gate",
@@ -54,7 +55,7 @@ export const NOT_DRILLED = [
         why: "deliberately not a verify recipe — `../.portulan/identity.md` argues why: CI installs nothing, so declaring it would make a recipe that exits 2 on every run. It is checked at the supervised checkpoints and before a release, which is a rail on no calendar, and that cost is already stated in `../.portulan/verify/README.md`.",
     },
     {
-        rail: "Dependabot, the `copilot auto-review` ruleset, and `pr-labels`",
+        rail: "Dependabot and `pr-labels`",
         why: "platform watchers whose triggering condition is an event this repository cannot manufacture on a schedule. `0007`'s own honest limit applies — not every watcher can be forced red safely — and each carries its own recorded observation instead.",
     },
     {
@@ -63,9 +64,20 @@ export const NOT_DRILLED = [
     },
 ];
 
-/** A rail that reads only the index misses a created file unless the drill sets `stage`. */
+/** Index-only rails need `stage` for a created file. */
 export const DRILLS = [
-    // ------------------------------------------------------------------------- the yielded recipes
+    {
+        rail: "cache-stability",
+        perturb: {
+            file: ".claude/rules/portulan/boot.md",
+            find: "# Portulan boot card",
+            replace: "# Portulan boot card\n\nCurrent date: 2099-12-31",
+        },
+        exit: 1,
+        tell: "differ from the committed golden",
+        why: "A volatile prefix change must require review of the committed baseline (#516), even when two renders agree.",
+    },
+    // The yielded recipes
     {
         rail: "docs",
         perturb: {
@@ -163,7 +175,7 @@ export const DRILLS = [
         },
         exit: 1,
         tell: "fixture(s) failed",
-        why: "The jq programs the merge gates branch on are executed rather than described. A filter that silently changed shape would take the label gate down with it.",
+        why: "The jq programs the label gate branches on are executed rather than described. A filter that silently changed shape would take the label gate down with it.",
     },
     {
         rail: "index",
@@ -199,6 +211,17 @@ export const DRILLS = [
         tell: "does not reproduce",
         why: "The host writes one usage record per content block, so a reader that stops deduplicating by message id multiplies every figure by the blocks per request and still prints plausible numbers. The fixture's known totals are the only thing that tells those numbers from the true ones.",
     },
+    {
+        rail: "ledger",
+        perturb: {
+            file: "cli/ledger.mjs",
+            find: "if (!calls.has(result.call)) continue;",
+            replace: "if (result.call === null) continue;",
+        },
+        exit: 1,
+        tell: "✗ fixture: local is",
+        why: "A local worker's subagent reports its receipt back to the session that delegated it, so a reader that takes a receipt from any tool result counts the same local work twice, once from the Bash call that ran it and once from the report quoting it, and the hybrid line still reads like a figure. Only the hybrid fixture's known receipt count tells the two apart.",
+    },
     {
         rail: "control-chars",
         perturb: {
@@ -248,7 +271,7 @@ export const DRILLS = [
         rail: "pack-identity",
         perturb: {
             file: "README.md",
-            find: "**Current release: `0.2.0`**",
+            find: "**Current release: `0.4.0`**",
             replace: "**Current release: `0.1.3`** <!-- the drill edited this and did not stage it -->",
         },
         stage: false,
@@ -332,7 +355,7 @@ export const DRILLS = [
         rail: "version-carriers",
         perturb: {
             file: "README.md",
-            find: "**Current release: `0.2.0`**",
+            find: "**Current release: `0.4.0`**",
             replace: "**Current release: `0.1.3`**",
         },
         // Staged: this rail reads the index (`git show :<path>`), so an unstaged edit is invisible to it.
@@ -374,6 +397,17 @@ export const DRILLS = [
         tell: "invokes cli/review-meter.mjs --fetch",
         why: "A verify recipe that can reach the network goes red about the world rather than about the tree, and this repository prohibits it in three carriers while nothing checked it. The drill proves the checker sees a real invocation — spread across continued lines, the spelling a recipe actually uses — rather than only the literal string a test would hand it.",
     },
+    {
+        rail: "telemetry",
+        perturb: {
+            file: ".portulan/verify/doctor.sh",
+            find: "node cli/doctor.mjs --static --pack-root packs",
+            replace: "node cli/doctor.mjs --pack-root packs",
+        },
+        exit: 1,
+        tell: "invokes cli/doctor.mjs without an immediate --static",
+        why: "Doctor reads local usage records by default. Removing static mode from its recipe must fail the source audit before verification can depend on this machine's records. The drill runs telemetry, never the altered doctor recipe; filesystem-denial tests separately prove the static runtime path does not consult usage files.",
+    },
     {
         rail: "ab",
         perturb: {
@@ -458,8 +492,19 @@ export const DRILLS = [
         tell: "is a tag or branch, not a commit",
         why: "The composed pack's own rail, drilled from the adopting workspace exactly as a workspace-owned one is — which is the property milestone 7's composition amendment bought and nothing else here re-checks.",
     },
+    {
+        rail: "tools/local-llm:runner-rails",
+        perturb: {
+            file: "packs/tools/local-llm/runner/local-llm.mjs",
+            find: "    if (!allowRemote && !LOOPBACK_HOSTS.has(parsed.hostname.toLowerCase())) {",
+            replace: "    if (!allowRemote && false) {",
+        },
+        exit: 1,
+        tell: "non-loopback endpoint was not refused by assertLoopback",
+        why: "Loopback is the rail that keeps a local worker's context on the machine, and the runner holds it in code rather than in any permission rule the compiler emits, so a guard that stopped refusing would leave every other rail green. The drill removes the refusal and requires the pack's own recipe to see it.",
+    },
 
-    // ------------------------------------------------------- the coverage rail, which is itself a rail
+    // The coverage rail, which is itself a rail
     {
         rail: "drills",
         perturb: {
@@ -475,7 +520,7 @@ export const DRILLS = [
         why: "The allow-list is what stops a misspelled recipe id being silently reclassified as a rail of its own, leaving the real recipe undrilled while the coverage check reports green. A drill naming a rail nothing yields is the shortest path to that state.",
     },
 
-    // ------------------------------------------------------------------------- the two non-recipe rails
+    // The two non-recipe rails
     {
         rail: "stop-gate",
         perturb: {
@@ -817,6 +862,7 @@ function runRail({ rail, worktree, stdin, workspaceRel }) {
             // After the spread, so a drill's own `cwd` cannot point the hook at another tree.
             input: `${JSON.stringify({ ...payload, cwd: worktree })}\n`,
             timeout: RAIL_TIMEOUT_MS,
+            maxBuffer: RAIL_MAX_BUFFER_BYTES,
             // Set, never inherited: the hooks read their tree and workspace from these two.
             env: { ...process.env, CLAUDE_PROJECT_DIR: worktree, PORTULAN_WORKSPACE: workspaceRel },
         });
@@ -828,6 +874,7 @@ function runRail({ rail, worktree, stdin, workspaceRel }) {
         cwd: worktree,
         encoding: "utf8",
         timeout: RAIL_TIMEOUT_MS,
+        maxBuffer: RAIL_MAX_BUFFER_BYTES,
     });
     if (result.error) throw new CouldNotRun(`rail \`${rail.id}\` could not run — ${result.error.message}`);
     return { status: result.status, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };

package/cli/finish.md

@@ -0,0 +1,34 @@
+# Finish verification boundaries
+
+Finish resolves the recipe set before staging tracked changes or creating its
+provisional commit. An empty result from `treeRoots` asks for normal recipe-set
+resolution; it does not mean verification succeeded without any recipes.
+
+| Workspace and roots | Behavior |
+| --- | --- |
+| No composed packs | The tree's pack directories are not probed. Declared workspace recipes still run. |
+| Tree roots contain every composed pack | Finish names those roots, avoiding an installed copy shadowing the tree. |
+| Tree roots are absent, empty or incomplete | Normal recipe-set resolution and its shadow checks apply. An installed pack can supply the missing recipes; an unresolved pack refuses the operation before commit. |
+| Explicit `--pack-root <directory>` | Only the named roots are used. Missing directories are refused, and missing packs do not fall back to an installed copy. |
+
+The controls in `finish.test.mjs` cover these cases. For an absent tree directory,
+the installed-pack fixture compares recipe-set's yielded identities against actual
+execution markers. The unavailable-pack fixture checks that no commit hook ran and
+that HEAD, the index, the worktree and the remote branch remain unchanged.
+
+Bash parse failures are **could not run**, with exit 2 and the diagnostic included
+in finish's report. A provisional commit made before the recipes ran is undone and
+its changes stay staged; nothing is pushed. Both tested recipe forms parse after
+the wrapper's `exec 2>&1` redirection. These controls do not demonstrate coverage
+of Bash startup failures.
+
+The manifest recipe format rejects newlines, carriage returns and tabs before
+Bash runs. The CLI controls therefore use a single-line missing `fi` and a leading
+`)`. Line numbers can differ between Bash versions. These are Bash's wrapper-script
+diagnostics, not a general promise to translate recipe line numbers.
+The historical two-line example in the review follow-up can be passed directly to
+`runRecipe`, but is not accepted as a current manifest recipe.
+
+This reference records concrete boundaries investigated for the historical review
+follow-up. That review posted no findings identifying a different empty-root case;
+these controls do not establish what its unspecified concern meant.

package/cli/finish.mjs

@@ -8,7 +8,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { spawn, spawnSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
 
 import { AUTO, discoverPackRoots, namedWithAuto } from "./discover.mjs";
@@ -16,19 +16,15 @@ import { packRoots, resolvePack } from "./compile.mjs";
 import { CHANGES_DIR, CHANGES_README } from "./form.mjs";
 import { CHANGE_NAME } from "./index.mjs";
 import { recipeSet, resolverFor } from "./recipe-set.mjs";
+import { INTERRUPTIONS, runRecipe, tailKeeper } from "./recipe-runner.mjs";
+export { runRecipe, tailKeeper };
 
 export const RECIPE_TIMEOUT_MS = 10 * 60 * 1000;
 
 export const TAIL_LINES = 25;
 
-const TAIL_BYTES = 64 * 1024;
-
-const DRAIN_MS = 1000;
-
 const GIT_TIMEOUT_MS = 2 * 60 * 1000;
 
-const CANNOT_RUN = new Set([2, 126, 127]);
-
 const USAGE = [
     "usage: node cli/finish.mjs -m <subject> [-m <paragraph>]... [options]",
     "       node cli/finish.mjs -F <file | -> [options]",
@@ -124,6 +120,9 @@ const textOf = (thrown) => {
 };
 
 const resultOf = (id, r) => {
+    if (INTERRUPTIONS.includes(r?.interrupted)) {
+        return { id, outcome: "could not run", code: null, interrupted: r.interrupted, output: typeof r.output === "string" ? r.output : `interrupted by ${r.interrupted}` };
+    }
     if (r?.outcome === "green") return { id, outcome: "green" };
     if (r?.outcome === "red" || r?.outcome === "could not run") {
         return { id, outcome: r.outcome, code: Number.isInteger(r.code) ? r.code : null, output: typeof r.output === "string" ? r.output : "" };
@@ -206,65 +205,6 @@ export function recipesOf({ root, workspaceDir, named, forced }) {
     return set.ok ? { recipes: set.recipes } : { why: set.reason };
 }
 
-/** A stream's last `limit` bytes, kept as it arrives: what is held never passes `limit` and one chunk. */
-export function tailKeeper(limit = TAIL_BYTES) {
-    const chunks = [];
-    let held = 0;
-    return {
-        add(chunk) {
-            chunks.push(chunk);
-            held += chunk.length;
-            while (held - chunks[0].length >= limit) held -= chunks.shift().length;
-        },
-        get held() {
-            return held;
-        },
-        text: () => Buffer.concat(chunks).subarray(-limit).toString("utf8"),
-    };
-}
-
-export function runRecipe(recipe, { root, env, timeout = RECIPE_TIMEOUT_MS }) {
-    return new Promise((resolve) => {
-        const kept = tailKeeper();
-        let failure = null;
-        let late = false;
-        let limit;
-        let drain;
-        const settle = (status) => {
-            clearTimeout(limit);
-            clearTimeout(drain);
-            const code = failure || late ? null : status;
-            if (code === 0) return resolve({ id: recipe.id, outcome: "green" });
-            const why = failure ? `\n${failure.message}` : late ? `\nkilled at its time limit of ${timeout / 1000} s` : "";
-            const cannot = code === null || CANNOT_RUN.has(code);
-            resolve({ id: recipe.id, outcome: cannot ? "could not run" : "red", code, output: `${kept.text()}${why}` });
-        };
-        // As CI and the Stop-gate run a recipe, its stderr joined to its stdout so its lines keep their order.
-        const child = spawn("bash", ["-c", `exec 2>&1\n${recipe.run}`], { cwd: root, env, stdio: ["ignore", "pipe", "pipe"] });
-        const stop = () => {
-            child.stdout.destroy();
-            child.stderr.destroy();
-        };
-        child.stdout.on("data", kept.add);
-        child.stderr.on("data", kept.add);
-        child.on("exit", () => {
-            clearTimeout(limit);
-            // A process the shell left running is not waited for: once the pipe closes, the child's next write kills it with SIGPIPE, or fails with EPIPE where it ignores that signal, and a child that never writes keeps running.
-            drain = setTimeout(stop, DRAIN_MS);
-        });
-        child.on("error", (error) => {
-            failure = error;
-            settle(null);
-        });
-        child.on("close", settle);
-        limit = setTimeout(() => {
-            late = true;
-            child.kill();
-            stop();
-        }, timeout);
-    });
-}
-
 /** Resolves to `{ code, lines }`: the exit code and what to print, the first line saying what happened. */
 export async function finish(options, { cwd = process.cwd(), env = process.env, readStdin, runOne = runRecipe } = {}) {
     const stop = (code, ...lines) => ({ code, lines: [`finish: ${lines[0]}`, ...lines.slice(1)] });
@@ -374,10 +314,11 @@ export async function finish(options, { cwd = process.cwd(), env = process.env,
         } catch (error) {
             results.push({ id: recipe.id, outcome: "could not run", code: null, output: textOf(error) });
         }
+        if (results.at(-1).interrupted) break;
     }
     const failed = results.filter((r) => r.outcome !== "green");
     if (failed.length) {
-        const code = failed.some((r) => r.outcome === "red") ? 1 : 2;
+        const code = failed.some((r) => r.interrupted) ? 2 : failed.some((r) => r.outcome === "red") ? 1 : 2;
         const named = failed.map((r) => r.id).join(", ");
         return stop(
             code,

package/cli/form.mjs

@@ -10,6 +10,7 @@ import { BOOT_CARD_LINE, BOOT_CARD_UNIT, GUIDANCE_RULES_DIR, leadsOfText } from
 import { CHANGE_SECTIONS, readChanges, renderChanges } from "./index.mjs";
 import { instructionsState, shellWord, splitCommand } from "./instructions.mjs";
 import { recipeSet } from "./recipe-set.mjs";
+import { isInside } from "./inside.mjs";
 
 /** Anything that means the form could not be read. Carries no verdict. */
 export class FormError extends Error {}
@@ -40,12 +41,23 @@ function present(file) {
     }
 }
 
-function readOrNull(file) {
+function readOrNull(file, boundary) {
     try {
-        return fs.readFileSync(file, "utf8");
+        fs.lstatSync(file);
     } catch (cause) {
         if (cause.code === "ENOENT" || cause.code === "ENOTDIR") return null;
-        throw new FormError(`${file} could not be read — ${cause.code ?? cause.message}`);
+        throw new FormError(`${file} could not be inspected — ${cause.code ?? "read error"}`);
+    }
+    try {
+        const real = fs.realpathSync(file);
+        if (!isInside(fs.realpathSync(boundary), real)) throw new FormError(`${file} is outside the form's source boundary`);
+        if (!fs.statSync(real).isFile()) throw new FormError(`${file} is not a regular form source`);
+        const raw = fs.readFileSync(real), text = raw.toString("utf8");
+        if (!Buffer.from(text, "utf8").equals(raw)) throw new FormError(`${file} is not valid UTF-8`);
+        return text;
+    } catch (cause) {
+        if (cause instanceof FormError) throw cause;
+        throw new FormError(`${file} could not be read — ${cause.code ?? "read error"}`);
     }
 }
 
@@ -87,7 +99,9 @@ export function handoffsReadme() {
 A handoff carries work still open, so the next session starts from where things stand. Write one only
 when a session ends with work not committed and pushed: committed work carries its why in its commit
 message, and needs none. Name it \`YYYY-MM-DD-<slug>.md\`, keep only the parts that have something to say,
-and five lines is a valid handoff. Drafted from the engine's \`core/templates/handoff.md\`.
+and five lines is a valid handoff. The H1 names the outcome; the filename already gives its date.
+Link measured figures and durable rules in their owning records. Keep decisions and their why when
+compressing to a declared token cap. Drafted from the engine's \`core/templates/handoff.md\`.
 
 **State.** Where things stand: what is committed, and what is in progress and uncommitted.
 
@@ -108,12 +122,14 @@ export function handoffIndexIgnore(rel, workspaceRel) {
 }
 
 export function withIgnoreLines(text, lines) {
-    const have = new Set((text ?? "").split(/\r?\n/).map((l) => l.trim()));
-    const patterns = lines.filter((l) => !l.startsWith("#"));
-    if (patterns.every((l) => have.has(l))) return text ?? "";
-    const base = text ?? "";
-    const sep = base === "" ? "" : base.endsWith("\n\n") ? "" : base.endsWith("\n") ? "\n" : "\n\n";
-    return `${base}${sep}${lines.join("\n")}\n`;
+    const bytes = Buffer.isBuffer(text), base = text ?? "";
+    const existing = bytes ? base.toString("latin1") : base;
+    const have = new Set(existing.split(/\r?\n/).map(l => bytes ? l.replace(/^[ \t\r]+|[ \t\r]+$/g, "") : l.trim()));
+    const patterns = lines.filter(l => !l.startsWith("#"));
+    if (patterns.every(l => have.has(bytes ? Buffer.from(l).toString("latin1") : l))) return base;
+    const sep = existing === "" || existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+    const addition = `${sep}${lines.join("\n")}\n`;
+    return bytes ? Buffer.concat([base, Buffer.from(addition)]) : base + addition;
 }
 
 export const COMMENTS_RECIPE = "comments";
@@ -181,9 +197,9 @@ exit 2
 
 // ------------------------------------------------------------------------- git
 
-export function gitIn(root) {
+export function gitIn(root, { env, timeout, noFsmonitor = false } = {}) {
     const run = (...args) => {
-        const out = spawnSync("git", ["-C", root, ...args], { encoding: "utf8" });
+        const out = spawnSync("git", [...(noFsmonitor ? ["-c", "core.fsmonitor=false"] : []), "-C", root, ...args], { encoding: "utf8", timeout, killSignal: "SIGKILL", env });
         if (out.error) return { status: null, stdout: "", stderr: String(out.error.code ?? out.error.message) };
         return { status: out.status, stdout: out.stdout, stderr: out.stderr };
     };
@@ -296,7 +312,7 @@ export function markdownOnDisk(root, keep = null) {
 export function sessionLogsIn(root, files) {
     const found = [];
     for (const rel of files) {
-        const text = readOrNull(path.join(root, ...rel.split("/")));
+        const text = readOrNull(path.join(root, ...rel.split("/")), root);
         if (text === null || !text.includes("Session log")) continue;
         const logs = sessionLogSections(text).filter((s) => s.entries);
         if (logs.length) found.push({ file: rel, line: logs[0].line });
@@ -567,7 +583,7 @@ export function formOf(workspaceDir, manifest) {
     const tree = typeof manifest?.tree === "string" ? path.resolve(wsDir, manifest.tree) : null;
     if (tree === null) return { tree, pieces };
 
-    const changelog = readOrNull(path.join(tree, CHANGELOG));
+    const changelog = readOrNull(path.join(tree, CHANGELOG), tree);
     const fragments = present(path.join(tree, CHANGES_README));
     if (changelog !== null || fragments) add("changes", fragments ? "new" : "today", fragments ? `changelog fragments in ${CHANGES_DIR}/` : `no ${CHANGES_README}`);
     const entries = changelog === null ? null : unreleasedCount(changelog);
@@ -593,16 +609,16 @@ export function formOf(workspaceDir, manifest) {
         if (typeof context !== "string") {
             add("card", "today", "no boot card: `slots.context` is undeclared");
         } else {
-            const source = readOrNull(path.resolve(wsDir, context, `${BOOT_CARD_UNIT}.md`));
+            const source = readOrNull(path.resolve(wsDir, context, `${BOOT_CARD_UNIT}.md`), wsDir);
             if (source === null) add("card", "new", "no boot card, by choice: `slots.context` holds no `boot` unit");
             else if (withReading(source) !== null) add("card", "today", "a boot card drafted before it carried the engine's rules on reading and the cache");
             else if (!carriesReading(source)) {
                 pieces.push({ id: "card", state: "today", hand: true, text: `a boot card without the engine's rules on reading and the cache, whose head \`upgrade\` does not recognise: add a section holding the line \`${READING_LINE}\`` });
-            } else if (readOrNull(path.join(tree, COMPILED_CARD)) !== null) add("card", "new", "a compiled boot card");
-            else if ((readOrNull(path.join(tree, "AGENTS.md")) ?? "").split(/\r?\n/).includes(BOOT_CARD_LINE)) add("card", "new", "a boot card at the head of AGENTS.md, which this host reads");
+            } else if (readOrNull(path.join(tree, COMPILED_CARD), tree) !== null) add("card", "new", "a compiled boot card");
+            else if ((readOrNull(path.join(tree, "AGENTS.md"), tree) ?? "").split(/\r?\n/).includes(BOOT_CARD_LINE)) add("card", "new", "a boot card at the head of AGENTS.md, which this host reads");
             else add("card", "today", `a boot card not yet compiled to ${COMPILED_CARD}: run \`portulan compile\``);
         }
-        const marked = instructionsState(tree, (rel) => readOrNull(path.join(tree, ...rel.split("/"))));
+        const marked = instructionsState(tree, (rel) => readOrNull(path.join(tree, ...rel.split("/")), tree));
         if (marked.files.length) {
             const files = marked.files.join(" and ");
             const count = (n) => `${n} section${n === 1 ? "" : "s"}`;

package/cli/frontmatter.mjs

@@ -0,0 +1,39 @@
+// Flat frontmatter for plugin components and host bindings.
+
+const BLOCK_SCALAR = /^[|>][+-]?$/;
+
+/** A flat-YAML reader: `fields` is null without a usable block, and `error` is set when that is a defect. */
+export function parseFrontmatter(text) {
+    const lines = text.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---") return { fields: null };
+
+    const close = lines.indexOf("---", 1);
+    if (close === -1) {
+        return { fields: null, error: "the frontmatter block is never closed" };
+    }
+
+    const fields = {};
+    const body = lines.slice(1, close);
+    for (let i = 0; i < body.length; i += 1) {
+        const match = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(body[i]);
+        if (!match) continue;
+        const key = match[1];
+        let value = match[2].trim();
+
+        if (BLOCK_SCALAR.test(value)) {
+            const collected = [];
+            while (i + 1 < body.length && (body[i + 1].trim() === "" || /^\s+/.test(body[i + 1]))) {
+                i += 1;
+                collected.push(body[i].trim());
+            }
+            value = collected.join(" ").trim();
+        } else if (
+            (value.startsWith('"') && value.endsWith('"') && value.length >= 2) ||
+            (value.startsWith("'") && value.endsWith("'") && value.length >= 2)
+        ) {
+            value = value.slice(1, -1);
+        }
+        fields[key] = value;
+    }
+    return { fields };
+}

package/cli/gate.mjs

@@ -7,7 +7,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { pathToFileURL } from "node:url";
 
 import { matchesRule, policyPath, packContributions, composeFragments, parse } from "./compile.mjs";
 
@@ -64,17 +64,19 @@ async function main() {
     const rule = decide(payload, yielded(policy));
     if (!rule) stepAside();
 
-    const decision = rule.tier === "prohibited" ? "deny" : "ask";
-    process.stdout.write(
-        `${JSON.stringify({
-            hookSpecificOutput: {
-                hookEventName: "PreToolUse",
-                permissionDecision: decision,
-                permissionDecisionReason: `PORTULAN GATE \`${rule.id}\` (${rule.tier}) — ${rule.reason}`,
-            },
-        })}\n`,
-    );
+    process.stdout.write(`${gateOutput(rule)}\n`);
     process.exit(0);
 }
 
-main().catch(stepAside);
+export function gateOutput(rule) {
+    if (!rule) return null;
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: rule.tier === "prohibited" ? "deny" : "ask",
+            permissionDecisionReason: `PORTULAN GATE \`${rule.id}\` (${rule.tier}) — ${rule.reason}`,
+        },
+    });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) main().catch(stepAside);