@sapporta/server 0.0.1

package/src/introspect/indexes.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { dbIndexes } from "./indexes.js";
+
+describe("db indexes", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("shows custom indexes", () => {
+    sqlite.exec(`
+      CREATE TABLE accounts (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL);
+      CREATE UNIQUE INDEX idx_accounts_name ON accounts(name);
+    `);
+
+    const result = dbIndexes(sqlite, "accounts");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const indexNames = result.data.map((r) => r.index_name);
+    expect(indexNames).toContain("idx_accounts_name");
+  });
+
+  it("shows message when no indexes", () => {
+    const result = dbIndexes(sqlite, "nonexistent");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(0);
+    expect(result.meta?.message).toBe(
+      "No indexes found for table 'nonexistent'.",
+    );
+  });
+});

package/src/introspect/indexes.ts

@@ -0,0 +1,95 @@
+// ============================================================================
+// SQLite Index Listing — index metadata via PRAGMA index_list / index_info
+// ============================================================================
+//
+// Uses two PRAGMAs:
+//   - index_list("table") → list of indexes with uniqueness flag and origin
+//   - 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.
+ */
+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 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/inference.ts

@@ -0,0 +1,98 @@
+/**
+ * LLM Inference — infer table and column metadata from sample data.
+ *
+ * Uses Claude (via nuabase gateway) to analyze the first row of a newly
+ * created table and suggest meaningful column names, types, and a table
+ * label. This runs once per table after the first row is committed.
+ */
+import { Nua, z } from "nuabase";
+import { logger } from "../db/logger.js";
+
+const log = logger.child({ module: "inference" });
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface InferenceInput {
+  columns: string[];
+  rows: Record<string, unknown>[];
+}
+
+export interface InferredColumn {
+  name: string;
+  header: string;
+  type: string;
+}
+
+export interface InferenceResult {
+  table_label: string;
+  columns: Record<string, InferredColumn>;
+}
+
+// ─── Output Schema ──────────────────────────────────────────────────────────
+
+const InferredColumnSchema = z.object({
+  name: z.string(),
+  header: z.string(),
+  type: z.enum([
+    "text", "integer", "numeric", "boolean", "date", "timestamp",
+    "select", "currency", "percentage", "email", "url",
+  ]),
+});
+
+const InferenceResultSchema = z.object({
+  table_label: z.string(),
+  columns: z.record(z.string(), InferredColumnSchema),
+});
+
+// ─── Prompt ──────────────────────────────────────────────────────────────────
+
+function buildPrompt(input: InferenceInput): string {
+  return `You are analyzing data entered into a spreadsheet. Based on the column names and sample data, infer:
+1. A descriptive table label (like "Contacts", "Products", "Invoices")
+2. For each column that has data, suggest a better column name (snake_case), a display header (Title Case), and a data type.
+
+Available data types: text, integer, numeric, boolean, date, timestamp, email, url, currency, percentage
+
+Input columns: ${JSON.stringify(input.columns)}
+Sample data: ${JSON.stringify(input.rows)}
+
+Rules:
+- Only include columns that have non-null, non-empty data in the output.
+- Column names must be snake_case, lowercase, no spaces.
+- If data looks like an email address (contains @), use type "email".
+- If data looks like a URL (starts with http:// or https://), use type "url".
+- If data is a number with decimals or currency symbol, use "numeric" or "currency".
+- If data is a whole number, use "integer".
+- If data looks like a date (YYYY-MM-DD or similar), use "date".
+- If data is "true"/"false"/"yes"/"no", use "boolean".
+- Default to "text" if unsure.`;
+}
+
+// ─── Inference Function ──────────────────────────────────────────────────────
+
+/**
+ * Call the LLM to infer table metadata from sample data.
+ *
+ * Uses NUABASE_API_KEY from environment. Returns null if the inference
+ * fails or returns no columns.
+ */
+export async function inferSchema(input: InferenceInput): Promise<InferenceResult | null> {
+  const nua = Nua.gateway({});
+
+  const result = await nua.get(buildPrompt(input), {
+    model: "claude-haiku-4-5-20251001",
+    output: { name: "inference", schema: InferenceResultSchema },
+  });
+
+  if (!result.success) {
+    log.warn("Inference failed", { error: result.error });
+    return null;
+  }
+
+  if (Object.keys(result.data.columns).length === 0) {
+    log.warn("Inference returned no columns");
+    return null;
+  }
+
+  return result.data;
+}

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

@@ -0,0 +1,40 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { dbListTables } from "./list-tables.js";
+
+describe("db list-tables", () => {
+  let sqlite: Database.Database;
+
+  beforeEach(() => {
+    sqlite = new Database(":memory:");
+    sqlite.pragma("foreign_keys = ON");
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("lists tables in the database", () => {
+    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 = dbListTables(sqlite);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const tableNames = result.data.map((r) => r.table_name);
+    expect(tableNames).toContain("accounts");
+    expect(tableNames).toContain("invoices");
+  });
+
+  it("shows message when no tables exist", () => {
+    const result = dbListTables(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/list-tables.ts

@@ -0,0 +1,62 @@
+// ============================================================================
+// SQLite Table Listing — enumerate user tables with row counts
+// ============================================================================
+//
+// Uses sqlite_master for table enumeration and SELECT COUNT(*) for exact
+// row counts. Exact counts are fine for SQLite's dataset sizes — if this
+// ever becomes a bottleneck, we can switch to a stat table or sampling.
+//
+// Excludes internal tables:
+//   - sqlite_* (sqlite_sequence, sqlite_stat1, etc.)
+//   - _litestream_* (Litestream replication metadata)
+
+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.
+ *
+ * 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.
+ */
+export function dbListTables(sqlite: Database.Database): OperationResult {
+  const rows = listTables(sqlite);
+
+  if (rows.length === 0) {
+    return { ok: true, data: [], meta: { message: "No tables found." } };
+  }
+
+  return {
+    ok: true,
+    data: rows.map((r) => ({ table_name: r.name, row_count: r.rowCount })),
+  };
+}

package/src/introspect/query.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { dbQuery } from "./query.js";
+
+describe("db query", () => {
+  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);
+      INSERT INTO accounts (name, type) VALUES ('Cash', 'asset'), ('Revenue', 'revenue');
+    `);
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("runs a SELECT query and returns results", () => {
+    const result = dbQuery(sqlite, "SELECT id, name FROM accounts ORDER BY id");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(2);
+    expect(result.data[0].name).toBe("Cash");
+    expect(result.data[1].name).toBe("Revenue");
+    expect(result.meta?.rowCount).toBe(2);
+  });
+
+  it("returns empty data for no results", () => {
+    const result = dbQuery(sqlite, "SELECT * FROM accounts WHERE id = 999");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(0);
+    expect(result.meta?.rowCount).toBe(0);
+  });
+
+  it("rejects non-SELECT queries", () => {
+    expect(() =>
+      dbQuery(sqlite, "INSERT INTO accounts (name, type) VALUES ('x', 'y')"),
+    ).toThrow("Only SELECT");
+  });
+
+  it("allows WITH (CTE) queries", () => {
+    const result = dbQuery(
+      sqlite,
+      "WITH cte AS (SELECT * FROM accounts) SELECT * FROM cte",
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data.length).toBeGreaterThan(0);
+    expect(result.data[0].name).toBe("Cash");
+  });
+
+  it("respects limit parameter", () => {
+    const result = dbQuery(sqlite, "SELECT * FROM accounts ORDER BY id", 1);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(1);
+    expect(result.meta?.truncated).toBe(true);
+    expect(result.meta?.limit).toBe(1);
+  });
+
+  it("does not set truncated when under limit", () => {
+    const result = dbQuery(sqlite, "SELECT * FROM accounts ORDER BY id", 10);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(2);
+    expect(result.meta?.truncated).toBeUndefined();
+  });
+});

package/src/introspect/query.ts

@@ -0,0 +1,47 @@
+// ============================================================================
+// SQLite SQL Proxy — read-only query execution
+// ============================================================================
+//
+// Same safety checks (requireSelect, rejectDangerousSQL) applied before
+// execution. 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/sample.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { dbSample } from "./sample.js";
+
+describe("db sample", () => {
+  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);
+      INSERT INTO accounts (name) VALUES ('A'), ('B'), ('C'), ('D'), ('E'), ('F');
+    `);
+  });
+
+  afterEach(() => {
+    sqlite.close();
+  });
+
+  it("shows sample rows with default limit", () => {
+    const result = dbSample(sqlite, "accounts");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(5);
+    expect(result.meta?.rowCount).toBe(5);
+    expect(result.meta?.limit).toBe(5);
+  });
+
+  it("respects custom limit", () => {
+    const result = dbSample(sqlite, "accounts", 2);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(2);
+    expect(result.meta?.rowCount).toBe(2);
+    expect(result.meta?.limit).toBe(2);
+  });
+
+  it("shows empty message for empty table", () => {
+    sqlite.exec("DELETE FROM accounts");
+
+    const result = dbSample(sqlite, "accounts");
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(0);
+    expect(result.meta?.message).toBe("Table 'accounts' is empty.");
+  });
+
+  it("rejects invalid table names", () => {
+    expect(() => dbSample(sqlite, "'; DROP TABLE accounts; --")).toThrow(
+      "Invalid table name",
+    );
+  });
+
+  it("selects specific fields with --fields", () => {
+    const result = dbSample(sqlite, "accounts", 5, ["name"]);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data).toHaveLength(5);
+    // Should only have the 'name' column (plus id from ORDER BY isn't added)
+    expect(Object.keys(result.data[0])).toEqual(["name"]);
+  });
+});

package/src/introspect/sample.ts

@@ -0,0 +1,50 @@
+// ============================================================================
+// SQLite Sample Rows — fetch sample data from a table
+// ============================================================================
+//
+// Same safety checks as the old 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/sql-safety.ts

@@ -0,0 +1,76 @@
+import { OperationError, ErrorCode } from "./types.js";
+import { isSafeIdentifier } from "../data/sanitize.js";
+import { rejectControlChars as coreRejectControlChars } from "../data/sanitize.js";
+
+/**
+ * Reject SQL that isn't a SELECT or WITH (CTE) statement.
+ * Throws if the query would mutate data.
+ */
+export function requireSelect(sql: string): void {
+  const trimmed = sql.trim().toUpperCase();
+  if (!trimmed.startsWith("SELECT") && !trimmed.startsWith("WITH")) {
+    throw new OperationError("Only SELECT and WITH (CTE) queries are allowed", ErrorCode.SELECT_ONLY);
+  }
+}
+
+/**
+ * Reject dangerous SQL statements that could destroy data or structure.
+ */
+export function rejectDangerousSQL(sql: string): void {
+  const trimmed = sql.trim().toUpperCase();
+  const dangerous = [
+    "DROP DATABASE",
+    "TRUNCATE",
+    "DROP SCHEMA",
+  ];
+
+  for (const pattern of dangerous) {
+    if (trimmed.includes(pattern)) {
+      throw new OperationError(`Dangerous SQL rejected: contains ${pattern}`, ErrorCode.DANGEROUS_SQL);
+    }
+  }
+}
+
+/**
+ * Validate that a table name is a safe SQL identifier.
+ * Rejects names containing special characters that could enable SQL injection.
+ */
+export function validateTableName(name: string): void {
+  if (!isSafeIdentifier(name)) {
+    throw new OperationError(
+      `Invalid table name: ${name}`,
+      ErrorCode.INVALID_TABLE_NAME,
+    );
+  }
+}
+
+/**
+ * Validate that all column names in a list are safe identifiers.
+ * Prevents SQL injection via hallucinated column names containing
+ * special characters like `;`, `?`, `'`, etc.
+ */
+export function validateColumnNames(columns: string[]): void {
+  for (const col of columns) {
+    if (!isSafeIdentifier(col)) {
+      throw new OperationError(
+        `Invalid column name: ${col}`,
+        ErrorCode.INVALID_COLUMN_NAME,
+      );
+    }
+  }
+}
+
+/**
+ * Reject JSON strings containing control characters.
+ * Delegates to core sanitize, wraps in OperationError for error envelope.
+ */
+export function rejectControlChars(text: string): void {
+  try {
+    coreRejectControlChars(text);
+  } catch {
+    throw new OperationError(
+      "Input contains control characters",
+      ErrorCode.INVALID_JSON,
+    );
+  }
+}