create-seiro 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# create-seiro
+
+Scaffold a new Seiro project.
+
+## Usage
+
+```bash
+bunx create-seiro my-app
+cd my-app
+docker compose up -d
+bun run dev
+```
+
+## What's Included
+
+The scaffolded project includes:
+
+- **Authentication** - User registration and login with JWT tokens
+- **Database** - PostgreSQL with Docker Compose setup
+- **Server** - WebSocket server with CQRS pattern
+- **Client** - Web Components with Preact Signals
+- **Skills** - Claude skills for adding new entities
+
+## Project Structure
+
+```
+my-app/
+├── auth/              # Authentication types and handlers
+├── components/        # Web components
+│   ├── auth.ts       # Login/register form
+│   └── shared/       # Shared utilities (modal, router)
+├── init_db/          # SQL initialization scripts
+├── .claude/skills/   # Claude skills for development
+├── server.ts         # Server entry point
+├── app.ts           # Client entry point
+├── types.ts         # Combined types
+└── compose.yml      # Docker Compose for PostgreSQL
+```
+
+## Adding Features
+
+Use the Claude skills to add new entities:
+
+1. Ask Claude to use the `new-entity` skill
+2. Provide entity name and fields
+3. Claude generates types, SQL, and handlers
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env bun
+import { $ } from "bun";
+import { cp, readFile, writeFile } from "fs/promises";
+import { join, resolve } from "path";
+
+const projectName = process.argv[2];
+if (!projectName) {
+  console.error("Usage: bunx create-seiro <project-name>");
+  process.exit(1);
+}
+
+const targetDir = resolve(projectName);
+const templateDir = join(import.meta.dir, "template");
+
+console.log(`Creating ${projectName}...`);
+
+// Copy template
+await cp(templateDir, targetDir, { recursive: true });
+
+// Update package.json name
+const pkgPath = join(targetDir, "package.json");
+const pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
+pkg.name = projectName;
+await writeFile(pkgPath, JSON.stringify(pkg, null, 2));
+
+// Install dependencies
+console.log("Installing dependencies...");
+await $`cd ${targetDir} && bun install`.quiet();
+
+console.log(`
+Done! Next steps:
+
+  cd ${projectName}
+  docker compose up -d
+  bun run dev
+`);

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "create-seiro",
+  "version": "0.1.0",
+  "description": "Scaffold a new Seiro project",
+  "type": "module",
+  "bin": {
+    "create-seiro": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "template"
+  ],
+  "keywords": [
+    "seiro",
+    "scaffold",
+    "cli",
+    "cqrs",
+    "websocket"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blueshed/seiro.git",
+    "directory": "packages/create-seiro"
+  }
+}

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

@@ -0,0 +1,169 @@
+# 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

@@ -0,0 +1,198 @@
+# 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

package/template/CLAUDE.md

@@ -0,0 +1,49 @@
+# Project Dev Context
+
+CQRS over WebSocket. Bun + Preact Signals + Web Components.
+
+## Commands
+
+```bash
+docker compose up -d   # start database
+bun run dev            # server on :3000
+bun run check          # typecheck
+bun test               # run tests
+```
+
+## Adding Entities
+
+Use the new-entity skill to add new entities with proper types and handlers.
+
+## Type Patterns
+
+Use `Command<D, R>` and `Query<P, R>` from seiro:
+
+```typescript
+import type { Command, Query } from "seiro";
+
+export type MyCommands = {
+  "thing.create": Command<{ name: string }, { id: number }>;
+};
+
+export type MyQueries = {
+  "things.all": Query<void, Thing>;
+};
+```
+
+## Typed SQL
+
+```typescript
+const rows = await sql<{ query_things_all: Thing }[]>`
+  SELECT query_things_all(${ctx.userId})
+`;
+for (const row of rows) {
+  yield row.query_things_all;
+}
+```
+
+## Wire Protocol
+
+Commands: `{ cmd: "name", cid: "abc123", data: {...} }`
+Queries: `{ q: "name", id: 1, params: {...} }`
+Events: `{ ev: "name", data: {...} }`

package/template/app.ts

@@ -0,0 +1,40 @@
+import { createClient, effect } from "seiro/client";
+import type { Commands, Queries, Events, User } from "./types";
+import { initAuth, user } from "./components/auth";
+import "./components/auth";
+
+// Create client
+const wsUrl = `ws://${window.location.host}/ws`;
+const client = createClient<Commands, Queries, Events>(wsUrl);
+
+// Connect and initialize
+async function main() {
+  const profile = await client.connect<User>();
+  initAuth(client, profile);
+  client.subscribe();
+
+  // Show/hide content based on auth state
+  effect(() => {
+    const main = document.querySelector("main");
+    if (main) {
+      if (user.value) {
+        main.innerHTML = `
+          <div class="text-center py-12">
+            <h2 class="text-2xl font-bold text-white mb-4">Welcome!</h2>
+            <p class="text-zinc-400">You are logged in as ${user.value.email}</p>
+            <p class="text-zinc-500 mt-8">Start building your app by adding entities.</p>
+          </div>
+        `;
+      } else {
+        main.innerHTML = `
+          <div class="text-center py-12">
+            <h2 class="text-2xl font-bold text-white mb-4">Welcome to Seiro</h2>
+            <p class="text-zinc-400">Please login or register to continue.</p>
+          </div>
+        `;
+      }
+    }
+  });
+}
+
+main().catch(console.error);