create-seiro 0.1.8 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-seiro",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Scaffold a new Seiro project",
   "type": "module",
   "bin": {

package/template/.claude/skills/cqrs-document/SKILL.md

@@ -130,6 +130,21 @@ export type Site = {
 - No UML diagrams
 - No abstract entity modelling before documents are clear
 
+## Alternative: seiro model
+
+For larger systems where you want to visualise the complete domain (entities, documents, commands, events, sequences), use `seiro model`:
+
+```bash
+bunx seiro model add entity Product
+bunx seiro model add document Catalogue
+bunx seiro model serve  # view diagrams
+bunx seiro model export # get JSON for code generation
+```
+
+Then use the `model-generate` skill to create the application from the export.
+
+Use this skill (cqrs-document) for conversational design. Use seiro model when you need the full picture and consistency checking across a larger domain.
+
 ## Iteration Pattern
 
 When requirements change:

package/template/.claude/skills/cqrs-document/references/seiro.md

@@ -87,6 +87,7 @@ await server.start({ "/": homepage });
 ```typescript
 import type { Sql } from "postgres";
 import type { Server } from "seiro";
+import { notifyLogger } from "seiro/server";
 import type { Entity, EntityCommands, EntityQueries, EntityEvents } from "./types";
 
 export async function register<
@@ -103,10 +104,10 @@ export async function register<
         try {
           server.emit("entity_created", JSON.parse(payload) as Entity);
         } catch (e) {
-          console.error("Failed to parse entity_created payload:", payload, e);
+          notifyLogger.error("Failed to parse entity_created payload:", payload, e);
         }
       },
-      () => console.log("Listening on entity_created"),
+      () => notifyLogger.info("Listening on entity_created"),
     );
 
     await listener.listen(
@@ -115,10 +116,10 @@ export async function register<
         try {
           server.emit("entity_updated", JSON.parse(payload) as Entity);
         } catch (e) {
-          console.error("Failed to parse entity_updated payload:", payload, e);
+          notifyLogger.error("Failed to parse entity_updated payload:", payload, e);
         }
       },
-      () => console.log("Listening on entity_updated"),
+      () => notifyLogger.info("Listening on entity_updated"),
     );
 
     // Different payload type for delete - just the id
@@ -128,10 +129,10 @@ export async function register<
         try {
           server.emit("entity_deleted", JSON.parse(payload) as { id: number });
         } catch (e) {
-          console.error("Failed to parse entity_deleted payload:", payload, e);
+          notifyLogger.error("Failed to parse entity_deleted payload:", payload, e);
         }
       },
-      () => console.log("Listening on entity_deleted"),
+      () => notifyLogger.info("Listening on entity_deleted"),
     );
   }
 

package/template/.claude/skills/model-build/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: model-build
+description: Build a CQRS domain model through conversation using seiro model CLI. Use when designing larger systems where you want diagrams, consistency checking, and a formal model before generating code. Captures entities, documents, commands, events, and their relationships in model.db.
+---
+
+# Build Domain Model Through Conversation
+
+Guide the user through building a complete CQRS domain model using the seiro model CLI. The model can be visualised with `bunx seiro model serve` and used to generate code with the `model-generate` skill.
+
+## Workflow
+
+### 1. Start with Documents
+
+Ask: "What documents (views) does the user see?"
+
+For each document, capture:
+- Name and description
+- What entities it contains
+- Queries that build it
+
+```bash
+bunx seiro model add document Catalogue "All products with parts and faces"
+bunx seiro model add doc-entity Catalogue Product
+bunx seiro model add doc-entity Catalogue Part
+bunx seiro model add doc-entity Catalogue Face
+bunx seiro model add query Catalogue products "SELECT id, name, spec, tag_ids FROM products"
+```
+
+### 2. Define Entities
+
+For each entity in the documents:
+- Name and description
+- Attributes with types
+- Relationships to other entities
+
+```bash
+bunx seiro model add entity Product "A product in the catalogue"
+bunx seiro model add attribute Product name string
+bunx seiro model add attribute Product spec json
+bunx seiro model add relationship Product tagIds Tag --many --reference
+bunx seiro model add relationship Product parts Part --many
+bunx seiro model add relationship Product faces Face --many
+```
+
+Types: `string`, `integer`, `boolean`, `json`, `integer[]`
+Options: `--nullable`, `--many`, `--reference`
+
+### 3. Define Commands for Each Document
+
+For each entity in a document, determine what commands change its state. At minimum: save and delete.
+
+```bash
+# Command with input type
+bunx seiro model add entity ProductSaveCmd
+bunx seiro model add attribute ProductSaveCmd id integer --nullable
+bunx seiro model add attribute ProductSaveCmd name string
+bunx seiro model add attribute ProductSaveCmd spec json
+bunx seiro model add attribute ProductSaveCmd tagIds integer[]
+
+bunx seiro model add command product.save --entity ProductSaveCmd
+bunx seiro model add command-doc product.save Catalogue
+```
+
+### 4. Define Events for Each Command
+
+Each command emits an event with payload describing the change:
+
+```bash
+# Event with payload type
+bunx seiro model add entity ProductSavedEvt
+bunx seiro model add attribute ProductSavedEvt id integer
+bunx seiro model add attribute ProductSavedEvt name string
+bunx seiro model add attribute ProductSavedEvt spec json
+bunx seiro model add attribute ProductSavedEvt tagIds integer[]
+
+bunx seiro model add event product_saved product.save --entity ProductSavedEvt
+```
+
+### 5. Ensure Complete Coverage
+
+For each entity in each document, verify:
+
+| Entity | save command | delete command | save event | delete event |
+|--------|--------------|----------------|------------|--------------|
+| Product | product.save | product.delete | product_saved | product_deleted |
+| Part | part.save | part.delete | part_saved | part_deleted |
+| Face | face.save | face.delete | face_saved | face_deleted |
+| Tag | tag.save | tag.delete | tag_saved | tag_deleted |
+
+This is the minimum surface. Additional commands (e.g., `product.tag`) can be added for specific operations.
+
+### 6. Visualise and Verify
+
+```bash
+bunx seiro model up      # start PlantUML server
+bunx seiro model serve   # open browser to view diagrams
+```
+
+Review:
+- Entity diagram - are relationships correct?
+- Document diagrams - do they contain the right entities?
+- Command coverage - does each document have all needed commands?
+
+### 7. Export for Code Generation
+
+```bash
+bunx seiro model export > model.json
+```
+
+Then use the `model-generate` skill to create the application code.
+
+## CLI Reference
+
+```bash
+# Entities
+bunx seiro model add entity <name> [description]
+bunx seiro model add attribute <entity> <name> <type> [--nullable]
+bunx seiro model add relationship <from> <field> <to> [--many] [--reference]
+
+# Documents
+bunx seiro model add document <name> [description]
+bunx seiro model add doc-entity <document> <entity>
+bunx seiro model add query <document> <name> <sql>
+
+# Commands & Events
+bunx seiro model add command <name> [--entity <type>]
+bunx seiro model add command-doc <command> <document>
+bunx seiro model add event <name> <command> [--entity <type>]
+
+# View
+bunx seiro model list entities|documents|commands|events
+bunx seiro model serve
+bunx seiro model export
+```
+
+## Conversation Pattern
+
+1. "What does the user see?" → identify documents
+2. "What's in each document?" → identify entities and their attributes
+3. "How are they related?" → define relationships
+4. "What can change each document?" → define commands per entity
+5. "What does each change notify?" → define events
+6. "Is the surface complete?" → verify coverage matrix
+7. "Let's visualise" → run serve, review diagrams
+8. "Ready to generate" → export and use model-generate skill

package/template/.claude/skills/model-generate/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: model-generate
+description: Generate a seiro application from seiro model export. Use when you have a model.db and want to generate schema.sql, TypeScript types, and command handlers. Run `bunx seiro model export` to get the JSON input.
+---
+
+# Generate Seiro Application from Model
+
+Takes the JSON export from seiro model and generates a complete seiro application.
+
+## Usage
+
+```bash
+# Get the model export
+bunx seiro model export > model.json
+
+# Or pipe directly
+bunx seiro model export | # use in generation
+```
+
+## Input Format
+
+The export JSON contains:
+
+```json
+{
+  "entities": [
+    {
+      "name": "Product",
+      "attributes": [
+        { "name": "id", "type": "integer" },
+        { "name": "name", "type": "string" }
+      ],
+      "relationships": [
+        { "field": "tagIds", "to": "Tag", "many": true, "reference": true }
+      ]
+    }
+  ],
+  "documents": [
+    {
+      "name": "Catalogue",
+      "entities": ["Product", "Part", "Face"],
+      "queries": [
+        { "name": "products", "sql": "SELECT ..." }
+      ],
+      "commands": [
+        {
+          "name": "product.save",
+          "input": { "name": "ProductSaveCmd", "attributes": [...] },
+          "events": [
+            { "name": "product_saved", "payload": { "name": "ProductSavedEvt", "attributes": [...] } }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Output Files
+
+### 1. SQL Schema (`src/db/schema.sql`)
+
+Generate tables from entities:
+
+```sql
+CREATE TABLE IF NOT EXISTS products (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL,
+  spec TEXT NOT NULL,
+  tag_ids TEXT NOT NULL DEFAULT '[]'
+);
+
+CREATE TABLE IF NOT EXISTS parts (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  product_id INTEGER NOT NULL REFERENCES products(id) ON DELETE CASCADE,
+  child_product_id INTEGER NOT NULL REFERENCES products(id),
+  quantity INTEGER NOT NULL
+);
+```
+
+Type mapping:
+- `string` → `TEXT`
+- `integer` → `INTEGER`
+- `json` → `TEXT` (stored as JSON string)
+- `integer[]` → `TEXT` (stored as JSON array)
+- `boolean` → `INTEGER` (0/1)
+
+Relationships:
+- `reference: false` (composition) → foreign key with `ON DELETE CASCADE`
+- `reference: true` (association) → stored as `_ids` JSON array
+
+### 2. TypeScript Types (`src/types.ts`)
+
+Generate from entities and command/event types:
+
+```typescript
+// Domain entities
+export type Product = {
+  id: number
+  name: string
+  spec: Record<string, unknown>
+  tagIds: number[]
+}
+
+// Command types
+export type ProductSaveCmd = {
+  id?: number
+  name: string
+  spec: Record<string, unknown>
+  tagIds: number[]
+}
+
+// Event types
+export type ProductSavedEvt = {
+  id: number
+  name: string
+  spec: Record<string, unknown>
+  tagIds: number[]
+}
+
+// Document types
+export type CatalogueDocument = {
+  products: Product[]
+  parts: Part[]
+  faces: Face[]
+}
+```
+
+Type mapping:
+- `string` → `string`
+- `integer` → `number`
+- `json` → `Record<string, unknown>`
+- `integer[]` → `number[]`
+- `boolean` → `boolean`
+- `nullable: true` → `| null`
+
+### 3. Command Handlers (`src/commands.ts`)
+
+Generate handler stubs for each command:
+
+```typescript
+import type { CommandContext } from "seiro"
+import type { Events, ProductSaveCmd } from "./types"
+import { db } from "./db"
+
+export async function productSave(
+  data: ProductSaveCmd,
+  ctx: CommandContext<Events>
+): Promise<{ id: number }> {
+  const { id, name, spec, tagIds } = data
+  
+  if (id) {
+    // Update
+    db.run(
+      `UPDATE products SET name = ?, spec = ?, tag_ids = ? WHERE id = ?`,
+      [name, JSON.stringify(spec), JSON.stringify(tagIds), id]
+    )
+  } else {
+    // Insert
+    const result = db.run(
+      `INSERT INTO products (name, spec, tag_ids) VALUES (?, ?, ?)`,
+      [name, JSON.stringify(spec), JSON.stringify(tagIds)]
+    )
+    id = result.lastInsertRowid
+  }
+  
+  ctx.send("product_saved", { id, name, spec, tagIds })
+  return { id }
+}
+```
+
+### 4. Query Handlers (`src/queries.ts`)
+
+Generate from document queries:
+
+```typescript
+import { db } from "./db"
+import type { Product, Part, Face } from "./types"
+
+export async function* catalogueProducts(): AsyncIterable<Product> {
+  const rows = db.query(`SELECT id, name, spec, tag_ids FROM products`).all()
+  for (const row of rows) {
+    yield {
+      id: row.id,
+      name: row.name,
+      spec: JSON.parse(row.spec),
+      tagIds: JSON.parse(row.tag_ids)
+    }
+  }
+}
+```
+
+### 5. Server Setup (`src/server.ts`)
+
+Wire up commands and queries:
+
+```typescript
+import { createServer } from "seiro"
+import type { Commands, Queries, Events } from "./types"
+import { productSave, productDelete, ... } from "./commands"
+import { catalogueProducts, ... } from "./queries"
+
+const server = createServer<Commands, Queries, Events>()
+
+// Register commands
+server.command("product.save", productSave)
+server.command("product.delete", productDelete)
+// ...
+
+// Register queries  
+server.query("catalogue.products", catalogueProducts)
+// ...
+
+export { server }
+```
+
+## Conventions
+
+Follow the same patterns as the `cqrs-document` skill:
+
+- Commands are `entity.action` (e.g., `product.save`, `product.delete`)
+- Events are `entity_actioned` (e.g., `product_saved`, `product_deleted`)
+- Save commands handle both create (no id) and update (with id)
+- Delete commands return void, emit event with just `{ id }`
+- Queries yield rows for streaming
+- JSON fields stored as TEXT, parsed on read
+
+## Workflow
+
+1. Run `bunx @seiro/model export` to get JSON
+2. Generate schema.sql from entities
+3. Generate types.ts from entities + command/event types
+4. Generate command handler stubs
+5. Generate query handlers from document queries
+6. Wire up in server.ts
+
+The generated code is a starting point - handlers will need business logic added.

package/template/CLAUDE.md

@@ -13,7 +13,40 @@ bun test               # run tests
 
 ## Adding Features
 
-Use the `cqrs-document` skill for document-first CQRS design through conversation.
+Two approaches for designing CQRS systems:
+
+### Quick Path: Conversational Design
+
+Use the `cqrs-document` skill for direct conversation-to-code design. Good for smaller systems or rapid prototyping.
+
+1. Discuss what the user sees (documents)
+2. Derive entities and commands through conversation
+3. Output SQL and TypeScript directly
+
+### Model Path: Formal Domain Model
+
+Use `seiro model` for larger systems where you want diagrams, consistency checking, and a complete view of the domain.
+
+1. Use the `model-build` skill to build model.db through conversation
+   ```bash
+   bunx seiro model add entity Product
+   bunx seiro model add document Catalogue
+   bunx seiro model add command product.save
+   # ... builds complete model via CLI
+   ```
+
+2. Visualise and verify
+   ```bash
+   bunx seiro model up      # start PlantUML
+   bunx seiro model serve   # view diagrams
+   ```
+
+3. Use the `model-generate` skill to create application code from the export
+   ```bash
+   bunx seiro model export  # outputs JSON for code generation
+   ```
+
+Choose the quick path when you know what you're building. Choose the model path when you need to see the full picture first.
 
 ## Type Patterns
 

package/template/package.json

@@ -10,7 +10,7 @@
     "test": "bun test server.test.ts"
   },
   "dependencies": {
-    "seiro": "^0.1.8",
+    "seiro": "^0.1.9",
     "@preact/signals-core": "^1.12.2",
     "postgres": "^3.4.8"
   },