create-agent-rig 0.1.0

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

@@ -0,0 +1,63 @@
+// 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 path from 'node:path';
+import { NoteSchema, type Note } from '@app/core';
+import { AppError, NotFoundError } from '@app/shared';
+
+type NoteTable = Record<string, unknown>;
+
+export class JsonFileNoteStore {
+  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);
+  }
+
+  async get(id: string): Promise<Note> {
+    const table = await this.load();
+    const raw = table[id];
+    if (raw === undefined) {
+      throw new NotFoundError(`note ${id} not found`);
+    }
+    // Validate on the way out: the file is an external system.
+    return NoteSchema.parse(raw);
+  }
+
+  async list(): Promise<Note[]> {
+    const table = await this.load();
+    // Validate every entry — silently skipping corruption would hide data loss.
+    return Object.values(table)
+      .map((raw) => NoteSchema.parse(raw))
+      .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  }
+
+  private async load(): Promise<NoteTable> {
+    let content: string;
+    try {
+      content = await readFile(this.file, 'utf8');
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return {};
+      throw error;
+    }
+    try {
+      return JSON.parse(content) as NoteTable;
+    } catch (cause) {
+      throw new AppError(`data file ${this.file} is corrupt`, { code: 'DATA_CORRUPT', cause });
+    }
+  }
+
+  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);
+  }
+}

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

@@ -0,0 +1,80 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { AppError, NotFoundError } from '@app/shared';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { JsonFileNoteStore } from '../src/note-store.js';
+
+const note = {
+  id: 'n1',
+  title: 'Hello',
+  slug: 'hello',
+  tags: ['x'],
+  createdAt: '2024-01-01T00:00:00.000Z',
+};
+
+let dir: string;
+let file: string;
+
+beforeEach(async () => {
+  dir = await mkdtemp(path.join(tmpdir(), 'note-store-'));
+  file = path.join(dir, 'data', 'notes.json');
+});
+
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('JsonFileNoteStore', () => {
+  it('round-trips a note (creating the data dir on first write)', async () => {
+    const store = new JsonFileNoteStore(file);
+    await store.put(note);
+    expect(await store.get('n1')).toEqual(note);
+    expect(JSON.parse(await readFile(file, 'utf8'))).toEqual({ n1: note });
+  });
+
+  it('refuses to overwrite an existing id', async () => {
+    const store = new JsonFileNoteStore(file);
+    await store.put(note);
+    await expect(store.put(note)).rejects.toThrow(AppError);
+    await expect(store.put(note)).rejects.toMatchObject({ statusCode: 409 });
+  });
+
+  it('throws NotFoundError on a miss', async () => {
+    await expect(new JsonFileNoteStore(file).get('nope')).rejects.toThrow(NotFoundError);
+  });
+
+  it('refuses corrupt stored entries instead of returning them', async () => {
+    const store = new JsonFileNoteStore(file);
+    await store.put(note);
+    const table = JSON.parse(await readFile(file, 'utf8'));
+    table.n1 = { id: 'n1' };
+    await writeFile(file, JSON.stringify(table));
+    await expect(store.get('n1')).rejects.toThrow();
+  });
+
+  it('reports a corrupt data file clearly', async () => {
+    const store = new JsonFileNoteStore(file);
+    await store.put(note);
+    await writeFile(file, '{not json');
+    await expect(store.get('n1')).rejects.toMatchObject({ code: 'DATA_CORRUPT' });
+  });
+
+  it('lists notes newest-first, and an empty store as []', async () => {
+    const store = new JsonFileNoteStore(file);
+    expect(await store.list()).toEqual([]);
+    await store.put({ ...note, id: 'a', createdAt: '2024-01-01T00:00:00.000Z' });
+    await store.put({ ...note, id: 'b', createdAt: '2024-02-01T00:00:00.000Z' });
+    const listed = await store.list();
+    expect(listed.map((n) => n.id)).toEqual(['b', 'a']);
+  });
+
+  it('refuses to list corrupt entries instead of skipping them silently', async () => {
+    const store = new JsonFileNoteStore(file);
+    await store.put(note);
+    const table = JSON.parse(await readFile(file, 'utf8'));
+    table.bad = { id: 'bad' };
+    await writeFile(file, JSON.stringify(table));
+    await expect(store.list()).rejects.toThrow();
+  });
+});

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

@@ -0,0 +1,11 @@
+{
+  "name": "@app/shared",
+  "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/shared/src/env.ts

@@ -0,0 +1,17 @@
+import type { ZodType } from 'zod';
+import { AppError } from './errors.js';
+
+/**
+ * Parse the environment through a zod schema, once, at startup. Configuration
+ * is invalid → the process fails loudly at boot, not deep inside a request.
+ */
+export function loadEnv<T>(schema: ZodType<T>, source: Record<string, string | undefined>): T {
+  const parsed = schema.safeParse(source);
+  if (!parsed.success) {
+    const details = parsed.error.issues
+      .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+      .join('; ');
+    throw new AppError(`invalid environment: ${details}`, { code: 'ENV_INVALID' });
+  }
+  return parsed.data;
+}

package/templates/skeleton/node-service/packages/shared/src/errors.ts

@@ -0,0 +1,33 @@
+/**
+ * Typed errors. Every error that crosses a layer boundary is one of these —
+ * handlers map them to transport codes without inspecting messages.
+ */
+export class AppError extends Error {
+  readonly code: string;
+  readonly statusCode: number;
+
+  constructor(
+    message: string,
+    options: { code?: string; statusCode?: number; cause?: unknown } = {},
+  ) {
+    super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+    this.name = new.target.name;
+    this.code = options.code ?? 'INTERNAL';
+    this.statusCode = options.statusCode ?? 500;
+  }
+}
+
+export class ValidationError extends AppError {
+  readonly issues: readonly string[];
+
+  constructor(message: string, issues: readonly string[] = []) {
+    super(message, { code: 'VALIDATION', statusCode: 400 });
+    this.issues = issues;
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(message: string) {
+    super(message, { code: 'NOT_FOUND', statusCode: 404 });
+  }
+}

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

@@ -0,0 +1,3 @@
+export { AppError, NotFoundError, ValidationError } from './errors.js';
+export { createLogger, type Logger } from './logger.js';
+export { loadEnv } from './env.js';

package/templates/skeleton/node-service/packages/shared/src/logger.ts

@@ -0,0 +1,20 @@
+/** Minimal structured logger: one JSON object per line on stdout. */
+export interface Logger {
+  info(message: string, fields?: Record<string, unknown>): void;
+  warn(message: string, fields?: Record<string, unknown>): void;
+  error(message: string, fields?: Record<string, unknown>): void;
+}
+
+export function createLogger(
+  base: Record<string, unknown> = {},
+  write: (line: string) => void = (line) => process.stdout.write(line + '\n'),
+): Logger {
+  const emit = (level: string, message: string, fields?: Record<string, unknown>) => {
+    write(JSON.stringify({ level, message, ...base, ...fields }));
+  };
+  return {
+    info: (message, fields) => emit('info', message, fields),
+    warn: (message, fields) => emit('warn', message, fields),
+    error: (message, fields) => emit('error', message, fields),
+  };
+}

package/templates/skeleton/node-service/packages/shared/test/env.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { AppError } from '../src/errors.js';
+import { loadEnv } from '../src/env.js';
+
+const schema = z.object({
+  TABLE_NAME: z.string().min(1),
+  QUEUE_URL: z.string().min(1),
+});
+
+describe('loadEnv', () => {
+  it('returns the typed subset of the environment', () => {
+    const env = loadEnv(schema, { TABLE_NAME: 't', QUEUE_URL: 'q', UNRELATED: 'x' });
+    expect(env).toEqual({ TABLE_NAME: 't', QUEUE_URL: 'q' });
+  });
+
+  it('fails loudly, naming every missing key', () => {
+    expect(() => loadEnv(schema, {})).toThrow(AppError);
+    expect(() => loadEnv(schema, {})).toThrow(/TABLE_NAME/);
+    expect(() => loadEnv(schema, {})).toThrow(/QUEUE_URL/);
+  });
+
+  it('rejects empty values', () => {
+    expect(() => loadEnv(schema, { TABLE_NAME: '', QUEUE_URL: 'q' })).toThrow(/TABLE_NAME/);
+  });
+});

package/templates/skeleton/node-service/packages/shared/test/errors.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { AppError, NotFoundError, ValidationError } from '../src/errors.js';
+
+describe('typed errors', () => {
+  it('AppError defaults to INTERNAL/500', () => {
+    const error = new AppError('boom');
+    expect(error.code).toBe('INTERNAL');
+    expect(error.statusCode).toBe(500);
+    expect(error.name).toBe('AppError');
+  });
+
+  it('preserves an explicit cause', () => {
+    const cause = new Error('root');
+    expect(new AppError('boom', { cause }).cause).toBe(cause);
+  });
+
+  it('ValidationError is 400 and carries issues', () => {
+    const error = new ValidationError('bad input', ['title: required']);
+    expect(error.statusCode).toBe(400);
+    expect(error.code).toBe('VALIDATION');
+    expect(error.issues).toEqual(['title: required']);
+    expect(error).toBeInstanceOf(AppError);
+  });
+
+  it('NotFoundError is 404', () => {
+    expect(new NotFoundError('nope').statusCode).toBe(404);
+  });
+});

package/templates/skeleton/node-service/packages/shared/test/logger.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { createLogger } from '../src/logger.js';
+
+describe('createLogger', () => {
+  it('emits one JSON line per call with level, message, base and call fields', () => {
+    const lines: string[] = [];
+    const log = createLogger({ service: 'api' }, (line) => lines.push(line));
+    log.info('started', { port: 3000 });
+    log.error('failed');
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0]!)).toEqual({
+      level: 'info',
+      message: 'started',
+      service: 'api',
+      port: 3000,
+    });
+    expect(JSON.parse(lines[1]!)).toMatchObject({ level: 'error', message: 'failed' });
+  });
+});