bonescript-compiler 0.8.0 → 0.9.0

package/src/emit_sqlite.ts

@@ -219,11 +219,35 @@ export function emitSqliteDbClient(system: IR.IRSystem): string {
     `  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`,
@@ -243,29 +267,48 @@ export function emitSqliteDbClient(system: IR.IRSystem): string {
     `  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] : [];`,
     `    }`,
@@ -282,17 +325,43 @@ export function emitSqliteDbClient(system: IR.IRSystem): string {
     `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`,
@@ -328,6 +397,7 @@ export function emitSqliteDbClient(system: IR.IRSystem): string {
 // ─── Migration runner (SQLite flavor) ─────────────────────────────────────────
 
 export function emitSqliteMigration(_system: IR.IRSystem, schemas: string[]): string {
+  const system = _system; // alias for use below — kept underscore for backwards compat
   // Build deterministic blocks just like the Postgres path does.
   const lines: string[] = [];
   lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
@@ -367,7 +437,7 @@ export function emitSqliteMigration(_system: IR.IRSystem, schemas: string[]): st
   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(``);
@@ -415,6 +485,7 @@ export function emitSqliteMigration(_system: IR.IRSystem, schemas: string[]): st
 // ─── Package.json (SQLite flavor) ─────────────────────────────────────────────
 
 export function emitSqlitePackageJson(system: IR.IRSystem): string {
+  // Full backend deps, but with better-sqlite3 instead of pg.
   const pkg = {
     name: toSnakeCase(system.name),
     version: system.version,
@@ -424,10 +495,13 @@ export function emitSqlitePackageJson(system: IR.IRSystem): string {
       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",
@@ -441,6 +515,7 @@ export function emitSqlitePackageJson(system: IR.IRSystem): string {
       "@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",
@@ -454,17 +529,76 @@ export function emitSqlitePackageJson(system: IR.IRSystem): string {
 
 // ─── Top-level emitter ────────────────────────────────────────────────────────
 
+import { FullEmitter, FullEmitterOptions } from "./emit_full";
+
 export class SqliteEmitter {
-  emit(system: IR.IRSystem): EmittedFile[] {
-    const files: 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[] {
+    // 1. Generate the full Express project
+    const fullFiles = new 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<string>([
+      "docker-compose.yaml",
+      "Dockerfile",
+      ".dockerignore",
+      "k8s/deployment.yaml",
+      "src/migration_diff.ts", // Postgres-specific schema diff
+    ]);
+
+    const out: EmittedFile[] = [];
+    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;
+      }
 
-    // 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" });
+      const replacement = replacements.get(f.path);
+      if (replacement) {
+        out.push(replacement);
+        replacements.delete(f.path);
+        continue;
+      }
+      out.push(f);
+    }
 
-    // 2. Schema files + collect for migration runner
-    const schemas: string[] = [];
+    // 4. Append per-entity SQLite migrations
     const seenPaths = new Set<string>();
     for (const mod of system.modules) {
       if (mod.kind === "data_store" || mod.kind === "api_service") {
@@ -472,28 +606,170 @@ export class SqliteEmitter {
           const file = emitSqliteSchema(model, mod, system);
           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. Add the SQLite migration runner (rebuilt with all schemas in scope)
+    const allSchemas: string[] = 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);
+    }
 
-    // 5. Migration runner
-    files.push({ path: "src/migrate.ts", content: emitSqliteMigration(system, schemas), language: "typescript", source_module: "infra" });
+    return out;
+  }
 
-    // 6. README
-    files.push({ path: "README.md", content: this.emitReadme(system), language: "yaml", source_module: "root" });
+  private buildReplacements(system: IR.IRSystem): Map<string, EmittedFile> {
+    const map = new Map<string, EmittedFile>();
+
+    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;
+  }
 
-    return files;
+  /**
+   * 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(system: IR.IRSystem): string {
+    const lines: string[] = [];
+    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");
   }
 
   private emitTsConfig(): string {
@@ -519,15 +795,41 @@ export class SqliteEmitter {
 
   private emitEnvExample(system: IR.IRSystem): string {
     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=
 `;
   }
 
@@ -544,19 +846,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.
 `;
   }
 }

package/src/lowering.ts

@@ -246,6 +246,32 @@ export class Lowering {
       fields.push(this.lowerField(f));
     }
 
+    // Auto-add foreign key columns for `belongs_to` relations.
+    //
+    // Without this, generated migrations reference a column that doesn't exist
+    // (e.g. `FOREIGN KEY (seller_id) REFERENCES sellers(id)` when no seller_id
+    // is declared in `owns:`). Users were having to duplicate the FK in
+    // `owns:` to make it work; we now synthesize it.
+    //
+    // If the user already declared a column with the same name (the legacy
+    // pattern), we don't add a duplicate — their declaration wins so they
+    // can override nullability or add @sensitive.
+    const existingFieldNames = new Set(fields.map(f => f.name));
+    for (const rel of entity.relations) {
+      if (rel.relationType !== "belongs_to") continue;
+      const fkName = toSnakeCase(rel.target) + "_id";
+      if (existingFieldNames.has(fkName)) continue;
+      fields.push({
+        name: fkName,
+        type: "uuid",
+        nullable: false,
+        unique: false,
+        indexed: true,
+        default_value: null,
+      });
+      existingFieldNames.add(fkName);
+    }
+
     // Add derived fields as generated columns (stored: false = virtual)
     const derivedFields: IR.IRField[] = entity.derived.map(d => ({
       name: d.name,

package/dist/test_notify.d.ts

@@ -1,11 +0,0 @@
-/**
- * Notification service tests.
- *
- * Generates the notify.ts file from a sample IR and verifies:
- *   - webhook is in the provider union
- *   - HMAC signing helper is emitted
- *   - URL validation rejects non-http(s) protocols
- *   - sendWebhook signs requests when NOTIFY_WEBHOOK_SECRET is set
- *   - sendWebhook posts to NOTIFY_WEBHOOK_URL with the right shape
- */
-export {};