@sapporta/server 0.0.1

package/src/introspect/sqlite/indexes.ts

@@ -0,0 +1,96 @@
+// ============================================================================
+// SQLite Index Listing — index metadata via PRAGMA index_list / index_info
+// ============================================================================
+//
+// SQLite equivalent of the Postgres indexes.ts. Uses two PRAGMAs:
+//   - index_list("table") → list of indexes with uniqueness flag
+//   - index_info("index")  → columns in each index
+
+import type Database from "better-sqlite3";
+import type { OperationResult } from "../types.js";
+
+/** Row from PRAGMA index_list("tableName") */
+interface PragmaIndexList {
+  seq: number;
+  name: string;
+  unique: number; // 0 or 1
+  origin: string; // "c" = CREATE INDEX, "u" = UNIQUE constraint, "pk" = PRIMARY KEY
+  partial: number; // 0 or 1
+}
+
+/** Row from PRAGMA index_info("indexName") */
+interface PragmaIndexInfo {
+  seqno: number;
+  cid: number;
+  name: string;
+}
+
+export interface IndexDescription {
+  name: string;
+  unique: boolean;
+  columns: string[];
+  origin: string;
+}
+
+/**
+ * List all indexes on a table.
+ *
+ * For each index, queries PRAGMA index_info to resolve column names.
+ * The origin field indicates how the index was created:
+ *   "c" = explicit CREATE INDEX
+ *   "u" = UNIQUE constraint in CREATE TABLE
+ *   "pk" = PRIMARY KEY constraint
+ */
+export function describeIndexes(
+  sqlite: Database.Database,
+  tableName: string,
+): IndexDescription[] {
+  const indexes = sqlite.pragma(
+    `index_list("${tableName}")`,
+  ) as PragmaIndexList[];
+
+  return indexes.map((idx) => {
+    const cols = sqlite.pragma(
+      `index_info("${idx.name}")`,
+    ) as PragmaIndexInfo[];
+    return {
+      name: idx.name,
+      unique: idx.unique === 1,
+      columns: cols.map((c) => c.name),
+      origin: idx.origin,
+    };
+  });
+}
+
+/**
+ * OperationResult wrapper for CLI/API consumption.
+ * Matches the interface of the Postgres dbIndexes().
+ */
+export function dbIndexes(
+  sqlite: Database.Database,
+  tableName: string,
+): OperationResult {
+  const indexes = describeIndexes(sqlite, tableName);
+
+  if (indexes.length === 0) {
+    return {
+      ok: true,
+      data: [],
+      meta: { message: `No indexes found for table '${tableName}'.` },
+    };
+  }
+
+  // Flatten to match the Postgres output shape for CLI table rendering
+  const data = indexes.map((idx) => ({
+    index_name: idx.name,
+    columns: idx.columns.join(", "),
+    is_unique: idx.unique,
+    is_primary: idx.origin === "pk",
+  }));
+
+  return {
+    ok: true,
+    data,
+    meta: { message: `Indexes on ${tableName}:` },
+  };
+}

package/src/introspect/sqlite/list-tables.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { listTables, dbListTables } from "./list-tables.js";
+
+describe("listTables", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("returns empty array for empty database", () => {
+    const tables = listTables(sqlite);
+    expect(tables).toEqual([]);
+  });
+
+  it("lists user tables with row counts", () => {
+    sqlite.exec(`CREATE TABLE accounts (id INTEGER PRIMARY KEY, name TEXT)`);
+    sqlite.exec(`CREATE TABLE entries (id INTEGER PRIMARY KEY, amount REAL)`);
+    sqlite.prepare("INSERT INTO accounts (name) VALUES (?)").run("Cash");
+    sqlite.prepare("INSERT INTO accounts (name) VALUES (?)").run("Revenue");
+    sqlite
+      .prepare("INSERT INTO entries (amount) VALUES (?)")
+      .run(100);
+
+    const tables = listTables(sqlite);
+    expect(tables).toEqual([
+      { name: "accounts", rowCount: 2 },
+      { name: "entries", rowCount: 1 },
+    ]);
+  });
+
+  it("excludes sqlite_ internal tables", () => {
+    // sqlite_sequence is auto-created when AUTOINCREMENT is used
+    sqlite.exec(
+      `CREATE TABLE test (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)`,
+    );
+    sqlite.prepare("INSERT INTO test (name) VALUES (?)").run("hello");
+
+    const tables = listTables(sqlite);
+    expect(tables).toHaveLength(1);
+    expect(tables[0].name).toBe("test");
+  });
+
+  it("excludes _litestream_ tables", () => {
+    sqlite.exec(`CREATE TABLE _litestream_seq (id INTEGER PRIMARY KEY)`);
+    sqlite.exec(`CREATE TABLE real_table (id INTEGER PRIMARY KEY)`);
+
+    const tables = listTables(sqlite);
+    expect(tables).toHaveLength(1);
+    expect(tables[0].name).toBe("real_table");
+  });
+
+  it("returns tables sorted alphabetically", () => {
+    sqlite.exec(`CREATE TABLE zeta (id INTEGER PRIMARY KEY)`);
+    sqlite.exec(`CREATE TABLE alpha (id INTEGER PRIMARY KEY)`);
+    sqlite.exec(`CREATE TABLE mu (id INTEGER PRIMARY KEY)`);
+
+    const names = listTables(sqlite).map((t) => t.name);
+    expect(names).toEqual(["alpha", "mu", "zeta"]);
+  });
+});
+
+describe("dbListTables", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("returns OperationResult with message for empty DB", () => {
+    const result = dbListTables(sqlite);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.data).toEqual([]);
+      expect(result.meta?.message).toBe("No tables found.");
+    }
+  });
+
+  it("returns OperationResult with table_name/row_count shape", () => {
+    sqlite.exec(`CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)`);
+    sqlite.prepare("INSERT INTO users (name) VALUES (?)").run("Alice");
+
+    const result = dbListTables(sqlite);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.data).toEqual([
+        { table_name: "users", row_count: 1 },
+      ]);
+    }
+  });
+});

package/src/introspect/sqlite/list-tables.ts

@@ -0,0 +1,67 @@
+// ============================================================================
+// SQLite Table Listing — enumerate user tables with row counts
+// ============================================================================
+//
+// SQLite equivalent of the Postgres list-tables.ts. Uses sqlite_master
+// instead of information_schema, and SELECT COUNT(*) for exact row counts
+// instead of pg_stat_get_live_tuples() (which returns estimates).
+//
+// Exact counts are fine for SQLite's dataset sizes. If this ever becomes
+// a bottleneck, we can switch to a stat table or sampling.
+
+import type Database from "better-sqlite3";
+import type { OperationResult } from "../types.js";
+
+export interface TableInfo {
+  name: string;
+  rowCount: number;
+}
+
+/**
+ * List all user tables in the SQLite database with exact row counts.
+ *
+ * Excludes:
+ * - sqlite_* internal tables (sqlite_sequence, sqlite_stat1, etc.)
+ * - _litestream_* tables (Litestream replication metadata)
+ *
+ * The WHERE filters use NOT LIKE rather than a NOT IN list so we
+ * automatically cover any future internal table prefixes.
+ */
+export function listTables(sqlite: Database.Database): TableInfo[] {
+  const tables = sqlite
+    .prepare(
+      `SELECT name FROM sqlite_master
+       WHERE type = 'table'
+         AND name NOT LIKE 'sqlite_%'
+         AND name NOT LIKE '_litestream_%'
+       ORDER BY name`,
+    )
+    .all() as { name: string }[];
+
+  return tables.map((t) => ({
+    name: t.name,
+    rowCount: (
+      sqlite.prepare(`SELECT COUNT(*) AS cnt FROM "${t.name}"`).get() as {
+        cnt: number;
+      }
+    ).cnt,
+  }));
+}
+
+/**
+ * OperationResult wrapper for CLI/API consumption.
+ * Matches the interface of the Postgres dbListTables().
+ */
+export function dbListTables(sqlite: Database.Database): OperationResult {
+  const rows = listTables(sqlite);
+
+  if (rows.length === 0) {
+    return { ok: true, data: [], meta: { message: "No tables found." } };
+  }
+
+  // Map to the same shape as the Postgres version (table_name, row_count)
+  return {
+    ok: true,
+    data: rows.map((r) => ({ table_name: r.name, row_count: r.rowCount })),
+  };
+}

package/src/introspect/sqlite/query.ts

@@ -0,0 +1,49 @@
+// ============================================================================
+// SQLite SQL Proxy — read-only query execution
+// ============================================================================
+//
+// SQLite equivalent of the Postgres query.ts. Same safety checks
+// (requireSelect, rejectDangerousSQL) applied before execution.
+//
+// Key difference: SQLite's LIMIT wrapping uses a bare subquery without
+// the AS alias (SQLite doesn't require subquery aliases).
+
+import type Database from "better-sqlite3";
+import type { OperationResult } from "../types.js";
+import { requireSelect, rejectDangerousSQL } from "../sql-safety.js";
+
+/**
+ * Run a read-only SQL query against the SQLite database.
+ * Only SELECT and WITH (CTE) queries are allowed.
+ *
+ * When limit is specified, wraps the query in a subquery with LIMIT
+ * so the database handles row capping efficiently.
+ */
+export function dbQuery(
+  sqlite: Database.Database,
+  rawSql: string,
+  limit?: number,
+): OperationResult {
+  requireSelect(rawSql);
+  rejectDangerousSQL(rawSql);
+
+  let effectiveSql = rawSql;
+  if (limit !== undefined) {
+    effectiveSql = `SELECT * FROM (${rawSql}) LIMIT ${limit}`;
+  }
+
+  const rows = sqlite.prepare(effectiveSql).all() as Record<
+    string,
+    unknown
+  >[];
+  const truncated = limit !== undefined && rows.length >= limit;
+
+  return {
+    ok: true,
+    data: rows,
+    meta: {
+      rowCount: rows.length,
+      ...(truncated && { truncated: true, limit }),
+    },
+  };
+}

package/src/introspect/sqlite/sample.ts

@@ -0,0 +1,50 @@
+// ============================================================================
+// SQLite Sample Rows — fetch sample data from a table
+// ============================================================================
+//
+// Same safety checks as the Postgres version: validates table and column
+// names via isSafeIdentifier() before interpolating into SQL.
+
+import type Database from "better-sqlite3";
+import type { OperationResult } from "../types.js";
+import { validateTableName, validateColumnNames } from "../sql-safety.js";
+
+/**
+ * Return sample rows from a table, optionally selecting specific columns.
+ *
+ * Table and column names are validated against SQL injection via
+ * isSafeIdentifier() before being interpolated into the query string.
+ * The limit is passed as a query parameter (not interpolated).
+ */
+export function dbSample(
+  sqlite: Database.Database,
+  tableName: string,
+  limit: number = 5,
+  fields?: string[],
+): OperationResult {
+  validateTableName(tableName);
+
+  let selectClause = "*";
+  if (fields && fields.length > 0) {
+    validateColumnNames(fields);
+    selectClause = fields.map((f) => `"${f}"`).join(", ");
+  }
+
+  const rows = sqlite
+    .prepare(`SELECT ${selectClause} FROM "${tableName}" ORDER BY id LIMIT ?`)
+    .all(limit) as Record<string, unknown>[];
+
+  if (rows.length === 0) {
+    return {
+      ok: true,
+      data: [],
+      meta: { message: `Table '${tableName}' is empty.` },
+    };
+  }
+
+  return {
+    ok: true,
+    data: rows,
+    meta: { rowCount: rows.length, limit },
+  };
+}

package/src/introspect/table-rename.test.ts

@@ -0,0 +1,235 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { tableRename } from "./table-rename.js";
+import type { SqlClient } from "./types.js";
+
+/**
+ * Convert Postgres-style $1, $2 placeholders to SQLite ? placeholders.
+ */
+function pgToSqliteParams(query: string): string {
+  return query.replace(/\$\d+/g, "?");
+}
+
+function createTestSql(sqlite: Database.Database): SqlClient {
+  function makeSql(db: Database.Database): SqlClient {
+    return {
+      unsafe: async (query: string, params?: any[]) => {
+        const converted = pgToSqliteParams(query);
+        const stmt = db.prepare(converted);
+        const trimmed = converted.trim().toUpperCase();
+        if (
+          trimmed.startsWith("SELECT") ||
+          trimmed.startsWith("WITH") ||
+          trimmed.startsWith("INSERT") && converted.toUpperCase().includes("RETURNING")
+        ) {
+          return stmt.all(...(params ?? [])) as any[];
+        }
+        stmt.run(...(params ?? []));
+        return [] as any[];
+      },
+      begin: async (fn) => {
+        // We can't use db.transaction() with async functions directly.
+        // Instead, manually manage BEGIN/COMMIT/ROLLBACK.
+        db.exec("BEGIN");
+        try {
+          const result = await fn(makeSql(db));
+          db.exec("COMMIT");
+          return result;
+        } catch (err) {
+          db.exec("ROLLBACK");
+          throw err;
+        }
+      },
+      end: async () => {},
+    };
+  }
+  return makeSql(sqlite);
+}
+
+describe("table rename", () => {
+  let sqlite: Database.Database;
+  let sql: SqlClient;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+    sql = createTestSql(sqlite);
+
+    // Create metadata tables
+    sqlite.exec(`
+      CREATE TABLE _sapporta_tables (
+        name            TEXT PRIMARY KEY,
+        label           TEXT,
+        display_column  TEXT,
+        immutable       INTEGER NOT NULL DEFAULT 0,
+        inferred        INTEGER NOT NULL DEFAULT 0,
+        position        INTEGER NOT NULL DEFAULT 0,
+        created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at      TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `);
+    sqlite.exec(`
+      CREATE TABLE _sapporta_columns (
+        table_name      TEXT NOT NULL REFERENCES _sapporta_tables(name) ON DELETE CASCADE,
+        column_name     TEXT NOT NULL,
+        column_type     TEXT NOT NULL DEFAULT 'text',
+        position        INTEGER NOT NULL DEFAULT 0,
+        not_null        INTEGER NOT NULL DEFAULT 0,
+        is_unique       INTEGER NOT NULL DEFAULT 0,
+        default_value   TEXT,
+        references_table TEXT,
+        select_options  TEXT,
+        ui_hints        TEXT NOT NULL DEFAULT '{}',
+        PRIMARY KEY (table_name, column_name)
+      )
+    `);
+
+    // Create a UI-managed table
+    sqlite.exec(`
+      CREATE TABLE untitled_1 (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT,
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now'))
+      )
+    `);
+    sqlite.exec(`
+      INSERT INTO _sapporta_tables (name, label) VALUES ('untitled_1', 'Untitled 1')
+    `);
+    sqlite.exec(`
+      INSERT INTO _sapporta_columns (table_name, column_name, column_type, position)
+      VALUES ('untitled_1', 'name', 'text', 1)
+    `);
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("renames table + metadata atomically", async () => {
+    const result = await tableRename(sql, "untitled_1", "targets");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data[0]).toEqual({
+      old_name: "untitled_1",
+      new_name: "targets",
+      label: "Targets",
+    });
+
+    // Table was renamed
+    const tables = sqlite
+      .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'targets'`)
+      .all();
+    expect(tables).toHaveLength(1);
+
+    // Old table is gone
+    const oldTables = sqlite
+      .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'untitled_1'`)
+      .all();
+    expect(oldTables).toHaveLength(0);
+
+    // Metadata updated
+    const meta = sqlite
+      .prepare(`SELECT name, label FROM _sapporta_tables WHERE name = 'targets'`)
+      .all() as any[];
+    expect(meta).toHaveLength(1);
+    expect(meta[0].label).toBe("Targets");
+
+    // Old metadata gone
+    const oldMeta = sqlite
+      .prepare(`SELECT name FROM _sapporta_tables WHERE name = 'untitled_1'`)
+      .all();
+    expect(oldMeta).toHaveLength(0);
+  });
+
+  it("updates _sapporta_columns.table_name", async () => {
+    await tableRename(sql, "untitled_1", "targets");
+
+    const cols = sqlite
+      .prepare(`SELECT table_name, column_name FROM _sapporta_columns WHERE table_name = 'targets'`)
+      .all() as any[];
+    expect(cols).toHaveLength(1);
+    expect(cols[0].column_name).toBe("name");
+
+    // No columns left for old name
+    const oldCols = sqlite
+      .prepare(`SELECT * FROM _sapporta_columns WHERE table_name = 'untitled_1'`)
+      .all();
+    expect(oldCols).toHaveLength(0);
+  });
+
+  it("updates _sapporta_columns.references_table for FK columns pointing to renamed table", async () => {
+    // Create another table that references untitled_1
+    sqlite.exec(`
+      CREATE TABLE tasks (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        target_id INTEGER,
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now'))
+      )
+    `);
+    sqlite.exec(`
+      INSERT INTO _sapporta_tables (name, label) VALUES ('tasks', 'Tasks')
+    `);
+    sqlite.exec(`
+      INSERT INTO _sapporta_columns (table_name, column_name, column_type, references_table, position)
+      VALUES ('tasks', 'target_id', 'link', 'untitled_1', 1)
+    `);
+
+    await tableRename(sql, "untitled_1", "targets");
+
+    // FK reference should now point to 'targets'
+    const fk = sqlite
+      .prepare(`SELECT references_table FROM _sapporta_columns WHERE table_name = 'tasks' AND column_name = 'target_id'`)
+      .all() as any[];
+    expect(fk[0].references_table).toBe("targets");
+  });
+
+  it("rejects non-existent table", async () => {
+    await expect(tableRename(sql, "no_such_table", "targets")).rejects.toThrow(
+      "not found in _sapporta_tables",
+    );
+  });
+
+  it("rejects rename to name that already exists", async () => {
+    // Create a second table
+    sqlite.exec(`
+      CREATE TABLE other_table (id INTEGER PRIMARY KEY AUTOINCREMENT)
+    `);
+    sqlite.exec(`
+      INSERT INTO _sapporta_tables (name, label) VALUES ('other_table', 'Other')
+    `);
+
+    await expect(tableRename(sql, "untitled_1", "other_table")).rejects.toThrow(
+      "already exists",
+    );
+  });
+
+  it("default label is title-cased from newName", async () => {
+    const result = await tableRename(sql, "untitled_1", "sales_targets");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data[0].label).toBe("Sales Targets");
+  });
+
+  it("uses custom label when provided", async () => {
+    const result = await tableRename(sql, "untitled_1", "targets", "My Targets");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data[0].label).toBe("My Targets");
+
+    const meta = sqlite
+      .prepare(`SELECT label FROM _sapporta_tables WHERE name = 'targets'`)
+      .all() as any[];
+    expect(meta[0].label).toBe("My Targets");
+  });
+
+  it("rejects same name", async () => {
+    await expect(tableRename(sql, "untitled_1", "untitled_1")).rejects.toThrow(
+      "same",
+    );
+  });
+});