create-seiro 0.1.1 → 0.1.2

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "create-seiro",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Scaffold a new Seiro project",
   "type": "module",
   "bin": {
     "create-seiro": "./index.ts"
   },
   "scripts": {
-    "test": "bun test --ignore-pattern 'template/**/*'"
+    "test": "bun test"
   },
   "files": [
     "index.ts",

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

@@ -0,0 +1,141 @@
+---
+name: cqrs-document
+description: Document-first CQRS design through conversation. Use when designing systems where users see documents (views) that are kept up to date by commands. Outputs SQL migrations and TypeScript types directly - no intermediate DSL. Triggers on discussions about documents, commands, entities, CQRS, Seiro protocol, or system design conversations that involve "what does the user see" questions.
+---
+
+# Document-First CQRS Design
+
+Design systems by starting with what the user sees (the document), then deriving entities and commands.
+
+## Core Principle
+
+A document is a composition of entity views. Commands exist to transition the document from one valid state to another. Entities are derived from what's needed to support the documents.
+
+## Conversation Workflow
+
+### 1. Establish the Document
+
+Ask: "What does the user see?"
+
+Capture the shape:
+```
+Document Venue {
+  id, name, location
+  sites: [Site { id, name, position, dimensions, area_id? }]
+  areas: [Area { id, name, parent_id? }]
+}
+```
+
+- Nesting implies joins
+- `?` means optional/nullable
+- `[]` means array/list
+- Use entity names, subset fields for views
+
+### 2. Define Commands
+
+Commands that transition the document:
+```
+commands {
+  save_venue(name, location, id?)
+  delete_venue(id)
+  save_site(venue_id, name, position, dimensions, area_id?, id?)
+  delete_site(id)
+}
+```
+
+Conventions:
+- `save_*` for create/update (id absent = create, id present = update)
+- Required parameters first, optional `id?` last
+- Commands return `{ id }` on success
+- `delete_*` with cascade logic documented
+
+### 3. Derive Entities
+
+Extract the minimal tables:
+```
+venues (id, name, location)
+sites (id, venue_id FK, name, position, dimensions, area_id?)
+areas (id, venue_id FK, name, parent_id?)
+```
+
+### 4. Output Code
+
+Once document is agreed, write directly:
+
+**SQL Migration** - Tables, constraints, command functions with pg_notify
+**TypeScript Types** - Document shapes, command/query types for Seiro
+
+## Output Conventions
+
+### SQL Command Functions
+
+```sql
+CREATE FUNCTION cmd_entity_save(
+  p_required_field text,
+  p_optional_field text DEFAULT NULL,
+  p_id int DEFAULT NULL
+) RETURNS jsonb AS $$
+DECLARE
+  v_entity entities%ROWTYPE;
+BEGIN
+  IF p_id IS NULL THEN
+    INSERT INTO entities (...) VALUES (...) RETURNING * INTO v_entity;
+  ELSE
+    UPDATE entities SET ... WHERE id = p_id RETURNING * INTO v_entity;
+  END IF;
+  
+  PERFORM pg_notify('entity_saved', jsonb_build_object(...));
+  RETURN jsonb_build_object('id', v_entity.id);
+END;
+$$ LANGUAGE plpgsql;
+```
+
+### SQL Delete with Cascade
+
+```sql
+CREATE FUNCTION cmd_entity_delete(p_id int) RETURNS void AS $$
+BEGIN
+  -- Nullify references before delete
+  UPDATE children SET entity_id = NULL WHERE entity_id = p_id;
+  DELETE FROM entities WHERE id = p_id;
+  PERFORM pg_notify('entity_deleted', jsonb_build_object('id', p_id));
+END;
+$$ LANGUAGE plpgsql;
+```
+
+### TypeScript Document Type
+
+```typescript
+export type VenueDocument = {
+  id: number
+  name: string
+  location: string
+  sites: Site[]
+  areas: Area[]
+}
+
+export type Site = {
+  id: number
+  name: string
+  position: { x: number, y: number }
+  dimensions: { w: number, h: number }
+  area_id: number | null
+}
+```
+
+## What NOT To Do
+
+- No intermediate DSL or spec files
+- No compiler or code generator to maintain
+- No UML diagrams
+- No abstract entity modelling before documents are clear
+
+## Iteration Pattern
+
+When requirements change:
+1. Update the document shape in conversation
+2. Identify entity/command changes
+3. Write migration SQL
+4. Update TypeScript types
+
+The code is the spec. PostgreSQL enforces it. TypeScript checks it.

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

@@ -0,0 +1,288 @@
+# Seiro Protocol Reference
+
+CQRS over WebSocket with Bun + Preact Signals + Web Components.
+
+## Wire Format
+
+```
+← { profile }               sent on connect (User or null)
+
+→ { cmd, cid, data }        command request
+← { cid, result }           command success
+← { cid, err }              command error
+
+→ { q, id, params }         query request
+← { id, row }               query row (repeated)
+← { id }                    query end
+← { id, err }               query error
+
+← { ev, data }              event broadcast
+
+→ { sub: "pattern" }        subscribe to events
+→ { unsub: "pattern" }      unsubscribe
+```
+
+## Type Definitions
+
+Use `Command<D, R>` and `Query<P, R>` helpers:
+
+```typescript
+import type { Command, Query } from "seiro";
+
+export type Entity = {
+  id: number;
+  name: string;
+};
+
+export type EntityCommands = {
+  "entity.create": Command<{ name: string }, { id: number }>;
+  "entity.save": Command<{ id: number; name: string }, { id: number }>;
+};
+
+export type EntityQueries = {
+  "entities.all": Query<void, Entity>;
+  "entity.detail": Query<{ id: number }, EntityDetail>;
+};
+
+export type EntityEvents = {
+  entity_created: Entity;
+  entity_updated: Entity;
+};
+```
+
+## Server Setup
+
+```typescript
+import postgres from "postgres";
+import { createServer } from "seiro/server";
+import * as auth from "./auth/server";
+import * as entity from "./entity/server";
+
+const sql = postgres(DATABASE_URL);
+
+const server = createServer({
+  port: 3000,
+  auth: {
+    verify: auth.verifyToken,
+    public: ["auth.register", "auth.login"],
+  },
+  healthCheck: async () => {
+    await sql`SELECT 1`;
+    return true;
+  },
+});
+
+// Register domain handlers
+auth.register(server, sql);
+entity.register(server, sql);
+
+await server.start({ "/": homepage });
+```
+
+## Server Handler Pattern
+
+```typescript
+import type { Sql } from "postgres";
+import type { Server } from "seiro";
+import type { Entity, EntityCommands, EntityQueries, EntityEvents } from "./types";
+
+export function register<
+  C extends EntityCommands,
+  Q extends EntityQueries,
+  E extends EntityEvents,
+>(server: Server<C, Q, E>, sql: Sql) {
+
+  // Send profile on connect (auth example)
+  server.onOpen(async (ctx) => {
+    if (!ctx.userId) {
+      ctx.send({ profile: null });
+      return;
+    }
+    // fetch and send user profile
+    ctx.send({ profile: user });
+  });
+
+  // Command with typed result
+  server.command("entity.save", async (data, ctx) => {
+    if (!ctx.userId) throw new Error("Not authenticated");
+    const [row] = await sql<[{ result: { id: number } }]>`
+      SELECT cmd_entity_save(${ctx.userId}, ${sql.json(data)}) as result
+    `;
+    return row?.result;
+  });
+
+  // Query with typed rows (generator)
+  server.query("entities.all", async function* (_params, ctx) {
+    if (!ctx.userId) throw new Error("Not authenticated");
+    const rows = await sql<{ query_entities_all: Entity }[]>`
+      SELECT query_entities_all(${ctx.userId})
+    `;
+    for (const row of rows) {
+      yield row.query_entities_all;
+    }
+  });
+}
+
+// Broadcast events from server
+server.emit("entity_created", entity);
+```
+
+## Client Setup
+
+```typescript
+import { createClient, effect } from "seiro/client";
+import type { Commands, Queries, Events, User } from "./types";
+
+const client = createClient<Commands, Queries, Events>(wsUrl);
+
+// Connect returns profile (User | null)
+const profile = await client.connect<User>();
+
+// Set up event listeners before subscribing
+client.on("entity_created", (data) => updateList(data));
+
+// Start receiving events
+client.subscribe();
+```
+
+## Client API
+
+```typescript
+// Command with callbacks
+client.cmd("entity.save", { id: 1, name: "Updated" }, {
+  onSuccess: (result) => navigate(`#/entities/${result.id}`),
+  onError: (err) => showError(err),
+});
+
+// Query (async iterator)
+for await (const row of client.query("entities.all")) {
+  items.push(row);
+}
+
+// Query all at once
+const items = await client.queryAll("entities.all");
+
+// Event subscription (returns unsubscribe function)
+const unsubscribe = client.on("entity_*", (data) => handle(data));
+
+// Sync events to a signal with reducer
+const entities = client.sync("entity_updated", initialState, (state, event) => {
+  return { ...state, [event.id]: event };
+});
+
+// Sync events to a Map signal
+const entityMap = client.syncMap("entity_updated", (e) => e.id);
+
+// Connection state (reactive signal)
+effect(() => {
+  if (client.connected.value) {
+    console.log("Connected");
+  }
+});
+
+// Auth token management
+client.setToken(token);
+client.getToken();
+client.logout();  // clears token
+
+// Connection management
+client.close();
+await client.reconnect();
+```
+
+## Web Component Pattern
+
+```typescript
+import { signal, effect } from "seiro/client";
+import type { Client } from "seiro";
+import type { Commands, Queries, Events, Entity } from "../types";
+
+type AppClient = Client<Commands, Queries, Events>;
+
+// Module-level state
+const entities = signal<Map<number, Entity>>(new Map());
+let client: AppClient;
+
+export function initEntity(c: AppClient) {
+  client = c;
+  client.on("entity_created", (entity) => {
+    const next = new Map(entities.value);
+    next.set(entity.id, entity);
+    entities.value = next;
+  });
+}
+
+class EntityList extends HTMLElement {
+  connectedCallback() {
+    this.innerHTML = `<div data-list></div>`;
+    const list = this.querySelector("[data-list]")!;
+
+    effect(() => {
+      const items = Array.from(entities.value.values());
+      list.innerHTML = items
+        .map(e => `<div>${e.name}</div>`)
+        .join("") || "<p>None yet</p>";
+    });
+  }
+}
+
+customElements.define("entity-list", EntityList);
+```
+
+## File Structure
+
+```
+project/
+  types.ts              # Combined Commands, Queries, Events
+  server.ts             # Server setup, registers handlers
+  app.ts                # Client setup, routing
+  init_db/              # SQL migrations
+  {domain}/
+    types.ts            # Domain types using Command/Query helpers
+    server.ts           # Domain handlers with typed SQL
+  components/
+    {domain}.ts         # Web Components with signals
+    shared/
+      modal.ts          # Shared modal utilities
+      router.ts         # Hash-based routing
+```
+
+## SQL Conventions
+
+Commands return `{ id }` via JSONB:
+
+```sql
+CREATE FUNCTION cmd_entity_save(p_user_id int, data jsonb)
+RETURNS jsonb AS $$
+DECLARE
+  v_entity entities%ROWTYPE;
+BEGIN
+  INSERT INTO entities (user_id, name)
+  VALUES (p_user_id, data->>'name')
+  RETURNING * INTO v_entity;
+
+  PERFORM pg_notify('entity_created', row_to_json(v_entity)::text);
+  RETURN jsonb_build_object('id', v_entity.id);
+END;
+$$ LANGUAGE plpgsql;
+```
+
+Queries return SETOF jsonb:
+
+```sql
+CREATE FUNCTION query_entities_all(p_user_id int)
+RETURNS SETOF jsonb AS $$
+  SELECT jsonb_build_object('id', id, 'name', name)
+  FROM entities
+  WHERE user_id = p_user_id
+  ORDER BY created_at DESC;
+$$ LANGUAGE sql;
+```
+
+## Conventions
+
+- Commands return `{ id }` for create/save operations
+- Queries stream rows, end with empty `{ id }`
+- Use typed SQL: `sql<[{ result: Type }]>` or `sql<{ fn_name: Type }[]>`
+- Events broadcast full data via pg_notify
+- Pattern subscriptions support wildcards: `entity_*`

package/template/CLAUDE.md

@@ -11,9 +11,9 @@ bun run check          # typecheck
 bun test               # run tests
 ```
 
-## Adding Entities
+## Adding Features
 
-Use the new-entity skill to add new entities with proper types and handlers.
+Use the `cqrs-document` skill for document-first CQRS design through conversation.
 
 ## Type Patterns
 

package/template/.claude/skills/entity-ui.md

@@ -1,169 +0,0 @@
-# Entity UI Skill
-
-Create UI components for entities using Web Components and Preact Signals.
-
-## Critical: Research First
-
-1. **Read existing components** - Look at `components/auth.ts` for the pattern
-2. **Check app.ts** - See how views are switched
-3. **Use shared utilities** - Don't reinvent modals, routing
-
-## Component Architecture
-
-### Initialization Pattern
-
-Components are initialized with the client after connection:
-
-```typescript
-// component file
-import { signal, effect } from "seiro/client";
-import type { Client } from "seiro";
-import type { Commands, Queries, Events } from "../types";
-
-type AppClient = Client<Commands, Queries, Events>;
-
-let client: AppClient;
-
-export function initMyEntity(c: AppClient) {
-  client = c;
-
-  // Subscribe to events
-  client.on("entity_created", handleCreated);
-  client.on("entity_updated", handleUpdated);
-}
-
-// app.ts - initialize after connect
-const profile = await client.connect<User>();
-initMyEntity(client);
-initAuth(client, profile);  // Auth last - triggers rendering
-client.subscribe();
-```
-
-### State with Signals
-
-Use signals for reactive state that drives UI updates:
-
-```typescript
-import { signal, effect } from "seiro/client";
-
-// Module-level state
-const entities = signal<Map<number, Entity>>(new Map());
-
-// Update by creating new Map (immutable pattern)
-function addEntity(entity: Entity) {
-  const next = new Map(entities.value);
-  next.set(entity.id, entity);
-  entities.value = next;
-}
-
-// Load from query
-async function loadEntities() {
-  const next = new Map<number, Entity>();
-  for await (const row of client.query("entities.all")) {
-    next.set(row.id, row);
-  }
-  entities.value = next;
-}
-```
-
-### Web Component Structure
-
-```typescript
-class EntityList extends HTMLElement {
-  private disposeEffects: (() => void)[] = [];
-
-  connectedCallback() {
-    this.innerHTML = `<div data-list></div>`;
-    const list = this.querySelector("[data-list]")!;
-
-    // React to signal changes
-    this.disposeEffects.push(
-      effect(() => {
-        const items = Array.from(entities.value.values());
-        list.innerHTML = items
-          .map(e => `<div>${e.name}</div>`)
-          .join("") || "<p>None yet</p>";
-      })
-    );
-  }
-
-  disconnectedCallback() {
-    // Clean up effects to prevent memory leaks
-    for (const dispose of this.disposeEffects) dispose();
-    this.disposeEffects = [];
-  }
-}
-
-customElements.define("entity-list", EntityList);
-```
-
-## Routing
-
-### Adding a Route
-
-Routes are handled in `app.ts` with hash-based navigation:
-
-```typescript
-import { route, navigate } from "./components/shared/router";
-
-effect(() => {
-  const currentRoute = route.value;
-
-  if (currentRoute.startsWith("#/myview")) {
-    main.innerHTML = `<my-component></my-component>`;
-  }
-});
-```
-
-### Navigation Links
-
-```html
-<a href="#/myview" class="text-zinc-500 hover:text-zinc-300">My View</a>
-```
-
-## Shared Utilities
-
-### Modals (components/shared/modal.ts)
-
-```typescript
-import { showToast, showInputModal, showConfirmModal, showFormModal } from "./shared/modal";
-
-// Toast notification
-showToast("Saved successfully");
-
-// Input modal - returns string or null
-const name = await showInputModal("Enter name", "Default value");
-
-// Confirm modal - returns boolean
-const confirmed = await showConfirmModal("Delete?", "This cannot be undone.");
-
-// Form modal - returns object or null
-const result = await showFormModal("Edit User", [
-  { name: "name", label: "Name", required: true },
-  { name: "email", label: "Email" },
-]);
-```
-
-### Router (components/shared/router.ts)
-
-```typescript
-import { route, navigate } from "./shared/router";
-
-// Read current route (reactive)
-effect(() => {
-  if (route.value === "#/myview") {
-    // show my view
-  }
-});
-
-// Navigate programmatically
-navigate("#/myview/123");
-```
-
-## Checklist
-
-- [ ] Component has `initX(client)` function called from app.ts
-- [ ] Event subscriptions set up in init function
-- [ ] Signal state with immutable updates (new Map)
-- [ ] Effects cleaned up in disconnectedCallback
-- [ ] Routes added to app.ts effect

package/template/.claude/skills/new-entity.md

@@ -1,198 +0,0 @@
-# New Entity Skill
-
-Create a new entity with database, server handlers, and client types.
-
-## Critical: Research First, Copy Patterns
-
-**Before writing any code:**
-
-1. **Read existing similar code** - Look at `auth/` for the pattern
-2. **Copy patterns exactly** - Don't invent new approaches, follow what already works
-3. **Check the wire protocol** - Review `CLAUDE.md` for message formats
-
-## Type Definitions
-
-Use `Command<D, R>` and `Query<P, R>` helpers for type-safe definitions:
-
-```typescript
-// {entity}/types.ts
-import type { Command, Query } from "seiro";
-
-export type {Entity} = {
-  id: number;
-  name: string;
-  // fields...
-};
-
-export type {Entity}Commands = {
-  "{entity}.create": Command<{ name: string }, { id: number }>;
-  "{entity}.save": Command<{ id: number; name: string }, { id: number }>;
-  "{entity}.delete": Command<{ id: number }, void>;
-};
-
-export type {Entity}Queries = {
-  "{entity}s.all": Query<void, {Entity}>;
-  "{entity}.detail": Query<{ id: number }, {Entity}Detail>;
-};
-
-export type {Entity}Events = {
-  {entity}_created: {Entity};
-  {entity}_updated: {Entity};
-};
-```
-
-## Typed SQL Pattern
-
-Use postgres library's type parameter:
-
-```typescript
-// Query returning multiple rows
-server.query("{entity}s.all", async function* (_params, ctx) {
-  if (!ctx.userId) throw new Error("Not authenticated");
-  const rows = await sql<{ query_{entity}s_all: {Entity} }[]>`
-    SELECT query_{entity}s_all(${ctx.userId})
-  `;
-  for (const row of rows) {
-    yield row.query_{entity}s_all;
-  }
-});
-
-// Command returning result
-server.command("{entity}.save", async (data, ctx) => {
-  if (!ctx.userId) throw new Error("Not authenticated");
-  const [row] = await sql<[{ result: { id: number } }]>`
-    SELECT cmd_{entity}_save(${ctx.userId}, ${sql.json(data)}) as result
-  `;
-  return row?.result;
-});
-```
-
-## Steps
-
-### 1. Types ({entity}/types.ts)
-
-```typescript
-import type { Command, Query } from "seiro";
-
-export type {Entity} = {
-  id: number;
-  name: string;
-};
-
-export type {Entity}Commands = {
-  "{entity}.create": Command<{ name: string }, { id: number }>;
-  "{entity}.save": Command<{ id?: number; name: string }, { id: number }>;
-  "{entity}.delete": Command<{ id: number }, void>;
-};
-
-export type {Entity}Queries = {
-  "{entity}s.all": Query<void, {Entity}>;
-};
-
-export type {Entity}Events = {
-  {entity}_created: {Entity};
-  {entity}_updated: {Entity};
-};
-```
-
-### 2. Database (init_db/)
-
-Create a new numbered SQL file (e.g., `04_{entity}_tables.sql`):
-
-```sql
--- Table
-CREATE TABLE {entity}s (
-  id SERIAL PRIMARY KEY,
-  user_id INTEGER NOT NULL REFERENCES users(id),
-  name TEXT NOT NULL,
-  created_at TIMESTAMPTZ DEFAULT now()
-);
-
--- Command: create
-CREATE OR REPLACE FUNCTION cmd_{entity}_create(p_user_id INTEGER, data JSONB)
-RETURNS JSONB AS $$
-DECLARE
-  v_result {entity}s;
-BEGIN
-  INSERT INTO {entity}s (user_id, name)
-  VALUES (p_user_id, data->>'name')
-  RETURNING * INTO v_result;
-
-  RETURN jsonb_build_object('id', v_result.id);
-END;
-$$ LANGUAGE plpgsql;
-
--- Query: all for user
-CREATE OR REPLACE FUNCTION query_{entity}s_all(p_user_id INTEGER)
-RETURNS SETOF JSONB AS $$
-  SELECT jsonb_build_object('id', id, 'name', name)
-  FROM {entity}s
-  WHERE user_id = p_user_id
-  ORDER BY created_at DESC;
-$$ LANGUAGE sql;
-```
-
-### 3. Server Handlers ({entity}/server.ts)
-
-```typescript
-import type { Sql } from "postgres";
-import type { Server } from "seiro";
-import type {
-  {Entity},
-  {Entity}Commands,
-  {Entity}Queries,
-  {Entity}Events,
-} from "./types";
-
-export function register<
-  C extends {Entity}Commands,
-  Q extends {Entity}Queries,
-  E extends {Entity}Events,
->(server: Server<C, Q, E>, sql: Sql) {
-  server.command("{entity}.create", async (data, ctx) => {
-    if (!ctx.userId) throw new Error("Not authenticated");
-    const [row] = await sql<[{ result: { id: number } }]>`
-      SELECT cmd_{entity}_create(${ctx.userId}, ${sql.json(data)}) as result
-    `;
-    return row?.result;
-  });
-
-  server.query("{entity}s.all", async function* (_params, ctx) {
-    if (!ctx.userId) throw new Error("Not authenticated");
-    const rows = await sql<{ query_{entity}s_all: {Entity} }[]>`
-      SELECT query_{entity}s_all(${ctx.userId})
-    `;
-    for (const row of rows) {
-      yield row.query_{entity}s_all;
-    }
-  });
-}
-
-export const channels = ["{entity}_created", "{entity}_updated"] as const;
-```
-
-### 4. Register Types (types.ts)
-
-```typescript
-import type { {Entity}Commands, {Entity}Queries, {Entity}Events } from "./{entity}/types";
-export type { {Entity} } from "./{entity}/types";
-
-export type Commands = AuthCommands & {Entity}Commands;
-export type Queries = AuthQueries & {Entity}Queries;
-export type Events = AuthEvents & {Entity}Events;
-```
-
-### 5. Register in Server (server.ts)
-
-```typescript
-import * as {entity} from "./{entity}/server";
-
-{entity}.register(server, sql);
-```
-
-## Checklist
-
-- [ ] Types use `Command<D, R>` and `Query<P, R>` helpers
-- [ ] Server handlers use typed SQL: `sql<[{ result: Type }]>`
-- [ ] Database functions return JSONB with `jsonb_build_object()`
-- [ ] Tests written and passing