recursive-board 0.1.0

package/dist/wi/wi.js

@@ -0,0 +1,1551 @@
+#!/usr/bin/env node
+
+// src/cli/wi.ts
+import { parseArgs } from "node:util";
+import { resolve as resolve2 } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/cli/vault.ts
+import { readdir, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, resolve as resolvePath, dirname, basename, sep } from "node:path";
+
+// src/shared/frontmatter.ts
+var KEY_LINE = /^([A-Za-z_][\w.-]*)\s*:(?:[ \t]+(.*))?$/;
+function splitBlock(text) {
+  if (!text.startsWith("---")) return null;
+  const first = /^---[ \t]*\r?\n/.exec(text);
+  if (!first) return null;
+  const lines = [];
+  const ends = [];
+  const contentStart = first[0].length;
+  let cursor = contentStart;
+  while (cursor < text.length) {
+    const nl = text.indexOf("\n", cursor);
+    const hasNewline = nl !== -1;
+    const lineEnd = hasNewline ? nl + 1 : text.length;
+    const raw = text.slice(cursor, lineEnd);
+    const line2 = raw.replace(/\r?\n$/, "");
+    const end = raw.slice(line2.length);
+    if (/^---[ \t]*$/.test(line2)) {
+      return { lines, ends, contentStart, contentEnd: cursor };
+    }
+    lines.push(line2);
+    ends.push(end);
+    cursor = lineEnd;
+    if (!hasNewline) break;
+  }
+  return null;
+}
+function readEntries(lines) {
+  const entries = [];
+  for (let i = 0; i < lines.length; i++) {
+    const match = KEY_LINE.exec(lines[i]);
+    if (!match) continue;
+    const [, key, rest] = match;
+    const value = rest === void 0 || rest.trim() === "" ? void 0 : parseScalar(rest);
+    let end = i + 1;
+    if (value === void 0) {
+      while (end < lines.length && (/^[ \t]/.test(lines[end]) || lines[end].trim() === "")) end++;
+    }
+    entries.push({ key, start: i, end, value });
+    i = end - 1;
+  }
+  return entries;
+}
+function parseScalar(raw) {
+  const text = raw.trim();
+  if (text === "") return void 0;
+  if (text.startsWith('"') && text.endsWith('"') && text.length >= 2) {
+    return text.slice(1, -1).replace(/\\(["\\])/g, "$1");
+  }
+  if (text.startsWith("'") && text.endsWith("'") && text.length >= 2) {
+    return text.slice(1, -1).replace(/''/g, "'");
+  }
+  if (text === "true") return true;
+  if (text === "false") return false;
+  if (/^-?\d+$/.test(text)) return Number(text);
+  if (/^-?\d*\.\d+$/.test(text)) return Number(text);
+  if (text.startsWith("[") || text.startsWith("{")) return void 0;
+  return text;
+}
+function needsQuotes(text) {
+  if (text === "") return true;
+  if (text !== text.trim()) return true;
+  if (/^[[\]{}#&*!|>'"%@`,?-]/.test(text)) return true;
+  if (text.includes(": ") || text.includes(" #") || /[\r\n]/.test(text)) return true;
+  if (text.endsWith(":")) return true;
+  if (/["'\\]/.test(text)) return true;
+  if (/^(true|false|null|~|yes|no|on|off)$/i.test(text)) return true;
+  if (/^-?\d+(\.\d+)?$/.test(text)) return true;
+  return false;
+}
+function formatScalar(value) {
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return String(value);
+  if (!needsQuotes(value)) return value;
+  return `"${value.replace(/([\\"])/g, "\\$1")}"`;
+}
+function parseFrontmatter(text) {
+  const block = splitBlock(text);
+  if (!block) return null;
+  const entries = readEntries(block.lines);
+  const byKey = new Map(entries.map((e) => [e.key, e]));
+  return {
+    entries,
+    keys: () => entries.map((e) => e.key),
+    has: (key) => byKey.has(key),
+    get: (key) => byKey.get(key)?.value,
+    entry: (key) => byKey.get(key)
+  };
+}
+function rewrite(text, block, lines, ends) {
+  const head = text.slice(0, block.contentStart);
+  const tail = text.slice(block.contentEnd);
+  const middle = lines.map((line2, i) => line2 + (ends[i] ?? "\n")).join("");
+  return head + middle + tail;
+}
+function setKey(text, key, value) {
+  const block = splitBlock(text);
+  if (!block) throw new Error(`cannot set "${key}": the file has no frontmatter`);
+  const entry = readEntries(block.lines).find((e) => e.key === key);
+  const line2 = `${key}: ${formatScalar(value)}`;
+  const lines = [...block.lines];
+  const ends = [...block.ends];
+  if (entry) {
+    lines.splice(entry.start, entry.end - entry.start, line2);
+    ends.splice(entry.start, entry.end - entry.start, ends[entry.start] ?? "\n");
+  } else {
+    lines.push(line2);
+    ends.push(ends[ends.length - 1] ?? defaultEnd(text));
+  }
+  return rewrite(text, block, lines, ends);
+}
+function removeKey(text, key) {
+  const block = splitBlock(text);
+  if (!block) return text;
+  const entry = readEntries(block.lines).find((e) => e.key === key);
+  if (!entry) return text;
+  const lines = [...block.lines];
+  const ends = [...block.ends];
+  lines.splice(entry.start, entry.end - entry.start);
+  ends.splice(entry.start, entry.end - entry.start);
+  return rewrite(text, block, lines, ends);
+}
+function defaultEnd(text) {
+  return text.includes("\r\n") ? "\r\n" : "\n";
+}
+
+// src/shared/schema.ts
+var STATUSES = ["backlog", "options", "doing", "done"];
+var CORE_FIELDS = [
+  "type",
+  "id",
+  "title",
+  "status",
+  "parent",
+  "created",
+  "updated",
+  "board",
+  "prev_status"
+];
+var OPTIONAL_FIELDS = [
+  "owner",
+  "agent",
+  "priority",
+  "due",
+  "blocked",
+  "depends_on",
+  "tags",
+  "archived"
+  // docs/adr/0007-archive-is-a-frontmatter-flag.md: a flag, not a status.
+];
+var INHERITED_FIELDS = ["owner", "agent"];
+var WORK_ITEM_TYPE = "work-item";
+var FOLDERS = ["Boards", "Templates"];
+var BOARDS = "Boards";
+function isStatus(value) {
+  return typeof value === "string" && STATUSES.includes(value);
+}
+function parseWikilink(value) {
+  if (typeof value !== "string") return null;
+  const match = /^\s*\[\[([^\]]+)\]\]\s*$/.exec(value);
+  if (!match) return null;
+  const target = match[1].split("|")[0].split("#")[0].trim();
+  return target === "" ? null : target;
+}
+function formatWikilink(target) {
+  return `[[${target}]]`;
+}
+var UNSAFE_IN_FILENAME = /[\\/:*?"<>|[\]#^]/g;
+function fileNameStem(title) {
+  const stem = title.replace(UNSAFE_IN_FILENAME, "-").replace(/\s+/g, " ").replace(/^[\s.]+|[\s.]+$/g, "");
+  return stem === "" ? "Untitled" : stem;
+}
+function idSuffix(id) {
+  return id.startsWith("wi-") ? id.slice(3) : id;
+}
+function fileNameFor(title, id, taken) {
+  const stem = fileNameStem(title);
+  if (!taken.has(stem.toLowerCase())) return stem;
+  return `${stem}--${idSuffix(id)}`;
+}
+var ID_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+function newId(taken, random = Math.random) {
+  for (let length = 4; length <= 12; length++) {
+    for (let attempt = 0; attempt < 200; attempt++) {
+      let short = "";
+      for (let i = 0; i < length; i++) {
+        short += ID_ALPHABET[Math.floor(random() * ID_ALPHABET.length)];
+      }
+      const id = `wi-${short}`;
+      if (!taken.has(id)) return id;
+    }
+  }
+  throw new Error("could not mint an unused work item id");
+}
+function today(now = /* @__PURE__ */ new Date()) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+
+// src/shared/vault-config.ts
+var WI_CONFIG_FILE = ".wi.json";
+var DEFAULT_VAULT_CONFIG = {
+  workItemFolder: "Boards",
+  defaultRoot: null,
+  extraSections: []
+};
+function parseVaultConfig(text) {
+  if (text === null) return { ...DEFAULT_VAULT_CONFIG, extraSections: [] };
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new Error(`${WI_CONFIG_FILE} must contain valid JSON.`);
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`${WI_CONFIG_FILE} must contain a JSON object.`);
+  }
+  const folderValue = "workItemFolder" in value ? value.workItemFolder : void 0;
+  const rootValue = "defaultRoot" in value ? value.defaultRoot : void 0;
+  const sectionsValue = "extraSections" in value ? value.extraSections : void 0;
+  let workItemFolder = DEFAULT_VAULT_CONFIG.workItemFolder;
+  if (folderValue !== void 0) {
+    if (typeof folderValue !== "string") {
+      throw new Error(`${WI_CONFIG_FILE}: workItemFolder must be a vault-relative folder path.`);
+    }
+    workItemFolder = folderValue.replace(/\/$/, "");
+    if (workItemFolder === "" || workItemFolder.startsWith("/") || workItemFolder.split("/").some((part) => part === "" || part === "." || part === "..") || /[\\:\0]/.test(workItemFolder)) {
+      throw new Error(`${WI_CONFIG_FILE}: workItemFolder must be a vault-relative folder path.`);
+    }
+  }
+  let defaultRoot = null;
+  if (rootValue !== void 0 && rootValue !== null) {
+    if (typeof rootValue !== "string" || rootValue === "" || fileNameStem(rootValue) !== rootValue) {
+      throw new Error(`${WI_CONFIG_FILE}: defaultRoot must be a work-item filename stem.`);
+    }
+    defaultRoot = rootValue;
+  }
+  const extraSections = [];
+  if (sectionsValue !== void 0) {
+    if (!Array.isArray(sectionsValue)) {
+      throw new Error(`${WI_CONFIG_FILE}: extraSections must be an array of non-empty, single-line headings.`);
+    }
+    const headings = sectionsValue;
+    for (const heading of headings) {
+      if (typeof heading !== "string" || heading.trim() === "" || /[\r\n]/.test(heading)) {
+        throw new Error(`${WI_CONFIG_FILE}: extraSections must be an array of non-empty, single-line headings.`);
+      }
+      extraSections.push(heading);
+    }
+  }
+  return { workItemFolder, defaultRoot, extraSections };
+}
+
+// src/shared/archive.ts
+function archiveEdits(archived, toArchived) {
+  if (archived === toArchived) return null;
+  return toArchived ? [{ op: "set", key: "archived", value: true }] : [{ op: "remove", key: "archived" }];
+}
+function archiveOwner(item, parentOf, flagged) {
+  const seen = /* @__PURE__ */ new Set();
+  for (let current = item; current !== null; current = parentOf(current)) {
+    if (seen.has(current)) break;
+    seen.add(current);
+    if (flagged(current)) return current;
+  }
+  return null;
+}
+function activeDescendant(item, childrenOf, statusOf) {
+  const seen = /* @__PURE__ */ new Set([item]);
+  const queue = [...childrenOf(item)];
+  for (let i = 0; i < queue.length; i++) {
+    const child = queue[i];
+    if (seen.has(child)) continue;
+    seen.add(child);
+    if (statusOf(child) === "doing") return child;
+    queue.push(...childrenOf(child));
+  }
+  return null;
+}
+
+// src/cli/vault.ts
+var MARKDOWN = /\.md$/i;
+var IGNORED_HIDDEN = /* @__PURE__ */ new Set([".DS_Store", ".localized", ".gitkeep"]);
+function isUnaccounted(name) {
+  if (!name.startsWith(".")) return false;
+  if (MARKDOWN.test(name)) return false;
+  return !IGNORED_HIDDEN.has(name);
+}
+function findVaultRoot(start) {
+  let dir = resolvePath(start);
+  for (; ; ) {
+    if (existsSync(join(dir, WI_CONFIG_FILE)) || existsSync(join(dir, BOARDS))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+async function scan(root, workItemFolder) {
+  const markdown = [];
+  const unaccounted = [];
+  const misplaced = [];
+  for (const folder of [workItemFolder, ...FOLDERS.filter((name) => name !== BOARDS && name !== workItemFolder && !workItemFolder.startsWith(`${name}/`))]) {
+    const dir = join(root, folder);
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true, recursive: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const parent = (entry.parentPath ?? dir).slice(root.length + 1).split(sep).join("/");
+      const rel = `${parent}/${entry.name}`;
+      if (entry.isDirectory()) continue;
+      if (folder === BOARDS && isUnaccounted(entry.name)) {
+        unaccounted.push(rel);
+        continue;
+      }
+      if (!MARKDOWN.test(entry.name)) continue;
+      if (parent !== folder) {
+        misplaced.push(rel);
+        continue;
+      }
+      markdown.push(rel);
+    }
+  }
+  return { markdown, unaccounted, misplaced };
+}
+function toWorkItem(root, relPath, text) {
+  const frontmatter = parseFrontmatter(text);
+  if (!frontmatter) return null;
+  if (frontmatter.get("type") !== WORK_ITEM_TYPE) return null;
+  const id = frontmatter.get("id");
+  const title = frontmatter.get("title");
+  const status = frontmatter.get("status");
+  const parentRaw = frontmatter.get("parent");
+  return {
+    path: join(root, ...relPath.split("/")),
+    relPath,
+    stem: basename(relPath).replace(MARKDOWN, ""),
+    id: typeof id === "string" ? id : void 0,
+    title: typeof title === "string" && title !== "" ? title : void 0,
+    status: isStatus(status) ? status : void 0,
+    parent: parseWikilink(parentRaw),
+    parentRaw: typeof parentRaw === "string" ? parentRaw : void 0,
+    board: frontmatter.get("board") === true,
+    archived: frontmatter.get("archived") === true,
+    frontmatter,
+    text
+  };
+}
+function compareSiblings(a, b) {
+  const priority = (i) => {
+    const value = i.frontmatter.get("priority");
+    return typeof value === "number" ? value : Number.POSITIVE_INFINITY;
+  };
+  const updated = (i) => {
+    const value = i.frontmatter.get("updated");
+    return typeof value === "string" ? value : "";
+  };
+  return priority(a) - priority(b) || updated(b).localeCompare(updated(a)) || a.stem.localeCompare(b.stem);
+}
+function linkKey(target) {
+  const last = target.split("/").pop() ?? target;
+  return last.replace(MARKDOWN, "").trim().toLowerCase();
+}
+function requireAccountedTree(vault, what) {
+  const files = vault.unaccounted;
+  if (files.length === 0) return;
+  const names = files.slice(0, 3).join(", ");
+  const more = files.length > 3 ? `, and ${files.length - 3} more` : "";
+  const one = files.length === 1;
+  throw new Error(
+    `cannot ${what}: ${names}${more} ${one ? "is" : "are"} not accounted for, so the tree is not fully visible. Let the sync client download ` + (one ? "it" : "them") + " if it is a work item, or delete it if it is a stray file, then retry."
+  );
+}
+async function loadVault(root) {
+  let configText = null;
+  try {
+    configText = await readFile(join(root, WI_CONFIG_FILE), "utf8");
+  } catch (error) {
+    if (!isMissingFile(error)) throw error;
+  }
+  const config = parseVaultConfig(configText);
+  const { markdown, unaccounted, misplaced } = await scan(root, config.workItemFolder);
+  const items = [];
+  const nonItems = [];
+  for (const relPath of markdown) {
+    if (!relPath.startsWith(`${config.workItemFolder}/`)) continue;
+    const text = await readFile(join(root, ...relPath.split("/")), "utf8");
+    const item = toWorkItem(root, relPath, text);
+    if (item) items.push(item);
+    else nonItems.push(relPath);
+  }
+  nonItems.sort();
+  items.sort((a, b) => a.relPath.localeCompare(b.relPath));
+  const byId = /* @__PURE__ */ new Map();
+  const duplicateIds = [];
+  for (const item of items) {
+    if (item.id === void 0) continue;
+    if (byId.has(item.id)) duplicateIds.push(item.id);
+    else byId.set(item.id, item);
+  }
+  const byStem = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const key = item.stem.toLowerCase();
+    if (!byStem.has(key)) byStem.set(key, item);
+  }
+  const byTitle = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    if (item.title === void 0) continue;
+    const key = item.title.toLowerCase();
+    byTitle.set(key, [...byTitle.get(key) ?? [], item]);
+  }
+  const children = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    if (item.parent === null) continue;
+    const key = linkKey(item.parent);
+    if (!byStem.has(key)) continue;
+    children.set(key, [...children.get(key) ?? [], item]);
+  }
+  for (const siblings of children.values()) siblings.sort(compareSiblings);
+  const resolveLink = (target) => target === null ? void 0 : byStem.get(linkKey(target));
+  const resolve3 = (ref) => {
+    const trimmed = ref.trim();
+    const byIdHit = byId.get(trimmed);
+    if (byIdHit) return byIdHit;
+    const byStemHit = byStem.get(linkKey(trimmed));
+    if (byStemHit) return byStemHit;
+    const byTitleHits = byTitle.get(trimmed.toLowerCase()) ?? [];
+    if (byTitleHits.length === 1) return byTitleHits[0];
+    if (byTitleHits.length > 1) {
+      const options = byTitleHits.map((i) => `${i.id ?? "?"} (${i.relPath})`).join(", ");
+      throw new Error(`"${ref}" matches ${byTitleHits.length} work items: ${options}. Use an id.`);
+    }
+    throw new Error(`no work item matches "${ref}". Try an id, a filename or a title.`);
+  };
+  return {
+    root,
+    config,
+    items,
+    byId,
+    duplicateIds,
+    unaccounted,
+    misplaced,
+    nonItems,
+    takenIds: new Set(byId.keys()),
+    takenStems: new Set(byStem.keys()),
+    resolveLink,
+    resolve: resolve3,
+    childrenOf: (item) => children.get(item.stem.toLowerCase()) ?? [],
+    isArchived: (item) => archiveOwner(item, (current) => resolveLink(current.parent) ?? null, (current) => current.archived) !== null
+  };
+}
+function isMissingFile(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+// src/cli/commands/new.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { join as join3 } from "node:path";
+
+// src/cli/write.ts
+import { writeFile, rename } from "node:fs/promises";
+import { dirname as dirname2, join as join2 } from "node:path";
+
+// src/shared/edits.ts
+function applyEdits(text, edits) {
+  let out = text;
+  for (const edit of edits) {
+    out = edit.op === "set" ? setKey(out, edit.key, edit.value) : removeKey(out, edit.key);
+  }
+  return out;
+}
+function withStamp(edits, stamp = today()) {
+  if (edits.some((e) => e.key === "updated")) return [...edits];
+  return [...edits, { op: "set", key: "updated", value: stamp }];
+}
+
+// src/cli/write.ts
+async function writeAtomic(path, text) {
+  const temp = join2(dirname2(path), `.wi-${process.pid}-${Date.now()}.tmp`);
+  await writeFile(temp, text, "utf8");
+  await rename(temp, path);
+}
+async function editItem(item, edits) {
+  const text = applyEdits(item.text, withStamp(edits));
+  if (text !== item.text) await writeAtomic(item.path, text);
+  return text;
+}
+
+// src/shared/templates.ts
+var TEMPLATES = [
+  {
+    name: "work-item",
+    description: "The default. What every work item starts as.",
+    sections: [
+      { heading: "Objective" },
+      { heading: "Context" },
+      { heading: "Acceptance Criteria", starter: "- " },
+      { heading: "Notes" }
+    ]
+  }
+];
+var DEFAULT_TEMPLATE = "work-item";
+function templateNames() {
+  return TEMPLATES.map((t) => t.name);
+}
+function findTemplate(name) {
+  return TEMPLATES.find((t) => t.name === name);
+}
+function requireTemplate(name = DEFAULT_TEMPLATE) {
+  const template = findTemplate(name);
+  if (template) return template;
+  throw new Error(`no template called "${name}". There is: ${templateNames().join(", ")}.`);
+}
+function renderBody(template, extraSections = []) {
+  const parts = [];
+  const sections = [
+    ...template.sections,
+    ...extraSections.map((heading) => ({ heading, starter: "- " }))
+  ];
+  for (const section of sections) {
+    parts.push(`## ${section.heading}`, "");
+    if (section.starter !== void 0) parts.push(section.starter, "");
+  }
+  return parts.join("\n");
+}
+function renderVaultTemplate(template, defaultRoot = null, extraSections = []) {
+  const placeholders = {
+    type: formatScalar(WORK_ITEM_TYPE),
+    id: "wi-XXXX",
+    title: "",
+    status: "backlog",
+    parent: defaultRoot === null ? "" : formatScalar(formatWikilink(defaultRoot)),
+    created: "",
+    updated: ""
+  };
+  const lines = CORE_FIELDS.filter((field) => field in placeholders).map(
+    (field) => `${field}: ${placeholders[field]}`.trimEnd()
+  );
+  return `---
+${lines.join("\n")}
+---
+
+${renderBody(template, extraSections)}`;
+}
+
+// src/shared/work-item.ts
+function renderWorkItem(item, extraSections = []) {
+  const fields = [
+    ["type", WORK_ITEM_TYPE],
+    ["id", item.id],
+    ["title", item.title],
+    ["status", item.status],
+    ["parent", formatWikilink(item.parentStem)]
+  ];
+  if (item.owner !== void 0 && item.owner !== "") fields.push(["owner", item.owner]);
+  if (item.agent !== void 0 && item.agent !== "") fields.push(["agent", item.agent]);
+  if (item.priority !== void 0) fields.push(["priority", item.priority]);
+  fields.push(["created", item.created], ["updated", item.updated]);
+  const frontmatter = fields.map(([key, value]) => `${key}: ${formatScalar(value)}`).join("\n");
+  return `---
+${frontmatter}
+---
+
+${renderBody(requireTemplate(item.template), extraSections)}`;
+}
+
+// src/cli/commands/new.ts
+async function createItem(vault, options) {
+  const title = options.title.trim();
+  if (title === "") throw new Error("a work item needs a title");
+  const parentRef = options.parent ?? vault.config.defaultRoot ?? "";
+  if (parentRef.trim() === "") {
+    throw new Error("a work item needs a --parent. Only the root has none.");
+  }
+  requireTemplate(options.template);
+  const status = options.status ?? "backlog";
+  if (!isStatus(status)) {
+    throw new Error(`"${status}" is not a status. Use backlog, options, doing or done.`);
+  }
+  const parent = vault.resolve(parentRef);
+  const id = newId(vault.takenIds);
+  const stem = fileNameFor(title, id, vault.takenStems);
+  const relPath = `${vault.config.workItemFolder}/${stem}.md`;
+  const path = join3(vault.root, ...vault.config.workItemFolder.split("/"), `${stem}.md`);
+  if (existsSync2(path)) {
+    throw new Error(`${relPath} already exists. Refusing to overwrite it.`);
+  }
+  const stamp = today();
+  const fields = {
+    id,
+    title,
+    status,
+    parentStem: parent.stem,
+    created: stamp,
+    updated: stamp,
+    template: options.template
+  };
+  for (const field of INHERITED_FIELDS) {
+    const value = options[field] ?? parent.frontmatter.get(field);
+    if (value !== void 0 && value !== "") fields[field] = String(value);
+  }
+  if (options.priority !== void 0) fields.priority = options.priority;
+  await writeAtomic(path, renderWorkItem(fields, vault.config.extraSections));
+  return { id, stem, relPath, path, parentStem: parent.stem };
+}
+
+// src/shared/transitions.ts
+function statusEdits(from, to, hasPrevStatus) {
+  if (from === to) return null;
+  const edits = [{ op: "set", key: "status", value: to }];
+  if (to === "done") {
+    if (from !== void 0) edits.push({ op: "set", key: "prev_status", value: from });
+  } else if (hasPrevStatus) {
+    edits.push({ op: "remove", key: "prev_status" });
+  }
+  return edits;
+}
+function moveEdits(currentParentStem, targetStem) {
+  if (currentParentStem !== null && currentParentStem.toLowerCase() === targetStem.toLowerCase()) {
+    return null;
+  }
+  return [{ op: "set", key: "parent", value: formatWikilink(targetStem) }];
+}
+function moveRefusal(check) {
+  const { item, target, isRoot, parentOf } = check;
+  if (isRoot) {
+    return "it is a root, and a root has no parent to change.";
+  }
+  if (item === target) return "an item cannot be moved under itself.";
+  const seen = /* @__PURE__ */ new Set();
+  for (let key = target; key !== null; key = parentOf(key)) {
+    if (key === item) return "the target is under its own subtree, so the move would make a loop.";
+    if (seen.has(key)) break;
+    seen.add(key);
+  }
+  return null;
+}
+
+// src/cli/commands/status.ts
+async function setStatus(vault, ref, status) {
+  if (!isStatus(status)) {
+    throw new Error(`"${status}" is not a status. Use one of: ${STATUSES.join(", ")}.`);
+  }
+  const item = vault.resolve(ref);
+  if (item.parent === null) {
+    throw new Error(
+      `${item.relPath} is a root, and a root is not a card in anyone's column. It takes no status.`
+    );
+  }
+  const from = item.status;
+  const edits = statusEdits(from, status, item.frontmatter.has("prev_status"));
+  if (edits === null) {
+    return { item, from, to: status, recorded: void 0, changed: false };
+  }
+  const recorded = status === "done" ? from : void 0;
+  await editItem(item, edits);
+  return { item, from, to: status, recorded, changed: true };
+}
+
+// src/cli/commands/children.ts
+function listChildren(vault, ref, options = {}) {
+  const { status, recursive = false, archived = false } = options;
+  if (status !== void 0 && !isStatus(status)) {
+    throw new Error(`"${status}" is not a status. Use one of: ${STATUSES.join(", ")}.`);
+  }
+  const parent = vault.resolve(ref);
+  const rows = [];
+  const seen = /* @__PURE__ */ new Set([parent.relPath]);
+  let cycle = false;
+  const walk = (item, depth) => {
+    for (const child of vault.childrenOf(item)) {
+      if (seen.has(child.relPath)) {
+        cycle = true;
+        continue;
+      }
+      seen.add(child.relPath);
+      const effectiveArchived = vault.isArchived(child);
+      if (!effectiveArchived || archived) {
+        rows.push({ item: child, childCount: vault.childrenOf(child).filter((kid) => !vault.isArchived(kid) || archived).length, depth, archived: effectiveArchived });
+      }
+      if (recursive) walk(child, depth + 1);
+    }
+  };
+  walk(parent, 0);
+  const filtered = status === void 0 ? rows : rows.filter((r) => r.item.status === status);
+  const byStatus = /* @__PURE__ */ new Map();
+  for (const value of STATUSES) {
+    byStatus.set(value, filtered.filter((r) => r.item.status === value));
+  }
+  return { parent, children: filtered, byStatus, cycle };
+}
+
+// src/cli/commands/validate.ts
+var ID_SHAPE = /^wi-[a-z0-9]+$/;
+var DATE_SHAPE = /^\d{4}-\d{2}-\d{2}$/;
+var KNOWN_FIELDS = /* @__PURE__ */ new Set([...CORE_FIELDS, ...OPTIONAL_FIELDS]);
+var DATE_FIELDS = ["created", "updated"];
+async function validate(vault) {
+  const problems = [];
+  const report = (rule, severity, relPath, id, message) => problems.push({ rule, severity, relPath, id, message });
+  checkLayout(vault, report);
+  checkIdentity(vault, report);
+  for (const item of vault.items) {
+    checkItem(item, vault, report);
+  }
+  checkDefaultRoot(vault, report);
+  checkRoots(vault, report);
+  checkCycles(vault, report);
+  problems.sort((a, b) => a.relPath.localeCompare(b.relPath) || a.rule.localeCompare(b.rule));
+  const errorCount = problems.filter((p) => p.severity === "error").length;
+  return {
+    problems,
+    errorCount,
+    warningCount: problems.length - errorCount,
+    ok: errorCount === 0,
+    itemCount: vault.items.length
+  };
+}
+function checkDefaultRoot(vault, report) {
+  const configured = vault.config.defaultRoot;
+  if (configured === null) return;
+  const target = vault.items.find((item) => item.stem.toLowerCase() === configured.toLowerCase());
+  if (target !== void 0 && target.parent === null) return;
+  report(
+    "default-root-unresolved",
+    "warning",
+    ".wi.json",
+    target?.id,
+    `sets defaultRoot to "${configured}", which does not name a root work item.`
+  );
+}
+function checkLayout(vault, report) {
+  for (const relPath of vault.misplaced) {
+    report(
+      "folder-nested",
+      "error",
+      relPath,
+      void 0,
+      "sits below one of the product folders. Hierarchy lives in the parent wikilink, never in a folder."
+    );
+  }
+  for (const relPath of vault.nonItems) {
+    report(
+      "not-a-work-item",
+      "warning",
+      relPath,
+      void 0,
+      `sits in ${vault.config.workItemFolder}/ but has no \`type: work-item\`. The board will never show it.`
+    );
+  }
+  for (const relPath of vault.unaccounted) {
+    report(
+      "unaccounted-file",
+      "warning",
+      relPath,
+      void 0,
+      "is a hidden file that is not Markdown, so its contents were not read. Let the sync client download it if it is a work item, or delete it if it is a stray file, then validate again."
+    );
+  }
+}
+function checkIdentity(vault, report) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const item of vault.items) {
+    if (item.id === void 0) continue;
+    byId.set(item.id, [...byId.get(item.id) ?? [], item]);
+  }
+  for (const [id, items] of byId) {
+    if (items.length < 2) continue;
+    const files = items.map((i) => i.relPath).join(", ");
+    for (const item of items) {
+      report(
+        "id-duplicate",
+        "error",
+        item.relPath,
+        id,
+        `shares id ${id} with another work item. Both files: ${files}. The id is what recovers the hierarchy, so it must be unique.`
+      );
+    }
+  }
+}
+function checkItem(item, vault, report) {
+  const say = (rule, severity, message) => report(rule, severity, item.relPath, item.id, message);
+  const rawId = item.frontmatter.get("id");
+  if (rawId === void 0 || rawId === "") say("id-missing", "error", "has no id.");
+  else if (!ID_SHAPE.test(String(rawId))) {
+    say("id-malformed", "error", `has id "${rawId}". An id looks like wi-a7f3.`);
+  }
+  if (item.title === void 0) say("title-missing", "error", "has no title.");
+  const rawStatus = item.frontmatter.get("status");
+  const isRoot = !item.frontmatter.has("parent");
+  if (isRoot) {
+    if (rawStatus !== void 0) {
+      say(
+        "status-on-root",
+        "error",
+        `is a root and carries status "${rawStatus}". A root is not a card in anyone's column, so it takes no status.`
+      );
+    }
+  } else if (rawStatus === void 0) {
+    say("status-missing", "error", `has no status. Use one of: ${STATUSES.join(", ")}.`);
+  } else if (!isStatus(rawStatus)) {
+    say(
+      "status-invalid",
+      "error",
+      `has status "${rawStatus}". The four values are ${STATUSES.join(", ")}.`
+    );
+  }
+  if (!isRoot) {
+    const raw = item.frontmatter.get("parent");
+    if (parseWikilink(raw) === null) {
+      say(
+        "parent-malformed",
+        "error",
+        `has parent ${JSON.stringify(raw)}, which is not a wikilink. Write parent: "[[Title]]".`
+      );
+    } else if (vault.resolveLink(item.parent) === void 0) {
+      say(
+        "parent-unresolved",
+        "error",
+        `points at [[${item.parent}]], which no file matches. This item appears on no board. Fix the link or recreate the parent; do not delete the child.`
+      );
+    }
+  }
+  const board = item.frontmatter.get("board");
+  if (board === false) {
+    say(
+      "board-false",
+      "error",
+      "carries board: false. Demotion deletes the key; absence means not a board."
+    );
+  } else if (board !== void 0 && board !== true) {
+    say("board-invalid", "error", `carries board: ${board}. The only value is true.`);
+  }
+  const archived = item.frontmatter.get("archived");
+  if (archived === false) {
+    say(
+      "archived-false",
+      "error",
+      "carries archived: false. Unarchiving deletes the key; absence means visible."
+    );
+  } else if (archived !== void 0 && archived !== true) {
+    say("archived-invalid", "error", `carries archived: ${archived}. The only value is true.`);
+  }
+  const prev = item.frontmatter.get("prev_status");
+  if (prev !== void 0) {
+    if (!isStatus(prev)) {
+      say(
+        "prev-status-invalid",
+        "error",
+        `has prev_status "${prev}". It holds what the item was before it was ticked done.`
+      );
+    } else if (item.status !== "done") {
+      say(
+        "prev-status-stale",
+        "warning",
+        `has prev_status while its status is "${item.status}". Leaving done should clear it.`
+      );
+    }
+  }
+  for (const field of DATE_FIELDS) {
+    const value = item.frontmatter.get(field);
+    if (value === void 0) {
+      say(
+        "date-missing",
+        "error",
+        `has no ${field}. The sibling sort and the Done window both read it.`
+      );
+    } else if (!DATE_SHAPE.test(String(value))) {
+      say("date-invalid", "error", `has ${field}: ${value}. Dates are YYYY-MM-DD.`);
+    }
+  }
+  for (const key of item.frontmatter.keys()) {
+    if (KNOWN_FIELDS.has(key)) continue;
+    say(
+      "unknown-key",
+      "warning",
+      `carries "${key}", which is outside the schema. It is preserved, not stripped. Use a supported field or remove it.`
+    );
+  }
+}
+function checkRoots(vault, report) {
+  const roots = vault.items.filter((i) => !i.frontmatter.has("parent"));
+  if (vault.items.length === 0 && roots.length === 0) {
+    report(
+      "root-missing",
+      "warning",
+      vault.config.workItemFolder,
+      void 0,
+      "holds no work items yet, so the vault has no root."
+    );
+    return;
+  }
+  if (roots.length === 0) {
+    report(
+      "root-missing",
+      "warning",
+      vault.config.workItemFolder,
+      void 0,
+      "holds no root. A root is a work item with no parent, and every board hangs off one."
+    );
+    return;
+  }
+  if (roots.length > 1) {
+    const files = roots.map((r) => r.relPath).join(", ");
+    for (const root of roots) {
+      report(
+        "root-multiple",
+        "warning",
+        root.relPath,
+        root.id,
+        `is one of ${roots.length} roots: ${files}. Nothing forbids this, but a defaultRoot can name only one.`
+      );
+    }
+  }
+}
+function checkCycles(vault, report) {
+  for (const item of vault.items) {
+    const seen = /* @__PURE__ */ new Set([item.relPath]);
+    let current = item;
+    for (; ; ) {
+      current = vault.resolveLink(current.parent);
+      if (current === void 0) break;
+      if (seen.has(current.relPath)) {
+        report(
+          "cycle",
+          "error",
+          item.relPath,
+          item.id,
+          `is its own ancestor. The parent chain loops back through ${current.relPath}.`
+        );
+        break;
+      }
+      seen.add(current.relPath);
+    }
+  }
+}
+
+// src/cli/commands/template.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { existsSync as existsSync3 } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { join as join4 } from "node:path";
+var TEMPLATES_FOLDER = "Templates";
+function listTemplates() {
+  return TEMPLATES;
+}
+async function writeTemplates(vault) {
+  const folder = join4(vault.root, TEMPLATES_FOLDER);
+  await mkdir(folder, { recursive: true });
+  const written = [];
+  for (const template of TEMPLATES) {
+    const path = join4(folder, `${template.name}.md`);
+    const relPath = `${TEMPLATES_FOLDER}/${template.name}.md`;
+    const next = renderVaultTemplate(template, vault.config.defaultRoot, vault.config.extraSections);
+    if (!existsSync3(path)) {
+      await writeAtomic(path, next);
+      written.push({ name: template.name, relPath, outcome: "created" });
+      continue;
+    }
+    const current = await readFile2(path, "utf8");
+    if (current === next) {
+      written.push({ name: template.name, relPath, outcome: "unchanged" });
+      continue;
+    }
+    await writeAtomic(path, next);
+    written.push({ name: template.name, relPath, outcome: "updated" });
+  }
+  return written;
+}
+
+// src/cli/commands/remove.ts
+import { mkdir as mkdir2, rename as rename2 } from "node:fs/promises";
+import { existsSync as existsSync4 } from "node:fs";
+import { join as join5 } from "node:path";
+var TRASH = ".trash";
+function subtree(vault, root) {
+  const ordered = [];
+  const seen = /* @__PURE__ */ new Set([root.relPath]);
+  const walk = (item) => {
+    for (const child of vault.childrenOf(item)) {
+      if (seen.has(child.relPath)) continue;
+      seen.add(child.relPath);
+      walk(child);
+    }
+    ordered.push(item);
+  };
+  walk(root);
+  return ordered;
+}
+function trashPath(vault, item) {
+  const stem = item.stem;
+  for (let n = 0; n < 1e3; n++) {
+    const name = n === 0 ? `${stem}.md` : `${stem} ${n}.md`;
+    if (!existsSync4(join5(vault.root, TRASH, name))) return `${TRASH}/${name}`;
+  }
+  return `${TRASH}/${stem} ${Date.now()}.md`;
+}
+async function removeItem(vault, ref, options = {}) {
+  const { recursive = false, dryRun = false } = options;
+  const item = vault.resolve(ref);
+  requireAccountedTree(vault, `remove ${item.title ?? item.stem}`);
+  if (item.parent === null) {
+    throw new Error(
+      `${item.relPath} is a root. Every board hangs off it, so it is not a card anyone can discard.`
+    );
+  }
+  const children = vault.childrenOf(item);
+  if (children.length > 0 && !recursive) {
+    const names = children.map((c) => `${c.id ?? "?"} ${c.title ?? c.stem}`).join(", ");
+    throw new Error(
+      `${item.title ?? item.stem} has ${children.length} children: ${names}. Removing it would leave them on no board. Move them first, or pass --recursive.`
+    );
+  }
+  const doomed = recursive ? subtree(vault, item) : [item];
+  const removed = [];
+  for (const target of doomed) {
+    const trashedTo = trashPath(vault, target);
+    if (!dryRun) {
+      await mkdir2(join5(vault.root, TRASH), { recursive: true });
+      await rename2(target.path, join5(vault.root, ...trashedTo.split("/")));
+    }
+    removed.push({ item: target, trashedTo });
+  }
+  return { removed, dryRun };
+}
+
+// src/cli/commands/move.ts
+async function moveItem(vault, ref, targetRef) {
+  const item = vault.resolve(ref);
+  const target = vault.resolve(targetRef);
+  requireAccountedTree(vault, `move ${item.title ?? item.stem}`);
+  const key = (w) => w.stem.toLowerCase();
+  const byKey = new Map(vault.items.map((w) => [key(w), w]));
+  const refusal = moveRefusal({
+    item: key(item),
+    target: key(target),
+    isRoot: item.parent === null,
+    parentOf: (k) => {
+      const parent = vault.resolveLink(byKey.get(k)?.parent ?? null);
+      return parent ? key(parent) : null;
+    }
+  });
+  if (refusal !== null) {
+    throw new Error(`cannot move ${item.title ?? item.stem} under ${target.title ?? target.stem}: ${refusal}`);
+  }
+  const edits = moveEdits(item.parent, target.stem);
+  if (edits === null) return { item, from: item.parent, to: target, changed: false };
+  await editItem(item, edits);
+  return { item, from: item.parent, to: target, changed: true };
+}
+
+// src/cli/commands/archive.ts
+async function archiveItem(vault, ref, undo) {
+  const item = vault.resolve(ref);
+  const archived = !undo;
+  requireAccountedTree(vault, `${archived ? "archive" : "unarchive"} ${item.title ?? item.stem}`);
+  const edits = archiveEdits(item.archived, archived);
+  if (edits === null) return { item, archived, changed: false };
+  if (archived) {
+    const active = activeDescendant(item, vault.childrenOf, (child) => child.status);
+    if (active) {
+      throw new Error(`cannot archive ${item.title ?? item.stem}: descendant ${active.title ?? active.stem} (${active.id ?? active.relPath}) is doing.`);
+    }
+  }
+  await editItem(item, edits);
+  return { item, archived, changed: true };
+}
+
+// src/cli/commands/hook.ts
+import { execFile } from "node:child_process";
+import { existsSync as existsSync5 } from "node:fs";
+import { chmod, mkdir as mkdir3, readFile as readFile3, rm, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname as dirname3, resolve } from "node:path";
+import { promisify } from "node:util";
+var run = promisify(execFile);
+var HOOK_MARK = "# installed by scripts/vault-git.mjs";
+async function gitHook(vault) {
+  try {
+    const top = (await run("git", ["-C", vault, "rev-parse", "--show-toplevel"])).stdout.trim();
+    const path = (await run("git", ["-C", vault, "rev-parse", "--git-path", "hooks/pre-commit"])).stdout.trim();
+    return { top, path: resolve(vault, path) };
+  } catch {
+    return null;
+  }
+}
+function isOurHook(body) {
+  return body.split("\n").some((line2) => line2 === HOOK_MARK || line2 === "# installed by wi hook");
+}
+function shellQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function hookBody(vault, entry) {
+  return `#!/bin/sh
+${HOOK_MARK}
+# Edits outside the plugin can leave a vault invalid. Validate before committing.
+# To bypass validation: git commit --no-verify
+
+exec ${shellQuote(process.execPath)} ${shellQuote(entry)} validate --vault ${shellQuote(vault)}
+`;
+}
+async function hookStatus(vault) {
+  const git = await gitHook(vault);
+  if (!git) return { vault, gitRepo: null, preCommit: "not installed" };
+  const present = existsSync5(git.path);
+  const ours = present && isOurHook(await readFile3(git.path, "utf8"));
+  return {
+    vault,
+    gitRepo: git.top,
+    preCommit: ours ? "installed" : present ? "present, not ours" : "not installed"
+  };
+}
+async function installHook(vault, entry, force) {
+  const git = await gitHook(vault);
+  if (!git) throw new Error(`${vault} is not inside a Git repository. Run: git -C ${shellQuote(vault)} init`);
+  if (existsSync5(git.path)) {
+    const current = await readFile3(git.path, "utf8");
+    if (!isOurHook(current) && !force) {
+      throw new Error(`${git.path} already exists and is not ours. Read it, then pass --force to replace it.`);
+    }
+  }
+  await mkdir3(dirname3(git.path), { recursive: true });
+  await writeFile2(git.path, hookBody(vault, entry), "utf8");
+  await chmod(git.path, 493);
+  return git.path;
+}
+async function uninstallHook(vault) {
+  const git = await gitHook(vault);
+  if (!git || !existsSync5(git.path) || !isOurHook(await readFile3(git.path, "utf8"))) return null;
+  await rm(git.path);
+  return git.path;
+}
+
+// src/cli/wi.ts
+var HELP = `wi \u2014 the Recursive Board CLI
+
+Usage
+  wi new <title> [--parent <ref>] [--status <s>] [--template <t>] [--owner <o>] [--agent <a>]
+                                [--priority <n>]
+  wi status <ref> <status>
+  wi move <ref> --to <ref>
+  wi archive <ref> [--undo]
+  wi rm <ref> [--recursive] [--dry-run]
+  wi children <ref> [--status <s>] [--tree] [--archived]
+  wi validate
+  wi template [list|write]
+  wi hook <install|uninstall|status> [--force]
+
+A <ref> is a work item id, a filename or a title. An id always wins.
+A <status> is one of: ${STATUSES.join(", ")}.
+A <template> is one of: ${templateNames().join(", ")}.
+
+Options
+  --vault <path>   The vault root. Defaults to $WI_VAULT, then the nearest configured vault or Boards/.
+  --json           Machine-readable output.
+  --force          Replace another pre-commit hook with wi hook install.
+  -h, --help       This text.
+  -V, --version    Print the version.
+
+Notes
+  Unticking a done item is \`wi status <ref> <its prev_status>\`, which also clears the record.
+  \`wi validate\` exits 1 when the vault has errors, so it works as a pre-commit hook.
+  \`wi template write\` regenerates Templates/ from the code, which is authoritative.
+  \`wi rm\` moves a file to the vault's .trash. It refuses an item that has children
+  unless you pass --recursive, because removing a parent leaves its children on no board.
+  \`wi move\` changes only the item's parent. Its status stays, and its children follow it.
+  \`wi rm\`, \`wi move\` and \`wi archive\` refuse while a hidden non-Markdown file sits in the work-item
+  folder, because the index cannot read it and may be missing a work item. Let the sync
+  client download the file, or delete the stray file, then retry. There is no --force.
+  \`wi archive\` changes one flag. Descendants disappear with their parent at read time.
+  \`wi new\` warns when such a file exists because a new id or filename may clash with it.
+`;
+var VERSION = "0.1.0";
+var UsageError = class extends Error {
+};
+async function main(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    strict: true,
+    options: {
+      parent: { type: "string" },
+      to: { type: "string" },
+      status: { type: "string" },
+      owner: { type: "string" },
+      agent: { type: "string" },
+      priority: { type: "string" },
+      template: { type: "string" },
+      vault: { type: "string" },
+      tree: { type: "boolean", default: false },
+      archived: { type: "boolean", default: false },
+      undo: { type: "boolean", default: false },
+      recursive: { type: "boolean", short: "r", default: false },
+      "dry-run": { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      force: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", short: "V", default: false }
+    }
+  });
+  if (values.version) {
+    process.stdout.write(`${VERSION}
+`);
+    return 0;
+  }
+  const [command, ...rest] = positionals;
+  if (values.help || command === void 0 || command === "help") {
+    process.stdout.write(HELP);
+    return command === void 0 && !values.help ? 2 : 0;
+  }
+  if (values.force && (command !== "hook" || rest[0] !== "install")) {
+    throw new UsageError("--force applies only to wi hook install.");
+  }
+  const vault = await openVault(values.vault);
+  const json = values.json;
+  switch (command) {
+    case "new":
+      return runNew(vault, rest, values, json);
+    case "status":
+      return runStatus(vault, rest, json);
+    case "move":
+      return runMove(vault, rest, values, json);
+    case "archive":
+      return runArchive(vault, rest, values, json);
+    case "rm":
+      return runRemove(vault, rest, values, json);
+    case "children":
+      return runChildren(vault, rest, values, json);
+    case "validate":
+      return runValidate(vault, json);
+    case "template":
+      return runTemplate(vault, rest, json);
+    case "hook":
+      return runHook(vault, rest, values, json);
+    default:
+      throw new UsageError(`unknown command "${command}". Run wi --help.`);
+  }
+}
+async function openVault(flag) {
+  const hint = flag ?? process.env["WI_VAULT"];
+  const root = hint ? resolve2(hint) : findVaultRoot(process.cwd());
+  if (root === null) {
+    throw new UsageError(
+      "no vault found. Run wi inside a vault, pass --vault <path>, or set WI_VAULT."
+    );
+  }
+  if (findVaultRoot(root) !== root) {
+    throw new UsageError(`${root} is not a vault: it has no Boards/ folder or .wi.json.`);
+  }
+  return loadVault(root);
+}
+async function runNew(vault, rest, values, json) {
+  const title = rest.join(" ").trim();
+  if (title === "") throw new UsageError('wi new needs a title. Try: wi new "Build server" --parent Main');
+  const parent = typeof values["parent"] === "string" ? values["parent"] : vault.config.defaultRoot;
+  if (!parent) throw new UsageError("wi new needs --parent <ref> or defaultRoot in .wi.json.");
+  const priority = typeof values["priority"] === "string" ? Number(values["priority"]) : void 0;
+  if (priority !== void 0 && !Number.isFinite(priority)) {
+    throw new UsageError(`--priority must be a number, not "${values["priority"]}".`);
+  }
+  const created = await createItem(vault, {
+    title,
+    parent,
+    ...typeof values["status"] === "string" ? { status: values["status"] } : {},
+    ...typeof values["owner"] === "string" ? { owner: values["owner"] } : {},
+    ...typeof values["agent"] === "string" ? { agent: values["agent"] } : {},
+    ...typeof values["template"] === "string" ? { template: values["template"] } : {},
+    ...priority !== void 0 ? { priority } : {}
+  });
+  if (vault.unaccounted.length > 0) {
+    process.stderr.write(
+      `wi: warning: a new id or filename may clash with an unread file. Unread files: ${vault.unaccounted.join(", ")}.
+`
+    );
+  }
+  if (json) print({ id: created.id, path: created.relPath, parent: created.parentStem });
+  else process.stdout.write(`${created.id}  ${created.relPath}  (child of ${created.parentStem})
+`);
+  return 0;
+}
+async function runStatus(vault, rest, json) {
+  const [ref, status] = rest;
+  if (ref === void 0 || status === void 0) {
+    throw new UsageError(`wi status needs a <ref> and a <status>. One of: ${STATUSES.join(", ")}.`);
+  }
+  const change = await setStatus(vault, ref, status);
+  if (json) {
+    print({
+      id: change.item.id,
+      path: change.item.relPath,
+      from: change.from ?? null,
+      to: change.to,
+      prev_status: change.recorded ?? null,
+      changed: change.changed
+    });
+  } else if (!change.changed) {
+    process.stdout.write(`${label(change.item)} is already ${change.to}. Nothing written.
+`);
+  } else {
+    const recorded = change.recorded ? `  (prev_status: ${change.recorded})` : "";
+    process.stdout.write(`${label(change.item)}  ${change.from ?? "\u2014"} \u2192 ${change.to}${recorded}
+`);
+  }
+  return 0;
+}
+async function runMove(vault, rest, values, json) {
+  const ref = rest.join(" ").trim();
+  const to = typeof values["to"] === "string" ? values["to"] : "";
+  if (ref === "" || to === "") {
+    throw new UsageError("wi move needs a <ref> and --to <ref>. Try: wi move wi-a7f3 --to Main");
+  }
+  const result = await moveItem(vault, ref, to);
+  if (json) {
+    print({
+      id: result.item.id,
+      path: result.item.relPath,
+      from: result.from,
+      to: result.to.stem,
+      changed: result.changed
+    });
+  } else if (!result.changed) {
+    process.stdout.write(`${label(result.item)} is already under ${result.to.stem}. Nothing written.
+`);
+  } else {
+    process.stdout.write(`${label(result.item)}  ${result.from ?? "\u2014"} \u2192 ${result.to.stem}
+`);
+  }
+  return 0;
+}
+async function runArchive(vault, rest, values, json) {
+  const ref = rest.join(" ").trim();
+  if (ref === "") throw new UsageError("wi archive needs a <ref>.");
+  const change = await archiveItem(vault, ref, values["undo"] === true);
+  if (json) {
+    print({ id: change.item.id, path: change.item.relPath, archived: change.archived, changed: change.changed });
+  } else {
+    const verb = change.archived ? "archived" : "unarchived";
+    process.stdout.write(`${label(change.item)}  ${verb}${change.changed ? "" : " (already so; nothing written)"}
+`);
+  }
+  return 0;
+}
+async function runRemove(vault, rest, values, json) {
+  const ref = rest.join(" ").trim();
+  if (ref === "") throw new UsageError("wi rm needs a <ref>.");
+  const result = await removeItem(vault, ref, {
+    recursive: values["recursive"] === true,
+    dryRun: values["dry-run"] === true
+  });
+  if (json) {
+    print({
+      dryRun: result.dryRun,
+      removed: result.removed.map((r) => ({
+        id: r.item.id,
+        title: r.item.title,
+        from: r.item.relPath,
+        to: r.trashedTo
+      }))
+    });
+    return 0;
+  }
+  const verb = result.dryRun ? "would remove" : "removed";
+  for (const entry of result.removed) {
+    const id = entry.item.id ?? "(no id)";
+    process.stdout.write(`${verb}  ${id}  ${entry.item.relPath} -> ${entry.trashedTo}
+`);
+  }
+  const count = result.removed.length;
+  process.stdout.write(`${count} work item${count === 1 ? "" : "s"}${result.dryRun ? ", nothing written" : ""}
+`);
+  return 0;
+}
+function runChildren(vault, rest, values, json) {
+  const ref = rest.join(" ").trim();
+  if (ref === "") throw new UsageError("wi children needs a <ref>.");
+  const listing = listChildren(vault, ref, {
+    ...typeof values["status"] === "string" ? { status: values["status"] } : {},
+    recursive: values["tree"] === true,
+    archived: values["archived"] === true
+  });
+  if (json) {
+    print({
+      parent: { id: listing.parent.id, path: listing.parent.relPath, board: listing.parent.board },
+      cycle: listing.cycle,
+      children: listing.children.map((row) => ({
+        id: row.item.id,
+        title: row.item.title,
+        path: row.item.relPath,
+        status: row.item.status ?? null,
+        children: row.childCount,
+        depth: row.depth,
+        archived: row.archived
+      }))
+    });
+    return 0;
+  }
+  const out = [
+    `${label(listing.parent)}${listing.parent.board ? "  [board]" : ""}`
+  ];
+  if (listing.children.length === 0) {
+    out.push("  no children");
+  } else if (values["tree"] === true || typeof values["status"] === "string") {
+    for (const row of listing.children) out.push(`  ${"  ".repeat(row.depth)}${row3(row)}`);
+  } else {
+    for (const [status, rows] of listing.byStatus) {
+      out.push(`  ${status} (${rows.length})`);
+      for (const row of rows) out.push(`    ${row3(row)}`);
+    }
+  }
+  if (listing.cycle) out.push("  ! the parent chain loops. Run wi validate.");
+  process.stdout.write(`${out.join("\n")}
+`);
+  return 0;
+}
+async function runValidate(vault, json) {
+  const report = await validate(vault);
+  if (json) {
+    print({
+      ok: report.ok,
+      items: report.itemCount,
+      errors: report.errorCount,
+      warnings: report.warningCount,
+      problems: report.problems
+    });
+    return report.ok ? 0 : 1;
+  }
+  for (const problem of report.problems) process.stdout.write(`${line(problem)}
+`);
+  const counts = `${report.itemCount} work items, ${report.errorCount} errors, ${report.warningCount} warnings`;
+  process.stdout.write(report.ok ? `ok: ${counts}
+` : `FAILED: ${counts}
+`);
+  return report.ok ? 0 : 1;
+}
+async function runTemplate(vault, rest, json) {
+  const action = rest[0] ?? "list";
+  if (action === "list") {
+    const templates = listTemplates();
+    if (json) {
+      print(templates.map((t) => ({
+        name: t.name,
+        description: t.description,
+        sections: t.sections.map((s) => s.heading)
+      })));
+      return 0;
+    }
+    for (const template of templates) {
+      process.stdout.write(`${template.name.padEnd(14)}  ${template.description}
+`);
+      process.stdout.write(`${" ".repeat(16)}${template.sections.map((s) => s.heading).join(", ")}
+`);
+    }
+    return 0;
+  }
+  if (action === "write") {
+    const written = await writeTemplates(vault);
+    if (json) {
+      print(written);
+      return 0;
+    }
+    for (const entry of written) {
+      process.stdout.write(`${entry.outcome.padEnd(10)}${entry.relPath}
+`);
+    }
+    return 0;
+  }
+  throw new UsageError(`wi template takes "list" or "write", not "${action}".`);
+}
+async function runHook(vault, rest, values, json) {
+  const [action, ...extra] = rest;
+  if (extra.length > 0 || action !== "install" && action !== "uninstall" && action !== "status") {
+    throw new UsageError("wi hook needs install, uninstall, or status. Run wi --help.");
+  }
+  if (values["force"] === true && action !== "install") {
+    throw new UsageError("--force applies only to wi hook install.");
+  }
+  if (action === "status") {
+    const status = await hookStatus(vault.root);
+    if (json) print(status);
+    else {
+      process.stdout.write(`vault        ${status.vault}
+`);
+      process.stdout.write(`git repo     ${status.gitRepo ?? "none \u2014 run git init in the vault"}
+`);
+      if (status.gitRepo) process.stdout.write(`pre-commit   ${status.preCommit}
+`);
+    }
+    return 0;
+  }
+  if (action === "uninstall") {
+    const removed = await uninstallHook(vault.root);
+    if (json) print({ removed });
+    else process.stdout.write(removed ? `removed ${removed}
+` : "done\n");
+    return 0;
+  }
+  const path = await installHook(vault.root, fileURLToPath(import.meta.url), values["force"] === true);
+  if (json) print({ installed: path });
+  else {
+    process.stdout.write(`installed ${path}
+`);
+    process.stdout.write("a commit that would record an invalid vault is now refused\n");
+    process.stdout.write("bypass with: git commit --no-verify\n");
+  }
+  const report = await validate(vault);
+  if (!report.ok && !json) {
+    process.stdout.write("\nheads up: the vault does not validate right now, so the next commit will be refused:\n");
+    for (const problem of report.problems) process.stdout.write(`${line(problem)}
+`);
+  }
+  return 0;
+}
+function line(problem) {
+  const mark = problem.severity === "error" ? "error" : "warn ";
+  return `${mark}  ${problem.relPath}  [${problem.rule}] ${problem.message}`;
+}
+function label(item) {
+  return `${item.id ?? "(no id)"}  ${item.title ?? item.stem}`;
+}
+function row3(row) {
+  const status = row.item.status ?? "\u2014";
+  const kids = row.childCount > 0 ? `  (${row.childCount})` : "";
+  const board = row.item.board ? "  [board]" : "";
+  const archived = row.archived ? "  [archived]" : "";
+  return `${row.item.id ?? "(no id)"}  ${status.padEnd(7)}  ${row.item.title ?? row.item.stem}${kids}${board}${archived}`;
+}
+function print(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+}
+try {
+  process.exitCode = await main(process.argv.slice(2));
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`wi: ${message}
+`);
+  process.exitCode = 2;
+}