prae-cli 0.1.0 → 0.1.2

package/lib/index.js

@@ -1,3 +1,4 @@
-import { a as planWrite, i as dshHome, n as applyWrite, o as praeRow, r as defaultProfile, s as profileAt, t as main } from "./cli-DGVWMDT0.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-B6X4uAj5.js";
+import "./views-BU0sOciR.js";
 
 export { applyWrite, defaultProfile, dshHome, main, planWrite, praeRow, profileAt };

package/lib/instructions-ijuj4IP1.js

@@ -0,0 +1,133 @@
+import { c as renderShell, o as esc, s as renderNav, t as navFor } from "./views-BU0sOciR.js";
+
+//#region src/console/instructions.ts
+const STYLE = `
+.stack { padding: 22px 30px 8px; }
+.layer {
+  display: grid; grid-template-columns: 92px 1fr 120px; gap: 16px;
+  padding: 12px 0; border-bottom: 1px solid var(--line-faint);
+  font-family: var(--proof); font-size: 12px; align-items: baseline;
+}
+.layer .who { letter-spacing: 0.1em; font-size: 11px; }
+.layer .who.operator { color: var(--signal-text); }
+.layer .who.project { color: var(--muted); }
+.layer .file { color: var(--ink-row); overflow-wrap: anywhere; }
+.layer .count { color: var(--muted); text-align: right; }
+
+.proposal {
+  padding: 20px 30px; border-bottom: 1px solid var(--line);
+  display: grid; grid-template-columns: 1fr 200px; gap: 24px;
+}
+.proposal h3 {
+  font-size: 16px; font-weight: 600; letter-spacing: -0.01em; margin: 0 0 10px;
+}
+.quote {
+  border-left: 2px solid var(--line-strong); padding: 6px 0 6px 14px;
+  font-family: var(--proof); font-size: 12px; color: var(--ink-row);
+  line-height: 1.7; margin: 0 0 10px;
+}
+.quote .where {
+  display: block; color: var(--muted); font-size: 11px; margin-top: 6px;
+}
+.reading { font-size: 13px; color: var(--secondary); margin: 0 0 10px; }
+.matcher {
+  font-family: var(--proof); font-size: 11.5px; color: var(--dim);
+  background: var(--sunk); padding: 8px 10px; border-radius: 2px;
+  overflow-wrap: anywhere;
+}
+.verdict-col { text-align: right; }
+.verdict-col .kind {
+  font-family: var(--proof); font-size: 20px; letter-spacing: 0.08em;
+  font-weight: 600;
+}
+.verdict-col .conf {
+  font-family: var(--proof); font-size: 10px; letter-spacing: 0.12em;
+  color: var(--muted); margin-top: 6px;
+}
+.context-only { padding: 22px 30px 30px; }
+.context-only ul {
+  margin: 10px 0 0; padding-left: 18px; font-size: 13px; line-height: 1.9;
+  color: var(--secondary); columns: 2; column-gap: 40px;
+}
+@media (max-width: 860px) {
+  .proposal { grid-template-columns: 1fr; }
+  .verdict-col { text-align: left; }
+  .context-only ul { columns: 1; }
+}
+@media print { .context-only ul { columns: 1; } }
+`;
+function renderInstructions(data, read, found) {
+	const layers = read.files.map((file) => `      <div class="layer">
+        <div class="who ${esc(file.layer)}">${esc(file.layer.toUpperCase())}</div>
+        <div class="file">${esc(file.path)}</div>
+        <div class="count">${file.sections.reduce((n, s) => n + s.statements.length, 0)} statements</div>
+      </div>`).join("\n");
+	const proposals = found.proposals.map((proposal) => `    <section class="proposal">
+      <div>
+        <h3>${esc(proposal.rule.id)} · ${esc(proposal.rule.title ?? "")}</h3>
+        <blockquote class="quote">${esc(proposal.from.text)}
+          <span class="where">${esc(proposal.from.path)}:${proposal.from.line} · ${esc(proposal.from.layer)}</span>
+        </blockquote>
+        <p class="reading">Read as: ${esc(proposal.why)}.</p>
+        <div class="matcher">${esc(JSON.stringify(proposal.rule.when))}</div>
+      </div>
+      <div class="verdict-col">
+        <div class="kind e-${esc(proposal.rule.effect.kind)}">${esc(proposal.rule.effect.kind.toUpperCase())}</div>
+        <div class="conf">${esc(proposal.confidence.toUpperCase())} CONFIDENCE</div>
+      </div>
+    </section>`).join("\n");
+	const body = `<style>${STYLE}</style>
+    <section class="stats">
+      <div class="stat"><div class="v">${read.files.length}</div><div class="k">FILES</div></div>
+      <div class="stat"><div class="v">${read.statements.length}</div><div class="k">STATEMENTS</div></div>
+      <div class="stat"><div class="v hold">${found.proposals.length}</div><div class="k">PROPOSED</div></div>
+      <div class="stat"><div class="v">${found.skipped.length}</div><div class="k">CONTEXT ONLY</div></div>
+    </section>
+
+    <section class="sect">
+      <h2>Precedence</h2>
+      <p>Least specific first. An operator file is named by the profile and
+      applies to every repository the agent is pointed at; a project file was
+      found by walking up from the work and applies only to the checkout that
+      shipped it.</p>
+    </section>
+    <div class="stack">
+${layers}
+    </div>
+
+    <section class="sect">
+      <h2>Proposed</h2>
+      <p>Nothing here is in force. Each rule is a <em>reading</em> of the
+      sentence beside it, and the only thing that turns a reading into policy
+      is a person putting it in a pack. Read every one against its sentence
+      before it enforces anything.</p>
+    </section>
+${found.proposals.length === 0 ? "    <div class=\"empty\">Nothing was proposed. On most real instruction files that is the expected result, not a failure.</div>" : proposals}
+
+    <section class="context-only">
+      <div class="k" style="font-family:var(--proof);font-size:10px;letter-spacing:0.14em;color:var(--muted)">
+        ${found.skipped.length} STATEMENTS PROPOSED NOTHING AND REMAIN CONTEXT
+      </div>
+      <p style="font-size:13px;color:var(--secondary);max-width:76ch;margin:10px 0 0">
+        Most engineering guidance is about code that gets written, not calls an
+        agent makes. These are served to the agent and sealed into the ledger;
+        they are not enforced, and pretending otherwise would be inventing
+        policy nobody wrote.
+      </p>
+      <ul>
+${found.skipped.slice(0, 40).map((statement) => `        <li>${esc(statement.text)}</li>`).join("\n")}
+      </ul>
+    </section>`;
+	return renderShell({
+		title: "Instructions",
+		nav: renderNav(navFor(data), "Instructions"),
+		head: `    <header class="head">
+      <div><h1>Instructions</h1><div class="meta">${esc(read.hash.slice(0, 16))} · ${read.files.length} files · ${found.proposals.length} proposed, unreviewed</div></div>
+      <div class="actions"><button type="button" class="btn" onclick="window.print()">Export evidence</button></div>
+    </header>`,
+		body
+	});
+}
+
+//#endregion
+export { renderInstructions };

package/lib/src-C5neqxZc.js

@@ -0,0 +1,274 @@
+import { basename, dirname, join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+
+//#region ../instructions/src/parse.ts
+const HEADING = /^(#{1,6})\s+(.*)$/;
+const BULLET = /^\s*(?:[-*+]|\d+[.)])\s+(.*)$/;
+const FENCE = /^\s*(?:```|~~~)/;
+const COMMENT_OPEN = /^\s*<!--/;
+const COMMENT_CLOSE = /-->/;
+/** How far a continuation line must be indented to belong to the bullet above. */
+const CONTINUATION = /^\s{1,}\S/;
+/** Trim, drop emphasis markers that carry no meaning for a reviewer. */
+function clean(text) {
+	return text.trim().replace(/\s+/g, " ");
+}
+/**
+* Parse an instruction file.
+*
+* `.cursorrules` and friends are plain text: every non-empty line is a
+* statement, because there is no structure to read and guessing at one would
+* invent provenance that is not in the file.
+*/
+function parseInstructions(text, format = "markdown") {
+	const hash = createHash("sha256").update(text).digest("hex");
+	const lines = text.split("\n");
+	if (format === "text") {
+		const statements = [];
+		for (const [index, raw] of lines.entries()) {
+			const line = clean(raw);
+			if (line === "" || line.startsWith("#")) continue;
+			statements.push({
+				text: line,
+				line: index + 1,
+				kind: "bullet",
+				headingPath: []
+			});
+		}
+		return {
+			format,
+			text,
+			hash,
+			sections: [{
+				headingPath: [],
+				level: 0,
+				statements
+			}]
+		};
+	}
+	const sections = [];
+	let path = [];
+	let current = {
+		level: 0,
+		statements: []
+	};
+	let currentPath = [];
+	let fenced = false;
+	let commented = false;
+	/** An open bullet, which an indented line below it continues. */
+	let bulletText;
+	/** Consecutive unindented prose lines, which are one wrapped sentence. */
+	let paragraph;
+	const push = (held, kind) => {
+		if (held === void 0) return;
+		const joined = clean(held.text.join(" "));
+		if (joined !== "") current.statements.push({
+			text: joined,
+			line: held.line,
+			kind,
+			headingPath: currentPath
+		});
+	};
+	const flush = () => {
+		push(bulletText, "bullet");
+		bulletText = void 0;
+		push(paragraph, "paragraph");
+		paragraph = void 0;
+	};
+	const flushSection = () => {
+		flush();
+		if (current.heading === void 0 && current.statements.length === 0) return;
+		sections.push({
+			...current.heading === void 0 ? {} : { heading: current.heading },
+			headingPath: currentPath,
+			level: current.level,
+			statements: current.statements
+		});
+	};
+	for (const [index, raw] of lines.entries()) {
+		if (commented) {
+			if (COMMENT_CLOSE.test(raw)) commented = false;
+			continue;
+		}
+		if (COMMENT_OPEN.test(raw)) {
+			flush();
+			if (!COMMENT_CLOSE.test(raw)) commented = true;
+			continue;
+		}
+		if (FENCE.test(raw)) {
+			flush();
+			fenced = !fenced;
+			continue;
+		}
+		if (fenced) continue;
+		const heading = HEADING.exec(raw);
+		if (heading?.[1] !== void 0 && heading[2] !== void 0) {
+			flushSection();
+			const level = heading[1].length;
+			const title = clean(heading[2]);
+			path = [...path.slice(0, level - 1), title];
+			currentPath = path;
+			current = {
+				heading: title,
+				level,
+				statements: []
+			};
+			continue;
+		}
+		const bullet = BULLET.exec(raw);
+		if (bullet?.[1] !== void 0) {
+			flush();
+			bulletText = {
+				text: [bullet[1]],
+				line: index + 1
+			};
+			continue;
+		}
+		if (clean(raw) === "") {
+			flush();
+			continue;
+		}
+		if (bulletText !== void 0 && CONTINUATION.test(raw)) {
+			bulletText.text.push(raw);
+			continue;
+		}
+		push(bulletText, "bullet");
+		bulletText = void 0;
+		if (paragraph === void 0) paragraph = {
+			text: [raw],
+			line: index + 1
+		};
+		else paragraph.text.push(raw);
+	}
+	flushSection();
+	return {
+		format,
+		text,
+		hash,
+		sections
+	};
+}
+/** Every statement in the document, in file order. */
+function statementsOf(doc) {
+	return doc.sections.flatMap((section) => section.statements);
+}
+
+//#endregion
+//#region ../instructions/src/discover.ts
+/** The formats each recognised filename is read as. */
+const FORMATS = {
+	"AGENTS.md": "markdown",
+	"CLAUDE.md": "markdown",
+	".cursorrules": "text",
+	".windsurfrules": "text"
+};
+const DEFAULT_CANDIDATES = Object.keys(FORMATS);
+const DEFAULT_ROOT_MARKERS = [
+	".git",
+	"package.json",
+	"pyproject.toml",
+	"go.mod"
+];
+const DEFAULT_MAX_BYTES = 256 * 1024;
+const DEFAULT_MAX_DEPTH = 24;
+function exists(path) {
+	try {
+		statSync(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Walk up from `from`, collecting instruction files, outermost first.
+*
+* A file larger than `maxBytes` is skipped rather than truncated: half an
+* instruction file is worse than none, because the half that is missing is
+* invisible to whoever reads the result.
+*/
+function discover(from, options = {}) {
+	const candidates = options.candidates ?? DEFAULT_CANDIDATES;
+	const markers = options.rootMarkers ?? DEFAULT_ROOT_MARKERS;
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+	const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+	const dirs = [];
+	let dir = resolve(from);
+	for (let depth = 0; depth < maxDepth; depth += 1) {
+		dirs.push(dir);
+		if (markers.some((marker) => exists(join(dir, marker)))) break;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	const found = [];
+	for (const directory of dirs.reverse()) for (const name of candidates) {
+		const path = join(directory, name);
+		if (!exists(path)) continue;
+		let size;
+		try {
+			size = statSync(path).size;
+		} catch {
+			continue;
+		}
+		if (size > maxBytes) continue;
+		let text;
+		try {
+			text = readFileSync(path, "utf8");
+		} catch {
+			continue;
+		}
+		if (text.trim() === "") continue;
+		found.push({
+			...parseInstructions(text, FORMATS[name] ?? "markdown"),
+			path,
+			name,
+			layer: "project",
+			depth: found.length
+		});
+	}
+	return found;
+}
+
+//#endregion
+//#region ../instructions/src/index.ts
+/**
+* Read every instruction file that governs work at `from`.
+*
+* Ordered least specific to most: operator files first, then project files
+* outermost-in. A reader looking at the stack can see which layer a sentence
+* came from without opening anything.
+*/
+function ingest(from, options = {}) {
+	const operator = [];
+	for (const path of options.operator ?? []) {
+		let text;
+		try {
+			text = readFileSync(path, "utf8");
+		} catch {
+			continue;
+		}
+		if (text.trim() === "") continue;
+		const name = basename(path);
+		operator.push({
+			...parseInstructions(text, FORMATS[name] ?? "markdown"),
+			path,
+			name,
+			layer: "operator",
+			depth: operator.length
+		});
+	}
+	const files = [...operator, ...discover(from, options)];
+	return {
+		files,
+		statements: files.flatMap((file) => statementsOf(file).map((statement) => ({
+			...statement,
+			path: file.path,
+			layer: file.layer
+		}))),
+		hash: createHash("sha256").update(files.map((file) => `${file.layer}:${file.path}:${file.hash}`).join("\n")).digest("hex")
+	};
+}
+
+//#endregion
+export { DEFAULT_CANDIDATES, DEFAULT_ROOT_MARKERS, FORMATS, discover, ingest, parseInstructions, statementsOf };

package/lib/src-Dd2_8m2g.js

@@ -0,0 +1,153 @@
+//#region ../extract/src/index.ts
+/** Backticked or quoted literals, which is where a real path or host appears. */
+function literals(text) {
+	const found = /* @__PURE__ */ new Set();
+	for (const match of text.matchAll(/`([^`]+)`|"([^"]+)"|'([^']+)'/g)) {
+		const value = (match[1] ?? match[2] ?? match[3] ?? "").trim();
+		if (value !== "") found.add(value);
+	}
+	return [...found];
+}
+const PATH_LIKE = /^[./~]|\/$|^[\w.-]+\/|\*\*/;
+const HOST_LIKE = /^(?:https?:\/\/)?([a-z0-9-]+\.)+[a-z]{2,}(?:\/|$)/i;
+function paths(text) {
+	return literals(text).filter((value) => PATH_LIKE.test(value) && !HOST_LIKE.test(value)).map((value) => value.endsWith("/") ? `${value}**` : value);
+}
+function hosts(text) {
+	return literals(text).filter((value) => HOST_LIKE.test(value)).map((value) => value.replace(/^https?:\/\//, "").replace(/\/.*$/, ""));
+}
+/** `PRAE-P01` — proposals are numbered apart from anything hand-written. */
+function id(index) {
+	return `PRAE-P${String(index + 1).padStart(2, "0")}`;
+}
+/**
+* The readings, kept few on purpose.
+*
+* Each one is a phrasing whose meaning is not in doubt *and* which names what
+* it applies to. Adding a looser pattern here trades precision for recall, and
+* the whole value of a proposal is that a reviewer can agree with it in a
+* second without opening the file.
+*/
+const READINGS = [
+	{
+		test: /\bwrites?\b[^.]*\b(?:stay|remain|live|only|confined)\b[^.]*\b(?:in|inside|within|under)\b/i,
+		confidence: "high",
+		why: "names where writes are allowed, so anything outside is not",
+		build: (found) => found.paths.length === 0 ? void 0 : {
+			title: "Writes stay in the workspace",
+			when: {
+				capability: "fs:write",
+				path: { outside: found.paths }
+			},
+			effect: {
+				kind: "deny",
+				because: `writes outside ${found.paths.join(", ")} are not granted in this pack`
+			}
+		}
+	},
+	{
+		test: /\b(?:never|do not|don't|no)\b[^.]*\bwrit\w*\b[^.]*\b(?:outside|beyond|above)\b/i,
+		confidence: "high",
+		why: "forbids writing outside the paths it names",
+		build: (found) => found.paths.length === 0 ? void 0 : {
+			title: "Writes stay in the workspace",
+			when: {
+				capability: "fs:write",
+				path: { outside: found.paths }
+			},
+			effect: {
+				kind: "deny",
+				because: `writes outside ${found.paths.join(", ")} are not granted in this pack`
+			}
+		}
+	},
+	{
+		test: /\b(?:never|do not|don't|no)\b[^.]*\b(?:read|open|access|touch)\b/i,
+		confidence: "high",
+		why: "forbids reading the paths it names",
+		build: (found) => found.paths.length === 0 ? void 0 : {
+			title: "Secrets are not readable",
+			when: {
+				capability: "fs:read",
+				path: { inside: found.paths }
+			},
+			effect: {
+				kind: "deny",
+				because: `reads of ${found.paths.join(", ")} are not granted in this pack`
+			}
+		}
+	},
+	{
+		test: /\bonly\b[^.]*\b(?:fetch|request|call|download)\b[^.]*\bfrom\b/i,
+		confidence: "high",
+		why: "names the only hosts allowed, so any other host is not",
+		build: (found) => found.hosts.length === 0 ? void 0 : {
+			title: "Fetches stay on listed hosts",
+			when: {
+				capability: "net:fetch",
+				host: { notIn: found.hosts }
+			},
+			effect: {
+				kind: "deny",
+				because: `this host is not on the pack allowlist (${found.hosts.join(", ")})`
+			}
+		}
+	},
+	{
+		test: /\b(?:never|do not|don't|no)\b[^.]*\b(?:fetch|request|download|call)\b/i,
+		confidence: "medium",
+		why: "forbids reaching the hosts it names, though the phrasing is broad",
+		build: (found) => found.hosts.length === 0 ? void 0 : {
+			title: "Listed hosts are refused",
+			when: {
+				capability: "net:fetch",
+				host: { in: found.hosts }
+			},
+			effect: {
+				kind: "deny",
+				because: `${found.hosts.join(", ")} is refused by this pack`
+			}
+		}
+	}
+];
+/** Read statements and propose rules. Deterministic; no model involved. */
+function extract(statements, options = {}) {
+	const proposals = [];
+	const skipped = [];
+	for (const statement of statements) {
+		const found = {
+			paths: paths(statement.text),
+			hosts: hosts(statement.text)
+		};
+		let proposed = false;
+		for (const reading of READINGS) {
+			if (!reading.test.test(statement.text)) continue;
+			const built = reading.build(found);
+			if (built === void 0) continue;
+			const effect = options.as === void 0 ? built.effect : {
+				kind: options.as,
+				because: built.effect.because
+			};
+			proposals.push({
+				rule: {
+					id: id(proposals.length),
+					...built,
+					effect
+				},
+				from: statement,
+				confidence: reading.confidence,
+				why: reading.why
+			});
+			proposed = true;
+			break;
+		}
+		if (!proposed) skipped.push(statement);
+	}
+	return {
+		proposals,
+		skipped
+	};
+}
+
+//#endregion
+export { extract };