create-agent-rig 0.1.0

package/templates/skeleton/aws-serverless/packages/db/test/note-model.test.ts

@@ -0,0 +1,91 @@
+import { GetCommand, PutCommand, ScanCommand } from '@aws-sdk/lib-dynamodb';
+import { NotFoundError } from '@app/shared';
+import { describe, expect, it } from 'vitest';
+import { NoteModel } from '../src/note-model.js';
+import type { DocumentClient } from '../src/client.js';
+
+const note = {
+  id: 'n1',
+  title: 'Hello',
+  slug: 'hello',
+  tags: ['x'],
+  createdAt: '2024-01-01T00:00:00.000Z',
+};
+
+function stubClient(response: unknown = {}) {
+  const sent: unknown[] = [];
+  const client: DocumentClient = {
+    send: (command) => {
+      sent.push(command);
+      return Promise.resolve(response);
+    },
+  };
+  return { client, sent };
+}
+
+describe('NoteModel.put', () => {
+  it('writes the note under the single-table key, refusing overwrites', async () => {
+    const { client, sent } = stubClient();
+    await new NoteModel(client, 'notes-table').put(note);
+    expect(sent).toHaveLength(1);
+    const command = sent[0] as PutCommand;
+    expect(command).toBeInstanceOf(PutCommand);
+    expect(command.input).toMatchObject({
+      TableName: 'notes-table',
+      Item: { pk: 'NOTE#n1', sk: 'META', ...note },
+      ConditionExpression: 'attribute_not_exists(pk)',
+    });
+  });
+});
+
+describe('NoteModel.get', () => {
+  it('reads by key and validates the stored shape', async () => {
+    const { client, sent } = stubClient({ Item: { pk: 'NOTE#n1', sk: 'META', ...note } });
+    const loaded = await new NoteModel(client, 'notes-table').get('n1');
+    expect(loaded).toEqual(note);
+    const command = sent[0] as GetCommand;
+    expect(command).toBeInstanceOf(GetCommand);
+    expect(command.input).toMatchObject({
+      TableName: 'notes-table',
+      Key: { pk: 'NOTE#n1', sk: 'META' },
+    });
+  });
+
+  it('throws NotFoundError on a miss', async () => {
+    const { client } = stubClient({});
+    await expect(new NoteModel(client, 'notes-table').get('nope')).rejects.toThrow(NotFoundError);
+  });
+
+  it('refuses corrupt stored data instead of returning it', async () => {
+    const { client } = stubClient({ Item: { pk: 'NOTE#n1', sk: 'META', id: 'n1' } });
+    await expect(new NoteModel(client, 'notes-table').get('n1')).rejects.toThrow();
+  });
+});
+
+describe('NoteModel.list', () => {
+  it('scans meta items, validates them, and returns newest-first', async () => {
+    const older = { ...note, id: 'a', createdAt: '2024-01-01T00:00:00.000Z' };
+    const newer = { ...note, id: 'b', createdAt: '2024-02-01T00:00:00.000Z' };
+    const { client, sent } = stubClient({
+      Items: [
+        { pk: 'NOTE#a', sk: 'META', ...older },
+        { pk: 'NOTE#b', sk: 'META', ...newer },
+      ],
+    });
+    const listed = await new NoteModel(client, 'notes-table').list();
+    expect(listed.map((n) => n.id)).toEqual(['b', 'a']);
+    const command = sent[0] as ScanCommand;
+    expect(command).toBeInstanceOf(ScanCommand);
+    expect(command.input.TableName).toBe('notes-table');
+  });
+
+  it('returns [] for an empty table', async () => {
+    const { client } = stubClient({ Items: [] });
+    expect(await new NoteModel(client, 'notes-table').list()).toEqual([]);
+  });
+
+  it('refuses corrupt stored entries instead of skipping them', async () => {
+    const { client } = stubClient({ Items: [{ pk: 'NOTE#x', sk: 'META', id: 'x' }] });
+    await expect(new NoteModel(client, 'notes-table').list()).rejects.toThrow();
+  });
+});

package/templates/skeleton/aws-serverless/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/aws-serverless/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/aws-serverless/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/aws-serverless/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/aws-serverless/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/aws-serverless/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/aws-serverless/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/aws-serverless/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' });
+  });
+});