@sapporta/server 0.0.1

package/src/reports/sqlite-sql-client.ts

@@ -0,0 +1,42 @@
+// ============================================================================
+// SQLite Report SQL Client — synchronous query adapter for the report engine
+// ============================================================================
+//
+// The existing ReportSqlClient interface (engine.ts) is async:
+//   { unsafe: (sql, params?) => Promise<any[]> }
+//
+// better-sqlite3 is synchronous. This module wraps a better-sqlite3 Database
+// to match the ReportSqlClient interface by wrapping synchronous results in
+// Promise.resolve(). This allows the report engine to work unchanged until
+// PLAN-2 migrates it to a synchronous execution model.
+//
+// In PLAN-2, the engine will likely switch to a sync interface. At that
+// point this wrapper becomes unnecessary. For now, it bridges the gap.
+
+import type Database from "better-sqlite3";
+import type { ReportSqlClient } from "./engine.js";
+
+/**
+ * Create a ReportSqlClient adapter from a better-sqlite3 Database.
+ *
+ * Maps the async ReportSqlClient.unsafe() interface to better-sqlite3's
+ * synchronous prepare().all() — the result is wrapped in Promise.resolve()
+ * for interface compatibility.
+ *
+ * The params array is spread into .all() which uses SQLite's ? positional
+ * parameter binding (not Postgres's $1 positional binding). The caller
+ * must use buildSQLitePositionalQuery() from sqlite-bind.ts to convert
+ * $name variables to ? placeholders before calling this client.
+ */
+export function createReportSqlClient(
+  sqlite: Database.Database,
+): ReportSqlClient {
+  return {
+    unsafe: (sql: string, params?: any[]): Promise<any[]> => {
+      const result = sqlite
+        .prepare(sql)
+        .all(...(params ?? [])) as Record<string, unknown>[];
+      return Promise.resolve(result);
+    },
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,3 @@
+// Backward-compatibility re-exports. The canonical home is boot.ts.
+export type { ProjectConfig, InProcessProject } from "./boot.js";
+export { bootProject } from "./boot.js";

package/src/schema/check.ts

@@ -0,0 +1,90 @@
+import { getTableConfig } from "drizzle-orm/sqlite-core";
+import { isDateObjectMode } from "./normalize-datatype.js";
+import type { TableDef } from "./table.js";
+
+export type SchemaIssue = {
+  table: string;
+  column: string;
+  message: string;
+};
+
+/**
+ * Check schema definitions for nullable numeric columns that should be NOT NULL.
+ *
+ * Three categories of nullable numeric columns:
+ *
+ * 1. **FK columns** (e.g. `parent_id`) — nullable because the relationship is
+ *    optional. Never aggregated. Auto-detected from Drizzle foreign key metadata.
+ *
+ * 2. **Additive measures** (e.g. `debit`, `credit`) — values where NULL breaks
+ *    SUM/AVG. Must be NOT NULL with .default("0").
+ *
+ * 3. **Non-additive optionals** (e.g. `account_balance_assertion`) — NULL means
+ *    "no value" and 0 means "value is zero". Legitimately nullable. Marked with
+ *    `additive: false` in column meta.
+ *
+ * This checker flags category 2 — nullable numerics that are not FK columns and
+ * not explicitly marked as non-additive.
+ */
+export function checkSchemaDefinitions(tables: TableDef[]): SchemaIssue[] {
+  const issues: SchemaIssue[] = [];
+
+  for (const table of tables) {
+    const config = getTableConfig(table.drizzle);
+
+    // Build FK column set from Drizzle foreign key metadata
+    const fkColumns = new Set<string>();
+    for (const fk of config.foreignKeys) {
+      const ref = fk.reference();
+      const sourceCol = ref.columns[0];
+      if (sourceCol) {
+        fkColumns.add(sourceCol.name);
+      }
+    }
+
+    for (const col of config.columns) {
+      // Skip primary keys — never aggregated
+      if (col.primary) continue;
+
+      // Skip foreign key columns — nullable because the relationship is optional
+      if (fkColumns.has(col.name)) continue;
+
+      // Flag Date-object-mode timestamps (Pg default mode or SQLite mode: "timestamp").
+      // These break in a JSON-over-HTTP framework because string values hit .toISOString().
+      // See timestamp() in table.ts for the string-mode convention.
+      if (isDateObjectMode(col)) {
+        issues.push({
+          table: config.name,
+          column: col.name,
+          message:
+            `Timestamp column using Date mode. ` +
+            `Sapporta is JSON-over-HTTP — dates arrive as strings, causing "toISOString is not a function" errors. ` +
+            `Use import { timestamp } from "@sapporta/server/table" which returns a text column storing ISO 8601 strings.`,
+        });
+      }
+
+      // SQLite integer and real both have dataType "number".
+      // Currency/percentage columns stored as TEXT won't match "number",
+      // which is correct — they shouldn't warn about nullable numerics
+      // since they're text.
+      const isNumeric = col.dataType === "number";
+
+      if (!isNumeric || col.notNull) continue;
+
+      // Skip columns explicitly marked as non-additive
+      if (table.meta.columns?.[col.name]?.additive === false) continue;
+
+      issues.push({
+        table: config.name,
+        column: col.name,
+        message:
+          `Nullable numeric column. ` +
+          `A single NULL causes SUM/AVG to silently produce NULL instead of a number. ` +
+          `Add .notNull() (with .default("0") if the column is optional). ` +
+          `If NULL is semantically distinct from 0, mark it with { additive: false } in column meta.`,
+      });
+    }
+  }
+
+  return issues;
+}

package/src/schema/ddl.test.ts

@@ -0,0 +1,210 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import {
+  generateCreateTableDDL,
+  generateAddColumnDDL,
+  generateCheckConstraintDDL,
+} from "./ddl.js";
+import type { ColumnMetaRow } from "./dynamic-builder.js";
+
+describe("generateCreateTableDDL", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("produces valid SQLite DDL", () => {
+    const ddl = generateCreateTableDDL("contacts");
+    // Should not throw when executed
+    sqlite.exec(ddl);
+
+    const cols = sqlite.pragma('table_info("contacts")') as {
+      name: string;
+      type: string;
+    }[];
+    const colNames = cols.map((c) => c.name);
+    expect(colNames).toContain("id");
+    expect(colNames).toContain("created_at");
+    expect(colNames).toContain("updated_at");
+  });
+
+  it("uses AUTOINCREMENT for id", () => {
+    const ddl = generateCreateTableDDL("test");
+    expect(ddl).toContain("AUTOINCREMENT");
+  });
+
+  it("uses datetime('now') for timestamps", () => {
+    const ddl = generateCreateTableDDL("test");
+    expect(ddl).toContain("datetime('now')");
+    expect(ddl).not.toContain("now()"); // Postgres-style
+  });
+});
+
+// generateAddColumnDDL returns string[] — the first element is the ALTER TABLE
+// statement, and an optional second element is a CREATE UNIQUE INDEX statement.
+// Helper to execute all returned statements against a SQLite handle.
+function execAll(sqlite: Database.Database, stmts: string[]) {
+  for (const s of stmts) sqlite.exec(s);
+}
+
+describe("generateAddColumnDDL", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+    sqlite.exec(generateCreateTableDDL("test"));
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  function makeCol(overrides: Partial<ColumnMetaRow>): ColumnMetaRow {
+    return {
+      column_name: "col",
+      column_type: "text",
+      position: 0,
+      not_null: false,
+      is_unique: false,
+      ...overrides,
+    };
+  }
+
+  it("returns a single-element array for non-unique columns", () => {
+    const stmts = generateAddColumnDDL("test", makeCol({ column_name: "name", column_type: "text" }));
+    expect(stmts).toHaveLength(1);
+    execAll(sqlite, stmts);
+    const cols = sqlite.pragma('table_info("test")') as { name: string }[];
+    expect(cols.map((c) => c.name)).toContain("name");
+  });
+
+  it("generates valid ALTER TABLE for integer column", () => {
+    const stmts = generateAddColumnDDL("test", makeCol({ column_name: "count", column_type: "integer" }));
+    execAll(sqlite, stmts);
+    const cols = sqlite.pragma('table_info("test")') as { name: string; type: string }[];
+    const col = cols.find((c) => c.name === "count")!;
+    expect(col.type).toBe("INTEGER");
+  });
+
+  it("adds NOT NULL constraint", () => {
+    const stmts = generateAddColumnDDL(
+      "test",
+      makeCol({ column_name: "required", column_type: "text", not_null: true, default_value: "" }),
+    );
+    expect(stmts[0]).toContain("NOT NULL");
+  });
+
+  it("emits UNIQUE as a separate CREATE UNIQUE INDEX (works on non-empty tables)", () => {
+    // SQLite rejects inline UNIQUE in ALTER TABLE ADD COLUMN for non-empty
+    // tables. Sapporta uses a separate CREATE UNIQUE INDEX instead, which
+    // works regardless of existing rows.
+
+    // Insert a row so the table is non-empty — this would fail with inline UNIQUE
+    sqlite.exec(`INSERT INTO test (created_at, updated_at) VALUES ('2024-01-01', '2024-01-01')`);
+
+    const stmts = generateAddColumnDDL(
+      "test",
+      makeCol({ column_name: "email", column_type: "email", is_unique: true }),
+    );
+
+    // Should produce two statements: ALTER TABLE + CREATE UNIQUE INDEX
+    expect(stmts).toHaveLength(2);
+    expect(stmts[0]).not.toContain("UNIQUE");
+    expect(stmts[1]).toContain("CREATE UNIQUE INDEX");
+    expect(stmts[1]).toContain('"email"');
+
+    // Both statements should execute without error on a non-empty table
+    execAll(sqlite, stmts);
+
+    // Verify the unique index was actually created
+    const indexes = sqlite
+      .prepare(`SELECT name FROM sqlite_master WHERE type = 'index' AND tbl_name = 'test'`)
+      .all() as { name: string }[];
+    expect(indexes.some((i) => i.name.includes("email"))).toBe(true);
+  });
+
+  it("adds FK REFERENCES for link columns", () => {
+    sqlite.exec(`CREATE TABLE accounts (id INTEGER PRIMARY KEY AUTOINCREMENT)`);
+    const stmts = generateAddColumnDDL(
+      "test",
+      makeCol({ column_name: "account_id", column_type: "link", references_table: "accounts" }),
+    );
+    expect(stmts[0]).toContain('REFERENCES "accounts"("id")');
+    execAll(sqlite, stmts);
+  });
+
+  it("generates link column without FK when references_table is missing", () => {
+    const stmts = generateAddColumnDDL(
+      "test",
+      makeCol({ column_name: "category_id", column_type: "link" }),
+    );
+    expect(stmts[0]).toContain("INTEGER");
+    expect(stmts[0]).not.toContain("REFERENCES");
+    execAll(sqlite, stmts);
+  });
+
+  it("converts boolean defaults: true → 1, false → 0", () => {
+    const stmtsTrue = generateAddColumnDDL(
+      "test",
+      makeCol({ column_name: "active", column_type: "boolean", default_value: "true" }),
+    );
+    expect(stmtsTrue[0]).toContain("DEFAULT 1");
+
+    const stmtsFalse = generateAddColumnDDL(
+      "test",
+      makeCol({ column_name: "deleted", column_type: "boolean", default_value: "false" }),
+    );
+    expect(stmtsFalse[0]).toContain("DEFAULT 0");
+  });
+
+  it("quotes string defaults", () => {
+    const stmts = generateAddColumnDDL(
+      "test",
+      makeCol({ column_name: "status", column_type: "text", default_value: "active" }),
+    );
+    expect(stmts[0]).toContain("DEFAULT 'active'");
+  });
+
+  it("escapes single quotes in string defaults", () => {
+    const stmts = generateAddColumnDDL(
+      "test",
+      makeCol({ column_name: "note", column_type: "text", default_value: "it's fine" }),
+    );
+    expect(stmts[0]).toContain("DEFAULT 'it''s fine'");
+  });
+
+  it("maps currency to TEXT type", () => {
+    const stmts = generateAddColumnDDL(
+      "test",
+      makeCol({ column_name: "amount", column_type: "currency" }),
+    );
+    expect(stmts[0]).toContain("TEXT");
+    expect(stmts[0]).not.toContain("REAL");
+  });
+});
+
+describe("generateCheckConstraintDDL", () => {
+  it("generates valid CHECK clause", () => {
+    const check = generateCheckConstraintDDL("status", [
+      "active",
+      "inactive",
+      "archived",
+    ]);
+    expect(check).toBe(
+      `CHECK("status" IN ('active', 'inactive', 'archived'))`,
+    );
+  });
+
+  it("escapes single quotes in option values", () => {
+    const check = generateCheckConstraintDDL("type", [
+      "it's special",
+      "normal",
+    ]);
+    expect(check).toBe(`CHECK("type" IN ('it''s special', 'normal'))`);
+  });
+});

package/src/schema/ddl.ts

@@ -0,0 +1,180 @@
+// ============================================================================
+// SQLite DDL Generation — CREATE TABLE and ALTER TABLE for UI-managed tables
+// ============================================================================
+//
+// These functions generate DDL for runtime table creation and column addition.
+// Used by the mutation API when users create tables/columns via the browser UI.
+//
+// Critical type mapping decisions for SQLite:
+//
+//   currency/percentage → TEXT (not REAL)
+//     REAL is IEEE 754 double-precision — loses precision for decimal values.
+//     TEXT stores exact decimal strings like "1234.56". The application layer
+//     handles formatting. This matches Postgres's NUMERIC type semantically.
+//
+//   date/timestamp → TEXT
+//     SQLite has no native date type. TEXT stores ISO 8601 strings.
+//     Matches Sapporta's convention of mode: "string" timestamps that
+//     flow as plain strings across JSON boundaries.
+//
+//   boolean → INTEGER (0/1)
+//     SQLite convention. Matches Drizzle's integer({ mode: "boolean" }).
+//
+//   select → TEXT
+//     Validated at the application layer via select_options metadata,
+//     not via database CHECK constraints (because ALTER TABLE ADD COLUMN
+//     doesn't support inline CHECK in SQLite).
+
+import type { ColumnMetaRow } from "./dynamic-builder.js";
+
+/**
+ * SQLite type mapping for UI-managed column types.
+ *
+ * Each logical column_type maps to a specific SQLite storage type.
+ * Types like "currency" and "email" are identical to TEXT at the DB level —
+ * the distinction only matters for UI formatting and validation.
+ */
+export const SQLITE_TYPE_MAP: Record<string, string> = {
+  text: "TEXT",
+  integer: "INTEGER",
+  numeric: "REAL",
+  boolean: "INTEGER",
+  date: "TEXT",
+  timestamp: "TEXT",
+  select: "TEXT",
+  link: "INTEGER",
+  currency: "TEXT", // NOT REAL — exact decimal representation
+  percentage: "TEXT", // NOT REAL — exact decimal representation
+  email: "TEXT",
+  url: "TEXT",
+};
+
+/**
+ * Map a logical column_type to its SQLite DDL type string.
+ * Returns undefined for unknown types (caller should reject).
+ */
+export function sqliteTypeForColumnType(
+  columnType: string,
+): string | undefined {
+  return SQLITE_TYPE_MAP[columnType];
+}
+
+/**
+ * Generate CREATE TABLE DDL for a new UI-managed table.
+ *
+ * Creates the standard system columns (id, created_at, updated_at).
+ * User-defined columns are added later via ALTER TABLE ADD COLUMN.
+ *
+ * Uses INTEGER PRIMARY KEY AUTOINCREMENT for the id column. In SQLite,
+ * this guarantees monotonically increasing IDs (never reuses deleted IDs),
+ * matching Postgres SERIAL behavior.
+ */
+export function generateCreateTableDDL(tableName: string): string {
+  return `CREATE TABLE "${tableName}" (
+  "id" INTEGER PRIMARY KEY AUTOINCREMENT,
+  "created_at" TEXT NOT NULL DEFAULT (datetime('now')),
+  "updated_at" TEXT NOT NULL DEFAULT (datetime('now'))
+)`;
+}
+
+/**
+ * Generate ALTER TABLE ADD COLUMN DDL for a UI-managed table.
+ *
+ * Returns an array of DDL statements to execute in order:
+ *   [0] ALTER TABLE ADD COLUMN — always present
+ *   [1] CREATE UNIQUE INDEX   — only if is_unique is true
+ *
+ * UNIQUE is handled via a separate CREATE UNIQUE INDEX because SQLite's
+ * ALTER TABLE ADD COLUMN rejects inline UNIQUE for non-empty tables.
+ * A CREATE UNIQUE INDEX works regardless of existing rows (as long as
+ * the data satisfies the constraint).
+ *
+ * Handles type mapping, NOT NULL, DEFAULT, and REFERENCES constraints.
+ * Default values are sanitized via formatLiteralDefault() to prevent injection.
+ *
+ * Note: SQLite's ALTER TABLE ADD COLUMN does NOT support:
+ *   - CHECK constraints inline (enforced at application layer instead)
+ *   - PRIMARY KEY (only one PK allowed, set at CREATE TABLE time)
+ *   - Columns with NOT NULL and no DEFAULT when the table has existing rows
+ *     (SQLite requires a default value for NOT NULL columns added to non-empty tables)
+ */
+export function generateAddColumnDDL(
+  tableName: string,
+  col: ColumnMetaRow,
+): string[] {
+  const sqlType = SQLITE_TYPE_MAP[col.column_type] ?? "TEXT";
+  let alterDdl = `ALTER TABLE "${tableName}" ADD COLUMN "${col.column_name}" ${sqlType}`;
+
+  if (col.not_null) {
+    alterDdl += " NOT NULL";
+  }
+  if (col.default_value !== undefined && col.default_value !== null) {
+    alterDdl += ` DEFAULT ${formatLiteralDefault(col.default_value, col.column_type)}`;
+  }
+  if (col.column_type === "link" && col.references_table) {
+    alterDdl += ` REFERENCES "${col.references_table}"("id")`;
+  }
+
+  const statements = [alterDdl];
+
+  // UNIQUE via separate index — SQLite rejects inline UNIQUE in ALTER TABLE
+  // ADD COLUMN when the table has existing rows.
+  if (col.is_unique) {
+    statements.push(
+      `CREATE UNIQUE INDEX "idx_${tableName}_${col.column_name}_unique" ON "${tableName}"("${col.column_name}")`,
+    );
+  }
+
+  return statements;
+}
+
+/**
+ * Generate a CHECK constraint clause for select/enum columns.
+ *
+ * This is only usable in CREATE TABLE statements, not ALTER TABLE ADD COLUMN.
+ * For columns added via ALTER TABLE, select validation is enforced at the
+ * application layer via select_options metadata.
+ *
+ * Returns just the CHECK clause (e.g., CHECK("status" IN ('active', 'inactive'))).
+ * The caller is responsible for including it in the appropriate DDL context.
+ */
+export function generateCheckConstraintDDL(
+  columnName: string,
+  options: string[],
+): string {
+  const values = options.map((o) => `'${o.replace(/'/g, "''")}'`).join(", ");
+  return `CHECK("${columnName}" IN (${values}))`;
+}
+
+/**
+ * Format a literal default value for SQLite DDL.
+ *
+ * SECURITY: Only accepts literal values (strings, numbers, booleans).
+ * Never interpolates raw SQL expressions. Prevents SQL injection via
+ * crafted default_value payloads.
+ *
+ * SQLite-specific: boolean true/false → 1/0
+ */
+function formatLiteralDefault(
+  value: string,
+  columnType: string,
+): string {
+  // Boolean types: true → 1, false → 0
+  if (columnType === "boolean") {
+    return value.toLowerCase() === "true" ? "1" : "0";
+  }
+
+  // Numeric types: must parse as a finite number
+  if (
+    ["integer", "numeric", "currency", "percentage"].includes(columnType)
+  ) {
+    const num = Number(value);
+    if (!Number.isFinite(num)) {
+      throw new Error(`Invalid numeric default: ${value}`);
+    }
+    return String(num);
+  }
+
+  // Text-like types: quote as a string literal with single-quote escaping
+  return `'${value.replace(/'/g, "''")}'`;
+}