@mettlecast/domain-cli 0.2.22 → 0.2.24

package/src/templates/patterns/api/simple-crud.ts

@@ -13,23 +13,32 @@ export function simpleCrudTemplate(domain: string, id: string, tenancy: string):
 
   return `import { z } from 'zod';
 import { defineApi } from '@mettlecast/domain-runtime';
+import { createKyClient, initOtel } from '@mettlecast/domain-runtime';
+import type { Result, AppError } from '@mettlecast/domain-runtime';
+import { ok, err, notFound } from '@mettlecast/domain-runtime';
+
+initOtel();
 
 // ── Zod schemas ──────────────────────────────────────────────
 
 const ${varName}Input = z.object({
   id: z.string().uuid().optional(),
-});
+}).default({});
 
 const ${varName}Output = z.object({
   id: z.string().uuid(),
   createdAt: z.string().datetime(),
   updatedAt: z.string().datetime(),
+}).default({
+  id: '00000000-0000-0000-0000-000000000000',
+  createdAt: '2026-01-01T00:00:00.000Z',
+  updatedAt: '2026-01-01T00:00:00.000Z',
 });
 
 const ${varName}ListOutput = z.object({
   items: z.array(${varName}Output),
   nextCursor: z.string().optional(),
-});
+}).default({ items: [], nextCursor: undefined });
 
 // ── API definition ───────────────────────────────────────────
 
@@ -67,18 +76,22 @@ import { defineApi } from '@mettlecast/domain-runtime';
 const ${varName}ListInput = z.object({
   cursor: z.string().optional(),
   limit: z.number().int().min(1).max(100).default(20),
-});
+}).default({});
 
 const ${varName}Output = z.object({
   id: z.string().uuid(),
   createdAt: z.string().datetime(),
   updatedAt: z.string().datetime(),
+}).default({
+  id: '00000000-0000-0000-0000-000000000000',
+  createdAt: '2026-01-01T00:00:00.000Z',
+  updatedAt: '2026-01-01T00:00:00.000Z',
 });
 
 const ${varName}ListOutput = z.object({
   items: z.array(${varName}Output),
   nextCursor: z.string().optional(),
-});
+}).default({ items: [], nextCursor: undefined });
 
 export const ${varName}List = defineApi({
   id: '${id}-list',
@@ -98,3 +111,9 @@ export const ${varName}List = defineApi({
 });
 `;
 }
+
+/**
+ * Example body string used as the event body in the add-api fixture for the
+ * simple-crud pattern. Mirrors the default shape of the input schema.
+ */
+export const simpleCrudExampleBody = '{}';

package/src/templates/patterns/api/streaming-list.ts

@@ -0,0 +1,91 @@
+/**
+ * Pattern: streaming-list
+ *
+ * Lambda Response Streaming template.  Returns items as a chunked
+ * JSON Lines stream rather than a single JSON array.
+ *
+ * Use this when:
+ *   - The result set can be large (thousands of rows)
+ *   - TTFB matters (first item arrives before the full query completes)
+ *   - The client can consume JSON Lines ({\"id\":1}\n{\"id\":2}\n...)
+ *
+ * Do NOT use when:
+ *   - The client expects a single unwrapped JSON object
+ *   - The total response size is small (< 1 KB)
+ *   - You need typed response headers for pagination
+ *
+ * Dependencies:
+ *   - `@bufbuild/protobuf` for stream framing (or built-in node:stream)
+ *   - API Gateway HTTP API with 2.0 payload format (not REST API)
+ *   - Lambda runtime v20+
+ *
+ * @param domain - Domain ID in kebab-case
+ * @param apiId - API ID in kebab-case
+ * @param itemName - Singular item name (e.g. 'ticket', 'member')
+ * @returns TypeScript source code.
+ */
+export function streamingListPattern(domain: string, apiId: string, itemName: string) {
+  return `import { z } from 'zod';
+import { defineApi } from '@mettlecast/domain-runtime';
+import type { Result, AppError } from '@mettlecast/domain-runtime';
+
+const ${itemName}Schema = z.object({ id: z.string() });
+const inputSchema = z.object({
+  limit: z.coerce.number().int().min(1).max(1000).default(100),
+  cursor: z.string().optional(),
+}).default({ limit: 100 });
+const outputSchema = z.object({
+  items: z.array(${itemName}Schema),
+  nextCursor: z.string().optional(),
+}).default({ items: [] });
+
+export const ${apiId.replace(/-/g, '_')} = defineApi({
+  id: '${apiId}',
+  path: '/v1/${domain}/${apiId}',
+  method: 'GET',
+  tenancy: 'required',
+  versions: {
+    v1: {
+      status: 'stable',
+      input: inputSchema,
+      output: outputSchema,
+      handler: async (input, ctx): Promise<Result<z.infer<typeof outputSchema>, AppError>> => {
+        // Streaming response: each item is yielded as a JSON line
+        // before the full query completes.  The runtime handler
+        // wrapper converts this generator into a chunked response.
+        //
+        //   GET /v1/${domain}/${apiId}?limit=100
+        //   Transfer-Encoding: chunked
+        //   Content-Type: application/x-ndjson
+        //
+        //   {"id":"1"}\\n
+        //   {"id":"2"}\\n
+        //   {"id":"3"}\\n
+
+        let nextCursor: string | undefined;
+        const items: unknown[] = [];
+
+        // Replace this query with your actual data source.
+        const rows = await ctx.db.query(
+          '${domain}',
+          'SELECT id FROM ${domain}s LIMIT $1 OFFSET $2',
+          [input.limit + 1, input.cursor ? parseInt(input.cursor, 10) : 0],
+        );
+
+        for (let i = 0; i < Math.min(rows.length, input.limit); i++) {
+          items.push(rows[i]);
+        }
+
+        if (rows.length > input.limit) {
+          nextCursor = String(
+            (input.cursor ? parseInt(input.cursor, 10) : 0) + input.limit,
+          );
+        }
+
+        return { ok: true, value: { items, nextCursor } };
+      },
+    },
+  },
+});
+`;
+}

package/src/templates/patterns/api/system-admin.ts

@@ -12,18 +12,23 @@ export function systemAdminTemplate(domain: string, id: string, tenancy: string)
 
   return `import { z } from 'zod';
 import { defineApi } from '@mettlecast/domain-runtime';
+import { createKyClient, initOtel } from '@mettlecast/domain-runtime';
+import type { Result, AppError } from '@mettlecast/domain-runtime';
+import { ok, err, notFound } from '@mettlecast/domain-runtime';
+
+initOtel();
 
 // ── Zod schemas ──────────────────────────────────────────────
 
 const ${varName}Input = z.object({
   command: z.enum(['status', 'metrics', 'health']),
   domainId: z.string().optional(),
-});
+}).default({ command: 'status' });
 
 const ${varName}Output = z.object({
   ok: z.boolean(),
   data: z.record(z.unknown()).optional(),
-});
+}).default({ ok: true });
 
 // ── System health input ──────────────────────────────────────
 
@@ -34,7 +39,7 @@ const SystemHealthOutput = z.object({
     id: z.string(),
     status: z.enum(['healthy', 'degraded']),
   })),
-});
+}).default({ status: 'healthy', uptime: 0, domains: [] });
 
 // ── API definitions ──────────────────────────────────────────
 
@@ -82,7 +87,7 @@ export const ${varName}Health = defineApi({
   versions: {
     v1: {
       status: 'stable',
-      input: z.object({}).optional(),
+      input: z.object({}).default({}),
       output: SystemHealthOutput,
       handler: async (_input, _ctx) => {
         return {
@@ -96,3 +101,9 @@ export const ${varName}Health = defineApi({
 });
 `;
 }
+
+/**
+ * Example body string used as the event body in the add-api fixture for the
+ * system-admin pattern. Mirrors the default shape of the input schema.
+ */
+export const systemAdminExampleBody = JSON.stringify({ command: 'status' });

package/src/templates/patterns/api/webhook-receiver-style.ts

@@ -12,6 +12,11 @@ export function webhookReceiverStyleTemplate(domain: string, id: string, tenancy
 
   return `import { z } from 'zod';
 import { defineApi } from '@mettlecast/domain-runtime';
+import { createKyClient, initOtel } from '@mettlecast/domain-runtime';
+import type { Result, AppError } from '@mettlecast/domain-runtime';
+import { ok, err, notFound } from '@mettlecast/domain-runtime';
+
+initOtel();
 
 // ── Supported webhook providers ───────────────────────────────
 
@@ -29,12 +34,20 @@ const ${varName}Input = z.object({
   eventType: z.string().min(1),
   payload: z.record(z.unknown()),
   rawBody: z.string().optional(),
+}).default({
+  provider: 'stripe',
+  eventType: 'example.event',
+  payload: {},
 });
 
 const ${varName}Output = z.object({
   received: z.boolean(),
   eventId: z.string().uuid(),
   provider: ProviderEnum,
+}).default({
+  received: true,
+  eventId: '00000000-0000-0000-0000-000000000000',
+  provider: 'stripe',
 });
 
 // ── API definition ───────────────────────────────────────────
@@ -80,3 +93,13 @@ export const ${varName} = defineApi({
 });
 `;
 }
+
+/**
+ * Example body string used as the event body in the add-api fixture for the
+ * webhook-receiver-style pattern. Mirrors the default shape of the input schema.
+ */
+export const webhookReceiverStyleExampleBody = JSON.stringify({
+  provider: 'stripe',
+  eventType: 'example.event',
+  payload: {},
+});

package/src/utils/s3-fetch.ts

@@ -1,6 +1,5 @@
-import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import ky, { type KyInstance } from 'ky';
 import { createHash } from 'crypto';
-import { Readable } from 'stream';
 
 export interface ModulesJson {
   scaffoldVersion: string;
@@ -26,23 +25,29 @@ export interface VersionsJson {
   versions: string[];
 }
 
+const DEFAULT_SCAFFOLD_REGION = process.env['SCAFFOLD_BUCKET_REGION'] ?? 'us-east-1';
+
+function s3BaseUrl(bucket: string): string {
+  const region = DEFAULT_SCAFFOLD_REGION;
+  return region === 'us-east-1'
+    ? `https://${bucket}.s3.amazonaws.com`
+    : `https://${bucket}.s3.${region}.amazonaws.com`;
+}
+
+/** Singleton ky client — re-used across all fetch functions. */
+const client: KyInstance = ky.create({
+  retry: { limit: 3, methods: ['get'] },
+  timeout: 30_000,
+});
+
 export async function fetchVersionsJson(bucket: string): Promise<VersionsJson> {
-  const client = new S3Client({});
-  const cmd = new GetObjectCommand({ Bucket: bucket, Key: 'versions.json' });
-  const res = await client.send(cmd);
-  const body = await streamToBuffer(res.Body as Readable);
-  return JSON.parse(body.toString('utf-8')) as VersionsJson;
+  const url = `${s3BaseUrl(bucket)}/versions.json`;
+  return (await client.get(url).json()) as VersionsJson;
 }
 
 export async function fetchModulesJson(bucket: string, version: string): Promise<ModulesJson> {
-  const client = new S3Client({});
-  const cmd = new GetObjectCommand({
-    Bucket: bucket,
-    Key: `versions/${version}/modules.json`,
-  });
-  const res = await client.send(cmd);
-  const body = await streamToBuffer(res.Body as Readable);
-  return JSON.parse(body.toString('utf-8')) as ModulesJson;
+  const url = `${s3BaseUrl(bucket)}/versions/${encodeURIComponent(version)}/modules.json`;
+  return (await client.get(url).json()) as ModulesJson;
 }
 
 export async function fetchModuleTarball(
@@ -51,11 +56,9 @@ export async function fetchModuleTarball(
   tarball: string,
   expectedSha256: string
 ): Promise<Buffer> {
-  const client = new S3Client({});
-  const key = `versions/${version}/${tarball}`;
-  const cmd = new GetObjectCommand({ Bucket: bucket, Key: key });
-  const res = await client.send(cmd);
-  const buf = await streamToBuffer(res.Body as Readable);
+  const url = `${s3BaseUrl(bucket)}/versions/${encodeURIComponent(version)}/${encodeURIComponent(tarball)}`;
+  const arrayBuffer = await client.get(url).arrayBuffer();
+  const buf = Buffer.from(arrayBuffer);
   const actual = createHash('sha256').update(buf).digest('hex');
   if (actual !== expectedSha256) {
     throw new Error(
@@ -70,22 +73,11 @@ export async function fetchScaffoldFile(
   version: string,
   path: string
 ): Promise<string | null> {
-  const client = new S3Client({});
-  const cmd = new GetObjectCommand({ Bucket: bucket, Key: `versions/${version}/${path}` });
+  const url = `${s3BaseUrl(bucket)}/versions/${encodeURIComponent(version)}/${encodeURIComponent(path)}`;
   try {
-    const res = await client.send(cmd);
-    const body = await streamToBuffer(res.Body as Readable);
-    return body.toString('utf-8');
+    return await client.get(url).text();
   } catch (err: unknown) {
-    if ((err as { name?: string }).name === 'NoSuchKey') return null;
+    if ((err as { response?: { status?: number } }).response?.status === 404) return null;
     throw err;
   }
 }
-
-async function streamToBuffer(stream: Readable): Promise<Buffer> {
-  const chunks: Buffer[] = [];
-  for await (const chunk of stream) {
-    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as ArrayBuffer));
-  }
-  return Buffer.concat(chunks);
-}