@sapporta/server 0.0.1

package/src/introspect/db-helpers.ts

@@ -0,0 +1,109 @@
+// ============================================================================
+// SQLite DB Helpers — existence checks and query builders
+// ============================================================================
+//
+// Low-level database helper functions for SQLite. These replace the Postgres
+// versions which queried information_schema with async postgres.js calls.
+//
+// All functions are synchronous — better-sqlite3 returns results immediately.
+
+import type Database from "better-sqlite3";
+import { OperationError, ErrorCode } from "./types.js";
+
+/**
+ * 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));
+}
+
+/**
+ * Assert that a table exists in the database.
+ * Throws TABLE_NOT_FOUND if the table doesn't exist.
+ */
+export function assertTableExists(
+  sqlite: Database.Database,
+  tableName: string,
+): void {
+  if (!tableExists(sqlite, tableName)) {
+    throw new OperationError(`Table '${tableName}' not found`, ErrorCode.TABLE_NOT_FOUND);
+  }
+}
+
+/**
+ * Validate that all payload columns exist in the target table.
+ * Calls assertTableExists first, then checks each payload column against
+ * the actual column set. Throws INVALID_COLUMN_NAME on unknown columns.
+ */
+export function validatePayloadColumns(
+  sqlite: Database.Database,
+  tableName: string,
+  payloadColumns: string[],
+): void {
+  assertTableExists(sqlite, tableName);
+  const dbColumns = getTableColumns(sqlite, tableName);
+  const unknown = payloadColumns.filter((c) => !dbColumns.has(c));
+  if (unknown.length > 0) {
+    throw new OperationError(
+      `Unknown column(s) in '${tableName}': ${unknown.join(", ")}`,
+      ErrorCode.INVALID_COLUMN_NAME,
+    );
+  }
+}
+
+/**
+ * Build a parameterized INSERT query from a table name and a row object.
+ * Column names are double-quoted to handle reserved words.
+ *
+ * SQLite uses ? positional parameters (not $1, $2, ...) and returns
+ * inserted rows via a separate SELECT (SQLite's RETURNING clause
+ * requires SQLite 3.35+, which better-sqlite3 ships).
+ */
+export function buildInsertQuery(
+  tableName: string,
+  row: Record<string, unknown>,
+): { query: string; values: unknown[] } {
+  const columns = Object.keys(row);
+  const values = Object.values(row);
+  const placeholders = columns.map(() => "?");
+  const query = `INSERT INTO "${tableName}" (${columns.map((c) => `"${c}"`).join(", ")}) VALUES (${placeholders.join(", ")}) RETURNING *`;
+  return { query, values };
+}

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

@@ -0,0 +1,73 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { dbDescribeAll } from "./describe-all.js";
+
+describe("db describe-all", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("returns all tables with their columns", () => {
+    sqlite.exec(`
+      CREATE TABLE accounts (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL);
+      CREATE TABLE invoices (id INTEGER PRIMARY KEY AUTOINCREMENT, amount INTEGER);
+    `);
+
+    const result = dbDescribeAll(sqlite);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    // Structured per-table data is in meta.tables
+    const tables = result.meta?.tables as any[];
+    expect(tables).toHaveLength(2);
+
+    const tableNames = tables.map((t: any) => t.table_name);
+    expect(tableNames).toContain("accounts");
+    expect(tableNames).toContain("invoices");
+
+    // Check columns are populated
+    const accounts = tables.find((t: any) => t.table_name === "accounts") as any;
+    const colNames = accounts.columns.map((c: any) => c.column_name);
+    expect(colNames).toContain("id");
+    expect(colNames).toContain("name");
+  });
+
+  it("includes foreign keys in column data", () => {
+    sqlite.exec(`
+      CREATE TABLE accounts (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL);
+      CREATE TABLE invoices (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        account_id INTEGER REFERENCES accounts(id)
+      );
+    `);
+
+    const result = dbDescribeAll(sqlite);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    // FK info is embedded in the column descriptions
+    const tables = result.meta?.tables as any[];
+    const invoices = tables.find((t: any) => t.table_name === "invoices") as any;
+    const fkCol = invoices.columns.find((c: any) => c.column_name === "account_id");
+    expect(fkCol.foreign_table).toBe("accounts");
+    expect(fkCol.foreign_column).toBe("id");
+  });
+
+  it("returns empty when no tables", () => {
+    const result = dbDescribeAll(sqlite);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(0);
+    expect(result.meta?.message).toBe("No tables found.");
+  });
+});

package/src/introspect/describe-all.ts

@@ -0,0 +1,80 @@
+// ============================================================================
+// 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 type { OperationResult } from "./types.js";
+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));
+}
+
+/**
+ * OperationResult wrapper for CLI/API consumption.
+ *
+ * Returns flat column array as primary data (for table-mode rendering)
+ * and structured per-table objects in meta (for JSON consumers).
+ */
+export function dbDescribeAll(sqlite: Database.Database): OperationResult {
+  const descriptions = describeAllTables(sqlite);
+
+  if (descriptions.length === 0) {
+    return { ok: true, data: [], meta: { message: "No tables found." } };
+  }
+
+  // Flat column array with table_name prefix for table-mode rendering
+  const flatData: Record<string, unknown>[] = [];
+  for (const desc of descriptions) {
+    for (const col of desc.columns) {
+      flatData.push({
+        table_name: desc.name,
+        ...col,
+      });
+    }
+  }
+
+  // Structured per-table format for JSON consumers
+  const structured = descriptions.map((desc) => ({
+    table_name: desc.name,
+    columns: desc.columns,
+  }));
+
+  // Text output grouping by table
+  const lines: string[] = [];
+  for (const desc of descriptions) {
+    lines.push(`\n── ${desc.name} ──`);
+    for (const col of desc.columns) {
+      const flags = [];
+      if (col.is_primary_key === "YES") flags.push("PK");
+      if (col.is_unique === "YES") flags.push("UNIQUE");
+      if (col.is_nullable === "NO") flags.push("NOT NULL");
+      if (col.column_default) flags.push(`DEFAULT ${col.column_default}`);
+      if (col.foreign_table) flags.push(`FK → ${col.foreign_table}.${col.foreign_column}`);
+      const flagStr = flags.length > 0 ? ` (${flags.join(", ")})` : "";
+      lines.push(`  ${col.column_name}: ${col.data_type}${flagStr}`);
+    }
+  }
+
+  return {
+    ok: true,
+    data: flatData,
+    meta: {
+      tables: structured,
+      textOutput: lines.join("\n"),
+      tableOutputHandled: true,
+      message: lines.join("\n"),
+    },
+  };
+}

package/src/introspect/describe.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { dbDescribe } from "./describe.js";
+
+describe("db describe", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("describes table columns", () => {
+    sqlite.exec(`
+      CREATE TABLE accounts (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL,
+        balance INTEGER
+      )
+    `);
+
+    const result = dbDescribe(sqlite, "accounts");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const columnNames = result.data.map((r) => r.column_name);
+    expect(columnNames).toContain("id");
+    expect(columnNames).toContain("name");
+    expect(columnNames).toContain("balance");
+    expect(result.meta?.tableName).toBe("accounts");
+  });
+
+  it("shows foreign keys", () => {
+    sqlite.exec(`CREATE TABLE accounts (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL)`);
+    sqlite.exec(`
+      CREATE TABLE invoices (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        account_id INTEGER NOT NULL REFERENCES accounts(id),
+        amount INTEGER NOT NULL
+      )
+    `);
+
+    const result = dbDescribe(sqlite, "invoices");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const fks = result.meta?.foreignKeys as Record<string, unknown>[];
+    expect(fks).toHaveLength(1);
+    expect(fks[0].column_name).toBe("account_id");
+    expect(fks[0].foreign_table).toBe("accounts");
+  });
+
+  it("shows message for nonexistent table", () => {
+    const result = dbDescribe(sqlite, "nonexistent");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(0);
+    expect(result.meta?.message).toBe("Table 'nonexistent' not found.");
+  });
+});

package/src/introspect/describe.ts

@@ -0,0 +1,184 @@
+// ============================================================================
+// 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 old 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.
+ */
+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 old 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/exec.test.ts

@@ -0,0 +1,103 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { dbExec } from "./exec.js";
+
+describe("dbExec", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+    sqlite.exec(`
+      CREATE TABLE accounts (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL,
+        type TEXT NOT NULL
+      )
+    `);
+    // Seed a row for UPDATE/DELETE tests
+    sqlite.exec(`INSERT INTO accounts (name, type) VALUES ('Cash', 'asset')`);
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("executes INSERT and returns OK with row count", () => {
+    const result = dbExec(sqlite, `INSERT INTO accounts (name, type) VALUES ('Revenue', 'revenue')`);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    // SQLite dbExec uses .run() which returns changes count, not rows
+    expect(result.data).toHaveLength(0);
+    expect(result.meta?.rowCount).toBe(1);
+  });
+
+  it("executes UPDATE and returns row count", () => {
+    const result = dbExec(sqlite, `UPDATE accounts SET name = 'Petty Cash' WHERE name = 'Cash'`);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(0);
+    expect(result.meta?.rowCount).toBe(1);
+  });
+
+  it("returns OK (0 rows) message for mutations affecting no rows", () => {
+    const result = dbExec(sqlite, `UPDATE accounts SET name = 'Petty Cash' WHERE name = 'NonExistent'`);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(0);
+    expect(result.meta?.message).toBe("OK (0 rows)");
+  });
+
+  it("executes DELETE", () => {
+    const result = dbExec(sqlite, `DELETE FROM accounts WHERE name = 'Cash'`);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.meta?.rowCount).toBe(1);
+
+    // Verify row is gone
+    const rows = sqlite.prepare("SELECT * FROM accounts").all();
+    expect(rows).toHaveLength(0);
+  });
+
+  // -- Dangerous SQL rejection --
+
+  it("rejects DROP DATABASE", () => {
+    expect(() => dbExec(sqlite, "DROP DATABASE sapporta")).toThrow("DROP DATABASE");
+  });
+
+  it("rejects TRUNCATE", () => {
+    expect(() => dbExec(sqlite, "TRUNCATE accounts")).toThrow("TRUNCATE");
+  });
+
+  it("rejects DROP SCHEMA", () => {
+    expect(() => dbExec(sqlite, "DROP SCHEMA public CASCADE")).toThrow("DROP SCHEMA");
+  });
+
+  // -- Dry-run mode --
+  // EXPLAIN QUERY PLAN validates the SQL plan without executing the statement.
+
+  it("dry-run returns EXPLAIN QUERY PLAN without executing", () => {
+    const result = dbExec(
+      sqlite,
+      `INSERT INTO accounts (name, type) VALUES ('Revenue', 'revenue')`,
+      true,
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.meta?.dryRun).toBe(true);
+    expect(result.meta?.message).toContain("Dry run");
+
+    // Verify nothing was actually inserted
+    const rows = sqlite.prepare("SELECT * FROM accounts").all();
+    expect(rows).toHaveLength(1); // Only the seeded row
+  });
+
+  it("dry-run still rejects dangerous SQL", () => {
+    expect(() => dbExec(sqlite, "DROP DATABASE sapporta", true)).toThrow("DROP DATABASE");
+  });
+});

package/src/introspect/exec.ts

@@ -0,0 +1,57 @@
+// ============================================================================
+// SQLite SQL Proxy — mutating statement execution
+// ============================================================================
+//
+// Allows INSERT, UPDATE, DELETE, and DDL statements. Rejects dangerous
+// operations (DROP DATABASE, TRUNCATE).
+//
+// 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)" }),
+    },
+  };
+}