create-agent-rig 0.1.0

package/templates/skeleton/node-service/pnpm-workspace.yaml

@@ -0,0 +1,13 @@
+packages:
+  - packages/*
+  - services/*
+  - apps/*
+
+# esbuild arrives via tsx. Its postinstall is intentionally NOT approved:
+# skipping it keeps the JS launcher (which resolves the platform binary
+# itself); approving it swaps in a raw binary that pnpm's bin shim can't run.
+# sharp (via next) only matters for the image optimizer, which a static
+# export never runs — its native build stays off.
+allowBuilds:
+  esbuild: false
+  sharp: false

package/templates/skeleton/node-service/services/api/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@app/api",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/main.ts",
+  "types": "src/main.ts",
+  "scripts": {
+    "start": "tsx src/main.ts"
+  },
+  "dependencies": {
+    "@app/core": "workspace:*",
+    "@app/db": "workspace:*",
+    "@app/shared": "workspace:*",
+    "zod": "^4.4.3"
+  }
+}

package/templates/skeleton/node-service/services/api/src/adapters/spool-publisher.ts

@@ -0,0 +1,23 @@
+// The queue between api and worker is a spool directory: one JSON file per
+// event. Same DLQ discipline as any queue — the worker moves poison files to
+// the DLQ directory after its retry budget.
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { NoteCreatedEvent } from '@app/core';
+import type { EventPublisher } from '../usecases/create-note.js';
+
+export class SpoolEventPublisher implements EventPublisher {
+  constructor(
+    private readonly queueDir: string,
+    /** Unique, sortable message name — injected so tests stay deterministic. */
+    private readonly nextName: () => string,
+  ) {}
+
+  async publish(event: NoteCreatedEvent): Promise<void> {
+    await mkdir(this.queueDir, { recursive: true });
+    const file = path.join(this.queueDir, `${this.nextName()}.json`);
+    // Write-then-rename so the worker never picks up a half-written message.
+    await writeFile(`${file}.tmp`, JSON.stringify(event));
+    await rename(`${file}.tmp`, file);
+  }
+}

package/templates/skeleton/node-service/services/api/src/handlers/create-note.ts

@@ -0,0 +1,40 @@
+// The handler translates transport ⇄ domain and nothing else: decode the
+// payload, call the usecase, map the result (or the typed error) to HTTP.
+import { InvalidNoteError } from '@app/core';
+import { AppError } from '@app/shared';
+import { createNoteUsecase, type CreateNoteDeps } from '../usecases/create-note.js';
+
+export interface HttpResponse {
+  statusCode: number;
+  body: string;
+}
+
+const json = (statusCode: number, body: unknown): HttpResponse => ({
+  statusCode,
+  body: JSON.stringify(body),
+});
+
+export function makeCreateNoteHandler(deps: CreateNoteDeps) {
+  return async (rawBody: string): Promise<HttpResponse> => {
+    let payload: unknown;
+    try {
+      payload = JSON.parse(rawBody);
+    } catch {
+      return json(400, { error: 'body must be valid JSON' });
+    }
+
+    try {
+      const note = await createNoteUsecase(payload, deps);
+      return json(201, { note });
+    } catch (error) {
+      if (error instanceof InvalidNoteError) {
+        return json(400, { error: 'invalid note', issues: error.issues });
+      }
+      if (error instanceof AppError) {
+        return json(error.statusCode, { error: error.message, code: error.code });
+      }
+      deps.log.error('unhandled error in create-note', { error: String(error) });
+      return json(500, { error: 'internal error' });
+    }
+  };
+}

package/templates/skeleton/node-service/services/api/src/handlers/list-notes.ts

@@ -0,0 +1,23 @@
+import { AppError } from '@app/shared';
+import type { Logger } from '@app/shared';
+import { listNotesUsecase, type ListNotesDeps } from '../usecases/list-notes.js';
+import type { HttpResponse } from './create-note.js';
+
+const json = (statusCode: number, body: unknown): HttpResponse => ({
+  statusCode,
+  body: JSON.stringify(body),
+});
+
+export function makeListNotesHandler(deps: ListNotesDeps & { log: Logger }) {
+  return async (): Promise<HttpResponse> => {
+    try {
+      return json(200, { notes: await listNotesUsecase(deps) });
+    } catch (error) {
+      if (error instanceof AppError) {
+        return json(error.statusCode, { error: error.message, code: error.code });
+      }
+      deps.log.error('unhandled error in list-notes', { error: String(error) });
+      return json(500, { error: 'internal error' });
+    }
+  };
+}

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

@@ -0,0 +1,47 @@
+// Composition root — the ONLY file with real wiring. Tests target the
+// factories with stub deps and never import this module.
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { z } from 'zod';
+import { JsonFileNoteStore } from '@app/db';
+import { createLogger, loadEnv } from '@app/shared';
+import { SpoolEventPublisher } from './adapters/spool-publisher.js';
+import { makeServer } from './server.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 env = loadEnv(
+  z.object({
+    PORT: z.coerce.number().int().positive().default(3000),
+    DATA_DIR: z.string().min(1).default('var/data'),
+    QUEUE_DIR: z.string().min(1).default('var/queue'),
+    STATIC_DIR: z.string().min(1).default(defaultStaticDir),
+  }),
+  process.env,
+);
+
+const log = createLogger({ service: 'api' });
+
+const server = makeServer(
+  {
+    notes: new JsonFileNoteStore(path.join(env.DATA_DIR, 'notes.json')),
+    events: new SpoolEventPublisher(env.QUEUE_DIR, () => `${Date.now()}-${randomUUID()}`),
+    newId: () => randomUUID(),
+    now: () => new Date().toISOString(),
+    log,
+  },
+  { staticDir: env.STATIC_DIR },
+);
+
+server.listen(env.PORT, () => {
+  log.info('api listening', { port: env.PORT });
+});

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

@@ -0,0 +1,89 @@
+// Thin HTTP shell around the handlers: routing, body collection, and (when
+// 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 { createServer, type Server } from 'node:http';
+import path from 'node:path';
+import type { CreateNoteDeps } from './usecases/create-note.js';
+import type { ListNotesDeps } from './usecases/list-notes.js';
+import { makeCreateNoteHandler } from './handlers/create-note.js';
+import { makeListNotesHandler } from './handlers/list-notes.js';
+import type { HttpResponse } from './handlers/create-note.js';
+
+export type ServerDeps = CreateNoteDeps & ListNotesDeps;
+
+export interface ServerOptions {
+  /** Directory of the built web bundle (apps/web/out). Unset = API only. */
+  staticDir?: string;
+}
+
+const CONTENT_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css',
+  '.js': 'text/javascript',
+  '.json': 'application/json',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.ico': 'image/x-icon',
+  '.txt': 'text/plain; charset=utf-8',
+};
+
+export function makeServer(deps: ServerDeps, options: ServerOptions = {}): Server {
+  const createNote = makeCreateNoteHandler(deps);
+  const listNotes = makeListNotesHandler(deps);
+
+  return createServer((request, response) => {
+    const respond = (result: HttpResponse) => {
+      response.writeHead(result.statusCode, { 'content-type': 'application/json' });
+      response.end(result.body);
+    };
+    const notFound = () => respond({ statusCode: 404, body: JSON.stringify({ error: 'not found' }) });
+
+    if (request.method === 'POST' && request.url === '/notes') {
+      const chunks: Buffer[] = [];
+      request.on('data', (chunk: Buffer) => chunks.push(chunk));
+      request.on('end', () => {
+        void createNote(Buffer.concat(chunks).toString('utf8')).then(respond);
+      });
+      return;
+    }
+
+    if (request.method === 'GET' && request.url === '/notes') {
+      void listNotes().then(respond);
+      return;
+    }
+
+    if (request.method === 'GET' && options.staticDir) {
+      void serveStatic(options.staticDir, request.url ?? '/', response, notFound);
+      return;
+    }
+
+    notFound();
+  });
+}
+
+async function serveStatic(
+  staticDir: string,
+  rawUrl: string,
+  response: import('node:http').ServerResponse,
+  notFound: () => void,
+): Promise<void> {
+  const pathname = decodeURIComponent(new URL(rawUrl, 'http://local').pathname);
+  const relative = pathname.endsWith('/') ? `${pathname}index.html` : pathname;
+  const resolved = path.normalize(path.join(staticDir, relative));
+  // Path-traversal guard: whatever the URL said, we never leave staticDir.
+  if (!resolved.startsWith(path.normalize(staticDir) + path.sep)) {
+    return notFound();
+  }
+  try {
+    const stats = await stat(resolved);
+    if (!stats.isFile()) return notFound();
+  } catch {
+    return notFound();
+  }
+  response.writeHead(200, {
+    'content-type': CONTENT_TYPES[path.extname(resolved)] ?? 'application/octet-stream',
+  });
+  createReadStream(resolved).pipe(response);
+}

package/templates/skeleton/node-service/services/api/src/usecases/create-note.ts

@@ -0,0 +1,30 @@
+// The usecase layer is mandatory: every business operation lives here, and
+// handlers call nothing below it. Dependencies are consumer-owned interfaces —
+// the usecase says what it needs, adapters satisfy it.
+import { createNote, makeNoteCreatedEvent, type Note, type NoteCreatedEvent } from '@app/core';
+import type { Logger } from '@app/shared';
+
+export interface NoteStore {
+  put(note: Note): Promise<void>;
+}
+
+export interface EventPublisher {
+  publish(event: NoteCreatedEvent): Promise<void>;
+}
+
+export interface CreateNoteDeps {
+  notes: NoteStore;
+  events: EventPublisher;
+  /** Id generation and the clock are decided here, never inside the core. */
+  newId(): string;
+  now(): string;
+  log: Logger;
+}
+
+export async function createNoteUsecase(input: unknown, deps: CreateNoteDeps): Promise<Note> {
+  const note = createNote(input, { id: deps.newId(), createdAt: deps.now() });
+  await deps.notes.put(note);
+  await deps.events.publish(makeNoteCreatedEvent(note));
+  deps.log.info('note created', { noteId: note.id, slug: note.slug });
+  return note;
+}

package/templates/skeleton/node-service/services/api/src/usecases/list-notes.ts

@@ -0,0 +1,14 @@
+// Even a trivial read goes through a usecase — the uniformity is the rule.
+import type { Note } from '@app/core';
+
+export interface NoteLister {
+  list(): Promise<Note[]>;
+}
+
+export interface ListNotesDeps {
+  notes: NoteLister;
+}
+
+export async function listNotesUsecase(deps: ListNotesDeps): Promise<Note[]> {
+  return deps.notes.list();
+}

package/templates/skeleton/node-service/services/api/test/create-note.handler.test.ts

@@ -0,0 +1,64 @@
+import { AppError, createLogger } from '@app/shared';
+import { describe, expect, it } from 'vitest';
+import { makeCreateNoteHandler } from '../src/handlers/create-note.js';
+import type { CreateNoteDeps } from '../src/usecases/create-note.js';
+
+function stubDeps(overrides: Partial<CreateNoteDeps> = {}) {
+  const deps: CreateNoteDeps = {
+    notes: { put: async () => {} },
+    events: { publish: async () => {} },
+    newId: () => 'fixed-id',
+    now: () => '2024-01-01T00:00:00.000Z',
+    log: createLogger({}, () => {}),
+    ...overrides,
+  };
+  return deps;
+}
+
+describe('POST /notes handler', () => {
+  it('returns 201 with the created note', async () => {
+    const handler = makeCreateNoteHandler(stubDeps());
+    const result = await handler(JSON.stringify({ title: 'Hello' }));
+    expect(result.statusCode).toBe(201);
+    expect(JSON.parse(result.body)).toMatchObject({
+      note: { id: 'fixed-id', slug: 'hello', createdAt: '2024-01-01T00:00:00.000Z' },
+    });
+  });
+
+  it('returns 400 for malformed JSON', async () => {
+    const result = await makeCreateNoteHandler(stubDeps())('{not json');
+    expect(result.statusCode).toBe(400);
+  });
+
+  it('returns 400 with issues for invalid input', async () => {
+    const result = await makeCreateNoteHandler(stubDeps())(JSON.stringify({ title: '' }));
+    expect(result.statusCode).toBe(400);
+    expect(JSON.parse(result.body).issues.join(' ')).toMatch(/title/);
+  });
+
+  it('maps typed errors to their status code', async () => {
+    const handler = makeCreateNoteHandler(
+      stubDeps({
+        notes: {
+          put: () => Promise.reject(new AppError('conflict', { statusCode: 409, code: 'DUP' })),
+        },
+      }),
+    );
+    const result = await handler(JSON.stringify({ title: 'T' }));
+    expect(result.statusCode).toBe(409);
+  });
+
+  it('hides unknown errors behind a 500 and logs them', async () => {
+    const logs: string[] = [];
+    const handler = makeCreateNoteHandler(
+      stubDeps({
+        notes: { put: () => Promise.reject(new Error('secret detail')) },
+        log: createLogger({}, (line) => logs.push(line)),
+      }),
+    );
+    const result = await handler(JSON.stringify({ title: 'T' }));
+    expect(result.statusCode).toBe(500);
+    expect(result.body).not.toContain('secret detail');
+    expect(logs.join('\n')).toContain('secret detail');
+  });
+});

package/templates/skeleton/node-service/services/api/test/create-note.usecase.test.ts

@@ -0,0 +1,43 @@
+import { InvalidNoteError, type Note, type NoteCreatedEvent } from '@app/core';
+import { createLogger } from '@app/shared';
+import { describe, expect, it } from 'vitest';
+import { createNoteUsecase, type CreateNoteDeps } from '../src/usecases/create-note.js';
+
+function stubDeps() {
+  const stored: Note[] = [];
+  const published: NoteCreatedEvent[] = [];
+  const logs: string[] = [];
+  const deps: CreateNoteDeps = {
+    notes: { put: async (note) => void stored.push(note) },
+    events: { publish: async (event) => void published.push(event) },
+    newId: () => 'fixed-id',
+    now: () => '2024-01-01T00:00:00.000Z',
+    log: createLogger({}, (line) => logs.push(line)),
+  };
+  return { deps, stored, published, logs };
+}
+
+describe('createNoteUsecase', () => {
+  it('creates, stores, publishes, and logs', async () => {
+    const { deps, stored, published, logs } = stubDeps();
+    const note = await createNoteUsecase({ title: 'Hello World' }, deps);
+    expect(note).toMatchObject({ id: 'fixed-id', slug: 'hello-world' });
+    expect(stored).toEqual([note]);
+    expect(published).toEqual([{ type: 'note.created', note }]);
+    expect(logs.join('\n')).toContain('fixed-id');
+  });
+
+  it('rejects invalid input before any side effect', async () => {
+    const { deps, stored, published } = stubDeps();
+    await expect(createNoteUsecase({ title: '' }, deps)).rejects.toThrow(InvalidNoteError);
+    expect(stored).toEqual([]);
+    expect(published).toEqual([]);
+  });
+
+  it('propagates store failures and does not publish', async () => {
+    const { deps, published } = stubDeps();
+    deps.notes = { put: () => Promise.reject(new Error('disk full')) };
+    await expect(createNoteUsecase({ title: 'T' }, deps)).rejects.toThrow('disk full');
+    expect(published).toEqual([]);
+  });
+});

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

@@ -0,0 +1,48 @@
+import { AppError, createLogger } from '@app/shared';
+import { describe, expect, it } from 'vitest';
+import { makeListNotesHandler } from '../src/handlers/list-notes.js';
+import { listNotesUsecase } from '../src/usecases/list-notes.js';
+
+const note = {
+  id: 'n1',
+  title: 'Hello',
+  slug: 'hello',
+  tags: [],
+  createdAt: '2024-01-01T00:00:00.000Z',
+};
+
+describe('listNotesUsecase', () => {
+  it('returns what the store lists', async () => {
+    expect(await listNotesUsecase({ notes: { list: async () => [note] } })).toEqual([note]);
+  });
+});
+
+describe('GET /notes handler', () => {
+  it('returns 200 with the notes', async () => {
+    const handler = makeListNotesHandler({
+      notes: { list: async () => [note] },
+      log: createLogger({}, () => {}),
+    });
+    const result = await handler();
+    expect(result.statusCode).toBe(200);
+    expect(JSON.parse(result.body)).toEqual({ notes: [note] });
+  });
+
+  it('maps typed errors and hides unknown ones', async () => {
+    const typed = makeListNotesHandler({
+      notes: { list: () => Promise.reject(new AppError('nope', { statusCode: 503, code: 'X' })) },
+      log: createLogger({}, () => {}),
+    });
+    expect((await typed()).statusCode).toBe(503);
+
+    const logs: string[] = [];
+    const unknown = makeListNotesHandler({
+      notes: { list: () => Promise.reject(new Error('secret')) },
+      log: createLogger({}, (line) => logs.push(line)),
+    });
+    const result = await unknown();
+    expect(result.statusCode).toBe(500);
+    expect(result.body).not.toContain('secret');
+    expect(logs.join('')).toContain('secret');
+  });
+});

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

@@ -0,0 +1,123 @@
+// 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 { tmpdir } from 'node:os';
+import type { AddressInfo } from 'node:net';
+import path from 'node:path';
+import { JsonFileNoteStore } from '@app/db';
+import { createLogger } from '@app/shared';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { Server } from 'node:http';
+import { SpoolEventPublisher } from '../src/adapters/spool-publisher.js';
+import { makeServer } from '../src/server.js';
+
+let dir: string;
+let server: Server;
+let baseUrl: string;
+
+beforeEach(async () => {
+  dir = await mkdtemp(path.join(tmpdir(), 'api-int-'));
+  let n = 0;
+  server = makeServer({
+    notes: new JsonFileNoteStore(path.join(dir, 'data', 'notes.json')),
+    events: new SpoolEventPublisher(path.join(dir, 'queue'), () => `msg-${++n}`),
+    newId: () => `id-${++n}`,
+    now: () => '2024-01-01T00:00:00.000Z',
+    log: createLogger({}, () => {}),
+  });
+  await new Promise<void>((resolve) => server.listen(0, resolve));
+  baseUrl = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+});
+
+afterEach(async () => {
+  await new Promise((resolve) => server.close(resolve));
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('the service end to end', () => {
+  it('creates a note over HTTP, persists it, and spools the event', async () => {
+    const response = await fetch(`${baseUrl}/notes`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ title: 'Integration proof', tags: ['e2e'] }),
+    });
+    expect(response.status).toBe(201);
+    const { note } = (await response.json()) as { note: { slug: string } };
+    expect(note.slug).toBe('integration-proof');
+
+    expect(await readdir(path.join(dir, 'queue'))).toHaveLength(1);
+    expect(await readdir(path.join(dir, 'data'))).toContain('notes.json');
+  });
+
+  it('rejects invalid input with 400', async () => {
+    const response = await fetch(`${baseUrl}/notes`, {
+      method: 'POST',
+      body: JSON.stringify({ title: '' }),
+    });
+    expect(response.status).toBe(400);
+  });
+
+  it('404s unknown routes', async () => {
+    const response = await fetch(`${baseUrl}/other`);
+    expect(response.status).toBe(404);
+  });
+
+  it('lists created notes back on GET /notes (the UI read path)', async () => {
+    for (const title of ['First note', 'Second note']) {
+      await fetch(`${baseUrl}/notes`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ title }),
+      });
+    }
+    const response = await fetch(`${baseUrl}/notes`);
+    expect(response.status).toBe(200);
+    const { notes } = (await response.json()) as { notes: Array<{ title: string }> };
+    expect(notes).toHaveLength(2);
+  });
+});
+
+describe('static serving (the built web bundle)', () => {
+  let staticServer: Server;
+  let staticBase: string;
+
+  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}`;
+  });
+
+  afterEach(async () => {
+    await new Promise((resolve) => staticServer.close(resolve));
+  });
+
+  it('serves index.html at the root', async () => {
+    const response = await fetch(staticBase + '/');
+    expect(response.status).toBe(200);
+    expect(response.headers.get('content-type')).toContain('text/html');
+    expect(await response.text()).toContain('web shell');
+  });
+
+  it('refuses path traversal out of the static dir', async () => {
+    await writeFile(path.join(dir, 'secret.txt'), 'nope');
+    const response = await fetch(staticBase + '/%2e%2e/secret.txt');
+    expect(response.status).toBe(404);
+  });
+
+  it('API routes still win over static files', async () => {
+    const response = await fetch(staticBase + '/notes');
+    expect(response.status).toBe(200);
+    expect(response.headers.get('content-type')).toContain('application/json');
+  });
+});

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

@@ -0,0 +1,32 @@
+import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { createNote, makeNoteCreatedEvent } from '@app/core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { SpoolEventPublisher } from '../src/adapters/spool-publisher.js';
+
+let dir: string;
+
+beforeEach(async () => {
+  dir = await mkdtemp(path.join(tmpdir(), 'spool-'));
+});
+
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('SpoolEventPublisher', () => {
+  it('writes one complete JSON message file per event', async () => {
+    const queueDir = path.join(dir, 'queue');
+    let n = 0;
+    const publisher = new SpoolEventPublisher(queueDir, () => `msg-${++n}`);
+    const note = createNote({ title: 'Hi' }, { id: 'n1', createdAt: '2024-01-01T00:00:00.000Z' });
+    const event = makeNoteCreatedEvent(note);
+    await publisher.publish(event);
+    await publisher.publish(event);
+
+    const files = (await readdir(queueDir)).sort();
+    expect(files).toEqual(['msg-1.json', 'msg-2.json']);
+    expect(JSON.parse(await readFile(path.join(queueDir, 'msg-1.json'), 'utf8'))).toEqual(event);
+  });
+});

package/templates/skeleton/node-service/services/worker/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@app/worker",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/main.ts",
+  "types": "src/main.ts",
+  "scripts": {
+    "start": "tsx src/main.ts"
+  },
+  "dependencies": {
+    "@app/core": "workspace:*",
+    "@app/shared": "workspace:*",
+    "zod": "^4.4.3"
+  }
+}

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

@@ -0,0 +1,28 @@
+// Composition root — the worker as a long-running process polling the spool.
+import { z } from 'zod';
+import { createLogger, loadEnv } from '@app/shared';
+import { processNoteCreated } from './usecases/process-note-created.js';
+import { processSpoolOnce } from './spool.js';
+
+const env = loadEnv(
+  z.object({
+    QUEUE_DIR: z.string().min(1).default('var/queue'),
+    DLQ_DIR: z.string().min(1).default('var/dlq'),
+    POLL_INTERVAL_MS: z.coerce.number().int().positive().default(1000),
+  }),
+  process.env,
+);
+
+const log = createLogger({ service: 'worker' });
+const config = { queueDir: env.QUEUE_DIR, dlqDir: env.DLQ_DIR, maxAttempts: 3 };
+const deps = { log, process: (raw: string) => processNoteCreated(raw, { log }) };
+
+log.info('worker polling', { queueDir: env.QUEUE_DIR, intervalMs: env.POLL_INTERVAL_MS });
+
+const tick = async () => {
+  const processed = await processSpoolOnce(config, deps);
+  if (processed > 0) log.info('spool pass complete', { processed });
+  setTimeout(() => void tick(), env.POLL_INTERVAL_MS);
+};
+
+void tick();