@wirecat/cli-template 0.0.0-stage → 0.1.0

package/kit/dist/interview.js

@@ -0,0 +1,170 @@
+const npmName = /^(@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+const commandWord = /^[a-z][a-z0-9-]*$/;
+const githubOwner = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
+const languageCode = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+export const NAME_QUESTIONS = [
+    {
+        key: "command",
+        flag: "command",
+        text: "The command word people type (lowercase, e.g. cal)",
+        check: (value) => commandWord.test(value) ? undefined : "lowercase letters, digits and dashes, starting with a letter",
+    },
+    {
+        key: "package",
+        flag: "package",
+        text: "The npm package name (e.g. @wirecat/cal-cli)",
+        check: (value) => (npmName.test(value) ? undefined : "a valid npm package name, scoped or not"),
+    },
+    {
+        key: "owner",
+        flag: "owner",
+        text: "The GitHub owner of the repository (e.g. WireCatLabs)",
+        check: (value) => (githubOwner.test(value) ? undefined : "a GitHub user or organisation name"),
+    },
+];
+export const INTERVIEW = [
+    {
+        key: "category",
+        title: "Category",
+        flag: "category",
+        text: "What kind of tool is it?",
+        choices: [
+            { value: "messenger", label: "messenger" },
+            { value: "mail", label: "mail" },
+            { value: "notes", label: "notes" },
+            { value: "files", label: "files and documents" },
+            { value: "calendar", label: "calendar" },
+            { value: "meetings", label: "meetings" },
+        ],
+    },
+    {
+        key: "contentLang",
+        title: "Content languages",
+        flag: "content-lang",
+        text: "Which languages is the content in? Language codes, several allowed (e.g. en,ru)",
+        multiple: true,
+        check: (value) => (languageCode.test(value) ? undefined : "a language code such as en, ru or pt-BR"),
+    },
+    {
+        key: "signIn",
+        title: "Sign-in",
+        flag: "sign-in",
+        text: "How does a person sign in?",
+        choices: [
+            { value: "oauth", label: "OAuth in the browser" },
+            { value: "token", label: "an API token or key" },
+            { value: "session", label: "a session (phone code, QR)" },
+            { value: "none", label: "none" },
+        ],
+    },
+    {
+        key: "api",
+        title: "The API",
+        flag: "api",
+        text: "What does the service offer to build on?",
+        choices: [
+            { value: "official-client", label: "an official API with an official client library" },
+            { value: "official-docs", label: "official API documentation only" },
+            { value: "unofficial", label: "nothing official" },
+        ],
+    },
+    {
+        key: "filters",
+        title: "How people filter",
+        flag: "filters",
+        text: "How do people filter what they find? Several allowed",
+        multiple: true,
+        choices: [
+            { value: "time", label: "by time" },
+            { value: "person", label: "by person" },
+            { value: "container", label: "by container (chat, folder, calendar)" },
+            { value: "text", label: "by words in the text" },
+            { value: "status", label: "by status or label" },
+        ],
+    },
+    {
+        key: "neverStore",
+        title: "Never in the store, a log or the output",
+        flag: "never-store",
+        text: "What must never reach the store, a log or the output? Several allowed",
+        multiple: true,
+        choices: [
+            { value: "tokens", label: "tokens and passwords" },
+            { value: "codes", label: "one-time codes and passcodes" },
+            { value: "secret-links", label: "links that carry a secret" },
+            { value: "content", label: "the full content, keep only metadata" },
+        ],
+    },
+    {
+        key: "untrusted",
+        title: "Untrusted input",
+        flag: "untrusted",
+        text: "What untrusted input arrives? Several allowed",
+        multiple: true,
+        exclusive: "none",
+        choices: [
+            { value: "messages", label: "messages from other people" },
+            { value: "files", label: "files and attachments" },
+            { value: "links", label: "links" },
+            { value: "names", label: "names and titles set by others" },
+            { value: "none", label: "none" },
+        ],
+    },
+];
+const OTHER = "other:";
+export const choiceList = (question) => question.choices
+    ? `${question.choices.map((choice) => choice.value).join(", ")}, or ${OTHER}<your answer>`
+    : (question.check?.("") ?? "");
+const checkOne = (question, value) => {
+    if (value.length === 0)
+        return "empty answer";
+    if (!question.choices)
+        return question.check?.(value);
+    if (value.startsWith(OTHER))
+        return value.length > OTHER.length ? undefined : `write the answer after "${OTHER}"`;
+    return question.choices.some((choice) => choice.value === value) ? undefined : `"${value}" is not one of the choices`;
+};
+export const parseAnswer = (question, raw) => {
+    const parts = question.multiple ? raw.split(",").map((part) => part.trim()) : [raw.trim()];
+    for (const part of parts) {
+        const problem = checkOne(question, part);
+        if (problem)
+            return { error: `--${question.flag}: ${problem}; expected ${choiceList(question)}` };
+    }
+    if (question.exclusive && parts.length > 1 && parts.includes(question.exclusive)) {
+        return { error: `--${question.flag}: "${question.exclusive}" cannot be combined with other answers` };
+    }
+    return { value: [...new Set(parts)] };
+};
+export const labelOf = (question, value) => value.startsWith(OTHER)
+    ? `other: ${value.slice(OTHER.length)}`
+    : (question.choices?.find((choice) => choice.value === value)?.label ?? value);
+const menu = (question) => [
+    ...(question.choices ?? []).map((choice, index) => `  ${index + 1}. ${choice.label}`),
+    `  ${(question.choices?.length ?? 0) + 1}. other (type it)`,
+].join("\n");
+const fromMenu = async (rl, question, line) => {
+    const choices = question.choices ?? [];
+    const picked = [];
+    for (const part of line.split(",")) {
+        const index = Number(part.trim()) - 1;
+        if (index === choices.length)
+            picked.push(`${OTHER}${(await rl.question("  Other: ")).trim()}`);
+        else
+            picked.push(choices[index]?.value ?? part.trim());
+    }
+    return picked.join(",");
+};
+export const ask = async (rl, output, question) => {
+    for (;;) {
+        const prompt = question.choices
+            ? `${question.text}\n${menu(question)}\n${question.multiple ? "Numbers, comma-separated: " : "Number: "}`
+            : `${question.text}: `;
+        const line = (await rl.question(prompt)).trim();
+        const raw = question.choices && /^[\d,\s]+$/.test(line) ? await fromMenu(rl, question, line) : line;
+        const { value, error } = parseAnswer(question, raw);
+        if (value)
+            return value;
+        output.write(`${error}\n`);
+    }
+};

package/kit/dist/main.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { INTERVIEW, NAME_QUESTIONS } from "./interview.js";
+import { runNew } from "./new.js";
+import { fetchPublished, loadSource, ownRoot } from "./source.js";
+import { parseMode, runUpgrade } from "./upgrade.js";
+const USAGE = `Usage:
+  npx @wirecat/cli-template new <name> [answers]   copy the template into ./<name>
+  npx @wirecat/cli-template upgrade [--apply | --replace | --skip] [--dry-run]
+
+new asks for every missing answer in a terminal; without one, a missing answer is an error.
+  --command <word>      the command word people type
+  --package <name>      the npm package name
+  --owner <owner>       the GitHub owner of the repository
+${INTERVIEW.map((question) => `  --${question.flag.padEnd(20)}${question.title ?? question.text}`).join("\n")}
+Any interview answer also takes "other:<your answer>"; several answers are comma-separated.
+
+upgrade brings template changes into a CLI made from it; it needs a clean git working tree.
+  --apply      merge the template's change into every changed file (conflicts get git markers)
+  --replace    take the template's new file as it is
+  --skip       keep this CLI's files
+  --dry-run    list the files and what each would get; write nothing
+`;
+const answerFlags = Object.fromEntries([...NAME_QUESTIONS, ...INTERVIEW].map((question) => [question.flag, { type: "string" }]));
+const main = async (argv, io) => {
+    const [command, ...rest] = argv;
+    if (!command || command === "--help" || command === "-h")
+        return USAGE;
+    const source = await loadSource(ownRoot());
+    if (command === "--version")
+        return source.version;
+    if (command === "new") {
+        const { values, positionals } = parseArgs({
+            args: rest,
+            options: answerFlags,
+            allowPositionals: true,
+            strict: true,
+        });
+        if (positionals.length > 1)
+            throw new Error(`new takes one folder name, got ${positionals.join(" ")}`);
+        return runNew(process.cwd(), source, { name: positionals[0], flags: values }, io);
+    }
+    if (command === "upgrade") {
+        const { values, positionals } = parseArgs({
+            args: rest,
+            options: {
+                apply: { type: "boolean" },
+                replace: { type: "boolean" },
+                skip: { type: "boolean" },
+                "dry-run": { type: "boolean" },
+            },
+            strict: true,
+        });
+        if (positionals.length)
+            throw new Error(`upgrade takes no arguments, got ${positionals.join(" ")}`);
+        return runUpgrade(process.cwd(), source, fetchPublished, { mode: parseMode(values), dryRun: values["dry-run"] ?? false }, io);
+    }
+    throw new Error(`unknown command "${command}"; expected new or upgrade\n\n${USAGE}`);
+};
+const io = {
+    input: process.stdin,
+    output: process.stdout,
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+};
+main(process.argv.slice(2), io).then((text) => {
+    process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+}, (error) => {
+    process.stderr.write(`cli-template: ${error.message}\n`);
+    process.exitCode = 1;
+});

package/kit/dist/manifest.js

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+export const MANIFEST = "template.json";
+export const DEFAULT_PLACEHOLDERS = {
+    command: "app",
+    name: "app-cli",
+    package: "@wirecat/app-cli",
+    repository: "WireCatLabs/app-cli",
+};
+// package.json and the interview's answers belong to the CLI from the first copy.
+const ALWAYS_SEEDS = ["package.json", "docs/dev/DESIGN.md"];
+// The copy tool and the template's own manifest are never part of a CLI, whatever template.json lists.
+const NEVER_COPIED = [MANIFEST, "kit/"];
+export const sha256 = (content) => createHash("sha256").update(content).digest("hex");
+const fail = (file, problem) => {
+    throw new Error(`${file}: ${problem}`);
+};
+const isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === "string" && item.length > 0);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const checkEntries = (file, key, entries) => {
+    for (const entry of entries) {
+        if (entry.startsWith("/") || entry.split("/").includes(".."))
+            fail(file, `"${key}" entry "${entry}" must be relative`);
+    }
+};
+export const parseTemplateManifest = (file, raw) => {
+    if (!isRecord(raw))
+        return fail(file, "must be a JSON object");
+    if (!isStringList(raw.files))
+        return fail(file, `"files" must be a list of paths`);
+    if (!isStringList(raw.seeds))
+        return fail(file, `"seeds" must be a list of paths`);
+    checkEntries(file, "files", raw.files);
+    checkEntries(file, "seeds", raw.seeds);
+    const placeholders = raw.placeholders ?? {};
+    if (!isRecord(placeholders))
+        return fail(file, `"placeholders" must be an object`);
+    for (const [key, value] of Object.entries(placeholders)) {
+        if (!(key in DEFAULT_PLACEHOLDERS))
+            fail(file, `unknown placeholder "${key}"`);
+        if (typeof value !== "string" || value.length === 0)
+            fail(file, `placeholder "${key}" must be a string`);
+    }
+    return {
+        files: raw.files,
+        seeds: raw.seeds,
+        placeholders: { ...DEFAULT_PLACEHOLDERS, ...placeholders },
+    };
+};
+export const parseCliManifest = (file, raw) => {
+    if (!isRecord(raw))
+        return fail(file, "must be a JSON object");
+    const { template, version, names, files, seeds, pending } = raw;
+    if (typeof template !== "string")
+        return fail(file, `"template" must be the template's package name`);
+    if (typeof version !== "string")
+        return fail(file, `"version" must be the template version this CLI is on`);
+    if (!isRecord(names) || !["name", "command", "package", "owner"].every((key) => typeof names[key] === "string")) {
+        return fail(file, `"names" must hold name, command, package and owner`);
+    }
+    if (!isRecord(files) || !Object.values(files).every((hash) => typeof hash === "string")) {
+        return fail(file, `"files" must map each template-owned path to its sha256`);
+    }
+    if (!isStringList(seeds))
+        return fail(file, `"seeds" must be a list of paths`);
+    if (pending !== undefined &&
+        (!isRecord(pending) ||
+            typeof pending.version !== "string" ||
+            !isRecord(pending.files) ||
+            !isStringList(pending.conflicts))) {
+        return fail(file, `"pending" must hold version, files and conflicts`);
+    }
+    return {
+        template,
+        version,
+        names: names,
+        files: files,
+        seeds,
+        ...(pending ? { pending: pending } : {}),
+    };
+};
+export const readJson = async (path) => {
+    const text = await readFile(path, "utf8").catch(() => fail(path, "not found"));
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return fail(path, "is not valid JSON");
+    }
+};
+export const readCliManifest = async (dir) => {
+    const path = join(dir, MANIFEST);
+    return parseCliManifest(path, await readJson(path));
+};
+const matches = (entry, path) => entry.endsWith("/") ? path.startsWith(entry) : path === entry;
+// An exact path beats a folder, and a deeper folder beats a shallower one, so a seed folder can hold
+// one template-owned file and the other way round.
+const specificity = (entry) => (entry.endsWith("/") ? entry.length : Number.MAX_SAFE_INTEGER);
+export const classify = (path, files, seeds) => {
+    if (NEVER_COPIED.some((entry) => matches(entry, path)))
+        return undefined;
+    if (ALWAYS_SEEDS.includes(path))
+        return "seed";
+    const best = (entries) => entries.reduce((top, entry) => (matches(entry, path) ? Math.max(top, specificity(entry)) : top), -1);
+    const file = best(files);
+    const seed = best(seeds);
+    if (file < 0 && seed < 0)
+        return undefined;
+    return seed >= file ? "seed" : "file";
+};

package/kit/dist/new.js

@@ -0,0 +1,249 @@
+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 { 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));
+    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);
+};
+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 });
+    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,35 @@
+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 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");
+};