@wirecat/cli-template 0.0.0-stage → 0.1.1

package/kit/dist/new.js

@@ -0,0 +1,256 @@
+import { execFile } from "node:child_process";
+import { chmod, mkdir, readdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { promisify } from "node:util";
+import { ask, choiceList, INTERVIEW, labelOf, NAME_QUESTIONS, parseAnswer } from "./interview.js";
+import { MANIFEST, sha256 } from "./manifest.js";
+import { PACKED_AS, renderTemplate } from "./source.js";
+const run = promisify(execFile);
+const REFERENCES = {
+    messenger: ["whatsapp-cli", "tg-cli", "max-cli"],
+    files: ["drive-cli"],
+    meetings: ["zoom-cli"],
+    notes: ["cli-memo"],
+};
+const STEMMED = ["en", "ru", "es"];
+// Parakeet v3's languages, from cli-core's speech model list.
+const PARAKEET = "bg cs da de el en es et fi fr hr hu it lt lv mt nl pl pt ro ru sk sl sv uk".split(" ");
+const baseLang = (code) => code.split("-")[0] ?? code;
+export const speechModels = (languages) => {
+    const bases = languages.map(baseLang);
+    if (bases.length > 0 && bases.every((lang) => lang === "ru"))
+        return ["gigaam-v3", "gigaam-v3-ctc", "parakeet-v3"];
+    if (bases.length > 0 && bases.every((lang) => PARAKEET.includes(lang)))
+        return ["parakeet-v3"];
+    return undefined;
+};
+export const languageWarnings = (languages) => languages.flatMap((lang) => [
+    ...(STEMMED.includes(baseLang(lang))
+        ? []
+        : [`${lang}: cli-core has no search stemmer for it; search matches whole words only`]),
+    ...(PARAKEET.includes(baseLang(lang)) ? [] : [`${lang}: no speech model in cli-core hears it`]),
+]);
+const NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+const NAME_QUESTION = {
+    key: "name",
+    flag: "name",
+    text: "The folder (and repository) name, e.g. cal-cli",
+    check: (value) => (NAME_PATTERN.test(value) ? undefined : "lowercase letters, digits, dots and dashes"),
+};
+const collect = async (args, io) => {
+    const questions = [NAME_QUESTION, ...NAME_QUESTIONS, ...INTERVIEW];
+    const given = { ...args.flags, name: args.name };
+    const answers = {};
+    const missing = [];
+    for (const question of questions) {
+        const raw = given[question.flag];
+        if (raw === undefined) {
+            missing.push(question);
+            continue;
+        }
+        const { value, error } = parseAnswer(question, raw);
+        if (error)
+            throw new Error(question === NAME_QUESTION ? `<name>: ${error.replace(/^--name: /, "")}` : error);
+        answers[question.key] = value ?? [];
+    }
+    if (missing.length > 0 && !io.interactive) {
+        const lines = missing.map((question) => question === NAME_QUESTION ? "  <name>: the folder to create" : `  --${question.flag}: ${choiceList(question)}`);
+        throw new Error(`no terminal to ask in, and these answers are missing:\n${lines.join("\n")}`);
+    }
+    if (missing.length > 0) {
+        const rl = createInterface({ input: io.input, output: io.output, terminal: false });
+        try {
+            for (const question of missing)
+                answers[question.key] = await ask(rl, io.output, question);
+        }
+        finally {
+            rl.close();
+        }
+    }
+    const one = (key) => answers[key]?.[0] ?? "";
+    return {
+        names: { name: one("name"), command: one("command"), package: one("package"), owner: one("owner") },
+        answers,
+    };
+};
+const isEmptyOrMissing = async (dir) => readdir(dir).then((entries) => entries.length === 0, () => true);
+const referenceLine = (category) => {
+    const refs = REFERENCES[category];
+    if (!refs) {
+        return "No reference CLI for this category yet: pick the nearest one with the owner from the Reference CLIs page.";
+    }
+    const [first, ...rest] = refs;
+    const link = (repo) => `[${repo}](https://github.com/WireCatLabs/${repo})`;
+    return `Learn from ${link(first ?? "")}${rest.length ? `, then ${rest.map(link).join(" and ")}` : ""}.`;
+};
+const START = "<!-- cli-template:reference-cli:start -->";
+const END = "<!-- cli-template:reference-cli:end -->";
+export const withReference = (agents, category) => {
+    const block = `${START}\n## Reference CLI\n\n${referenceLine(category)}\n${END}`;
+    const start = agents.indexOf(START);
+    const end = agents.indexOf(END);
+    if (start >= 0 && end > start)
+        return agents.slice(0, start) + block + agents.slice(end + END.length);
+    return `${agents.replace(/\n*$/, "")}\n\n${block}\n`;
+};
+export const designDoc = (names, answers) => {
+    const rows = INTERVIEW.map((question) => `- **${question.title ?? question.text}:** ${(answers[question.key] ?? []).map((value) => labelOf(question, value)).join(", ")}`);
+    const languages = answers.contentLang ?? [];
+    const speech = speechModels(languages);
+    const warnings = languageWarnings(languages);
+    return [
+        `# ${names.command} — design`,
+        "",
+        `Written by \`npx @wirecat/cli-template new\`. The agent reads it first, asks the further questions the reference CLI`,
+        "does not answer, and starts building only after the owner has read it.",
+        "",
+        "## Answers",
+        "",
+        ...rows,
+        "",
+        "## Reference CLI",
+        "",
+        referenceLine(answers.category?.[0] ?? ""),
+        "",
+        "## Content languages",
+        "",
+        `Languages: ${languages.join(", ")}.`,
+        speech
+            ? `If this CLI defines a messenger, set its \`speechModels\` to ${speech.map((model) => `\`${model}\``).join(", ")}.`
+            : "No speech model in cli-core covers all of these languages: leave `speechModels` out.",
+        ...warnings.map((warning) => `- ${warning}`),
+        "",
+        "## Further answers",
+        "",
+        "## Open questions for the owner",
+        "",
+    ].join("\n");
+};
+const removeKit = (command) => command
+    .split(" && ")
+    .filter((part) => !/\bkit[:/]/.test(part))
+    .join(" && ");
+export const cliPackageJson = (text, names) => {
+    const pkg = JSON.parse(text);
+    const isKit = (value) => typeof value === "string" && /^(\.\/)?kit(\/|$)/.test(value);
+    const repoUrl = `git+https://github.com/${names.owner}/${names.name}.git`;
+    const next = { ...pkg, name: names.package, version: "0.0.0" };
+    if (typeof pkg.bin === "object" && pkg.bin) {
+        next.bin = Object.fromEntries(Object.entries(pkg.bin).filter(([, value]) => !isKit(value)));
+    }
+    if (Array.isArray(pkg.files))
+        next.files = pkg.files.filter((entry) => !isKit(entry) && !Object.values(PACKED_AS).includes(entry));
+    if (typeof pkg.scripts === "object" && pkg.scripts) {
+        next.scripts = Object.fromEntries(Object.entries(pkg.scripts)
+            .filter(([key]) => !key.startsWith("kit:"))
+            .map(([key, value]) => [key, removeKit(value)])
+            .filter(([, value]) => value.length > 0));
+    }
+    if (pkg.repository)
+        next.repository = { type: "git", url: repoUrl };
+    if (pkg.homepage)
+        next.homepage = `https://github.com/${names.owner}/${names.name}#readme`;
+    if (pkg.bugs)
+        next.bugs = { url: `https://github.com/${names.owner}/${names.name}/issues` };
+    return `${JSON.stringify(next, null, 2)}\n`;
+};
+const VERSION_FILE = "src/version.ts";
+export const cliReadme = (names) => [
+    `# ${names.command}`,
+    "",
+    `\`${names.command}\` is a WireCat command-line tool, started from`,
+    "[cli-template](https://github.com/WireCatLabs/cli-template). Its design is in",
+    "[docs/dev/DESIGN.md](docs/dev/DESIGN.md).",
+    "",
+    "## Quick start",
+    "",
+    "```sh",
+    "pnpm install",
+    "pnpm build",
+    `node dist/bin/${names.command}.js personal doctor`,
+    "```",
+    "",
+    "`personal` is the profile: a name you choose for one account. Every command that uses an account starts with it.",
+    "",
+].join("\n");
+export const cliChangelog = (names, source) => [
+    "# Changelog",
+    "",
+    `Notable changes to \`${names.package}\`. One section per version, newest first.`,
+    "",
+    "## Unreleased",
+    "",
+    "### Added",
+    "",
+    `- Started from \`${source.name}\` ${source.version}.`,
+    "",
+].join("\n");
+const writeOut = async (dir, path, content, mode = 0o644) => {
+    const full = join(dir, path);
+    await mkdir(dirname(full), { recursive: true });
+    await writeFile(full, content);
+    await chmod(full, mode);
+};
+// Git for Windows sets core.fileMode=false, so a later `git add -A` there records every file as 644; a mode set
+// in the index survives that add.
+export const markExecutable = async (cwd, paths) => {
+    if (paths.length)
+        await run("git", ["add", "--chmod=+x", "--", ...paths], { cwd });
+};
+export const manualSteps = (names) => [
+    `1. Create the repository ${names.owner}/${names.name} and its main ruleset (cli-base docs/standards/new-cli.md).`,
+    `2. Set npm trusted publishing for ${names.package}, naming release.yml (WC-REL-11), and add any secrets.`,
+    "3. Pick a monthly cron day no other repository uses: .github/workflows/monthly.yml holds a placeholder CI rejects.",
+    "4. WireCat CLIs only: a pull request to cli-base's PARITY_GROUPS, a line in cli-core's WIRECAT_TOOLS and in cli-docs' tools.json.",
+];
+export const runNew = async (cwd, source, args, io) => {
+    const { names, answers } = await collect(args, io);
+    const target = join(cwd, names.name);
+    if (!(await isEmptyOrMissing(target)))
+        throw new Error(`${target} already exists and is not empty`);
+    const rendered = await renderTemplate(source, names);
+    const category = answers.category?.[0] ?? "";
+    const rewrites = {
+        "package.json": (text) => cliPackageJson(text, names),
+        "README.md": () => cliReadme(names),
+        "CHANGELOG.md": () => cliChangelog(names, source),
+        [VERSION_FILE]: (text) => text.replace(/VERSION = "[^"]*"/, 'VERSION = "0.0.0"'),
+        "AGENTS.md": (text) => withReference(text, category),
+    };
+    const hashes = {};
+    for (const [path, file] of rendered) {
+        if (file.kind === "file")
+            hashes[path] = sha256(file.content);
+        const rewrite = rewrites[path];
+        const content = rewrite ? rewrite(file.content.toString("utf8")) : file.content;
+        await writeOut(target, path, content, file.mode);
+    }
+    if (!rendered.has("AGENTS.md"))
+        await writeOut(target, "AGENTS.md", withReference("", category));
+    await writeOut(target, "docs/dev/DESIGN.md", designDoc(names, answers));
+    const manifest = {
+        template: source.name,
+        version: source.version,
+        names,
+        files: hashes,
+        seeds: source.manifest.seeds,
+    };
+    await writeOut(target, MANIFEST, `${JSON.stringify(manifest, null, 2)}\n`);
+    await run("git", ["init", "-q", "-b", "main"], { cwd: target });
+    await markExecutable(target, [...rendered].filter(([, file]) => file.mode & 0o111).map(([path]) => path));
+    const warnings = languageWarnings(answers.contentLang ?? []);
+    return [
+        `Created ${target} from ${source.name}@${source.version}.`,
+        ...(warnings.length ? ["", "Content languages:", ...warnings.map((warning) => `  ${warning}`)] : []),
+        "",
+        "Next:",
+        `  cd ${names.name} && pnpm install && pnpm ci:quick`,
+        '  git add -A && git commit -m "chore: start from @wirecat/cli-template"',
+        `  then give the agent docs/dev/DESIGN.md; every example passes a profile, e.g. ${names.command} personal doctor`,
+        "",
+        "Four steps need a person:",
+        ...manualSteps(names).map((step) => `  ${step}`),
+        "",
+    ].join("\n");
+};

package/kit/dist/rename.js

@@ -0,0 +1,36 @@
+const escapeRegex = (text) => text.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+const word = (text) => `(?<![A-Za-z0-9_])${escapeRegex(text)}(?![A-Za-z0-9])`;
+export const upperCommand = (command) => command.toUpperCase().replaceAll("-", "_");
+// The command word followed by ": " is a key, such as cli-core's `app: APP` in a program definition, and
+// stays. One pass, so a replacement that itself contains the command placeholder (a package named
+// "@x/app-tools") is never renamed a second time.
+export const renamer = (placeholders, names) => {
+    const table = new Map([
+        [placeholders.package, names.package],
+        [placeholders.repository, `${names.owner}/${names.name}`],
+        [placeholders.name, names.name],
+        [placeholders.command, names.command],
+        [upperCommand(placeholders.command), upperCommand(names.command)],
+    ]);
+    const pattern = new RegExp([escapeRegex(placeholders.package), escapeRegex(placeholders.repository), word(placeholders.name)]
+        .concat(`${word(placeholders.command)}(?!:\\s)`)
+        .concat(word(upperCommand(placeholders.command)))
+        .join("|"), "g");
+    return (text) => text.replace(pattern, (match) => table.get(match) ?? match);
+};
+const isBinary = (content) => content.subarray(0, 8000).includes(0);
+export const withLf = (content) => isBinary(content) || !content.includes(13) ? content : Buffer.from(content.toString("utf8").replaceAll("\r\n", "\n"));
+export const renameContent = (rename, content) => isBinary(content) ? content : Buffer.from(rename(content.toString("utf8")), "utf8");
+const KIT_CONFIG = /(^|\/)(vitest\.config\.ts|biome\.json|cspell\.json|tsconfig[^/]*\.json|\.markdownlint-cli2\.jsonc)$/;
+// The template's configs name kit/ so its own checks cover the copy tool; a CLI has no kit/, and the
+// entries would point at nothing (or fail, for an include that must match).
+export const stripKit = (path, content) => {
+    if (!KIT_CONFIG.test(path))
+        return content;
+    const text = content.toString("utf8");
+    const stripped = text
+        .replace(/\[\s*"!?(\.\/)?kit\/[^"]*"\s*\]/g, "[]")
+        .replace(/,\s*"!?(\.\/)?kit\/[^"]*"/g, "")
+        .replace(/"!?(\.\/)?kit\/[^"]*",\s*/g, "");
+    return stripped === text ? content : Buffer.from(stripped, "utf8");
+};

package/kit/dist/source.js

@@ -0,0 +1,98 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdtemp, readdir, readFile, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { classify, MANIFEST, parseTemplateManifest, readJson, } from "./manifest.js";
+import { renameContent, renamer, stripKit } from "./rename.js";
+const run = promisify(execFile);
+export const ownRoot = () => fileURLToPath(new URL("../../", import.meta.url));
+export const loadSource = async (root) => {
+    const pkg = (await readJson(join(root, "package.json")));
+    if (typeof pkg.name !== "string" || typeof pkg.version !== "string") {
+        throw new Error(`${join(root, "package.json")}: needs a name and a version`);
+    }
+    const manifestPath = join(root, MANIFEST);
+    const manifest = parseTemplateManifest(manifestPath, await readJson(manifestPath));
+    return { root, name: pkg.name, version: pkg.version, manifest };
+};
+const SKIP_DIRS = new Set([".git", "node_modules"]);
+// npm renames .gitignore to .npmignore when it installs a package, so the package ships it as gitignore.
+export const PACKED_AS = { ".gitignore": "gitignore" };
+const onDisk = async (root, path) => {
+    const packed = PACKED_AS[path];
+    const full = join(root, path);
+    if (!packed)
+        return full;
+    return (await stat(full).catch(() => undefined)) ? full : join(root, packed);
+};
+const walk = async (dir) => {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const nested = await Promise.all(entries.map(async (entry) => {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            return SKIP_DIRS.has(entry.name) ? [] : walk(path);
+        return entry.isFile() ? [path] : [];
+    }));
+    return nested.flat();
+};
+const listEntry = async (root, entry) => {
+    const path = await onDisk(root, entry);
+    const info = await stat(path).catch(() => undefined);
+    if (!info)
+        throw new Error(`${MANIFEST} lists "${entry}", but the package has no such ${entry.endsWith("/") ? "folder" : "file"}`);
+    if (!entry.endsWith("/"))
+        return [entry];
+    return (await walk(path)).map((file) => relative(root, file).split(sep).join("/"));
+};
+export const listTemplate = async (source) => {
+    const { files, seeds } = source.manifest;
+    const paths = (await Promise.all(["package.json", ...files, ...seeds].map((entry) => listEntry(source.root, entry)))).flat();
+    return new Map([...new Set(paths)].sort().flatMap((path) => {
+        const kind = classify(path, files, seeds);
+        return kind ? [[path, kind]] : [];
+    }));
+};
+// npm cannot set the executable bit when it installs on Windows, so a shebang stands in for it there. A .ts or .js
+// entry point carries one for node, not for the shell.
+const isExecutable = (path, content, mode) => (mode & 0o111) !== 0 || (content.subarray(0, 2).toString() === "#!" && !/\.[cm]?[jt]sx?$/.test(path));
+export const renderTemplate = async (source, names) => {
+    const rename = renamer(source.manifest.placeholders, names);
+    const listed = await listTemplate(source);
+    const rendered = await Promise.all([...listed].map(async ([path, kind]) => {
+        const full = await onDisk(source.root, path);
+        const [content, info] = await Promise.all([readFile(full), stat(full)]);
+        const renamed = renameContent(rename, stripKit(path, content));
+        const mode = isExecutable(path, content, info.mode) ? 0o755 : 0o644;
+        return [rename(path), { kind, content: renamed, mode }];
+    }));
+    return new Map(rendered);
+};
+// On Windows npm is npm.cmd, which execFile cannot start without a shell; npm-cli.js beside node runs anywhere.
+export const npmCommand = (args) => {
+    const home = dirname(process.execPath);
+    const cli = [
+        join(home, "node_modules/npm/bin/npm-cli.js"),
+        join(home, "../lib/node_modules/npm/bin/npm-cli.js"),
+    ].find((path) => existsSync(path));
+    return cli ? [process.execPath, [cli, ...args]] : ["npm", args];
+};
+export const fetchPublished = async (name, version) => {
+    const dir = await mkdtemp(join(tmpdir(), "cli-template-"));
+    const { stdout } = await run(...npmCommand(["pack", `${name}@${version}`, "--silent", "--pack-destination", dir])).catch((error) => {
+        throw new Error(`could not download ${name}@${version} from npm, which upgrade needs as the merge base: ${error.message}`);
+    });
+    const tarball = stdout.trim().split("\n").pop() ?? "";
+    const dispose = () => rm(dir, { recursive: true, force: true });
+    try {
+        // GNU tar reads "C:" in a path as a remote host, so the archive is named relative to its folder.
+        await run("tar", ["-xzf", tarball], { cwd: dir });
+        return { source: await loadSource(join(dir, "package")), dispose };
+    }
+    catch (error) {
+        await dispose();
+        throw error;
+    }
+};

package/kit/dist/upgrade.js

@@ -0,0 +1,230 @@
+import { execFile } from "node:child_process";
+import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { promisify } from "node:util";
+import { classify, MANIFEST, readCliManifest, sha256 } from "./manifest.js";
+import { markExecutable } from "./new.js";
+import { withLf } from "./rename.js";
+import { renderTemplate } from "./source.js";
+const run = promisify(execFile);
+const MODES = ["apply", "replace", "skip"];
+// Git for Windows checks text out with CRLF by default; the template's hashes and merges are of LF text.
+const readMaybe = (path) => readFile(path).then(withLf, () => undefined);
+const requireCleanTree = async (cwd) => {
+    const { stdout } = await run("git", ["status", "--porcelain"], { cwd }).catch(() => {
+        throw new Error(`${cwd} is not a git repository; upgrade needs one so every change can be seen and undone`);
+    });
+    if (stdout.trim()) {
+        throw new Error("the git working tree has changes; commit or stash them first, so upgrade's changes stand alone");
+    }
+};
+const stateOf = (recorded, ours) => {
+    if (recorded === undefined)
+        return ours ? "new, a file exists here" : "new";
+    if (!ours)
+        return "deleted here";
+    return sha256(ours) === recorded ? "clean" : "edited";
+};
+export const mergeFile = async (ours, base, theirs) => {
+    const dir = await mkdtemp(join(tmpdir(), "cli-template-merge-"));
+    try {
+        const files = ["ours", "base", "theirs"].map((name) => join(dir, name));
+        await Promise.all([ours, base, theirs].map((content, index) => writeFile(files[index] ?? "", content)));
+        const args = ["merge-file", "-p", "-L", "this CLI", "-L", "template before", "-L", "template now", ...files];
+        return await run("git", args, { encoding: "buffer", maxBuffer: 64 * 1024 * 1024 }).then(({ stdout }) => ({ content: stdout, conflicts: 0 }), (error) => {
+            if (typeof error.code === "number" && error.code > 0 && error.code < 128 && error.stdout) {
+                return { content: error.stdout, conflicts: error.code };
+            }
+            throw new Error(`git merge-file failed: ${error.message}`);
+        });
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+};
+const writeAs = async (path, content, mode) => {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content);
+    if (mode !== undefined)
+        await chmod(path, mode);
+};
+const diffText = async (before, after) => {
+    const dir = await mkdtemp(join(tmpdir(), "cli-template-diff-"));
+    try {
+        const [a, b] = [join(dir, "template-before"), join(dir, "template-now")];
+        await Promise.all([writeFile(a, before), writeFile(b, after)]);
+        return await run("git", ["diff", "--no-index", "--no-color", a, b]).then(({ stdout }) => stdout, (error) => error.stdout ?? "");
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+};
+const hasMarkers = (content) => /^(<{7} |={7}$|>{7} )/m.test(content.toString("utf8"));
+const writeManifest = (cwd, manifest) => writeFile(join(cwd, MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`);
+// A conflict leaves the new version waiting in "pending"; it moves in once the markers are gone, so a
+// resolved file is never merged a second time against the old base.
+const finishPending = async (cwd, manifest) => {
+    const { pending, ...rest } = manifest;
+    if (!pending)
+        return manifest;
+    const left = [];
+    for (const path of pending.conflicts) {
+        const content = await readMaybe(join(cwd, path));
+        if (content && hasMarkers(content))
+            left.push(path);
+    }
+    if (left.length) {
+        throw new Error(`conflict markers are still in:\n${left.map((path) => `  ${path}`).join("\n")}\nResolve them, then run upgrade again.`);
+    }
+    const done = { ...rest, version: pending.version, files: pending.files };
+    await writeManifest(cwd, done);
+    return done;
+};
+export const runUpgrade = async (cwd, target, fetchVersion, options, io) => {
+    const recorded = await readCliManifest(cwd);
+    const manifest = options.dryRun ? recorded : await finishPending(cwd, recorded);
+    if (manifest !== recorded && manifest.version === target.version) {
+        return `Conflicts resolved; ${MANIFEST} is now on ${target.version}. Review with git diff, then commit.`;
+    }
+    if (manifest.version === target.version)
+        return `Already on ${target.name}@${target.version}.`;
+    if (!options.dryRun && manifest === recorded)
+        await requireCleanTree(cwd);
+    const seeds = [...new Set([...manifest.seeds, ...target.manifest.seeds])];
+    const renderedNow = await renderTemplate(target, manifest.names);
+    const owned = new Map([...renderedNow].filter(([path, file]) => file.kind === "file" && classify(path, [path], seeds) === "file"));
+    let before;
+    const baseOf = async (path) => {
+        before ??= fetchVersion(manifest.template, manifest.version).then(async ({ source, dispose }) => {
+            try {
+                return await renderTemplate(source, manifest.names);
+            }
+            finally {
+                await dispose();
+            }
+        });
+        return (await before).get(path)?.content ?? Buffer.alloc(0);
+    };
+    const changes = [];
+    for (const [path, theirs] of owned) {
+        const recorded = manifest.files[path];
+        if (recorded === sha256(theirs.content))
+            continue;
+        const ours = await readMaybe(join(cwd, path));
+        if (ours && sha256(ours) === sha256(theirs.content))
+            continue;
+        changes.push({ path, state: stateOf(recorded, ours), theirs, ours });
+    }
+    const dropped = Object.keys(manifest.files).filter((path) => !owned.has(path) && classify(path, [path], seeds) === "file");
+    let header = [`Upgrading from ${manifest.template}@${manifest.version} to ${target.version}.`];
+    if (dropped.length) {
+        header = header.concat("No longer part of the template, left in place for you to keep or delete:", dropped.map((path) => `  ${path}`));
+    }
+    const planned = async (change, mode) => {
+        if (mode === "skip")
+            return { outcome: "skipped" };
+        if (mode === "replace")
+            return { outcome: "replaced", content: change.theirs.content };
+        if (change.state === "deleted here")
+            return { outcome: "kept deleted" };
+        if (change.state === "clean" || change.state === "new" || !change.ours) {
+            return { outcome: "applied", content: change.theirs.content };
+        }
+        const base = change.state === "edited" ? await baseOf(change.path) : Buffer.alloc(0);
+        const merged = await mergeFile(change.ours, base, change.theirs.content);
+        return { outcome: merged.conflicts ? "conflict" : "applied", content: merged.content };
+    };
+    if (options.dryRun) {
+        const rows = await Promise.all(changes.map(async (change) => {
+            const what = options.mode
+                ? (await planned(change, options.mode)).outcome
+                : "asked: apply, replace, skip or diff";
+            return `  ${change.path} (${change.state}): ${what}`;
+        }));
+        return [
+            ...header,
+            changes.length ? "Would change:" : "No template-owned file changed.",
+            ...rows,
+            "Dry run: nothing written.",
+        ].join("\n");
+    }
+    if (changes.length && !options.mode && !io.interactive) {
+        throw new Error(`no terminal to ask in; pass --apply, --replace or --skip for every file, or --dry-run to list them:\n${changes
+            .map((change) => `  ${change.path} (${change.state})`)
+            .join("\n")}`);
+    }
+    const rl = changes.length && !options.mode
+        ? createInterface({ input: io.input, output: io.output, terminal: false })
+        : undefined;
+    const choose = async (change) => {
+        if (options.mode || !rl)
+            return options.mode ?? "skip";
+        for (;;) {
+            const answer = (await rl.question(`${change.path} (${change.state}): [a]pply, [r]eplace, [s]kip, [d]iff? `)).trim();
+            const mode = MODES.find((candidate) => candidate === answer || candidate[0] === answer);
+            if (mode)
+                return mode;
+            if (answer === "d" || answer === "diff") {
+                const base = change.state === "new" || change.state === "new, a file exists here"
+                    ? Buffer.alloc(0)
+                    : await baseOf(change.path);
+                io.output.write(await diffText(base, change.theirs.content));
+            }
+        }
+    };
+    const results = [];
+    const conflicts = [];
+    const executable = [];
+    try {
+        for (const change of changes) {
+            const { outcome, content } = await planned(change, await choose(change));
+            if (content)
+                await writeAs(join(cwd, change.path), content, change.ours ? undefined : change.theirs.mode);
+            if (content && !change.ours && change.theirs.mode & 0o111)
+                executable.push(change.path);
+            if (outcome === "conflict")
+                conflicts.push(change.path);
+            results.push(`  ${change.path} (${change.state}): ${outcome}`);
+        }
+    }
+    finally {
+        rl?.close();
+    }
+    await markExecutable(cwd, executable);
+    const footer = ["Then re-run community's adopt-standards.py for config/wirecat/, which upgrade never touches."];
+    const files = Object.fromEntries([...owned].map(([path, file]) => [path, sha256(file.content)]));
+    if (conflicts.length) {
+        await writeManifest(cwd, { ...manifest, seeds, pending: { version: target.version, files, conflicts } });
+        return [
+            ...header,
+            ...results,
+            "",
+            `Conflicts left in ${conflicts.length} file(s); ${MANIFEST} stays on ${manifest.version} until they are resolved:`,
+            ...conflicts.map((path) => `  ${path}`),
+            `Resolve the markers, then run upgrade again: it checks they are gone and moves ${MANIFEST} to ${target.version}.`,
+            ...footer,
+        ].join("\n");
+    }
+    const next = {
+        ...manifest,
+        template: target.name,
+        version: target.version,
+        files,
+        seeds,
+    };
+    await writeManifest(cwd, next);
+    return [
+        ...header,
+        ...(results.length ? results : ["No template-owned file changed."]),
+        `${MANIFEST} is now on ${target.version}. Review with git diff, then commit.`,
+        ...footer,
+    ].join("\n");
+};
+export const parseMode = (flags) => {
+    const picked = MODES.filter((mode) => flags[mode]);
+    if (picked.length > 1)
+        throw new Error(`pick one of --apply, --replace or --skip, not ${picked.map((mode) => `--${mode}`).join(" and ")}`);
+    return picked[0];
+};

package/kit/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
+}

package/kit/tsconfig.test.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "noEmit": true, "rootDir": "." },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}

package/lefthook.yml

@@ -0,0 +1,2 @@
+extends:
+  - config/wirecat/lefthook.yml

package/lint/overrides.json

@@ -0,0 +1 @@
+[]