create-elnop-stack 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# create-elnop-stack
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Creates a project from one of the [elnop-stacks](https://github.com/Elnop/elnop-stacks) templates and lets you drop the parts you do not need. Whatever you pick, the project passes `npm run check` on the first run.
+
+```sh
+npm create elnop-stack my-app
+```
+
+Node 26 is required, like the templates.
+
+## Stacks and options
+
+| Stack | Template | Options |
+|---|---|---|
+| `vite` | [template-vite](https://github.com/Elnop/template-vite) | `example`, `zustand`, `component-tests`, `e2e`, `claude-hook`, `ci` |
+| `fastify` | [template-fastify](https://github.com/Elnop/template-fastify) | `example`, `swagger`, `database`, `claude-hook`, `ci` |
+
+`example` keeps the todo list. Without it you get the same structure with empty `src/features/` and `src/shared-features/` folders. On vite, `App.tsx` then only shows the project name, and zustand can only be removed together with the example, since the example uses it. On fastify, `buildApp.ts` only creates the server, and the Swagger UI, if kept, is titled with the project name.
+
+On fastify, `database` keeps `node:sqlite` and the `DATABASE_PATH` variable. Without it, the example keeps its todos in a `Map`: `todosQueries.ts` has the same functions, so the services and the routes do not change. Without `swagger`, `@fastify/swagger` and `openapi-types` stay installed, because `fastify-type-provider-zod` needs them.
+
+The CLI also asks whether to run `git init` and `npm install`. Without git, the `prepare` script that installs the pre-commit hook is removed. The next steps tell you how to set it up later.
+
+## Without questions
+
+Every option has a flag, `--<option>` or `--no-<option>`. `--yes` takes the default for every question left:
+
+```sh
+npm create elnop-stack my-app -- --stack vite --no-example --no-e2e --yes
+```
+
+A preset file holds the same answers, and flags override it:
+
+```json
+{ "stack": "vite", "git": true, "install": true, "options": { "example": false, "e2e": false } }
+```
+
+```sh
+npm create elnop-stack my-app -- --preset minimal.json --yes
+```
+
+`npm create elnop-stack -- --help` lists the stacks and their options.
+
+## How it works
+
+Each version of the package downloads every template at the commit its submodule points to in elnop-stacks (`dist/stackRefs.json`, written at build time), so a given version always produces the same project. The options are described in `src/stacks/viteStack.ts` and `src/stacks/fastifyStack.ts`: files to remove, text to replace in the docs and configs, scripts and dependencies to drop, and files to copy from `overlays/`. A replacement whose text cannot be found stops the CLI with the file name and the missing text, rather than producing a half-edited project.
+
+## Developing
+
+From the root of elnop-stacks:
+
+```sh
+npm install
+node create-elnop-stack/src/cli.ts ../my-app --local
+npm run matrix
+```
+
+`--local` copies the templates from the submodules, local changes included. `npm run matrix` creates a project for every combination of options (options marked `independent` are switched on and off without being crossed with the others), installs it, then runs `npm run check` and `npm test`. `--e2e` adds `npm run e2e` (use `--jobs 1`, Playwright needs port 4173), `--keep` keeps the projects in `.matrix/`.

package/dist/CliTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/ScaffoldConfig.js

@@ -0,0 +1,5 @@
+import { fileURLToPath } from 'node:url';
+export const PROJECT_NAME_TOKEN = '__PROJECT_NAME__';
+export const OVERLAYS_ROOT = fileURLToPath(new URL('../overlays', import.meta.url));
+export const LOCAL_ROOT = fileURLToPath(new URL('../..', import.meta.url));
+export const STACK_REFS_URL = new URL('stackRefs.json', import.meta.url);

package/dist/StackTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/applyFileEdit.js

@@ -0,0 +1,38 @@
+function headingLevel(line) {
+    return /^(#+) /u.exec(line)?.[1]?.length ?? 0;
+}
+function dropSection(text, heading) {
+    const lines = text.split('\n');
+    const start = lines.indexOf(heading);
+    if (start === -1)
+        throw new Error(`section "${heading}" not found`);
+    const level = headingLevel(heading);
+    const length = lines.slice(start + 1).findIndex((line) => {
+        const lineLevel = headingLevel(line);
+        return lineLevel > 0 && lineLevel <= level;
+    });
+    lines.splice(start, length === -1 ? lines.length - start : length + 1);
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+function dropLines(text, needle) {
+    const lines = text.split('\n');
+    const kept = lines.filter((line) => !line.includes(needle));
+    if (kept.length === lines.length)
+        throw new Error(`no line contains "${needle}"`);
+    return kept.join('\n').replaceAll(/\n{3,}/gu, '\n\n');
+}
+function replaceText(text, search, replacement, all) {
+    const count = text.split(search).length - 1;
+    if (all && count === 0)
+        throw new Error(`"${search}" not found`);
+    if (!all && count !== 1)
+        throw new Error(`expected "${search}" once, found it ${count} times`);
+    return all ? text.replaceAll(search, () => replacement) : text.replace(search, () => replacement);
+}
+export function applyFileEdit(text, edit) {
+    if ('replace' in edit)
+        return replaceText(text, edit.replace, edit.with, edit.all === true);
+    if ('dropLines' in edit)
+        return dropLines(text, edit.dropLines);
+    return dropSection(text, edit.dropSection);
+}

package/dist/applyStackChanges.js

@@ -0,0 +1,96 @@
+import { cpSync, existsSync, globSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { applyFileEdit } from './applyFileEdit.js';
+import { errorMessage } from './errorMessage.js';
+import { isRecord } from './isRecord.js';
+import { PROJECT_NAME_TOKEN } from './ScaffoldConfig.js';
+function matches(change, answers) {
+    return Object.entries(change.when).every(([id, value]) => answers[id] === value);
+}
+function removePaths(dir, patterns) {
+    for (const pattern of patterns) {
+        const found = globSync(pattern, { cwd: dir });
+        if (found.length === 0)
+            throw new Error(`nothing matches ${pattern}`);
+        for (const path of found)
+            rmSync(join(dir, path), { recursive: true, force: true });
+    }
+}
+function editFiles(dir, edits, projectName) {
+    for (const edit of edits) {
+        const path = join(dir, edit.file);
+        if (!existsSync(path))
+            throw new Error(`${edit.file} does not exist`);
+        const named = 'with' in edit ? { ...edit, with: edit.with.replaceAll(PROJECT_NAME_TOKEN, projectName) } : edit;
+        try {
+            writeFileSync(path, applyFileEdit(readFileSync(path, 'utf8'), named));
+        }
+        catch (error) {
+            throw new Error(`${edit.file}: ${errorMessage(error)}`, { cause: error });
+        }
+    }
+}
+function sortedRecord(record) {
+    return Object.fromEntries(Object.entries(record).toSorted(([a], [b]) => a.localeCompare(b)));
+}
+export function updatePackageJson(dir, update) {
+    const path = join(dir, 'package.json');
+    const pkg = JSON.parse(readFileSync(path, 'utf8'));
+    if (!isRecord(pkg))
+        throw new Error('package.json is not an object');
+    update(pkg);
+    writeFileSync(path, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+function updatePackage(dir, change) {
+    updatePackageJson(dir, (pkg) => {
+        for (const script of change.scripts ?? []) {
+            if (pkg.scripts?.[script] === undefined)
+                throw new Error(`package.json has no script ${script}`);
+            delete pkg.scripts[script];
+        }
+        for (const name of change.dependencies ?? []) {
+            const field = pkg.dependencies?.[name] === undefined ? pkg.devDependencies : pkg.dependencies;
+            if (field?.[name] === undefined)
+                throw new Error(`package.json has no dependency ${name}`);
+            delete field[name];
+        }
+        if (change.devDependencies !== undefined)
+            pkg.devDependencies = sortedRecord({ ...pkg.devDependencies, ...change.devDependencies });
+    });
+}
+function copyOverlay(from, to, projectName) {
+    for (const entry of readdirSync(from)) {
+        const source = join(from, entry);
+        const target = join(to, entry);
+        if (statSync(source).isDirectory()) {
+            mkdirSync(target, { recursive: true });
+            copyOverlay(source, target, projectName);
+        }
+        else {
+            cpSync(source, target);
+            writeFileSync(target, readFileSync(target, 'utf8').replaceAll(PROJECT_NAME_TOKEN, projectName));
+        }
+    }
+}
+function keepFolders(dir, folders) {
+    for (const folder of folders) {
+        const path = join(dir, folder);
+        mkdirSync(path, { recursive: true });
+        if (readdirSync(path).length === 0)
+            writeFileSync(join(path, '.gitkeep'), '');
+    }
+}
+export function applyStackChanges(dir, stack, answers, overlaysRoot, projectName) {
+    for (const change of stack.changes.filter((candidate) => matches(candidate, answers))) {
+        removePaths(dir, change.remove ?? []);
+        editFiles(dir, change.edits ?? [], projectName);
+        if (change.scripts !== undefined || change.dependencies !== undefined || change.devDependencies !== undefined)
+            updatePackage(dir, change);
+        if (change.overlay !== undefined)
+            copyOverlay(join(overlaysRoot, stack.id, change.overlay), dir, projectName);
+        keepFolders(dir, change.keep ?? []);
+    }
+    updatePackageJson(dir, (pkg) => {
+        pkg['name'] = projectName;
+    });
+}

package/dist/cli.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { cancel, confirm, intro, isCancel, log, note, outro, select, spinner, text } from '@clack/prompts';
+import { errorMessage } from './errorMessage.js';
+import { readArgs } from './readArgs.js';
+import { readStackRefs } from './readStackRefs.js';
+import { resolveAnswers } from './resolveAnswers.js';
+import { scaffoldProject } from './scaffoldProject.js';
+import { LOCAL_ROOT } from './ScaffoldConfig.js';
+import { stacks } from './stacks/stacksConfig.js';
+const PROJECT_NAME = /^[a-z0-9][a-z0-9._-]*$/u;
+const USAGE = `Usage: npm create elnop-stack [dir] -- [flags]
+
+  --stack <id>       ${stacks.map((stack) => stack.id).join(', ')}
+  --preset <file>    JSON file with stack, options, git and install
+  --yes, -y          take the default of every question left
+  --no-git           skip git init (the pre-commit hook is dropped)
+  --no-install       skip npm install
+  --local            copy the templates from this elnop-stacks checkout
+
+Each stack option has a flag: --<option> or --no-<option>.
+${stacks.map((stack) => `  ${stack.id}: ${stack.options.map((option) => option.id).join(', ')}`).join('\n')}`;
+function stopCancelled() {
+    cancel('Cancelled.');
+    process.exit(1);
+}
+function validateDir(value) {
+    if (value === undefined || value === '')
+        return 'Give a folder name.';
+    if (!PROJECT_NAME.test(basename(resolve(value))))
+        return 'Use lowercase letters, digits, dots, dashes and underscores.';
+    if (existsSync(value) && readdirSync(value).length > 0)
+        return `${value} is not empty.`;
+    return undefined;
+}
+async function pickDir(given, yes) {
+    if (given !== undefined || yes) {
+        const error = validateDir(given);
+        if (error !== undefined)
+            throw new Error(error);
+        return given ?? '';
+    }
+    const value = await text({ message: 'Project folder', placeholder: 'my-app', validate: validateDir });
+    return isCancel(value) ? stopCancelled() : value;
+}
+async function pickStack(id, yes) {
+    if (id !== undefined) {
+        const found = stacks.find((stack) => stack.id === id);
+        if (found === undefined)
+            throw new Error(`Unknown stack ${id}. Choose one of: ${stacks.map((stack) => stack.id).join(', ')}`);
+        return found;
+    }
+    if (yes)
+        throw new Error('--yes needs --stack');
+    const value = await select({ message: 'Stack', options: stacks.map((stack) => ({ value: stack, label: stack.label })) });
+    return isCancel(value) ? stopCancelled() : value;
+}
+async function askOption(option) {
+    const value = await confirm({ message: option.message, initialValue: option.default });
+    return isCancel(value) ? stopCancelled() : value;
+}
+async function askYesNo(given, yes, message) {
+    if (given !== undefined)
+        return given;
+    if (yes)
+        return true;
+    const value = await confirm({ message, initialValue: true });
+    return isCancel(value) ? stopCancelled() : value;
+}
+function templateSource(stack, local) {
+    if (local)
+        return { kind: 'local', root: LOCAL_ROOT };
+    const ref = readStackRefs().get(stack.id);
+    if (ref === undefined)
+        throw new Error(`No template commit recorded for ${stack.id}: run from a published build or pass --local`);
+    return { kind: 'github', ref };
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const first = readArgs(argv, undefined);
+    if (first.help) {
+        process.stdout.write(`${USAGE}\n`);
+        return;
+    }
+    intro('create-elnop-stack');
+    const dir = await pickDir(first.dir, first.yes);
+    const stack = await pickStack(first.stack, first.yes);
+    const args = readArgs(argv, stack);
+    const answers = await resolveAnswers(stack.options, args.options, args.yes ? undefined : askOption);
+    const git = await askYesNo(args.git, args.yes, 'Run git init?');
+    const install = await askYesNo(args.install, args.yes, 'Run npm install?');
+    const existed = existsSync(dir);
+    const progress = spinner();
+    progress.start('Creating the project');
+    try {
+        await scaffoldProject({ dir: resolve(dir), projectName: basename(resolve(dir)), stack, answers, source: templateSource(stack, args.local), git, install }, (message) => progress.message(message));
+    }
+    catch (error) {
+        progress.error('Failed');
+        if (existed)
+            for (const entry of readdirSync(dir))
+                rmSync(resolve(dir, entry), { recursive: true, force: true });
+        else
+            rmSync(dir, { recursive: true, force: true });
+        throw error;
+    }
+    progress.stop(`Created ${dir}`);
+    note([`cd ${dir}`, ...(install ? [] : ['npm install']), ...(git ? [] : ['git init && git config core.hooksPath .githooks']), ...stack.nextSteps(answers)].join('\n'), 'Next steps');
+    outro('Run npm run check before each commit.');
+}
+try {
+    await main();
+}
+catch (error) {
+    log.error(errorMessage(error));
+    process.exit(1);
+}

package/dist/errorMessage.js

@@ -0,0 +1,3 @@
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/fetchTemplate.js

@@ -0,0 +1,21 @@
+import { cpSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { downloadTemplate } from 'giget';
+import { runCommand } from './runCommand.js';
+function copyWorkingTree(from, to) {
+    const files = runCommand('git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z'], from, true).split('\0').filter(Boolean);
+    for (const file of files) {
+        const source = join(from, file);
+        if (!existsSync(source))
+            continue;
+        mkdirSync(dirname(join(to, file)), { recursive: true });
+        cpSync(source, join(to, file));
+    }
+}
+export async function fetchTemplate(stack, dir, source) {
+    if (source.kind === 'local') {
+        copyWorkingTree(join(source.root, stack.submodule), dir);
+        return;
+    }
+    await downloadTemplate(`github:${stack.repository}#${source.ref}`, { dir, silent: true });
+}

package/dist/isRecord.js

@@ -0,0 +1,3 @@
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/matrixCombinations.js

@@ -0,0 +1,13 @@
+function satisfiesRequirements(options, answers) {
+    return options.every((option) => !answers[option.id] || Object.entries(option.requires ?? {}).every(([id, value]) => answers[id] === value));
+}
+export function matrixCombinations(options) {
+    const crossed = options.filter((option) => option.independent !== true);
+    const independent = options.filter((option) => option.independent === true);
+    let combinations = [{}];
+    for (const option of crossed)
+        combinations = combinations.flatMap((answers) => [true, false].map((value) => ({ ...answers, [option.id]: value })));
+    return combinations
+        .filter((answers) => satisfiesRequirements(options, answers))
+        .map((answers, index) => ({ ...answers, ...Object.fromEntries(independent.map((option, position) => [option.id, Math.floor(index / 2 ** position) % 2 === 0])) }));
+}

package/dist/readArgs.js

@@ -0,0 +1,56 @@
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { isRecord } from './isRecord.js';
+const BASE_OPTIONS = {
+    stack: { type: 'string' },
+    preset: { type: 'string' },
+    yes: { type: 'boolean', short: 'y' },
+    local: { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+    git: { type: 'boolean' },
+    install: { type: 'boolean' },
+};
+function booleanEntries(value) {
+    if (!isRecord(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === 'boolean'));
+}
+function readPreset(path) {
+    if (typeof path !== 'string')
+        return { options: {} };
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (!isRecord(parsed))
+        throw new Error(`${path} is not a JSON object`);
+    const { stack, git, install } = parsed;
+    return {
+        ...(typeof stack === 'string' ? { stack } : {}),
+        ...(typeof git === 'boolean' ? { git } : {}),
+        ...(typeof install === 'boolean' ? { install } : {}),
+        options: booleanEntries(parsed['options']),
+    };
+}
+function optionalBoolean(value, fallback) {
+    return typeof value === 'boolean' ? value : fallback;
+}
+export function readArgs(argv, stack) {
+    const stackOptions = Object.fromEntries((stack?.options ?? []).map((option) => [option.id, { type: 'boolean' }]));
+    const { values, positionals } = parseArgs({ args: argv, options: { ...BASE_OPTIONS, ...stackOptions }, allowPositionals: true, allowNegative: true, strict: stack !== undefined });
+    const preset = readPreset(values['preset']);
+    const options = { ...preset.options };
+    for (const option of stack?.options ?? []) {
+        const value = values[option.id];
+        if (typeof value === 'boolean')
+            options[option.id] = value;
+    }
+    const stackId = values['stack'];
+    return {
+        dir: positionals[0],
+        stack: typeof stackId === 'string' ? stackId : preset.stack,
+        yes: values['yes'] === true,
+        local: values['local'] === true,
+        help: values['help'] === true,
+        git: optionalBoolean(values['git'], preset.git),
+        install: optionalBoolean(values['install'], preset.install),
+        options,
+    };
+}

package/dist/readStackRefs.js

@@ -0,0 +1,11 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { isRecord } from './isRecord.js';
+import { STACK_REFS_URL } from './ScaffoldConfig.js';
+export function readStackRefs() {
+    if (!existsSync(STACK_REFS_URL))
+        return new Map();
+    const parsed = JSON.parse(readFileSync(STACK_REFS_URL, 'utf8'));
+    if (!isRecord(parsed))
+        throw new Error('stackRefs.json is not an object');
+    return new Map(Object.entries(parsed).filter((entry) => typeof entry[1] === 'string'));
+}

package/dist/resolveAnswers.js

@@ -0,0 +1,28 @@
+function forcedValue(option, options, answers) {
+    for (const other of options) {
+        const required = other.requires?.[option.id];
+        if (answers[other.id] && required !== undefined)
+            return { value: required, by: other.id };
+    }
+    return undefined;
+}
+function flag(id, value) {
+    return value ? `--${id}` : `--no-${id}`;
+}
+export async function resolveAnswers(options, given, ask) {
+    const answers = {};
+    for (const option of options) {
+        const forced = forcedValue(option, options, answers);
+        const chosen = given[option.id];
+        if (forced !== undefined && chosen !== undefined && chosen !== forced.value) {
+            throw new Error(`${flag(option.id, chosen)} cannot be used with ${flag(forced.by, true)}`);
+        }
+        if (forced !== undefined)
+            answers[option.id] = forced.value;
+        else if (chosen !== undefined)
+            answers[option.id] = chosen;
+        else
+            answers[option.id] = ask === undefined ? option.default : await ask(option);
+    }
+    return answers;
+}

package/dist/runCommand.js

@@ -0,0 +1,7 @@
+import { spawnSync } from 'node:child_process';
+export function runCommand(command, args, cwd, quiet = false) {
+    const result = spawnSync(command, args, { cwd, encoding: 'utf8', shell: process.platform === 'win32', stdio: quiet ? 'pipe' : 'inherit' });
+    if (result.status !== 0)
+        throw new Error(`${command} ${args.join(' ')} failed${quiet ? `: ${result.stderr}` : ''}`);
+    return result.stdout ?? '';
+}

package/dist/scaffoldProject.js

@@ -0,0 +1,23 @@
+import { applyStackChanges, updatePackageJson } from './applyStackChanges.js';
+import { fetchTemplate } from './fetchTemplate.js';
+import { runCommand } from './runCommand.js';
+import { OVERLAYS_ROOT } from './ScaffoldConfig.js';
+export async function scaffoldProject(plan, step) {
+    step(`Downloading ${plan.stack.repository}`);
+    await fetchTemplate(plan.stack, plan.dir, plan.source);
+    step('Applying the options');
+    applyStackChanges(plan.dir, plan.stack, plan.answers, OVERLAYS_ROOT, plan.projectName);
+    if (plan.git) {
+        step('Initializing git');
+        runCommand('git', ['init', '--quiet'], plan.dir);
+    }
+    else {
+        updatePackageJson(plan.dir, (pkg) => {
+            delete pkg.scripts?.['prepare'];
+        });
+    }
+    if (plan.install) {
+        step('Installing dependencies');
+        runCommand('npm', ['install'], plan.dir);
+    }
+}

package/dist/stackRefs.json

@@ -0,0 +1,4 @@
+{
+  "vite": "539012b17ec842b65a69f16c9bee7ef146057af2",
+  "fastify": "bb1433dcf2e78d158fd5bb44319ea1f3f16c6ba0"
+}

package/dist/stacks/fastifyStack.js

@@ -0,0 +1,125 @@
+const NPM_TEST_ROW = '`node:test`: queries on an in-memory database, routes through `inject()`';
+const ROW_ID_SENTENCE = " That is also why `src/shared-features/todos/todosQueries.ts` reads `row['id']`.";
+const TEST_FILES_OPENING_A_DATABASE = ['src/shared-features/todos/todosQueries.test.ts', 'src/features/todo-list/todoListRoutes.test.ts', 'src/features/todo-stats/todoStatsRoutes.test.ts'];
+export const fastifyStack = {
+    id: 'fastify',
+    label: 'Fastify API',
+    repository: 'Elnop/template-fastify',
+    submodule: 'template-fastify',
+    options: [
+        { id: 'example', message: 'Keep the todo list API example?', default: true },
+        { id: 'swagger', message: 'Serve a Swagger UI on /docs?', default: true },
+        { id: 'database', message: 'Use SQLite (node:sqlite)? Without it, the example keeps its todos in memory.', default: true },
+        { id: 'claude-hook', message: 'Add the Claude Code hook that lints each edited file?', default: true, independent: true },
+        { id: 'ci', message: 'Add the GitHub Actions workflow?', default: true, independent: true },
+    ],
+    changes: [
+        {
+            when: {},
+            edits: [{ file: 'README.md', replace: '# template-fastify\n', with: '# __PROJECT_NAME__\n' }],
+        },
+        {
+            when: { example: false },
+            remove: ['src/features', 'src/shared-features/todos', 'src/shared/ErrorSchemas.ts'],
+            edits: [
+                { file: 'src/app/buildApp.ts', dropLines: '#src/features/' },
+                { file: 'src/app/buildApp.ts', dropLines: 'createTodosQueries' },
+                { file: 'src/app/buildApp.ts', dropLines: 'Routes(create' },
+                { file: 'src/app/buildApp.ts', replace: "'Todos API'", with: "'__PROJECT_NAME__'", all: true },
+                { file: 'README.md', dropLines: 'The example is the todo list API' },
+                { file: 'README.md', dropSection: '## Endpoints' },
+                {
+                    file: 'README.md',
+                    replace: ' `src/shared-features/todos/` holds the schemas, the types and `todosQueries.ts`, the only file that runs SQL on the todos table. `src/features/todo-list/` and `src/features/todo-stats/` both use it without knowing each other.',
+                    with: '',
+                },
+                { file: 'README.md', replace: NPM_TEST_ROW, with: '`node:test`, routes through `inject()`' },
+                { file: 'README.md', dropLines: '1. Delete `src/features/`' },
+                { file: 'README.md', replace: '2. Add a shared feature', with: '1. Add a shared feature' },
+                { file: 'README.md', replace: '3. Run `npm run check` often', with: '2. Run `npm run check` often' },
+                { file: 'docs/verifications.md', replace: ROW_ID_SENTENCE, with: '' },
+                { file: 'docs/verifications.md', dropLines: '| Queries |' },
+                { file: 'docs/verifications.md', dropLines: '| Routes |' },
+            ],
+            keep: ['src/features', 'src/shared-features'],
+        },
+        {
+            when: { example: false, swagger: true },
+            overlay: 'skeleton-swagger',
+        },
+        {
+            when: { example: false, swagger: false },
+            overlay: 'skeleton-no-swagger',
+        },
+        {
+            when: { example: true, swagger: false },
+            overlay: 'example-no-swagger',
+            edits: [{ file: 'README.md', replace: ', serialize the output and produce the OpenAPI document served on `/docs/json`.', with: ' and serialize the output.' }],
+        },
+        {
+            when: { swagger: false },
+            remove: ['src/shared/swaggerTheme.css'],
+            edits: [
+                { file: 'src/app/buildApp.ts', dropLines: 'readFileSync' },
+                { file: 'src/app/buildApp.ts', dropLines: '@fastify/swagger' },
+                { file: 'src/app/buildApp.ts', dropLines: 'jsonSchemaTransform' },
+                { file: 'src/app/buildApp.ts', dropLines: 'SWAGGER_THEME' },
+                { file: 'README.md', replace: ', and the Swagger UI on `/docs`.', with: '.' },
+                { file: 'README.md', replace: ', routes, Swagger', with: ', routes' },
+                { file: 'docs/verifications.md', replace: 'the full wiring and the OpenAPI document', with: 'the full wiring' },
+            ],
+            dependencies: ['@fastify/swagger-ui'],
+        },
+        {
+            when: { example: true, database: false },
+            overlay: 'memory-store',
+            edits: [
+                ...TEST_FILES_OPENING_A_DATABASE.flatMap((file) => [
+                    { file, dropLines: "import { openDatabase } from '#src/shared/lib/openDatabase.ts';" },
+                    { file, replace: "createTodosQueries(openDatabase(':memory:'))", with: 'createTodosQueries()' },
+                ]),
+                { file: 'src/app/buildApp.ts', replace: 'createTodosQueries(database)', with: 'createTodosQueries()' },
+                { file: 'README.md', replace: 'the only file that runs SQL on the todos table', with: 'which keeps the todos in memory' },
+                { file: 'README.md', replace: NPM_TEST_ROW, with: '`node:test`: queries, routes through `inject()`' },
+                { file: 'docs/verifications.md', replace: ROW_ID_SENTENCE, with: '' },
+                { file: 'docs/verifications.md', replace: 'the SQL, on a `:memory:` database', with: 'the in-memory store' },
+            ],
+        },
+        {
+            when: { database: false },
+            remove: ['src/shared/lib/openDatabase.ts'],
+            edits: [
+                { file: 'src/app/buildApp.ts', dropLines: 'openDatabase' },
+                { file: 'src/app/buildApp.ts', dropLines: 'database.close()' },
+                { file: 'src/app/buildApp.ts', replace: '{ databasePath, logLevel }', with: '{ logLevel }' },
+                { file: 'src/app/buildApp.test.ts', replace: "databasePath: ':memory:', ", with: '', all: true },
+                { file: 'src/app/AppTypes.ts', replace: "'databasePath' | 'logLevel'", with: "'logLevel'" },
+                { file: 'src/shared/EnvTypes.ts', dropLines: 'databasePath' },
+                { file: 'src/shared/lib/readEnv.ts', dropLines: 'DATABASE_PATH: z' },
+                { file: 'src/shared/lib/readEnv.ts', replace: ', databasePath: env.DATABASE_PATH', with: '' },
+                { file: 'src/shared/lib/readEnv.test.ts', replace: ", databasePath: 'todos.db'", with: '' },
+                { file: 'src/shared/lib/readEnv.test.ts', replace: " DATABASE_PATH: ':memory:',", with: '' },
+                { file: 'src/shared/lib/readEnv.test.ts', dropLines: "databasePath: ':memory:'" },
+                { file: 'README.md', dropLines: '| `DATABASE_PATH` |' },
+                { file: 'README.md', replace: 'wires everything: database, ', with: 'wires everything: ' },
+                { file: 'README.md', replace: 'env, database connection, server factory', with: 'env, server factory' },
+                { file: 'docs/verifications.md', replace: 'it holds three plain modules', with: 'it holds two plain modules' },
+            ],
+        },
+        {
+            when: { 'claude-hook': false },
+            remove: ['.claude'],
+            edits: [
+                { file: 'knip.json', replace: '"@elnop/agent-hook", ', with: '' },
+                { file: 'README.md', dropSection: '## Working with an agent' },
+            ],
+            dependencies: ['@elnop/agent-hook'],
+        },
+        {
+            when: { ci: false },
+            remove: ['.github'],
+            edits: [{ file: 'docs/verifications.md', replace: 'runs locally, in the pre-commit hook and in CI.', with: 'runs locally and in the pre-commit hook.' }],
+        },
+    ],
+    nextSteps: () => ['npm run dev'],
+};

package/dist/stacks/stacksConfig.js

@@ -0,0 +1,3 @@
+import { fastifyStack } from './fastifyStack.js';
+import { viteStack } from './viteStack.js';
+export const stacks = [viteStack, fastifyStack];

package/dist/stacks/viteStack.js

@@ -0,0 +1,192 @@
+const CHROMIUM_LINE = '      - run: npx playwright install --with-deps --only-shell chromium\n';
+const E2E_JOB = `
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 26
+          cache: npm
+      - run: npm ci
+${CHROMIUM_LINE}      - run: npm run e2e
+`;
+const UNIT_PROJECT = "{ extends: true, test: { name: 'unit', environment: 'node', include: ['src/**/*.test.ts'] } }";
+const COMPONENT_PROJECT = `        {
+          extends: true,
+          test: {
+            name: 'component',
+            include: ['src/**/*.test.tsx'],
+            browser: { enabled: true, provider: playwright(), headless: true, instances: [{ browser: 'chromium' }] },
+          },
+        },
+`;
+const CHROMIUM_DOC = 'Component tests and e2e need headless Chromium: `npx playwright install --only-shell chromium`.';
+export const viteStack = {
+    id: 'vite',
+    label: 'Vite + React',
+    repository: 'Elnop/template-vite',
+    submodule: 'template-vite',
+    options: [
+        { id: 'example', message: 'Keep the todo list example?', default: true, requires: { zustand: true } },
+        { id: 'zustand', message: 'Add zustand for state?', default: true },
+        { id: 'component-tests', message: 'Add component tests (Vitest in Chromium)?', default: true },
+        { id: 'e2e', message: 'Add e2e tests (Playwright)?', default: true },
+        { id: 'claude-hook', message: 'Add the Claude Code hook that lints each edited file?', default: true, independent: true },
+        { id: 'ci', message: 'Add the GitHub Actions workflow?', default: true },
+    ],
+    changes: [
+        {
+            when: {},
+            edits: [{ file: 'README.md', replace: '# template-vite\n', with: '# __PROJECT_NAME__\n' }],
+        },
+        {
+            when: { example: false },
+            remove: ['src/features', 'src/shared-features/todos', 'src/shared/lib'],
+            edits: [
+                {
+                    file: 'README.md',
+                    replace: 'The example app is a todo list. It is there so every rule has real code to check: delete it and keep the structure. The look',
+                    with: 'The look',
+                },
+                {
+                    file: 'README.md',
+                    replace: 'In the example, `src/shared-features/todos/` holds the tasks and the current filter, used by both `src/features/todo-list/` (add, check, rename, delete, filter) and `src/features/todo-stats/` (counters, clear done). Renaming a task is a sub-feature: `src/features/todo-list/features/todo-editor/`. ',
+                    with: '',
+                },
+                { file: 'README.md', dropLines: '1. Delete `src/features/`' },
+                { file: 'README.md', replace: '2. Write your first feature', with: '1. Write your first feature' },
+                { file: 'README.md', replace: '3. Run `npm run check` often', with: '2. Run `npm run check` often' },
+                { file: 'docs/verifications.md', replace: '`src/shared/lib/normalizeTitle.test.ts` next to its source', with: 'next to its source' },
+                { file: 'docs/verifications.md', replace: '`src/features/todo-list/components/presenters/TodoInput.test.tsx`', with: 'next to the presenter' },
+            ],
+            overlay: 'skeleton',
+            keep: ['src/features', 'src/shared-features', 'src/shared'],
+        },
+        {
+            when: { example: false, e2e: true },
+            remove: ['e2e/todos.spec.ts'],
+            edits: [
+                {
+                    file: 'docs/verifications.md',
+                    replace: ' `e2e/todos.spec.ts` covers the example: the same two checks while a task is being renamed, the counters while adding, checking, filtering and clearing tasks, and renaming.',
+                    with: '',
+                },
+            ],
+        },
+        {
+            when: { example: false, zustand: true },
+            edits: [{ file: 'knip.json', replace: '"ignoreDependencies": ["@swc/core", ', with: '"ignoreDependencies": ["@swc/core", "zustand", ' }],
+        },
+        {
+            when: { example: false, 'component-tests': true },
+            edits: [{ file: 'knip.json', replace: '"ignoreDependencies": ["@swc/core", ', with: '"ignoreDependencies": ["@swc/core", "vitest-browser-react", ' }],
+        },
+        {
+            when: { zustand: false },
+            dependencies: ['zustand'],
+        },
+        {
+            when: { 'component-tests': false, example: true },
+            remove: ['src/**/*.test.tsx'],
+        },
+        {
+            when: { 'component-tests': false },
+            edits: [
+                { file: 'vitest.config.ts', replace: "import { playwright } from '@vitest/browser-playwright';\n", with: '' },
+                { file: 'vitest.config.ts', replace: `      projects: [\n        ${UNIT_PROJECT},\n${COMPONENT_PROJECT}      ],\n`, with: `      projects: [${UNIT_PROJECT}],\n` },
+                { file: 'tsconfig.test.json', replace: ', "@vitest/browser-playwright"]', with: ']' },
+                { file: 'README.md', replace: 'Vitest: unit tests in Node, component tests in headless Chromium', with: 'Vitest unit tests, in Node' },
+                { file: 'docs/verifications.md', dropLines: '| Component |' },
+                {
+                    file: 'docs/verifications.md',
+                    replace: 'The extension picks the kind: `.test.ts` runs in Node, `.test.tsx` in Chromium. Only presenters get component tests, since orchestrators read stores and e2e covers them. ',
+                    with: '',
+                },
+            ],
+            scripts: ['test:component'],
+            dependencies: ['@vitest/browser-playwright', 'vitest-browser-react'],
+        },
+        {
+            when: { 'component-tests': false, ci: true },
+            edits: [{ file: '.github/workflows/ci.yml', replace: `      - run: npm ci\n${CHROMIUM_LINE}      - run: npm run check`, with: '      - run: npm ci\n      - run: npm run check' }],
+        },
+        {
+            when: { e2e: false },
+            remove: ['e2e', 'playwright.config.ts'],
+            edits: [
+                {
+                    file: 'package.json',
+                    replace: 'oxlint --type-aware src e2e oxlint.config.ts vite.config.ts vitest.config.ts playwright.config.ts',
+                    with: 'oxlint --type-aware src oxlint.config.ts vite.config.ts vitest.config.ts',
+                },
+                { file: 'tsconfig.test.json', replace: '"include": ["src", "e2e",', with: '"include": ["src",' },
+                { file: 'tsconfig.test.json', replace: ', "playwright.config.ts"]', with: ']' },
+                { file: 'tsconfig.test.json', replace: '"@/*": ["./src/*"],\n      "@e2e/*": ["./e2e/*"]', with: '"@/*": ["./src/*"]' },
+                { file: 'oxlint.config.ts', replace: 'import through an alias (@/ in src/, @e2e/ in e2e/).', with: 'import through the @/ alias.' },
+                { file: 'README.md', dropLines: '| `npm run e2e` |' },
+                { file: 'docs/verifications.md', replace: " That last one is why `playwright.config.ts` reads `process.env['CI']`.", with: '' },
+                { file: 'docs/verifications.md', replace: 'on tests, e2e and configs', with: 'on tests and configs' },
+                { file: 'docs/verifications.md', replace: '`@/` in `src/`, `@e2e/` in `e2e/`', with: '`@/` in `src/`' },
+                { file: 'docs/verifications.md', dropLines: '| E2e |' },
+                { file: 'docs/verifications.md', dropLines: 'The specs import `test`' },
+            ],
+            scripts: ['e2e'],
+            dependencies: ['@playwright/test', '@axe-core/playwright', '@elnop/playwright-fixtures'],
+        },
+        {
+            when: { e2e: false, example: true },
+            edits: [
+                {
+                    file: 'README.md',
+                    replace: ', the files in `src/shared/` and `e2e/todos.spec.ts`. `e2e/app.spec.ts` and `e2e/openApp.ts` work on any app whose first screen has an `h1`.',
+                    with: ' and the files in `src/shared/`.',
+                },
+            ],
+        },
+        {
+            when: { e2e: false, ci: true },
+            edits: [
+                { file: '.github/workflows/ci.yml', replace: E2E_JOB, with: '' },
+                { file: 'README.md', replace: ' in one job and `e2e` in another.', with: '.' },
+            ],
+        },
+        {
+            when: { e2e: false, 'component-tests': true },
+            devDependencies: { playwright: '1.64.1' },
+            edits: [
+                { file: 'docs/verifications.md', replace: CHROMIUM_DOC, with: 'Component tests need headless Chromium: `npx playwright install --only-shell chromium`.' },
+                { file: 'docs/verifications.md', replace: ', since orchestrators read stores and e2e covers them.', with: ', since orchestrators read stores.' },
+            ],
+        },
+        {
+            when: { e2e: true, 'component-tests': false },
+            edits: [{ file: 'docs/verifications.md', replace: CHROMIUM_DOC, with: 'E2e needs headless Chromium: `npx playwright install --only-shell chromium`.' }],
+        },
+        {
+            when: { e2e: false, 'component-tests': false },
+            edits: [
+                { file: 'docs/verifications.md', replace: ` ${CHROMIUM_DOC}`, with: '' },
+                { file: 'README.md', dropLines: 'npx playwright install' },
+            ],
+        },
+        {
+            when: { 'claude-hook': false },
+            remove: ['.claude'],
+            edits: [
+                { file: 'knip.json', replace: '"@elnop/agent-hook", ', with: '' },
+                { file: 'README.md', dropSection: '## Working with an agent' },
+            ],
+            dependencies: ['@elnop/agent-hook'],
+        },
+        {
+            when: { ci: false },
+            remove: ['.github'],
+            edits: [
+                { file: 'README.md', dropLines: 'CI (`.github/workflows/ci.yml`)' },
+                { file: 'docs/verifications.md', replace: 'runs locally, in the pre-commit hook and in CI.', with: 'runs locally and in the pre-commit hook.' },
+            ],
+        },
+    ],
+    nextSteps: (answers) => [...(answers['e2e'] || answers['component-tests'] ? ['npx playwright install --only-shell chromium'] : []), 'npm run dev'],
+};

package/overlays/fastify/example-no-swagger/src/app/buildApp.test.ts

@@ -0,0 +1,12 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { buildApp } from '#src/app/buildApp.ts';
+
+describe('buildApp', () => {
+  it('wires the todo list and the stats on the same todos', async () => {
+    const app = await buildApp({ databasePath: ':memory:', logLevel: 'silent' });
+    await app.inject({ method: 'POST', url: '/todos', payload: { title: 'Wire the app' } });
+    assert.deepEqual((await app.inject({ method: 'GET', url: '/stats' })).json(), { total: 1, completed: 0, remaining: 1 });
+    await app.close();
+  });
+});

package/overlays/fastify/memory-store/src/shared-features/todos/todosQueries.ts

@@ -0,0 +1,47 @@
+import type { Todo, TodosQueries } from '#src/shared-features/todos/TodosTypes.ts';
+
+export function createTodosQueries(): TodosQueries {
+  const todos = new Map<number, Todo>();
+  let lastId = 0;
+
+  function all(): Todo[] {
+    return [...todos.values()].map((todo) => ({ ...todo }));
+  }
+
+  return {
+    list: all,
+    listByCompleted: (completed) => all().filter((todo) => todo.completed === completed),
+    find: (id) => {
+      const todo = todos.get(id);
+      return todo === undefined ? null : { ...todo };
+    },
+    insert: ({ title }) => {
+      lastId += 1;
+      const todo = { id: lastId, title, completed: false };
+      todos.set(todo.id, todo);
+      return { ...todo };
+    },
+    update: (id, { title, completed }) => {
+      const todo = todos.get(id);
+      if (todo === undefined) return null;
+      const updated = { id, title: title ?? todo.title, completed: completed ?? todo.completed };
+      todos.set(id, updated);
+      return { ...updated };
+    },
+    remove: (id) => {
+      const todo = todos.get(id);
+      if (todo === undefined) return null;
+      todos.delete(id);
+      return todo;
+    },
+    removeCompleted: () => {
+      const completed = all().filter((todo) => todo.completed);
+      for (const todo of completed) todos.delete(todo.id);
+      return completed.length;
+    },
+    count: () => {
+      const list = all();
+      return { total: list.length, completed: list.filter((todo) => todo.completed).length };
+    },
+  };
+}

package/overlays/fastify/skeleton-no-swagger/src/app/buildApp.test.ts

@@ -0,0 +1,11 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { buildApp } from '#src/app/buildApp.ts';
+
+describe('buildApp', () => {
+  it('answers 404 on a route nobody registered', async () => {
+    const app = await buildApp({ databasePath: ':memory:', logLevel: 'silent' });
+    assert.equal((await app.inject({ method: 'GET', url: '/' })).statusCode, 404);
+    await app.close();
+  });
+});

package/overlays/fastify/skeleton-swagger/src/app/buildApp.test.ts

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { buildApp } from '#src/app/buildApp.ts';
+
+describe('buildApp', () => {
+  it('serves the OpenAPI document and the Swagger UI', async () => {
+    const app = await buildApp({ databasePath: ':memory:', logLevel: 'silent' });
+    const spec = await app.inject({ method: 'GET', url: '/docs/json' });
+    assert.equal(spec.json<{ info: { title: string } }>().info.title, '__PROJECT_NAME__');
+    const ui = await app.inject({ method: 'GET', url: '/docs/' });
+    assert.equal(ui.statusCode, 200);
+    await app.close();
+  });
+});

package/overlays/vite/skeleton/src/app/App.tsx

@@ -0,0 +1,12 @@
+export function App() {
+  return (
+    <div className="page">
+      <header className="page-header">
+        <h1>__PROJECT_NAME__</h1>
+      </header>
+      <main className="page-body">
+        <p>Write your first feature in src/features/ and render it here.</p>
+      </main>
+    </div>
+  );
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "create-elnop-stack",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Creates a project from one of the elnop-stacks templates, with the options you pick.",
+  "keywords": [
+    "create",
+    "template",
+    "vite",
+    "react",
+    "fastify"
+  ],
+  "homepage": "https://github.com/Elnop/elnop-stacks/tree/main/create-elnop-stack#readme",
+  "bugs": "https://github.com/Elnop/elnop-stacks/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Elnop/elnop-stacks.git",
+    "directory": "create-elnop-stack"
+  },
+  "license": "MIT",
+  "author": "elnop",
+  "type": "module",
+  "engines": {
+    "node": ">=26"
+  },
+  "files": [
+    "dist",
+    "overlays"
+  ],
+  "bin": {
+    "create-elnop-stack": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/writeStackRefs.ts",
+    "prepack": "npm run build",
+    "test": "node --test 'src/**/*.test.ts'"
+  },
+  "dependencies": {
+    "@clack/prompts": "1.8.1",
+    "giget": "3.3.1"
+  }
+}