@warlock.js/core 5.29.0 → 5.31.0

package/esm/tooling/board/board-message.mjs

@@ -0,0 +1,86 @@
+import { BOARD_VERDICT_LINES } from "./board.types.mjs";
+
+//#region ../../packages/core/src/tooling/board/board-message.ts
+/** Subjects are one line: newlines would break the front matter. */
+function oneLine(value) {
+	return value.replace(/[\r\n]+/g, " ").trim();
+}
+/**
+* Render a message file: front matter (`from`, `to`, `item`, `subject`, `at`),
+* a blank line, the body, and — for a verdict — a final line that is exactly
+* `VERDICT: APPROVED` or `VERDICT: CHANGES REQUESTED`.
+*/
+function formatBoardMessage(fields, body, verdict = null) {
+	const lines = [
+		"---",
+		`from: ${oneLine(fields.from)}`,
+		`to: ${oneLine(fields.to)}`,
+		`item: ${fields.item ?? ""}`,
+		`subject: ${oneLine(fields.subject)}`,
+		`at: ${fields.at}`,
+		"---",
+		""
+	];
+	const text = body.replace(/\s+$/, "");
+	if (text.length > 0) lines.push(text);
+	if (verdict) {
+		if (text.length > 0) lines.push("");
+		lines.push(BOARD_VERDICT_LINES[verdict]);
+	}
+	return `${lines.join("\n")}\n`;
+}
+/** The verdict a line spells, or `null`. */
+function verdictOf(line) {
+	const trimmed = line.trim();
+	if (trimmed === BOARD_VERDICT_LINES.approved) return "approved";
+	if (trimmed === BOARD_VERDICT_LINES["changes-requested"]) return "changes-requested";
+	return null;
+}
+/**
+* Parse a message file. Tolerates a file without front matter (everything is
+* the body). The verdict is read from the last non-empty line only, so a
+* quoted verdict inside the body does not count.
+*/
+function parseBoardMessage(text) {
+	const fields = {
+		from: "",
+		to: "",
+		item: null,
+		subject: "",
+		at: ""
+	};
+	let rest = text.replace(/\r\n/g, "\n");
+	if (rest.startsWith("---\n")) {
+		const end = rest.indexOf("\n---", 4);
+		if (end !== -1) {
+			const header = rest.slice(4, end);
+			for (const line of header.split("\n")) {
+				const separator = line.indexOf(":");
+				if (separator === -1) continue;
+				const key = line.slice(0, separator).trim();
+				const value = line.slice(separator + 1).trim();
+				if (key === "from") fields.from = value;
+				else if (key === "to") fields.to = value;
+				else if (key === "subject") fields.subject = value;
+				else if (key === "at") fields.at = value;
+				else if (key === "item") {
+					const id = Number.parseInt(value, 10);
+					fields.item = Number.isInteger(id) && id > 0 ? id : null;
+				}
+			}
+			rest = rest.slice(end + 4).replace(/^\n+/, "");
+		}
+	}
+	const lines = rest.replace(/\s+$/, "").split("\n");
+	const verdict = verdictOf(lines[lines.length - 1] ?? "");
+	if (verdict) lines.pop();
+	return {
+		...fields,
+		body: lines.join("\n").replace(/\s+$/, ""),
+		verdict
+	};
+}
+
+//#endregion
+export { formatBoardMessage, parseBoardMessage };
+//# sourceMappingURL=board-message.mjs.map

package/esm/tooling/board/board-message.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-message.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/board/board-message.ts"],"sourcesContent":["import { BOARD_VERDICT_LINES, type BoardVerdict } from \"./board.types\";\n\n/** The fields a message file's front matter carries. */\nexport type BoardMessageFields = {\n  from: string;\n  to: string;\n  item: number | null;\n  subject: string;\n  at: string;\n};\n\n/** A message file's contents, parsed. */\nexport type ParsedBoardMessage = BoardMessageFields & {\n  body: string;\n  verdict: BoardVerdict | null;\n};\n\n/** Subjects are one line: newlines would break the front matter. */\nfunction oneLine(value: string): string {\n  return value.replace(/[\\r\\n]+/g, \" \").trim();\n}\n\n/**\n * Render a message file: front matter (`from`, `to`, `item`, `subject`, `at`),\n * a blank line, the body, and — for a verdict — a final line that is exactly\n * `VERDICT: APPROVED` or `VERDICT: CHANGES REQUESTED`.\n */\nexport function formatBoardMessage(\n  fields: BoardMessageFields,\n  body: string,\n  verdict: BoardVerdict | null = null,\n): string {\n  const lines = [\n    \"---\",\n    `from: ${oneLine(fields.from)}`,\n    `to: ${oneLine(fields.to)}`,\n    `item: ${fields.item ?? \"\"}`,\n    `subject: ${oneLine(fields.subject)}`,\n    `at: ${fields.at}`,\n    \"---\",\n    \"\",\n  ];\n  const text = body.replace(/\\s+$/, \"\");\n\n  if (text.length > 0) lines.push(text);\n\n  if (verdict) {\n    if (text.length > 0) lines.push(\"\");\n    lines.push(BOARD_VERDICT_LINES[verdict]);\n  }\n\n  return `${lines.join(\"\\n\")}\\n`;\n}\n\n/** The verdict a line spells, or `null`. */\nfunction verdictOf(line: string): BoardVerdict | null {\n  const trimmed = line.trim();\n\n  if (trimmed === BOARD_VERDICT_LINES.approved) return \"approved\";\n  if (trimmed === BOARD_VERDICT_LINES[\"changes-requested\"]) return \"changes-requested\";\n\n  return null;\n}\n\n/**\n * Parse a message file. Tolerates a file without front matter (everything is\n * the body). The verdict is read from the last non-empty line only, so a\n * quoted verdict inside the body does not count.\n */\nexport function parseBoardMessage(text: string): ParsedBoardMessage {\n  const fields: BoardMessageFields = { from: \"\", to: \"\", item: null, subject: \"\", at: \"\" };\n  let rest = text.replace(/\\r\\n/g, \"\\n\");\n\n  if (rest.startsWith(\"---\\n\")) {\n    const end = rest.indexOf(\"\\n---\", 4);\n\n    if (end !== -1) {\n      const header = rest.slice(4, end);\n\n      for (const line of header.split(\"\\n\")) {\n        const separator = line.indexOf(\":\");\n\n        if (separator === -1) continue;\n\n        const key = line.slice(0, separator).trim();\n        const value = line.slice(separator + 1).trim();\n\n        if (key === \"from\") fields.from = value;\n        else if (key === \"to\") fields.to = value;\n        else if (key === \"subject\") fields.subject = value;\n        else if (key === \"at\") fields.at = value;\n        else if (key === \"item\") {\n          const id = Number.parseInt(value, 10);\n          fields.item = Number.isInteger(id) && id > 0 ? id : null;\n        }\n      }\n\n      rest = rest.slice(end + 4).replace(/^\\n+/, \"\");\n    }\n  }\n\n  const lines = rest.replace(/\\s+$/, \"\").split(\"\\n\");\n  const last = lines[lines.length - 1] ?? \"\";\n  const verdict = verdictOf(last);\n\n  if (verdict) lines.pop();\n\n  return { ...fields, body: lines.join(\"\\n\").replace(/\\s+$/, \"\"), verdict };\n}\n"],"mappings":";;;;AAkBA,SAAS,QAAQ,OAAuB;CACtC,OAAO,MAAM,QAAQ,YAAY,GAAG,CAAC,CAAC,KAAK;AAC7C;;;;;;AAOA,SAAgB,mBACd,QACA,MACA,UAA+B,MACvB;CACR,MAAM,QAAQ;EACZ;EACA,SAAS,QAAQ,OAAO,IAAI;EAC5B,OAAO,QAAQ,OAAO,EAAE;EACxB,SAAS,OAAO,QAAQ;EACxB,YAAY,QAAQ,OAAO,OAAO;EAClC,OAAO,OAAO;EACd;EACA;CACF;CACA,MAAM,OAAO,KAAK,QAAQ,QAAQ,EAAE;CAEpC,IAAI,KAAK,SAAS,GAAG,MAAM,KAAK,IAAI;CAEpC,IAAI,SAAS;EACX,IAAI,KAAK,SAAS,GAAG,MAAM,KAAK,EAAE;EAClC,MAAM,KAAK,oBAAoB,QAAQ;CACzC;CAEA,OAAO,GAAG,MAAM,KAAK,IAAI,EAAE;AAC7B;;AAGA,SAAS,UAAU,MAAmC;CACpD,MAAM,UAAU,KAAK,KAAK;CAE1B,IAAI,YAAY,oBAAoB,UAAU,OAAO;CACrD,IAAI,YAAY,oBAAoB,sBAAsB,OAAO;CAEjE,OAAO;AACT;;;;;;AAOA,SAAgB,kBAAkB,MAAkC;CAClE,MAAM,SAA6B;EAAE,MAAM;EAAI,IAAI;EAAI,MAAM;EAAM,SAAS;EAAI,IAAI;CAAG;CACvF,IAAI,OAAO,KAAK,QAAQ,SAAS,IAAI;CAErC,IAAI,KAAK,WAAW,OAAO,GAAG;EAC5B,MAAM,MAAM,KAAK,QAAQ,SAAS,CAAC;EAEnC,IAAI,QAAQ,IAAI;GACd,MAAM,SAAS,KAAK,MAAM,GAAG,GAAG;GAEhC,KAAK,MAAM,QAAQ,OAAO,MAAM,IAAI,GAAG;IACrC,MAAM,YAAY,KAAK,QAAQ,GAAG;IAElC,IAAI,cAAc,IAAI;IAEtB,MAAM,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC,KAAK;IAC1C,MAAM,QAAQ,KAAK,MAAM,YAAY,CAAC,CAAC,CAAC,KAAK;IAE7C,IAAI,QAAQ,QAAQ,OAAO,OAAO;SAC7B,IAAI,QAAQ,MAAM,OAAO,KAAK;SAC9B,IAAI,QAAQ,WAAW,OAAO,UAAU;SACxC,IAAI,QAAQ,MAAM,OAAO,KAAK;SAC9B,IAAI,QAAQ,QAAQ;KACvB,MAAM,KAAK,OAAO,SAAS,OAAO,EAAE;KACpC,OAAO,OAAO,OAAO,UAAU,EAAE,KAAK,KAAK,IAAI,KAAK;IACtD;GACF;GAEA,OAAO,KAAK,MAAM,MAAM,CAAC,CAAC,CAAC,QAAQ,QAAQ,EAAE;EAC/C;CACF;CAEA,MAAM,QAAQ,KAAK,QAAQ,QAAQ,EAAE,CAAC,CAAC,MAAM,IAAI;CAEjD,MAAM,UAAU,UADH,MAAM,MAAM,SAAS,MAAM,EACV;CAE9B,IAAI,SAAS,MAAM,IAAI;CAEvB,OAAO;EAAE,GAAG;EAAQ,MAAM,MAAM,KAAK,IAAI,CAAC,CAAC,QAAQ,QAAQ,EAAE;EAAG;CAAQ;AAC1E"}

package/esm/tooling/board/board.d.mts

@@ -0,0 +1,109 @@
+import { BoardItem, BoardMessage, BoardState, BoardStatus, BoardVerdict } from "./board.types.mjs";
+
+//#region ../../packages/core/src/tooling/board/board.d.ts
+/** What `initBoard` did. */
+type InitBoardResult = {
+  /** The board directory, relative to the project root. */directory: string; /** `false` when the board already existed. */
+  created: boolean; /** Whether `.warlock/board/` was added to `.gitignore` by this call. */
+  gitignoreUpdated: boolean;
+};
+/** Inputs of {@link addBoardItem}. */
+type AddBoardItemInput = {
+  title: string;
+  assignee?: string | null;
+  reviewer?: string | null; /** The agent creating it, recorded in the history. */
+  by?: string | null; /** Clock, for tests. */
+  now?: () => Date;
+};
+/** Inputs of {@link moveBoardItem}. */
+type MoveBoardItemOptions = {
+  by?: string | null;
+  note?: string | null;
+  now?: () => Date;
+};
+/** Inputs of {@link sendBoardMessage}. */
+type SendBoardMessageInput = {
+  to: string;
+  from: string;
+  subject: string;
+  body?: string; /** The item the message is about. */
+  item?: number | null; /** A review verdict; with `item`, also moves the item to that state. */
+  verdict?: BoardVerdict | null;
+  now?: () => Date;
+};
+/** What {@link sendBoardMessage} wrote. */
+type SendBoardMessageResult = {
+  message: BoardMessage; /** The item after the verdict moved it, when the message carried one. */
+  item: BoardItem | null;
+};
+/** Inputs of {@link watchBoard}. */
+type WatchBoardOptions = {
+  agent: string; /** Return messages numbered above this. Default: the agent's cursor. */
+  since?: number; /** Give up after this long; throws `WL7404`. Default: 10 minutes. */
+  timeoutMs?: number; /** Poll interval. Default: 250 ms. */
+  intervalMs?: number; /** Stop early (resolves with no messages). */
+  signal?: AbortSignal;
+};
+/** What {@link watchBoard} returned. */
+type WatchBoardResult = {
+  agent: string; /** The new messages, oldest first. */
+  messages: BoardMessage[]; /** The agent's cursor after the call. */
+  cursor: number;
+};
+/** A file-name slug: lower-case, dashes, at most 48 characters. */
+declare function boardSlug(value: string, fallback: string): string;
+/** Throw unless `name` is a valid agent name. */
+declare function assertAgentName(name: string, label?: string): void;
+/** Whether a `.gitignore` already ignores the board folder (or `.warlock` as a whole). */
+declare function gitignoreCoversBoard(content: string): boolean;
+/**
+ * Create the board (idempotent): `.warlock/board/` with its `board.json`
+ * marker, `items/`, and `.warlock/board/` in `.gitignore` unless the project
+ * already ignores it. A `.gitignore` is created when there is none.
+ */
+declare function initBoard(cwd?: string, now?: () => Date): InitBoardResult;
+/** Every item, by id. Throws `WL7401` when the board does not exist. */
+declare function listBoardItems(cwd?: string): BoardItem[];
+/** One item. Throws `WL7402` for an unknown id. */
+declare function readBoardItem(id: number, cwd?: string): BoardItem;
+/** Add an item in state `todo`, with a fresh id no other writer can take. */
+declare function addBoardItem(input: AddBoardItemInput, cwd?: string): BoardItem;
+/** The states an item in `state` may move to. */
+declare function nextBoardStates(state: BoardState): readonly BoardState[];
+/** Throw `WL7403` unless `from → to` is in {@link BOARD_TRANSITIONS}. */
+declare function assertBoardTransition(id: number, from: BoardState, to: BoardState): void;
+/**
+ * Move an item to another state, recording who moved it and why. Throws
+ * `WL7402` for an unknown id and `WL7403` for a move the state machine does
+ * not allow.
+ */
+declare function moveBoardItem(id: number, to: BoardState, options?: MoveBoardItemOptions, cwd?: string): BoardItem;
+/**
+ * Write a message to `to-<agent>/NNNN-<slug>.md`. Messages are append-only:
+ * the number is reserved exclusively and the file is created with `wx`, so it
+ * is never rewritten. A verdict with an `item` also moves the item to
+ * `approved` / `changes-requested` — before the message is written, so a
+ * refused move (`WL7403`) leaves no message behind.
+ */
+declare function sendBoardMessage(input: SendBoardMessageInput, cwd?: string): SendBoardMessageResult;
+/** The messages in an agent's inbox numbered above `since`, oldest first. */
+declare function listBoardMessages(agent: string, options?: {
+  since?: number;
+}, cwd?: string): BoardMessage[];
+/** The highest message number `watch` has returned to `agent` (0 when none). */
+declare function readBoardCursor(agent: string, cwd?: string): number;
+/** Record that `agent` has seen messages up to `number`. Never moves the cursor back. */
+declare function writeBoardCursor(agent: string, number: number, cwd?: string): number;
+/** Every item and every inbox with its message count, cursor and unread count. */
+declare function readBoardStatus(cwd?: string): BoardStatus;
+/**
+ * Block until `agent` has a message numbered above `since` (default: its
+ * cursor), then return every such message and advance the cursor past them.
+ *
+ * Polls the inbox every `intervalMs`; throws `WL7404` when `timeoutMs` passes
+ * first. An aborted `signal` resolves with no messages.
+ */
+declare function watchBoard(options: WatchBoardOptions, cwd?: string): Promise<WatchBoardResult>;
+//#endregion
+export { AddBoardItemInput, InitBoardResult, MoveBoardItemOptions, SendBoardMessageInput, SendBoardMessageResult, WatchBoardOptions, WatchBoardResult, addBoardItem, assertAgentName, assertBoardTransition, boardSlug, gitignoreCoversBoard, initBoard, listBoardItems, listBoardMessages, moveBoardItem, nextBoardStates, readBoardCursor, readBoardItem, readBoardStatus, sendBoardMessage, watchBoard, writeBoardCursor };
+//# sourceMappingURL=board.d.mts.map

package/esm/tooling/board/board.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"board.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/board/board.ts"],"mappings":";;;;KAiCY,eAAA;EAAA,yDAEV,SAAA;EAEA,OAAA,WAFA;EAIA,gBAAA;AAAA;;KAIU,iBAAA;EACV,KAAA;EACA,QAAA;EACA,QAAA,kBAIgB;EAFhB,EAAA,kBAHA;EAKA,GAAA,SAAY,IAAI;AAAA;;KAIN,oBAAA;EACV,EAAA;EACA,IAAA;EACA,GAAA,SAAY,IAAI;AAAA;;KAIN,qBAAA;EACV,EAAA;EACA,IAAA;EACA,OAAA;EACA,IAAA,WARgB;EAUhB,IAAA,kBANU;EAQV,OAAA,GAAU,YAAA;EACV,GAAA,SAAY,IAAI;AAAA;;KAIN,sBAAA;EACV,OAAA,EAAS,YAAA,EAVT;EAYA,IAAA,EAAM,SAAS;AAAA;;KAIL,iBAAA;EACV,KAAA,UAZgB;EAchB,KAAA,WAVU;EAYV,SAAA;EAEA,UAAA,WAbA;EAeA,MAAA,GAAS,WAAW;AAAA;;KAIV,gBAAA;EACV,KAAA,UAdU;EAgBV,QAAA,EAAU,YAAY;EAEtB,MAAA;AAAA;;iBAgBc,SAAA,CAAU,KAAA,UAAe,QAAgB;;iBAYzC,eAAA,CAAgB,IAAA,UAAc,KAAe;;iBA8E7C,oBAAA,CAAqB,OAAe;AAnH9B;AAItB;;;;AAJsB,iBAyIN,SAAA,CACd,GAAA,WACA,GAAA,SAAW,IAAA,GACV,eAAe;;iBA4FF,cAAA,CAAe,GAAA,YAAsB,SAAS;;iBAe9C,aAAA,CAAc,EAAA,UAAY,GAAA,YAAsB,SAAS;AA9OjE;AAAA,iBA8PQ,YAAA,CAAa,KAAA,EAAO,iBAAA,EAAmB,GAAA,YAAsB,SAAS;;iBAqCtE,eAAA,CAAgB,KAAA,EAAO,UAAA,YAAsB,UAAU;;iBAKvD,qBAAA,CAAsB,EAAA,UAAY,IAAA,EAAM,UAAA,EAAY,EAAA,EAAI,UAAU;AA5QlF;;;;AAA6D;AAA7D,iBA0RgB,aAAA,CACd,EAAA,UACA,EAAA,EAAI,UAAA,EACJ,OAAA,GAAS,oBAAA,EACT,GAAA,YACC,SAAA;;;;AAjNiD;AAsBpD;;;iBA+NgB,gBAAA,CACd,KAAA,EAAO,qBAAA,EACP,GAAA,YACC,sBAAsB;;iBAyDT,iBAAA,CACd,KAAA,UACA,OAAA;EAAW,KAAA;AAAA,GACX,GAAA,YACC,YAAY;;iBA6BC,eAAA,CAAgB,KAAA,UAAe,GAAmB;AA7NlE;AAAA,iBA4OgB,gBAAA,CAAiB,KAAA,UAAe,MAAA,UAAgB,GAAA;;iBAchD,eAAA,CAAgB,GAAA,YAAsB,WAAW;AA1PH;AAe9D;;;;;;AAf8D,iBAyRxC,UAAA,CACpB,OAAA,EAAS,iBAAA,EACT,GAAA,YACC,OAAA,CAAQ,gBAAA"}

package/esm/tooling/board/board.mjs

@@ -0,0 +1,406 @@
+import { WarlockError } from "../../errors/warlock-error.mjs";
+import { BOARD_DIRECTORY, BOARD_TRANSITIONS, isBoardState } from "./board.types.mjs";
+import { formatBoardMessage, parseBoardMessage } from "./board-message.mjs";
+import path from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+
+//#region ../../packages/core/src/tooling/board/board.ts
+/** Agent names: lower-case letters, digits and dashes, starting with a letter or digit. */
+const AGENT_NAME = /^[a-z0-9][a-z0-9-]*$/;
+/** How many sequence numbers a writer tries before giving up on a contended slot. */
+const MAX_ALLOCATION_ATTEMPTS = 1e3;
+/** The marker file `init` writes; its presence is what "initialized" means. */
+const BOARD_FILE = "board.json";
+function boardRoot(cwd) {
+	return path.join(cwd, BOARD_DIRECTORY);
+}
+function toPosix(value) {
+	return value.split(path.sep).join("/");
+}
+function pad(value) {
+	return String(value).padStart(4, "0");
+}
+/** A file-name slug: lower-case, dashes, at most 48 characters. */
+function boardSlug(value, fallback) {
+	const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48).replace(/-+$/g, "");
+	return slug.length > 0 ? slug : fallback;
+}
+/** Throw unless `name` is a valid agent name. */
+function assertAgentName(name, label = "agent") {
+	if (!AGENT_NAME.test(name)) throw new Error(`Invalid ${label} name ${JSON.stringify(name)}: use lower-case letters, digits and dashes (e.g. "reviewer").`);
+}
+function isErrnoException(error) {
+	return error instanceof Error && "code" in error;
+}
+/** Write a file through a temp file and a rename, so a reader never sees half of it. */
+function writeAtomic(file, content) {
+	const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+	writeFileSync(temporary, content, "utf8");
+	renameSync(temporary, file);
+}
+/** The `NNNN` numbers of the files in a directory named `NNNN-…`. */
+function numberedEntries(directory, extension) {
+	if (!existsSync(directory)) return [];
+	return readdirSync(directory).filter((name) => !name.startsWith(".") && name.endsWith(extension)).flatMap((name) => {
+		const match = /^(\d+)-/.exec(name);
+		return match?.[1] ? [{
+			number: Number.parseInt(match[1], 10),
+			name
+		}] : [];
+	}).sort((first, second) => first.number - second.number);
+}
+/**
+* Reserve the next free sequence number in `directory` by creating
+* `.seq/NNNN` exclusively (`wx`). Two writers racing for the same number:
+* one gets `EEXIST` and moves on to the next, so numbers are never shared.
+*/
+function reserveNumber(directory, start) {
+	const sequence = path.join(directory, ".seq");
+	mkdirSync(sequence, { recursive: true });
+	for (let number = start, attempt = 0; attempt < MAX_ALLOCATION_ATTEMPTS; number++, attempt++) try {
+		writeFileSync(path.join(sequence, pad(number)), "", { flag: "wx" });
+		return number;
+	} catch (error) {
+		if (isErrnoException(error) && error.code === "EEXIST") continue;
+		throw error;
+	}
+	throw new Error(`Could not allocate a sequence number in ${directory}.`);
+}
+function nextNumber(directory, extension) {
+	const entries = numberedEntries(directory, extension);
+	return reserveNumber(directory, (entries[entries.length - 1]?.number ?? 0) + 1);
+}
+/** Throw `WL7401` unless the board exists. */
+function assertInitialized(cwd) {
+	const root = boardRoot(cwd);
+	if (!existsSync(path.join(root, BOARD_FILE))) throw new WarlockError("WL7401", `No agent board in ${BOARD_DIRECTORY}. Run \`warlock board init\` at the project root.`);
+	return root;
+}
+/** Whether a `.gitignore` already ignores the board folder (or `.warlock` as a whole). */
+function gitignoreCoversBoard(content) {
+	const covering = new Set([
+		".warlock",
+		".warlock/",
+		"/.warlock",
+		"/.warlock/",
+		".warlock/*",
+		"/.warlock/*",
+		".warlock/board",
+		".warlock/board/",
+		"/.warlock/board",
+		"/.warlock/board/"
+	]);
+	return content.split(/\r?\n/).some((line) => covering.has(line.trim()));
+}
+/**
+* Create the board (idempotent): `.warlock/board/` with its `board.json`
+* marker, `items/`, and `.warlock/board/` in `.gitignore` unless the project
+* already ignores it. A `.gitignore` is created when there is none.
+*/
+function initBoard(cwd = process.cwd(), now = () => /* @__PURE__ */ new Date()) {
+	const root = boardRoot(cwd);
+	const marker = path.join(root, BOARD_FILE);
+	const created = !existsSync(marker);
+	mkdirSync(path.join(root, "items"), { recursive: true });
+	mkdirSync(path.join(root, "cursors"), { recursive: true });
+	if (created) writeAtomic(marker, `${JSON.stringify({
+		schemaVersion: 1,
+		createdAt: now().toISOString()
+	}, null, 2)}\n`);
+	const gitignore = path.join(cwd, ".gitignore");
+	const current = existsSync(gitignore) ? readFileSync(gitignore, "utf8") : "";
+	let gitignoreUpdated = false;
+	if (!gitignoreCoversBoard(current)) {
+		writeFileSync(gitignore, `${current}${current.length === 0 || current.endsWith("\n") ? "" : "\n"}${current.length > 0 ? "\n" : ""}# Agent board (warlock board)\n${BOARD_DIRECTORY}/\n`, "utf8");
+		gitignoreUpdated = true;
+	}
+	return {
+		directory: BOARD_DIRECTORY,
+		created,
+		gitignoreUpdated
+	};
+}
+function parseItem(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const id = Reflect.get(value, "id");
+	const title = Reflect.get(value, "title");
+	const state = Reflect.get(value, "state");
+	if (typeof id !== "number" || typeof title !== "string") return void 0;
+	if (typeof state !== "string" || !isBoardState(state)) return void 0;
+	const text = (key) => {
+		const field = Reflect.get(value, key);
+		return typeof field === "string" ? field : null;
+	};
+	const history = Reflect.get(value, "history");
+	return {
+		id,
+		title,
+		state,
+		assignee: text("assignee"),
+		reviewer: text("reviewer"),
+		createdAt: text("createdAt") ?? "",
+		updatedAt: text("updatedAt") ?? "",
+		history: Array.isArray(history) ? history.flatMap((entry) => {
+			if (typeof entry !== "object" || entry === null) return [];
+			const from = Reflect.get(entry, "from");
+			const to = Reflect.get(entry, "to");
+			const by = Reflect.get(entry, "by");
+			const at = Reflect.get(entry, "at");
+			const note = Reflect.get(entry, "note");
+			if (typeof to !== "string" || !isBoardState(to)) return [];
+			return [{
+				from: typeof from === "string" && isBoardState(from) ? from : null,
+				to,
+				by: typeof by === "string" ? by : null,
+				at: typeof at === "string" ? at : "",
+				note: typeof note === "string" ? note : null
+			}];
+		}) : []
+	};
+}
+function itemFile(root, id) {
+	const entry = numberedEntries(path.join(root, "items"), ".json").find((candidate) => candidate.number === id);
+	return entry ? path.join(root, "items", entry.name) : void 0;
+}
+/** Every item, by id. Throws `WL7401` when the board does not exist. */
+function listBoardItems(cwd = process.cwd()) {
+	const root = assertInitialized(cwd);
+	const directory = path.join(root, "items");
+	return numberedEntries(directory, ".json").flatMap(({ name }) => {
+		try {
+			const item = parseItem(JSON.parse(readFileSync(path.join(directory, name), "utf8")));
+			return item ? [item] : [];
+		} catch {
+			return [];
+		}
+	});
+}
+/** One item. Throws `WL7402` for an unknown id. */
+function readBoardItem(id, cwd = process.cwd()) {
+	const file = itemFile(assertInitialized(cwd), id);
+	const item = file ? parseItem(JSON.parse(readFileSync(file, "utf8"))) : void 0;
+	if (!item) throw new WarlockError("WL7402", `Board item ${id} does not exist. Run \`warlock board status\` to list the items.`);
+	return item;
+}
+/** Add an item in state `todo`, with a fresh id no other writer can take. */
+function addBoardItem(input, cwd = process.cwd()) {
+	const root = assertInitialized(cwd);
+	const title = input.title.replace(/[\r\n]+/g, " ").trim();
+	if (title.length === 0) throw new Error("A board item needs a title.");
+	for (const [label, name] of [
+		["assignee", input.assignee],
+		["reviewer", input.reviewer],
+		["by", input.by]
+	]) if (name) assertAgentName(name, label);
+	const directory = path.join(root, "items");
+	const id = nextNumber(directory, ".json");
+	const at = (input.now ?? (() => /* @__PURE__ */ new Date()))().toISOString();
+	const item = {
+		id,
+		title,
+		state: "todo",
+		assignee: input.assignee ?? null,
+		reviewer: input.reviewer ?? null,
+		createdAt: at,
+		updatedAt: at,
+		history: [{
+			from: null,
+			to: "todo",
+			by: input.by ?? null,
+			at,
+			note: null
+		}]
+	};
+	writeAtomic(path.join(directory, `${pad(id)}-${boardSlug(title, "item")}.json`), `${JSON.stringify(item, null, 2)}\n`);
+	return item;
+}
+/** The states an item in `state` may move to. */
+function nextBoardStates(state) {
+	return BOARD_TRANSITIONS[state];
+}
+/** Throw `WL7403` unless `from → to` is in {@link BOARD_TRANSITIONS}. */
+function assertBoardTransition(id, from, to) {
+	if (!BOARD_TRANSITIONS[from].includes(to)) throw new WarlockError("WL7403", `Board item ${id} is "${from}" and cannot move to "${to}". Allowed next states: ${BOARD_TRANSITIONS[from].join(", ")}.`);
+}
+/**
+* Move an item to another state, recording who moved it and why. Throws
+* `WL7402` for an unknown id and `WL7403` for a move the state machine does
+* not allow.
+*/
+function moveBoardItem(id, to, options = {}, cwd = process.cwd()) {
+	const root = assertInitialized(cwd);
+	const item = readBoardItem(id, cwd);
+	const file = itemFile(root, id);
+	if (options.by) assertAgentName(options.by, "by");
+	assertBoardTransition(id, item.state, to);
+	const at = (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString();
+	const moved = {
+		...item,
+		state: to,
+		updatedAt: at,
+		history: [...item.history, {
+			from: item.state,
+			to,
+			by: options.by ?? null,
+			at,
+			note: options.note ?? null
+		}]
+	};
+	if (file) writeAtomic(file, `${JSON.stringify(moved, null, 2)}\n`);
+	return moved;
+}
+function inboxDirectory(root, agent) {
+	return path.join(root, `to-${agent}`);
+}
+/**
+* Write a message to `to-<agent>/NNNN-<slug>.md`. Messages are append-only:
+* the number is reserved exclusively and the file is created with `wx`, so it
+* is never rewritten. A verdict with an `item` also moves the item to
+* `approved` / `changes-requested` — before the message is written, so a
+* refused move (`WL7403`) leaves no message behind.
+*/
+function sendBoardMessage(input, cwd = process.cwd()) {
+	const root = assertInitialized(cwd);
+	assertAgentName(input.to, "recipient");
+	assertAgentName(input.from, "sender");
+	const subject = input.subject.replace(/[\r\n]+/g, " ").trim();
+	if (subject.length === 0) throw new Error("A board message needs a subject.");
+	const itemId = input.item ?? null;
+	const verdict = input.verdict ?? null;
+	const now = input.now ?? (() => /* @__PURE__ */ new Date());
+	if (itemId !== null) readBoardItem(itemId, cwd);
+	const item = itemId !== null && verdict !== null ? moveBoardItem(itemId, verdict, {
+		by: input.from,
+		note: subject,
+		now
+	}, cwd) : null;
+	const directory = inboxDirectory(root, input.to);
+	mkdirSync(directory, { recursive: true });
+	const number = nextNumber(directory, ".md");
+	const at = now().toISOString();
+	const name = `${pad(number)}-${boardSlug(subject, "message")}.md`;
+	const file = path.join(directory, name);
+	writeFileSync(file, formatBoardMessage({
+		from: input.from,
+		to: input.to,
+		item: itemId,
+		subject,
+		at
+	}, input.body ?? "", verdict), {
+		encoding: "utf8",
+		flag: "wx"
+	});
+	return {
+		message: {
+			number,
+			file: toPosix(path.relative(cwd, file)),
+			from: input.from,
+			to: input.to,
+			item: itemId,
+			subject,
+			at,
+			body: (input.body ?? "").replace(/\s+$/, ""),
+			verdict
+		},
+		item
+	};
+}
+/** The messages in an agent's inbox numbered above `since`, oldest first. */
+function listBoardMessages(agent, options = {}, cwd = process.cwd()) {
+	const root = assertInitialized(cwd);
+	assertAgentName(agent);
+	const directory = inboxDirectory(root, agent);
+	const since = options.since ?? 0;
+	return numberedEntries(directory, ".md").filter((entry) => entry.number > since).map(({ number, name }) => {
+		const file = path.join(directory, name);
+		const parsed = parseBoardMessage(readFileSync(file, "utf8"));
+		return {
+			number,
+			file: toPosix(path.relative(cwd, file)),
+			from: parsed.from,
+			to: parsed.to || agent,
+			item: parsed.item,
+			subject: parsed.subject,
+			at: parsed.at,
+			body: parsed.body,
+			verdict: parsed.verdict
+		};
+	});
+}
+/** The highest message number `watch` has returned to `agent` (0 when none). */
+function readBoardCursor(agent, cwd = process.cwd()) {
+	const root = assertInitialized(cwd);
+	assertAgentName(agent);
+	const file = path.join(root, "cursors", agent);
+	if (!existsSync(file)) return 0;
+	const value = Number.parseInt(readFileSync(file, "utf8").trim(), 10);
+	return Number.isInteger(value) && value > 0 ? value : 0;
+}
+/** Record that `agent` has seen messages up to `number`. Never moves the cursor back. */
+function writeBoardCursor(agent, number, cwd = process.cwd()) {
+	const root = assertInitialized(cwd);
+	const current = readBoardCursor(agent, cwd);
+	const next = Math.max(current, number);
+	if (next !== current) {
+		mkdirSync(path.join(root, "cursors"), { recursive: true });
+		writeAtomic(path.join(root, "cursors", agent), `${next}\n`);
+	}
+	return next;
+}
+/** Every item and every inbox with its message count, cursor and unread count. */
+function readBoardStatus(cwd = process.cwd()) {
+	const root = assertInitialized(cwd);
+	const inboxes = readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory() && entry.name.startsWith("to-")).map((entry) => entry.name.slice(3)).filter((agent) => /^[a-z0-9][a-z0-9-]*$/.test(agent)).sort().map((agent) => {
+		const numbers = numberedEntries(inboxDirectory(root, agent), ".md").map((entry) => entry.number);
+		const cursor = readBoardCursor(agent, cwd);
+		return {
+			agent,
+			messages: numbers.length,
+			cursor,
+			unread: numbers.filter((number) => number > cursor).length
+		};
+	});
+	return {
+		schemaVersion: 1,
+		items: listBoardItems(cwd),
+		inboxes
+	};
+}
+/**
+* Block until `agent` has a message numbered above `since` (default: its
+* cursor), then return every such message and advance the cursor past them.
+*
+* Polls the inbox every `intervalMs`; throws `WL7404` when `timeoutMs` passes
+* first. An aborted `signal` resolves with no messages.
+*/
+async function watchBoard(options, cwd = process.cwd()) {
+	assertInitialized(cwd);
+	assertAgentName(options.agent);
+	const since = options.since ?? readBoardCursor(options.agent, cwd);
+	const timeoutMs = options.timeoutMs ?? 600 * 1e3;
+	const intervalMs = options.intervalMs ?? 250;
+	const deadline = Date.now() + timeoutMs;
+	for (;;) {
+		const messages = listBoardMessages(options.agent, { since }, cwd);
+		if (messages.length > 0) {
+			const newest = messages[messages.length - 1]?.number ?? since;
+			return {
+				agent: options.agent,
+				messages,
+				cursor: writeBoardCursor(options.agent, newest, cwd)
+			};
+		}
+		if (options.signal?.aborted) return {
+			agent: options.agent,
+			messages: [],
+			cursor: readBoardCursor(options.agent, cwd)
+		};
+		const remaining = deadline - Date.now();
+		if (remaining <= 0) throw new WarlockError("WL7404", `No new message for "${options.agent}" after ${Math.round(timeoutMs / 1e3)}s (watching messages above #${since}).`);
+		await new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, remaining)));
+	}
+}
+
+//#endregion
+export { addBoardItem, assertAgentName, assertBoardTransition, boardSlug, gitignoreCoversBoard, initBoard, listBoardItems, listBoardMessages, moveBoardItem, nextBoardStates, readBoardCursor, readBoardItem, readBoardStatus, sendBoardMessage, watchBoard, writeBoardCursor };
+//# sourceMappingURL=board.mjs.map