@anja.codes/vitakit 0.1.0 → 0.2.0

package/dist/chunks/emit.mjs

@@ -0,0 +1,200 @@
+import { mkdir, writeFile, readdir, rm, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { Eta } from 'eta';
+import { r as resolveAsset } from '../shared/vitakit.DQ6PmGoL.mjs';
+import { b as escapeUrl, a as escapeTex, e as escapeRichTex } from '../shared/vitakit.DcQOdM4I.mjs';
+import { f as formatDateRange, e as entrySecondaryParts, b as entryTitleField } from '../shared/vitakit.CfB3hMHl.mjs';
+import { f as fail } from '../shared/vitakit.DbSeENVS.mjs';
+import { i as isSitePath } from '../shared/vitakit.D10HyDhF.mjs';
+import { selectEntries } from './documents.mjs';
+import 'node:url';
+import 'yaml';
+import 'zod';
+import '../shared/vitakit.TSMTC5Jl.mjs';
+import '../shared/vitakit.D-DdJaDZ.mjs';
+
+const SITE_PATH_HELP = "is a path on the website, and the PDF can only link it with the address the site is published at: add it to content/profile.yml, e.g. `url: https://jane.example.org/`";
+class Fragment {
+  constructor(value) {
+    this.value = value;
+  }
+  toString() {
+    return this.value;
+  }
+}
+const fragment = (value) => value ? new Fragment(value) : "";
+function isRichText(value) {
+  return typeof value === "object" && value !== null && "text" in value && typeof value.text === "string" && "html" in value && typeof value.html === "string";
+}
+function isTemplate(value) {
+  return Array.isArray(value) && "raw" in value && Array.isArray(value.raw);
+}
+function createTemplateHelpers(where, source) {
+  const text = (value) => {
+    if (value === void 0 || value === null || value === "") return "";
+    if (value instanceof Fragment) return value;
+    if (typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
+      return fragment(escapeTex(String(value)));
+    }
+    if (isRichText(value)) {
+      try {
+        return fragment(escapeRichTex(value.text));
+      } catch (error) {
+        return fail(where, error instanceof Error ? error.message : String(error));
+      }
+    }
+    return fail(where, "text expects text or a number; use date(...) or linked(...) for structured values");
+  };
+  const url = (value) => {
+    if (value === void 0 || value === null || value === "") return "";
+    if (typeof value !== "string") return fail(where, "url expects a URL string");
+    if (isSitePath(value)) fail(source, `${value} ${SITE_PATH_HELP}`);
+    return fragment(escapeUrl(value));
+  };
+  const linked = (value, target) => {
+    let label = value;
+    if (typeof value === "object" && value !== null && !(value instanceof Fragment) && !isRichText(value)) {
+      if ("label" in value && typeof value.label === "string") label = value.label;
+      else return fail(where, "linked expects text or { label, url? }; use `linked` in the section schema");
+      if (target === void 0 && "url" in value) target = value.url;
+    }
+    const body = text(label);
+    if (!body) return "";
+    const href = url(target);
+    return href ? fragment(`\\href{${href}}{${body}}`) : body;
+  };
+  const date = (value) => {
+    if (value === void 0 || value === null) return "";
+    if (typeof value !== "object" || !("from" in value) || typeof value.from !== "object" || value.from === null || !("year" in value.from) || typeof value.from.year !== "number" || !("point" in value) || typeof value.point !== "boolean" || !("ongoing" in value) || typeof value.ongoing !== "boolean") {
+      return fail(where, "date expects a normalized date; use dateRange in the collection schema");
+    }
+    return fragment(escapeTex(formatDateRange(value)));
+  };
+  const join = (values, separator = ", ") => {
+    if (!Array.isArray(values)) return fail(where, "join expects an array of values");
+    const parts = values.map((value) => String(text(value))).filter((value) => value !== "");
+    return fragment(parts.join(String(text(separator))));
+  };
+  const optional = (strings, ...values) => {
+    if (!isTemplate(strings) || strings.raw.length !== values.length + 1) {
+      return fail(where, "optional must be used as a tagged template: optional`...${value}...`");
+    }
+    if (values.some((value) => value === void 0 || value === null || value === "")) return "";
+    const parts = values.map(text);
+    if (parts.some((value) => !value)) return "";
+    return fragment(strings.raw.map((literal, index) => literal + (parts[index] ?? "")).join(""));
+  };
+  function note(value, ...values) {
+    const body = isTemplate(value) ? optional(value, ...values) : text(value);
+    return body ? fragment(`\\vitanote{${body}}`) : "";
+  }
+  const entry = (layout) => {
+    if (typeof layout !== "object" || layout === null || !Object.hasOwn(layout, "title") || Object.keys(layout).some((key) => !["date", "title", "context"].includes(key))) {
+      return fail(where, "vita.entry expects { title, date?, context? }");
+    }
+    return fragment(`\\vitaentry{${text(layout.date)}}{${text(layout.title)}}{${text(layout.context)}}`);
+  };
+  return { text, date, linked, url, join, optional, vita: { entry, note } };
+}
+
+const bundledTexDir = resolveAsset("tex");
+const eta = new Eta({ autoEscape: false, autoTrim: [false, false] });
+function tidy(body) {
+  return body.replace(/[ \t]+$/gm, "").replace(/\n{2,}/g, "\n").trim();
+}
+function genericHelpers(h) {
+  return {
+    title(entry) {
+      const field = entryTitleField(entry);
+      return h.text(field ? entry[field] : void 0);
+    },
+    context(entry) {
+      return h.join(entrySecondaryParts(entry, entryTitleField(entry)).map((part) => part.kind === "linked" ? h.linked(part.linked) : part.text));
+    }
+  };
+}
+function bibgroup(group, where) {
+  const unsafe = /[\s%#\\{},~]/;
+  const bad = [group.id, ...group.entries.map((entry) => entry.key)].find((value) => !value || unsafe.test(value));
+  if (bad !== void 0) {
+    fail(where, `"${bad}" cannot be used as a citation key or group id in LaTeX; use letters, digits and - _ : . / +`);
+  }
+  return fragment(`\\vitabibgroup{${group.id}}{${group.entries.map((entry) => entry.key).join(",")}}`);
+}
+async function resolveTemplate(id, userDir, { exclude } = {}) {
+  const candidates = [
+    { path: join(userDir, `${id}.eta`), origin: "local", generic: false },
+    { path: join(bundledTexDir, "templates", `${id}.eta`), origin: "bundled", generic: false },
+    { path: join(userDir, "_generic.eta"), origin: "local", generic: true },
+    { path: join(bundledTexDir, "templates", "_generic.eta"), origin: "bundled", generic: true }
+  ];
+  for (const candidate of candidates) {
+    if (candidate.path === exclude) continue;
+    if (existsSync(candidate.path)) return { ...candidate, source: await readFile(candidate.path, "utf8") };
+  }
+  throw new Error(`vitakit: no template for section ${id}`);
+}
+async function assertTemplatesAreUsed(templateDir, ids) {
+  const files = await readdir(templateDir).catch(() => []);
+  const known = /* @__PURE__ */ new Set([...ids, "publications", "_generic"]);
+  for (const file of files.filter((name) => name.endsWith(".eta")).sort()) {
+    const id = file.slice(0, -".eta".length);
+    if (known.has(id)) continue;
+    const suggestion = ids.find((candidate) => candidate.startsWith(id) || id.startsWith(candidate));
+    fail(
+      `cv-tex/templates/${file}`,
+      `no section is called "${id}", so this template is never used${suggestion ? `; did you mean ${suggestion}.eta?` : ""}
+  sections: ${ids.join(", ") || "(none)"}`
+    );
+  }
+}
+async function renderSection(id, entries, options, templateDir) {
+  const selected = selectEntries(entries, options, id);
+  const { path: templatePath, source } = await resolveTemplate(id, templateDir);
+  const h = createTemplateHelpers(templatePath, `content/${id}.yml`);
+  try {
+    return tidy(eta.renderString(source, { entries: selected, ...h, generic: genericHelpers(h) }));
+  } catch (error) {
+    throw new Error(`template ${id}.eta: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+}
+async function renderPublications(publications, options, templateDir, siteUrl) {
+  const groups = options.publications.groups ? options.publications.groups.map((id) => publications.find((group) => group.id === id)).filter((group) => group !== void 0) : publications;
+  if (!siteUrl) {
+    const local = groups.flatMap((group) => group.entries).find((entry) => entry.titleUrl && isSitePath(entry.titleUrl));
+    if (local) fail("content/publications.bib", `${local.key}: url ${local.titleUrl} ${SITE_PATH_HELP}`);
+  }
+  const { path: templatePath, source } = await resolveTemplate("publications", templateDir);
+  return tidy(eta.renderString(source, {
+    groups,
+    ...createTemplateHelpers(templatePath, "content/publications.bib"),
+    bib: { group: (group) => bibgroup(group, templatePath) }
+  }));
+}
+async function emitDocument(emit) {
+  await mkdir(emit.outDir, { recursive: true });
+  await assertTemplatesAreUsed(emit.templateDir, Object.keys(emit.sections));
+  const written = [];
+  for (const [id, entries] of Object.entries(emit.sections)) {
+    const body2 = await renderSection(id, entries, emit.options, emit.templateDir);
+    const file2 = join(emit.outDir, `${id}.tex`);
+    await writeFile(file2, `% Generated by vitakit. Do not edit; edit content/${id}.yml instead.
+${body2.trim()}
+`);
+    written.push(file2);
+  }
+  const body = await renderPublications(emit.publications, emit.options, emit.templateDir, emit.siteUrl);
+  const file = join(emit.outDir, "publications.tex");
+  await writeFile(file, `% Generated by vitakit. Do not edit; edit content/publications.bib instead.
+${body.trim()}
+`);
+  written.push(file);
+  const current = /* @__PURE__ */ new Set(["profile.tex", ...written.map((file2) => basename(file2))]);
+  for (const file2 of await readdir(emit.outDir)) {
+    if (file2.endsWith(".tex") && !current.has(file2)) await rm(join(emit.outDir, file2));
+  }
+  return written;
+}
+
+export { SITE_PATH_HELP, assertTemplatesAreUsed, bundledTexDir, emitDocument, renderPublications, renderSection, resolveTemplate };

package/dist/chunks/eta.mjs

@@ -0,0 +1,16 @@
+function addToEntryLoop(source, lines) {
+  const all = source.split("\n");
+  let close = -1;
+  for (let index = all.length - 1; index >= 0; index--) {
+    if (/^\s*<%\s*}\s*%>\s*$/.test(all[index])) {
+      close = index;
+      break;
+    }
+  }
+  if (close === -1) return { ok: false, reason: "it has no `<% } %>` line ending its loop over the entries" };
+  const fresh = lines.filter((line) => !source.includes(line));
+  if (!fresh.length) return { ok: true, value: source };
+  return { ok: true, value: [...all.slice(0, close), ...fresh, ...all.slice(close)].join("\n") };
+}
+
+export { addToEntryLoop };

package/dist/chunks/fields.mjs

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+import { v as visibility, t as text, a as richText, d as dateRange, u as url, b as absoluteUrl, l as linked, r as requiredLink } from '../shared/vitakit.BerUaxtF.mjs';
+import '../shared/vitakit.DbSeENVS.mjs';
+import 'node:url';
+import '../shared/vitakit.D10HyDhF.mjs';
+
+const FIELD_TYPE_NAMES = {
+  "text": "text",
+  "formatted-text": "formatted text",
+  "number": "number",
+  "yes-no": "yes/no",
+  "date": "date",
+  "web-address": "web address",
+  "link": "link",
+  "choice": "one of a fixed list",
+  "group": "group of fields",
+  "custom": "custom"
+};
+const PRIMITIVES = /* @__PURE__ */ new Map([
+  [text, "text"],
+  [richText, "formatted-text"],
+  [dateRange, "date"],
+  [url, "web-address"],
+  [absoluteUrl, "web-address"],
+  [linked, "link"],
+  [requiredLink, "link"]
+]);
+function describeField(path, schema) {
+  let current = schema;
+  let optional = false;
+  let several = false;
+  let fallback;
+  let hasDefault = false;
+  for (; ; ) {
+    if (PRIMITIVES.has(current)) break;
+    if (current instanceof z.ZodOptional || current instanceof z.ZodNullable) {
+      optional = true;
+      current = current.unwrap();
+    } else if (current instanceof z.ZodDefault) {
+      optional = true;
+      hasDefault = true;
+      fallback = current.def.defaultValue;
+      current = current.unwrap();
+    } else if (current instanceof z.ZodArray && !several) {
+      several = true;
+      current = current.element;
+    } else {
+      break;
+    }
+  }
+  const description = { path, type: "custom", optional, several };
+  if (hasDefault) description.default = fallback;
+  const primitive = PRIMITIVES.get(current);
+  if (primitive) description.type = primitive;
+  else if (current instanceof z.ZodString) description.type = "text";
+  else if (current instanceof z.ZodNumber) description.type = "number";
+  else if (current instanceof z.ZodBoolean) description.type = "yes-no";
+  else if (current instanceof z.ZodEnum) {
+    description.type = "choice";
+    description.choices = current.options.map(String);
+  } else if (current instanceof z.ZodObject) {
+    description.type = "group";
+    description.fields = Object.entries(current.shape).map(([name, field]) => describeField(`${path}.${name}`, field));
+  }
+  return description;
+}
+function describeSection(schema) {
+  if (!(schema instanceof z.ZodArray) || !(schema.element instanceof z.ZodObject)) return void 0;
+  return Object.entries(schema.element.shape).filter(([name, field]) => !(name === "visibility" && field === visibility)).map(([name, field]) => describeField(name, field));
+}
+function fieldSummary(field) {
+  const type = field.type === "choice" && field.choices ? `one of ${field.choices.join(", ")}` : FIELD_TYPE_NAMES[field.type];
+  return [
+    field.several ? `list of ${type}` : type,
+    field.optional ? field.default !== void 0 ? `default ${JSON.stringify(field.default)}` : "optional" : "required"
+  ].join(", ");
+}
+
+export { FIELD_TYPE_NAMES, describeField, describeSection, fieldSummary };

package/dist/chunks/inventory.mjs

@@ -0,0 +1,199 @@
+import { readFile, stat, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import matter from 'gray-matter';
+import { parse } from 'yaml';
+import { l as loadContent } from '../shared/vitakit.By5VWQ1n.mjs';
+import { describeSection } from './fields.mjs';
+import { findSectionFiles, resolveSectionSchema } from './sections.mjs';
+import { schemas } from './schemas.mjs';
+import { findDocuments, documentSectionProblems } from './documents.mjs';
+import { p as pageRoute, d as documentDirective, f as findPdfPlacements, a as findWebPlacements } from '../shared/vitakit.Do5HC_MD.mjs';
+import { m as messageOf, w as whereOf } from '../shared/vitakit.DbSeENVS.mjs';
+import 'unified';
+import 'remark-parse';
+import 'remark-gfm';
+import 'remark-math';
+import 'remark-rehype';
+import 'rehype-katex';
+import 'rehype-raw';
+import 'rehype-stringify';
+import 'unist-util-visit';
+import '../shared/vitakit.D10HyDhF.mjs';
+import '../shared/vitakit.DQ6PmGoL.mjs';
+import 'node:url';
+import '@behackl/citation-js-extras';
+import 'rehype-parse';
+import 'rehype-sanitize';
+import 'zod';
+import '../shared/vitakit.BerUaxtF.mjs';
+import '../shared/vitakit.TSMTC5Jl.mjs';
+import '../shared/vitakit.D-DdJaDZ.mjs';
+
+const posix = (path) => path.split(sep).join("/");
+async function files(dir, filter) {
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  const found = [];
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) found.push(...await files(path, filter));
+    else if (filter(entry.name)) found.push(path);
+  }
+  return found.sort();
+}
+async function newest(paths) {
+  let latest = 0;
+  for (const path of paths) {
+    const info = await stat(path).catch(() => void 0);
+    if (info && info.mtimeMs > latest) latest = info.mtimeMs;
+  }
+  return latest;
+}
+function sharedSchema(source) {
+  return /export\s*\{\s*default\s*\}\s*from\s*['"]\.\/([a-z0-9-]+)(?:\.ts)?['"]/.exec(source)?.[1] ?? /^export\s+default\s+schemas\.([a-z]\w*)\s*;?\s*$/m.exec(source)?.[1];
+}
+function belongsTo(problem, file) {
+  return problem.where === file.where || problem.where === `schemas/${file.id}.ts`;
+}
+async function inventory(rootDir, options = {}) {
+  const content = await loadContent(rootDir, { strict: false, maxVisibility: "private" });
+  const problems = [...content.issues];
+  const { files: sectionFiles } = await findSectionFiles(rootDir).catch(() => ({ files: [] }));
+  const sections = [];
+  const schemasForDocuments = [];
+  for (const file of sectionFiles) {
+    const local = join(rootDir, "schemas", `${file.id}.ts`);
+    const builtIn = Object.hasOwn(schemas, file.id);
+    const section = {
+      id: file.id,
+      where: file.where,
+      schema: { origin: existsSync(local) ? "local" : builtIn ? "built-in" : "none" },
+      problems: problems.filter((problem) => belongsTo(problem, file))
+    };
+    if (section.schema.origin === "local") {
+      section.schema.file = `schemas/${file.id}.ts`;
+      const source = await readFile(local, "utf8");
+      const shared = sharedSchema(source);
+      if (shared) section.schema.sharedWith = shared;
+      if (builtIn && /\bextendSection\s*\(\s*schemas\.[\w$]+/.test(source)) section.schema.extendsBuiltIn = true;
+    }
+    try {
+      const raw = parse(await readFile(file.file, "utf8"));
+      if (Array.isArray(raw)) section.entries = raw.length;
+      else if (raw === null) section.entries = 0;
+    } catch {
+    }
+    if (section.schema.origin !== "none") {
+      try {
+        const source = await resolveSectionSchema(rootDir, file);
+        schemasForDocuments.push({ id: file.id, schema: source.schema });
+        const fields = describeSection(source.schema);
+        if (fields) section.fields = fields;
+      } catch {
+      }
+    }
+    if (!section.problems.length) {
+      const counts = { public: 0, cv: 0, private: 0 };
+      for (const entry of content.sections[file.id] ?? []) counts[entry.visibility]++;
+      section.counts = counts;
+    }
+    sections.push(section);
+  }
+  const menu = new Set(content.profile.nav.map((item) => item.url));
+  const pages = /* @__PURE__ */ new Map();
+  const page = (route) => {
+    if (!pages.has(route)) pages.set(route, { route, inMenu: menu.has(route) });
+    return pages.get(route);
+  };
+  const pagesDir = join(rootDir, "content", "pages");
+  for (const path of await files(pagesDir, (name) => name.endsWith(".md"))) {
+    const slug = relative(pagesDir, path).replace(/\.md$/, "");
+    let route = slug === "index" ? "/" : `/${slug}/`;
+    let title;
+    try {
+      const { data } = matter(await readFile(path, "utf8"));
+      if (typeof data.route === "string") route = data.route;
+      if (typeof data.title === "string") title = data.title;
+    } catch {
+    }
+    Object.assign(page(route), { markdown: posix(relative(rootDir, path)), ...title ? { title } : {} });
+  }
+  let catchAll;
+  const vuePagesDir = join(rootDir, "app", "pages");
+  for (const path of await files(vuePagesDir, (name) => name.endsWith(".vue"))) {
+    const below = relative(vuePagesDir, path);
+    if (below.includes("[")) {
+      if (/\[\.\.\.[^\]]+\]\.vue$/.test(below) && !below.includes(sep)) catchAll = posix(relative(rootDir, path));
+      continue;
+    }
+    page(pageRoute(below)).vue = posix(relative(rootDir, path));
+  }
+  const bib = join(rootDir, "content", "publications.bib");
+  const publications = existsSync(bib) ? {
+    file: "content/publications.bib",
+    entries: content.publications.reduce((sum, group) => sum + group.entries.length, 0),
+    groups: content.publications.length
+  } : void 0;
+  const cvDir = join(rootDir, "cv-tex");
+  const { documents: found, problems: documentProblems } = await findDocuments(cvDir);
+  problems.push(...documentProblems);
+  const known = /* @__PURE__ */ new Set([...sections.map((section) => section.id), "publications", "profile"]);
+  const groupIds = new Set(content.publications.map((group) => group.id));
+  const documents = [];
+  for (const document of found) {
+    const tex = `cv-tex/${document.name}.tex`;
+    const source = await readFile(document.texFile, "utf8");
+    const pdfPath = join(cvDir, `${document.name}.pdf`);
+    const pdf = await stat(pdfPath).catch(() => void 0);
+    const own = documentSectionProblems(document, schemasForDocuments);
+    const directive = documentDirective(source);
+    if (!directive) own.push({ where: tex, message: `has no \\vitadocument{${document.name}}` });
+    else if (directive.name !== document.name) {
+      own.push({ where: `${tex}:${directive.line}`, message: `\\vitadocument{${directive.name}} does not match the file name; expected \\vitadocument{${document.name}}` });
+    }
+    const placements = findPdfPlacements(document.name, tex, source);
+    for (const placement of placements) {
+      if (!known.has(placement.section)) {
+        own.push({ where: `${tex}:${placement.line}`, message: `no section called "${placement.section}"` });
+      }
+    }
+    for (const group of document.options.publications.groups ?? []) {
+      if (!groupIds.has(group) && publications) {
+        own.push({ where: `cv-tex/${document.name}.yml`, message: `publications.groups: no publication group "${group}"` });
+      }
+    }
+    problems.push(...own);
+    documents.push({
+      name: document.name,
+      tex,
+      ...existsSync(join(cvDir, `${document.name}.yml`)) ? { yml: `cv-tex/${document.name}.yml` } : {},
+      options: document.options,
+      placements,
+      ...pdf ? { pdf: { file: `cv-tex/${document.name}.pdf`, mtimeMs: pdf.mtimeMs } } : {},
+      problems: [...documentProblems.filter((problem) => problem.where === `cv-tex/${document.name}.yml`), ...own]
+    });
+  }
+  const sourcesMtimeMs = await newest([
+    ...await files(join(rootDir, "content"), () => true),
+    ...await files(join(rootDir, "schemas"), () => true),
+    ...await files(cvDir, (name) => /\.(tex|yml|yaml|eta|cls)$/.test(name)).then((list) => list.filter((path) => !relative(cvDir, path).startsWith("generated")))
+  ]);
+  const web = options.web === false ? { placements: [], dynamic: [], components: /* @__PURE__ */ new Map() } : await findWebPlacements(rootDir).catch((error) => {
+    problems.push({ where: whereOf(error, "app/"), message: messageOf(error) });
+    return { placements: [], dynamic: [], components: /* @__PURE__ */ new Map() };
+  });
+  return {
+    root: rootDir,
+    sections,
+    pages: [...pages.values()].sort((a, b) => a.route.localeCompare(b.route)),
+    ...catchAll ? { catchAll } : {},
+    ...publications ? { publications } : {},
+    documents,
+    web,
+    sourcesMtimeMs,
+    problems,
+    content
+  };
+}
+
+export { inventory };

package/dist/chunks/plan.mjs

@@ -0,0 +1,144 @@
+import { existsSync } from 'node:fs';
+import { readFile, mkdir, writeFile, rename } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { C as CommandError } from '../shared/vitakit.CoWX2Z4R.mjs';
+import '../shared/vitakit.DQ6PmGoL.mjs';
+import 'node:url';
+import 'node:process';
+import 'node:util';
+import 'node:readline/promises';
+
+const writes = (plan) => plan.items.filter((item) => item.kind === "create" || item.kind === "replace" || item.kind === "edit");
+function diff(before, after, context = 2) {
+  const a = before.split("\n");
+  const b = after.split("\n");
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) start++;
+  let endA = a.length;
+  let endB = b.length;
+  while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+    endA--;
+    endB--;
+  }
+  const from = Math.max(0, start - context);
+  return [
+    ...a.slice(from, start).map((line) => `    ${line}`),
+    ...a.slice(start, endA).map((line) => `  - ${line}`),
+    ...b.slice(start, endB).map((line) => `  + ${line}`),
+    ...a.slice(endA, Math.min(a.length, endA + context)).map((line) => `    ${line}`)
+  ];
+}
+function printPlan(io, style, plan) {
+  const lines = [];
+  for (const item of plan.items) {
+    if (item.kind === "create") {
+      lines.push(`${style.green("+")} ${item.path}   ${style.dim(item.reason)}`);
+      if (item.show) lines.push(...item.content.trimEnd().split("\n").map((line) => style.dim(`    ${line}`)));
+    } else if (item.kind === "replace") {
+      lines.push(`${style.yellow("!")} ${item.path}   ${style.dim(item.reason)}`);
+      if (item.show) lines.push(...item.content.trimEnd().split("\n").map((line) => style.dim(`    ${line}`)));
+    } else if (item.kind === "keep") lines.push(`${style.dim("=")} ${item.path}   ${style.dim(item.reason)}`);
+    else if (item.kind === "edit") {
+      lines.push(`${style.yellow("~")} ${item.path}   ${style.dim(item.reason)}`);
+      lines.push(...diff(item.before, item.after).map((line) => line.startsWith("  +") ? style.green(line) : line.startsWith("  -") ? style.red(line) : style.dim(line)));
+    } else {
+      lines.push(`${style.yellow("?")} ${item.path}   ${item.reason}`);
+      lines.push(...item.snippet.split("\n").map((line) => `    ${line}`));
+    }
+  }
+  io.out(`${lines.join("\n")}
+`);
+}
+async function confirmPlan(io, plan, yes) {
+  if (!writes(plan).length || yes) return true;
+  if (!io.interactive) {
+    throw new CommandError("nothing written: confirm with --yes, or only preview with --dry-run");
+  }
+  const answer = (await io.ask("\nWrite these changes? [Y/n] ")).trim().toLowerCase();
+  if (answer === "" || answer === "y" || answer === "yes") return true;
+  io.out("Cancelled; nothing was written.\n");
+  return false;
+}
+function backupPath(path) {
+  let candidate = `${path}.backup`;
+  for (let index = 2; existsSync(candidate); index++) candidate = `${path}.backup-${index}`;
+  return candidate;
+}
+async function applyPlan(root, plan) {
+  for (const item of writes(plan)) {
+    const path = join(root, item.path);
+    if (item.kind === "create" && existsSync(path)) throw new CommandError(`${item.path} exists now; nothing was written`);
+    if (item.kind !== "create" && !existsSync(path)) throw new CommandError(`${item.path} is gone now; nothing was written`);
+  }
+  const written = [];
+  try {
+    for (const item of writes(plan)) {
+      const path = join(root, item.path);
+      await mkdir(dirname(path), { recursive: true });
+      if (item.kind === "create") await writeFile(path, item.content, { flag: "wx" });
+      else if (item.kind === "replace") {
+        await rename(path, backupPath(path));
+        await writeFile(path, item.content);
+      } else await writeFile(path, item.after);
+      written.push(item.path);
+    }
+  } catch (error) {
+    throw new CommandError(`${error instanceof Error ? error.message : String(error)}${written.length ? `
+  Already written: ${written.join(", ")}` : "\n  Nothing was written."}`);
+  }
+  return written;
+}
+class Workspace {
+  constructor(root) {
+    this.root = root;
+  }
+  items = [];
+  find(path) {
+    return this.items.find((item) => item.path === path && item.kind !== "paste" && item.kind !== "keep");
+  }
+  /** The file as it will be: planned contents first, the disk otherwise. */
+  async read(path) {
+    const planned = this.find(path);
+    if (planned?.kind === "create" || planned?.kind === "replace") return planned.content;
+    if (planned?.kind === "edit") return planned.after;
+    return readFile(join(this.root, path), "utf8").catch(() => void 0);
+  }
+  exists(path) {
+    return Boolean(this.find(path)) || existsSync(join(this.root, path));
+  }
+  /** A new file; `show` prints its contents in the plan, for short files worth reading. */
+  create(path, content, reason, { show = false } = {}) {
+    if (this.exists(path)) throw new CommandError(`${path} exists already; nothing was written`);
+    this.items.push({ kind: "create", path, content, reason, ...show ? { show } : {} });
+  }
+  /** Replace an existing file; the old one is kept as a backup. */
+  replace(path, content, reason, { show = false } = {}) {
+    this.items.push({ kind: "replace", path, content, reason, ...show ? { show } : {} });
+  }
+  /** Change a file; for a file this plan creates, the change becomes part of it. */
+  async edit(path, after, reason) {
+    const planned = this.find(path);
+    if (planned?.kind === "create" || planned?.kind === "replace") {
+      planned.content = after;
+      return;
+    }
+    if (planned?.kind === "edit") {
+      planned.after = after;
+      planned.reason = `${planned.reason}; ${reason}`;
+      return;
+    }
+    const before = await readFile(join(this.root, path), "utf8");
+    this.items.push({ kind: "edit", path, before, after, reason });
+  }
+  keep(path, reason) {
+    this.items.push({ kind: "keep", path, reason });
+  }
+  paste(path, snippet, reason) {
+    this.items.push({ kind: "paste", path, snippet, reason });
+  }
+  plan() {
+    return { items: [...this.items] };
+  }
+}
+
+export { Workspace, applyPlan, backupPath, confirmPlan, diff, printPlan };

package/dist/chunks/prompt.mjs

@@ -0,0 +1,33 @@
+async function choose(io, question, choices, defaultIndex = 0) {
+  io.out(`
+${question}
+`);
+  choices.forEach((choice, index) => io.out(`  ${index + 1}  ${choice.label}${index === defaultIndex ? "   (Enter)" : ""}
+`));
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const answer = (await io.ask("> ")).trim();
+    if (answer === "") return choices[defaultIndex].value;
+    const number = Number(answer);
+    if (Number.isInteger(number) && number >= 1 && number <= choices.length) return choices[number - 1].value;
+    const named = choices.find((choice) => choice.label.toLowerCase() === answer.toLowerCase());
+    if (named) return named.value;
+    io.out(`  A number from 1 to ${choices.length}, please.
+`);
+  }
+  return choices[defaultIndex].value;
+}
+async function confirm(io, question, yes = true) {
+  const answer = (await io.ask(`${question} ${yes ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase();
+  if (answer === "") return yes;
+  return answer === "y" || answer === "yes";
+}
+async function input(io, question, fallback) {
+  const answer = (await io.ask(`${question}${fallback ? ` [${fallback}]` : ""}: `)).trim();
+  return answer || fallback || "";
+}
+function headingFor(id) {
+  const words = id.split("-").join(" ");
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+export { choose, confirm, headingFor, input };