chamba 0.6.0 → 0.7.0

package/templates/pane-apps/server/specs.mjs

@@ -0,0 +1,1588 @@
+import { closeSync, constants, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+//#region src/specs/contracts/index.ts
+/** Where the tool keeps everything it writes, inside a piece of work. */
+var TOOL_DIR = ".specs";
+/** The reader's own marks and drafts for one piece of work. */
+var STATE_FILE = "reader-state.json";
+/** The user's feedback, written by the tool and applied by an agent. */
+var FEEDBACK_FILE = "user-feedback.json";
+/** Assets referenced from the feedback file, relative to the tool's directory. */
+var FEEDBACK_ASSETS_DIR = "user-feedback-assets";
+var DEFAULT_TOOLBAR = {
+	textScale: 1,
+	contentWidth: 1100,
+	theme: "dark"
+};
+function emptyState() {
+	return {
+		version: 1,
+		units: {},
+		overallDraft: "",
+		dismissed: [],
+		toolbar: { ...DEFAULT_TOOLBAR }
+	};
+}
+function emptyFeedback(entry) {
+	return {
+		version: 1,
+		entry,
+		rounds: []
+	};
+}
+var isObject$2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var str$2 = (value, fallback = "") => typeof value === "string" ? value : fallback;
+var num = (value, fallback) => typeof value === "number" && Number.isFinite(value) ? value : fallback;
+/**
+* Read the reader's state from whatever is on disk. Anything missing,
+* unreadable or written under a version this tool does not know reads as empty
+* state, so a corrupt or future file costs the user their marks and drafts and
+* nothing more.
+*/
+function readState$1(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw || "null");
+	} catch {
+		return emptyState();
+	}
+	if (!isObject$2(parsed) || parsed.version !== 1) return emptyState();
+	const state = emptyState();
+	if (isObject$2(parsed.units)) for (const [id, value] of Object.entries(parsed.units)) {
+		if (!isObject$2(value)) continue;
+		const unit = {};
+		if (typeof value.readHash === "string") unit.readHash = value.readHash;
+		if (typeof value.readAt === "string") unit.readAt = value.readAt;
+		if (typeof value.draft === "string") unit.draft = value.draft;
+		state.units[id] = unit;
+	}
+	state.overallDraft = str$2(parsed.overallDraft);
+	if (Array.isArray(parsed.dismissed)) state.dismissed = parsed.dismissed.filter((id) => typeof id === "string");
+	if (isObject$2(parsed.toolbar)) state.toolbar = {
+		textScale: num(parsed.toolbar.textScale, DEFAULT_TOOLBAR.textScale),
+		contentWidth: num(parsed.toolbar.contentWidth, DEFAULT_TOOLBAR.contentWidth),
+		theme: parsed.toolbar.theme === "light" ? "light" : DEFAULT_TOOLBAR.theme
+	};
+	return state;
+}
+/**
+* Read a feedback file the tool wrote earlier and is about to merge into. An
+* unreadable or unknown-version file reads as empty for the given entry: a new
+* submit then starts a fresh file rather than appending to something the
+* applying agent could not make sense of.
+*/
+function readFeedback(raw, entry) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw || "null");
+	} catch {
+		return emptyFeedback(entry);
+	}
+	if (!isObject$2(parsed) || parsed.version !== 1) return emptyFeedback(entry);
+	const rounds = [];
+	if (Array.isArray(parsed.rounds)) for (const round of parsed.rounds) {
+		if (!isObject$2(round)) continue;
+		const comments = [];
+		if (Array.isArray(round.comments)) for (const comment of round.comments) {
+			if (!isObject$2(comment) || typeof comment.unit !== "string") continue;
+			const assets = [];
+			if (Array.isArray(comment.assets)) for (const asset of comment.assets) {
+				if (!isObject$2(asset) || typeof asset.path !== "string") continue;
+				assets.push({
+					path: asset.path,
+					name: str$2(asset.name, asset.path),
+					type: str$2(asset.type)
+				});
+			}
+			comments.push({
+				unit: comment.unit,
+				file: str$2(comment.file),
+				heading: str$2(comment.heading),
+				kind: comment.kind === "remove" ? "remove" : "comment",
+				quote: str$2(comment.quote),
+				text: str$2(comment.text),
+				assets
+			});
+		}
+		rounds.push({
+			submittedAt: str$2(round.submittedAt),
+			comments
+		});
+	}
+	return {
+		version: 1,
+		entry: str$2(parsed.entry, entry),
+		rounds
+	};
+}
+//#endregion
+//#region src/specs/contracts/protocol.ts
+var SPEC_STATE_FILE = "state.json";
+/**
+* Every stage a protocol may hold, in the one order every view uses.
+*
+* This is the list the agent composes a recommendation over. It is data rather
+* than something an agent remembers, so a recommendation cannot name a stage
+* that does not exist, and a stage added here reaches every view at once.
+*/
+var STAGE_CATALOG = [
+	{
+		id: "exploration",
+		title: "High-level exploration",
+		group: "discovery",
+		about: "We think the problem through together first - directions to take, risks, and what is still unclear."
+	},
+	{
+		id: "interview",
+		title: "Interview",
+		group: "discovery",
+		about: "I ask you focused questions until nothing important is left open."
+	},
+	{
+		id: "research",
+		title: "Research",
+		group: "discovery",
+		about: "I look outside your code - a library, a protocol, an algorithm, a subject area - and write up what I find."
+	},
+	{
+		id: "codebase-analysis",
+		title: "Codebase analysis",
+		group: "discovery",
+		about: "I read the parts of your code this work touches and note what shapes the design."
+	},
+	{
+		id: "technical-specs",
+		title: "Technical specs",
+		group: "deliverables",
+		about: "A written specification another agent can build from without asking you anything."
+	},
+	{
+		id: "ui-mocks",
+		title: "UI mocks",
+		group: "deliverables",
+		about: "Mock screens you open in your browser and comment on before anything is built."
+	},
+	{
+		id: "execution-plan",
+		title: "Execution plan",
+		group: "deliverables",
+		about: "The work split into phases, each with a goal and a way to tell it is done."
+	},
+	{
+		id: "quality-review",
+		title: "Quality review",
+		group: "deliverables",
+		about: "Fresh helper agents review everything we wrote, and I fix what is plainly wrong and bring the judgment calls to you."
+	}
+];
+/** The stages whose presence makes imagination mode worth offering. */
+var IMAGINATION_TRIGGERS = ["exploration", "ui-mocks"];
+function catalogStage(id) {
+	return STAGE_CATALOG.find((stage) => stage.id === id) ?? null;
+}
+function emptySpecState(name, at) {
+	return {
+		version: 1,
+		name,
+		created: at,
+		status: "specifying",
+		protocol: [],
+		modes: { imagination: false },
+		activity: {
+			said: "",
+			at: ""
+		},
+		awaiting: [],
+		phases: [],
+		reviews: [],
+		approvals: [],
+		log: []
+	};
+}
+var isObject$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var str$1 = (value, fallback = "") => typeof value === "string" ? value : fallback;
+var STATUSES = [
+	"specifying",
+	"ready",
+	"executing",
+	"complete"
+];
+var STAGE_STATUSES$1 = [
+	"waiting",
+	"running",
+	"done"
+];
+var KINDS = [
+	"gate",
+	"round",
+	"protocol"
+];
+/**
+* Read the state from whatever is on disk, and keep everything else about it.
+*
+* What this reader does not know is not carried here. `writeSpecState` merges a
+* write into the file it read, which is what keeps a later tool's fields; this
+* side stays a plain shape. A file this reader cannot parse at all reads as
+* a fresh state rather than throwing: a spec whose state file is broken is still
+* a spec, and the artifacts in it are the durable half.
+*/
+function readSpecState(raw, name = "", at = "") {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw || "null");
+	} catch {
+		return emptySpecState(name, at);
+	}
+	if (!isObject$1(parsed) || parsed.version !== 1) return emptySpecState(name, at);
+	const state = emptySpecState(str$1(parsed.name, name), str$1(parsed.created, at));
+	const status = str$1(parsed.status);
+	if (STATUSES.includes(status)) state.status = status;
+	if (Array.isArray(parsed.protocol)) for (const stage of parsed.protocol) {
+		if (!isObject$1(stage) || !catalogStage(str$1(stage.id))) continue;
+		const held = str$1(stage.status);
+		state.protocol.push({
+			id: str$1(stage.id),
+			status: STAGE_STATUSES$1.includes(held) ? held : "waiting",
+			artifacts: Array.isArray(stage.artifacts) ? stage.artifacts.filter((path) => typeof path === "string") : []
+		});
+	}
+	if (isObject$1(parsed.modes)) state.modes.imagination = parsed.modes.imagination === true;
+	if (isObject$1(parsed.activity)) state.activity = {
+		said: str$1(parsed.activity.said),
+		at: str$1(parsed.activity.at)
+	};
+	if (Array.isArray(parsed.awaiting)) for (const item of parsed.awaiting) {
+		if (!isObject$1(item) || !item.id) continue;
+		const kind = str$1(item.kind);
+		state.awaiting.push({
+			id: str$1(item.id),
+			kind: KINDS.includes(kind) ? kind : "round",
+			title: str$1(item.title),
+			file: str$1(item.file),
+			payload: str$1(item.payload),
+			declaredAt: str$1(item.declaredAt)
+		});
+	}
+	if (Array.isArray(parsed.phases)) for (const phase of parsed.phases) {
+		if (!isObject$1(phase) || !phase.id) continue;
+		const held = str$1(phase.status);
+		state.phases.push({
+			id: str$1(phase.id),
+			title: str$1(phase.title),
+			status: STAGE_STATUSES$1.includes(held) ? held : "waiting"
+		});
+	}
+	if (Array.isArray(parsed.reviews)) for (const review of parsed.reviews) {
+		if (!isObject$1(review) || typeof review.round !== "number") continue;
+		state.reviews.push({
+			round: review.round,
+			verdict: str$1(review.verdict),
+			findings: typeof review.findings === "number" ? review.findings : 0,
+			judgments: typeof review.judgments === "number" ? review.judgments : 0,
+			at: str$1(review.at)
+		});
+	}
+	if (Array.isArray(parsed.approvals)) for (const one of parsed.approvals) {
+		if (!isObject$1(one) || !one.id) continue;
+		state.approvals.push({
+			id: str$1(one.id),
+			at: str$1(one.at),
+			outcome: str$1(one.outcome)
+		});
+	}
+	if (Array.isArray(parsed.log)) for (const line of parsed.log) {
+		if (!isObject$1(line)) continue;
+		state.log.push({
+			at: str$1(line.at),
+			said: str$1(line.said)
+		});
+	}
+	return state;
+}
+/**
+* The state as it goes to disk, carrying anything a later tool wrote.
+*
+* The known fields are this tool's and are replaced whole; everything else in
+* the file it read is kept as it was.
+*/
+function writeSpecState(previousRaw, state) {
+	let held = {};
+	try {
+		const parsed = JSON.parse(previousRaw || "null");
+		if (isObject$1(parsed)) held = parsed;
+	} catch {
+		held = {};
+	}
+	return `${JSON.stringify({
+		...held,
+		...state
+	}, null, 2)}\n`;
+}
+//#endregion
+//#region src/lib/files.ts
+var MARKDOWN = /* @__PURE__ */ new Set([
+	"md",
+	"markdown",
+	"mdown",
+	"mkd"
+]);
+var HTML = /* @__PURE__ */ new Set(["html", "htm"]);
+var IMAGE = /* @__PURE__ */ new Set([
+	"png",
+	"jpg",
+	"jpeg",
+	"gif",
+	"webp",
+	"svg",
+	"avif",
+	"bmp",
+	"ico"
+]);
+var TEXT = new Set("txt text log json yaml yml toml ini cfg conf csv tsv xml css scss js jsx mjs cjs ts tsx py rb go rs java kt swift c h cpp hpp sh bash zsh fish sql graphql gql env diff patch lock gitignore editorconfig".split(" "));
+/**
+* The extension, lowercased and without its dot; empty when there is none.
+* A dot-prefixed name is a name, not an extension: `.specs` has none.
+*/
+function extensionOf(name) {
+	const match = name.slice(name.lastIndexOf("/") + 1).slice(1).match(/\.([^.]+)$/);
+	return match ? match[1].toLowerCase() : "";
+}
+/** Whether an entry is hidden from a tool: dot-prefixed names never render. */
+function isHidden(name) {
+	return name.startsWith(".");
+}
+function fileKind(name) {
+	const extension = extensionOf(name);
+	if (MARKDOWN.has(extension)) return "markdown";
+	if (HTML.has(extension)) return "html";
+	if (IMAGE.has(extension)) return "image";
+	if (TEXT.has(extension)) return "text";
+	if (!extension) return "text";
+	return "binary";
+}
+var startsUppercase = (name) => /^[A-Z]/.test(name);
+/**
+* Names starting with an uppercase letter first, then the rest, both halves in
+* plain name order. A stage's uppercase main document then renders before its
+* lowercase supporting artifacts, and numbered artifacts still follow their
+* prefixes. Plain ASCII order alone would put `01-input.md` above `SPEC.md`,
+* since digits sort before uppercase letters.
+*/
+function compareNames(a, b) {
+	const upperA = startsUppercase(a);
+	if (upperA !== startsUppercase(b)) return upperA ? -1 : 1;
+	return a.localeCompare(b, "en");
+}
+//#endregion
+//#region server/specs/paths.ts
+var PathRefused = class extends Error {
+	requested;
+	constructor(requested) {
+		super(`specs: refused path ${requested}`);
+		this.requested = requested;
+		this.name = "PathRefused";
+	}
+};
+/** A path the server was asked for but which is not a directory it can serve. */
+var NoSuchEntry = class extends Error {
+	requested;
+	constructor(requested) {
+		super(`specs: no directory at ${requested}`);
+		this.requested = requested;
+		this.name = "NoSuchEntry";
+	}
+};
+/**
+* Where a path really lands on disk, symlinks and all. A path being created
+* does not exist yet, so the walk goes up to the nearest parent that does and
+* puts the rest back on: the link that matters is always one of the parents.
+*/
+function realPath(absolute) {
+	let candidate = absolute;
+	const tail = [];
+	for (;;) try {
+		return join(realpathSync(candidate), ...tail);
+	} catch {
+		const parent = dirname(candidate);
+		if (parent === candidate) return absolute;
+		tail.unshift(basename(candidate));
+		candidate = parent;
+	}
+}
+/** The served root, resolved through symlinks once at start. */
+function resolveRoot(root) {
+	const absolute = resolve(root);
+	try {
+		return realpathSync(absolute);
+	} catch {
+		return absolute;
+	}
+}
+/** Whether any segment of a root-relative path is dot-prefixed. */
+function hasHiddenSegment(relativePath) {
+	return relativePath.split("/").some((segment) => segment !== "" && isHidden(segment));
+}
+/**
+* Resolve a root-relative path handed in by the browser.
+* Refused: an absolute path, a path that climbs out of the root however it is
+* spelled, a path that lands outside it through a symlink, and - depending on
+* the caller - a dot-prefixed name.
+*
+* `hidden: 'refuse'` is the reading side: no path through a dot-prefixed name
+* is served, the tool's own `.specs/` included, which is why no name of its
+* own needs excluding anywhere else.
+* `hidden: 'require'` is the writing side: everything the tool writes lives
+* inside a dot-prefixed directory, so a path without one is not its to write.
+*
+* The dot-prefixed rule is applied to how the path is spelled and to where it
+* lands, because the two can disagree: `.specs/../spec/SPEC.md` is spelled
+* through a dot-prefixed directory and lands outside one.
+*/
+function resolvePath(root, relativePath, hidden) {
+	const requested = relativePath.replace(/^\/+/, "");
+	if (isAbsolute(relativePath) || requested.includes("\0")) throw new PathRefused(relativePath);
+	const need = hidden === "require";
+	if (hasHiddenSegment(requested) !== need) throw new PathRefused(relativePath);
+	const absolute = resolve(root, requested);
+	if (!containsOrEquals(root, absolute)) throw new PathRefused(relativePath);
+	if (!containsOrEquals(root, realPath(absolute))) throw new PathRefused(relativePath);
+	if (hasHiddenSegment(relative(root, absolute).split(sep).join("/")) !== need) throw new PathRefused(relativePath);
+	return absolute;
+}
+/** Resolve a path the browser asked to read. */
+function resolveWithin(root, relativePath) {
+	return resolvePath(root, relativePath, "refuse");
+}
+/** Resolve a path the tool writes to. */
+function resolveToolWrite(root, relativePath) {
+	return resolvePath(root, relativePath, "require");
+}
+/** Whether one directory contains another, or is the same directory. */
+function containsOrEquals(outer, inner) {
+	return inner === outer || inner.startsWith(outer + sep);
+}
+/**
+* The entry a root-relative path belongs to: the top-level directory holding
+* it, an archived directory named with its group, or the empty string for a
+* file sitting loose at the served root. Under `self` the root is the only
+* entry, so everything under it belongs to it.
+*/
+function entryForPath(relativePath, mode = "children") {
+	if (mode === "self") return "";
+	const segments = relativePath.split("/").filter(Boolean);
+	if (segments.length < 2) return "";
+	if (segments[0] === "archive") return segments.length > 2 ? `archive/${segments[1]}` : "";
+	return segments[0];
+}
+//#endregion
+//#region server/specs/listing.ts
+/** The one name the tool knows: entries under it render read-only. */
+var ARCHIVE_DIR = "archive";
+function visibleEntries(directory) {
+	let entries;
+	try {
+		entries = readdirSync(directory, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	return entries.filter((entry) => !isHidden(entry.name)).sort((a, b) => compareNames(a.name, b.name));
+}
+/** A file this big is not read to hash it; its size and time answer instead. */
+var HASHED_LIMIT = 4 * 1024 * 1024;
+/**
+* What an image or a binary hashes to, so a read mark hangs on its content.
+* A file the page reads as text is hashed by the page itself from that text,
+* and a file too big to read here keeps no hash - it falls back to size and time.
+*
+* Only a page asks for this. The dashboard is names, counts and times, and
+* opens no file at all.
+*/
+function bytesHash(absolute, kind, size) {
+	if (kind === "markdown" || kind === "text") return void 0;
+	if (size > HASHED_LIMIT) return void 0;
+	try {
+		return createHash("sha1").update(readFileSync(absolute)).digest("hex").slice(0, 16);
+	} catch {
+		return;
+	}
+}
+/**
+* Walk a directory into a flat list of files in render order: a directory's own
+* files first, then its subdirectories, each name-ordered so a stage's uppercase
+* main document leads its group.
+*/
+function walk(absolute, relative, recursive = true, hashed = false) {
+	const entries = visibleEntries(absolute);
+	const files = [];
+	let modified = 0;
+	for (const entry of entries) {
+		if (!entry.isFile() && !entry.isDirectory()) continue;
+		if (entry.isDirectory()) continue;
+		const path = relative ? `${relative}/${entry.name}` : entry.name;
+		let stats;
+		try {
+			stats = statSync(join(absolute, entry.name));
+		} catch {
+			continue;
+		}
+		modified = Math.max(modified, stats.mtimeMs);
+		const kind = fileKind(entry.name);
+		files.push({
+			path,
+			name: entry.name,
+			dir: relative,
+			kind,
+			size: stats.size,
+			modified: new Date(stats.mtimeMs).toISOString(),
+			hash: hashed ? bytesHash(join(absolute, entry.name), kind, stats.size) : void 0
+		});
+	}
+	if (recursive) for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const path = relative ? `${relative}/${entry.name}` : entry.name;
+		const inner = walk(join(absolute, entry.name), path, true, hashed);
+		files.push(...inner.files);
+		modified = Math.max(modified, inner.modified);
+	}
+	return {
+		files,
+		modified
+	};
+}
+function entryOf(root, path, recursive) {
+	const absolute = path ? join(root, path) : root;
+	const walked = walk(absolute, "", recursive);
+	let modified = walked.modified;
+	if (!modified) try {
+		modified = statSync(absolute).mtimeMs;
+	} catch {
+		modified = 0;
+	}
+	return {
+		path,
+		name: path ? basename(path) : basename(root),
+		files: walked.files.length,
+		modified: new Date(modified).toISOString(),
+		archived: isArchived(path),
+		status: statusOf(root, path),
+		awaiting: awaitingOf(root, path)
+	};
+}
+/**
+* Where a piece of work stands, read off its own state file.
+*
+* The navigator says this beside each name, so a reader sees which work is moving and which is waiting
+* without opening every one of them. A directory with no state file yet is work somebody started by hand
+* rather than through the tool, and it has no status to show rather than a wrong one.
+*/
+function readState(root, path) {
+	if (!path) return null;
+	try {
+		return readSpecState(readFileSync(join(root, path, TOOL_DIR, SPEC_STATE_FILE), "utf8"), basename(path));
+	} catch {
+		return null;
+	}
+}
+function statusOf(root, path) {
+	return readState(root, path)?.status ?? null;
+}
+function awaitingOf(root, path) {
+	return readState(root, path)?.awaiting.length ?? 0;
+}
+/**
+* The dashboard.
+*
+* Serving a root that holds one directory per piece of work (`children`): its
+* own page first when it holds visible files of its own, then its directories,
+* with everything under `archive/` in the archived group at the end.
+* Serving a piece of work directly (`self`): one entry, the root itself, whole.
+*/
+function readDashboard(root, mode = "children") {
+	const rootName = basename(root);
+	if (mode === "self") return {
+		root,
+		rootName,
+		mode,
+		entries: [entryOf(root, "", true)]
+	};
+	const top = visibleEntries(root);
+	const entries = [];
+	if (top.some((entry) => entry.isFile())) entries.push(entryOf(root, "", false));
+	for (const entry of top) {
+		if (!entry.isDirectory() || entry.name === ARCHIVE_DIR) continue;
+		entries.push(entryOf(root, entry.name, true));
+	}
+	if (top.some((entry) => entry.isDirectory() && entry.name === ARCHIVE_DIR)) for (const archived of visibleEntries(join(root, ARCHIVE_DIR))) {
+		if (!archived.isDirectory()) continue;
+		entries.push(entryOf(root, `${ARCHIVE_DIR}/${archived.name}`, true));
+	}
+	return {
+		root,
+		rootName,
+		mode,
+		entries
+	};
+}
+/** Whether a root-relative path sits under the archive directory. */
+function isArchived(path) {
+	return path === ARCHIVE_DIR || path.startsWith(`${ARCHIVE_DIR}/`);
+}
+/**
+* One entry's visible content, in render order: the entry's own files first,
+* then each subdirectory's, so the page reads as groups. Under `children`, the
+* served root's own entry holds its loose files alone - each of its directories
+* is an entry of its own. Under `self`, the root is the entry and holds it all.
+*
+* A path that is not a directory - one archived or renamed while a tab had it
+* open - is refused rather than answered as an empty page.
+*/
+function readEntry(root, path, mode = "children") {
+	const absolute = path ? resolveWithin(root, path) : root;
+	let stats;
+	try {
+		stats = statSync(absolute);
+	} catch {
+		throw new NoSuchEntry(path);
+	}
+	if (!stats.isDirectory()) throw new NoSuchEntry(path);
+	return {
+		path,
+		name: path ? basename(path) : basename(root),
+		archived: isArchived(path),
+		files: walk(absolute, "", path !== "" || mode === "self", true).files
+	};
+}
+//#endregion
+//#region src/lib/units.ts
+/**
+* Lowercase, every run of characters that is not a letter or a digit turned
+* into one dash, no dash left at either end. Backticks are dropped first, so a
+* heading like "## The `.specs` directory" slugs as the words alone.
+*/
+function slugify(text) {
+	return text.toLowerCase().replace(/`/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "";
+}
+//#endregion
+//#region src/specs/contracts/readme.ts
+/** The day of an ISO timestamp, which is the resolution a log line is read at. */
+function day(iso) {
+	return /^\d{4}-\d{2}-\d{2}/.test(iso) ? iso.slice(0, 10) : "";
+}
+function renderSpecReadme(state) {
+	const lines = [`# ${state.name || "A piece of work"}`, ""];
+	const created = day(state.created);
+	if (created) lines.push(`- Created: ${created}`);
+	lines.push(`- Status: ${state.status}`);
+	if (state.modes.imagination) lines.push("- Mode: imagination");
+	if (state.protocol.length > 0) {
+		lines.push("", "## Protocol", "");
+		for (const stage of state.protocol) {
+			const known = catalogStage(stage.id);
+			const running = stage.status === "running" ? " (running)" : "";
+			lines.push(`- [${stage.status === "done" ? "x" : " "}] ${known?.title ?? stage.id}${running}`);
+		}
+	}
+	if (state.log.length > 0) {
+		lines.push("", "## Log", "");
+		for (const line of state.log) {
+			const at = day(line.at);
+			lines.push(at ? `- ${at}: ${line.said}` : `- ${line.said}`);
+		}
+	}
+	return `${lines.join("\n")}\n`;
+}
+//#endregion
+//#region src/specs/contracts/rounds.ts
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var str = (value, fallback = "") => typeof value === "string" ? value : fallback;
+var OUTCOMES = [
+	"approved",
+	"changes",
+	"apply",
+	"dismiss",
+	"answered"
+];
+/** An answer as it stands on disk, or null for something nobody has answered. */
+function readAnswer(value) {
+	if (!isObject(value)) return null;
+	const outcome = str(value.outcome);
+	if (!OUTCOMES.includes(outcome)) return null;
+	const questions = [];
+	for (const one of Array.isArray(value.questions) ? value.questions : []) {
+		if (!isObject(one) || typeof one.question !== "string") continue;
+		questions.push({
+			question: one.question,
+			chosen: Array.isArray(one.chosen) ? one.chosen.filter((id) => typeof id === "string") : [],
+			said: str(one.said),
+			answered: one.answered === true
+		});
+	}
+	return {
+		outcome,
+		said: str(value.said),
+		questions,
+		answeredAt: str(value.answeredAt)
+	};
+}
+//#endregion
+//#region server/specs/write.ts
+/** The tool's directory inside one entry, as a root-relative path. */
+function toolDirOf(entry) {
+	return entry ? `${entry}/${TOOL_DIR}` : TOOL_DIR;
+}
+/** Write a file atomically: a temporary name beside it, then a rename. */
+function writeAtomic(absolute, contents) {
+	mkdirSync(dirname(absolute), { recursive: true });
+	const temporary = `${absolute}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+	try {
+		writeFileSync(temporary, contents);
+		renameSync(temporary, absolute);
+	} finally {
+		rmSync(temporary, { force: true });
+	}
+}
+/** Write one of the tool's own files, refusing any path outside a `.specs/`. */
+function writeToolFile(root, relativePath, contents) {
+	writeAtomic(resolveToolWrite(root, relativePath), contents);
+}
+function readToolFile(root, relativePath) {
+	const absolute = resolveToolWrite(root, relativePath);
+	try {
+		return readFileSync(absolute, "utf8");
+	} catch {
+		return null;
+	}
+}
+/**
+* An entry's state. A directory nobody has marked or drafted in yet has no
+* state file, and starts from the reading preferences set at the served root,
+* so the theme and the text size a reader chose carry into the next directory
+* they open rather than snapping back to the defaults.
+*/
+function readEntryState(root, entry) {
+	entryMustExist$1(root, entry);
+	const raw = readToolFile(root, `${toolDirOf(entry)}/${STATE_FILE}`);
+	if (raw !== null || entry === "") return readState$1(raw);
+	const state = readState$1(null);
+	state.toolbar = readState$1(readToolFile(root, `${TOOL_DIR}/${STATE_FILE}`)).toolbar;
+	return state;
+}
+/** Write an entry's state, creating its `.specs/` directory the first time. */
+function writeEntryState(root, entry, state) {
+	entryMustAcceptWrites(root, entry);
+	writeToolFile(root, `${toolDirOf(entry)}/${STATE_FILE}`, `${JSON.stringify(state, null, 2)}\n`);
+}
+function entryMustExist$1(root, entry) {
+	if (!existsSync(entry ? resolveWithin(root, entry) : root)) throw new Error(`specs: no entry at ${entry}`);
+}
+/**
+* An archived directory is signed off: the tool reads it and writes nothing
+* into it, so browsing an archived piece of work leaves it exactly as it was.
+*/
+function entryMustAcceptWrites(root, entry) {
+	entryMustExist$1(root, entry);
+	if (isArchived(entry)) throw new PathRefused(entry);
+}
+/** A name safe to write, keeping the extension the user's file arrived with. */
+function assetFileName(stamp, name) {
+	return `${stamp}-${name.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[-.]+/, "") || "attachment"}`;
+}
+function freeName(directory, name) {
+	if (!existsSync(join(directory, name))) return name;
+	const dot = name.lastIndexOf(".");
+	const stem = dot > 0 ? name.slice(0, dot) : name;
+	const extension = dot > 0 ? name.slice(dot) : "";
+	let n = 2;
+	while (existsSync(join(directory, `${stem}-${n}${extension}`))) n++;
+	return `${stem}-${n}${extension}`;
+}
+/**
+* The rounds already filed for one spec, newest last.
+*
+* A window shows what it has queued of its own, which is unsent and nobody else's. This is the other
+* half: what has been sent, which is on disk and is the same for every window on the same work.
+*/
+function filedRounds(root, entry) {
+	return readFeedback(readToolFile(root, `${toolDirOf(entry)}/${FEEDBACK_FILE}`), entry).rounds;
+}
+function submitFeedback(root, entry, submission, now = /* @__PURE__ */ new Date()) {
+	entryMustAcceptWrites(root, entry);
+	const toolDir = toolDirOf(entry);
+	const assetsDir = `${toolDir}/${FEEDBACK_ASSETS_DIR}`;
+	const absoluteAssets = resolveToolWrite(root, assetsDir);
+	const stamp = now.toISOString().slice(0, 19).replace("T", "-").replace(/:/g, "");
+	const comments = [];
+	for (const comment of submission.comments) {
+		if (!comment.unit) continue;
+		const kind = comment.kind === "remove" ? "remove" : "comment";
+		if (kind === "comment" && !comment.text.trim() && comment.assets.length === 0) continue;
+		const assets = [];
+		for (const asset of comment.assets) {
+			mkdirSync(absoluteAssets, { recursive: true });
+			const name = freeName(absoluteAssets, assetFileName(stamp, asset.name));
+			writeToolFile(root, `${assetsDir}/${name}`, Buffer.from(asset.data, "base64"));
+			assets.push({
+				path: `${FEEDBACK_ASSETS_DIR}/${name}`,
+				name: asset.name,
+				type: asset.type
+			});
+		}
+		comments.push({
+			unit: comment.unit,
+			file: comment.file,
+			heading: comment.heading,
+			kind,
+			quote: comment.quote ?? "",
+			text: comment.text,
+			assets
+		});
+	}
+	const feedbackPath = `${toolDir}/${FEEDBACK_FILE}`;
+	const feedback = readFeedback(readToolFile(root, feedbackPath), entry);
+	feedback.version = 1;
+	feedback.entry = entry;
+	feedback.rounds.push({
+		submittedAt: now.toISOString(),
+		comments
+	});
+	writeToolFile(root, feedbackPath, `${JSON.stringify(feedback, null, 2)}\n`);
+	clearSentDrafts(root, entry, comments);
+	return {
+		path: feedbackPath,
+		round: feedback.rounds.length
+	};
+}
+/**
+* A sent draft is no longer a draft. Read marks are left alone: what the user
+* folded away stays folded, and the text stays visible in the boxes.
+*/
+function clearSentDrafts(root, entry, comments) {
+	const state = readEntryState(root, entry);
+	let changed = false;
+	for (const comment of comments) {
+		if (comment.unit === "overall") {
+			if (state.overallDraft) {
+				state.overallDraft = "";
+				changed = true;
+			}
+			continue;
+		}
+		const unit = state.units[comment.unit];
+		if (unit?.draft) {
+			delete unit.draft;
+			changed = true;
+		}
+	}
+	if (changed) writeEntryState(root, entry, state);
+}
+//#endregion
+//#region server/specs/protocol.ts
+/** A request this module will not act on. The mount turns it into a bad request. */
+var Refused = class extends Error {
+	constructor(said) {
+		super(`specs: ${said}`);
+		this.name = "Refused";
+	}
+};
+/** Where a spec's rounds and gates keep their payloads, inside the tool's directory. */
+var ROUNDS_DIR = "rounds";
+/** The artifact an intake becomes, at the root of the spec directory. */
+var INTAKE_FILE = "intake.md";
+var INTAKE_ASSETS_DIR = "intake-assets";
+function statePathOf(entry) {
+	return `${toolDirOf(entry)}/${SPEC_STATE_FILE}`;
+}
+/**
+* The tool reading one of its own files.
+*
+* This resolves through the writing door rather than the reading one: the
+* reading door refuses every dot-prefixed name, which is where everything the
+* tool writes lives. A file that is not there reads as nothing, since a spec
+* with no state file yet is the ordinary case rather than a failure.
+*/
+function readRaw(root, relativePath) {
+	try {
+		return readFileSync(resolveToolWrite(root, relativePath), "utf8");
+	} catch {
+		return null;
+	}
+}
+/**
+* A spec's state as it stands, with the file it came from, so a write keeps what this reader ignores.
+*
+* The spec has to be there. Every verb that moves a piece of work reads through here and writes back,
+* and a write makes the directories under it, so without this check any name a caller hands over
+* becomes a spec: a typo raises a directory that lists in the navigator as real work, and an empty
+* name raises one at the served root itself, with a generated README beside the specs. Filing an
+* intake is the one verb that creates a spec, and it makes the directory before it writes any state,
+* so it does not come through here.
+*/
+function specState(root, entry) {
+	entryMustExist(root, entry);
+	const raw = readRaw(root, statePathOf(entry));
+	return {
+		state: readSpecState(raw, entry.split("/").pop() ?? entry),
+		raw
+	};
+}
+/**
+* Refuse a name that is not a piece of work sitting in the served root.
+*
+* Called at the head of the verbs that write their payload before they read the state, because a write
+* makes the directory it needs and the name would exist by the time the state was read.
+*/
+function entryMustExist(root, entry) {
+	const named = entry.trim();
+	if (!named) throw new Refused("which piece of work? name one");
+	let there = false;
+	try {
+		there = statSync(resolveWithin(root, named)).isDirectory();
+	} catch {
+		there = false;
+	}
+	if (!there) throw new Refused(`there is no piece of work called "${named}"`);
+}
+/** Write the state, and render the README beside it in the same act. */
+function saveSpecState(root, entry, state, raw) {
+	writeToolFile(root, statePathOf(entry), writeSpecState(raw, state));
+	writeAtomic(resolveWithin(root, `${entry}/README.md`), renderSpecReadme(state));
+}
+/** Add one dated line to the log, which is what the rendered README shows. */
+function log(state, said, at) {
+	state.log.push({
+		at,
+		said
+	});
+}
+/** A name safe to write, keeping the extension the file arrived with. */
+function assetName(name) {
+	return name.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[-.]+/, "") || "attachment";
+}
+/**
+* The directory a working name becomes. A name already taken gets a number, so
+* two pieces of work with one name are two directories rather than one that
+* overwrote the other.
+*/
+function freeSlug(root, name) {
+	const base = slugify(name) || "spec";
+	if (!existsSync(resolveWithin(root, base))) return base;
+	let n = 2;
+	while (existsSync(resolveWithin(root, `${base}-${n}`))) n++;
+	return `${base}-${n}`;
+}
+/**
+* File an intake: the one way a piece of work begins, from the pane's form or
+* from a session through the helper.
+*/
+function fileIntake(root, intake, now = /* @__PURE__ */ new Date()) {
+	const name = intake.name.trim();
+	if (!name) throw new Refused("an intake needs a working name");
+	if (!intake.text.trim() && intake.attachments.length === 0) throw new Refused("an intake needs something in it");
+	const entry = freeSlug(root, name);
+	mkdirSync(resolveWithin(root, entry), { recursive: true });
+	const written = [];
+	for (const attachment of intake.attachments) {
+		const relative = `${INTAKE_ASSETS_DIR}/${assetName(attachment.name)}`;
+		mkdirSync(resolveWithin(root, `${entry}/${INTAKE_ASSETS_DIR}`), { recursive: true });
+		writeAtomic(resolveWithin(root, `${entry}/${relative}`), Buffer.from(attachment.data, "base64"));
+		written.push(relative);
+	}
+	const body = [
+		`# ${name}`,
+		"",
+		intake.text.trim(),
+		""
+	];
+	if (written.length > 0) {
+		body.push("## Attached", "");
+		for (const relative of written) body.push(`- [${relative.split("/").pop()}](${relative})`);
+		body.push("");
+	}
+	writeAtomic(resolveWithin(root, `${entry}/${INTAKE_FILE}`), body.join("\n"));
+	const at = now.toISOString();
+	const state = readSpecState(null, name, at);
+	log(state, "filed", at);
+	saveSpecState(root, entry, state, null);
+	return {
+		entry,
+		path: `${entry}/${INTAKE_FILE}`
+	};
+}
+/** The proposal file the confirmation form is rendered from. */
+var PROPOSAL_FILE = `${ROUNDS_DIR}/protocol.json`;
+/**
+* Take the agent's recommendation and put the question to the user.
+*
+* Every catalog stage is answered here, whether it is recommended or not: a
+* form that shows only what was recommended asks the user to notice an absence,
+* which is the one thing a form is worst at.
+*/
+function proposeProtocol(root, entry, proposal, now = /* @__PURE__ */ new Date()) {
+	entryMustExist(root, entry);
+	const said = /* @__PURE__ */ new Map();
+	for (const stage of proposal.stages) {
+		if (!catalogStage(stage.id)) throw new Refused(`no stage named ${stage.id}`);
+		said.set(stage.id, stage);
+	}
+	const stages = STAGE_CATALOG.map((stage) => ({
+		id: stage.id,
+		recommended: said.get(stage.id)?.recommended === true,
+		why: said.get(stage.id)?.why ?? ""
+	}));
+	const at = now.toISOString();
+	writeToolFile(root, `${toolDirOf(entry)}/${PROPOSAL_FILE}`, `${JSON.stringify({
+		stages,
+		note: proposal.note,
+		offeredAt: at
+	}, null, 2)}\n`);
+	const item = {
+		id: "protocol",
+		kind: "protocol",
+		title: "Confirm the steps for this work",
+		file: "",
+		payload: PROPOSAL_FILE,
+		declaredAt: at
+	};
+	const { state, raw } = specState(root, entry);
+	state.awaiting = [...state.awaiting.filter((held) => held.id !== item.id), item];
+	saveSpecState(root, entry, state, raw);
+	return item;
+}
+/**
+* Write the confirmed protocol. The order is the catalog's, whatever order the
+* answers arrived in, so every view of a run reads the same sequence.
+*/
+function confirmProtocol(root, entry, confirmation, now = /* @__PURE__ */ new Date()) {
+	const chosen = new Set(confirmation.stages);
+	for (const id of chosen) if (!catalogStage(id)) throw new Refused(`no stage named ${id}`);
+	const { state, raw } = specState(root, entry);
+	const held = new Map(state.protocol.map((stage) => [stage.id, stage]));
+	state.protocol = STAGE_CATALOG.filter((stage) => chosen.has(stage.id)).map((stage) => held.get(stage.id) ?? {
+		id: stage.id,
+		status: "waiting",
+		artifacts: []
+	});
+	state.modes.imagination = confirmation.imagination && state.protocol.some((stage) => IMAGINATION_TRIGGERS.includes(stage.id));
+	state.awaiting = state.awaiting.filter((item) => item.kind !== "protocol");
+	const at = now.toISOString();
+	state.approvals.push({
+		id: "protocol",
+		at,
+		outcome: "confirmed"
+	});
+	log(state, `protocol confirmed${state.modes.imagination ? " - imagination mode" : ""}`, at);
+	if (confirmation.note.trim()) log(state, `said with the protocol: ${confirmation.note.trim()}`, at);
+	saveSpecState(root, entry, state, raw);
+	return state;
+}
+function postProgress(root, entry, post, now = /* @__PURE__ */ new Date()) {
+	const { state, raw } = specState(root, entry);
+	const at = now.toISOString();
+	if (post.kind === "activity") state.activity = {
+		said: post.said,
+		at
+	};
+	else if (post.kind === "stage") {
+		const known = catalogStage(post.stage);
+		if (!known) throw new Refused(`no stage named ${post.stage}`);
+		const stage = state.protocol.find((held) => held.id === post.stage);
+		if (!stage) throw new Refused(`${post.stage} is not in this protocol`);
+		stage.status = post.status;
+		if (post.artifacts) stage.artifacts = [.../* @__PURE__ */ new Set([...stage.artifacts, ...post.artifacts])];
+		if (post.status === "done") log(state, `${known.title.toLowerCase()} complete`, at);
+		if (post.status === "running") state.activity = {
+			said: known.title,
+			at
+		};
+	} else if (post.kind === "phase") {
+		const id = slugify(post.phase);
+		if (!id) throw new Refused("a phase needs a name");
+		const held = state.phases.find((phase) => phase.id === id);
+		const title = post.title ?? held?.title ?? post.phase;
+		if (held) {
+			held.status = post.status;
+			held.title = title;
+		} else state.phases.push({
+			id,
+			title,
+			status: post.status
+		});
+		if (post.status === "done") log(state, `${title} done`, at);
+		if (post.status === "running") state.activity = {
+			said: title,
+			at
+		};
+	} else if (post.kind === "status") {
+		state.status = post.status;
+		log(state, `status: ${post.status}`, at);
+	} else log(state, post.said, at);
+	saveSpecState(root, entry, state, raw);
+	return state;
+}
+function declareAwaiting(root, entry, declaration, now = /* @__PURE__ */ new Date()) {
+	entryMustExist(root, entry);
+	const id = slugify(declaration.id);
+	if (!id) throw new Refused("an awaiting item needs an id");
+	const payloadPath = `${ROUNDS_DIR}/${id}.json`;
+	const at = now.toISOString();
+	writeToolFile(root, `${toolDirOf(entry)}/${payloadPath}`, `${JSON.stringify({
+		id,
+		kind: declaration.kind,
+		title: declaration.title,
+		file: declaration.file,
+		declaredAt: at,
+		payload: declaration.payload
+	}, null, 2)}\n`);
+	const item = {
+		id,
+		kind: declaration.kind,
+		title: declaration.title,
+		file: declaration.file,
+		payload: payloadPath,
+		declaredAt: at
+	};
+	const { state, raw } = specState(root, entry);
+	state.awaiting = [...state.awaiting.filter((held) => held.id !== id), item];
+	saveSpecState(root, entry, state, raw);
+	return item;
+}
+/**
+* One round or gate as it was declared, with the answer if it has one.
+*
+* This is how the pane reads what it has to render: the payload files live
+* inside the tool's dot-directory, which the reading route refuses on purpose,
+* so a round is read through the verb rather than as a workspace file.
+*/
+function readRound(root, entry, id) {
+	const name = slugify(id);
+	if (!name) throw new Refused("a round has an id");
+	const raw = readRaw(root, `${toolDirOf(entry)}/${ROUNDS_DIR}/${name}.json`);
+	if (raw === null) throw new Refused(`no round named ${id}`);
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Refused(`the round named ${id} could not be read`);
+		return parsed;
+	} catch {
+		throw new Refused(`the round named ${id} could not be read`);
+	}
+}
+/**
+* What the user answered, or nothing when they have not.
+*
+* A round is answered by writing the answer into its own file, so reading it
+* back is reading one file rather than matching a submission to a question.
+*/
+function readAnswers(root, entry, id) {
+	return readRound(root, entry, id).answer ?? null;
+}
+/**
+* Answer one thing the run is waiting on.
+*
+* The answer goes into the round's own file, and the item stops awaiting. The
+* first answer wins: two windows can be looking at one gate, and the second one
+* is told it was already answered rather than quietly overwriting the first.
+*/
+function answerRound(root, entry, id, answer, now = /* @__PURE__ */ new Date()) {
+	const name = slugify(id);
+	const round = readRound(root, entry, name);
+	if (readAnswer(round.answer) !== null) throw new Refused(`${id} was already answered`);
+	const at = now.toISOString();
+	const written = {
+		...answer,
+		answeredAt: at
+	};
+	const payloadPath = `${toolDirOf(entry)}/${ROUNDS_DIR}/${name}.json`;
+	writeToolFile(root, payloadPath, `${JSON.stringify({
+		...round,
+		answer: written
+	}, null, 2)}\n`);
+	const { state, raw } = specState(root, entry);
+	const item = state.awaiting.find((held) => held.id === name);
+	state.awaiting = state.awaiting.filter((held) => held.id !== name);
+	state.approvals.push({
+		id: name,
+		at,
+		outcome: answer.outcome
+	});
+	log(state, `${item?.title || name}: ${SAID[answer.outcome]}`, at);
+	saveSpecState(root, entry, state, raw);
+	return {
+		path: payloadPath,
+		outcome: answer.outcome
+	};
+}
+/** How each outcome reads in the log, which is what the rendered README shows. */
+var SAID = {
+	approved: "approved",
+	changes: "changes asked for",
+	apply: "applied",
+	dismiss: "dismissed",
+	answered: "answered"
+};
+/** Post one round of quality review, which the board shows as it lands. */
+function postReview(root, entry, review, now = /* @__PURE__ */ new Date()) {
+	const at = now.toISOString();
+	const { state, raw } = specState(root, entry);
+	const round = {
+		...review,
+		at
+	};
+	state.reviews = [...state.reviews.filter((held) => held.round !== round.round), round].sort((one, two) => one.round - two.round);
+	log(state, `review round ${round.round}: ${round.verdict}`, at);
+	saveSpecState(root, entry, state, raw);
+	return state;
+}
+//#endregion
+//#region server/specs/read.ts
+var MEDIA_TYPES = {
+	md: "text/markdown; charset=utf-8",
+	markdown: "text/markdown; charset=utf-8",
+	html: "text/html; charset=utf-8",
+	htm: "text/html; charset=utf-8",
+	css: "text/css; charset=utf-8",
+	js: "text/javascript; charset=utf-8",
+	json: "application/json; charset=utf-8",
+	svg: "image/svg+xml",
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	gif: "image/gif",
+	webp: "image/webp",
+	avif: "image/avif",
+	bmp: "image/bmp",
+	ico: "image/x-icon",
+	pdf: "application/pdf",
+	txt: "text/plain; charset=utf-8"
+};
+/** The media type to serve a name with; plain text for anything textual. */
+function mediaType(name) {
+	return MEDIA_TYPES[extensionOf(name)] ?? "application/octet-stream";
+}
+/** A file that exists and is not served, because reading it whole is not something a request may ask for. */
+var FileTooLarge = class extends Error {
+	requested;
+	size;
+	constructor(requested, size) {
+		super(`specs: too large to serve - ${requested}`);
+		this.requested = requested;
+		this.size = size;
+		this.name = "FileTooLarge";
+	}
+};
+/**
+* Read a file inside the served root. Throws `PathRefused` for anything outside it.
+*
+* The file is opened once and everything after that is asked of the open handle, so the size and the
+* bytes describe the same file. The open refuses to follow a link at the last step, which is what the
+* resolve above cannot promise on its own: it reads where the path lands now, and a process in the
+* container can put a link where the file was in the moment between the two, and have this route hand
+* a frame a file from outside the root - the one thing the frame exists to be unable to reach. So a
+* file reached through a link is not read here, and the resolve stays for everything above the leaf.
+*/
+function readWithin(root, relativePath) {
+	const handle = openSync(resolveWithin(root, relativePath), constants.O_RDONLY | constants.O_NOFOLLOW);
+	try {
+		const stats = fstatSync(handle);
+		if (!stats.isFile()) throw new Error(`specs: not a file - ${relativePath}`);
+		if (stats.size > 33554432) throw new FileTooLarge(relativePath, stats.size);
+		return {
+			bytes: readFileSync(handle),
+			mediaType: mediaType(relativePath),
+			size: stats.size,
+			modified: new Date(stats.mtimeMs).toISOString()
+		};
+	} finally {
+		closeSync(handle);
+	}
+}
+/**
+* Watch the served root recursively and hand each change to `onChange`, at most
+* once per path per debounce window. A platform without recursive watching
+* still reports changes at the root itself, which is the honest fallback.
+*/
+function watchRoot(root, onChange, debounceMs = 120, mode = "children") {
+	const pending = /* @__PURE__ */ new Map();
+	let timer = null;
+	const flush = () => {
+		timer = null;
+		const events = [...pending.values()];
+		pending.clear();
+		for (const event of events) try {
+			onChange(event);
+		} catch {}
+	};
+	const record = (relative) => {
+		const path = relative.split(/[\\/]/).filter(Boolean).join("/");
+		if (!path) return;
+		if (hasHiddenSegment(path) && !path.endsWith(`/.specs/user-feedback.json`)) return;
+		const kind = existsSync(`${root}/${path}`) ? "changed" : "gone";
+		pending.set(path, {
+			entry: entryForPath(path, mode),
+			path,
+			kind
+		});
+		if (!timer) timer = setTimeout(flush, debounceMs);
+	};
+	let watcher = null;
+	try {
+		watcher = watch(root, { recursive: true }, (_event, filename) => {
+			if (filename) record(filename.toString());
+		});
+		watcher.on("error", () => {
+			watcher?.close();
+			watcher = null;
+		});
+	} catch {
+		watcher = null;
+	}
+	return { close() {
+		if (timer) clearTimeout(timer);
+		timer = null;
+		watcher?.close();
+	} };
+}
+//#endregion
+//#region server/specs/index.ts
+/** A request the module understood and refused. */
+var BadRequest = class extends Error {
+	code = "bad-request";
+	constructor(what) {
+		super(`specs: ${what}`);
+		this.name = "BadRequest";
+	}
+};
+/**
+* The status a mount should answer a thrown error with. A path outside the root
+* is refused, a missing entry or file is not found, a body the module could not
+* use is a bad request, a file too big to read whole is too large, and anything
+* else is the mount's own fault.
+*/
+function statusFor(error) {
+	if (error instanceof PathRefused) return 403;
+	if (error instanceof NoSuchEntry) return 404;
+	if (error instanceof BadRequest || error instanceof Refused) return 400;
+	if (error instanceof FileTooLarge) return 413;
+	if (error instanceof Error && /^specs: (no entry|not a file)/.test(error.message)) return 404;
+	if (isMissingFile(error)) return 404;
+	return 500;
+}
+function isMissingFile(error) {
+	const code = error?.code;
+	return code === "ENOENT" || code === "ENOTDIR";
+}
+/**
+* The two artifacts this tool writes outside its own dot-directory: the intake
+* it files, and the README it renders from the state. Everything else at the
+* top of a spec directory was written by whoever is doing the work.
+*/
+var TOOL_ARTIFACTS = /* @__PURE__ */ new Set([INTAKE_FILE, "README.md"]);
+/**
+* Where a file this tool wrote sits on disk.
+*
+* Two kinds, and no third: everything inside a `.specs/`, and the artifacts the
+* tool renders into the spec directory itself. A path that is neither is
+* refused, which is what keeps "a delivery names something this tool wrote"
+* true rather than approximate.
+*/
+function toolWritten(root, path) {
+	const parts = path.split("/");
+	const name = parts.pop() ?? "";
+	if (parts.length === 1 && parts[0] && TOOL_ARTIFACTS.has(name)) return resolveWithin(root, path);
+	return resolveToolWrite(root, path);
+}
+var asObject = (value, what) => {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new BadRequest(`${what} is an object`);
+	return value;
+};
+var asText = (value, fallback = "") => typeof value === "string" ? value : fallback;
+var asList = (value) => Array.isArray(value) ? value : [];
+function asIntake(payload) {
+	const body = asObject(payload, "an intake");
+	const attachments = [];
+	for (const one of asList(body.attachments)) {
+		const file = asObject(one, "an attachment");
+		if (typeof file.data !== "string" || typeof file.name !== "string") throw new BadRequest("an attachment carries a name and base64 data");
+		attachments.push({
+			name: file.name,
+			type: asText(file.type),
+			data: file.data
+		});
+	}
+	return {
+		name: asText(body.name),
+		text: asText(body.text),
+		attachments
+	};
+}
+function asProposal(payload) {
+	const body = asObject(payload, "a proposal");
+	const stages = [];
+	for (const one of asList(body.stages)) {
+		const stage = asObject(one, "a proposed stage");
+		if (typeof stage.id !== "string") throw new BadRequest("a proposed stage names one");
+		stages.push({
+			id: stage.id,
+			recommended: stage.recommended === true,
+			why: asText(stage.why)
+		});
+	}
+	return {
+		stages,
+		note: asText(body.note)
+	};
+}
+function asConfirmation(payload) {
+	const body = asObject(payload, "a confirmation");
+	return {
+		stages: asList(body.stages).filter((id) => typeof id === "string"),
+		imagination: body.imagination === true,
+		note: asText(body.note)
+	};
+}
+function asPost(payload) {
+	const body = asObject(payload, "a post");
+	const kind = asText(body.kind);
+	if (kind === "activity" || kind === "note") return {
+		kind,
+		said: asText(body.said)
+	};
+	if (kind === "status") {
+		const status = asText(body.status);
+		if (!SPEC_STATUSES.includes(status)) throw new BadRequest(`a status is one of ${SPEC_STATUSES.join(", ")}`);
+		return {
+			kind,
+			status
+		};
+	}
+	if (kind === "phase") {
+		const status = asText(body.status);
+		if (!STAGE_STATUSES.includes(status)) throw new BadRequest(`a phase status is one of ${STAGE_STATUSES.join(", ")}`);
+		const named = asText(body.title);
+		return {
+			kind,
+			phase: asText(body.phase),
+			status,
+			...named ? { title: named } : {}
+		};
+	}
+	if (kind === "stage") {
+		const status = asText(body.status);
+		if (!STAGE_STATUSES.includes(status)) throw new BadRequest(`a stage status is one of ${STAGE_STATUSES.join(", ")}`);
+		const artifacts = asList(body.artifacts).filter((path) => typeof path === "string");
+		return {
+			kind,
+			stage: asText(body.stage),
+			status,
+			artifacts
+		};
+	}
+	throw new BadRequest("a post is an activity, a stage, a phase, a status or a note");
+}
+function asAnswer(payload) {
+	const body = asObject(payload, "an answer");
+	const outcome = asText(body.outcome);
+	if (!ANSWER_OUTCOMES.includes(outcome)) throw new BadRequest(`an outcome is one of ${ANSWER_OUTCOMES.join(", ")}`);
+	const questions = [];
+	for (const one of asList(body.questions)) {
+		const given = asObject(one, "an answered question");
+		if (typeof given.question !== "string") throw new BadRequest("an answer names its question");
+		const chosen = asList(given.chosen).filter((id) => typeof id === "string");
+		const said = asText(given.said);
+		questions.push({
+			question: given.question,
+			chosen,
+			said,
+			answered: given.answered === true
+		});
+	}
+	return {
+		outcome,
+		said: asText(body.said),
+		questions,
+		answeredAt: ""
+	};
+}
+function asReview(payload) {
+	const body = asObject(payload, "a review round");
+	if (typeof body.round !== "number") throw new BadRequest("a review round is numbered");
+	return {
+		round: body.round,
+		verdict: asText(body.verdict),
+		findings: typeof body.findings === "number" ? body.findings : 0,
+		judgments: typeof body.judgments === "number" ? body.judgments : 0,
+		at: ""
+	};
+}
+var ANSWER_OUTCOMES = [
+	"approved",
+	"changes",
+	"apply",
+	"dismiss",
+	"answered"
+];
+function asDeclaration(payload) {
+	const body = asObject(payload, "a declaration");
+	const kind = asText(body.kind);
+	if (kind !== "gate" && kind !== "round") throw new BadRequest("a declaration is a gate or a round");
+	return {
+		id: asText(body.id),
+		kind,
+		title: asText(body.title),
+		file: asText(body.file),
+		payload: body.payload ?? null
+	};
+}
+var SPEC_STATUSES = [
+	"specifying",
+	"ready",
+	"executing",
+	"complete"
+];
+var STAGE_STATUSES = [
+	"waiting",
+	"running",
+	"done"
+];
+/** Mount the Specs tool over one root. */
+function createSpecsModule(options) {
+	const root = resolveRoot(options.root);
+	const mode = options.entries ?? "children";
+	const onChange = options.onChange;
+	const watcher = onChange ? watchRoot(root, onChange, void 0, mode) : null;
+	return {
+		root,
+		dashboard: () => readDashboard(root, mode),
+		entry: (path) => readEntry(root, path, mode),
+		state: (entry) => readEntryState(root, entry),
+		writeState(entry, value) {
+			writeEntryState(root, entry, readState$1(typeof value === "string" ? value : JSON.stringify(value)));
+		},
+		feedback(entry, submission) {
+			const comments = submission?.comments;
+			if (!Array.isArray(comments)) throw new BadRequest("a submission is a list of comments");
+			return submitFeedback(root, entry, { comments });
+		},
+		filed: (entry) => filedRounds(root, entry),
+		toolPath(path) {
+			const absolute = toolWritten(root, path);
+			if (!existsSync(absolute)) throw new Error(`specs: not a file at ${path}`);
+			return absolute;
+		},
+		stages: () => STAGE_CATALOG,
+		specState: (entry) => specState(root, entry).state,
+		intake: (payload) => fileIntake(root, asIntake(payload)),
+		propose: (entry, payload) => proposeProtocol(root, entry, asProposal(payload)),
+		confirm: (entry, payload) => confirmProtocol(root, entry, asConfirmation(payload)),
+		post: (entry, payload) => postProgress(root, entry, asPost(payload)),
+		declare: (entry, payload) => declareAwaiting(root, entry, asDeclaration(payload)),
+		answers: (entry, id) => readAnswers(root, entry, id),
+		answer: (entry, id, payload) => answerRound(root, entry, id, asAnswer(payload)),
+		review: (entry, payload) => postReview(root, entry, asReview(payload)),
+		round: (entry, id) => readRound(root, entry, id),
+		file: (path) => readWithin(root, path),
+		close: () => watcher?.close()
+	};
+}
+//#endregion
+export { BadRequest, createSpecsModule, statusFor };