create-agent-rig 0.1.0

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

@@ -0,0 +1,74 @@
+# __PROJECT_NAME__
+
+A plain Node service generated by `create-agent-rig`, target
+`node-service`. Same architecture as every target — pure core, mandatory
+usecase layer, single-owner storage model, queue with DLQ discipline — with no
+cloud: HTTP via `node:http`, storage in a JSON file, the queue as a spool
+directory, the worker as a process. This project is yours: **delete what you
+don't need.**
+
+## Layout
+
+```
+packages/core/     pure domain: zod schemas + createNote()  (no I/O — hook-enforced)
+packages/shared/   logger, loadEnv(zod), typed errors
+packages/db/       JsonFileNoteStore — the only code touching the data file
+services/api/      POST /notes + GET /notes: payload → handler → usecase → model;
+                   also serves the built web bundle (no second runtime)
+services/worker/   spool consumer (3 attempts → var/dlq + ALARM log line)
+apps/web/          static Next export; validates with the SAME core schema the
+                   server trusts (imports core+shared only — hook-enforced)
+.claude/           the agent operating system: rules, gates, blocking hooks
+```
+
+The agent-facing map is `CLAUDE.md`; the rules live in `.claude/rules/`.
+
+## Run it
+
+```sh
+pnpm install
+pnpm test
+pnpm lint
+pnpm typecheck
+pnpm check       # all of the above
+```
+
+Start the service (two processes; build the web bundle first to get the UI):
+
+```sh
+pnpm build:web      # static Next export → apps/web/out
+pnpm start:api      # PORT=3000; serves the API and apps/web/out at /
+pnpm start:worker   # polls var/queue, dead-letters into var/dlq
+```
+
+Open http://localhost:3000/ — the form validates with the same core schema
+the server applies again on POST.
+
+Configuration is environment-first (`PORT`, `DATA_DIR`, `QUEUE_DIR`, `DLQ_DIR`,
+`POLL_INTERVAL_MS`) with working defaults — see each service's `main.ts`.
+
+## Verify runtime health (CI-green ≠ runtime-healthy)
+
+```sh
+curl -s -X POST localhost:3000/notes \
+  -H 'content-type: application/json' \
+  -d '{"title":"smoke test","tags":["deploy"]}'
+# expect: HTTP 201 with { "note": { … } }
+```
+
+Then confirm the pipeline: the worker logs `note.created processed`, and
+**`var/dlq/` stays empty** (an `ALARM` log line means a message was
+dead-lettered). On regression: roll back to the previous revision first,
+diagnose second.
+
+## Boundaries (the short version)
+
+- Every request follows `payload → handler → usecase → model`. The usecase
+  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.
+- 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.
+
+See `.claude/rules/architecture.md` for the full rules.

package/templates/skeleton/node-service/apps/web/next.config.mjs

@@ -0,0 +1,17 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // Static export: one build, no second runtime — the API server (or a CDN)
+  // serves the bundle. See README for how this target serves it.
+  output: 'export',
+  // The core ships as TypeScript source; Next transpiles it for the browser.
+  transpilePackages: ['@app/core'],
+  // The core uses NodeNext-style relative imports ("./note.js" resolving to
+  // note.ts). Turbopack cannot map that, so the build runs webpack (see the
+  // build script) with the standard extension alias.
+  webpack: (config) => {
+    config.resolve.extensionAlias = { '.js': ['.ts', '.tsx', '.js'] };
+    return config;
+  },
+};
+
+export default nextConfig;

package/templates/skeleton/node-service/apps/web/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@app/web",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --port 3001 --webpack",
+    "build": "next build --webpack"
+  },
+  "dependencies": {
+    "@app/core": "workspace:*",
+    "next": "^16.2.11",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3"
+  }
+}

package/templates/skeleton/node-service/apps/web/src/app/layout.tsx

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+
+// Deliberately unstyled: a starter's frontend is scaffolding, not a product.
+// Polish belongs in the mechanism (the shared validation, the boundary hook),
+// not in the pixels — replace all of this freely.
+export const metadata = {
+  title: '__PROJECT_NAME__',
+  description: 'Notes — generated by create-agent-rig',
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/templates/skeleton/node-service/apps/web/src/app/page.tsx

@@ -0,0 +1,96 @@
+'use client';
+// One page, one point: the SAME domain schema validates here (instant
+// feedback) and on the server (trust). See src/lib/validate.ts.
+import { useCallback, useEffect, useState } from 'react';
+import type { Note } from '@app/core';
+import { createNote, listNotes } from '../lib/api';
+import { validateNewNote } from '../lib/validate';
+
+export default function NotesPage() {
+  const [title, setTitle] = useState('');
+  const [tags, setTags] = useState('');
+  const [issues, setIssues] = useState<string[]>([]);
+  const [notes, setNotes] = useState<Note[]>([]);
+  const [status, setStatus] = useState<string>('');
+
+  const refresh = useCallback(async () => {
+    try {
+      setNotes(await listNotes());
+      setStatus('');
+    } catch (error) {
+      setStatus(`could not load notes: ${String(error)}`);
+    }
+  }, []);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  async function onSubmit(event: React.FormEvent) {
+    event.preventDefault();
+    const input = {
+      title,
+      tags: tags
+        .split(',')
+        .map((tag) => tag.trim())
+        .filter(Boolean),
+    };
+    // Client-side: the same core schema the server will apply again.
+    const verdict = validateNewNote(input);
+    setIssues(verdict.issues);
+    if (!verdict.ok) return;
+    try {
+      await createNote(input);
+      setTitle('');
+      setTags('');
+      await refresh();
+    } catch (error) {
+      setIssues([String(error)]);
+    }
+  }
+
+  return (
+    <main>
+      <h1>Notes</h1>
+      <p>
+        The form validates with the <em>same</em> core function the server
+        trusts — one schema, both sides of the wire.
+      </p>
+
+      <form onSubmit={onSubmit}>
+        <label>
+          Title{' '}
+          <input
+            name="title"
+            value={title}
+            onChange={(event) => setTitle(event.target.value)}
+          />
+        </label>{' '}
+        <label>
+          Tags (comma-separated){' '}
+          <input name="tags" value={tags} onChange={(event) => setTags(event.target.value)} />
+        </label>{' '}
+        <button type="submit">Create</button>
+      </form>
+
+      {issues.length > 0 && (
+        <ul role="alert">
+          {issues.map((issue) => (
+            <li key={issue}>{issue}</li>
+          ))}
+        </ul>
+      )}
+      {status && <p role="status">{status}</p>}
+
+      <h2>Existing</h2>
+      <ul>
+        {notes.map((note) => (
+          <li key={note.id}>
+            <strong>{note.title}</strong> <code>{note.slug}</code>{' '}
+            <small>{note.tags.join(', ')}</small>
+          </li>
+        ))}
+      </ul>
+    </main>
+  );
+}

package/templates/skeleton/node-service/apps/web/src/lib/api.ts

@@ -0,0 +1,29 @@
+// The web talks to the backend over HTTP only — never by importing it
+// (the guard-web-boundary hook refuses such imports at the tool layer).
+import type { Note } from '@app/core';
+
+// Same-origin by default (the API server serves this bundle); set
+// NEXT_PUBLIC_API_URL at build time when the API lives elsewhere.
+const base = process.env.NEXT_PUBLIC_API_URL ?? '';
+
+export async function createNote(input: { title: string; tags: string[] }): Promise<Note> {
+  const response = await fetch(`${base}/notes`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(input),
+  });
+  const body = (await response.json()) as { note?: Note; error?: string; issues?: string[] };
+  if (!response.ok || !body.note) {
+    throw new Error(body.issues?.join('; ') ?? body.error ?? `HTTP ${response.status}`);
+  }
+  return body.note;
+}
+
+export async function listNotes(): Promise<Note[]> {
+  const response = await fetch(`${base}/notes`);
+  const body = (await response.json()) as { notes?: Note[]; error?: string };
+  if (!response.ok || !body.notes) {
+    throw new Error(body.error ?? `HTTP ${response.status}`);
+  }
+  return body.notes;
+}

package/templates/skeleton/node-service/apps/web/src/lib/validate.ts

@@ -0,0 +1,23 @@
+// The load-bearing import of this whole app: the browser validates with the
+// SAME schema the server trusts. Client-side for instant feedback,
+// server-side for trust — one function, two sides of the wire. This is what
+// core purity buys: `@app/core` has no I/O, so it runs anywhere.
+import { NewNoteSchema } from '@app/core';
+
+export interface ValidationResult {
+  ok: boolean;
+  issues: string[];
+}
+
+export function validateNewNote(input: unknown): ValidationResult {
+  const parsed = NewNoteSchema.safeParse(input);
+  if (parsed.success) {
+    return { ok: true, issues: [] };
+  }
+  return {
+    ok: false,
+    issues: parsed.error.issues.map(
+      (issue) => `${issue.path.join('.') || 'input'}: ${issue.message}`,
+    ),
+  };
+}

package/templates/skeleton/node-service/apps/web/test/shared-validation.test.ts

@@ -0,0 +1,38 @@
+// THE load-bearing test of the frontend (web brief §5): the browser-side
+// validator and the server-side schema must be the same decision procedure.
+// No jsdom, no rendering — the boundary is the point, not the pixels.
+import { InvalidNoteError, NewNoteSchema, createNote } from '@app/core';
+import { describe, expect, it } from 'vitest';
+import { validateNewNote } from '../src/lib/validate';
+
+const identity = { id: 'n1', createdAt: '2024-01-01T00:00:00.000Z' };
+
+const CASES: Array<{ name: string; input: unknown }> = [
+  { name: 'valid minimal', input: { title: 'Hello' } },
+  { name: 'valid with tags', input: { title: 'Hello', tags: ['a', 'b'] } },
+  { name: 'empty title', input: { title: '' } },
+  { name: 'whitespace title', input: { title: '   ' } },
+  { name: 'title too long', input: { title: 'x'.repeat(201) } },
+  { name: 'too many tags', input: { title: 'T', tags: Array.from({ length: 11 }, (_, i) => `${i}`) } },
+  { name: 'empty tag', input: { title: 'T', tags: [''] } },
+  { name: 'wrong types', input: { title: 42 } },
+  { name: 'not an object', input: 'nope' },
+];
+
+describe('one schema, both sides of the wire', () => {
+  for (const { name, input } of CASES) {
+    it(`web and core agree on: ${name}`, () => {
+      const webVerdict = validateNewNote(input);
+      const coreVerdict = NewNoteSchema.safeParse(input);
+      expect(webVerdict.ok).toBe(coreVerdict.success);
+
+      // …and the domain function (used by the API usecase) agrees with both.
+      if (coreVerdict.success) {
+        expect(() => createNote(input, identity)).not.toThrow();
+      } else {
+        expect(() => createNote(input, identity)).toThrow(InvalidNoteError);
+        expect(webVerdict.issues.length).toBeGreaterThan(0);
+      }
+    });
+  }
+});

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

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "jsx": "preserve",
+    "lib": ["dom", "dom.iterable", "es2022"],
+    "noEmit": true,
+    "allowJs": true,
+    "plugins": [{ "name": "next" }]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "test/**/*.ts"],
+  "exclude": ["node_modules", "out", ".next"]
+}

package/templates/skeleton/node-service/eslint.config.mjs

@@ -0,0 +1,20 @@
+import eslint from '@eslint/js';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  {
+    ignores: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/coverage/**',
+      '**/var/**',
+      '**/.next/**',
+      '**/out/**',
+      '**/next-env.d.ts',
+    ],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  { languageOptions: { globals: globals.node } },
+);

package/templates/skeleton/node-service/gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+coverage/
+*.tsbuildinfo
+.DS_Store
+var/
+.next/
+out/
+next-env.d.ts

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

@@ -0,0 +1,28 @@
+{
+  "name": "@app/root",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json && tsc -p apps/web/tsconfig.json",
+    "build:web": "pnpm --filter @app/web build",
+    "start:api": "pnpm --filter @app/api start",
+    "start:worker": "pnpm --filter @app/worker start",
+    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm build:web"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.1.1",
+    "eslint": "^10.7.0",
+    "globals": "^17.7.0",
+    "tsx": "^4.23.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.65.0",
+    "vitest": "^4.1.10"
+  }
+}

package/templates/skeleton/node-service/packages/core/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@app/core",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "dependencies": {
+    "zod": "^4.4.3"
+  }
+}

package/templates/skeleton/node-service/packages/core/src/events.ts

@@ -0,0 +1,14 @@
+// Domain event vocabulary. The schema is the contract between the API (producer)
+// and the worker (consumer) — both sides validate against it.
+import { z } from 'zod';
+import { NoteSchema, type Note } from './note.js';
+
+export const NoteCreatedEventSchema = z.object({
+  type: z.literal('note.created'),
+  note: NoteSchema,
+});
+export type NoteCreatedEvent = z.infer<typeof NoteCreatedEventSchema>;
+
+export function makeNoteCreatedEvent(note: Note): NoteCreatedEvent {
+  return { type: 'note.created', note };
+}

package/templates/skeleton/node-service/packages/core/src/index.ts

@@ -0,0 +1,15 @@
+export {
+  NewNoteSchema,
+  NoteSchema,
+  InvalidNoteError,
+  createNote,
+  slugify,
+  type NewNote,
+  type Note,
+  type NoteIdentity,
+} from './note.js';
+export {
+  NoteCreatedEventSchema,
+  makeNoteCreatedEvent,
+  type NoteCreatedEvent,
+} from './events.js';

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

@@ -0,0 +1,69 @@
+// The domain core is pure: no I/O, no clock, no randomness, no environment.
+// "Now" and "a new id" are decided by the caller (the usecase layer) and enter
+// as arguments. The guard-core-purity hook enforces this at the tool layer.
+import { z } from 'zod';
+
+export const NewNoteSchema = z.object({
+  title: z.string().trim().min(1, 'title must not be empty').max(200, 'title too long'),
+  tags: z.array(z.string().trim().min(1).max(40)).max(10).default([]),
+});
+export type NewNote = z.infer<typeof NewNoteSchema>;
+
+export const NoteSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().min(1),
+  slug: z.string().min(1),
+  tags: z.array(z.string()),
+  createdAt: z.string().min(1),
+});
+export type Note = z.infer<typeof NoteSchema>;
+
+/** Thrown when input fails domain validation. The core owns its own error type. */
+export class InvalidNoteError extends Error {
+  readonly issues: readonly string[];
+
+  constructor(issues: readonly string[]) {
+    super(`invalid note: ${issues.join('; ')}`);
+    this.name = 'InvalidNoteError';
+    this.issues = issues;
+  }
+}
+
+export interface NoteIdentity {
+  /** Generated by the caller — the core never invents ids. */
+  id: string;
+  /** ISO-8601 timestamp decided by the caller — the core never reads the clock. */
+  createdAt: string;
+}
+
+/**
+ * The one domain function: validate raw input and construct a Note.
+ * Deterministic — identical arguments always yield an identical note.
+ */
+export function createNote(input: unknown, identity: NoteIdentity): Note {
+  const parsed = NewNoteSchema.safeParse(input);
+  if (!parsed.success) {
+    throw new InvalidNoteError(
+      parsed.error.issues.map((issue) => `${issue.path.join('.') || 'input'}: ${issue.message}`),
+    );
+  }
+  const { title, tags } = parsed.data;
+  return {
+    id: identity.id,
+    title,
+    slug: slugify(title),
+    tags: [...new Set(tags)],
+    createdAt: identity.createdAt,
+  };
+}
+
+/** Lowercased, hyphen-separated, ascii-ish slug. Pure string work. */
+export function slugify(title: string): string {
+  const slug = title
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '') // strip combining marks left by NFKD
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug.length > 0 ? slug : 'note';
+}

package/templates/skeleton/node-service/packages/core/test/events.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { NoteCreatedEventSchema, makeNoteCreatedEvent } from '../src/events.js';
+import { createNote } from '../src/note.js';
+
+const note = createNote({ title: 'Hello' }, { id: 'n1', createdAt: '2024-01-01T00:00:00.000Z' });
+
+describe('note.created event', () => {
+  it('wraps a note and round-trips through its own schema', () => {
+    const event = makeNoteCreatedEvent(note);
+    expect(event.type).toBe('note.created');
+    expect(NoteCreatedEventSchema.parse(JSON.parse(JSON.stringify(event)))).toEqual(event);
+  });
+
+  it('rejects a payload with the wrong type tag', () => {
+    expect(NoteCreatedEventSchema.safeParse({ type: 'other', note }).success).toBe(false);
+  });
+
+  it('rejects a payload with a malformed note', () => {
+    expect(
+      NoteCreatedEventSchema.safeParse({ type: 'note.created', note: { id: '' } }).success,
+    ).toBe(false);
+  });
+});

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

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+import { InvalidNoteError, createNote, slugify } from '../src/note.js';
+
+const identity = { id: 'note-1', createdAt: '2024-01-01T00:00:00.000Z' };
+
+describe('createNote', () => {
+  it('builds a note from valid input', () => {
+    const note = createNote({ title: 'Hello World', tags: ['a', 'b'] }, identity);
+    expect(note).toEqual({
+      id: 'note-1',
+      title: 'Hello World',
+      slug: 'hello-world',
+      tags: ['a', 'b'],
+      createdAt: '2024-01-01T00:00:00.000Z',
+    });
+  });
+
+  it('is deterministic: identical arguments yield an identical note', () => {
+    const a = createNote({ title: 'Same' }, identity);
+    const b = createNote({ title: 'Same' }, identity);
+    expect(a).toEqual(b);
+  });
+
+  it('defaults tags to an empty array', () => {
+    expect(createNote({ title: 'No tags' }, identity).tags).toEqual([]);
+  });
+
+  it('trims the title', () => {
+    expect(createNote({ title: '  padded  ' }, identity).title).toBe('padded');
+  });
+
+  it('deduplicates tags', () => {
+    expect(createNote({ title: 'T', tags: ['x', 'x', 'y'] }, identity).tags).toEqual(['x', 'y']);
+  });
+
+  it('refuses an empty or whitespace-only title', () => {
+    expect(() => createNote({ title: '' }, identity)).toThrow(InvalidNoteError);
+    expect(() => createNote({ title: '   ' }, identity)).toThrow(InvalidNoteError);
+  });
+
+  it('refuses a title over 200 characters', () => {
+    expect(() => createNote({ title: 'x'.repeat(201) }, identity)).toThrow(InvalidNoteError);
+    expect(() => createNote({ title: 'x'.repeat(200) }, identity)).not.toThrow();
+  });
+
+  it('refuses more than 10 tags', () => {
+    const tags = Array.from({ length: 11 }, (_, i) => `t${i}`);
+    expect(() => createNote({ title: 'T', tags }, identity)).toThrow(InvalidNoteError);
+  });
+
+  it('refuses empty or oversized tags', () => {
+    expect(() => createNote({ title: 'T', tags: [''] }, identity)).toThrow(InvalidNoteError);
+    expect(() => createNote({ title: 'T', tags: ['x'.repeat(41)] }, identity)).toThrow(
+      InvalidNoteError,
+    );
+  });
+
+  it('refuses non-object input', () => {
+    for (const bad of [null, undefined, 42, 'title', []]) {
+      expect(() => createNote(bad, identity)).toThrow(InvalidNoteError);
+    }
+  });
+
+  it('refuses wrongly-typed fields', () => {
+    expect(() => createNote({ title: 42 }, identity)).toThrow(InvalidNoteError);
+    expect(() => createNote({ title: 'T', tags: 'not-an-array' }, identity)).toThrow(
+      InvalidNoteError,
+    );
+  });
+
+  it('reports every issue with its path', () => {
+    try {
+      createNote({ title: '', tags: [''] }, identity);
+      expect.unreachable('should have thrown');
+    } catch (error) {
+      const invalid = error as InvalidNoteError;
+      expect(invalid.issues.length).toBeGreaterThanOrEqual(2);
+      expect(invalid.issues.join('\n')).toMatch(/title/);
+      expect(invalid.issues.join('\n')).toMatch(/tags/);
+    }
+  });
+});
+
+describe('slugify', () => {
+  it('lowercases and hyphenates', () => {
+    expect(slugify('Hello World')).toBe('hello-world');
+  });
+
+  it('collapses runs of non-alphanumerics and trims hyphens', () => {
+    expect(slugify('  a -- b!! c  ')).toBe('a-b-c');
+  });
+
+  it('strips diacritics', () => {
+    expect(slugify('Crème Brûlée')).toBe('creme-brulee');
+  });
+
+  it('falls back to "note" when nothing survives', () => {
+    expect(slugify('!!!')).toBe('note');
+    expect(slugify('日本語')).toBe('note');
+  });
+});

package/templates/skeleton/node-service/packages/db/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@app/db",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "dependencies": {
+    "@app/core": "workspace:*",
+    "@app/shared": "workspace:*"
+  }
+}

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

@@ -0,0 +1 @@
+export { JsonFileNoteStore } from './note-store.js';