create-agent-rig 0.1.0

package/templates/skeleton/aws-serverless/infra/lib/app-stack.ts

@@ -0,0 +1,116 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CfnOutput, Duration, RemovalPolicy, Stack, type StackProps } from 'aws-cdk-lib';
+import { CorsHttpMethod, HttpApi, HttpMethod } from 'aws-cdk-lib/aws-apigatewayv2';
+import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
+import { ComparisonOperator, TreatMissingData } from 'aws-cdk-lib/aws-cloudwatch';
+import { AttributeType, BillingMode, Table } from 'aws-cdk-lib/aws-dynamodb';
+import { Runtime } from 'aws-cdk-lib/aws-lambda';
+import { SqsEventSource } from 'aws-cdk-lib/aws-lambda-event-sources';
+import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
+import { Queue } from 'aws-cdk-lib/aws-sqs';
+import type { Construct } from 'constructs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const workspaceRoot = path.resolve(here, '..', '..');
+
+export class AppStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    // --- storage: one single-table DynamoDB table --------------------------
+    const table = new Table(this, 'NotesTable', {
+      partitionKey: { name: 'pk', type: AttributeType.STRING },
+      sortKey: { name: 'sk', type: AttributeType.STRING },
+      billingMode: BillingMode.PAY_PER_REQUEST,
+      // Skeleton default: destroyable. Flip to RETAIN before storing real data.
+      removalPolicy: RemovalPolicy.DESTROY,
+    });
+
+    // --- queue with DLQ + alarm -------------------------------------------
+    const deadLetterQueue = new Queue(this, 'NotesDlq', {
+      retentionPeriod: Duration.days(14),
+    });
+    const queue = new Queue(this, 'NotesQueue', {
+      visibilityTimeout: Duration.seconds(30),
+      deadLetterQueue: { queue: deadLetterQueue, maxReceiveCount: 3 },
+    });
+    deadLetterQueue
+      .metricApproximateNumberOfMessagesVisible({ period: Duration.minutes(1) })
+      .createAlarm(this, 'DlqNotEmptyAlarm', {
+        alarmDescription: 'A message reached the DLQ — a consumer is failing.',
+        threshold: 1,
+        evaluationPeriods: 1,
+        comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+      });
+
+    // --- functions ---------------------------------------------------------
+    const bundling = { sourceMap: false } as const;
+    const apiFunction = new NodejsFunction(this, 'CreateNoteFunction', {
+      entry: path.join(workspaceRoot, 'services', 'api', 'src', 'main.ts'),
+      handler: 'handler',
+      runtime: Runtime.NODEJS_22_X,
+      memorySize: 256,
+      timeout: Duration.seconds(10),
+      depsLockFilePath: path.join(workspaceRoot, 'pnpm-lock.yaml'),
+      bundling,
+      environment: {
+        TABLE_NAME: table.tableName,
+        QUEUE_URL: queue.queueUrl,
+      },
+    });
+
+    const listFunction = new NodejsFunction(this, 'ListNotesFunction', {
+      entry: path.join(workspaceRoot, 'services', 'api', 'src', 'list-main.ts'),
+      handler: 'handler',
+      runtime: Runtime.NODEJS_22_X,
+      memorySize: 256,
+      timeout: Duration.seconds(10),
+      depsLockFilePath: path.join(workspaceRoot, 'pnpm-lock.yaml'),
+      bundling,
+      environment: {
+        TABLE_NAME: table.tableName,
+      },
+    });
+
+    const workerFunction = new NodejsFunction(this, 'NoteCreatedWorker', {
+      entry: path.join(workspaceRoot, 'services', 'worker', 'src', 'main.ts'),
+      handler: 'handler',
+      runtime: Runtime.NODEJS_22_X,
+      memorySize: 256,
+      timeout: Duration.seconds(10),
+      depsLockFilePath: path.join(workspaceRoot, 'pnpm-lock.yaml'),
+      bundling,
+    });
+    workerFunction.addEventSource(new SqsEventSource(queue, { batchSize: 1 }));
+
+    // --- least-privilege grants: exactly what each function does ----------
+    table.grantWriteData(apiFunction); // the creator only puts
+    queue.grantSendMessages(apiFunction); // and publishes
+    table.grantReadData(listFunction); // the lister only reads
+
+    // --- the HTTP routes ---------------------------------------------------
+    // CORS: the web bundle is served from another origin (CloudFront).
+    const httpApi = new HttpApi(this, 'NotesApi', {
+      corsPreflight: {
+        allowOrigins: ['*'],
+        allowMethods: [CorsHttpMethod.GET, CorsHttpMethod.POST],
+        allowHeaders: ['content-type'],
+      },
+    });
+    httpApi.addRoutes({
+      path: '/notes',
+      methods: [HttpMethod.POST],
+      integration: new HttpLambdaIntegration('CreateNoteIntegration', apiFunction),
+    });
+    httpApi.addRoutes({
+      path: '/notes',
+      methods: [HttpMethod.GET],
+      integration: new HttpLambdaIntegration('ListNotesIntegration', listFunction),
+    });
+
+    new CfnOutput(this, 'ApiUrl', { value: httpApi.apiEndpoint });
+    new CfnOutput(this, 'DlqUrl', { value: deadLetterQueue.queueUrl });
+  }
+}

package/templates/skeleton/aws-serverless/infra/lib/web-stack.ts

@@ -0,0 +1,32 @@
+// Stateless serving for the static web export: a private S3 bucket behind
+// CloudFront. Deliberately no BucketDeployment construct — synth must never
+// depend on `next build` having run. The bundle ships via `aws s3 sync`
+// (see README), keeping the stack small and the dependency one-way.
+import { CfnOutput, RemovalPolicy, Stack, type StackProps } from 'aws-cdk-lib';
+import { Distribution, ViewerProtocolPolicy } from 'aws-cdk-lib/aws-cloudfront';
+import { S3BucketOrigin } from 'aws-cdk-lib/aws-cloudfront-origins';
+import { BlockPublicAccess, Bucket } from 'aws-cdk-lib/aws-s3';
+import type { Construct } from 'constructs';
+
+export class WebStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const bucket = new Bucket(this, 'WebBucket', {
+      blockPublicAccess: BlockPublicAccess.BLOCK_ALL,
+      // Skeleton default: destroyable. Flip to RETAIN before real traffic.
+      removalPolicy: RemovalPolicy.DESTROY,
+    });
+
+    const distribution = new Distribution(this, 'WebDistribution', {
+      defaultBehavior: {
+        origin: S3BucketOrigin.withOriginAccessControl(bucket),
+        viewerProtocolPolicy: ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
+      },
+      defaultRootObject: 'index.html',
+    });
+
+    new CfnOutput(this, 'WebBucketName', { value: bucket.bucketName });
+    new CfnOutput(this, 'WebUrl', { value: `https://${distribution.domainName}` });
+  }
+}

package/templates/skeleton/aws-serverless/infra/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@app/infra",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "synth": "cdk synth --quiet",
+    "deploy": "cdk deploy",
+    "destroy": "cdk destroy"
+  },
+  "dependencies": {
+    "aws-cdk-lib": "^2.261.0",
+    "constructs": "^10.7.1"
+  },
+  "devDependencies": {
+    "aws-cdk": "^2.1132.0"
+  }
+}

package/templates/skeleton/aws-serverless/infra/test/app-stack.test.ts

@@ -0,0 +1,104 @@
+import { App } from 'aws-cdk-lib';
+import { Match, Template } from 'aws-cdk-lib/assertions';
+import { beforeAll, describe, expect, it } from 'vitest';
+import { AppStack } from '../lib/app-stack.js';
+
+// Template.fromStack bundles the Lambda entries with esbuild — slow-ish, run once.
+let template: Template;
+
+beforeAll(() => {
+  const app = new App();
+  template = Template.fromStack(new AppStack(app, 'TestStack'));
+});
+
+describe('storage', () => {
+  it('creates the single table with pk/sk and on-demand billing', () => {
+    template.hasResourceProperties('AWS::DynamoDB::Table', {
+      KeySchema: [
+        { AttributeName: 'pk', KeyType: 'HASH' },
+        { AttributeName: 'sk', KeyType: 'RANGE' },
+      ],
+      BillingMode: 'PAY_PER_REQUEST',
+    });
+    template.resourceCountIs('AWS::DynamoDB::Table', 1);
+  });
+});
+
+describe('queue discipline', () => {
+  it('wires the DLQ with maxReceiveCount 3', () => {
+    template.hasResourceProperties('AWS::SQS::Queue', {
+      RedrivePolicy: Match.objectLike({ maxReceiveCount: 3 }),
+    });
+  });
+
+  it('alarms as soon as one message reaches the DLQ', () => {
+    template.hasResourceProperties('AWS::CloudWatch::Alarm', {
+      MetricName: 'ApproximateNumberOfMessagesVisible',
+      Threshold: 1,
+      EvaluationPeriods: 1,
+      ComparisonOperator: 'GreaterThanOrEqualToThreshold',
+    });
+  });
+
+  it('feeds the worker one message at a time', () => {
+    template.hasResourceProperties('AWS::Lambda::EventSourceMapping', {
+      BatchSize: 1,
+    });
+  });
+});
+
+describe('functions and routes', () => {
+  it('deploys exactly the create, list and worker functions — one purpose each', () => {
+    template.resourceCountIs('AWS::Lambda::Function', 3);
+  });
+
+  it('passes table and queue to the api via environment', () => {
+    template.hasResourceProperties('AWS::Lambda::Function', {
+      Environment: {
+        Variables: Match.objectLike({
+          TABLE_NAME: Match.anyValue(),
+          QUEUE_URL: Match.anyValue(),
+        }),
+      },
+    });
+  });
+
+  it('exposes exactly two routes: POST /notes and GET /notes', () => {
+    template.hasResourceProperties('AWS::ApiGatewayV2::Route', {
+      RouteKey: 'POST /notes',
+    });
+    template.hasResourceProperties('AWS::ApiGatewayV2::Route', {
+      RouteKey: 'GET /notes',
+    });
+    template.resourceCountIs('AWS::ApiGatewayV2::Route', 2);
+  });
+
+  it('allows the browser origin in: CORS is configured', () => {
+    template.hasResourceProperties('AWS::ApiGatewayV2::Api', {
+      CorsConfiguration: Match.objectLike({
+        AllowMethods: Match.arrayWith(['GET', 'POST']),
+      }),
+    });
+  });
+});
+
+describe('least-privilege IAM', () => {
+  it('grants writes to the creator, reads to the lister, queue send — nothing broad', () => {
+    const policies = template.findResources('AWS::IAM::Policy');
+    const statements = Object.values(policies).flatMap(
+      (policy) =>
+        (policy.Properties as { PolicyDocument: { Statement: Array<Record<string, unknown>> } })
+          .PolicyDocument.Statement,
+    );
+    const actions = statements.flatMap((s) =>
+      Array.isArray(s.Action) ? (s.Action as string[]) : [s.Action as string],
+    );
+
+    expect(actions).toContain('dynamodb:PutItem');
+    expect(actions).toContain('dynamodb:Scan'); // the list function reads
+    expect(actions).toContain('sqs:SendMessage');
+    // Least privilege: nothing broad.
+    expect(actions).not.toContain('dynamodb:*');
+    expect(actions.some((a) => a === '*')).toBe(false);
+  });
+});

package/templates/skeleton/aws-serverless/infra/test/web-stack.test.ts

@@ -0,0 +1,41 @@
+import { App } from 'aws-cdk-lib';
+import { Match, Template } from 'aws-cdk-lib/assertions';
+import { beforeAll, describe, it } from 'vitest';
+import { WebStack } from '../lib/web-stack.js';
+
+// The web stack is stateless serving only: a private bucket behind CloudFront.
+// The bundle itself is synced by the deploy step (see README) — synth stays
+// independent of `next build`.
+let template: Template;
+
+beforeAll(() => {
+  template = Template.fromStack(new WebStack(new App(), 'TestWebStack'));
+});
+
+describe('web serving stack', () => {
+  it('keeps the bucket fully private', () => {
+    template.hasResourceProperties('AWS::S3::Bucket', {
+      PublicAccessBlockConfiguration: Match.objectLike({
+        BlockPublicAcls: true,
+        BlockPublicPolicy: true,
+        IgnorePublicAcls: true,
+        RestrictPublicBuckets: true,
+      }),
+    });
+  });
+
+  it('serves through CloudFront with origin access control', () => {
+    template.resourceCountIs('AWS::CloudFront::Distribution', 1);
+    template.resourceCountIs('AWS::CloudFront::OriginAccessControl', 1);
+    template.hasResourceProperties('AWS::CloudFront::Distribution', {
+      DistributionConfig: Match.objectLike({
+        DefaultRootObject: 'index.html',
+      }),
+    });
+  });
+
+  it('exports the distribution domain and bucket name for the deploy step', () => {
+    template.hasOutput('WebBucketName', {});
+    template.hasOutput('WebUrl', {});
+  });
+});

package/templates/skeleton/aws-serverless/package.json

@@ -0,0 +1,30 @@
+{
+  "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",
+    "synth": "pnpm --filter @app/infra synth",
+    "deploy": "pnpm --filter @app/infra deploy",
+    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm build:web && pnpm synth"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/aws-lambda": "^8.10.162",
+    "@types/node": "^26.1.1",
+    "esbuild": "^0.28.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/aws-serverless/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/aws-serverless/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/aws-serverless/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/aws-serverless/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/aws-serverless/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/aws-serverless/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/aws-serverless/packages/db/package.json

@@ -0,0 +1,14 @@
+{
+  "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:*",
+    "@aws-sdk/client-dynamodb": "^3.1092.0",
+    "@aws-sdk/lib-dynamodb": "^3.1092.0"
+  }
+}

package/templates/skeleton/aws-serverless/packages/db/src/client.ts

@@ -0,0 +1,17 @@
+// The ONLY file in the project that constructs the storage SDK client.
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+
+/**
+ * Structural view of the document client — models depend on this, tests stub it.
+ * (Method parameters are bivariant, so the real client satisfies it.)
+ */
+export interface DocumentClient {
+  send(command: unknown): Promise<unknown>;
+}
+
+export function createDocumentClient(): DocumentClient {
+  return DynamoDBDocumentClient.from(new DynamoDBClient({}), {
+    marshallOptions: { removeUndefinedValues: true },
+  }) as DocumentClient;
+}

package/templates/skeleton/aws-serverless/packages/db/src/index.ts

@@ -0,0 +1,2 @@
+export { createDocumentClient, type DocumentClient } from './client.js';
+export { NoteModel } from './note-model.js';

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

@@ -0,0 +1,52 @@
+// Single-table layout: pk = NOTE#<id>, sk = META. One model, one table, one
+// place that knows the key schema.
+import { GetCommand, PutCommand, ScanCommand } from '@aws-sdk/lib-dynamodb';
+import { NoteSchema, type Note } from '@app/core';
+import { NotFoundError } from '@app/shared';
+import type { DocumentClient } from './client.js';
+
+const noteKey = (id: string) => ({ pk: `NOTE#${id}`, sk: 'META' });
+
+export class NoteModel {
+  constructor(
+    private readonly client: DocumentClient,
+    private readonly tableName: string,
+  ) {}
+
+  async put(note: Note): Promise<void> {
+    await this.client.send(
+      new PutCommand({
+        TableName: this.tableName,
+        Item: { ...noteKey(note.id), ...note },
+        ConditionExpression: 'attribute_not_exists(pk)',
+      }),
+    );
+  }
+
+  async get(id: string): Promise<Note> {
+    const result = (await this.client.send(
+      new GetCommand({ TableName: this.tableName, Key: noteKey(id) }),
+    )) as { Item?: Record<string, unknown> };
+    if (!result.Item) {
+      throw new NotFoundError(`note ${id} not found`);
+    }
+    // Validate on the way out too: the database is an external system.
+    return NoteSchema.parse(result.Item);
+  }
+
+  async list(): Promise<Note[]> {
+    // A filtered Scan is fine at skeleton scale; swap for a GSI Query when
+    // real data volume arrives (a Tier-2 change — it touches the schema).
+    const result = (await this.client.send(
+      new ScanCommand({
+        TableName: this.tableName,
+        FilterExpression: 'sk = :meta',
+        ExpressionAttributeValues: { ':meta': 'META' },
+      }),
+    )) as { Items?: Array<Record<string, unknown>> };
+    // Validate every entry — silently skipping corruption would hide data loss.
+    return (result.Items ?? [])
+      .map((item) => NoteSchema.parse(item))
+      .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+  }
+}