@sapporta/server 0.0.1

package/src/introspect/sqlite/db-helpers.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { tableExists, columnExists, getTableColumns } from "./db-helpers.js";
+
+describe("tableExists", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("returns true for existing table", () => {
+    sqlite.exec(`CREATE TABLE accounts (id INTEGER PRIMARY KEY)`);
+    expect(tableExists(sqlite, "accounts")).toBe(true);
+  });
+
+  it("returns false for non-existent table", () => {
+    expect(tableExists(sqlite, "accounts")).toBe(false);
+  });
+
+  it("returns false for sqlite_ internal tables", () => {
+    // sqlite_master always exists but tableExists filters by name = ?
+    // so it would find it — this is correct behavior (it does exist).
+    // The filtering of internal tables is done at the list-tables level, not here.
+    sqlite.exec(`CREATE TABLE test (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)`);
+    sqlite.prepare("INSERT INTO test (name) VALUES (?)").run("x");
+    // sqlite_sequence exists after AUTOINCREMENT insert
+    expect(tableExists(sqlite, "sqlite_sequence")).toBe(true);
+  });
+});
+
+describe("columnExists", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+    sqlite.exec(`CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)`);
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("returns true for existing column", () => {
+    expect(columnExists(sqlite, "users", "name")).toBe(true);
+    expect(columnExists(sqlite, "users", "email")).toBe(true);
+  });
+
+  it("returns false for non-existent column", () => {
+    expect(columnExists(sqlite, "users", "phone")).toBe(false);
+  });
+});
+
+describe("getTableColumns", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+    sqlite.exec(`CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)`);
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("returns set of column names", () => {
+    const cols = getTableColumns(sqlite, "users");
+    expect(cols).toEqual(new Set(["id", "name", "email"]));
+  });
+
+  it("returns empty set for non-existent table", () => {
+    const cols = getTableColumns(sqlite, "nonexistent");
+    expect(cols).toEqual(new Set());
+  });
+});

package/src/introspect/sqlite/db-helpers.ts

@@ -0,0 +1,56 @@
+// ============================================================================
+// SQLite DB Helpers — low-level existence checks and query builders
+// ============================================================================
+//
+// These are the SQLite equivalents of the Postgres db-helpers.ts functions.
+// They use sqlite_master and PRAGMA table_info instead of information_schema.
+//
+// Unlike the Postgres versions which are async (because postgres.js is async),
+// these are synchronous — better-sqlite3 returns results immediately.
+
+import type Database from "better-sqlite3";
+
+/**
+ * Check whether a table exists in the database.
+ * Uses sqlite_master (the authoritative catalog for SQLite).
+ */
+export function tableExists(
+  sqlite: Database.Database,
+  tableName: string,
+): boolean {
+  const row = sqlite
+    .prepare(
+      `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?`,
+    )
+    .get(tableName);
+  return row !== undefined;
+}
+
+/**
+ * Check whether a specific column exists in a table.
+ * Uses PRAGMA table_info which returns one row per column.
+ */
+export function columnExists(
+  sqlite: Database.Database,
+  tableName: string,
+  columnName: string,
+): boolean {
+  const cols = sqlite.pragma(
+    `table_info("${tableName}")`,
+  ) as { name: string }[];
+  return cols.some((c) => c.name === columnName);
+}
+
+/**
+ * Return the set of column names for a table.
+ * Used to validate payload columns against actual table structure.
+ */
+export function getTableColumns(
+  sqlite: Database.Database,
+  tableName: string,
+): Set<string> {
+  const cols = sqlite.pragma(
+    `table_info("${tableName}")`,
+  ) as { name: string }[];
+  return new Set(cols.map((c) => c.name));
+}

package/src/introspect/sqlite/describe-all.ts

@@ -0,0 +1,21 @@
+// ============================================================================
+// SQLite Describe All — batch table description
+// ============================================================================
+//
+// Calls describeTable() for each table from listTables().
+// No new PRAGMA patterns — just composition of existing primitives.
+
+import type Database from "better-sqlite3";
+import { listTables } from "./list-tables.js";
+import { describeTable, type TableDescription } from "./describe.js";
+
+/**
+ * Describe all user tables in the database.
+ * Returns an array of TableDescription objects in alphabetical order.
+ */
+export function describeAllTables(
+  sqlite: Database.Database,
+): TableDescription[] {
+  const tables = listTables(sqlite);
+  return tables.map((t) => describeTable(sqlite, t.name));
+}

package/src/introspect/sqlite/describe.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import {
+  buildColumnDescriptions,
+  describeTable,
+  type PragmaTableInfo,
+  type PragmaForeignKey,
+} from "./describe.js";
+
+// ─── Pure function tests (no DB) ───────────────────────────────────────────
+
+describe("buildColumnDescriptions (pure)", () => {
+  it("maps basic column info", () => {
+    const pragmaInfo: PragmaTableInfo[] = [
+      { cid: 0, name: "id", type: "INTEGER", notnull: 1, dflt_value: null, pk: 1 },
+      { cid: 1, name: "name", type: "TEXT", notnull: 1, dflt_value: null, pk: 0 },
+      { cid: 2, name: "email", type: "TEXT", notnull: 0, dflt_value: null, pk: 0 },
+    ];
+
+    const result = buildColumnDescriptions(pragmaInfo, []);
+    expect(result).toEqual([
+      {
+        column_name: "id",
+        data_type: "INTEGER",
+        is_nullable: "NO",
+        column_default: null,
+        is_primary_key: "YES",
+        is_unique: "NO",
+        foreign_table: null,
+        foreign_column: null,
+      },
+      {
+        column_name: "name",
+        data_type: "TEXT",
+        is_nullable: "NO",
+        column_default: null,
+        is_primary_key: "NO",
+        is_unique: "NO",
+        foreign_table: null,
+        foreign_column: null,
+      },
+      {
+        column_name: "email",
+        data_type: "TEXT",
+        is_nullable: "YES",
+        column_default: null,
+        is_primary_key: "NO",
+        is_unique: "NO",
+        foreign_table: null,
+        foreign_column: null,
+      },
+    ]);
+  });
+
+  it("attaches FK information from foreign_key_list", () => {
+    const pragmaInfo: PragmaTableInfo[] = [
+      { cid: 0, name: "id", type: "INTEGER", notnull: 1, dflt_value: null, pk: 1 },
+      { cid: 1, name: "account_id", type: "INTEGER", notnull: 1, dflt_value: null, pk: 0 },
+    ];
+
+    const pragmaFks: PragmaForeignKey[] = [
+      { id: 0, seq: 0, table: "accounts", from: "account_id", to: "id", on_update: "NO ACTION", on_delete: "NO ACTION", match: "NONE" },
+    ];
+
+    const result = buildColumnDescriptions(pragmaInfo, pragmaFks);
+    expect(result[1].foreign_table).toBe("accounts");
+    expect(result[1].foreign_column).toBe("id");
+  });
+
+  it("handles default values", () => {
+    const pragmaInfo: PragmaTableInfo[] = [
+      { cid: 0, name: "status", type: "TEXT", notnull: 1, dflt_value: "'active'", pk: 0 },
+      { cid: 1, name: "count", type: "INTEGER", notnull: 0, dflt_value: "0", pk: 0 },
+    ];
+
+    const result = buildColumnDescriptions(pragmaInfo, []);
+    expect(result[0].column_default).toBe("'active'");
+    expect(result[1].column_default).toBe("0");
+  });
+
+  it("handles empty type string (SQLite allows typeless columns)", () => {
+    const pragmaInfo: PragmaTableInfo[] = [
+      { cid: 0, name: "data", type: "", notnull: 0, dflt_value: null, pk: 0 },
+    ];
+
+    const result = buildColumnDescriptions(pragmaInfo, []);
+    expect(result[0].data_type).toBe("TEXT"); // falls back to TEXT
+  });
+
+  it("marks unique columns from provided set", () => {
+    const pragmaInfo: PragmaTableInfo[] = [
+      { cid: 0, name: "id", type: "INTEGER", notnull: 1, dflt_value: null, pk: 1 },
+      { cid: 1, name: "email", type: "TEXT", notnull: 1, dflt_value: null, pk: 0 },
+    ];
+
+    const uniqueCols = new Set(["email"]);
+    const result = buildColumnDescriptions(pragmaInfo, [], uniqueCols);
+    expect(result[1].is_unique).toBe("YES");
+    expect(result[0].is_unique).toBe("NO");
+  });
+});
+
+// ─── I/O wrapper tests (with in-memory DB) ─────────────────────────────────
+
+describe("describeTable", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("describes a simple table", () => {
+    sqlite.exec(`CREATE TABLE users (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL,
+      email TEXT UNIQUE
+    )`);
+
+    const desc = describeTable(sqlite, "users");
+    expect(desc.name).toBe("users");
+    expect(desc.columns).toHaveLength(3);
+
+    const idCol = desc.columns.find((c) => c.column_name === "id")!;
+    expect(idCol.is_primary_key).toBe("YES");
+    // SQLite quirk: PRAGMA table_info reports notnull=0 for INTEGER PRIMARY KEY
+    // columns even though they are implicitly NOT NULL. The PRAGMA only reflects
+    // the explicit NOT NULL constraint in the CREATE TABLE statement, not the
+    // implicit one from being a PK. This is a known SQLite behavior.
+    expect(idCol.is_nullable).toBe("YES");
+
+    const emailCol = desc.columns.find((c) => c.column_name === "email")!;
+    expect(emailCol.is_unique).toBe("YES");
+    expect(emailCol.is_nullable).toBe("YES");
+  });
+
+  it("describes foreign key relationships", () => {
+    sqlite.exec(`CREATE TABLE accounts (id INTEGER PRIMARY KEY, name TEXT)`);
+    sqlite.exec(`CREATE TABLE entries (
+      id INTEGER PRIMARY KEY,
+      account_id INTEGER NOT NULL REFERENCES accounts(id),
+      amount REAL
+    )`);
+
+    const desc = describeTable(sqlite, "entries");
+    const fkCol = desc.columns.find((c) => c.column_name === "account_id")!;
+    expect(fkCol.foreign_table).toBe("accounts");
+    expect(fkCol.foreign_column).toBe("id");
+    expect(fkCol.is_nullable).toBe("NO");
+  });
+
+  it("returns empty columns for non-existent table", () => {
+    const desc = describeTable(sqlite, "nonexistent");
+    expect(desc.columns).toEqual([]);
+  });
+});

package/src/introspect/sqlite/describe.ts

@@ -0,0 +1,185 @@
+// ============================================================================
+// SQLite Table Description — column metadata via PRAGMA table_info
+// ============================================================================
+//
+// Split into a pure transformer (buildColumnDescriptions) and a thin I/O
+// wrapper (describeTable). The pure function can be tested with mock
+// PRAGMA output, without touching any database.
+//
+// SQLite's PRAGMA table_info returns a fundamentally different shape than
+// PostgreSQL's information_schema. Key differences:
+//   - Types are affinity-based (TEXT, INTEGER, REAL, BLOB, NUMERIC),
+//     not rich types (varchar(255), timestamptz, etc.)
+//   - Primary key is indicated by pk > 0, not a separate constraint query
+//   - Foreign keys require a separate PRAGMA foreign_key_list() call
+//   - No UNIQUE information from table_info (requires index_list + index_info)
+
+import type Database from "better-sqlite3";
+import type { OperationResult } from "../types.js";
+
+// ─── Raw PRAGMA result types ────────────────────────────────────────────────
+
+/** Row from PRAGMA table_info("tableName") */
+export interface PragmaTableInfo {
+  cid: number;
+  name: string;
+  type: string;
+  notnull: number; // 0 or 1
+  dflt_value: string | null;
+  pk: number; // 0 = not PK, >0 = PK ordinal position
+}
+
+/** Row from PRAGMA foreign_key_list("tableName") */
+export interface PragmaForeignKey {
+  id: number;
+  seq: number;
+  table: string;
+  from: string;
+  to: string;
+  on_update: string;
+  on_delete: string;
+  match: string;
+}
+
+// ─── Output types ───────────────────────────────────────────────────────────
+
+export interface ColumnDescription {
+  column_name: string;
+  data_type: string;
+  is_nullable: string; // "YES" | "NO" — matches Postgres information_schema convention
+  column_default: string | null;
+  is_primary_key: string; // "YES" | "NO"
+  is_unique: string; // "YES" | "NO"
+  foreign_table: string | null;
+  foreign_column: string | null;
+}
+
+export interface TableDescription {
+  name: string;
+  columns: ColumnDescription[];
+}
+
+// ─── Pure transformer ───────────────────────────────────────────────────────
+
+/**
+ * Transform raw PRAGMA output into a unified column description format.
+ *
+ * This is the pure, testable core. It maps SQLite's PRAGMA structures into
+ * the same shape used by the Postgres describe.ts, so the CLI and API
+ * layers can consume both uniformly.
+ *
+ * @param pragmaInfo Rows from PRAGMA table_info()
+ * @param pragmaFks  Rows from PRAGMA foreign_key_list()
+ * @param uniqueCols Set of column names that have a UNIQUE index (from describeTable)
+ */
+export function buildColumnDescriptions(
+  pragmaInfo: PragmaTableInfo[],
+  pragmaFks: PragmaForeignKey[],
+  uniqueCols: Set<string> = new Set(),
+): ColumnDescription[] {
+  // Build FK lookup: source column name → { table, column }
+  // A column can only be the source of one FK in practice, but
+  // PRAGMA foreign_key_list can return multi-column FKs (seq > 0).
+  // We only handle single-column FKs here (seq === 0).
+  const fkMap = new Map<string, { table: string; column: string }>();
+  for (const fk of pragmaFks) {
+    if (fk.seq === 0) {
+      fkMap.set(fk.from, { table: fk.table, column: fk.to });
+    }
+  }
+
+  return pragmaInfo.map((col) => {
+    const fk = fkMap.get(col.name);
+    return {
+      column_name: col.name,
+      data_type: col.type || "TEXT", // SQLite allows empty type strings
+      is_nullable: col.notnull === 1 ? "NO" : "YES",
+      column_default: col.dflt_value,
+      is_primary_key: col.pk > 0 ? "YES" : "NO",
+      is_unique: uniqueCols.has(col.name) ? "YES" : "NO",
+      foreign_table: fk?.table ?? null,
+      foreign_column: fk?.column ?? null,
+    };
+  });
+}
+
+// ─── I/O wrapper ────────────────────────────────────────────────────────────
+
+/**
+ * Describe a table's structure by querying SQLite PRAGMAs.
+ *
+ * Gathers column info, foreign keys, and unique constraints from three
+ * separate PRAGMAs and merges them via buildColumnDescriptions.
+ */
+export function describeTable(
+  sqlite: Database.Database,
+  tableName: string,
+): TableDescription {
+  const info = sqlite.pragma(`table_info("${tableName}")`) as PragmaTableInfo[];
+  const fks = sqlite.pragma(
+    `foreign_key_list("${tableName}")`,
+  ) as PragmaForeignKey[];
+
+  // Determine which columns have UNIQUE indexes.
+  // PRAGMA index_list returns all indexes; we filter for unique ones,
+  // then check index_info for single-column indexes to mark them.
+  const uniqueCols = new Set<string>();
+  const indexes = sqlite.pragma(`index_list("${tableName}")`) as {
+    name: string;
+    unique: number;
+  }[];
+  for (const idx of indexes) {
+    if (idx.unique === 1) {
+      const cols = sqlite.pragma(`index_info("${idx.name}")`) as {
+        name: string;
+      }[];
+      // Only mark single-column unique indexes (multi-column unique
+      // constraints are a table-level property, not per-column)
+      if (cols.length === 1) {
+        uniqueCols.add(cols[0].name);
+      }
+    }
+  }
+
+  return {
+    name: tableName,
+    columns: buildColumnDescriptions(info, fks, uniqueCols),
+  };
+}
+
+/**
+ * OperationResult wrapper for CLI/API consumption.
+ * Matches the interface of the Postgres dbDescribe().
+ */
+export function dbDescribe(
+  sqlite: Database.Database,
+  tableName: string,
+): OperationResult {
+  const desc = describeTable(sqlite, tableName);
+
+  if (desc.columns.length === 0) {
+    return {
+      ok: true,
+      data: [],
+      meta: { message: `Table '${tableName}' not found.` },
+    };
+  }
+
+  // Separate FK info for structured output (same pattern as Postgres version)
+  const fkColumns = desc.columns.filter((c) => c.foreign_table !== null);
+  const foreignKeys = fkColumns.map((c) => ({
+    column_name: c.column_name,
+    foreign_table: c.foreign_table,
+    foreign_column: c.foreign_column,
+  }));
+
+  return {
+    ok: true,
+    data: desc.columns as unknown as Record<string, unknown>[],
+    meta: {
+      message: `Table: ${tableName}\n`,
+      tableName,
+      foreignKeys,
+    },
+  };
+}

package/src/introspect/sqlite/exec.ts

@@ -0,0 +1,57 @@
+// ============================================================================
+// SQLite SQL Proxy — mutating statement execution
+// ============================================================================
+//
+// SQLite equivalent of the Postgres exec.ts. Allows INSERT, UPDATE, DELETE,
+// and DDL statements. Rejects dangerous operations (DROP DATABASE, TRUNCATE).
+//
+// Key difference from Postgres: uses EXPLAIN QUERY PLAN (not EXPLAIN) for
+// dry-run validation, since SQLite's EXPLAIN output is bytecode-level and
+// not useful for human consumption. EXPLAIN QUERY PLAN gives a high-level
+// description of the query strategy.
+
+import type Database from "better-sqlite3";
+import type { OperationResult } from "../types.js";
+import { rejectDangerousSQL } from "../sql-safety.js";
+
+/**
+ * Execute a mutating SQL statement against the SQLite database.
+ *
+ * When dryRun is true, uses EXPLAIN QUERY PLAN to validate syntax
+ * without executing. Returns the query plan as data rows.
+ *
+ * When executing, returns the number of rows changed via info.changes.
+ */
+export function dbExec(
+  sqlite: Database.Database,
+  rawSql: string,
+  dryRun: boolean = false,
+): OperationResult {
+  rejectDangerousSQL(rawSql);
+
+  if (dryRun) {
+    const plan = sqlite
+      .prepare(`EXPLAIN QUERY PLAN ${rawSql}`)
+      .all() as Record<string, unknown>[];
+    return {
+      ok: true,
+      data: plan,
+      meta: {
+        message: "Dry run: SQL is valid (EXPLAIN QUERY PLAN succeeded)",
+        dryRun: true,
+        tableOutputHandled: true,
+      },
+    };
+  }
+
+  const info = sqlite.prepare(rawSql).run();
+
+  return {
+    ok: true,
+    data: [],
+    meta: {
+      rowCount: info.changes,
+      ...(info.changes === 0 && { message: "OK (0 rows)" }),
+    },
+  };
+}

package/src/introspect/sqlite/indexes.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { describeIndexes } from "./indexes.js";
+
+describe("describeIndexes", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("returns empty array for table with no explicit indexes", () => {
+    sqlite.exec(`CREATE TABLE simple (id INTEGER PRIMARY KEY, name TEXT)`);
+    // INTEGER PRIMARY KEY doesn't create an entry in index_list in SQLite
+    const indexes = describeIndexes(sqlite, "simple");
+    expect(indexes).toEqual([]);
+  });
+
+  it("lists UNIQUE constraint indexes", () => {
+    sqlite.exec(`CREATE TABLE users (
+      id INTEGER PRIMARY KEY,
+      email TEXT UNIQUE
+    )`);
+
+    const indexes = describeIndexes(sqlite, "users");
+    expect(indexes.length).toBeGreaterThanOrEqual(1);
+    const emailIdx = indexes.find((i) => i.columns.includes("email"));
+    expect(emailIdx).toBeDefined();
+    expect(emailIdx!.unique).toBe(true);
+    expect(emailIdx!.origin).toBe("u"); // from UNIQUE constraint
+  });
+
+  it("lists explicit CREATE INDEX", () => {
+    sqlite.exec(`CREATE TABLE orders (id INTEGER PRIMARY KEY, customer TEXT, date TEXT)`);
+    sqlite.exec(`CREATE INDEX idx_orders_customer ON orders(customer)`);
+    sqlite.exec(`CREATE UNIQUE INDEX idx_orders_date ON orders(date)`);
+
+    const indexes = describeIndexes(sqlite, "orders");
+    const customerIdx = indexes.find((i) => i.name === "idx_orders_customer")!;
+    expect(customerIdx.unique).toBe(false);
+    expect(customerIdx.columns).toEqual(["customer"]);
+
+    const dateIdx = indexes.find((i) => i.name === "idx_orders_date")!;
+    expect(dateIdx.unique).toBe(true);
+    expect(dateIdx.columns).toEqual(["date"]);
+  });
+
+  it("handles multi-column indexes", () => {
+    sqlite.exec(`CREATE TABLE events (id INTEGER PRIMARY KEY, year INTEGER, month INTEGER)`);
+    sqlite.exec(`CREATE INDEX idx_events_period ON events(year, month)`);
+
+    const indexes = describeIndexes(sqlite, "events");
+    const periodIdx = indexes.find((i) => i.name === "idx_events_period")!;
+    expect(periodIdx.columns).toEqual(["year", "month"]);
+  });
+});