@sapporta/server 0.0.1

package/src/schema/registry.test.ts

@@ -0,0 +1,174 @@
+import { describe, it, expect, vi } from "vitest";
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { table } from "./table.js";
+import { SchemaRegistry } from "./registry.js";
+
+function makeTable(name: string) {
+  return table({
+    drizzle: sqliteTable(name, {
+      id: integer("id").primaryKey({ autoIncrement: true }),
+      name: text("name").notNull(),
+    }),
+  });
+}
+
+describe("SchemaRegistry", () => {
+  it("register and retrieve defs", () => {
+    const reg = new SchemaRegistry();
+    const a = makeTable("accounts");
+    const b = makeTable("invoices");
+    reg.register(a, "file");
+    reg.register(b, "file");
+
+    expect(reg.has("accounts")).toBe(true);
+    expect(reg.has("invoices")).toBe(true);
+    expect(reg.has("unknown")).toBe(false);
+    expect(reg.get("accounts")?.def).toBe(a);
+    expect(reg.get("accounts")?.source).toBe("file");
+  });
+
+  it("all() returns defs in insertion order", () => {
+    const reg = new SchemaRegistry();
+    const a = makeTable("alpha");
+    const b = makeTable("beta");
+    const c = makeTable("gamma");
+    reg.register(a, "file");
+    reg.register(b, "ui");
+    reg.register(c, "file");
+
+    const names = reg.all().map((d) => d.sqlName);
+    expect(names).toEqual(["alpha", "beta", "gamma"]);
+  });
+
+  it("unregister removes the entry", () => {
+    const reg = new SchemaRegistry();
+    reg.register(makeTable("accounts"), "file");
+    expect(reg.has("accounts")).toBe(true);
+
+    reg.unregister("accounts");
+    expect(reg.has("accounts")).toBe(false);
+    expect(reg.all()).toHaveLength(0);
+  });
+
+  it("unregister is a no-op for unknown names", () => {
+    const reg = new SchemaRegistry();
+    reg.unregister("nonexistent"); // should not throw
+    expect(reg.all()).toHaveLength(0);
+  });
+
+  it("file def shadows UI def with same name", () => {
+    const reg = new SchemaRegistry();
+    const fileDef = makeTable("accounts");
+    const uiDef = makeTable("accounts");
+
+    reg.register(fileDef, "file");
+    reg.register(uiDef, "ui");
+
+    // File def wins
+    expect(reg.get("accounts")?.def).toBe(fileDef);
+    expect(reg.get("accounts")?.source).toBe("file");
+
+    // UI def is shadowed
+    expect(reg.isShadowed("accounts")).toBe(true);
+    expect(reg.shadowedEntries().get("accounts")).toBe(uiDef);
+
+    // Only one entry in all()
+    expect(reg.all()).toHaveLength(1);
+  });
+
+  it("file def takes over from existing UI def", () => {
+    const reg = new SchemaRegistry();
+    const uiDef = makeTable("accounts");
+    const fileDef = makeTable("accounts");
+
+    reg.register(uiDef, "ui");
+    reg.register(fileDef, "file");
+
+    // File def wins
+    expect(reg.get("accounts")?.def).toBe(fileDef);
+    expect(reg.get("accounts")?.source).toBe("file");
+
+    // Original UI def is now shadowed
+    expect(reg.isShadowed("accounts")).toBe(true);
+    expect(reg.shadowedEntries().get("accounts")).toBe(uiDef);
+  });
+
+  it("fileManaged and uiManaged return correct subsets", () => {
+    const reg = new SchemaRegistry();
+    reg.register(makeTable("accounts"), "file");
+    reg.register(makeTable("invoices"), "ui");
+    reg.register(makeTable("products"), "file");
+
+    expect(reg.fileManaged().map((d) => d.sqlName)).toEqual(["accounts", "products"]);
+    expect(reg.uiManaged().map((d) => d.sqlName)).toEqual(["invoices"]);
+  });
+
+  it("onChange fires on register and unregister", () => {
+    const reg = new SchemaRegistry();
+    const listener = vi.fn();
+    reg.onChange(listener);
+
+    reg.register(makeTable("accounts"), "file");
+    expect(listener).toHaveBeenCalledWith("accounts");
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    reg.unregister("accounts");
+    expect(listener).toHaveBeenCalledWith("accounts");
+    expect(listener).toHaveBeenCalledTimes(2);
+  });
+
+  it("onChange does not fire when UI def is shadowed (no runtime change)", () => {
+    const reg = new SchemaRegistry();
+    reg.register(makeTable("accounts"), "file");
+
+    const listener = vi.fn();
+    reg.onChange(listener);
+
+    // Registering a UI def that gets shadowed should not notify
+    reg.register(makeTable("accounts"), "ui");
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it("re-registering same name replaces the def", () => {
+    const reg = new SchemaRegistry();
+    const v1 = makeTable("accounts");
+    const v2 = makeTable("accounts");
+    reg.register(v1, "file");
+    reg.register(v2, "file");
+
+    expect(reg.get("accounts")?.def).toBe(v2);
+    // Should still be only one entry
+    expect(reg.all()).toHaveLength(1);
+  });
+
+  it("allEntries returns entries with source tags", () => {
+    const reg = new SchemaRegistry();
+    reg.register(makeTable("a"), "file");
+    reg.register(makeTable("b"), "ui");
+
+    const entries = reg.allEntries();
+    expect(entries).toHaveLength(2);
+    expect(entries[0].source).toBe("file");
+    expect(entries[1].source).toBe("ui");
+  });
+
+  it("unregistering file def does NOT promote shadowed UI def", () => {
+    // The shadow is discarded alongside the file entry. The boot sequence
+    // reloads UI schemas from metadata tables, so promoting a stale
+    // in-memory copy would be incorrect.
+    const reg = new SchemaRegistry();
+    const uiDef = makeTable("accounts");
+    const fileDef = makeTable("accounts");
+
+    reg.register(uiDef, "ui");
+    reg.register(fileDef, "file");
+    expect(reg.isShadowed("accounts")).toBe(true);
+
+    reg.unregister("accounts");
+
+    // Both the file entry AND the shadowed UI def are gone
+    expect(reg.has("accounts")).toBe(false);
+    expect(reg.isShadowed("accounts")).toBe(false);
+    expect(reg.all()).toHaveLength(0);
+  });
+});

package/src/schema/registry.ts

@@ -0,0 +1,139 @@
+import type { TableDef } from "./table.js";
+
+export interface RegistryEntry {
+  def: TableDef;
+  /** "file" = defined in TypeScript schema files (always authoritative).
+   *  "ui"   = created at runtime via the metadata tables. */
+  source: "file" | "ui";
+}
+
+/**
+ * Mutable, in-memory registry of table schemas shared across a project's runtime.
+ * The dynamic router queries this on each request to resolve table names to schemas,
+ * so tables added at runtime are immediately accessible without a restart.
+ *
+ * ## Merge semantics
+ *
+ * During boot the registry is populated in two phases:
+ *   1. File schemas are registered first (from `loadSchemas()`)
+ *   2. UI schemas are registered second (from `_sapporta_tables` metadata)
+ *
+ * **File always wins.** If a UI-managed table has the same name as a file-managed
+ * one, the UI definition is "shadowed" — tracked separately so the Schema API can
+ * warn the user, but the file definition is used at runtime. This prevents
+ * UI-created tables from accidentally overriding TypeScript schemas.
+ *
+ * ## Ordering
+ *
+ * Stable insertion order is maintained for sidebar display. File-managed tables
+ * keep their load order; UI-managed tables are ordered by position/created_at.
+ */
+export class SchemaRegistry {
+  private entries = new Map<string, RegistryEntry>();
+
+  /** Separate from entries because re-registering a name must keep its position. */
+  private order: string[] = [];
+
+  /** UI defs hidden by a file def with the same name. Kept for Schema API warnings. */
+  private shadowedDefs = new Map<string, TableDef>();
+
+  private listeners: Array<(name: string) => void> = [];
+
+  /**
+   * Register a table definition. File definitions always take precedence:
+   * - File exists + UI registering → UI def is shadowed (not registered)
+   * - UI exists + File registering → File takes over, UI def moves to shadow
+   * - Same source re-registering → replaced in-place (for schema rebuilds)
+   */
+  register(def: TableDef, source: "file" | "ui"): void {
+    const name = def.sqlName;
+    const existing = this.entries.get(name);
+
+    // File is authoritative — shadow the UI def, don't notify (no runtime change).
+    if (existing && existing.source === "file" && source === "ui") {
+      this.shadowedDefs.set(name, def);
+      return;
+    }
+
+    // File takes over from UI — move the existing UI def to the shadow map.
+    if (existing && existing.source === "ui" && source === "file") {
+      this.shadowedDefs.set(name, existing.def);
+    }
+
+    this.entries.set(name, { def, source });
+
+    // Re-registrations keep their original position in the ordering.
+    if (!this.order.includes(name)) {
+      this.order.push(name);
+    }
+    this.notify(name);
+  }
+
+  /** Remove a table from the registry (e.g. when drift validation finds the DB table is missing). */
+  unregister(name: string): void {
+    if (this.entries.delete(name)) {
+      this.order = this.order.filter((n) => n !== name);
+      this.shadowedDefs.delete(name);
+      this.notify(name);
+    }
+  }
+
+  /** Look up a registry entry by table name. */
+  get(name: string): RegistryEntry | undefined {
+    return this.entries.get(name);
+  }
+
+  /** Check if a table name is registered (active, not just shadowed). */
+  has(name: string): boolean {
+    return this.entries.has(name);
+  }
+
+  /** All active table definitions, in stable insertion order. */
+  all(): TableDef[] {
+    return this.order
+      .filter((name) => this.entries.has(name))
+      .map((name) => this.entries.get(name)!.def);
+  }
+
+  /** All entries with source tags, in stable insertion order. */
+  allEntries(): RegistryEntry[] {
+    return this.order
+      .filter((name) => this.entries.has(name))
+      .map((name) => this.entries.get(name)!);
+  }
+
+  /** Only file-sourced table definitions. */
+  fileManaged(): TableDef[] {
+    return this.allEntries()
+      .filter((e) => e.source === "file")
+      .map((e) => e.def);
+  }
+
+  /** Only UI-sourced table definitions. */
+  uiManaged(): TableDef[] {
+    return this.allEntries()
+      .filter((e) => e.source === "ui")
+      .map((e) => e.def);
+  }
+
+  /** UI definitions shadowed by file definitions. Returns a copy of the map. */
+  shadowedEntries(): Map<string, TableDef> {
+    return new Map(this.shadowedDefs);
+  }
+
+  /** Check if a table name has a shadowed UI definition. */
+  isShadowed(name: string): boolean {
+    return this.shadowedDefs.has(name);
+  }
+
+  /** Subscribe to register/unregister events. Listener receives the table name. */
+  onChange(listener: (name: string) => void): void {
+    this.listeners.push(listener);
+  }
+
+  private notify(name: string): void {
+    for (const listener of this.listeners) {
+      listener(name);
+    }
+  }
+}

package/src/schema/reserved.ts

@@ -0,0 +1,227 @@
+/**
+ * Reserved identifiers that cannot be used as table names.
+ * These collide with static route segments mounted before the dynamic CRUD handler.
+ */
+const RESERVED_TABLE_NAMES = new Set([
+  // Static API route segments
+  "_schema",
+  "_meta",
+  "_reports",
+  "_forms",
+  "actions",
+  // Per-table sub-path segments (used in /:tableName/_lookup etc.)
+  "_lookup",
+  "_count",
+]);
+
+/**
+ * Reserved prefixes. Any name starting with these is rejected.
+ */
+const RESERVED_PREFIXES = ["_sapporta_"];
+
+/**
+ * Validate a SQL table name for use as a UI-managed table.
+ *
+ * Rules:
+ * - Must match [a-z][a-z0-9_]* (snake_case, starts with letter)
+ * - Must not be a reserved route segment
+ * - Must not start with a reserved prefix
+ * - Must not be a SQLite reserved keyword
+ */
+export function validateTableName(
+  name: string,
+): { valid: true } | { valid: false; reason: string } {
+  if (!/^[a-z][a-z0-9_]*$/.test(name)) {
+    return {
+      valid: false,
+      reason: "Must be lowercase snake_case starting with a letter",
+    };
+  }
+  if (RESERVED_TABLE_NAMES.has(name)) {
+    return { valid: false, reason: `"${name}" is a reserved system name` };
+  }
+  for (const prefix of RESERVED_PREFIXES) {
+    if (name.startsWith(prefix)) {
+      return {
+        valid: false,
+        reason: `Names starting with "${prefix}" are reserved for internal use`,
+      };
+    }
+  }
+  if (SQLITE_RESERVED_WORDS.has(name)) {
+    return { valid: false, reason: `"${name}" is a SQLite reserved word` };
+  }
+  return { valid: true };
+}
+
+/**
+ * Validate a SQL column name.
+ */
+export function validateColumnName(
+  name: string,
+): { valid: true } | { valid: false; reason: string } {
+  if (!/^[a-z][a-z0-9_]*$/.test(name)) {
+    return {
+      valid: false,
+      reason: "Must be lowercase snake_case starting with a letter",
+    };
+  }
+  if (name === "id" || name === "created_at" || name === "updated_at") {
+    return {
+      valid: false,
+      reason: `"${name}" is auto-managed and cannot be added manually`,
+    };
+  }
+  return { valid: true };
+}
+
+/** SQLite reserved keywords from https://www.sqlite.org/lang_keywords.html */
+const SQLITE_RESERVED_WORDS = new Set([
+  "abort",
+  "action",
+  "add",
+  "after",
+  "all",
+  "alter",
+  "always",
+  "analyze",
+  "and",
+  "as",
+  "asc",
+  "attach",
+  "autoincrement",
+  "before",
+  "begin",
+  "between",
+  "by",
+  "cascade",
+  "case",
+  "cast",
+  "check",
+  "collate",
+  "column",
+  "commit",
+  "conflict",
+  "constraint",
+  "create",
+  "cross",
+  "current",
+  "current_date",
+  "current_time",
+  "current_timestamp",
+  "database",
+  "default",
+  "deferrable",
+  "deferred",
+  "delete",
+  "desc",
+  "detach",
+  "distinct",
+  "do",
+  "drop",
+  "each",
+  "else",
+  "end",
+  "escape",
+  "except",
+  "exclude",
+  "exclusive",
+  "exists",
+  "explain",
+  "fail",
+  "filter",
+  "first",
+  "following",
+  "for",
+  "foreign",
+  "from",
+  "full",
+  "generated",
+  "glob",
+  "group",
+  "groups",
+  "having",
+  "if",
+  "ignore",
+  "immediate",
+  "in",
+  "index",
+  "indexed",
+  "initially",
+  "inner",
+  "insert",
+  "instead",
+  "intersect",
+  "into",
+  "is",
+  "isnull",
+  "join",
+  "key",
+  "last",
+  "left",
+  "like",
+  "limit",
+  "match",
+  "materialized",
+  "natural",
+  "no",
+  "not",
+  "nothing",
+  "notnull",
+  "null",
+  "nulls",
+  "of",
+  "offset",
+  "on",
+  "or",
+  "order",
+  "others",
+  "outer",
+  "over",
+  "partition",
+  "plan",
+  "pragma",
+  "preceding",
+  "primary",
+  "query",
+  "raise",
+  "range",
+  "recursive",
+  "references",
+  "regexp",
+  "reindex",
+  "release",
+  "rename",
+  "replace",
+  "restrict",
+  "returning",
+  "right",
+  "rollback",
+  "row",
+  "rows",
+  "savepoint",
+  "select",
+  "set",
+  "table",
+  "temp",
+  "temporary",
+  "then",
+  "ties",
+  "to",
+  "transaction",
+  "trigger",
+  "unbounded",
+  "union",
+  "unique",
+  "update",
+  "using",
+  "vacuum",
+  "values",
+  "view",
+  "virtual",
+  "when",
+  "where",
+  "window",
+  "with",
+  "without",
+]);

package/src/schema/table.ts

@@ -0,0 +1,135 @@
+import { type SQLiteTableWithColumns, getTableConfig } from "drizzle-orm/sqlite-core";
+import { text } from "drizzle-orm/sqlite-core";
+import type { z } from "zod";
+
+/**
+ * Pre-configured timestamp column for Sapporta schemas.
+ *
+ * SQLite has no native timestamp type. We use TEXT columns that store
+ * ISO 8601 strings (e.g. "2024-01-15T10:30:00.000Z"). This matches
+ * Sapporta's JSON-over-HTTP data flow — dates cross every boundary as
+ * strings, so storing them as text avoids any Date↔string conversion.
+ *
+ * Callers can chain:
+ *   - .$defaultFn(() => new Date().toISOString()) — JS-side default
+ *   - .default(sql`(datetime('now'))`)            — DDL-side default
+ *
+ * Usage in schema files:
+ * ```ts
+ * import { timestamp } from "@sapporta/server/table";
+ * eaten_at: timestamp("eaten_at").notNull().$defaultFn(() => new Date().toISOString()),
+ * ```
+ */
+export function timestamp(name: string) {
+  return text(name);
+}
+
+/** Metadata for a select/enum column */
+export interface SelectMeta {
+  type: "select";
+  column: string;
+  options: string[];
+}
+
+/** Declares a has-many child relationship for grid display */
+export interface ChildMeta {
+  /** SQL name of the child table */
+  table: string;
+  /** FK column in the child table that references this parent's PK */
+  foreignKey: string;
+  /** Display label (defaults to child table's label) */
+  label?: string;
+  /** Columns to show in nested grid (defaults to all non-PK, non-FK, non-timestamp cols) */
+  columns?: string[];
+  /** Default sort: "column" or "-column" (defaults to PK asc) */
+  defaultSort?: string;
+  /** Width hint in approximate character count (same as ColumnMeta.width) */
+  width?: number;
+}
+
+/** Per-column metadata for display and behavior */
+export interface ColumnMeta {
+  /** Display type override (e.g. "money" for right-aligned decimal formatting) */
+  type?: "money";
+  /** Logical column type from UI metadata (e.g. "text", "email", "link", "currency").
+   *  Only set for UI-managed tables. File-managed tables don't have this. */
+  columnType?: string;
+  /** Custom column header for display */
+  header?: string;
+  /** Hide column from grid and drawer (auto-set for created_at/updated_at) */
+  hidden?: boolean;
+  /** Width hint in approximate character count */
+  width?: number;
+  /** Minimum width in approximate character count */
+  minWidth?: number;
+  /** Maximum width in approximate character count */
+  maxWidth?: number;
+  /** Pixel width from user drag-resize (UI-managed tables only, not for schema-as-code) */
+  widthPx?: number;
+  /** Set to false for nullable numeric columns where NULL is semantically distinct
+      from 0 (e.g. an optional assertion value). Suppresses the nullable-numeric
+      checker warning. */
+  additive?: boolean;
+  /** Freeform notes describing the column's meaning, conventions, or formula */
+  notes?: string;
+}
+
+/** Sapporta-specific metadata attached to a table */
+export interface SapportaMeta {
+  /** Display label for the table */
+  label?: string;
+  /** Column used as the display value in lookups and FK references */
+  displayColumn?: string;
+  /** Select/enum columns */
+  selects?: SelectMeta[];
+  /** Whether records are immutable (no update/delete) */
+  immutable?: boolean;
+  /** Whether LLM inference has been run on this table (UI-managed tables only) */
+  inferred?: boolean;
+  /** User-provided Zod validation schema (overrides auto-inferred) */
+  validation?: z.ZodObject<any>;
+  /** Custom save function (overrides default insert/update) */
+  save?: (record: Record<string, unknown>, db: any) => Promise<any>;
+  /** Has-many child relationships for nested grid display */
+  children?: ChildMeta[];
+  /** Per-column metadata keyed by column name */
+  columns?: Record<string, ColumnMeta>;
+}
+
+/** A Sapporta table definition — wraps a Drizzle SQLite table with metadata */
+export interface TableDef {
+  /** The Drizzle SQLite table object */
+  drizzle: SQLiteTableWithColumns<any>;
+  /** SQL table name extracted from the Drizzle table */
+  sqlName: string;
+  /** Sapporta metadata */
+  meta: SapportaMeta;
+}
+
+/** Options for the table() function */
+export interface TableOptions {
+  /** The Drizzle sqliteTable definition */
+  drizzle: SQLiteTableWithColumns<any>;
+  /** Optional sapporta metadata */
+  meta?: SapportaMeta;
+}
+
+/**
+ * Define a Sapporta table. Wraps a Drizzle sqliteTable with metadata.
+ *
+ * Usage:
+ * ```ts
+ * const accounts = table({
+ *   drizzle: sqliteTable("accounts", { ... }),
+ *   meta: { label: "Accounts" }
+ * });
+ * ```
+ */
+export function table(options: TableOptions): TableDef {
+  const config = getTableConfig(options.drizzle);
+  return {
+    drizzle: options.drizzle,
+    sqlName: config.name,
+    meta: options.meta ?? {},
+  };
+}

package/src/test-fixtures/schema/accounts.ts

@@ -0,0 +1,24 @@
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { table } from "../../schema/table.js";
+
+// SQLite has no native enum type. Enum values are expressed as
+// text({ enum: [...] }) directly in the column definition.
+export default table({
+  drizzle: sqliteTable("accounts", {
+    id: integer("id").primaryKey({ autoIncrement: true }),
+    name: text("name").notNull(),
+    account_type: text("account_type", {
+      enum: ["Asset", "Liability", "Equity", "Revenue", "Expense"],
+    }).notNull(),
+  }),
+  meta: {
+    label: "Accounts",
+    selects: [
+      {
+        type: "select",
+        column: "account_type",
+        options: ["Asset", "Liability", "Equity", "Revenue", "Expense"],
+      },
+    ],
+  },
+});

package/src/test-fixtures/schema/not-a-table.ts

@@ -0,0 +1,6 @@
+// This file exports things that are NOT TableDefs.
+// loadSchemas should skip them without throwing.
+
+export const someConfig = { host: "localhost", port: 5432 };
+export function helper() { return 42; }
+export default "not a table";