netjes 0.0.0-stage → 0.0.1

package/cli/main.mjs

@@ -0,0 +1,167 @@
+// @ts-check
+// The netjes command line: parses the arguments and runs the command from the table in commands.mjs.
+import { readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { COMMANDS } from './commands.mjs';
+import { GLOBAL_OPTIONS, commandHelp, overviewHelp } from './help.mjs';
+import { packageVersion } from './scaffold.mjs';
+import { suggest } from './suggest.mjs';
+import { Interrupted, printError } from './terminal.mjs';
+
+/**
+ * A process to run, with the terminal's stdin and stderr. Its stdout is the terminal's too, or with `stdout: 'stderr'`
+ * the CLI's stderr, for a command whose own output on stdout is data. `prompt`, there only with a terminal to ask in,
+ * resolves to null when no answer comes and rejects with Interrupted on Ctrl+C.
+ * @typedef {{ command: string; args: string[]; cwd: string; env: Record<string, string | undefined>; stdout?: 'stderr' }} SpawnCall
+ * @typedef {{
+ *   cwd: string;
+ *   env: Record<string, string | undefined>;
+ *   stdout(text: string): void;
+ *   stderr(text: string): void;
+ *   spawn(call: SpawnCall): Promise<number>;
+ *   capture?(call: SpawnCall): Promise<{ code: number; stdout: string; stderr: string }>;
+ *   color?: { stdout: boolean; stderr: boolean };
+ *   prompt?(question: string): Promise<string | null>;
+ *   portFree?(port: number, host?: string): Promise<boolean>;
+ * }} CliIo
+ * @typedef {import('./commands.mjs').Command} Command
+ * @typedef {import('./commands.mjs').OptionSpec} OptionSpec
+ */
+
+/** Words people try for a command that is called something else here. Suggestions only, never aliases. */
+const MEANT = new Map([
+  ['doctor', 'info'],
+  ['init', 'new'],
+  ['create', 'new'],
+  ['serve', 'start'],
+  ['version', '--version'],
+]);
+
+/** A mistake in the arguments: reported as one line on stderr, with exit code 1. */
+class UsageError extends Error {}
+
+/** @param {string | undefined} name */
+const commandNamed = (name) => (name !== undefined && Object.hasOwn(COMMANDS, name) ? COMMANDS[name] : undefined);
+
+/**
+ * parseArgs options for these specs; never strict, so that each mistake gets a message of our own.
+ * @param {Record<string, OptionSpec>} specs
+ * @param {string[]} args
+ */
+function parse(specs, args) {
+  /** @type {Record<string, { type: 'string' | 'boolean'; short?: string }>} */
+  const options = Object.fromEntries(
+    Object.entries(specs).map(([name, { type, short }]) => [name, short ? { type, short } : { type }]),
+  );
+  return parseArgs({ args, options, allowPositionals: true, strict: false, tokens: true });
+}
+
+/**
+ * The options and arguments a command was given, or a UsageError for the first mistake in them. With `helping`, the
+ * arguments are `help [<command>]`, and the command's options are accepted as they are next to --help.
+ * @param {string[]} argv
+ * @param {string | undefined} name
+ * @param {Command | undefined} command
+ * @param {boolean} helping
+ */
+function validate(argv, name, command, helping = false) {
+  /** @type {Record<string, OptionSpec>} */
+  const allowed = { ...GLOBAL_OPTIONS, ...command?.options };
+  const own = name !== undefined && !helping;
+  const prefix = helping ? 'netjes help' : own ? `netjes ${name}` : 'netjes';
+  const helpCommand = own ? `netjes help ${name}` : 'netjes --help';
+  const { values, positionals, tokens } = parse(allowed, argv);
+  const accepts = helping ? 1 : Object.keys(command?.arguments ?? {}).length;
+  // The first positional is the command itself (or help); `accepts` more may follow it.
+  let seen = 0;
+  for (const token of tokens) {
+    if (token.kind === 'positional') {
+      if (seen++ > accepts) throw new UsageError(`${prefix}: unexpected argument '${token.value}'; run \`${helpCommand}\` for its usage`);
+    } else if (token.kind === 'option') {
+      const spec = Object.hasOwn(allowed, token.name) ? allowed[token.name] : undefined;
+      if (!spec) {
+        if (own && (name === 'dev' || name === 'start') && (token.name === 'port' || token.name === 'p')) {
+          // The number the user typed (`--port 3000`, `--port=3000`, `-p3000`), else a placeholder.
+          const typed = [token.value, /^-p(\d+)$/.exec(argv[token.index] ?? '')?.[1], argv[token.index + 1]];
+          const port = typed.find((value) => value !== undefined && /^\d+$/.test(value)) ?? '<port>';
+          throw new UsageError(
+            `${prefix}: unknown option '${token.rawName}'; netjes has no port option, the app's URL sets it: ` +
+              `set ASPNETCORE_URLS=http://localhost:${port} when you run netjes ${name}`,
+          );
+        }
+        const meant = token.rawName.startsWith('--') ? suggest(token.name, Object.keys(allowed)) : undefined;
+        throw new UsageError(
+          `${prefix}: unknown option '${token.rawName}'; ` +
+            (meant ? `did you mean '--${meant}'?` : `run \`${helpCommand}\` for ${own ? 'its' : 'the'} options`),
+        );
+      }
+      if (spec.type === 'string' && (token.value === undefined || (!token.inlineValue && token.value.startsWith('-')))) {
+        throw new UsageError(`${prefix}: option '--${token.name}' needs a value: --${token.name} ${spec.value ?? '<value>'}`);
+      }
+      if (spec.type === 'boolean' && token.value !== undefined) {
+        throw new UsageError(`${prefix}: option '--${token.name}' takes no value`);
+      }
+    }
+  }
+  return { values, args: positionals.slice(1) };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {CliIo} io
+ * @returns {Promise<number>}
+ */
+export async function run(argv, io) {
+  try {
+    return await dispatch(argv, io);
+  } catch (error) {
+    if (error instanceof Interrupted) return 130;
+    if (!(error instanceof UsageError)) throw error;
+    printError(io, error.message);
+    return 1;
+  }
+}
+
+/**
+ * @param {string[]} argv
+ * @param {CliIo} io
+ * @returns {Promise<number>}
+ */
+async function dispatch(argv, io) {
+  // A first pass, knowing every option's type so that a value (--name Shop) is not taken for the command.
+  const every = Object.assign({}, GLOBAL_OPTIONS, ...Object.values(COMMANDS).map((command) => command.options));
+  const first = parse(every, argv);
+  if (first.values.version) {
+    io.stdout(`${await packageVersion()}\n`);
+    return 0;
+  }
+
+  const [word, ...rest] = first.positionals;
+  const helping = word === 'help';
+  // `netjes help help` is the overview, as `netjes help` is.
+  const name = helping ? (rest[0] === 'help' ? undefined : rest[0]) : word;
+  const command = commandNamed(name);
+  if (name !== undefined && !command) {
+    const meant = MEANT.get(name.toLowerCase()) ?? suggest(name, Object.keys(COMMANDS));
+    throw new UsageError(
+      `netjes: unknown command '${name}'; ` + (meant ? `did you mean \`netjes ${meant}\`?` : 'run `netjes --help` for the commands'),
+    );
+  }
+
+  const { values, args } = validate(argv, name, command, helping);
+  if (helping || values.help || !command || !name) {
+    io.stdout(command && name ? commandHelp(name, command) : overviewHelp(COMMANDS, await packageVersion()));
+    return 0;
+  }
+  const cwd = typeof values.cwd === 'string' ? path.resolve(io.cwd, values.cwd) : io.cwd;
+  if (typeof values.cwd === 'string' && !statSync(cwd, { throwIfNoEntry: false })?.isDirectory()) {
+    throw new UsageError(`netjes ${name}: --cwd ${values.cwd} is not a directory (${cwd})`);
+  }
+  if (command.project?.(values) && !readdirSync(cwd).some((entry) => entry.endsWith('.csproj'))) {
+    throw new UsageError(
+      `netjes ${name}: no .csproj in ${cwd}; run it in the app's folder, pass --cwd <dir>, or create an app with \`netjes new <dir>\``,
+    );
+  }
+  return command.run({ io, cwd, args, options: values });
+}

package/cli/packages.mjs

@@ -0,0 +1,19 @@
+// @ts-check
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Where a package is installed for the app: its package.json in the nearest node_modules, as Node and the app's
+ * sidecar resolve it. Read directly rather than through require.resolve, which only finds package.json when the
+ * package exports it.
+ * @param {string} cwd
+ * @param {string} name
+ * @returns {string | null}
+ */
+export function findPackage(cwd, name) {
+  for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) {
+    const manifest = path.join(dir, 'node_modules', name, 'package.json');
+    if (existsSync(manifest)) return manifest;
+    if (path.dirname(dir) === dir) return null;
+  }
+}

package/cli/process-io.mjs

@@ -0,0 +1,163 @@
+// @ts-check
+// The CliIo of a real run: this process's directory, environment and streams, and child processes.
+import { execFile, spawn } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { constants } from 'node:os';
+import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { DOTNET_DOWNLOAD, MIN_DOTNET, NODE_DOWNLOAD, NODE_RANGE } from './info.mjs';
+import { Interrupted, colorSupport, printError } from './terminal.mjs';
+
+const windows = process.platform === 'win32';
+
+/** What to install when a command the CLI runs is missing. */
+const INSTALL = new Map([
+  ['dotnet', `Install the .NET SDK, ${MIN_DOTNET}.0 or newer: ${DOTNET_DOWNLOAD}`],
+  ['npm', `Install a Node.js release that matches ${NODE_RANGE}, which includes npm: ${NODE_DOWNLOAD}`],
+]);
+
+/**
+ * The exit code for a process that ended with `code` or by `signal`: 128 + the signal number, as shells report it.
+ * @param {number | null} code
+ * @param {NodeJS.Signals | null} signal
+ */
+const exitCode = (code, signal) => code ?? (signal ? 128 + (constants.signals[signal] ?? 0) : 0);
+
+/**
+ * Whether `file` is a file. False as well when it cannot be looked at, as in a PATH folder the user may not read, which
+ * cmd.exe skips.
+ * @param {string} file
+ */
+function isAFile(file) {
+  try {
+    return statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Where cmd.exe would find `command` on the PATH in `env`: the first directory with `command` plus one of the PATHEXT
+ * extensions. Null when no directory has it. Variable names match in any case, as on Windows.
+ * @param {string} command
+ * @param {Record<string, string | undefined>} env
+ * @param {(file: string) => boolean} [isFile]
+ * @returns {string | null}
+ */
+export function findOnWindowsPath(command, env, isFile = isAFile) {
+  /** @param {string} name */
+  const variable = (name) => Object.entries(env).find(([key]) => key.toUpperCase() === name)?.[1] ?? '';
+  const extensions = (variable('PATHEXT') || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean);
+  for (const folder of variable('PATH').split(';')) {
+    const directory = folder.trim().replace(/^"(.*)"$/, '$1');
+    if (!directory) continue;
+    for (const extension of extensions) {
+      const file = path.win32.join(directory, `${command}${extension.toLowerCase()}`);
+      if (isFile(file)) return file;
+    }
+  }
+  return null;
+}
+
+/**
+ * The command line that runs a .cmd file with `args` through cmd.exe: the file in quotes, and each argument as it is,
+ * or in quotes when it has more than letters, digits and path characters. Node joins `args` with spaces when it starts
+ * a shell, unquoted (DEP0190), so the CLI passes this one string instead. For the CLI's own arguments (npm install):
+ * cmd.exe still expands %VARIABLES% in quotes.
+ * @param {string} file
+ * @param {string[]} args
+ */
+export function windowsCommandLine(file, args) {
+  return [`"${file}"`, ...args.map((arg) => (/^[\w@+=:,./\\-]+$/.test(arg) ? arg : `"${arg}"`))].join(' ');
+}
+
+/** @returns {import('./main.mjs').CliIo} */
+export function processIo() {
+  /** @type {import('./main.mjs').CliIo} */
+  const io = {
+    cwd: process.cwd(),
+    env: process.env,
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+    color: { stdout: colorSupport(process.env, process.stdout.isTTY), stderr: colorSupport(process.env, process.stderr.isTTY) },
+    spawn: ({ command, args, cwd, env, stdout }) =>
+      new Promise((resolve) => {
+        /** @type {import('node:child_process').StdioOptions} */
+        const stdio = ['inherit', stdout === 'stderr' ? 2 : 'inherit', 'inherit'];
+        const notInstalled = () =>
+          printError(io, `netjes: ${command} is not installed, or not on PATH. ${INSTALL.get(command) ?? ''}`.trimEnd());
+        // npm and npx are .cmd files on Windows, which Node starts only through cmd.exe. cmd.exe would report a missing
+        // one in a message of its own, with exit code 9009, so the CLI looks it up first, as cmd.exe does.
+        const shim = windows && command.startsWith('np') ? findOnWindowsPath(command, env) : undefined;
+        if (shim === null) {
+          notInstalled();
+          resolve(127);
+          return;
+        }
+        const child = shim
+          ? spawn(windowsCommandLine(shim, args), { cwd, env, stdio, shell: true })
+          : spawn(command, args, { cwd, env, stdio });
+        const forward = (/** @type {NodeJS.Signals} */ signal) => child.kill(signal);
+        process.on('SIGINT', forward);
+        process.on('SIGTERM', forward);
+        const done = (/** @type {number} */ code) => {
+          process.off('SIGINT', forward);
+          process.off('SIGTERM', forward);
+          resolve(code);
+        };
+        child.on('error', (error) => {
+          if (/** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT' && existsSync(cwd)) notInstalled();
+          else printError(io, `netjes: could not run ${command}: ${error.message}`);
+          done(127);
+        });
+        child.on('exit', (code, signal) => done(exitCode(code, signal)));
+      }),
+    capture: ({ command, args, cwd, env }) =>
+      new Promise((resolve) => {
+        execFile(command, args, { cwd, env }, (error, stdout, stderr) => {
+          if (!error) return resolve({ code: 0, stdout, stderr });
+          const code = typeof error.code === 'number' ? error.code : error.code === 'ENOENT' ? 127 : error.signal ? exitCode(null, error.signal) : 1;
+          resolve({ code, stdout, stderr });
+        });
+      }),
+  };
+  io.portFree = (port, host = '127.0.0.1') =>
+    new Promise((resolve) => {
+      const server = createServer();
+      server.once('error', () => resolve(false));
+      server.listen({ port, host, exclusive: true }, () => server.close(() => resolve(true)));
+    });
+  // Only with a terminal on both ends; in a script or CI a missing answer is an error instead of a hang.
+  if (process.stdin.isTTY && process.stdout.isTTY) io.prompt = terminalPrompt(process.stdin, process.stdout);
+  return io;
+}
+
+/**
+ * A prompt on a terminal: asks on `output`, reads the answer from `input`. Resolves to null when the input ends
+ * (Ctrl+D), and rejects with Interrupted on Ctrl+C.
+ * @param {NodeJS.ReadableStream} input
+ * @param {NodeJS.WritableStream} output
+ * @returns {NonNullable<import('./main.mjs').CliIo['prompt']>}
+ */
+export function terminalPrompt(input, output) {
+  return async (question) => {
+    const readline = createInterface({ input, output, terminal: true });
+    // Cancelling the question ends the line it is on, so that what comes next starts on a line of its own.
+    const cancel = new AbortController();
+    let interrupted = false;
+    readline.once('SIGINT', () => {
+      interrupted = true;
+      cancel.abort();
+    });
+    readline.once('close', () => cancel.abort());
+    try {
+      return await readline.question(question, { signal: cancel.signal });
+    } catch {
+      if (interrupted) throw new Interrupted();
+      return null;
+    } finally {
+      readline.close();
+    }
+  };
+}

package/cli/routes.mjs

@@ -0,0 +1,31 @@
+// @ts-check
+
+/**
+ * @typedef {{ pattern: string; file: string; loader: boolean; action: boolean; props: string | null; cached: boolean; authorized: boolean }} RouteRow
+ * @typedef {{ method: string; route: string }} EndpointRow
+ * @typedef {{ kind: string; message: string; files: string[] }} RouteWarning
+ */
+
+/** @param {string[][]} rows */
+function table(rows) {
+  const widths = rows[0]?.map((_, column) => Math.max(...rows.map((row) => row[column]?.length ?? 0))) ?? [];
+  return rows.map((row) => row.map((cell, column) => (column === row.length - 1 ? cell : cell.padEnd(widths[column] ?? 0))).join('  ').trimEnd());
+}
+
+const yes = (/** @type {boolean} */ value) => (value ? 'yes' : '');
+
+/**
+ * The route table the app reported (`NETJES_COMMAND=routes`), as text, with the app's route warnings after it.
+ * @param {{ routes: RouteRow[]; endpoints: EndpointRow[]; warnings?: RouteWarning[] }} report
+ */
+export function formatRoutes(report) {
+  const pages = table([
+    ['Pattern', 'File', 'Loader', 'Action', 'Props', 'Cached', 'Auth'],
+    ...report.routes.map((r) => [r.pattern, r.file, yes(r.loader), yes(r.action), r.props ?? '', yes(r.cached), yes(r.authorized)]),
+  ]);
+  const endpoints = report.endpoints.length
+    ? ['', 'Endpoints', ...table(report.endpoints.map((e) => [e.method, e.route]))]
+    : [];
+  const warnings = report.warnings?.length ? ['', 'Warnings', ...report.warnings.map((w) => `  ${w.message}`)] : [];
+  return [...pages, ...endpoints, ...warnings].join('\n') + '\n';
+}

package/cli/scaffold.mjs

@@ -0,0 +1,193 @@
+// @ts-check
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = fileURLToPath(new URL('..', import.meta.url));
+const TEMPLATE = path.join(PACKAGE_ROOT, 'template');
+/** Skills for coding agents, copied to `.claude/skills/` in an app as they are. */
+const SKILLS = path.join(PACKAGE_ROOT, 'skills');
+/**
+ * Template files stored under another name: ones npm would drop or rename when publishing, and the app's guides for
+ * coding agents, which agents working on Netjes would otherwise apply to the template.
+ */
+const RENAMED = new Map([
+  ['_gitignore', '.gitignore'],
+  ['_gitattributes', '.gitattributes'],
+  ['_AGENTS.md', 'AGENTS.md'],
+  ['_CLAUDE.md', 'CLAUDE.md'],
+]);
+
+/**
+ * The ASCII words in a name, accents dropped (Café gives Cafe).
+ * @param {string} value
+ */
+function words(value) {
+  return value
+    .normalize('NFD')
+    .replace(/\p{M}/gu, '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean);
+}
+
+/**
+ * Names for a project, from its directory or `--name`: a C# identifier, an npm package name, a title.
+ * @param {string} name
+ */
+export function projectNames(name) {
+  const parts = words(name);
+  const pascal = parts.map((w) => w[0]?.toUpperCase() + w.slice(1)).join('') || 'App';
+  return {
+    dotnet: /^[0-9]/.test(pascal) ? `App${pascal}` : pascal,
+    npm: parts.map((w) => w.toLowerCase()).join('-') || 'app',
+    title: parts.map((w) => w[0]?.toUpperCase() + w.slice(1)).join(' ') || 'App',
+  };
+}
+
+/** A name `--name` accepts as it is: what the template can use as a file name, a namespace and an assembly name. */
+const DOTNET_NAME = /^[A-Za-z][A-Za-z0-9]*$/;
+
+/** The C# reserved keywords, which cannot name a namespace (CS1001). */
+const CSHARP_KEYWORDS = new Set(
+  ('abstract as base bool break byte case catch char checked class const continue decimal default delegate do double ' +
+    'else enum event explicit extern false finally fixed float for foreach goto if implicit in int interface internal ' +
+    'is lock long namespace new null object operator out override params private protected public readonly ref return ' +
+    'sbyte sealed short sizeof stackalloc static string struct switch this throw true try typeof uint ulong unchecked ' +
+    'unsafe ushort using virtual void volatile while').split(' '),
+);
+
+// Types the template's C# uses by their simple names. A root namespace of the same name hides the type from that code,
+// and the build fails (CS0118, CS0234); Program is the class the top-level statements in Program.cs make (CS0101).
+const TEMPLATE_TYPES = new Set([
+  'Program',
+  'SiteProps',
+  'Page',
+  'ServerAction',
+  'WebApplication',
+  'ValueTask',
+  'DateTimeOffset',
+  'TimeProvider',
+  'IEndpointRouteBuilder',
+  'FromFormAttribute',
+]);
+
+/**
+ * The names for a new app in `target`, or a message saying why there are none: `--name` as given when it is a .NET
+ * project name, else derived from the folder name; neither may clash with the template's own type names or with a
+ * package the app depends on (npm refuses to install a package into one of the same name).
+ * @param {string} target
+ * @param {string | undefined} name
+ * @returns {Promise<{ names: ReturnType<typeof projectNames> } | { problem: string }>}
+ */
+export async function namesFor(target, name) {
+  if (name !== undefined && !DOTNET_NAME.test(name)) {
+    return {
+      problem: `--name '${name}' is not a valid .NET project name; use letters and digits, starting with a letter, e.g. --name ${projectNames(name).dotnet}`,
+    };
+  }
+  if (name !== undefined && CSHARP_KEYWORDS.has(name)) {
+    return { problem: `--name '${name}' is a C# keyword; choose another name, e.g. --name ${projectNames(name).dotnet}` };
+  }
+  if (name === undefined && words(path.basename(target)).length === 0) {
+    return { problem: `cannot make a project name from the folder name '${path.basename(target)}'; pass --name <Name>` };
+  }
+  const names = name === undefined ? projectNames(path.basename(target)) : { ...projectNames(name), dotnet: name };
+  if (TEMPLATE_TYPES.has(names.dotnet)) {
+    return { problem: `'${names.dotnet}' is the name of a type the app's code uses; choose another name with --name` };
+  }
+  const manifest = JSON.parse(await readFile(path.join(TEMPLATE, 'package.json'), 'utf8'));
+  if (Object.hasOwn({ ...manifest.dependencies, ...manifest.devDependencies }, names.npm)) {
+    return { problem: `the app's npm name would be '${names.npm}', a package it depends on; choose another folder name or --name` };
+  }
+  return { names };
+}
+
+/** The repository root when this package runs from a Netjes checkout, else null. */
+export function checkoutRoot() {
+  const root = path.resolve(PACKAGE_ROOT, '..', '..');
+  return existsSync(path.join(root, 'src', 'Netjes', 'Netjes.csproj')) ? root : null;
+}
+
+/** @returns {Promise<string>} */
+export async function packageVersion() {
+  const manifest = JSON.parse(await readFile(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+  return String(manifest.version);
+}
+
+/**
+ * Fills the name placeholders of a template file: `__NAME__` (the C# name), `__name__` (the npm name), `__TITLE__`.
+ * @param {string} text
+ * @param {ReturnType<typeof projectNames>} names
+ */
+export function fillNames(text, names) {
+  return text.replaceAll('__NAME__', names.dotnet).replaceAll('__name__', names.npm).replaceAll('__TITLE__', names.title);
+}
+
+/** @param {string} file a path in the template @returns {Promise<string>} */
+export const readTemplate = (file) => readFile(path.join(TEMPLATE, file), 'utf8');
+
+/** @param {string} from @param {string} to */
+const toPosix = (from, to) => path.relative(from, to).split(path.sep).join('/');
+
+/**
+ * Copies the template into `target`, filling in the names and how Netjes is referenced: the local checkout
+ * (ProjectReference + a `file:` dependency) or the published packages.
+ * @param {string} target
+ * @param {{ name?: string; packages?: boolean }} options
+ */
+export async function scaffold(target, options = {}) {
+  const found = await namesFor(target, options.name);
+  if ('problem' in found) throw new Error(found.problem);
+  const { names } = found;
+  const existing = await stat(target).catch(() => null);
+  if (existing && !existing.isDirectory()) throw new Error(`${target} is a file, not a folder`);
+  if (existing && (await readdir(target)).length > 0) throw new Error(`${target} already exists and is not empty; choose a new folder`);
+
+  const version = await packageVersion();
+  const root = options.packages ? null : checkoutRoot();
+  const references = root
+    ? `  <Import Project="${toPosix(target, root)}/src/Netjes/build/Netjes.targets" />\n\n` +
+      `  <ItemGroup>\n    <ProjectReference Include="${toPosix(target, root)}/src/Netjes/Netjes.csproj" />\n  </ItemGroup>\n`
+    : // Exact versions: the C# and npm halves speak one payload protocol, and a bare NuGet version is a minimum.
+      `  <ItemGroup>\n    <PackageReference Include="Netjes" Version="[${version}]" />\n  </ItemGroup>\n`;
+  const dependency = root ? `file:${toPosix(target, path.join(root, 'packages', 'netjes'))}` : version;
+
+  /** @param {string} text */
+  const fill = (text) =>
+    fillNames(text.replaceAll('<!--NETJES_REFERENCES-->\n', references).replaceAll('__NETJES_DEPENDENCY__', dependency), names);
+
+  /** @param {string} from @param {string} to */
+  async function copy(from, to) {
+    await mkdir(to, { recursive: true });
+    for (const entry of await readdir(from)) {
+      const source = path.join(from, entry);
+      const destination = path.join(to, fill(RENAMED.get(entry) ?? entry));
+      if ((await stat(source)).isDirectory()) await copy(source, destination);
+      else await writeFile(destination, fill(await readFile(source, 'utf8')));
+    }
+  }
+
+  await copy(TEMPLATE, target);
+  for (const skill of await skillFiles()) {
+    await mkdir(path.dirname(path.join(target, skill.path)), { recursive: true });
+    await writeFile(path.join(target, skill.path), skill.text);
+  }
+  return { names, mode: root ? 'checkout' : 'packages' };
+}
+
+/**
+ * The skill pack's files, by their path in an app (`.claude/skills/netjes/SKILL.md`, posix).
+ * @returns {Promise<{ path: string; text: string }[]>}
+ */
+export async function skillFiles() {
+  const entries = await readdir(SKILLS, { recursive: true, withFileTypes: true });
+  const files = entries.filter((entry) => entry.isFile()).map((entry) => path.join(entry.parentPath, entry.name));
+  return Promise.all(
+    files.sort().map(async (file) => ({
+      path: ['.claude', 'skills', ...path.relative(SKILLS, file).split(path.sep)].join('/'),
+      text: await readFile(file, 'utf8'),
+    })),
+  );
+}

package/cli/suggest.mjs

@@ -0,0 +1,50 @@
+// @ts-check
+
+/**
+ * Edit distance with adjacent transpositions (optimal string alignment), so `nwe` is one edit from `new`.
+ * @param {string} a
+ * @param {string} b
+ */
+function distance(a, b) {
+  /** @type {number[][]} */
+  const d = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const row = /** @type {number[]} */ (d[i]);
+      const above = /** @type {number[]} */ (d[i - 1]);
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      row[j] = Math.min(/** @type {number} */ (above[j]) + 1, /** @type {number} */ (row[j - 1]) + 1, /** @type {number} */ (above[j - 1]) + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        row[j] = Math.min(/** @type {number} */ (row[j]), /** @type {number} */ (d[i - 2]?.[j - 2]) + 1);
+      }
+    }
+  }
+  return /** @type {number} */ (d[a.length]?.[b.length]);
+}
+
+/**
+ * The candidate someone most likely meant by `input`, or undefined: the same word in another case, a close spelling,
+ * or the only candidate that starts with or contains it.
+ * @param {string} input
+ * @param {Iterable<string>} candidates
+ * @returns {string | undefined}
+ */
+export function suggest(input, candidates) {
+  const typed = input.toLowerCase();
+  const all = [...candidates];
+  const exact = all.find((candidate) => candidate.toLowerCase() === typed);
+  if (exact) return exact;
+
+  const limit = typed.length <= 4 ? 1 : 2;
+  const close = all
+    .map((candidate) => ({ candidate, edits: distance(typed, candidate.toLowerCase()) }))
+    .filter(({ edits }) => edits <= limit)
+    .sort((a, b) => a.edits - b.edits);
+  if (close[0]) return close[0].candidate;
+
+  if (typed.length < 2) return undefined;
+  const starting = all.filter((candidate) => candidate.toLowerCase().startsWith(typed));
+  if (starting.length === 1) return starting[0];
+  const containing = typed.length >= 3 ? all.filter((candidate) => candidate.toLowerCase().includes(typed)) : [];
+  return containing.length === 1 ? containing[0] : undefined;
+}

package/cli/terminal.mjs

@@ -0,0 +1,40 @@
+// @ts-check
+// Colour for a terminal that wants it: never in pipes or files, never with NO_COLOR (https://no-color.org).
+
+/**
+ * Whether to colour a stream: NO_COLOR turns it off, FORCE_COLOR on (or off with 0 or false), a dumb terminal off;
+ * otherwise only when the stream is a terminal.
+ * @param {Record<string, string | undefined>} env
+ * @param {boolean | undefined} tty
+ */
+export function colorSupport(env, tty) {
+  if (env.NO_COLOR) return false;
+  const force = env.FORCE_COLOR;
+  if (force !== undefined && force !== '') return force !== '0' && force !== 'false';
+  if (env.TERM === 'dumb') return false;
+  return tty === true;
+}
+
+/**
+ * Styles that only apply when `on`.
+ * @param {boolean} on
+ */
+export function paint(on) {
+  /** @param {number} open @param {number} close */
+  const style = (open, close) => (/** @type {string} */ text) => (on ? `\u001b[${open}m${text}\u001b[${close}m` : text);
+  return { bold: style(1, 22), dim: style(2, 22), red: style(31, 39), green: style(32, 39), yellow: style(33, 39), cyan: style(36, 39) };
+}
+
+/**
+ * Writes one message to stderr, its `netjes …:` label in red when stderr takes colour.
+ * @param {import('./main.mjs').CliIo} io
+ * @param {string} message
+ */
+export function printError(io, message) {
+  const colon = message.indexOf(': ');
+  const { red } = paint(io.color?.stderr === true);
+  io.stderr(colon > 0 ? `${red(message.slice(0, colon + 1))}${message.slice(colon + 1)}\n` : `${red(message)}\n`);
+}
+
+/** Ctrl+C at a prompt. The command stops there, with exit code 130, as a shell reports SIGINT. */
+export class Interrupted extends Error {}