@wirecat/cli-template 0.0.0-stage → 0.1.1

package/kit/README.md

@@ -0,0 +1,127 @@
+# kit — `new` and `upgrade`
+
+The copy tool behind `npx @wirecat/cli-template`. It is the package's `cli-template` bin
+(`kit/dist/main.js`, built from `kit/src` by `tsc -p kit`). It is never copied into a new CLI.
+
+```sh
+npx @wirecat/cli-template new cal-cli --command cal --package @wirecat/cal-cli --owner WireCatLabs \
+  --category notes --content-lang en,ru --sign-in token --api official-docs --filters time,person \
+  --never-store tokens --untrusted messages,links
+npx @wirecat/cli-template upgrade --dry-run
+```
+
+## `new <name>`
+
+`new` copies the files of its own package version into `./<name>`. It renames the placeholders, rewrites
+`package.json`, runs `git init` and writes `template.json`, `docs/dev/DESIGN.md` and the reference CLI into
+`AGENTS.md`. It then prints the four steps that need a person. It does not install packages, commit or push.
+
+In a terminal it asks for every missing answer. Without a terminal, a missing answer is an error that lists the
+choices. Nothing is guessed.
+
+| Flag | Answers (several are comma-separated) |
+|---|---|
+| `<name>` | the folder and repository name |
+| `--command` | the command word |
+| `--package` | the npm package name |
+| `--owner` | the GitHub owner |
+| `--category` | `messenger`, `mail`, `notes`, `files`, `calendar`, `meetings` |
+| `--content-lang` | language codes, several: `en,ru` |
+| `--sign-in` | `oauth`, `token`, `session`, `none` |
+| `--api` | `official-client`, `official-docs`, `unofficial` |
+| `--filters` | several of `time`, `person`, `container`, `text`, `status` |
+| `--never-store` | several of `tokens`, `codes`, `secret-links`, `content` |
+| `--untrusted` | several of `messages`, `files`, `links`, `names`, or `none` alone |
+
+Every question except the names and `--content-lang` also takes `other:<your answer>`.
+
+The content languages go only into `DESIGN.md`. The file also holds the speech-model order a messenger definition
+should use, and the warnings for languages that have no stemmer or speech model in cli-core. `new` writes no search
+or model setting.
+
+## `upgrade`
+
+Run it in a CLI made from the template, with a clean git working tree. For each template-owned file that the
+template changed since the recorded version, it asks one of four things:
+
+- **apply** merges the change with `git merge-file`. The base is the recorded version, downloaded with `npm pack`.
+  "Ours" is the CLI's file and "theirs" is this version. Both template versions are renamed first, so the command
+  word never conflicts.
+- **replace** takes the template's file as it is.
+- **skip** keeps the CLI's file. It is asked again only when the template changes that file again.
+- **diff** shows the template's change.
+
+Without a terminal, `--apply`, `--replace` or `--skip` sets the answer for every file. `--dry-run` lists what each
+file would get and writes nothing. Seeds and `package.json` are never touched.
+
+A conflict leaves git markers, and `template.json` keeps the new state under `pending`. Resolve the markers and run
+`upgrade` again: it checks that the markers are gone and then moves to the new version.
+
+## `template.json` in this repository
+
+```json
+{
+  "files": [".github/", "bin/release", "AGENTS.md", "docs/meta.json"],
+  "seeds": ["src/", "README.md", "docs/", "config/wirecat/"],
+  "placeholders": {
+    "command": "app", "name": "app-cli", "package": "@wirecat/app-cli", "repository": "WireCatLabs/app-cli"
+  }
+}
+```
+
+- `files` lists the template-owned files that `upgrade` replays. `seeds` lists the files copied once and never
+  touched again; `config/wirecat/` goes there, because community's installer owns it. An entry ending in `/` is a
+  folder. The most specific entry wins: an exact path beats a folder, a deeper folder beats a shallower one, and a
+  seed wins a tie. Only listed files are copied. A listed file missing from the package stops `new`.
+- `template.json` and `kit/` are never copied, whatever the lists say. The kit's tests run inside `pnpm test`, so
+  the configs name `kit/`: `new` and `upgrade` drop every `"kit/…"` entry from `vitest.config.ts`, `biome.json`,
+  `cspell.json`, `tsconfig*.json` and `.markdownlint-cli2.jsonc`. Do not add a kit-only workflow: `.github/` is
+  template-owned and would carry it into every new CLI.
+- `README.md` and `CHANGELOG.md` describe the template, so `new` writes short ones for the new CLI.
+- `docs/dev/DESIGN.md` is always a seed: it holds the CLI's interview answers.
+- `package.json` is always a seed. `new` rewrites it: `name` becomes `--package`, `version` becomes `0.0.0`, and
+  `repository`, `homepage` and `bugs` point at `<owner>/<name>`. It also drops every `bin`, `files` entry and script
+  that points into `kit/`, and the `&& pnpm kit:…` parts of other scripts. `src/version.ts` gets `VERSION = "0.0.0"`.
+- `placeholders` is optional; the defaults are shown above. The command word is replaced as a whole word, so `app`
+  changes but `application` does not. Its upper-case form changes too: `APP_HOME` becomes `CAL_HOME`. Followed by a
+  colon and a space it is a key and stays, so cli-core's `app: APP` becomes `app: CAL`. `name` (`app-cli`) is the repository
+  name: `skills/app-cli/` becomes `skills/cal-cli/`. The word `app` cannot appear in prose for any other meaning.
+  Paths are renamed the same way: `src/bin/app.ts` becomes `src/bin/cal.ts`.
+- The version is `package.json`'s, never a second copy.
+- `AGENTS.md` can hold the block that `new` fills with the reference CLI:
+
+  ```md
+  <!-- cli-template:reference-cli:start -->
+  <!-- cli-template:reference-cli:end -->
+  ```
+
+  Without the block, `new` appends one.
+
+## `template.json` in a CLI made from it
+
+`new` writes this shape and `upgrade` keeps it current:
+
+```json
+{
+  "template": "@wirecat/cli-template",
+  "version": "0.1.0",
+  "names": { "name": "cal-cli", "command": "cal", "package": "@wirecat/cal-cli", "owner": "WireCatLabs" },
+  "files": { ".github/workflows/ci.yml": "<sha256 of the renamed template file at this version>" },
+  "seeds": ["src/", "README.md", "docs/", "config/wirecat/"]
+}
+```
+
+## What the package needs from the repository
+
+- `"bin": { "cli-template": "kit/dist/main.js" }`, and `kit/dist` in `files`. No ignore file inside `kit/`: npm
+  applies it and drops `kit/dist` from the package. npm also never packs `pnpm-lock.yaml`, so it is not a seed; the
+  new CLI makes its own on `pnpm install`.
+- Every template-owned file and seed in `files`. npm drops a nested `.gitignore` and any `.npmrc` when it packs.
+  When it installs a package, it renames `.gitignore` to `.npmignore`. So the package ships the root `.gitignore` as
+  `gitignore`, and `new` and `upgrade` read it back as `.gitignore`. The test in `kit/test/package.test.ts` runs the
+  bin from a tarball installed with `npm install` to catch that.
+- `kit:build` (`tsc -p kit`, then the copy to `gitignore`) run by `build`, because `bin/release` and CI pack with
+  `--ignore-scripts`. Node does not strip types under `node_modules`, so the bin must be JavaScript.
+- `pnpm kit:e2e` packs this repository, installs the tarball with npm, runs `new` and then `pnpm install` and
+  `pnpm ci:quick` in the new CLI. It needs the network and takes a few minutes, so it is not part of `pnpm test`.
+- `kit/test/**/*.test.ts` in vitest's `include`; `kit/dist` is ignored by the root `**/dist` rules of Biome and git.

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";
+};