@eventmodelers/cli 0.0.1

package/stacks/supabase/templates/.claude/skills/build-state-view/SKILL.md

@@ -0,0 +1,390 @@
+---
+name: build-state-view
+description: Implements an emmett state-view slice (projection, tests, route, migration) from a slice.json definition
+---
+
+# Build State View Slice
+
+> Before doing anything else, read the slice definition from `.slices/{Context}/{slicename}/slice.json`. This file is the **source of truth** for all fields, events, and read model shape. Never invent fields not defined there.
+
+---
+
+## What a State View Slice is
+
+A state-view slice is a **read model projection**. It listens to events from the event store and materializes them into a queryable PostgreSQL table. It does not emit events or process commands.
+
+---
+
+## Step 1 — Read the slice.json
+
+From the slice definition, extract:
+- **sliceName** — the projection name
+- **context** — bounded context
+- **events[]** — events this projection handles (its `canHandle` list)
+- **readModel / fields** — the columns of the output table
+> **Comments & description**: Each element (commands, events, readmodels, processors, screens, tables) carries a `comments: string[]` array (board comments on that node) and a `description` field. The slice itself also has `comments: string[]`. Use these as implementation hints — pass them as code comments, documentation, or validation logic where they add value. When done, resolve each used comment: `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve` (get comment IDs first via GET on the same path without the last two segments).
+
+
+---
+
+## Step 2 — Create the migration
+
+File: `supabase/migrations/V{N}__{tablename}.sql`
+
+Choose the next available version number by checking existing migration files.
+
+```sql
+CREATE TABLE IF NOT EXISTS "public"."{tablename}"
+(
+    id          TEXT PRIMARY KEY,
+    -- other columns from read model fields in slice.json
+    -- use snake_case for all column names
+    created_at  TIMESTAMP DEFAULT NOW()
+);
+```
+
+**Column type guide:**
+
+| Field type | SQL type |
+|-----------|---------|
+| string / UUID | `TEXT` |
+| number (integer) | `INTEGER` |
+| number (float) | `NUMERIC` |
+| boolean | `BOOLEAN` |
+| date | `TIMESTAMP` |
+| nullable number | `INTEGER` (allow NULL) |
+
+The PRIMARY KEY column is the one used in `.onConflict(...)` in the projection.
+
+---
+
+## Step 3 — Create `{SliceName}Projection.ts`
+
+File: `src/slices/{context}/{SliceName}/{SliceName}Projection.ts`
+
+### Full structure
+
+```typescript
+import {postgreSQLRawSQLProjection} from '@event-driven-io/emmett-postgresql';
+import {sql, SQL} from '@event-driven-io/dumbo';
+import knex, {Knex} from 'knex';
+import {type {EventA}, type {EventB}} from '../{Context}Events';
+
+export const tableName = '{tablename}';
+
+// TypeScript shape of one row in the read model
+export type {SliceName}ReadModel = {
+    id: string;
+    // ... fields from slice.json readModel
+};
+
+export const getKnexInstance = (connectionString: string): Knex =>
+    knex({client: 'pg', connection: connectionString, pool: {min: 0, max: 1}});
+
+type {SliceName}Events = {EventA} | {EventB};
+
+export const {SliceName}Projection = postgreSQLRawSQLProjection<{SliceName}Events>({
+    name: '{SliceName}Projection',
+    canHandle: ['{EventA}', '{EventB}'],
+    evolve: async (event, context): Promise<SQL[]> => {
+        const db = getKnexInstance(context.connection.connectionString);
+
+        try {
+            switch (event.type) {
+                case '{EventA}':
+                    // Insert with upsert — use for create/update events
+                    return [sql(db(tableName)
+                        .withSchema('public')
+                        .insert({
+                            id:     event.data.id,
+                            field1: event.data.field1,
+                            field2: event.data.field2,
+                        })
+                        .onConflict('id')
+                        .merge(['field1', 'field2'])
+                        .toQuery())];
+
+                case '{EventB}':
+                    // Delete — use for cancellation/removal events
+                    return [sql(db(tableName)
+                        .withSchema('public')
+                        .where({id: event.data.id})
+                        .delete()
+                        .toQuery())];
+
+                default:
+                    return [];
+            }
+        } finally {
+            await db.destroy();
+        }
+    },
+});
+```
+
+### SQL operation patterns
+
+**Insert with upsert (create or update):**
+```typescript
+return [sql(db(tableName)
+    .withSchema('public')
+    .insert({ id: event.data.id, field: event.data.field })
+    .onConflict('id')
+    .merge(['field'])   // list only columns to update on conflict
+    .toQuery())];
+```
+
+**Update only (record already exists):**
+```typescript
+return [sql(db(tableName)
+    .withSchema('public')
+    .where({id: event.data.id})
+    .update({field: event.data.field})
+    .toQuery())];
+```
+
+**Delete:**
+```typescript
+return [sql(db(tableName)
+    .withSchema('public')
+    .where({id: event.data.id})
+    .delete()
+    .toQuery())];
+```
+
+**Async DB lookup before update** (when you need to read current state first):
+```typescript
+const row = await db(tableName)
+    .withSchema('public')
+    .where({id: event.data.id})
+    .select('field')
+    .first();
+
+if (!row) return [];
+
+const newValue = row.field + delta;
+return [sql(db(tableName)
+    .withSchema('public')
+    .where({id: event.data.id})
+    .update({field: newValue})
+    .toQuery())];
+```
+
+Always wrap in `try/finally` and call `db.destroy()` in the `finally` block.
+
+---
+
+## Step 4 — Register the projection in the event store
+
+File: `src/common/loadPostgresEventstore.ts`
+
+Add the new projection to the `projections.inline([...])` array:
+
+```typescript
+import {{SliceName}Projection} from '../slices/{context}/{SliceName}/{SliceName}Projection';
+
+// inside getPostgreSQLEventStore options:
+projections: projections.inline([
+    // ... existing projections ...
+    {SliceName}Projection,
+]),
+```
+
+---
+
+## Step 5 — Create `{SliceName}.test.ts`
+
+File: `src/slices/{context}/{SliceName}/{SliceName}.test.ts`
+
+Uses `PostgreSQLProjectionSpec` with a real PostgreSQL container (Testcontainers). Flyway runs actual migrations so the schema matches production exactly.
+
+```typescript
+import {before, after, describe, it} from 'node:test';
+import {PostgreSQLProjectionAssert, PostgreSQLProjectionSpec} from '@event-driven-io/emmett-postgresql';
+import {{SliceName}Projection} from './{SliceName}Projection';
+import {PostgreSqlContainer, StartedPostgreSqlContainer} from '@testcontainers/postgresql';
+import knex, {Knex} from 'knex';
+import assert from 'assert';
+import {runFlywayMigrations} from '../../../common/testHelpers';
+
+const TEST_ID = 'test-id-001';
+
+describe('{SliceName} Specification', () => {
+    let postgres: StartedPostgreSqlContainer;
+    let connectionString: string;
+    let db: Knex;
+    let given: PostgreSQLProjectionSpec<any>;
+
+    before(async () => {
+        postgres = await new PostgreSqlContainer('postgres').start();
+        connectionString = postgres.getConnectionUri();
+
+        db = knex({client: 'pg', connection: connectionString});
+
+        await runFlywayMigrations(connectionString);
+
+        // Insert any prerequisite rows required by foreign keys:
+        // await db('parent_table').withSchema('public').insert({...});
+
+        given = PostgreSQLProjectionSpec.for({
+            projection: {SliceName}Projection,
+            connectionString,
+        });
+    });
+
+    after(async () => {
+        await db?.destroy();
+        await postgres?.stop();
+    });
+
+    it('spec: {SliceName} - inserts row on {EventA}', async () => {
+        const assertReadModel: PostgreSQLProjectionAssert = async ({connectionString: connStr}) => {
+            const queryDb = knex({client: 'pg', connection: connStr});
+            try {
+                const result = await queryDb('{tablename}')
+                    .withSchema('public')
+                    .where({id: TEST_ID})
+                    .first();
+
+                assert.ok(result, 'row should exist');
+                assert.strictEqual(result.id, TEST_ID);
+                assert.strictEqual(result.field1, 'expected-value');
+            } finally {
+                await queryDb.destroy();
+            }
+        };
+
+        await given([{
+            type: '{EventA}',
+            data: {id: TEST_ID, field1: 'expected-value'},
+            metadata: {stream_name: `{context}-${TEST_ID}`},
+        }])
+            .when([])
+            .then(assertReadModel);
+    });
+
+    it('spec: {SliceName} - removes row on {EventB}', async () => {
+        const assertReadModel: PostgreSQLProjectionAssert = async ({connectionString: connStr}) => {
+            const queryDb = knex({client: 'pg', connection: connStr});
+            try {
+                const result = await queryDb('{tablename}')
+                    .withSchema('public')
+                    .where({id: TEST_ID})
+                    .first();
+
+                assert.strictEqual(result, undefined, 'row should be deleted');
+            } finally {
+                await queryDb.destroy();
+            }
+        };
+
+        await given([
+            {
+                type: '{EventA}',
+                data: {id: TEST_ID, field1: 'value'},
+                metadata: {stream_name: `{context}-${TEST_ID}`},
+            },
+            {
+                type: '{EventB}',
+                data: {id: TEST_ID},
+                metadata: {stream_name: `{context}-${TEST_ID}`},
+            },
+        ])
+            .when([])
+            .then(assertReadModel);
+    });
+});
+```
+
+Write one `it` block per specification in the slice.json. Use `given([events]).when([]).then(assertReadModel)`.
+
+---
+
+## Step 6 — Create `routes.ts`
+
+File: `src/slices/{context}/{SliceName}/routes.ts`
+
+> **Concrete example**: `src/slices/example/routes.ts` — shows the full pattern with `requireUser`, `assertNotEmpty`, error mapping, and OpenAPI annotations. Read it before implementing.
+
+```typescript
+import {Request, Response, Router} from 'express';
+import {WebApiSetup} from '@event-driven-io/emmett-expressjs';
+import {requireUser} from '../../../supabase/requireUser';
+import {{SliceName}ReadModel, tableName} from './{SliceName}Projection';
+import {readmodel} from '../../../core/readmodel';
+import createClient from '../../../supabase/api';
+
+export const api = (): WebApiSetup => (router: Router): void => {
+
+    router.get('/api/query/{slicename}-collection', async (req: Request, res: Response) => {
+        try {
+            const principal = await requireUser(req, res, true);
+            if (principal.error) return;
+
+            const id = req.query._id?.toString();
+            const supabase = createClient();
+
+            const data: {SliceName}ReadModel | {SliceName}ReadModel[] | null =
+                id
+                    ? await readmodel(tableName, supabase).findById<{SliceName}ReadModel>('id', id)
+                    : await readmodel(tableName, supabase).findAll<{SliceName}ReadModel>({});
+
+            const sanitized = JSON.parse(
+                JSON.stringify(data ?? [], (_, value) =>
+                    typeof value === 'bigint' ? value.toString() : value,
+                ),
+            );
+
+            return res.status(200).json(sanitized);
+        } catch (err) {
+            console.error(err);
+            return res.status(500).json({ok: false, error: 'Server error'});
+        }
+    });
+};
+```
+
+---
+
+## Step 7 — Wire up the route
+
+Find the application's router registration (usually `src/index.ts` or `src/app.ts`) and add:
+
+```typescript
+import {api as {SliceName}Api} from './slices/{context}/{SliceName}/routes';
+
+{SliceName}Api()(router);
+```
+
+---
+
+## Files to create / modify
+
+```
+src/slices/{context}/{SliceName}/
+├── {SliceName}Projection.ts    ← projection logic
+├── {SliceName}.test.ts          ← PostgreSQLProjectionSpec tests
+└── routes.ts                    ← GET query endpoint
+
+supabase/migrations/
+└── V{N}__{tablename}.sql        ← table DDL
+
+src/common/
+└── loadPostgresEventstore.ts    ← add projection to inline([...]) list
+```
+
+---
+
+## Checklist
+
+- [ ] Migration file created with correct version number and all columns
+- [ ] `tableName` constant matches the migration table name exactly
+- [ ] Projection registered in `loadPostgresEventstore.ts`
+- [ ] `canHandle` lists every event type the projection reacts to
+- [ ] `finally { await db.destroy() }` present in every `evolve` handler
+- [ ] Tests use `runFlywayMigrations()` to apply the real schema
+- [ ] One test scenario per specification in slice.json
+- [ ] Every field in the read model definition in slice.json has a column in the migration and a field in the TypeScript type — no invented columns
+- [ ] Every event type in `events[]` is listed in the projection's `canHandle` — no assumed events
+- [ ] No extra columns or fields were added beyond what slice.json defines
+- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code

package/stacks/supabase/templates/.claude/skills/build-webhook/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: build-webhook
+description: Implements a webhook slice as a self-contained Supabase Edge Function using the Emmett framework — exposes an HTTP endpoint, fires a command, emits events
+---
+
+# Build Webhook Slice (Supabase Edge Function)
+
+> Before doing anything else, read the slice definition from `.build-kit/.slices/{Context}/{slicename}/slice.json`. This file is the **source of truth** for all commands, events, and endpoint behaviour.
+
+---
+
+
+## What a Webhook Slice is
+
+A webhook slice exposes an HTTP endpoint (Supabase Edge Function) that accepts an external request (e.g. payment provider callback), translates it into an Emmett command, and appends events to the PostgreSQL event store.
+
+Architecture:
+
+```
+HTTP Request (external webhook / API call)
+    │
+    ▼
+supabase/functions/{name}/index.ts   ← edge function — parse, build command, handle
+    │
+    ▼
+CommandHandler (Emmett)              ← evolve state, decide events
+    │
+    ▼
+PostgreSQL Event Store               ← new events appended
+```
+
+The edge function is **self-contained** — it does not import from the Node.js backend. Emmett imports use Deno's `npm:` specifier; the runtime scaffold uses `jsr:@supabase/server`.
+
+---
+
+## Step 1 — Read the slice.json
+
+Extract:
+- **sliceName** — becomes the Command name and function folder name (PascalCase / kebab-case)
+- **context** — bounded context
+- **commands[]** — command data fields (build the request body shape from these)
+- **events[]** — events emitted when the command succeeds
+- **endpoint** (if present) — preferred URL path; default to kebab-case slice name
+> **Comments & description**: Each element carries a `comments: string[]` array and a `description` field. The slice also has `comments: string[]`. Use as implementation hints. When done, resolve each used comment: `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve` (get IDs first via GET on same path).
+
+---
+
+## Step 2 — Ensure the shared events union exists
+
+Check whether `src/slices/{context}/{Context}Events.ts` already has the event types. If not, add them using the same pattern as `build-state-change`:
+
+```typescript
+// src/slices/{context}/{Context}Events.ts
+import type {Event} from '@event-driven-io/emmett';
+
+type CommonMeta = {
+    stream_name?: string;
+    userId?: string;
+    correlation_id?: string;
+    causation_id?: string;
+};
+
+export type {EventName} = Event<'{EventName}', {
+    id: string;
+    // fields from slice.json events[]
+}, CommonMeta>;
+
+export type {Context}Events = /* existing */ | {EventName};
+```
+
+This keeps backend event types in sync even though the edge function is self-contained.
+
+---
+
+## Step 3 — Create the Supabase Edge Function
+
+File: `supabase/functions/{function-name}/index.ts`
+
+Function name is the slice name in kebab-case (e.g. `activate-license`).
+
+```typescript
+// Setup type definitions for built-in Supabase Runtime APIs
+import "jsr:@supabase/functions-js/edge-runtime.d.ts";
+import {withSupabase} from "jsr:@supabase/server@^1";
+import {CommandHandler, type Command} from 'npm:@event-driven-io/emmett';
+import {getPostgresEventStore} from 'npm:@event-driven-io/emmett-postgresql';
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+type CommonMeta = {
+    correlation_id?: string;
+    causation_id?: string;
+    userId?: string;
+};
+
+// Event type(s) — mirror src/slices/{context}/{Context}Events.ts
+type {EventName} = {
+    type: '{EventName}';
+    data: {
+        id: string;
+        // fields from slice.json events[]
+    };
+    metadata: CommonMeta;
+};
+
+type {Context}Events = {EventName}; // extend union if multiple events
+
+// Command type — fields from slice.json commands[]
+type {SliceName}Command = Command<'{SliceName}', {
+    id: string;
+    // other fields from slice.json commands[].fields
+}, CommonMeta>;
+
+// Request body shape — derived from commands[].fields
+interface {SliceName}Payload {
+    id?: string;
+    // other fields from slice.json commands[].fields
+}
+
+// ── State (idempotency) ───────────────────────────────────────────────────────
+
+type {SliceName}State = {
+    processed: boolean;
+};
+
+const initialState = (): {SliceName}State => ({processed: false});
+
+const evolve = (state: {SliceName}State, event: {Context}Events): {SliceName}State => {
+    switch (event.type) {
+        case '{EventName}':
+            return {...state, processed: true};
+        default:
+            return state;
+    }
+};
+
+const decide = (
+    command: {SliceName}Command,
+    state: {SliceName}State,
+): {Context}Events[] => {
+    if (state.processed) {
+        throw {code: 'already_processed', message: 'Already processed'};
+    }
+
+    return [{
+        type: '{EventName}',
+        data: {
+            id: command.data.id,
+            // map all fields from command.data per slice.json
+        },
+        metadata: {
+            correlation_id: command.metadata?.correlation_id,
+            causation_id: command.metadata?.causation_id,
+        },
+    }];
+};
+
+// ── Handler ───────────────────────────────────────────────────────────────────
+
+const {SliceName}Handler = CommandHandler<{SliceName}State, {Context}Events>({
+    evolve,
+    initialState,
+});
+
+async function handle{SliceName}(id: string, command: {SliceName}Command) {
+    const connectionString = Deno.env.get('SUPABASE_DB_URL');
+    if (!connectionString) throw new Error('SUPABASE_DB_URL not set');
+
+    const eventStore = getPostgresEventStore(connectionString);
+    const result = await {SliceName}Handler(
+        eventStore,
+        id,
+        (state: {SliceName}State) => decide(command, state),
+    );
+    return {
+        nextExpectedStreamVersion: result.nextExpectedStreamVersion?.toString(),
+        lastEventGlobalPosition: result.lastEventGlobalPosition?.toString(),
+    };
+}
+
+// ── HTTP Handler ──────────────────────────────────────────────────────────────
+
+console.info('{function-name} started');
+
+export default {
+    fetch: withSupabase({auth: ['publishable', 'secret']}, async (req, _ctx) => {
+        try {
+            const body: {SliceName}Payload = await req.json();
+            const id = body.id ?? crypto.randomUUID();
+
+            const command: {SliceName}Command = {
+                type: '{SliceName}',
+                data: {
+                    id,
+                    // map fields from body per slice.json commands[].fields
+                },
+                metadata: {
+                    correlation_id: req.headers.get('x-correlation-id') ?? id,
+                    causation_id: id,
+                },
+            };
+
+            const result = await handle{SliceName}(id, command);
+
+            return Response.json({ok: true, id, ...result}, {status: 201});
+        } catch (err: unknown) {
+            const error = err as {code?: string; message?: string};
+            if (error.code) {
+                return Response.json({error: error.message}, {status: 409});
+            }
+            console.error('[{function-name}] Unhandled error:', err);
+            return Response.json({error: 'Internal server error'}, {status: 500});
+        }
+    }),
+};
+```
+
+### Key decisions when filling in the template
+
+**Function name** — use kebab-case of the slice name as the directory (e.g. `activate-license`). This becomes the function URL: `/functions/v1/activate-license`.
+
+**`withSupabase` auth modes** — `"publishable"` allows calls with the anon key; `"secret"` allows calls with the service role key. Use `ctx.authMode` to branch on privileged vs. unprivileged behaviour if needed. For payment webhooks where the provider cannot supply a Supabase key, you may need to verify a provider-specific signature header instead (e.g. Stripe's `x-stripe-signature`).
+
+**`id` field** — always use the aggregate identifier as both the stream key and response `id`. Generate with `crypto.randomUUID()` if not provided in the request body.
+
+**Idempotency** — `state.processed` guards against replaying the same command. Match the guard to the emitted event: the `evolve` case for `{EventName}` sets `processed: true`.
+
+**Error codes** — throw `{code: 'snake_case_code', message: '...'}` from `decide`. The handler maps those to `409 Conflict`.
+
+**`SUPABASE_DB_URL`** — PostgreSQL connection string. Available automatically as a built-in secret in Supabase Edge Functions — no manual configuration needed.
+
+**CORS** — `withSupabase` handles preflight automatically. No manual `OPTIONS` handler needed.
+
+---
+
+## Step 4 — Verify event store schema migration
+
+The Emmett schema must be migrated before the edge function can write events. This happens once in the **backend startup**. Confirm that `src/common/loadPostgresEventstore.ts` calls `schema.migrate()`:
+
+```typescript
+await eventStoreInstance.schema.migrate();  // must be present
+```
+
+If the project has no Node.js backend yet, run the migration manually via a one-off script before deploying the edge function.
+
+---
+
+## Step 5 — Register the function in supabase config
+
+Add to `supabase/config.toml`:
+
+```toml
+[functions.{function-name}]
+verify_jwt = false   # false for public webhooks; true for internal API calls
+```
+
+Payment providers (Stripe, Paddle, etc.) cannot supply a Supabase JWT, so `verify_jwt = false` is the correct choice for webhook endpoints. Verify the provider's own signature header in the handler body instead.
+
+---
+
+## Step 6 — Test the edge function locally
+
+```bash
+supabase functions serve {function-name} --env-file .env.local
+```
+
+Then call it:
+
+```bash
+curl -i -X POST http://localhost:54321/functions/v1/{function-name} \
+  -H "Content-Type: application/json" \
+  -d '{ "id": "test-123", ... }'
+```
+
+---
+
+## Checklist
+
+- [ ] `supabase/functions/{function-name}/index.ts` created
+- [ ] All `{SliceName}`, `{EventName}`, `{Context}`, `{function-name}` placeholders replaced
+- [ ] Fields in `command.data` match `commands[].fields` from slice.json exactly
+- [ ] Fields in emitted event `data` match `events[].fields` from slice.json exactly
+- [ ] Idempotency guard in `decide` (throws `already_processed` on duplicate)
+- [ ] Error `code` used in `throw` so the 409 mapping works
+- [ ] Event type added to `src/slices/{context}/{Context}Events.ts`
+- [ ] `supabase/config.toml` entry added with correct `verify_jwt` setting
+- [ ] `schema.migrate()` confirmed in backend startup (or run manually)
+- [ ] Local test with `supabase functions serve` passes
+
+---
+
+## Files to create / modify
+
+```
+supabase/functions/{function-name}/
+└── index.ts    ← self-contained Deno edge function
+
+src/slices/{context}/
+└── {Context}Events.ts    ← add new event type and update union
+
+supabase/
+└── config.toml    ← register the new function
+```