create-elnop-stack 0.1.0 → 0.2.0

package/README.md

@@ -13,8 +13,11 @@ Node 26 is required, like the templates.
 | 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/`, `src/shared-features/` and `src/shared/` folders, and an `App.tsx` that only shows the project name. zustand can only be removed together with the example, since the example uses it.
+`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.
 
@@ -40,7 +43,7 @@ npm create elnop-stack my-app -- --preset minimal.json --yes
 
 ## 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`: 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.
+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
 

package/dist/applyFileEdit.js

@@ -21,15 +21,17 @@ function dropLines(text, needle) {
         throw new Error(`no line contains "${needle}"`);
     return kept.join('\n').replaceAll(/\n{3,}/gu, '\n\n');
 }
-function replaceOnce(text, search, replacement) {
+function replaceText(text, search, replacement, all) {
     const count = text.split(search).length - 1;
-    if (count !== 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 text.replace(search, () => replacement);
+    return all ? text.replaceAll(search, () => replacement) : text.replace(search, () => replacement);
 }
 export function applyFileEdit(text, edit) {
     if ('replace' in edit)
-        return replaceOnce(text, edit.replace, edit.with);
+        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/stackRefs.json

@@ -1,3 +1,4 @@
 {
-  "vite": "539012b17ec842b65a69f16c9bee7ef146057af2"
+  "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

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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-elnop-stack",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Creates a project from one of the elnop-stacks templates, with the options you pick.",
   "keywords": [
     "create",