honestdocs 0.0.0-stage → 0.1.0

package/src/commands/init.mjs

@@ -0,0 +1,166 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { c, die, ok, parseArgs, say } from "../cli.mjs";
+import { CONFIG_FILE, CONFIG_IN_ROOT, DEFAULT_AREAS, DEFAULT_ROOT, findConfig, loadConfig } from "../config.mjs";
+import { today } from "../docs.mjs";
+import { stringify } from "../frontmatter.mjs";
+import { fill, packageFile } from "../templates.mjs";
+import { report, runIndex } from "./index.mjs";
+
+export const summary = "set honestdocs up in this project";
+
+export const help = `honestdocs init — ${summary}
+
+  honestdocs init [--root <dir>] [--area <name[=description]>]… [--code-repo <path>]…
+                  [--title <text>] [--agents] [--agents-file <file>] [--skill]
+
+Creates ${DEFAULT_ROOT}/ with its config, a README, a first rule document
+(rules/…-before-you-build.md) and INDEX.md. Refuses a folder that already
+holds Markdown files — your own docs stay yours.
+
+  --root <dir>          the documents folder (default: ${DEFAULT_ROOT}). With
+                        any other folder the config goes to ${CONFIG_FILE}
+                        at the top of the project instead.
+  --area <name>         an area; repeat for more (default: general, rules).
+                        "rules" is always added.
+  --code-repo <path>    where commits carrying the trailer are read from
+                        (default: "."). Repeat for several repositories, or
+                        point at the parent when the documents are a separate
+                        repository nested inside the code.
+  --title <text>        the heading of INDEX.md
+  --agents              add the honestdocs section to AGENTS.md (created if
+                        missing; updated in place between markers on re-runs)
+  --agents-file <file>  the same, into another file — CLAUDE.md, say
+  --skill               install the agent skill at .claude/skills/honestdocs/
+
+Run again in a project that is already set up, --agents and --skill refresh
+those two and change nothing else.
+`;
+
+function hasMarkdown(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === ".git" || entry.name === "node_modules") continue;
+    if (entry.isDirectory() ? hasMarkdown(join(dir, entry.name)) : entry.name.endsWith(".md")) return true;
+  }
+  return false;
+}
+
+const START = "<!-- honestdocs:start -->";
+const END = "<!-- honestdocs:end -->";
+
+/** Insert or replace the marked block, leaving everything else in the file alone. */
+function upsertBlock(file, block) {
+  const wrapped = `${START}\n${block.trim()}\n${END}`;
+  if (!existsSync(file)) {
+    writeFileSync(file, wrapped + "\n");
+    return "created";
+  }
+  const text = readFileSync(file, "utf8");
+  const a = text.indexOf(START);
+  const b = text.indexOf(END);
+  if (a >= 0 && b > a) {
+    const next = text.slice(0, a) + wrapped + text.slice(b + END.length);
+    if (next === text) return "unchanged";
+    writeFileSync(file, next);
+    return "updated";
+  }
+  writeFileSync(file, text.replace(/\s*$/, "\n\n") + wrapped + "\n");
+  return "appended";
+}
+
+function installAgentBits(base, args, root, trailer) {
+  const values = { root, trailer };
+  if (args.agents || args["agents-file"]) {
+    const file = resolve(base, args["agents-file"] ?? "AGENTS.md");
+    const how = upsertBlock(file, fill(packageFile("guide", "agents-snippet.md"), values));
+    ok(`${relative(base, file)} — honestdocs section ${how}`);
+  }
+  if (args.skill) {
+    const file = join(base, ".claude", "skills", "honestdocs", "SKILL.md");
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, fill(packageFile("guide", "skill", "SKILL.md"), values));
+    ok(`${relative(base, file).split("\\").join("/")} — skill installed`);
+  }
+}
+
+export function run(argv) {
+  const args = parseArgs(argv, {
+    root: "string", area: "list", "code-repo": "list", title: "string",
+    agents: "boolean", "agents-file": "string", skill: "boolean",
+  });
+  const cwd = process.cwd();
+
+  const existing = findConfig(cwd);
+  if (existing) {
+    const config = loadConfig(cwd);
+    if (!args.agents && !args["agents-file"] && !args.skill) {
+      die(`already set up: ${existing.file} — re-run with --agents or --skill to refresh those`);
+    }
+    installAgentBits(config.base, args, config.root, config.trailer);
+    return;
+  }
+
+  const root = (args.root ?? DEFAULT_ROOT).replace(/[\\/]+$/, "").replace(/^\.[\\/]/, "");
+  const target = resolve(cwd, root);
+  if (existsSync(target) && hasMarkdown(target)) {
+    die(`${root}/ already holds Markdown files — choose another folder with --root`);
+  }
+  const areas = {};
+  for (const spec of args.area.length ? args.area : Object.keys(DEFAULT_AREAS)) {
+    const [name, ...rest] = spec.split("=");
+    areas[name.trim()] = rest.join("=").trim() || DEFAULT_AREAS[name.trim()] || "";
+  }
+  if (!areas.rules) areas.rules = DEFAULT_AREAS.rules;
+
+  const raw = {
+    root,
+    title: args.title ?? "Development documents",
+    areas,
+    trailer: "Doc",
+    codeRepos: args["code-repo"].length ? args["code-repo"] : ["."],
+  };
+  const configPath = root === DEFAULT_ROOT ? CONFIG_IN_ROOT : CONFIG_FILE;
+  mkdirSync(dirname(join(cwd, configPath)), { recursive: true });
+  writeFileSync(join(cwd, configPath), JSON.stringify(raw, null, 2) + "\n");
+  ok(configPath);
+
+  const config = loadConfig(cwd);
+  mkdirSync(join(config.docsDir, "rules"), { recursive: true });
+
+  const readme = join(config.docsDir, "README.md");
+  if (!existsSync(readme)) {
+    writeFileSync(readme, fill(packageFile("guide", "docs-readme.md"), { root, trailer: config.trailer }));
+    ok(`${root}/README.md`);
+  }
+
+  const id = `${today()}-before-you-build`;
+  const rulesFile = join(config.docsDir, "rules", `${id}.md`);
+  const meta = {
+    id,
+    title: "Before you build: the checklist every change goes through",
+    area: "rules",
+    type: "rule",
+    status: "current",
+    created: today(),
+    updated: today(),
+    completed: "",
+    progress: "",
+    supersedes: [],
+    "superseded-by": "",
+    related: [],
+    files: [],
+  };
+  writeFileSync(rulesFile, stringify(meta) + fill(packageFile("guide", "before-you-build.md"), { root, trailer: config.trailer }));
+  ok(`${root}/rules/${id}.md`);
+
+  installAgentBits(config.base, args, root, config.trailer);
+  report(config, runIndex(config), false);
+
+  say("");
+  const area = Object.keys(config.areas).find((a) => a !== "rules") ?? "rules";
+  say("Next:");
+  say(c.dim(`  start a document     honestdocs new ${area} my-first-design --title "…"`));
+  say(c.dim(`  link work to it      git commit -m "…" -m "${config.trailer}: <id>"`));
+  say(c.dim("  keep it honest       honestdocs index && honestdocs check"));
+  if (!args.agents && !args["agents-file"]) say(c.dim("  teach your agents    honestdocs init --agents"));
+}

package/src/commands/new.mjs

@@ -0,0 +1,91 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { UsageError, c, die, emitJson, ok, parseArgs, say } from "../cli.mjs";
+import { loadConfig, statusesFor } from "../config.mjs";
+import { loadDocs, slugify, today } from "../docs.mjs";
+import { stringify } from "../frontmatter.mjs";
+import { fill, templateFor } from "../templates.mjs";
+
+export const summary = "start a document";
+
+export const help = `honestdocs new — ${summary}
+
+  honestdocs new <area> <slug> --title "<title>" [--type <type>]
+
+Writes <root>/<area>/<YYYY-MM-DD>-<slug>.md with its frontmatter filled in and
+the body template for its type, and prints the path on stdout.
+With a single area configured, <area> may be left out.
+
+  --type <type>        default: design
+  --status <status>    default: draft
+  --supersedes <id>    this document replaces <id> (repeatable)
+  --related <id>       a related document or path (repeatable)
+  --dry-run            print what would be written, write nothing
+  --json               { id, path, type, status } on stdout
+`;
+
+export function run(argv) {
+  const args = parseArgs(argv, {
+    type: "string", title: "string", status: "string",
+    supersedes: "list", related: "list", "dry-run": "boolean", json: "boolean",
+  });
+  const config = loadConfig();
+  const areas = Object.keys(config.areas);
+
+  let [area, rawSlug] = args._;
+  if (args._.length === 1 && areas.length === 1) [area, rawSlug] = [areas[0], args._[0]];
+  if (!area || !rawSlug) throw new UsageError("need <area> and <slug>");
+  if (!areas.includes(area)) die(`unknown area "${area}" — expected one of: ${areas.join(", ")}`);
+
+  const type = args.type ?? "design";
+  if (!config.types[type]) die(`unknown type "${type}" — expected one of: ${Object.keys(config.types).join(", ")}`);
+
+  const statuses = statusesFor(config, type);
+  const status = args.status ?? "draft";
+  if (!statuses[status]) die(`"${status}" is not a status for a ${type} — expected one of: ${Object.keys(statuses).join(", ")}`);
+
+  if (!args.title) throw new UsageError('need --title "…" — an index of ids nobody can read is no index');
+
+  const slug = slugify(rawSlug);
+  if (!slug) die(`"${rawSlug}" leaves nothing usable for a filename — use letters and digits`);
+  const id = `${today()}-${slug}`;
+  const docs = loadDocs(config);
+  if (docs.some((d) => d.id === id)) die(`a document with the id ${id} already exists`);
+  for (const target of args.supersedes) {
+    if (!docs.some((d) => d.id === target)) die(`--supersedes ${target}: no document has that id`);
+  }
+
+  const meta = {
+    id,
+    title: args.title,
+    area,
+    type,
+    status,
+    created: today(),
+    updated: today(),
+    completed: "",
+    progress: "",
+    supersedes: args.supersedes,
+    "superseded-by": "",
+    related: args.related,
+    files: [],
+  };
+  const content = stringify(meta) + fill(templateFor(config, type), { title: args.title, id, date: today() });
+  const file = join(config.docsDir, area, `${id}.md`);
+  const shown = relative(config.base, file).split("\\").join("/");
+
+  if (args["dry-run"]) {
+    say(c.dim(`would write ${shown}`));
+    say(content);
+    return;
+  }
+  if (existsSync(file)) die(`${shown} already exists`);
+  mkdirSync(join(config.docsDir, area), { recursive: true });
+  writeFileSync(file, content);
+
+  if (args.json) return emitJson({ id, path: shown, type, status });
+  ok(c.dim(`${type} · ${area} · ${status}`));
+  say(c.dim(`  Put "${config.trailer}: ${id}" in the commits that do this work —`));
+  say(c.dim("  that is how `honestdocs index` learns which files it touched."));
+  console.log(shown);
+}

package/src/commands/promote.mjs

@@ -0,0 +1,55 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { UsageError, c, die, ok, parseArgs, say } from "../cli.mjs";
+import { asList, findDoc, loadDocs, writeDoc } from "../docs.mjs";
+import { loadConfig } from "../config.mjs";
+
+export const summary = "scaffold a public document from a development document";
+
+export const help = `honestdocs promote — ${summary}
+
+  honestdocs promote <id> --to <path.md> [--dry-run]
+
+Creates <path.md> with the source's headings and nothing else, and links the two
+both ways. The prose is not copied on purpose: a development document explains a
+decision to the people who were there; a public document explains the result to
+someone who was not. Translating one into the other serves neither.
+`;
+
+export function run(argv) {
+  const args = parseArgs(argv, { to: "string", "dry-run": "boolean" });
+  const [id] = args._;
+  if (!id || !args.to) throw new UsageError("need <id> and --to <path.md>");
+  const config = loadConfig();
+  const doc = findDoc(loadDocs(config), id);
+  if (!doc) die(`no document with the id "${id}"`);
+
+  const out = isAbsolute(args.to) ? args.to : resolve(process.cwd(), args.to);
+  const shown = relative(config.base, out).split("\\").join("/");
+  if (shown.startsWith("..")) die(`--to must be inside the project (${config.base})`);
+  if (existsSync(out)) die(`${shown} already exists`);
+
+  const headings = doc.body.split(/\r?\n/).filter((l) => /^#{2,3} /.test(l));
+  const skeleton = [
+    `# ${doc.meta.title ?? id}`,
+    "",
+    `<!-- Started from the development document ${id}. Written for someone who has never`,
+    "     seen this project: what it does, how to use it, what goes wrong. Why it was",
+    `     chosen stays in ${config.root}/. -->`,
+    "",
+    ...headings.flatMap((h) => [h, "", "_TODO_", ""]),
+  ].join("\n");
+
+  if (args["dry-run"]) {
+    say(c.yellow(`dry run — would write ${shown}`));
+    say(skeleton);
+    return;
+  }
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, skeleton);
+  doc.meta.related = [...new Set([...asList(doc.meta.related), shown])];
+  writeDoc(doc);
+  ok(shown);
+  say(c.dim(`  ${doc.rel} now lists it under related.`));
+  console.log(shown);
+}

package/src/commands/rules.mjs

@@ -0,0 +1,51 @@
+import { emitJson, parseArgs } from "../cli.mjs";
+import { loadConfig } from "../config.mjs";
+import { loadDocs } from "../docs.mjs";
+import { parseRules } from "../rules.mjs";
+
+export const summary = "list the rules in force, with the tests that prove them";
+
+export const help = `honestdocs rules — ${summary}
+
+  honestdocs rules [<id-prefix>] [--all] [--json]
+
+Reads every document of type "rule" that is current (or still a draft) and
+lists its numbered rules. Give a prefix — R, SEC — to see one family.
+
+  --all    include retired and superseded rule documents
+  --json   the full list on stdout
+`;
+
+function collectRules(config, { all = false, prefix = "" } = {}) {
+  return loadDocs(config)
+    .filter((d) => d.hasMeta && d.meta.type === "rule")
+    .filter((d) => all || d.meta.status === "current" || d.meta.status === "draft")
+    .map((d) => ({
+      id: d.id,
+      path: `${config.root}/${d.rel}`,
+      title: d.meta.title,
+      status: d.meta.status,
+      rules: parseRules(d.body)
+        .filter((r) => !prefix || r.id.startsWith(prefix.toUpperCase()))
+        .map(({ id, text, tests, line }) => ({ id, text, tests, line })),
+    }))
+    .filter((d) => !prefix || d.rules.length);
+}
+
+export function run(argv) {
+  const args = parseArgs(argv, { all: "boolean", json: "boolean" });
+  const config = loadConfig();
+  const docs = collectRules(config, { all: args.all, prefix: args._[0] ?? "" });
+  if (args.json) return emitJson(docs);
+  if (!docs.length) return console.log("no rule documents in force");
+  const out = [];
+  for (const d of docs) {
+    out.push(`${d.path} — ${d.title} [${d.status}]`);
+    for (const r of d.rules) {
+      const text = r.text.length > 110 ? r.text.slice(0, 107) + "…" : r.text;
+      out.push(`  ${r.id.padEnd(5)} ${text}${r.tests.length ? `\n        test: ${r.tests.join(", ")}` : ""}`);
+    }
+    out.push("");
+  }
+  console.log(out.join("\n").trimEnd());
+}

package/src/commands/search.mjs

@@ -0,0 +1,88 @@
+import { UsageError, emitJson, parseArgs } from "../cli.mjs";
+import { loadConfig } from "../config.mjs";
+import { loadDocs } from "../docs.mjs";
+import { MARK } from "../render.mjs";
+
+export const summary = "find documents — including the superseded and abandoned ones";
+
+export const help = `honestdocs search — ${summary}
+
+  honestdocs search <words…> [--section <heading>] [--status <s>] [--area <a>]
+                             [--type <t>] [--limit <n>] [--json]
+
+Every word must appear in the document (case-insensitive). Results show the
+matching lines under their section heading.
+
+Search before proposing a design: if the idea was weighed and rejected, the
+reason is in some document's "Alternatives considered".
+
+  --section <heading>   only lines under headings containing this text,
+                        e.g. --section alternatives
+  --limit <n>           at most n documents (default 20)
+`;
+
+/** Split a body into `{ heading, line, text }` for each non-empty line. */
+function linesWithHeadings(body) {
+  const out = [];
+  let heading = "";
+  let inFence = false;
+  body.split(/\r?\n/).forEach((text, i) => {
+    if (/^\s*(```|~~~)/.test(text)) inFence = !inFence;
+    const h = !inFence && /^#{1,6}\s+(.*)$/.exec(text);
+    if (h) heading = h[1].trim();
+    else if (text.trim()) out.push({ heading, line: i + 1, text: text.trim() });
+  });
+  return out;
+}
+
+export function search(config, words, opts = {}) {
+  const terms = words.map((w) => w.toLowerCase()).filter(Boolean);
+  const section = opts.section?.toLowerCase();
+  const hits = [];
+  for (const d of loadDocs(config)) {
+    const m = d.meta;
+    if (opts.status && m.status !== opts.status) continue;
+    if (opts.area && m.area !== opts.area) continue;
+    if (opts.type && m.type !== opts.type) continue;
+    const lines = linesWithHeadings(d.body).filter((l) => !section || l.heading.toLowerCase().includes(section));
+    const title = String(m.title ?? "").toLowerCase();
+    const haystack = (section ? "" : title + "\n") + lines.map((l) => l.text.toLowerCase()).join("\n");
+    if (!terms.every((t) => haystack.includes(t))) continue;
+    const matching = lines.filter((l) => terms.some((t) => l.text.toLowerCase().includes(t)));
+    const score = terms.filter((t) => title.includes(t)).length * 10 + matching.length;
+    hits.push({
+      id: d.id,
+      path: `${config.root}/${d.rel}`,
+      title: m.title ?? "",
+      status: m.status ?? "",
+      type: m.type ?? "",
+      score,
+      matches: matching.map((l) => ({ section: l.heading, line: l.line, text: l.text })),
+    });
+  }
+  hits.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+  return hits;
+}
+
+export function run(argv) {
+  const args = parseArgs(argv, {
+    section: "string", status: "string", area: "string", type: "string", limit: "string", json: "boolean",
+  });
+  if (!args._.length) throw new UsageError("need at least one word to search for");
+  const config = loadConfig();
+  const limit = Number(args.limit ?? 20) || 20;
+  const hits = search(config, args._, args).slice(0, limit);
+  if (args.json) return emitJson(hits);
+  if (!hits.length) return console.log("no document matches");
+  const out = [];
+  for (const h of hits) {
+    const flag = h.status === "superseded" || h.status === "abandoned" || h.status === "retired" ? `  [${h.status.toUpperCase()}]` : "";
+    out.push(`${MARK[h.status] ?? " "} ${h.path} — ${h.title}${flag}`);
+    for (const m of h.matches.slice(0, 3)) {
+      const text = m.text.length > 140 ? m.text.slice(0, 137) + "…" : m.text;
+      out.push(`    ${m.section ? `§ ${m.section}: ` : ""}${text}`);
+    }
+    if (h.matches.length > 3) out.push(`    … ${h.matches.length - 3} more lines`);
+  }
+  console.log(out.join("\n"));
+}

package/src/commands/status.mjs

@@ -0,0 +1,43 @@
+import { UsageError, die, ok, parseArgs } from "../cli.mjs";
+import { lifecycleOf, loadConfig, statusesFor } from "../config.mjs";
+import { findDoc, loadDocs, today, writeDoc } from "../docs.mjs";
+import { report, runIndex } from "./index.mjs";
+
+export const summary = "move a document to another status";
+
+export const help = `honestdocs status — ${summary}
+
+  honestdocs status <id> <status>
+
+Work documents:    draft · planned · in-progress   (finish with \`honestdocs done\`)
+Living documents:  draft · current · retired
+
+"superseded" is never set by hand: write \`supersedes: [<old id>]\` in the newer
+document and \`honestdocs index\` marks the old one.
+`;
+
+export function run(argv) {
+  const args = parseArgs(argv, {});
+  const [id, status] = args._;
+  if (!id || !status) throw new UsageError("need <id> and <status>");
+  const config = loadConfig();
+  const doc = findDoc(loadDocs(config), id);
+  if (!doc) die(`no document with the id "${id}"`);
+  if (!doc.hasMeta) die(`${doc.rel} has no frontmatter`);
+
+  const allowed = statusesFor(config, doc.meta.type);
+  if (!allowed) die(`${doc.rel} has an unknown type "${doc.meta.type}"`);
+  if (status === "superseded") {
+    die("set `supersedes: [" + id + "]` on the document that replaces it, then run `honestdocs index`");
+  }
+  if (status === "done" || status === "abandoned") die(`use \`honestdocs done ${id}${status === "abandoned" ? " --abandoned" : ""}\` — it checks the checklist first`);
+  if (!allowed[status]) {
+    die(`"${status}" is not a status for a ${doc.meta.type} (${lifecycleOf(config, doc.meta.type)}) — expected one of: ${Object.keys(allowed).filter((s) => s !== "superseded").join(", ")}`);
+  }
+
+  doc.meta.status = status;
+  if (status === "retired") doc.meta.completed = today();
+  writeDoc(doc);
+  ok(`${id} → ${status}`);
+  report(config, runIndex(config), false);
+}

package/src/config.mjs

@@ -0,0 +1,146 @@
+// Finding and reading honestdocs.config.json.
+//
+// The config is found by walking up from the working directory, the way git finds .git,
+// so every command works from anywhere inside the project. Everything a project may want
+// to differ on — areas, the docs folder, the trailer word, where the code lives — is here;
+// the lifecycles are not, because the checks only mean something if "done" and "current"
+// mean the same thing in every project that uses this.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { Failure } from "./cli.mjs";
+
+/** The default home: documents and config together, out of the way of the project's own folders. */
+export const DEFAULT_ROOT = ".honestdocs";
+export const CONFIG_IN_ROOT = `${DEFAULT_ROOT}/config.json`;
+/** For a project that keeps its documents somewhere else, the config sits at the top. */
+export const CONFIG_FILE = "honestdocs.config.json";
+
+/**
+ * Two kinds of document, with two lifecycles.
+ *
+ * Work documents describe something that gets done and then is finished: they move
+ * towards `done` or `abandoned`. Living documents — references and rules — are never
+ * finished; they are true now and edited in place, so they are `current` until retired.
+ * Forcing a standing rule through "draft → in-progress → done" leaves it in `draft`
+ * forever while everyone follows it, which is its own kind of lie.
+ */
+export const LIFECYCLES = {
+  work: {
+    draft: "Being written; not ready to build from",
+    planned: "Decided and written down, but no code yet — re-check it against reality before building",
+    "in-progress": "Decided, and the work is under way",
+    done: "Finished and shipped",
+    superseded: "A newer document replaced this one — do not build from it",
+    abandoned: "Deliberately not done; kept so the reasoning survives",
+  },
+  living: {
+    draft: "Being written; not in force yet",
+    current: "In force: true today, kept true in place",
+    retired: "No longer in force; kept so the reasoning survives",
+    superseded: "A newer document replaced this one — follow that one instead",
+  },
+};
+
+const DEFAULT_TYPES = {
+  research: { lifecycle: "work", description: "A question and what was found out, with sources" },
+  design: { lifecycle: "work", description: "How something should work, decided before building it" },
+  plan: { lifecycle: "work", description: "A sequence of work with a checklist that drives progress" },
+  decision: { lifecycle: "work", description: "One choice, its context and its consequences (MADR)" },
+  postmortem: { lifecycle: "work", description: "Something went wrong: timeline, impact, root cause, what changed" },
+  reference: { lifecycle: "living", description: "Background that stays true: a protocol, an API, a guide" },
+  rule: { lifecycle: "living", description: "Numbered rules every change must keep, each naming its test where it can" },
+};
+
+export const DEFAULT_AREAS = {
+  general: "Anything that does not belong to a narrower area yet",
+  rules: "Standing rules every change must keep — read before building, updated in place",
+};
+
+/**
+ * Walk up from `start` to the nearest project: a folder holding `.honestdocs/config.json`
+ * or `honestdocs.config.json`. Returns `{ file, base }` — `base` is the project folder,
+ * which every relative path in the config is read against — or null.
+ */
+export function findConfig(start = process.cwd()) {
+  let dir = resolve(start);
+  for (;;) {
+    const found = [join(dir, CONFIG_IN_ROOT), join(dir, CONFIG_FILE)].filter((f) => existsSync(f));
+    if (found.length > 1) {
+      throw new Failure(`two configs in ${dir}: ${CONFIG_IN_ROOT} and ${CONFIG_FILE} — keep one`);
+    }
+    if (found.length) return { file: found[0], base: dir };
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Load and validate the config. Returns a normalised object with absolute paths, so no
+ * command ever has to think about where it was started from.
+ */
+export function loadConfig(start = process.cwd()) {
+  const found = findConfig(start);
+  if (!found) throw new Failure(`no ${CONFIG_IN_ROOT} here or above — run \`honestdocs init\` first`);
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(found.file, "utf8"));
+  } catch (e) {
+    throw new Failure(`${found.file} is not valid JSON: ${e.message}`);
+  }
+  return normalise(raw, found.base, found.file);
+}
+
+function normalise(raw, base, file = join(base, CONFIG_FILE)) {
+  const problems = [];
+  const root = typeof raw.root === "string" && raw.root ? raw.root : DEFAULT_ROOT;
+
+  const areas = raw.areas && typeof raw.areas === "object" ? raw.areas : DEFAULT_AREAS;
+  if (!Object.keys(areas).length) problems.push("`areas` is empty — a document needs somewhere to live");
+  for (const a of Object.keys(areas)) {
+    if (!/^[a-z0-9_][a-z0-9_-]*$/.test(a)) problems.push(`area "${a}" must be lower-case letters, digits, - or _`);
+  }
+
+  const types = { ...DEFAULT_TYPES };
+  for (const [name, def] of Object.entries(raw.types ?? {})) {
+    if (def === false || def === null) {
+      delete types[name];
+      continue;
+    }
+    const lifecycle = def?.lifecycle ?? types[name]?.lifecycle;
+    if (!LIFECYCLES[lifecycle]) {
+      problems.push(`type "${name}" needs a lifecycle: ${Object.keys(LIFECYCLES).join(" or ")}`);
+      continue;
+    }
+    types[name] = { lifecycle, description: def?.description ?? types[name]?.description ?? "" };
+  }
+
+  const trailer = typeof raw.trailer === "string" && raw.trailer ? raw.trailer : "Doc";
+  if (!/^[A-Za-z][A-Za-z0-9-]*$/.test(trailer)) problems.push(`trailer "${trailer}" must be a git trailer key such as Doc`);
+
+  const codeRepos = (Array.isArray(raw.codeRepos) && raw.codeRepos.length ? raw.codeRepos : ["."])
+    .map((p) => (isAbsolute(p) ? p : resolve(base, p)));
+
+  if (problems.length) throw new Failure(`${file}:\n  ${problems.join("\n  ")}`);
+
+  return {
+    file,
+    base,
+    root,
+    docsDir: resolve(base, root),
+    title: typeof raw.title === "string" && raw.title ? raw.title : "Development documents",
+    areas,
+    types,
+    trailer,
+    codeRepos,
+    templatesDir: raw.templates ? resolve(base, raw.templates) : null,
+    recent: Number.isInteger(raw.recent) && raw.recent > 0 ? raw.recent : 25,
+    raw,
+  };
+}
+
+/** The statuses a document of this type may have. */
+export const statusesFor = (config, type) => LIFECYCLES[config.types[type]?.lifecycle] ?? null;
+
+export const lifecycleOf = (config, type) => config.types[type]?.lifecycle ?? null;