@nebulit/embuilder 0.1.46 → 0.1.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulit/embuilder",
-  "version": "0.1.46",
+  "version": "0.1.48",
   "description": "Event-model driven development toolkit for Claude Code",
   "type": "module",
   "bin": {

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

@@ -1,49 +1,251 @@
 ---
-name: skeleton-automation
-description: Generate automation slices from config.json
+name: slice-automation
+description: builds an automation slice from an event model
 ---
 
-# Generate Automation Slice
+### Critical understanding
 
-Generate automation slices (background processors with CRON scheduling) from your event model configuration.
+Make sure to read the Agents.md file before building anything.
 
-## Task
+If the processors-Array is not empty, it´s an automation slice.
 
-You are tasked with generating one or more automation slices using the emmet-supabase Yeoman generator.
+Important - an automation slice is "just" a state-change slice with an additional automation that triggers the command.
+So also read the skill for 'state-change-slice'
 
-## Steps
+## Critical Requirements
 
-1. Check if a `config.json` file exists in the current directory
-   - If not found, inform the user they need a config.json file
-   - Exit with instructions on creating one
+### Restaurant ID Requirement
+- **CRITICAL**: ALL events MUST have `restaurantId` in their metadata (camelCase)
+- **NEVER** use `locationId` or `location_id` - these are outdated and forbidden
+- **CRITICAL**: ALL database tables (including TODO lists) MUST have a `restaurant_id` column (snake_case)
+- This ensures proper multi-tenancy and data isolation
 
-2. Read the config.json to find available AUTOMATION slices:
-   - Look for slices with `"sliceType": "AUTOMATION"`
-   - Extract their IDs and titles
+## Overview
 
-3. Show the user available automation slices and ask which ones to generate
-   - Allow multiple selections
-   - Or accept slice IDs from the user's original request
+Automations are processes that happen in the background, based on a TODO List.
+TODO Lists are always tables (read models) and each row in the table is a TODO Item.
 
-4. Run the local generator with selected slices:
-   ```bash
-   npx yo ./.claude/skills/gen-skeleton/generators/emmet-supabase/app --action AUTOMATION --slices <slice-id-1>,<slice-id-2>
-   ```
+The automation is only responsible to:
+1. Fetch items from the TODO List (read model)
+2. Fire the command for each item
+3. Repeat on a schedule using CRON
 
-5. After generation completes:
-   - List the files that were created
-   - Run tests for the generated slices if available
-   - Explain the CRON configuration if applicable
-   - Suggest next steps
+## Architecture Pattern
+
+```
+┌─────────────────┐
+│  TODO List      │  (Read Model - Inbound Dependency)
+│  "items to do"  │  Example: "clerks_to_invite", "items_to_fetch"
+└────────┬────────┘
+         │
+         │ reads
+         │
+┌────────▼────────┐
+│   processor.ts  │  (CRON scheduled automation)
+│                 │  - Fetches TODO items
+│                 │  - Fires commands
+└────────┬────────┘
+         │
+         │ invokes
+         │
+┌────────▼────────┐
+│ CommandHandler  │  (State-change logic)
+│   Command.ts    │  - decide() function
+│   routes.ts     │  - evolve() function
+└─────────────────┘
+```
+
+## Implementation Structure
+
+An automation slice consists of:
+1. **processor.ts** - CRON automation that fetches TODO items and fires commands
+2. **[Command]Command.ts** - Command handler with decide/evolve logic
+3. **routes.ts** - HTTP API endpoint for manual command invocation
+
+## Processor Configuration
+
+Two patterns exist in the codebase:
+
+### Pattern 1: Using startProcessor helper (Recommended)
+
+```typescript
+import {ProcessorConfig, ProcessorTodoItem, startProcessor} from "../../process/process";
+import {handleYourCommand} from "./YourCommandCommand";
+
+export type ItemToProcess = {
+    itemId: string,
+    // other fields from read model
+}
+
+const config: ProcessorConfig = {
+    schedule: "*/5 * * * * *", // Every 5 seconds (cron format)
+    endpoint: "your-todo-list-collection", // Read model endpoint
+    query: {
+        "status": "OPEN",    // Filter criteria
+        "_limit": "1"         // Process one at a time
+    }
+}
+
+const handler = async (item: ItemToProcess & ProcessorTodoItem) => {
+    console.log(`Processing item: ${item.itemId}`)
+
+    try {
+        await handleYourCommand(`aggregate-${item.itemId}`, {
+            type: "YourCommand",
+            data: {
+                itemId: item.itemId,
+                // map other fields
+            },
+            metadata: {}
+        })
+
+        console.log(`Successfully processed item: ${item.itemId}`)
+    } catch (error) {
+        console.error(`Error processing item ${item.itemId}:`, error)
+    }
+}
+
+export const processor = {
+    start: () => {
+        console.log("[YourProcessor] Starting processor...")
+        startProcessor<ItemToProcess>(config, handler)
+    }
+}
+```
+
+### Pattern 2: Direct Supabase query (Legacy)
+
+```typescript
+import {ProcessorConfig} from "../../process/process";
+import {YourCommand, handleYourCommand} from "./YourCommandCommand";
+import cron from "node-cron";
+import {createServiceClient} from "../../supabase/api";
+
+const config: ProcessorConfig = {
+    schedule: '*/30 * * * * *',  // Every 30 seconds
+    endpoint: "your_todo_table",  // Supabase table name
+}
+
+export const processor = {
+    start: () => {
+        cron.schedule(config.schedule, async () => {
+            console.log("Running process")
+            let client = createServiceClient()
+            let result = await client.from(config.endpoint).select("*")
+
+            if (result.count == 0) {
+                console.log(`Nothing to do for ${config.endpoint}`)
+                return;
+            }
+
+            for (const item of result.data ?? []) {
+                const command: YourCommand = {
+                    type: "YourCommand",
+                    data: {
+                        itemId: item.itemId!
+                    },
+                    metadata: {}
+                }
+
+                const id = item.itemId
+                if (!id) {
+                    throw `Cannot process Command ${command.type}. No Id available.`
+                }
+                await handleYourCommand(id, command)
+            }
+        })
+    }
+}
+```
+
+## CRON Schedule Format
+
+```
+┌───────────── second (0-59)
+│ ┌─────────── minute (0-59)
+│ │ ┌───────── hour (0-23)
+│ │ │ ┌─────── day of month (1-31)
+│ │ │ │ ┌───── month (1-12)
+│ │ │ │ │ ┌─── day of week (0-7)
+│ │ │ │ │ │
+* * * * * *
+```
+
+Common schedules:
+- `*/5 * * * * *` - Every 5 seconds
+- `*/30 * * * * *` - Every 30 seconds
+- `0 */1 * * * *` - Every minute
+- `0 0 * * * *` - Every hour
+
+## Real Examples from Codebase
+
+### Example 1: ConfirmInvitation (Clerk management)
+
+**TODO List Read Model**: `clerks_to_invite` table
+**Automation**: `src/slices/ConfirmInvitation/processor.ts`
+**Command**: `ConfirmInvitationCommand`
+**Event Emitted**: `ClerkInvitationConfirmed`
+
+```typescript
+// processor.ts
+const config: ProcessorConfig = {
+    schedule: '*/30 * * * * *',
+    endpoint: "clerks_to_invite",
+}
+
+// Fetches clerks from TODO list and confirms their invitations
+for (const clerk of result.data ?? []) {
+    const command: ConfirmInvitationCommand = {
+        type: "ConfirmInvitation",
+        data: {
+            clerkId: clerk.clerkId!
+        },
+        metadata: {}
+    }
+    await handleConfirmInvitation(clerk.clerkId, command)
+}
+```
+
+in each slice folder, generate a file .slice.json
+```
+{
+    "id" : "<slice id>",
+    "slice": "<slice title>",
+    "context": "<contextx>",
+    "link": "https://miro.com/app/board/<board-id>=/?moveToWidget=<slice id>"
+}
+```
+
+## Key Points
+
+1. **TODO List Naming**: Use format `<things>_to_<action>` (e.g., `clerks_to_invite`, `items_to_fetch`)
+2. **Read Model Endpoint**: TODO list is accessed via `/api/query/<name>-collection` endpoint
+3. **Processor Types**: Define TypeScript types for TODO items matching read model structure
+4. **Error Handling**: Always wrap command execution in try-catch, log errors but continue processing
+5. **Schedule Wisely**: Balance responsiveness vs system load (30 seconds is common for production)
+6. **Status Management**: TODO list typically has a `status` field ("OPEN", "PROCESSING", "DONE")
+7. **Limit Processing**: Use `_limit: "1"` to process one item at a time, preventing concurrent issues
+8. **Stream Naming**: Use aggregate-based stream names (e.g., `catalogue-${itemId}`)
+
+## Implementation Steps
+
+1. **Read the input JSON** from templates/sample-input.json
+2. **Create processor.ts** following one of the patterns above
+3. **Implement state-change slice** using the 'state-change-slice' skill
+    - Creates `[Command]Command.ts` with decide/evolve functions
+    - No `routes.ts` for Automations.
+4. **Register processor** in main application startup
+5. **Ensure TODO List exists** as a read model (separate slice handles this)
+
+## Sample Input Structure
+
+Sample input: read 'templates/sample-input.json'
+
+The input defines:
+- **processors[]**: Array of automation definitions
+    - title: Automation name
+    - dependencies: Inbound (TODO list) and Outbound (Command) connections
+- **commands[]**: Commands triggered by the automation
+- **events[]**: Events emitted by the commands
 
-## Important Notes
 
-- The generator is located in `.claude/skills/gen-skeleton/generators/emmet-supabase`
-- Multiple slices can be generated in one command (comma-separated)
-- Slice IDs must exactly match those in config.json
-- Generated files typically include:
-  - processor.ts (background automation logic)
-  - CRON configuration
-  - Tests
-- Automation slices read from TODO lists (work queues) and fire commands on a schedule
-- Common use cases: auto-confirm invitations, process checkouts, send notifications