create-agent-rig 0.1.0

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

@@ -0,0 +1,60 @@
+// A directory is the queue: one JSON file per message. Retries are encoded in
+// the filename (msg.json → msg.retry1.json → …); after maxAttempts the file
+// moves to the DLQ directory and an alarm line is logged. Same discipline as
+// any managed queue — visible failure, bounded retries, no silent loss.
+import { mkdir, readFile, readdir, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import type { Logger } from '@app/shared';
+
+export interface SpoolConfig {
+  queueDir: string;
+  dlqDir: string;
+  /** Total attempts a message gets before it is dead-lettered. */
+  maxAttempts: number;
+}
+
+export interface SpoolDeps {
+  log: Logger;
+  process(raw: string): Promise<void>;
+}
+
+const RETRY_PATTERN = /\.retry(\d+)\.json$/;
+
+const attemptOf = (name: string): number => {
+  const match = RETRY_PATTERN.exec(name);
+  return match ? Number.parseInt(match[1]!, 10) + 1 : 1;
+};
+
+const withRetrySuffix = (name: string, attempt: number): string =>
+  name.replace(/(\.retry\d+)?\.json$/, `.retry${attempt}.json`);
+
+/** One pass over the queue. Returns how many messages were processed successfully. */
+export async function processSpoolOnce(config: SpoolConfig, deps: SpoolDeps): Promise<number> {
+  await mkdir(config.queueDir, { recursive: true });
+  await mkdir(config.dlqDir, { recursive: true });
+  let processed = 0;
+
+  const entries = (await readdir(config.queueDir)).filter((name) => name.endsWith('.json')).sort();
+  for (const name of entries) {
+    const file = path.join(config.queueDir, name);
+    try {
+      await deps.process(await readFile(file, 'utf8'));
+      await rm(file);
+      processed += 1;
+    } catch (error) {
+      const attempt = attemptOf(name);
+      if (attempt >= config.maxAttempts) {
+        await rename(file, path.join(config.dlqDir, name));
+        deps.log.error('ALARM: message dead-lettered', {
+          file: name,
+          attempts: attempt,
+          error: String(error),
+        });
+      } else {
+        await rename(file, path.join(config.queueDir, withRetrySuffix(name, attempt)));
+        deps.log.warn('message failed, will retry', { file: name, attempt });
+      }
+    }
+  }
+  return processed;
+}

package/templates/skeleton/node-service/services/worker/src/usecases/process-note-created.ts

@@ -0,0 +1,38 @@
+// Queue discipline: validate the message against the shared event schema; a
+// message that does not parse is poison — throw, let the spool retry it, and
+// after the retry budget the DLQ directory (watched by the alarm log line)
+// catches it. Never swallow poison.
+import { NoteCreatedEventSchema, type NoteCreatedEvent } from '@app/core';
+import { ValidationError, type Logger } from '@app/shared';
+
+export interface ProcessDeps {
+  log: Logger;
+}
+
+export function parseNoteCreatedEvent(raw: string): NoteCreatedEvent {
+  let candidate: unknown;
+  try {
+    candidate = JSON.parse(raw);
+  } catch {
+    throw new ValidationError('message body is not JSON');
+  }
+  const parsed = NoteCreatedEventSchema.safeParse(candidate);
+  if (!parsed.success) {
+    throw new ValidationError(
+      'message is not a note.created event',
+      parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`),
+    );
+  }
+  return parsed.data;
+}
+
+export async function processNoteCreated(raw: string, deps: ProcessDeps): Promise<void> {
+  const event = parseNoteCreatedEvent(raw);
+  // The skeleton's "processing" is deliberately small: acknowledge the note.
+  // Replace this with real downstream work; keep the validate-first shape.
+  deps.log.info('note.created processed', {
+    noteId: event.note.id,
+    slug: event.note.slug,
+    tagCount: event.note.tags.length,
+  });
+}

package/templates/skeleton/node-service/services/worker/test/process-note-created.test.ts

@@ -0,0 +1,34 @@
+import { createNote, makeNoteCreatedEvent } from '@app/core';
+import { ValidationError, createLogger } from '@app/shared';
+import { describe, expect, it } from 'vitest';
+import { parseNoteCreatedEvent, processNoteCreated } from '../src/usecases/process-note-created.js';
+
+const note = createNote({ title: 'Hello' }, { id: 'n1', createdAt: '2024-01-01T00:00:00.000Z' });
+const validBody = JSON.stringify(makeNoteCreatedEvent(note));
+
+describe('parseNoteCreatedEvent', () => {
+  it('parses a valid event', () => {
+    expect(parseNoteCreatedEvent(validBody).note.id).toBe('n1');
+  });
+
+  it('throws ValidationError for non-JSON bodies', () => {
+    expect(() => parseNoteCreatedEvent('not json')).toThrow(ValidationError);
+  });
+
+  it('throws ValidationError for JSON that is not a note.created event', () => {
+    expect(() => parseNoteCreatedEvent(JSON.stringify({ type: 'other' }))).toThrow(ValidationError);
+  });
+});
+
+describe('processNoteCreated', () => {
+  it('logs the processed note', async () => {
+    const lines: string[] = [];
+    await processNoteCreated(validBody, { log: createLogger({}, (line) => lines.push(line)) });
+    expect(lines.join('\n')).toContain('n1');
+  });
+
+  it('lets poison messages throw — the DLQ is the safety net, not a catch block', async () => {
+    const log = createLogger({}, () => {});
+    await expect(processNoteCreated('poison', { log })).rejects.toThrow(ValidationError);
+  });
+});

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

@@ -0,0 +1,76 @@
+import { mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { createNote, makeNoteCreatedEvent } from '@app/core';
+import { createLogger } from '@app/shared';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { processNoteCreated } from '../src/usecases/process-note-created.js';
+import { processSpoolOnce, type SpoolConfig } from '../src/spool.js';
+
+const note = createNote({ title: 'Hello' }, { id: 'n1', createdAt: '2024-01-01T00:00:00.000Z' });
+const validBody = JSON.stringify(makeNoteCreatedEvent(note));
+
+let dir: string;
+let config: SpoolConfig;
+
+beforeEach(async () => {
+  dir = await mkdtemp(path.join(tmpdir(), 'spool-worker-'));
+  config = {
+    queueDir: path.join(dir, 'queue'),
+    dlqDir: path.join(dir, 'dlq'),
+    maxAttempts: 3,
+  };
+});
+
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+function makeDeps() {
+  const lines: string[] = [];
+  const log = createLogger({}, (line) => lines.push(line));
+  return { deps: { log, process: (raw: string) => processNoteCreated(raw, { log }) }, lines };
+}
+
+async function spool(name: string, content: string) {
+  await writeFile(path.join(config.queueDir, name), content);
+}
+
+describe('processSpoolOnce', () => {
+  it('processes valid messages and removes them', async () => {
+    const { deps, lines } = makeDeps();
+    await processSpoolOnce(config, deps); // creates the dirs
+    await spool('m1.json', validBody);
+    await spool('m2.json', validBody);
+
+    expect(await processSpoolOnce(config, deps)).toBe(2);
+    expect(await readdir(config.queueDir)).toEqual([]);
+    expect(await readdir(config.dlqDir)).toEqual([]);
+    expect(lines.filter((l) => l.includes('note.created processed'))).toHaveLength(2);
+  });
+
+  it('retries poison, then dead-letters it with an ALARM after maxAttempts', async () => {
+    const { deps, lines } = makeDeps();
+    await processSpoolOnce(config, deps);
+    await spool('poison.json', 'not json');
+
+    expect(await processSpoolOnce(config, deps)).toBe(0); // attempt 1 → retry1
+    expect(await readdir(config.queueDir)).toEqual(['poison.retry1.json']);
+    expect(await processSpoolOnce(config, deps)).toBe(0); // attempt 2 → retry2
+    expect(await readdir(config.queueDir)).toEqual(['poison.retry2.json']);
+    expect(await processSpoolOnce(config, deps)).toBe(0); // attempt 3 → DLQ
+    expect(await readdir(config.queueDir)).toEqual([]);
+    expect(await readdir(config.dlqDir)).toEqual(['poison.retry2.json']);
+    expect(lines.some((line) => line.includes('ALARM'))).toBe(true);
+  });
+
+  it('keeps processing good messages when one is poison', async () => {
+    const { deps } = makeDeps();
+    await processSpoolOnce(config, deps);
+    await spool('a-poison.json', '{broken');
+    await spool('b-good.json', validBody);
+
+    expect(await processSpoolOnce(config, deps)).toBe(1);
+    expect(await readdir(config.queueDir)).toEqual(['a-poison.retry1.json']);
+  });
+});

package/templates/skeleton/node-service/tsconfig.base.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  }
+}

package/templates/skeleton/node-service/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": [
+    "packages/*/src/**/*.ts",
+    "packages/*/test/**/*.ts",
+    "services/*/src/**/*.ts",
+    "services/*/test/**/*.ts",
+    "vitest.config.ts"
+  ]
+}

package/templates/skeleton/node-service/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: [
+      'packages/*/test/**/*.test.ts',
+      'services/*/test/**/*.test.ts',
+      'apps/*/test/**/*.test.ts',
+    ],
+    testTimeout: 30_000,
+  },
+});