@stdd/plugin 0.9.0

package/runtime/cli/path-bytes.mjs

@@ -0,0 +1,83 @@
+import fs from "node:fs";
+import path from "node:path";
+import { escapeNonPrintableSingleLine, isPrintableSingleLine } from "../sdk/text.mjs";
+import { globToRegExp } from "./lib.mjs";
+
+/**
+ * Split a Buffer of NUL-delimited records into per-record Buffers. Git's
+ * `-z` output is raw pathname bytes (a path is any byte sequence but NUL),
+ * so records must be sliced on the byte, never decoded first.
+ */
+export function splitNul(buf) {
+	const out = [];
+	let start = 0;
+	for (let i = 0; i < buf.length; i++) {
+		if (buf[i] === 0) {
+			out.push(buf.subarray(start, i));
+			start = i + 1;
+		}
+	}
+	if (start < buf.length) out.push(buf.subarray(start));
+	return out;
+}
+
+// A git path is arbitrary bytes. Across the review subsystem the byte-exact
+// latin1 decode (a bijection: distinct paths never collapse, ASCII structure
+// — the `/`, `.md`, directory names a glob keys on — is preserved) is the
+// match/dedupe/snapshot key; the UTF-8 view, escaped by displayPath, is what
+// a human reads. A glob is source text (Unicode), so it too is encoded to
+// its byte form before compiling, or a non-ASCII glob literal (docs/über/**)
+// would never match its latin1 pathname.
+export const pathForMatch = (buf) => buf.toString("latin1");
+export const pathForView = (latin1) => Buffer.from(latin1, "latin1").toString("utf8");
+export const latinGlob = (glob) => globToRegExp(Buffer.from(glob, "utf8").toString("latin1"));
+export const absPathBuf = (cwd, latin1) =>
+	Buffer.concat([Buffer.from(`${cwd}/`), Buffer.from(latin1, "latin1")]);
+
+export function parentPathBuf(absolute) {
+	const separator = path.sep.charCodeAt(0);
+	const index = absolute.lastIndexOf(separator);
+	return index === 0 ? absolute.subarray(0, 1) : absolute.subarray(0, index);
+}
+
+export function realPathBuf(value) {
+	return fs.realpathSync(value, { encoding: "buffer" });
+}
+
+export function bufferPathIsWithin(root, candidate) {
+	if (candidate.equals(root)) return true;
+	const separator = Buffer.from(path.sep);
+	const prefix =
+		root.length === separator.length && root.equals(separator) ? root : Buffer.concat([root, separator]);
+	return candidate.length > prefix.length && candidate.subarray(0, prefix.length).equals(prefix);
+}
+
+// Present a path as a quoted literal whenever it contains syntax or a scalar
+// that the shared single-line boundary rejects. Every unsafe scalar is made
+// visible, so a filename cannot split, repaint, hide, or reorder the brief.
+export function displayPath(p) {
+	const escaped = escapeNonPrintableSingleLine(p);
+	if (escaped === p && isPrintableSingleLine(p) && !p.includes('"') && !p.includes("\\")) return p;
+	let quoted = '"';
+	for (const scalar of p) {
+		if (scalar === '"' || scalar === "\\") quoted += `\\${scalar}`;
+		else quoted += escapeNonPrintableSingleLine(scalar);
+	}
+	return `${quoted}"`;
+}
+// The human view of a latin1 (byte-exact) path. A valid-UTF-8 path renders
+// as its text; a path that is not valid UTF-8 is shown byte-escaped and
+// quoted (`"…\xff.md"`), so distinct invalid byte sequences stay
+// distinguishable in the brief instead of both collapsing to U+FFFD.
+export function viewPath(latin1) {
+	const buf = Buffer.from(latin1, "latin1");
+	const utf8 = pathForView(latin1);
+	if (Buffer.from(utf8, "utf8").equals(buf)) return displayPath(utf8);
+	let out = '"';
+	for (const b of buf) {
+		if (b === 0x22 || b === 0x5c) out += `\\${String.fromCharCode(b)}`;
+		else if (b >= 0x20 && b < 0x7f) out += String.fromCharCode(b);
+		else out += `\\x${b.toString(16).padStart(2, "0")}`;
+	}
+	return `${out}"`;
+}

package/runtime/cli/policy.mjs

@@ -0,0 +1,112 @@
+// --- the project policy document: standing decisions, bounded grants ---
+// Policy is durable repository state, not task state: it needs no active task
+// and never touches the ledger. It is tracked, so it is published the way every
+// other tracked file is — identity-bound and atomic, never written in place.
+// Callers translate these errors into CLI diagnostics; the module itself stays
+// testable in process.
+import fs from "node:fs";
+import { resolveWritableRepoPath } from "../sdk/path.mjs";
+import {
+	openNativeRepoMutation,
+	publishNativeRepoFile,
+	readOptionalNativeRepoFile,
+} from "./held-fs.mjs";
+import {
+	appendPolicyNote,
+	appendPolicyPermission,
+	assertPolicyAction,
+	POLICY_ACTIONS,
+	parsePolicy,
+} from "./lib.mjs";
+import { readWorkerMetadata } from "./worker-metadata.mjs";
+
+const POLICY_REL = ".stdd/policy.md";
+
+/**
+ * Apply one append to the policy document. The document is read and republished
+ * inside a single native session: the destination is bound to the identity and
+ * bytes observed at read time, so a concurrent edit or a target swapped after
+ * resolution fails the publication instead of silently losing the other write.
+ */
+async function mutatePolicy(cwd, transform) {
+	// Proven state, not a bare marker: a malformed `.stdd/worker.json` in an
+	// owning checkout must surface as invalid metadata rather than as the false
+	// claim that this is a sandbox.
+	if (readWorkerMetadata(cwd)) {
+		throw new Error(
+			"policy is owned by the source checkout — a managed worker cannot record standing decisions",
+		);
+	}
+	resolveWritableRepoPath(cwd, POLICY_REL, "policy path");
+	const context = await openNativeRepoMutation(cwd, "native filesystem helper for policy");
+	try {
+		const state = await readOptionalNativeRepoFile(context, POLICY_REL, { label: "policy path" });
+		const next = transform(state ? state.bytes.toString("utf8") : "");
+		await publishNativeRepoFile(context, POLICY_REL, next, {
+			mode: 0o644,
+			tempPrefix: ".policy-",
+			directoryMode: 0o755,
+			expectedTarget: state ? state.file.observation.identity : null,
+			...(state ? { expectedBytes: state.bytes } : {}),
+		});
+	} finally {
+		await context.close();
+	}
+	return POLICY_REL;
+}
+
+/**
+ * `stdd policy show` — the enforcing read of the policy document.
+ *
+ * A session must consult policy through this command rather than reading the
+ * markdown itself: the closed action set, the printable-line rule and the
+ * section boundary live in `parsePolicy`, and a reader that skips it is back to
+ * trusting whatever the file happens to say.
+ */
+export function policyShow(cwd) {
+	const target = resolveWritableRepoPath(cwd, POLICY_REL, "policy path");
+	if (!fs.existsSync(target)) {
+		console.log("no project policy recorded — stdd policy add <text> starts one");
+		return 0;
+	}
+	const policy = parsePolicy(fs.readFileSync(target, "utf8"));
+	if (policy.permissions.length === 0) console.log("permissions: none");
+	else {
+		console.log("permissions (verify the condition before acting):");
+		for (const { action, condition } of policy.permissions) {
+			console.log(`  ${action} — when: ${condition}`);
+		}
+	}
+	if (policy.notes.length > 0) {
+		console.log("notes (advisory — they grant nothing):");
+		for (const note of policy.notes) console.log(`  ${note}`);
+	}
+	if (policy.rejected.length > 0) {
+		console.log(
+			`ignored — ${policy.rejected.length} entr${policy.rejected.length === 1 ? "y names" : "ies name"} an action this kit does not know:`,
+		);
+		for (const entry of policy.rejected) console.log(`  ${entry}`);
+		console.log(`  known actions: ${POLICY_ACTIONS.join(", ")}`);
+	}
+	return 0;
+}
+
+/** `stdd policy add <text>` — record project nuance. Grants nothing. */
+export async function policyAdd(cwd, text) {
+	return await mutatePolicy(cwd, (content) => appendPolicyNote(content, text));
+}
+
+/**
+ * `stdd policy allow <action> --when <condition>` — pre-authorize one outward
+ * effect. The action must come from the closed set, and the condition is
+ * mandatory: a grant the session cannot verify is not a grant.
+ */
+export async function policyAllow(cwd, action, condition) {
+	assertPolicyAction(action);
+	if (typeof condition !== "string" || condition.trim() === "") {
+		throw new Error(
+			`every permission names what to verify: policy allow <action> --when "<verifiable condition>"`,
+		);
+	}
+	return await mutatePolicy(cwd, (content) => appendPolicyPermission(content, action, condition.trim()));
+}

package/runtime/cli/recorders.mjs

@@ -0,0 +1,188 @@
+// Checkout docs/run recorders; intentionally independent of the CLI entry module.
+
+import { spawnSync } from "node:child_process";
+import { resolveRepoPath } from "../sdk/path.mjs";
+import { assertPrintableSingleLine } from "../sdk/text.mjs";
+import { loadConfig } from "./config.mjs";
+import {
+	appendLedger,
+	DOCS_DECISIONS,
+	ledgerAppendContext,
+	withCapturedLedgerIdentity,
+} from "./ledger.mjs";
+import { redGenuine } from "./lib.mjs";
+import { fail, MAX_SUBPROCESS_BUFFER } from "./runtime.mjs";
+import { checkoutSnapshot } from "./snapshot.mjs";
+
+const EXCERPT_LIMIT = 2000;
+
+/** `stdd docs <decision> [paths…] [--reason <why>]` — record the docs decision. */
+export function recordDocs(cwd, decision, paths, reason) {
+	if (!DOCS_DECISIONS.includes(decision)) {
+		// Free text is the recurring mistake — answer with the exact forms
+		// and, when a decision word is buried in the prose, the corrected call.
+		const joined = [decision ?? "", ...paths].join(" ");
+		const stem = /not[- ]applicable/i.test(joined)
+			? "not-applicable"
+			: /updated[- ]first/i.test(joined)
+				? "updated-first"
+				: /\bchecked\b/i.test(joined)
+					? "checked"
+					: null;
+		fail(
+			`unknown docs decision "${decision ?? ""}" — the decision is one word, then its arguments:\n` +
+				"  stdd docs updated-first <paths…>\n" +
+				"  stdd docs checked <paths…> --reason <why>\n" +
+				"  stdd docs not-applicable --reason <why>" +
+				(stem ? `\ndid you mean: stdd docs ${stem} …` : ""),
+		);
+	}
+	if (reason !== null) {
+		try {
+			assertPrintableSingleLine(reason, "docs reason");
+		} catch {
+			fail("docs reason must be a non-empty single printable line without control characters");
+		}
+	}
+	if (decision === "not-applicable") {
+		if (paths.length > 0) {
+			fail(
+				"not-applicable takes no paths — put the why into --reason:\n" +
+					'  stdd docs not-applicable --reason "<why implementation-only>"',
+			);
+		}
+		if (!reason) fail("not-applicable needs --reason <why implementation-only>");
+	} else if (paths.length === 0) {
+		fail(`${decision} needs at least one docs path`);
+	}
+	if (decision === "checked" && !reason) {
+		fail("checked needs --reason <why no change is needed>");
+	}
+	for (const docPath of paths) {
+		try {
+			resolveRepoPath(cwd, docPath, `docs path ${JSON.stringify(docPath)}`);
+		} catch (err) {
+			fail(err.message);
+		}
+	}
+	const docsContext = ledgerAppendContext(cwd, { event: "docs" });
+	const event = {
+		event: "docs",
+		decision,
+		paths,
+		snapshot: checkoutSnapshot(cwd),
+		...(reason ? { reason } : {}),
+		...(docsContext.task ? { taskId: docsContext.task.id } : {}),
+	};
+	try {
+		withCapturedLedgerIdentity(
+			cwd,
+			{
+				expectedBranch: docsContext.branch,
+				expectedTaskState: docsContext.taskState,
+				subject: "docs evidence",
+				retry: "stdd docs",
+			},
+			() =>
+				appendLedger(cwd, event, {
+					preserveTaskScope: true,
+					lockHeld: true,
+					expectedBranch: docsContext.branch,
+				}),
+		);
+	} catch (err) {
+		fail(err.message);
+	}
+	console.log(`stdd docs: recorded ${decision}${paths.length ? ` (${paths.join(", ")})` : ""}`);
+}
+
+/**
+ * `stdd red|verify -- <cmd>` — run the command, record {cmd, exit, excerpt}
+ * verbatim, pass the exit code through. Output flows to the caller unchanged.
+ */
+export function recordRun(cwd, kind, argv) {
+	// A single whitespace-carrying word after -- is a description, not a
+	// command — it can never spawn. Reject with the corrected form and
+	// record nothing: prose in the ledger verifies nothing.
+	if (argv.length === 1 && /\s/.test(argv[0])) {
+		fail(
+			`${kind} takes the command and its arguments, never prose — nothing was recorded\n` +
+				`  e.g.:             stdd ${kind} -- pnpm --filter api test\n` +
+				`  shell constructs: stdd ${kind} -- sh -c "<cmd>"`,
+		);
+	}
+	// A recorder must know it can persist the result before it launches a
+	// command with arbitrary side effects.
+	const runContext = ledgerAppendContext(cwd, { event: kind });
+	const config = loadConfig(cwd);
+	const result = spawnSync(argv[0], argv.slice(1), {
+		encoding: "utf8",
+		maxBuffer: MAX_SUBPROCESS_BUFFER,
+	});
+	let exit = result.status ?? 1;
+	let output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+	if (result.error) {
+		exit = 127;
+		output += `${result.error.message}\n`;
+	}
+	if (result.stdout) process.stdout.write(result.stdout);
+	if (result.stderr) process.stderr.write(result.stderr);
+	if (result.error) {
+		console.error(
+			`stdd ${kind}: ${result.error.message}` +
+				(result.error.code === "ENOENT"
+					? " — command not found; is the worktree ready (stdd doctor --readiness)? " +
+						"Shell constructs need sh -c"
+					: ""),
+		);
+	}
+
+	const event = {
+		event: kind,
+		cmd: argv.join(" "),
+		exit,
+		excerpt: output.slice(-EXCERPT_LIMIT),
+		snapshot: checkoutSnapshot(cwd),
+	};
+	if (kind === "red") {
+		event.genuine = redGenuine(exit, output, config.redPattern ?? null);
+		if (exit === 0) {
+			console.error('stdd red: the command exited 0 — that is green, not red (recorded genuine: "no")');
+		} else if (event.genuine === "unknown") {
+			console.error(
+				'stdd red: no redPattern in .stdd/config.json — cannot assert genuine-red (recorded genuine: "unknown")',
+			);
+		} else if (event.genuine === "no") {
+			console.error(
+				'stdd red: output does not match redPattern — this looks like an environment error, not a genuine red (recorded genuine: "no")',
+			);
+		}
+	}
+	try {
+		withCapturedLedgerIdentity(
+			cwd,
+			{
+				expectedBranch: runContext.branch,
+				expectedTaskState: runContext.taskState,
+				subject: `${kind} result`,
+				retry: `stdd ${kind}`,
+			},
+			() =>
+				appendLedger(
+					cwd,
+					{
+						...event,
+						...(runContext.task ? { taskId: runContext.task.id } : {}),
+					},
+					{
+						preserveTaskScope: true,
+						lockHeld: true,
+						expectedBranch: runContext.branch,
+					},
+				),
+		);
+	} catch (err) {
+		fail(err.message);
+	}
+	process.exit(exit);
+}