create-agent-rig 0.4.0 → 0.5.0

package/templates/skeleton/node-service/README.md

@@ -87,7 +87,17 @@ diagnose second.
   layer is mandatory even when it looks like ceremony.
 - `packages/core` is pure — the `guard-core-purity` hook refuses I/O, clock,
   randomness, and environment access at the tool layer.
-- `packages/db` is the only module that touches the stored data.
+- `packages/db` is the only module that touches the stored data. It is a
+  **single-instance store**: writes serialise inside one `JsonFileNoteStore`
+  object, and that is the whole of it. Two stores over the same file lose
+  notes to each other whether they sit in one process or two — share the one
+  instance, and reach for a real lock before you share the file.
+  A hard kill between the temp write and the rename leaves a `*.tmp` file
+  behind; nothing sweeps them.
+- `POST /notes` buffers at most **1 MB** of request body and answers `413` past
+  that. The cap lives in that route, not in the shell: a new route that reads a
+  body adds its own. Raise it in `services/api/src/server.ts` if your payloads
+  are bigger; do not remove it.
 - A failing queue message is poison: it throws, the spool retries ×3, then the
   DLQ gets it and the ALARM line fires. Never wrap the worker in a broad catch.
 

package/templates/skeleton/node-service/gitignore

@@ -9,10 +9,44 @@ out/
 next-env.d.ts
 dist/
 .claude/worktrees/
+# per-checkout queue state: the tier the last close recorded. The queue CONFIG
+# is composed and tracked; this is runtime state and must never be committed.
+.claude/queue.state.json
+# gate rounds, one count per branch
+.claude/gate-rounds.json
+# per-run machine trace (.claude/scripts/run-journal.mjs): forensics that churn
+# on every gate and collide across concurrent sessions. Unlike a committed
+# evidence directory, this one is per-run and stays out of the repository.
+.claude/runs/
 
 # secrets — never commit these
+*.env
 .env
 .env.*
 !.env.example
+.envrc
+.npmrc
+.netrc
+.pgpass
+id_rsa
+id_ed25519
 *.pem
 *.key
+*.p12
+*.pfx
+*.keystore
+*.jks
+*.secret
+*.secrets
+*.token
+*.tokens
+*.password
+*.passwords
+*.credential
+*.credentials
+*.apikey
+*.apikeys
+*.passwd
+*.creds
+*.jwt
+*.bearer

package/templates/skeleton/node-service/packages/db/src/note-store.ts

@@ -1,7 +1,8 @@
 // The model boundary, same contract as any other target — only the medium
 // differs: one JSON file. This is the ONLY module that knows how notes are
 // persisted; nothing else composes a path into the data file.
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { NoteSchema, type Note } from '@app/core';
 import { AppError, NotFoundError } from '@app/shared';
@@ -9,15 +10,28 @@ import { AppError, NotFoundError } from '@app/shared';
 type NoteTable = Record<string, unknown>;
 
 export class JsonFileNoteStore {
+  /**
+   * Writes run one at a time — **per instance, which is the whole extent of
+   * it**. A write is load → mutate → save, and that is not atomic: two
+   * concurrent `put()`s would both read the same table and the second save
+   * would drop the first note. This chain serialises the ones going through
+   * *this* object. Two `JsonFileNoteStore`s over the same file lose notes to
+   * each other exactly as before — in one process as readily as in two — so
+   * share the instance, and reach for a real lock before sharing the file.
+   */
+  private writes: Promise<unknown> = Promise.resolve();
+
   constructor(private readonly file: string) {}
 
   async put(note: Note): Promise<void> {
-    const table = await this.load();
-    if (note.id in table) {
-      throw new AppError(`note ${note.id} already exists`, { code: 'CONFLICT', statusCode: 409 });
-    }
-    table[note.id] = note;
-    await this.save(table);
+    return this.serialised(async () => {
+      const table = await this.load();
+      if (note.id in table) {
+        throw new AppError(`note ${note.id} already exists`, { code: 'CONFLICT', statusCode: 409 });
+      }
+      table[note.id] = note;
+      await this.save(table);
+    });
   }
 
   async get(id: string): Promise<Note> {
@@ -38,6 +52,20 @@ export class JsonFileNoteStore {
       .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
   }
 
+  /** Queues `work` behind the writes already in flight on this instance. */
+  private serialised<T>(work: () => Promise<T>): Promise<T> {
+    const result = this.writes.then(work);
+    // The caller gets the rejection; the chain gets a settled promise. Without
+    // this line one failed write (a 409, say) would reject every write queued
+    // behind it, and this store object would stay broken for as long as it is
+    // held — the chain is per instance, so a fresh store would still work.
+    this.writes = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result;
+  }
+
   private async load(): Promise<NoteTable> {
     let content: string;
     try {
@@ -56,8 +84,17 @@ export class JsonFileNoteStore {
   private async save(table: NoteTable): Promise<void> {
     await mkdir(path.dirname(this.file), { recursive: true });
     // Write-then-rename keeps readers from ever seeing a half-written file.
-    const tmp = `${this.file}.tmp`;
-    await writeFile(tmp, JSON.stringify(table, null, 2));
-    await rename(tmp, this.file);
+    // The temp name is unique per write: a shared one lets two writers scribble
+    // over each other's file and lose a rename to ENOENT.
+    const tmp = `${this.file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(tmp, JSON.stringify(table, null, 2));
+      await rename(tmp, this.file);
+    } catch (error) {
+      // Best-effort tidy-up: a failure to remove the temp file must not
+      // replace the failure that actually matters.
+      await rm(tmp, { force: true }).catch(() => undefined);
+      throw error;
+    }
   }
 }

package/templates/skeleton/node-service/packages/db/test/note-store.test.ts

@@ -40,6 +40,17 @@ describe('JsonFileNoteStore', () => {
     await expect(store.put(note)).rejects.toMatchObject({ statusCode: 409 });
   });
 
+  it('a rejected write does not block the writes queued behind it', async () => {
+    // The 409 above cannot see this: a poisoned write chain rejects the next
+    // put() with the very same AppError the duplicate would have raised.
+    const store = new JsonFileNoteStore(file);
+    await store.put(note);
+    await expect(store.put(note)).rejects.toThrow(AppError);
+
+    await expect(store.put({ ...note, id: 'n2' })).resolves.toBeUndefined();
+    expect((await store.list()).map((n) => n.id).sort()).toEqual(['n1', 'n2']);
+  });
+
   it('throws NotFoundError on a miss', async () => {
     await expect(new JsonFileNoteStore(file).get('nope')).rejects.toThrow(NotFoundError);
   });
@@ -69,6 +80,15 @@ describe('JsonFileNoteStore', () => {
     expect(listed.map((n) => n.id)).toEqual(['b', 'a']);
   });
 
+  it('keeps every concurrently written note (no lost update)', async () => {
+    const store = new JsonFileNoteStore(file);
+    const ids = Array.from({ length: 20 }, (_, i) => `n${i}`);
+    await Promise.all(ids.map((id) => store.put({ ...note, id })));
+
+    expect((await store.list()).map((n) => n.id).sort()).toEqual([...ids].sort());
+    expect(Object.keys(JSON.parse(await readFile(file, 'utf8'))).sort()).toEqual([...ids].sort());
+  });
+
   it('refuses to list corrupt entries instead of skipping them silently', async () => {
     const store = new JsonFileNoteStore(file);
     await store.put(note);

package/templates/skeleton/node-service/services/api/src/main.ts

@@ -7,17 +7,10 @@ import { JsonFileNoteStore } from '@app/db';
 import { createLogger, loadEnv } from '@app/shared';
 import { SpoolEventPublisher } from './adapters/spool-publisher.js';
 import { makeServer } from './server.js';
+import { defaultStaticDirFor } from './static-dir.js';
 
 // The built web bundle (pnpm build:web) lives here; served when present.
-const defaultStaticDir = path.resolve(
-  path.dirname(new URL(import.meta.url).pathname),
-  '..',
-  '..',
-  '..',
-  'apps',
-  'web',
-  'out',
-);
+const defaultStaticDir = defaultStaticDirFor(import.meta.url);
 
 const env = loadEnv(
   z.object({

package/templates/skeleton/node-service/services/api/src/server.ts

@@ -2,7 +2,7 @@
 // configured) serving the built web bundle. No second runtime for the
 // frontend — the same process serves the static export.
 import { createReadStream } from 'node:fs';
-import { stat } from 'node:fs/promises';
+import { realpath, stat } from 'node:fs/promises';
 import { createServer, type Server } from 'node:http';
 import path from 'node:path';
 import type { CreateNoteDeps } from './usecases/create-note.js';
@@ -18,6 +18,14 @@ export interface ServerOptions {
   staticDir?: string;
 }
 
+/**
+ * Largest request body `POST /notes` will buffer — that route and no other:
+ * the cap is applied where the body is read, so a second route that reads one
+ * brings its own. A note is a title and some tags; anything past this is a
+ * mistake or an attack, and either way the process must not hold it in memory.
+ */
+const MAX_BODY_BYTES = 1024 * 1024;
+
 const CONTENT_TYPES: Record<string, string> = {
   '.html': 'text/html; charset=utf-8',
   '.css': 'text/css',
@@ -39,11 +47,34 @@ export function makeServer(deps: ServerDeps, options: ServerOptions = {}): Serve
       response.end(result.body);
     };
     const notFound = () => respond({ statusCode: 404, body: JSON.stringify({ error: 'not found' }) });
+    const badRequest = () =>
+      respond({ statusCode: 400, body: JSON.stringify({ error: 'bad request' }) });
 
     if (request.method === 'POST' && request.url === '/notes') {
       const chunks: Buffer[] = [];
-      request.on('data', (chunk: Buffer) => chunks.push(chunk));
+      let size = 0;
+      let refused = false;
+      // A socket that dies mid-upload emits 'error'; unhandled, it takes the
+      // process with it.
+      request.on('error', () => {
+        refused = true;
+      });
+      request.on('data', (chunk: Buffer) => {
+        if (refused) return;
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES) {
+          refused = true;
+          chunks.length = 0;
+          respond({ statusCode: 413, body: JSON.stringify({ error: 'payload too large' }) });
+          // Keep draining rather than destroying the socket: a client that is
+          // still uploading has to stay connected to read the refusal.
+          request.resume();
+          return;
+        }
+        chunks.push(chunk);
+      });
       request.on('end', () => {
+        if (refused) return;
         void createNote(Buffer.concat(chunks).toString('utf8')).then(respond);
       });
       return;
@@ -55,7 +86,21 @@ export function makeServer(deps: ServerDeps, options: ServerOptions = {}): Serve
     }
 
     if (request.method === 'GET' && options.staticDir) {
-      void serveStatic(options.staticDir, request.url ?? '/', response, notFound);
+      // The rejection handler is the point: without it a throw in here is an
+      // unhandled rejection, which ends the process on one malformed request.
+      void serveStatic(options.staticDir, request.url ?? '/', response, notFound, badRequest).catch(
+        (error: unknown) => {
+          // Say nothing to the client beyond the code, but never swallow it —
+          // a static path that fails silently is a blind spot in every
+          // generated project.
+          deps.log.error('static serve failed', { url: request.url, error: String(error) });
+          if (response.headersSent) {
+            response.destroy();
+            return;
+          }
+          respond({ statusCode: 500, body: JSON.stringify({ error: 'internal error' }) });
+        },
+      );
       return;
     }
 
@@ -68,22 +113,60 @@ async function serveStatic(
   rawUrl: string,
   response: import('node:http').ServerResponse,
   notFound: () => void,
+  badRequest: () => void,
 ): Promise<void> {
-  const pathname = decodeURIComponent(new URL(rawUrl, 'http://local').pathname);
+  let pathname: string;
+  try {
+    pathname = decodeURIComponent(new URL(rawUrl, 'http://local').pathname);
+  } catch {
+    // A malformed escape (`GET /%`) is the client's error, not ours.
+    return badRequest();
+  }
   const relative = pathname.endsWith('/') ? `${pathname}index.html` : pathname;
-  const resolved = path.normalize(path.join(staticDir, relative));
+  // Resolve the root first: a configured dir with a trailing separator would
+  // otherwise build a `//` prefix that no resolved path can start with, and
+  // every request would 404.
+  const root = path.resolve(staticDir);
+  const resolved = path.resolve(root, `.${path.sep}${relative}`);
   // Path-traversal guard: whatever the URL said, we never leave staticDir.
-  if (!resolved.startsWith(path.normalize(staticDir) + path.sep)) {
+  // The string test is only half of it — it says where the path points, not
+  // what the filesystem will open, and stat/open both follow symlinks.
+  if (!within(root, resolved)) {
     return notFound();
   }
+  let file: string;
   try {
-    const stats = await stat(resolved);
+    // …so ask the filesystem too, and test the answer the same way. A missing
+    // file throws here, which is the 404 we would give it anyway.
+    file = await realpath(resolved);
+    if (!within(await realpath(root), file)) return notFound();
+    const stats = await stat(file);
     if (!stats.isFile()) return notFound();
   } catch {
     return notFound();
   }
-  response.writeHead(200, {
-    'content-type': CONTENT_TYPES[path.extname(resolved)] ?? 'application/octet-stream',
+  // Open before the headers go out: a file that passes stat can still fail to
+  // open (EACCES, or it is gone by now), and after writeHead(200) there is no
+  // way left to say so — which is one GET away from an unhandled stream error.
+  const stream = createReadStream(file);
+  await new Promise<void>((resolve, reject) => {
+    stream.once('error', reject);
+    stream.once('open', () => {
+      stream.removeListener('error', reject);
+      response.writeHead(200, {
+        'content-type': CONTENT_TYPES[path.extname(file)] ?? 'application/octet-stream',
+      });
+      // Past the headers the only honest answer to a read failure is to cut
+      // the response short, so the client sees a truncated body rather than a
+      // complete one.
+      stream.once('error', () => response.destroy());
+      stream.pipe(response);
+      resolve();
+    });
   });
-  createReadStream(resolved).pipe(response);
+}
+
+/** Whether `candidate` is `root` itself or sits underneath it. */
+function within(root: string, candidate: string): boolean {
+  return candidate === root || candidate.startsWith(root + path.sep);
 }

package/templates/skeleton/node-service/services/api/src/static-dir.ts

@@ -0,0 +1,20 @@
+// Where the built web bundle lives, resolved relative to the composition root.
+// A pure function rather than an inline expression in main.ts: main.ts is wiring
+// that tests never import, and this resolution has a bug worth pinning —
+// `new URL(url).pathname` leaves percent-escapes in place (a checkout under
+// "/Users/a b/" resolves to "/Users/a%20b/") and prefixes a slash on Windows.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** `apps/web/out`, three levels up from a module in `services/api/src`. */
+export function defaultStaticDirFor(moduleUrl: string): string {
+  return path.resolve(
+    path.dirname(fileURLToPath(moduleUrl)),
+    '..',
+    '..',
+    '..',
+    'apps',
+    'web',
+    'out',
+  );
+}

package/templates/skeleton/node-service/services/api/test/server.test.ts

@@ -1,6 +1,6 @@
 // Integration: the real HTTP server over a real socket, with real file
 // storage and a real spool directory — the whole request path at once.
-import { mkdir, mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, mkdtemp, readdir, rm, symlink, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import type { AddressInfo } from 'node:net';
 import path from 'node:path';
@@ -75,8 +75,43 @@ describe('the service end to end', () => {
     const { notes } = (await response.json()) as { notes: Array<{ title: string }> };
     expect(notes).toHaveLength(2);
   });
+
+  it('refuses a request body larger than the cap with 413', async () => {
+    // Well-formed JSON on purpose: what is rejected is the size, not the shape.
+    // The server must answer before it has buffered the whole upload, and must
+    // stay readable long enough for the client to see that answer.
+    const body = JSON.stringify({ title: 'x'.repeat(1024 * 1024 + 1024) });
+    const response = await fetch(`${baseUrl}/notes`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body,
+    });
+    expect(response.status).toBe(413);
+  });
 });
 
+/** A listening server serving `staticDir`, plus its base URL. */
+async function startStaticServer(staticDir: string): Promise<{ server: Server; base: string }> {
+  const server = makeServer(
+    {
+      notes: new JsonFileNoteStore(path.join(dir, 'data', 'notes.json')),
+      events: new SpoolEventPublisher(path.join(dir, 'queue'), () => 'm'),
+      newId: () => 'id',
+      now: () => '2024-01-01T00:00:00.000Z',
+      log: createLogger({}, () => {}),
+    },
+    { staticDir },
+  );
+  await new Promise<void>((resolve) => server.listen(0, resolve));
+  return { server, base: `http://127.0.0.1:${(server.address() as AddressInfo).port}` };
+}
+
+// Windows has no POSIX mode bits, and root reads a 0o000 file regardless — in
+// both cases the "unreadable file" this test needs cannot be built at all.
+const cannotMakeFileUnreadable = process.platform === 'win32' || process.getuid?.() === 0;
+// Creating a symlink on Windows needs a privilege the test runner may not hold.
+const cannotSymlink = process.platform === 'win32';
+
 describe('static serving (the built web bundle)', () => {
   let staticServer: Server;
   let staticBase: string;
@@ -84,18 +119,9 @@ describe('static serving (the built web bundle)', () => {
   beforeEach(async () => {
     await mkdir(path.join(dir, 'static'), { recursive: true });
     await writeFile(path.join(dir, 'static', 'index.html'), '<h1>web shell</h1>');
-    staticServer = makeServer(
-      {
-        notes: new JsonFileNoteStore(path.join(dir, 'data', 'notes.json')),
-        events: new SpoolEventPublisher(path.join(dir, 'queue'), () => 'm'),
-        newId: () => 'id',
-        now: () => '2024-01-01T00:00:00.000Z',
-        log: createLogger({}, () => {}),
-      },
-      { staticDir: path.join(dir, 'static') },
-    );
-    await new Promise<void>((resolve) => staticServer.listen(0, resolve));
-    staticBase = `http://127.0.0.1:${(staticServer.address() as AddressInfo).port}`;
+    ({ server: staticServer, base: staticBase } = await startStaticServer(
+      path.join(dir, 'static'),
+    ));
   });
 
   afterEach(async () => {
@@ -120,4 +146,63 @@ describe('static serving (the built web bundle)', () => {
     expect(response.status).toBe(200);
     expect(response.headers.get('content-type')).toContain('application/json');
   });
+
+  it('answers 400 to an undecodable URL and keeps serving afterwards', async () => {
+    // The signal is a leash, not a relaxation: a server that dies on this URL
+    // never answers at all, and the run should say so in seconds.
+    const response = await fetch(staticBase + '/%', { signal: AbortSignal.timeout(5000) });
+    expect(response.status).toBe(400);
+
+    const afterwards = await fetch(staticBase + '/');
+    expect(afterwards.status).toBe(200);
+    expect(await afterwards.text()).toContain('web shell');
+  });
+
+  it.skipIf(cannotMakeFileUnreadable)(
+    'answers a file it cannot open and keeps serving afterwards',
+    async () => {
+      // A file that passes stat() but fails open() (EACCES here; in production
+      // the stat/open race gives ENOENT). Before the headers are held back
+      // until the stream opens, that error reached no handler at all and the
+      // process paid for one unreadable file.
+      const locked = path.join(dir, 'static', 'locked.txt');
+      await writeFile(locked, 'unreadable');
+      await chmod(locked, 0o000);
+      try {
+        const response = await fetch(staticBase + '/locked.txt', {
+          signal: AbortSignal.timeout(5000),
+        });
+        expect(response.status).toBe(500);
+
+        const afterwards = await fetch(staticBase + '/');
+        expect(afterwards.status).toBe(200);
+        expect(await afterwards.text()).toContain('web shell');
+      } finally {
+        // Restore before afterEach removes the temp dir.
+        await chmod(locked, 0o600);
+      }
+    },
+  );
+
+  it.skipIf(cannotSymlink)('refuses a symlink that escapes the static dir', async () => {
+    // A lexical guard inspects only the resolved string, while stat and the
+    // read stream follow the link wherever it points — which is why the guard
+    // asks realpath as well.
+    await writeFile(path.join(dir, 'secret-target.txt'), 'nope');
+    await symlink(path.join(dir, 'secret-target.txt'), path.join(dir, 'static', 'escape.txt'));
+
+    const response = await fetch(staticBase + '/escape.txt');
+    expect(response.status).toBe(404);
+  });
+
+  it('serves the bundle when the configured static dir has a trailing separator', async () => {
+    const { server, base } = await startStaticServer(path.join(dir, 'static') + path.sep);
+    try {
+      const response = await fetch(base + '/');
+      expect(response.status).toBe(200);
+      expect(await response.text()).toContain('web shell');
+    } finally {
+      await new Promise((resolve) => server.close(resolve));
+    }
+  });
 });

package/templates/skeleton/node-service/services/api/test/static-dir.test.ts

@@ -0,0 +1,28 @@
+// The composition root resolves the built web bundle relative to itself; the
+// resolution is a pure function so it can be tested without importing main.ts.
+//
+// What is NOT pinned here: the Windows half of the same defect — the old
+// `new URL(url).pathname` yielded `/C:/…`. Both expressions are identical on a
+// POSIX runner, so observing the difference would mean passing a path flavour
+// into `defaultStaticDirFor`, i.e. a parameter that exists only for the test.
+// The decision was to leave that hook out; percent-decoding below is the same
+// bug's POSIX-visible half, and it fails against the old expression.
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { defaultStaticDirFor } from '../src/static-dir.js';
+
+describe('resolving the default static dir from the module url', () => {
+  it('decodes percent-escapes in the path (a directory may contain a space)', () => {
+    const resolved = defaultStaticDirFor('file:///Users/a%20b/proj/services/api/src/main.ts');
+
+    expect(resolved).toContain('a b');
+    expect(resolved).not.toContain('%20');
+  });
+
+  it('points three levels up from services/api/src at apps/web/out', () => {
+    const resolved = defaultStaticDirFor('file:///Users/a%20b/proj/services/api/src/main.ts');
+
+    expect(resolved.endsWith(path.join('a b', 'proj', 'apps', 'web', 'out'))).toBe(true);
+    expect(path.isAbsolute(resolved)).toBe(true);
+  });
+});