bonescript-compiler 0.8.0 → 0.9.0

package/dist/emit_sqlite.d.ts

@@ -25,8 +25,49 @@ export declare function emitSqliteAuditSchema(): string;
 export declare function emitSqliteDbClient(system: IR.IRSystem): string;
 export declare function emitSqliteMigration(_system: IR.IRSystem, schemas: string[]): string;
 export declare function emitSqlitePackageJson(system: IR.IRSystem): string;
+import { FullEmitterOptions } from "./emit_full";
 export declare class SqliteEmitter {
-    emit(system: IR.IRSystem): EmittedFile[];
+    /**
+     * Emit a complete SQLite-backed Express project.
+     *
+     * Strategy: delegate the bulk of generation to FullEmitter (routes, auth,
+     * websocket, etc), then swap out the Postgres-specific pieces for SQLite
+     * equivalents. The generated routes use a Postgres-shaped SQL surface that
+     * our SQLite db.ts client translates at runtime (NOW() → datetime('now'),
+     * $N → ?, RETURNING * → re-select by id).
+     *
+     * What's swapped:
+     *   - package.json       SQLite deps (better-sqlite3) instead of pg
+     *   - .env.example       SQLite-shaped env vars
+     *   - src/db.ts          better-sqlite3 client with SQL translation
+     *   - src/migrate.ts     SQLite migration runner
+     *   - migrations/*.sql   SQLite-flavored DDL (TEXT, no JSONB, etc.)
+     *   - README.md          SQLite-aware quick start
+     *
+     * What's removed:
+     *   - docker-compose.yaml, Dockerfile, k8s/deployment.yaml — SQLite is
+     *     single-file; no service orchestration needed
+     *
+     * Known limitations:
+     *   - Capability bodies that use jsonb_set / jsonb_agg / jsonb_array_elements
+     *     fail at runtime. Refactor those capabilities or use the Express target.
+     *   - Durable event delivery (EVENT_MODE=durable) requires Postgres-only
+     *     features (FOR UPDATE SKIP LOCKED). Default is in_process which works
+     *     fine on SQLite.
+     *   - row_to_json(t.*) in LIST joins degrades to t.id (no full join object).
+     */
+    emit(system: IR.IRSystem, options?: FullEmitterOptions): EmittedFile[];
+    private buildReplacements;
+    /**
+     * In-process-only event bus for SQLite.
+     *
+     * The default Express target's events.ts has a durable mode backed by a
+     * Postgres outbox with FOR UPDATE SKIP LOCKED. SQLite has no equivalent,
+     * so we ship a simpler bus that only does in-memory delivery. Callers
+     * can still use the same eventBus.publish() / .subscribe() API; only
+     * `EVENT_MODE=durable` is unsupported.
+     */
+    private emitInProcessEventBus;
     private emitTsConfig;
     private emitEnvExample;
     private emitReadme;

package/dist/emit_sqlite.js

@@ -209,11 +209,35 @@ function emitSqliteDbClient(system) {
         `  return _db;`,
         `}`,
         ``,
-        `// Translate Postgres-style $1, $2, ... placeholders to SQLite ? placeholders.`,
-        `// The generated route handlers use $N because the Postgres backend is the`,
-        `// canonical target; this keeps the surface uniform.`,
-        `function translateSql(sql: string): string {`,
-        `  return sql.replace(/\\$(\\d+)/g, "?");`,
+        `// Translate Postgres-style SQL to SQLite-compatible SQL.`,
+        `//`,
+        `// Handles:`,
+        `//   - $1, $2, ... → ? (and rebuilds params for out-of-order references)`,
+        `//   - NOW() → datetime('now')`,
+        `//   - row_to_json(t.*) → json_object(...) — best-effort, see comment below`,
+        `//`,
+        `// We can't translate every Postgres-ism. Capability effects that use`,
+        `// jsonb_set / jsonb_agg / jsonb_array_elements still fail at runtime; if`,
+        `// you hit those, refactor the capability or use the Express target.`,
+        `function translateSql(sql: string, params: any[]): { sql: string; params: any[] } {`,
+        `  let out = sql.replace(/\\bNOW\\s*\\(\\s*\\)/gi, "datetime('now')");`,
+        ``,
+        `  // row_to_json(t.*) → json_object('col', t.col, ...) is hard to do without`,
+        `  // knowing the columns. As a degraded fallback, replace it with the table`,
+        `  // alias so the LIST join still returns *something* (the joined table's id).`,
+        `  // The "as <name>" still works; consumers will see a string instead of an`,
+        `  // object. This is a known limitation.`,
+        `  out = out.replace(/row_to_json\\((\\w+)\\.\\*\\)/gi, "$1.id");`,
+        ``,
+        `  // Postgres-style placeholders → SQLite ?, with param rewrite for`,
+        `  // out-of-order references (e.g. "WHERE id = $1 AND ... = $2" vs`,
+        `  // "SET col = $2 WHERE id = $1").`,
+        `  const newParams: any[] = [];`,
+        `  out = out.replace(/\\$(\\d+)/g, (_m, n) => {`,
+        `    newParams.push(params[parseInt(n, 10) - 1]);`,
+        `    return "?";`,
+        `  });`,
+        `  return { sql: out, params: newParams };`,
         `}`,
         ``,
         `// Strip Postgres-only RETURNING * — better-sqlite3 returns the inserted/updated`,
@@ -233,29 +257,48 @@ function emitSqliteDbClient(system) {
         `  return null;`,
         `}`,
         ``,
+        // Parse the WHERE clause to find the param index that holds the id. The
+        // generated SQL uses two shapes:
+        //   - emit_runtime PUT:    "UPDATE t SET ... WHERE id = $1"     → idIdx = 1
+        //   - emit_capability:     "UPDATE t SET col = $1 WHERE id = $2" → idIdx = 2
+        // For INSERT the row id is always $1 by convention.
+        `function findIdParamIndex(sql: string, params: any[]): any {`,
+        `  // Look for "WHERE id = $N" or "WHERE id = ?" (after translation).`,
+        `  const m = sql.match(/WHERE\\s+id\\s*=\\s*\\$(\\d+)/i);`,
+        `  if (m) {`,
+        `    const idx = parseInt(m[1], 10) - 1;`,
+        `    return params[idx];`,
+        `  }`,
+        `  // Translated form: count which "?" corresponds to the WHERE id.`,
+        `  const beforeWhere = sql.split(/WHERE\\s+id\\s*=\\s*\\?/i)[0] || "";`,
+        `  const placeholdersBeforeId = (beforeWhere.match(/\\?/g) || []).length;`,
+        `  return params[placeholdersBeforeId];`,
+        `}`,
+        ``,
         `export async function query<T = any>(text: string, params: any[] = []): Promise<T[]> {`,
         `  const db = getDb();`,
         `  const { sql: stripped, hadReturning } = stripReturning(text);`,
-        `  const sql = translateSql(stripped);`,
+        `  const { sql, params: translatedParams } = translateSql(stripped, params);`,
         `  const trimmed = sql.trim().toUpperCase();`,
         `  if (trimmed.startsWith("SELECT") || trimmed.startsWith("WITH")) {`,
-        `    return db.prepare(sql).all(...params) as T[];`,
+        `    return db.prepare(sql).all(...translatedParams) as T[];`,
         `  }`,
         `  // INSERT / UPDATE / DELETE`,
         `  const stmt = db.prepare(sql);`,
-        `  const info = stmt.run(...params);`,
+        `  const info = stmt.run(...translatedParams);`,
         `  if (hadReturning) {`,
         `    const table = extractTable(sql);`,
         `    if (!table) return [];`,
         `    if (trimmed.startsWith("INSERT")) {`,
-        `      // Look up by id (which is in params[0] for our generated INSERT shape)`,
+        `      // Generated INSERTs have id as the first column → params[0].`,
         `      const id = params[0];`,
         `      const row = db.prepare(\`SELECT * FROM \${table} WHERE id = ?\`).get(id);`,
         `      return row ? [row as T] : [];`,
         `    }`,
         `    if (trimmed.startsWith("UPDATE")) {`,
-        `      // The id parameter for our generated UPDATE shape is params[0] (WHERE id = $1).`,
-        `      const id = params[0];`,
+        `      // Find the id from the WHERE clause regardless of param order.`,
+        `      const id = findIdParamIndex(stripped, params);`,
+        `      if (id === undefined) return [];`,
         `      const row = db.prepare(\`SELECT * FROM \${table} WHERE id = ?\`).get(id);`,
         `      return row ? [row as T] : [];`,
         `    }`,
@@ -272,17 +315,43 @@ function emitSqliteDbClient(system) {
         `export async function execute(text: string, params: any[] = []): Promise<number> {`,
         `  const db = getDb();`,
         `  const { sql: stripped } = stripReturning(text);`,
-        `  const sql = translateSql(stripped);`,
-        `  const info = db.prepare(sql).run(...params);`,
+        `  const { sql, params: translatedParams } = translateSql(stripped, params);`,
+        `  const info = db.prepare(sql).run(...translatedParams);`,
         `  return info.changes;`,
         `}`,
         ``,
-        `export async function transaction<T>(fn: (client: any) => Promise<T>): Promise<T> {`,
+        `// Run a function inside a SQLite transaction.`,
+        `//`,
+        `// IMPORTANT: better-sqlite3 transactions are synchronous. The callback runs`,
+        `// to completion before COMMIT — but if you do "await" inside it for a Promise`,
+        `// other than another query()/execute(), the transaction will commit before`,
+        `// the awaited work finishes.`,
+        `//`,
+        `// In practice this is fine: query()/execute() above are async only at the`,
+        `// type level; their bodies are synchronous because better-sqlite3 is.`,
+        `// The transaction will be safely committed once the callback returns, and`,
+        `// any chained query/execute calls inside it run on the same database in the`,
+        `// same transaction.`,
+        `//`,
+        `// Don't put fetch(), setTimeout, or other genuinely-async work inside fn.`,
+        `export async function transaction<T>(fn: (client: { query: typeof query; execute: typeof execute }) => Promise<T> | T): Promise<T> {`,
         `  const db = getDb();`,
-        `  // better-sqlite3 transactions are synchronous; we adapt with deasync-style`,
-        `  // immediate execution. The fn here uses query/execute which read the same db.`,
-        `  const txn = db.transaction(async () => await fn({ query: query, execute: execute }));`,
-        `  return await txn();`,
+        `  let result!: T;`,
+        `  let promise: Promise<T> | null = null;`,
+        `  const txn = db.transaction(() => {`,
+        `    const r = fn({ query, execute });`,
+        `    if (r instanceof Promise) {`,
+        `      // Capture the promise; await outside the synchronous transaction.`,
+        `      // Note: this means async work inside fn runs OUTSIDE the transaction,`,
+        `      // which may be a bug in caller code. Better to keep fn synchronous.`,
+        `      promise = r;`,
+        `      return;`,
+        `    }`,
+        `    result = r as T;`,
+        `  });`,
+        `  txn();`,
+        `  if (promise) return await promise;`,
+        `  return result;`,
         `}`,
         ``,
         `// Compatibility shim: the Postgres path uses pool.connect()/release() for nested`,
@@ -317,6 +386,7 @@ function emitSqliteDbClient(system) {
 exports.emitSqliteDbClient = emitSqliteDbClient;
 // ─── Migration runner (SQLite flavor) ─────────────────────────────────────────
 function emitSqliteMigration(_system, schemas) {
+    const system = _system; // alias for use below — kept underscore for backwards compat
     // Build deterministic blocks just like the Postgres path does.
     const lines = [];
     lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
@@ -354,7 +424,7 @@ function emitSqliteMigration(_system, schemas) {
     lines.push(`}`);
     lines.push(``);
     lines.push(`async function migrate() {`);
-    lines.push(`  const dbPath = process.env.SQLITE_PATH || path.resolve(process.cwd(), "app.db");`);
+    lines.push(`  const dbPath = process.env.SQLITE_PATH || path.resolve(process.cwd(), "${toSnakeCase(_system.name)}.db");`);
     lines.push(`  const db = new Database(dbPath);`);
     lines.push(`  db.pragma("foreign_keys = ON");`);
     lines.push(``);
@@ -400,6 +470,7 @@ function emitSqliteMigration(_system, schemas) {
 exports.emitSqliteMigration = emitSqliteMigration;
 // ─── Package.json (SQLite flavor) ─────────────────────────────────────────────
 function emitSqlitePackageJson(system) {
+    // Full backend deps, but with better-sqlite3 instead of pg.
     const pkg = {
         name: toSnakeCase(system.name),
         version: system.version,
@@ -409,10 +480,13 @@ function emitSqlitePackageJson(system) {
             start: "node dist/index.js",
             dev: "ts-node src/index.ts",
             migrate: "ts-node src/migrate.ts",
+            seed: "ts-node src/seed.ts",
         },
         dependencies: {
+            // Pinned versions match the Express target except pg → better-sqlite3.
             express: "4.22.2",
             "better-sqlite3": "11.5.0",
+            ws: "8.18.0",
             uuid: "10.0.0",
             cors: "2.8.5",
             helmet: "8.0.0",
@@ -426,6 +500,7 @@ function emitSqlitePackageJson(system) {
             "@types/express": "4.17.21",
             "@types/node": "20.14.0",
             "@types/better-sqlite3": "7.6.11",
+            "@types/ws": "8.5.13",
             "@types/cors": "2.8.17",
             "@types/jsonwebtoken": "9.0.7",
             "@types/uuid": "10.0.0",
@@ -438,15 +513,70 @@ function emitSqlitePackageJson(system) {
 }
 exports.emitSqlitePackageJson = emitSqlitePackageJson;
 // ─── Top-level emitter ────────────────────────────────────────────────────────
+const emit_full_1 = require("./emit_full");
 class SqliteEmitter {
-    emit(system) {
-        const files = [];
-        // 1. Package + tsconfig
-        files.push({ path: "package.json", content: emitSqlitePackageJson(system), language: "json", source_module: "root" });
-        files.push({ path: "tsconfig.json", content: this.emitTsConfig(), language: "json", source_module: "root" });
-        files.push({ path: ".env.example", content: this.emitEnvExample(system), language: "yaml", source_module: "root" });
-        // 2. Schema files + collect for migration runner
-        const schemas = [];
+    /**
+     * Emit a complete SQLite-backed Express project.
+     *
+     * Strategy: delegate the bulk of generation to FullEmitter (routes, auth,
+     * websocket, etc), then swap out the Postgres-specific pieces for SQLite
+     * equivalents. The generated routes use a Postgres-shaped SQL surface that
+     * our SQLite db.ts client translates at runtime (NOW() → datetime('now'),
+     * $N → ?, RETURNING * → re-select by id).
+     *
+     * What's swapped:
+     *   - package.json       SQLite deps (better-sqlite3) instead of pg
+     *   - .env.example       SQLite-shaped env vars
+     *   - src/db.ts          better-sqlite3 client with SQL translation
+     *   - src/migrate.ts     SQLite migration runner
+     *   - migrations/*.sql   SQLite-flavored DDL (TEXT, no JSONB, etc.)
+     *   - README.md          SQLite-aware quick start
+     *
+     * What's removed:
+     *   - docker-compose.yaml, Dockerfile, k8s/deployment.yaml — SQLite is
+     *     single-file; no service orchestration needed
+     *
+     * Known limitations:
+     *   - Capability bodies that use jsonb_set / jsonb_agg / jsonb_array_elements
+     *     fail at runtime. Refactor those capabilities or use the Express target.
+     *   - Durable event delivery (EVENT_MODE=durable) requires Postgres-only
+     *     features (FOR UPDATE SKIP LOCKED). Default is in_process which works
+     *     fine on SQLite.
+     *   - row_to_json(t.*) in LIST joins degrades to t.id (no full join object).
+     */
+    emit(system, options = {}) {
+        // 1. Generate the full Express project
+        const fullFiles = new emit_full_1.FullEmitter().emit(system, options);
+        // 2. Files we replace with SQLite equivalents (keyed by path)
+        const replacements = this.buildReplacements(system);
+        // 3. Files we drop entirely (Postgres-specific infra)
+        const drops = new Set([
+            "docker-compose.yaml",
+            "Dockerfile",
+            ".dockerignore",
+            "k8s/deployment.yaml",
+            "src/migration_diff.ts", // Postgres-specific schema diff
+        ]);
+        const out = [];
+        for (const f of fullFiles) {
+            if (drops.has(f.path))
+                continue;
+            // Migrations need wholesale replacement: regenerate per-entity SQLite SQL.
+            if (f.path.startsWith("migrations/") && f.path.endsWith(".sql") &&
+                f.path !== "migrations/event_outbox.sql" &&
+                f.path !== "migrations/audit_log.sql") {
+                // We re-emit these from scratch below.
+                continue;
+            }
+            const replacement = replacements.get(f.path);
+            if (replacement) {
+                out.push(replacement);
+                replacements.delete(f.path);
+                continue;
+            }
+            out.push(f);
+        }
+        // 4. Append per-entity SQLite migrations
         const seenPaths = new Set();
         for (const mod of system.modules) {
             if (mod.kind === "data_store" || mod.kind === "api_service") {
@@ -455,23 +585,157 @@ class SqliteEmitter {
                     if (seenPaths.has(file.path))
                         continue;
                     seenPaths.add(file.path);
-                    files.push(file);
-                    schemas.push(file.content);
+                    out.push(file);
                 }
             }
         }
-        // 3. Outbox + audit infra schemas
-        files.push({ path: "migrations/event_outbox.sql", content: emitSqliteOutboxSchema(), language: "sql", source_module: "infra" });
-        files.push({ path: "migrations/audit_log.sql", content: emitSqliteAuditSchema(), language: "sql", source_module: "infra" });
-        schemas.push(emitSqliteOutboxSchema());
-        schemas.push(emitSqliteAuditSchema());
-        // 4. DB client
-        files.push({ path: "src/db.ts", content: emitSqliteDbClient(system), language: "typescript", source_module: "infra" });
-        // 5. Migration runner
-        files.push({ path: "src/migrate.ts", content: emitSqliteMigration(system, schemas), language: "typescript", source_module: "infra" });
-        // 6. README
-        files.push({ path: "README.md", content: this.emitReadme(system), language: "yaml", source_module: "root" });
-        return files;
+        // 5. Add the SQLite migration runner (rebuilt with all schemas in scope)
+        const allSchemas = out
+            .filter(f => f.path.startsWith("migrations/") && f.path.endsWith(".sql"))
+            .map(f => f.content);
+        out.push({
+            path: "src/migrate.ts",
+            content: emitSqliteMigration(system, allSchemas),
+            language: "typescript",
+            source_module: "infra",
+        });
+        // 6. Add any replacements that weren't already handled (i.e. files unique to SQLite)
+        for (const r of replacements.values()) {
+            out.push(r);
+        }
+        return out;
+    }
+    buildReplacements(system) {
+        const map = new Map();
+        map.set("package.json", {
+            path: "package.json",
+            content: emitSqlitePackageJson(system),
+            language: "json",
+            source_module: "root",
+        });
+        map.set(".env.example", {
+            path: ".env.example",
+            content: this.emitEnvExample(system),
+            language: "yaml",
+            source_module: "root",
+        });
+        map.set("src/db.ts", {
+            path: "src/db.ts",
+            content: emitSqliteDbClient(system),
+            language: "typescript",
+            source_module: "infra",
+        });
+        map.set("src/events.ts", {
+            path: "src/events.ts",
+            content: this.emitInProcessEventBus(system),
+            language: "typescript",
+            source_module: "infra",
+        });
+        map.set("migrations/event_outbox.sql", {
+            path: "migrations/event_outbox.sql",
+            content: emitSqliteOutboxSchema(),
+            language: "sql",
+            source_module: "infra",
+        });
+        map.set("migrations/audit_log.sql", {
+            path: "migrations/audit_log.sql",
+            content: emitSqliteAuditSchema(),
+            language: "sql",
+            source_module: "infra",
+        });
+        map.set("README.md", {
+            path: "README.md",
+            content: this.emitReadme(system),
+            language: "yaml",
+            source_module: "root",
+        });
+        return map;
+    }
+    /**
+     * In-process-only event bus for SQLite.
+     *
+     * The default Express target's events.ts has a durable mode backed by a
+     * Postgres outbox with FOR UPDATE SKIP LOCKED. SQLite has no equivalent,
+     * so we ship a simpler bus that only does in-memory delivery. Callers
+     * can still use the same eventBus.publish() / .subscribe() API; only
+     * `EVENT_MODE=durable` is unsupported.
+     */
+    emitInProcessEventBus(system) {
+        const lines = [];
+        lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
+        lines.push(`// In-process event bus (SQLite target — durable mode is Postgres-only).`);
+        lines.push(``);
+        lines.push(`import { v4 as uuid } from "uuid";`);
+        lines.push(`import { logger } from "./logger";`);
+        lines.push(`import { counter } from "./metrics";`);
+        lines.push(``);
+        lines.push(`export interface EventMetadata {`);
+        lines.push(`  source: string;`);
+        lines.push(`  timestamp: Date;`);
+        lines.push(`  correlation_id: string;`);
+        lines.push(`  causation_id: string;`);
+        lines.push(`}`);
+        lines.push(``);
+        lines.push(`export interface SystemEvent {`);
+        lines.push(`  type: string;`);
+        lines.push(`  payload: Record<string, unknown>;`);
+        lines.push(`  metadata: EventMetadata;`);
+        lines.push(`}`);
+        lines.push(``);
+        lines.push(`type Handler = (event: SystemEvent) => Promise<void>;`);
+        lines.push(``);
+        lines.push(`class InProcessBus {`);
+        lines.push(`  private handlers: Map<string, Handler[]> = new Map();`);
+        lines.push(``);
+        lines.push(`  subscribe(type: string, handler: Handler): void {`);
+        lines.push(`    const existing = this.handlers.get(type) || [];`);
+        lines.push(`    existing.push(handler);`);
+        lines.push(`    this.handlers.set(type, existing);`);
+        lines.push(`  }`);
+        lines.push(``);
+        lines.push(`  async publish(`);
+        lines.push(`    type: string,`);
+        lines.push(`    payload: Record<string, unknown>,`);
+        lines.push(`    source: string,`);
+        lines.push(`    correlationId?: string,`);
+        lines.push(`    _client?: unknown,`);
+        lines.push(`  ): Promise<void> {`);
+        lines.push(`    const event: SystemEvent = {`);
+        lines.push(`      type,`);
+        lines.push(`      payload,`);
+        lines.push(`      metadata: {`);
+        lines.push(`        source,`);
+        lines.push(`        timestamp: new Date(),`);
+        lines.push(`        correlation_id: correlationId || uuid(),`);
+        lines.push(`        causation_id: uuid(),`);
+        lines.push(`      },`);
+        lines.push(`    };`);
+        lines.push(`    counter("event.published", { type, mode: "in_process" });`);
+        lines.push(`    const handlers = this.handlers.get(type) || [];`);
+        lines.push(`    for (const handler of handlers) {`);
+        lines.push(`      try {`);
+        lines.push(`        await handler(event);`);
+        lines.push(`        counter("event.delivered", { type, mode: "in_process" });`);
+        lines.push(`      } catch (e: any) {`);
+        lines.push(`        counter("event.delivery_failed", { type, mode: "in_process" });`);
+        lines.push(`        logger.error("event_handler_failed", { event: type, metadata: { error: e.message } });`);
+        lines.push(`      }`);
+        lines.push(`    }`);
+        lines.push(`  }`);
+        lines.push(``);
+        lines.push(`  startWorker(_intervalMs?: number): null {`);
+        lines.push(`    // No-op for in-process mode.`);
+        lines.push(`    return null;`);
+        lines.push(`  }`);
+        lines.push(`}`);
+        lines.push(``);
+        lines.push(`if (process.env.EVENT_MODE === "durable") {`);
+        lines.push(`  console.warn("[events] EVENT_MODE=durable is not supported on the SQLite target. Falling back to in_process.");`);
+        lines.push(`}`);
+        lines.push(``);
+        lines.push(`export const eventBus = new InProcessBus();`);
+        lines.push(``);
+        return lines.join("\n");
     }
     emitTsConfig() {
         const cfg = {
@@ -495,15 +759,41 @@ class SqliteEmitter {
     }
     emitEnvExample(system) {
         return `# ${system.name} (SQLite target)
+# Copy to .env and customize.
 
+# --- Database ---
 # Path to the SQLite database file. Defaults to ./<system_name>.db
 SQLITE_PATH=./${toSnakeCase(system.name)}.db
 
+# --- Required in production ---
+# Generate with: node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
+JWT_SECRET=
+
+# --- Server ---
 PORT=3000
 NODE_ENV=development
 
-JWT_SECRET=
+# --- CORS ---
+# Comma-separated list of allowed origins. Leave empty to disallow cross-origin requests.
+ALLOWED_ORIGINS=
+
+# --- Event delivery ---
+# in_process: in-memory bus, no durability — recommended for SQLite.
+# durable mode (Postgres outbox + FOR UPDATE SKIP LOCKED) is not supported.
 EVENT_MODE=in_process
+
+# --- Request timeout ---
+REQUEST_TIMEOUT_MS=30000
+
+# --- Notifications ---
+# NOTIFY_PROVIDER=log|resend|sendgrid|webhook (default: log)
+NOTIFY_PROVIDER=log
+NOTIFY_API_KEY=
+NOTIFY_FROM_EMAIL=noreply@example.com
+
+# --- Webhook delivery ---
+NOTIFY_WEBHOOK_URL=
+NOTIFY_WEBHOOK_SECRET=
 `;
     }
     emitReadme(system) {
@@ -519,19 +809,53 @@ npm run migrate
 npm run dev
 \`\`\`
 
-The database file will be created at \`./${toSnakeCase(system.name)}.db\` by default.
-Override with the \`SQLITE_PATH\` environment variable.
+The database file will be created at \`./${toSnakeCase(system.name)}.db\` by
+default. Override with the \`SQLITE_PATH\` environment variable.
+
+The server starts at http://localhost:3000 with all routes wired:
+
+- CRUD endpoints for every entity
+- Capability endpoints (\`POST /<entity>s/<capability-name>\`)
+- Health checks at \`/health/live\`, \`/health/ready\`, \`/health/metrics\`
+- Admin panel at \`/admin\`
 
 ## Why SQLite
 
-This target produces a self-contained backend with no external services:
-- No Postgres / Redis to start
-- No Docker
-- The whole database is one file you can copy, version, or back up easily
+Self-contained, single-file database. No external services to start, no
+Docker, no Postgres. The whole database is one file you can copy, version,
+or back up.
+
+Ideal for: local development, demos, integration tests, single-node
+deployments. For production multi-writer workloads, use the default Express
+target (Postgres-backed).
+
+## Auth
+
+Send a Bearer token in the Authorization header:
+
+\`\`\`
+Authorization: Bearer <jwt-token>
+\`\`\`
+
+Generate a token by signing with the same \`JWT_SECRET\` from your \`.env\`.
+
+## Differences from the Postgres target
+
+- Schema uses \`TEXT\`/\`INTEGER\` instead of \`VARCHAR\`/\`BIGINT\`/\`JSONB\`
+- The DB client (\`src/db.ts\`) translates Postgres-flavored SQL at runtime:
+  - \`$N\` placeholders → \`?\` (with param array reordering)
+  - \`NOW()\` → \`datetime('now')\`
+  - \`RETURNING *\` → re-select by id
+  - \`row_to_json(t.*)\` in LIST joins degrades to \`t.id\` only
+- Durable event mode (\`EVENT_MODE=durable\`) is not supported on SQLite —
+  it requires Postgres-only \`FOR UPDATE SKIP LOCKED\`. Use \`in_process\`.
+- Capability bodies that reference \`jsonb_set\`, \`jsonb_agg\`, or
+  \`jsonb_array_elements\` will fail at runtime. Refactor those capabilities
+  or compile to the Express target.
+
+## Environment
 
-It's ideal for local development, demos, integration tests, and small
-single-node deployments. For production multi-writer workloads, use the
-default Express target which generates a Postgres-backed project.
+Copy \`.env.example\` to \`.env\` and configure.
 `;
     }
 }