@sleepy_panda_srl/portulan 0.3.0 → 0.4.1

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,22 +16,19 @@ 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]",
+    "       portulan finish <the same arguments>, where the package is installed",
     "",
     "  -m <text>            a paragraph of the commit message, the first its subject, as git takes -m",
     "  -F <file | ->        the whole commit message, from a file or from standard input",
@@ -124,6 +121,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 +206,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 +315,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 });
@@ -527,7 +543,7 @@ export function draftCard(manifest, read, { workspace, inTree, repoCards = [] })
     }
     section(
         "Records",
-        'Close a change with `git add <new files> && node <plugin root>/cli/finish.mjs -m "<subject>" -m "<why>"` after writing its changelog entry, a one-bullet file `changes/<slug>.<section>.md`: it commits and pushes only when every verify recipe passes.',
+        'Close a change with `git add <new files> && portulan finish -m "<subject>" -m "<why>"` after writing its changelog entry, a one-bullet file `changes/<slug>.<section>.md`: it commits and pushes only when every verify recipe passes. Where `portulan` is not on the path, run `npx @sleepy_panda_srl/portulan finish` instead, and do not search the disk for it.',
         ...(slots.handoffs ? [`A session ending with work not committed and pushed leaves a dated handoff in ${shown(slots.handoffs)}.`] : []),
     );
     section(
@@ -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);