@eventmodelers/node-kit 0.0.11 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/node-kit",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Real-time Claude agent that reacts to slice:changed events on an Eventmodelers board",
   "type": "module",
   "bin": {

package/templates/.claude/skills/build-automation/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: build-automation
+description: Implements an emmett automation slice (reactor processor + command handler) from a slice.json definition
+---
+
+# Build Automation Slice
+
+> Before doing anything else, read the slice definition from `.slices/{Context}/{slicename}/slice.json`. This file is the **source of truth** for which trigger event drives the automation and what command it fires.
+
+---
+
+## What an Automation Slice is
+
+An automation slice reacts to events from the event store and fires a command in response. It replaces the old CRON + TODO-list pattern with an event-driven **reactor**.
+
+Architecture:
+
+```
+Event Store
+    │  (TriggerEvent emitted by another slice)
+    ▼
+processor.ts   ← reactor — listens, maps, fires command
+    │
+    ▼
+{SliceName}Command.ts   ← command handler (decide/evolve)
+    │
+    ▼
+Event Store   ← new events appended
+```
+
+An automation slice is a **state-change slice with a reactor**. Always build the command handler first, then wire the processor.
+
+---
+
+## Step 1 — Read the slice.json
+
+From the slice definition, extract:
+- **sliceName** — the command being fired by the automation
+- **context** — bounded context
+- **processors[]** — each processor defines:
+  - `triggerEvent` — the event that starts the automation
+  - `command` — the command to fire
+  - `processorId` — unique kebab-case identifier
+- **commands[]** — command data fields
+- **events[]** — events emitted by the command
+
+---
+
+## Step 2 — Build the command handler
+
+Follow the **build-state-change** skill to create:
+- `{SliceName}Command.ts` (Command type, evolve, decide, handle{SliceName})
+- `{SliceName}.test.ts` (DeciderSpecification tests)
+
+**Do NOT create a `routes.ts`** for automations — the command is fired internally by the processor, not via HTTP.
+
+Refer to the build-state-change skill for the full command handler structure.
+
+---
+
+## Step 3 — Ensure the trigger event type exists
+
+The trigger event must be defined in `[Context]Events.ts`. If it belongs to a different context, import it from that context's events file.
+
+If the trigger event is missing from the union type, add it:
+
+```typescript
+// in {TriggerContext}Events.ts
+export type {TriggerEventName} = Event<'{TriggerEventName}', {
+    id: string;
+    // fields the processor will use to construct the command
+}, CommonMeta>;
+
+export type {TriggerContext}Events = /* existing */ | {TriggerEventName};
+```
+
+---
+
+## Step 4 — Create `processor.ts`
+
+File: `src/slices/{context}/{SliceName}/processor.ts`
+
+```typescript
+import {type {TriggerEventName}} from '../{TriggerContext}Events';
+import {{SliceName}Command, handle{SliceName}} from './{SliceName}Command';
+import {PostgresEventStore, PostgreSQLEventStoreConsumer} from '@event-driven-io/emmett-postgresql';
+import {storeDlqMessage} from '../../../common/processorDlq';
+import {v4} from 'uuid';
+
+const PROCESSOR_ID = '{unique-kebab-case-processor-id}';
+
+let _consumer: PostgreSQLEventStoreConsumer<{TriggerEventName}> | null = null;
+
+export const processor = {
+    start: async (eventStore: PostgresEventStore) => {
+        _consumer = eventStore.consumer<{TriggerEventName}>();
+
+        _consumer.reactor<{TriggerEventName}>({
+            processorId: PROCESSOR_ID,
+            processorInstanceId: v4(),   // new UUID each restart — enables competing consumers
+            canHandle: ['{TriggerEventName}'],
+            lock: {
+                timeoutSeconds: 30,
+                acquisitionPolicy: {type: 'retry', retries: 60, minTimeout: 1000, maxTimeout: 2000},
+            },
+            eachMessage: async (message) => {
+                try {
+                    console.log(`Processing ${message.type} for ${message.data.id}`);
+
+                    const command: {SliceName}Command = {
+                        type: '{SliceName}',
+                        data: {
+                            id: message.data.id,
+                            // map fields from message.data to the command's data shape
+                        },
+                        metadata: {
+                            correlation_id: message.data.id,
+                            causation_id: message.metadata?.correlation_id,
+                        },
+                    };
+
+                    await handle{SliceName}(message.data.id, command);
+                } catch (err) {
+                    console.error(`${PROCESSOR_ID}: failed to process message`, message.data, err);
+                    await storeDlqMessage(PROCESSOR_ID, message, err);
+                }
+            },
+        });
+
+        _consumer?.start().catch(err =>
+            console.error(`${PROCESSOR_ID} consumer error:`, err),
+        );
+    },
+
+    stop: async () => {
+        await _consumer?.stop();
+    },
+};
+```
+
+### Key decisions when filling in the template
+
+**`PROCESSOR_ID`** — unique kebab-case string identifying this processor across restarts. Use format: `{slicename}-automation` (e.g. `assign-user-to-organization-automation`). Never reuse IDs between processors.
+
+**`processorInstanceId`** — `v4()` UUID generated at startup. A new UUID each time the server restarts allows multiple competing consumers to run safely in parallel.
+
+**`canHandle`** — must list only the exact event type string(s) this reactor listens to.
+
+**`lock`** — do not change the lock configuration unless there is a specific reason. The defaults provide safe at-least-once delivery with retry.
+
+**Metadata mapping:**
+- `correlation_id` in the command → pass the trigger message's `id` (aggregate identifier)
+- `causation_id` in the command → pass the trigger message's `metadata?.correlation_id`
+
+**DLQ** — always wrap `eachMessage` in try/catch and call `storeDlqMessage` on failure. Failed messages are not retried automatically; the DLQ record allows manual reprocessing.
+
+---
+
+## Step 5 — Register the processor in application startup
+
+Find the app startup file (usually `src/index.ts` or `src/server.ts`) where other processors are started. Add:
+
+```typescript
+import {processor as {SliceName}Processor} from './slices/{context}/{SliceName}/processor';
+
+// during startup, after eventStore is initialized:
+await {SliceName}Processor.start(eventStore);
+
+// during shutdown:
+await {SliceName}Processor.stop();
+```
+
+The `eventStore` instance is the one returned by `findEventstore()` — reuse the shared instance, do not create a second one.
+
+---
+
+## Step 6 — Verify the event store bootstrap
+
+The event store **must** call `schema.migrate()` before any processor starts. Check `src/common/loadPostgresEventstore.ts`:
+
+```typescript
+export const findEventstore = async () => {
+    // ...
+    await eventStoreInstance.schema.migrate();  // ← must be present
+    return eventStoreInstance;
+};
+```
+
+If this line is missing, add it. Without it, the emmett schema functions (`emt_try_acquire_processor_lock` etc.) are not created and the reactor will fail to start.
+
+---
+
+## Processor patterns reference
+
+### Single trigger event → single command (standard)
+
+```typescript
+eachMessage: async (message) => {
+    const command: MyCommand = {
+        type: 'MyCommand',
+        data: {id: message.data.id},
+        metadata: {
+            correlation_id: message.data.id,
+            causation_id: message.metadata?.correlation_id,
+        },
+    };
+    await handleMyCommand(message.data.id, command);
+},
+```
+
+### Conditional processing (skip if condition not met)
+
+```typescript
+eachMessage: async (message) => {
+    if (!message.data.someField) {
+        console.log(`Skipping — someField not set for ${message.data.id}`);
+        return;
+    }
+    // proceed normally
+},
+```
+
+### Multiple commands from one trigger
+
+```typescript
+eachMessage: async (message) => {
+    await handleFirstCommand(message.data.id, firstCommand);
+    await handleSecondCommand(message.data.id, secondCommand);
+},
+```
+
+---
+
+## Files to create / modify
+
+```
+src/slices/{context}/{SliceName}/
+├── {SliceName}Command.ts    ← command handler (decide/evolve/handle) — see build-state-change
+├── {SliceName}.test.ts      ← DeciderSpecification tests — see build-state-change
+└── processor.ts             ← reactor (start/stop)
+
+src/
+└── index.ts (or server.ts)  ← register processor.start() / processor.stop()
+
+src/common/
+└── loadPostgresEventstore.ts ← verify schema.migrate() is called
+```
+
+---
+
+## Checklist
+
+- [ ] `PROCESSOR_ID` is unique across all processors in the codebase (grep to verify)
+- [ ] `processorInstanceId` uses `v4()` — not a hardcoded string
+- [ ] `canHandle` matches the exact event type string from `{Context}Events.ts`
+- [ ] `eachMessage` is wrapped in try/catch with `storeDlqMessage` fallback
+- [ ] Processor registered in application startup (start + stop)
+- [ ] `schema.migrate()` is called in `loadPostgresEventstore.ts`
+- [ ] No `routes.ts` created (automations are not exposed via HTTP)
+- [ ] Command handler tests cover idempotency (what happens if the command fires twice)

package/templates/.claude/skills/build-state-change/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: build-state-change
+description: Implements an emmett state-change slice (command handler, tests, route) from a slice.json definition
+---
+
+# Build State Change 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 metadata. Never invent fields not defined there.
+
+---
+
+## What a State Change Slice is
+
+A state-change slice processes a command using event sourcing. It:
+1. Loads the current aggregate state by replaying past events (`evolve`)
+2. Validates the command against that state (`decide`)
+3. Returns new events if valid, throws if not
+
+---
+
+## Step 1 — Read the slice.json
+
+From the slice definition, extract:
+- **sliceName** — the slice title (becomes the Command name)
+- **context** — the bounded context (used to find `[Context]Events.ts`)
+- **commands[]** — list of commands with their data fields
+- **events[]** — list of events emitted by each command
+- **specifications[]** — test scenarios (given/when/then)
+
+---
+
+## Step 2 — Ensure the shared events union exists
+
+Each context has one `[Context]Events.ts` file that exports a union of all event types.
+
+File location: `src/slices/{context}/[Context]Events.ts` (or wherever the existing one lives — search for it).
+
+### Event type shape
+
+```typescript
+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}', {
+    // data fields from slice.json
+}, CommonMeta>;
+
+// Add the new event to the union
+export type {Context}Events = /* existing events */ | {EventName};
+```
+
+Add each new event type and update the union. Do NOT remove existing types.
+
+---
+
+## Step 3 — Create `{SliceName}Command.ts`
+
+File: `src/slices/{context}/{SliceName}/{SliceName}Command.ts`
+
+### Full structure
+
+```typescript
+import type {Command} from '@event-driven-io/emmett';
+import {CommandHandler} from '@event-driven-io/emmett';
+import {type {Context}Events} from '../{Context}Events';
+import {findEventstore} from '../../../common/loadPostgresEventstore';
+
+// 1. Command type — data fields come from slice.json commands[]
+export type {SliceName}Command = Command<'{SliceName}', {
+    id: string;
+    // ... other data fields from the slice definition
+}, {
+    correlation_id?: string;
+    causation_id?: string;
+}>;
+
+// 2. State — only fields needed for validation
+export type {SliceName}State = {
+    // e.g. { processed: boolean } or { assignedIds: Set<string> }
+    // Use {} if no validation state is needed
+};
+
+export const {SliceName}InitialState = (): {SliceName}State => ({
+    // initial values
+});
+
+// 3. Evolve — pure function, updates state from past events
+export const evolve = (
+    state: {SliceName}State,
+    event: {Context}Events,
+): {SliceName}State => {
+    const {type} = event;
+
+    switch (type) {
+        case '{EmittedEventName}':
+            return {...state, /* update field */};
+        default:
+            return state;
+    }
+};
+
+// 4. Decide — validates command, returns events or throws
+export const decide = (
+    command: {SliceName}Command,
+    state: {SliceName}State,
+): {Context}Events[] => {
+    // idempotency / business rule check
+    if (state.processed) {
+        throw {code: 'already_processed', message: 'Already processed'};
+    }
+
+    return [{
+        type: '{EmittedEventName}',
+        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,
+            userId: command.data.userId,
+        },
+    }];
+};
+
+// 5. CommandHandler + exported handle function
+const {SliceName}CommandHandler = CommandHandler<{SliceName}State, {Context}Events>({
+    evolve,
+    initialState: {SliceName}InitialState,
+});
+
+export const handle{SliceName} = async (id: string, command: {SliceName}Command) => {
+    const eventStore = await findEventstore();
+    const result = await {SliceName}CommandHandler(
+        eventStore,
+        id,
+        (state: {SliceName}State) => decide(command, state),
+    );
+    return {
+        nextExpectedStreamVersion: result.nextExpectedStreamVersion,
+        lastEventGlobalPosition: result.lastEventGlobalPosition,
+    };
+};
+```
+
+### State complexity guide
+
+| Scenario | State shape |
+|----------|-------------|
+| Simple create-once | `{ created: boolean }` |
+| Idempotency by user | `{ processedUserIds: Set<string> }` |
+| Count validation | `{ count: number; limit: number }` |
+| No validation needed | `{}` (empty object) |
+
+---
+
+## Step 4 — Create `{SliceName}.test.ts`
+
+File: `src/slices/{context}/{SliceName}/{SliceName}.test.ts`
+
+Use `DeciderSpecification` for unit tests. Derive test scenarios from `specifications[]` in the slice.json.
+
+```typescript
+import {DeciderSpecification} from '@event-driven-io/emmett';
+import {
+    {SliceName}Command,
+    {SliceName}InitialState,
+    decide,
+    evolve,
+} from './{SliceName}Command';
+import {describe, it} from 'node:test';
+
+describe('{SliceName} Specification', () => {
+    const given = DeciderSpecification.for({
+        decide,
+        evolve,
+        initialState: {SliceName}InitialState,
+    });
+
+    it('spec: {SliceName} - creates event on empty stream', () => {
+        const command: {SliceName}Command = {
+            type: '{SliceName}',
+            data: {
+                id: 'test-id',
+                // ... test values
+            },
+            metadata: {},
+        };
+
+        given([])
+            .when(command)
+            .then([{
+                type: '{EmittedEventName}',
+                data: {
+                    id: 'test-id',
+                    // ... expected event data
+                },
+                metadata: {},
+            }]);
+    });
+
+    it('spec: {SliceName} - throws when already processed', () => {
+        const command: {SliceName}Command = {
+            type: '{SliceName}',
+            data: {id: 'test-id'},
+            metadata: {},
+        };
+
+        given([{
+            type: '{EmittedEventName}',
+            data: {id: 'test-id'},
+            metadata: {},
+        }])
+            .when(command)
+            .thenThrows();
+    });
+});
+```
+
+Add one test per specification in the slice.json. If the spec has no precondition events, use `given([])`.
+
+---
+
+## Step 5 — 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}Command, handle{SliceName}} from './{SliceName}Command';
+
+export const api = (): WebApiSetup => (router: Router): void => {
+
+    router.post('/api/{slicename}/:id', async (req: Request, res: Response) => {
+        const auth = await requireUser(req, res);
+        if (auth.error) return;
+
+        const id = req.params.id;
+        const correlationId = req.header('correlation_id') ?? id;
+
+        try {
+            const command: {SliceName}Command = {
+                type: '{SliceName}',
+                data: {
+                    id,
+                    // ... map from req.body
+                },
+                metadata: {
+                    correlation_id: correlationId,
+                    causation_id: id,
+                },
+            };
+
+            const result = await handle{SliceName}(id, command);
+
+            res.set('correlation_id', correlationId);
+            res.set('causation_id', id);
+
+            return res.status(201).json({
+                ok: true,
+                next_expected_stream_version: result.nextExpectedStreamVersion?.toString(),
+                last_event_global_position: result.lastEventGlobalPosition?.toString(),
+            });
+        } catch (err: any) {
+            const errorMessage = errorMapping(err?.code);
+            if (errorMessage) {
+                return res.status(409).json({error: errorMessage});
+            }
+            console.error(err);
+            return res.status(500).json({ok: false, error: 'Server error'});
+        }
+    });
+};
+
+const errorMapping = (code: string): string | null => {
+    switch (code) {
+        case 'already_processed': return 'This action has already been performed.';
+        // add other error codes from slice.json specifications
+        default: return null;
+    }
+};
+```
+
+---
+
+## Step 6 — 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';
+
+// inside the router setup:
+{SliceName}Api()(router);
+```
+
+---
+
+## Key patterns
+
+- **Metadata optional chaining**: always use `command.metadata?.correlation_id` (metadata may be absent in tests)
+- **Throw with code**: `throw {code: 'snake_case_code', message: '...'}` — routes catch by `err?.code`
+- **Idempotency in evolve**: track processed IDs in state, check in decide
+- **Stream ID**: pass the aggregate ID as the first argument to `handle{SliceName}(id, command)` — the stream is `{context}-{id}`
+- **No side effects in evolve**: evolve must be a pure function; all side effects go in decide or the route
+
+---
+
+## Files to create
+
+```
+src/slices/{context}/{SliceName}/
+├── {SliceName}Command.ts    ← command handler (decide/evolve/handle)
+├── {SliceName}.test.ts      ← DeciderSpecification tests
+└── routes.ts                ← Express POST endpoint
+
+src/slices/{context}/
+└── {Context}Events.ts       ← add new event types here (update union)
+```