agnes-cli 0.0.1

package/src/config.ts

@@ -0,0 +1,73 @@
+import { resolve } from "node:path";
+import type { Dialect } from "./dialect";
+import type { DslSchema } from "./ir";
+
+export interface CacheConfig {
+  enabled: boolean;
+  walPath?: string;
+  compactionThreshold?: number;
+}
+
+export interface AgnesConfig {
+  /** Target database dialect. */
+  driver: Dialect;
+  /** Connection URL, e.g. postgres://user:pass@host/db or sqlite://./dev.db */
+  url: string;
+  /** The schema object exported from your schema.ts (`export const schema = {...}`). */
+  schema: DslSchema;
+  /** Where `pull` writes the generated schema (default: ./schema.ts). */
+  out?: string;
+  /** Directory for versioned migration files (default: ./migrations). */
+  migrationsDir?: string;
+  maxConnections?: number;
+  /** Cache config baked into the client generated by `agnes generate`. */
+  cache?: CacheConfig;
+  /**
+   * Output path for `agnes generate` — the pre-wired AgnesClient module.
+   * Extension decides the language: `.ts` or `.js`. Nested dirs are created.
+   * e.g. "src/services/db.ts" or "db.js".
+   */
+  output?: string;
+  /**
+   * Module that exports `schema`, imported by the generated client.
+   * Default: `out` (the pull target) or "./schema". A filesystem path
+   * (e.g. "./schema.ts") — the generated import is made relative automatically.
+   */
+  schemaPath?: string;
+}
+
+/** Identity helper for type-checked config files. */
+export function defineConfig(config: AgnesConfig): AgnesConfig {
+  return config;
+}
+
+const CANDIDATES = ["agnes.config.ts", "agnes.config.js", "agnes.config.mjs"];
+
+/** Load and validate the config file (explicit path or auto-discovered). */
+export async function loadConfig(explicitPath?: string): Promise<AgnesConfig> {
+  let path: string | undefined;
+  if (explicitPath) {
+    path = resolve(process.cwd(), explicitPath);
+  } else {
+    for (const c of CANDIDATES) {
+      const p = resolve(process.cwd(), c);
+      if (await Bun.file(p).exists()) {
+        path = p;
+        break;
+      }
+    }
+  }
+  if (!path) {
+    throw new Error(
+      `No config found. Create agnes.config.ts (see agnes-cli README) or pass --config <path>.`,
+    );
+  }
+
+  const mod = (await import(path)) as { default?: AgnesConfig } & Partial<AgnesConfig>;
+  const config = mod.default ?? (mod as AgnesConfig);
+
+  if (!config?.driver || !config.url || !config.schema) {
+    throw new Error(`Config at ${path} must export { driver, url, schema }.`);
+  }
+  return config;
+}

package/src/db.ts

@@ -0,0 +1,26 @@
+// Opens a database connection via agnes-library's AgnesClient (Rust bridge)
+// and exposes the query/mutate surface the CLI needs.
+import { AgnesClient } from "agnes-library";
+import type { AgnesConfig } from "./config";
+import type { QueryClient } from "./introspect";
+
+export interface CliDb extends QueryClient {
+  mutate(sql: string, params?: unknown[]): Promise<number>;
+}
+
+export async function openDb(config: AgnesConfig): Promise<CliDb> {
+  const client = await AgnesClient.create(
+    {
+      driver: config.driver,
+      url: config.url,
+      maxConnections: config.maxConnections,
+    },
+    config.schema as never,
+  );
+
+  return {
+    query: <T = Record<string, unknown>>(sql: string, params?: unknown[]) =>
+      client.query<T>(sql, params, { bypassCache: true }),
+    mutate: (sql: string, params?: unknown[]) => client.mutate(sql, params),
+  };
+}

package/src/dialect.ts

@@ -0,0 +1,67 @@
+import type { ColumnType } from "./ir";
+
+export type Dialect = "postgres" | "mysql" | "sqlite";
+
+// Logical type → physical column type per dialect.
+const TYPE_MAP: Record<Dialect, Record<ColumnType, string>> = {
+  postgres: {
+    int: "integer",
+    bigint: "bigint",
+    text: "text",
+    bool: "boolean",
+    float: "double precision",
+    bytes: "bytea",
+    json: "jsonb",
+  },
+  mysql: {
+    int: "int",
+    bigint: "bigint",
+    text: "text",
+    bool: "tinyint(1)",
+    float: "double",
+    bytes: "blob",
+    json: "json",
+  },
+  sqlite: {
+    int: "integer",
+    bigint: "integer",
+    text: "text",
+    bool: "integer",
+    float: "real",
+    bytes: "blob",
+    json: "text",
+  },
+};
+
+export function physicalType(dialect: Dialect, type: ColumnType): string {
+  return TYPE_MAP[dialect][type];
+}
+
+/** Reverse-map a raw DB type name back to a logical ColumnType (best effort). */
+export function logicalType(raw: string): ColumnType {
+  const t = raw.toLowerCase();
+  if (t.includes("bigint")) return "bigint";
+  if (t.includes("int")) return "int"; // tinyint/smallint/int/integer
+  if (t.includes("bool")) return "bool";
+  if (t.includes("double") || t.includes("real") || t.includes("float") || t.includes("numeric") || t.includes("decimal"))
+    return "float";
+  if (t.includes("json")) return "json";
+  if (t.includes("blob") || t.includes("bytea") || t.includes("binary")) return "bytes";
+  return "text"; // text/varchar/char/uuid/timestamp/etc. collapse to text
+}
+
+export function ident(dialect: Dialect, name: string): string {
+  return dialect === "mysql" ? `\`${name}\`` : `"${name}"`;
+}
+
+/** Render a default value as a SQL literal. */
+export function defaultLiteral(dialect: Dialect, value: unknown): string {
+  if (value === null) return "NULL";
+  if (typeof value === "boolean") {
+    if (dialect === "postgres") return value ? "TRUE" : "FALSE";
+    return value ? "1" : "0";
+  }
+  if (typeof value === "number" || typeof value === "bigint") return String(value);
+  // Strings / everything else → single-quoted, escaped.
+  return `'${String(value).replace(/'/g, "''")}'`;
+}

package/src/diff.ts

@@ -0,0 +1,131 @@
+import type { ColumnIR, DatabaseIR, ForeignKeyIR, IndexIR, TableIR } from "./ir";
+
+// A single schema-change operation. `destructive` ops delete data or objects
+// and require confirmation before execution.
+export type Operation =
+  | { kind: "createTable"; table: TableIR }
+  | { kind: "dropTable"; table: string; destructive: true }
+  | { kind: "addColumn"; table: string; column: ColumnIR }
+  | { kind: "dropColumn"; table: string; column: string; destructive: true }
+  | { kind: "alterColumn"; table: string; from: ColumnIR; to: ColumnIR }
+  | { kind: "createIndex"; table: string; index: IndexIR }
+  | { kind: "dropIndex"; table: string; index: string }
+  | { kind: "addForeignKey"; table: string; fk: ForeignKeyIR }
+  | { kind: "dropForeignKey"; table: string; fk: string };
+
+export function isDestructive(op: Operation): boolean {
+  return op.kind === "dropTable" || op.kind === "dropColumn";
+}
+
+function byName<T extends { name: string }>(items: T[]): Map<string, T> {
+  return new Map(items.map((i) => [i.name, i]));
+}
+
+function columnChanged(a: ColumnIR, b: ColumnIR): boolean {
+  return a.type !== b.type || a.nullable !== b.nullable || a.primary !== b.primary;
+}
+
+/**
+ * Diff `desired` (from schema.ts) against `current` (from the DB).
+ * Returns ordered operations: creates first, then column/index/fk changes,
+ * then drops last (so dependents go before the tables they reference).
+ */
+export function diffSchemas(desired: DatabaseIR, current: DatabaseIR): Operation[] {
+  const creates: Operation[] = [];
+  const alters: Operation[] = [];
+  const drops: Operation[] = [];
+
+  // Tables present in desired.
+  for (const tableName in desired) {
+    const want = desired[tableName]!;
+    const have = current[tableName];
+
+    if (!have) {
+      creates.push({ kind: "createTable", table: want });
+      continue;
+    }
+
+    const wantCols = byName(want.columns);
+    const haveCols = byName(have.columns);
+
+    for (const [name, col] of wantCols) {
+      const existing = haveCols.get(name);
+      if (!existing) alters.push({ kind: "addColumn", table: tableName, column: col });
+      else if (columnChanged(existing, col))
+        alters.push({ kind: "alterColumn", table: tableName, from: existing, to: col });
+    }
+    for (const [name] of haveCols) {
+      if (!wantCols.has(name))
+        drops.push({ kind: "dropColumn", table: tableName, column: name, destructive: true });
+    }
+
+    // Indexes.
+    const wantIdx = byName(want.indexes);
+    const haveIdx = byName(have.indexes);
+    for (const [name, idx] of wantIdx) {
+      const existing = haveIdx.get(name);
+      if (!existing) alters.push({ kind: "createIndex", table: tableName, index: idx });
+      else if (existing.unique !== idx.unique || existing.columns.join() !== idx.columns.join()) {
+        alters.push({ kind: "dropIndex", table: tableName, index: name });
+        alters.push({ kind: "createIndex", table: tableName, index: idx });
+      }
+    }
+    for (const [name] of haveIdx) {
+      if (!wantIdx.has(name)) alters.push({ kind: "dropIndex", table: tableName, index: name });
+    }
+
+    // Foreign keys.
+    const wantFk = byName(want.foreignKeys);
+    const haveFk = byName(have.foreignKeys);
+    for (const [name, fk] of wantFk) {
+      if (!haveFk.has(name)) alters.push({ kind: "addForeignKey", table: tableName, fk });
+    }
+    for (const [name] of haveFk) {
+      if (!wantFk.has(name)) alters.push({ kind: "dropForeignKey", table: tableName, fk: name });
+    }
+  }
+
+  // Tables present only in the DB → drop (full sync).
+  for (const tableName in current) {
+    if (!desired[tableName]) drops.push({ kind: "dropTable", table: tableName, destructive: true });
+  }
+
+  // Order creates so referenced tables come first; drops in the reverse order
+  // (dependents before the tables they reference) to respect FK constraints.
+  const createOrder = topoSort(desired);
+  creates.sort((a, b) => {
+    const an = a.kind === "createTable" ? a.table.name : "";
+    const bn = b.kind === "createTable" ? b.table.name : "";
+    return (createOrder.get(an) ?? 0) - (createOrder.get(bn) ?? 0);
+  });
+  const dropOrder = topoSort(current);
+  drops.sort((a, b) => {
+    const an = a.kind === "dropTable" ? a.table : "";
+    const bn = b.kind === "dropTable" ? b.table : "";
+    return (dropOrder.get(bn) ?? 0) - (dropOrder.get(an) ?? 0);
+  });
+
+  return [...creates, ...alters, ...drops];
+}
+
+/** Assign each table a rank so that a table always ranks after tables it references. */
+function topoSort(ir: DatabaseIR): Map<string, number> {
+  const rank = new Map<string, number>();
+  const visiting = new Set<string>();
+
+  const visit = (name: string): number => {
+    if (rank.has(name)) return rank.get(name)!;
+    if (visiting.has(name)) return 0; // cycle guard
+    visiting.add(name);
+    let r = 0;
+    for (const fk of ir[name]?.foreignKeys ?? []) {
+      if (fk.refTable !== name && ir[fk.refTable]) r = Math.max(r, visit(fk.refTable) + 1);
+    }
+    visiting.delete(name);
+    rank.set(name, r);
+    return r;
+  };
+
+  for (const name in ir) visit(name);
+  return rank;
+}

package/src/generate.ts

@@ -0,0 +1,137 @@
+import { defaultLiteral, ident, physicalType, type Dialect } from "./dialect";
+import type { ColumnIR, ForeignKeyIR, TableIR } from "./ir";
+import type { Operation } from "./diff";
+
+function columnDef(dialect: Dialect, col: ColumnIR): string {
+  let s = `${ident(dialect, col.name)} ${physicalType(dialect, col.type)}`;
+  if (col.primary) s += " PRIMARY KEY";
+  if (!col.nullable && !col.primary) s += " NOT NULL";
+  if (col.default !== undefined) s += ` DEFAULT ${defaultLiteral(dialect, col.default)}`;
+  return s;
+}
+
+function fkClause(dialect: Dialect, fk: ForeignKeyIR): string {
+  return (
+    `CONSTRAINT ${ident(dialect, fk.name)} FOREIGN KEY (${ident(dialect, fk.column)}) ` +
+    `REFERENCES ${ident(dialect, fk.refTable)} (${ident(dialect, fk.refColumn)}) ` +
+    `ON UPDATE ${fk.onUpdate} ON DELETE ${fk.onDelete}`
+  );
+}
+
+function createTable(dialect: Dialect, t: TableIR): string {
+  const lines = t.columns.map((c) => `  ${columnDef(dialect, c)}`);
+  // SQLite can only declare FKs inline at table-create time.
+  if (dialect === "sqlite") {
+    for (const fk of t.foreignKeys) lines.push(`  ${fkClause(dialect, fk)}`);
+  }
+  return `CREATE TABLE ${ident(dialect, t.name)} (\n${lines.join(",\n")}\n);`;
+}
+
+function createIndex(dialect: Dialect, table: string, name: string, cols: string[], unique: boolean): string {
+  const u = unique ? "UNIQUE " : "";
+  const colList = cols.map((c) => ident(dialect, c)).join(", ");
+  return `CREATE ${u}INDEX ${ident(dialect, name)} ON ${ident(dialect, table)} (${colList});`;
+}
+
+/**
+ * Render one operation into zero or more SQL statements for `dialect`.
+ * Emits `-- SKIPPED` comments for operations a dialect can't express (e.g.
+ * SQLite ALTER limitations) instead of producing invalid SQL.
+ */
+export function renderOperation(dialect: Dialect, op: Operation): string[] {
+  const t = (name: string) => ident(dialect, name);
+
+  switch (op.kind) {
+    case "createTable": {
+      const out = [createTable(dialect, op.table)];
+      for (const idx of op.table.indexes)
+        out.push(createIndex(dialect, op.table.name, idx.name, idx.columns, idx.unique));
+      // Non-SQLite: add FKs after create (SQLite already inlined them).
+      if (dialect !== "sqlite")
+        for (const fk of op.table.foreignKeys)
+          out.push(`ALTER TABLE ${t(op.table.name)} ADD ${fkClause(dialect, fk)};`);
+      return out;
+    }
+
+    case "dropTable":
+      return [`DROP TABLE ${t(op.table)};`];
+
+    case "addColumn":
+      return [`ALTER TABLE ${t(op.table)} ADD COLUMN ${columnDef(dialect, op.column)};`];
+
+    case "dropColumn":
+      return [`ALTER TABLE ${t(op.table)} DROP COLUMN ${t(op.column)};`];
+
+    case "alterColumn": {
+      if (dialect === "sqlite")
+        return [`-- SKIPPED: SQLite cannot ALTER column ${op.table}.${op.to.name}; recreate the table manually.`];
+      if (dialect === "postgres") {
+        const col = t(op.to.name);
+        const type = physicalType(dialect, op.to.type);
+        const out = [
+          `ALTER TABLE ${t(op.table)} ALTER COLUMN ${col} TYPE ${type} USING ${col}::${type};`,
+        ];
+        out.push(
+          `ALTER TABLE ${t(op.table)} ALTER COLUMN ${col} ${op.to.nullable ? "DROP NOT NULL" : "SET NOT NULL"};`,
+        );
+        return out;
+      }
+      // mysql
+      const nullSql = op.to.nullable ? "NULL" : "NOT NULL";
+      return [
+        `ALTER TABLE ${t(op.table)} MODIFY COLUMN ${columnDef(dialect, op.to).replace(/ PRIMARY KEY/, "")} ${op.to.primary ? "" : nullSql};`,
+      ];
+    }
+
+    case "createIndex":
+      return [createIndex(dialect, op.table, op.index.name, op.index.columns, op.index.unique)];
+
+    case "dropIndex":
+      // MySQL scopes index names to the table; others are global.
+      return dialect === "mysql"
+        ? [`DROP INDEX ${t(op.index)} ON ${t(op.table)};`]
+        : [`DROP INDEX ${t(op.index)};`];
+
+    case "addForeignKey": {
+      if (dialect === "sqlite")
+        return [`-- SKIPPED: SQLite cannot add FK ${op.fk.name} after table creation.`];
+      return [`ALTER TABLE ${t(op.table)} ADD ${fkClause(dialect, op.fk)};`];
+    }
+
+    case "dropForeignKey": {
+      if (dialect === "sqlite")
+        return [`-- SKIPPED: SQLite cannot drop FK ${op.fk}.`];
+      if (dialect === "mysql") return [`ALTER TABLE ${t(op.table)} DROP FOREIGN KEY ${t(op.fk)};`];
+      return [`ALTER TABLE ${t(op.table)} DROP CONSTRAINT ${t(op.fk)};`];
+    }
+  }
+}
+
+/** Render a full operation list into a flat SQL statement array. */
+export function renderPlan(dialect: Dialect, ops: Operation[]): string[] {
+  return ops.flatMap((op) => renderOperation(dialect, op));
+}
+
+/** Human-readable one-line summary of an operation (for confirmation prompts). */
+export function describeOperation(op: Operation): string {
+  switch (op.kind) {
+    case "createTable":
+      return `+ create table ${op.table.name}`;
+    case "dropTable":
+      return `- DROP TABLE ${op.table}  (destructive)`;
+    case "addColumn":
+      return `+ add column ${op.table}.${op.column.name}`;
+    case "dropColumn":
+      return `- DROP COLUMN ${op.table}.${op.column}  (destructive)`;
+    case "alterColumn":
+      return `~ alter column ${op.table}.${op.to.name}`;
+    case "createIndex":
+      return `+ create index ${op.index.name} on ${op.table}`;
+    case "dropIndex":
+      return `- drop index ${op.index}`;
+    case "addForeignKey":
+      return `+ add fk ${op.fk.name} on ${op.table}`;
+    case "dropForeignKey":
+      return `- drop fk ${op.fk} on ${op.table}`;
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+// Public API — import `defineConfig` in your agnes.config.ts.
+export { defineConfig, type AgnesConfig, type CacheConfig } from "./config";
+export { run } from "./cli";
+export { push } from "./commands/push";
+export { pull } from "./commands/pull";
+export { migrate } from "./commands/migrate";
+export { generate } from "./commands/generate";
+export { schemaToIR } from "./ir";
+export { diffSchemas } from "./diff";
+export { introspect } from "./introspect";
+export type { DatabaseIR, TableIR, ColumnIR, IndexIR, ForeignKeyIR } from "./ir";

package/src/introspect.ts

@@ -0,0 +1,242 @@
+import { logicalType, type Dialect } from "./dialect";
+import type { ColumnIR, DatabaseIR, ForeignKeyIR, IndexIR, TableIR } from "./ir";
+
+// Minimal DB surface the CLI needs — satisfied by AgnesClient.
+export interface QueryClient {
+  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+
+type Row = Record<string, unknown>;
+
+const str = (v: unknown): string => (v == null ? "" : String(v));
+const truthy = (v: unknown): boolean =>
+  v === true || v === 1 || v === "1" || v === "YES" || v === "t" || v === "true";
+
+/** Tables the CLI manages internally and must never diff/drop. */
+function isInternal(name: string): boolean {
+  return name.startsWith("_agnes") || name.startsWith("sqlite_");
+}
+
+export async function introspect(db: QueryClient, dialect: Dialect): Promise<DatabaseIR> {
+  switch (dialect) {
+    case "postgres":
+      return introspectPostgres(db);
+    case "mysql":
+      return introspectMysql(db);
+    case "sqlite":
+      return introspectSqlite(db);
+  }
+}
+
+// ─── PostgreSQL ─────────────────────────────────────────────────────────────
+
+async function introspectPostgres(db: QueryClient): Promise<DatabaseIR> {
+  const ir: DatabaseIR = {};
+  const tables = await db.query<Row>(
+    `SELECT table_name FROM information_schema.tables
+     WHERE table_schema = 'public' AND table_type = 'BASE TABLE'`,
+  );
+
+  for (const tr of tables) {
+    const name = str(tr.table_name);
+    if (isInternal(name)) continue;
+
+    const cols = await db.query<Row>(
+      `SELECT column_name, data_type, is_nullable, column_default
+       FROM information_schema.columns
+       WHERE table_schema = 'public' AND table_name = $1
+       ORDER BY ordinal_position`,
+      [name],
+    );
+    const pks = await db.query<Row>(
+      `SELECT kcu.column_name FROM information_schema.table_constraints tc
+       JOIN information_schema.key_column_usage kcu
+         ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+       WHERE tc.constraint_type = 'PRIMARY KEY' AND tc.table_name = $1 AND tc.table_schema = 'public'`,
+      [name],
+    );
+    const pkSet = new Set(pks.map((r) => str(r.column_name)));
+
+    const columns: ColumnIR[] = cols.map((c) => ({
+      name: str(c.column_name),
+      type: logicalType(str(c.data_type)),
+      nullable: str(c.is_nullable) === "YES",
+      primary: pkSet.has(str(c.column_name)),
+      default: c.column_default == null ? undefined : str(c.column_default),
+    }));
+
+    const idxRows = await db.query<Row>(
+      `SELECT i.relname AS index_name, a.attname AS column_name,
+              ix.indisunique AS is_unique, ix.indisprimary AS is_primary
+       FROM pg_class t
+       JOIN pg_index ix ON t.oid = ix.indrelid
+       JOIN pg_class i ON i.oid = ix.indexrelid
+       JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(ix.indkey)
+       WHERE t.relname = $1 AND t.relkind = 'r'`,
+      [name],
+    );
+    const indexes = groupIndexes(
+      idxRows
+        .filter((r) => !truthy(r.is_primary))
+        .map((r) => ({ index: str(r.index_name), column: str(r.column_name), unique: truthy(r.is_unique) })),
+    );
+
+    const fkRows = await db.query<Row>(
+      `SELECT tc.constraint_name, kcu.column_name,
+              ccu.table_name AS foreign_table, ccu.column_name AS foreign_column,
+              rc.update_rule, rc.delete_rule
+       FROM information_schema.table_constraints tc
+       JOIN information_schema.key_column_usage kcu
+         ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+       JOIN information_schema.constraint_column_usage ccu
+         ON ccu.constraint_name = tc.constraint_name AND ccu.table_schema = tc.table_schema
+       JOIN information_schema.referential_constraints rc
+         ON rc.constraint_name = tc.constraint_name AND rc.constraint_schema = tc.table_schema
+       WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_name = $1 AND tc.table_schema = 'public'`,
+      [name],
+    );
+    const foreignKeys: ForeignKeyIR[] = fkRows.map((r) => ({
+      name: str(r.constraint_name),
+      column: str(r.column_name),
+      refTable: str(r.foreign_table),
+      refColumn: str(r.foreign_column),
+      onUpdate: str(r.update_rule).toUpperCase(),
+      onDelete: str(r.delete_rule).toUpperCase(),
+    }));
+
+    ir[name] = { name, columns, indexes, foreignKeys };
+  }
+  return ir;
+}
+
+// ─── MySQL ──────────────────────────────────────────────────────────────────
+
+async function introspectMysql(db: QueryClient): Promise<DatabaseIR> {
+  const ir: DatabaseIR = {};
+  const tables = await db.query<Row>(
+    `SELECT table_name AS table_name FROM information_schema.tables
+     WHERE table_schema = DATABASE() AND table_type = 'BASE TABLE'`,
+  );
+
+  for (const tr of tables) {
+    const name = str(tr.table_name);
+    if (isInternal(name)) continue;
+
+    const cols = await db.query<Row>(
+      `SELECT column_name, data_type, is_nullable, column_default, column_key
+       FROM information_schema.columns
+       WHERE table_schema = DATABASE() AND table_name = ?
+       ORDER BY ordinal_position`,
+      [name],
+    );
+    const columns: ColumnIR[] = cols.map((c) => ({
+      name: str(c.column_name),
+      type: logicalType(str(c.data_type)),
+      nullable: str(c.is_nullable) === "YES",
+      primary: str(c.column_key) === "PRI",
+      default: c.column_default == null ? undefined : str(c.column_default),
+    }));
+
+    const idxRows = await db.query<Row>(
+      `SELECT index_name, column_name, non_unique
+       FROM information_schema.statistics
+       WHERE table_schema = DATABASE() AND table_name = ?
+       ORDER BY index_name, seq_in_index`,
+      [name],
+    );
+    const indexes = groupIndexes(
+      idxRows
+        .filter((r) => str(r.index_name) !== "PRIMARY")
+        .map((r) => ({ index: str(r.index_name), column: str(r.column_name), unique: !truthy(r.non_unique) })),
+    );
+
+    const fkRows = await db.query<Row>(
+      `SELECT kcu.constraint_name, kcu.column_name,
+              kcu.referenced_table_name AS foreign_table, kcu.referenced_column_name AS foreign_column,
+              rc.update_rule, rc.delete_rule
+       FROM information_schema.key_column_usage kcu
+       JOIN information_schema.referential_constraints rc
+         ON rc.constraint_name = kcu.constraint_name AND rc.constraint_schema = kcu.table_schema
+       WHERE kcu.table_schema = DATABASE() AND kcu.table_name = ?
+         AND kcu.referenced_table_name IS NOT NULL`,
+      [name],
+    );
+    const foreignKeys: ForeignKeyIR[] = fkRows.map((r) => ({
+      name: str(r.constraint_name),
+      column: str(r.column_name),
+      refTable: str(r.foreign_table),
+      refColumn: str(r.foreign_column),
+      onUpdate: str(r.update_rule).toUpperCase(),
+      onDelete: str(r.delete_rule).toUpperCase(),
+    }));
+
+    ir[name] = { name, columns, indexes, foreignKeys };
+  }
+  return ir;
+}
+
+// ─── SQLite ─────────────────────────────────────────────────────────────────
+
+async function introspectSqlite(db: QueryClient): Promise<DatabaseIR> {
+  const ir: DatabaseIR = {};
+  const tables = await db.query<Row>(
+    `SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'`,
+  );
+
+  for (const tr of tables) {
+    const name = str(tr.name);
+    if (isInternal(name)) continue;
+    const q = (s: string) => name.replace(/'/g, "''"); // guard, name only
+
+    const cols = await db.query<Row>(`PRAGMA table_info('${q(name)}')`);
+    const columns: ColumnIR[] = cols.map((c) => ({
+      name: str(c.name),
+      type: logicalType(str(c.type)),
+      nullable: !truthy(c.notnull),
+      primary: truthy(c.pk),
+      default: c.dflt_value == null ? undefined : str(c.dflt_value),
+    }));
+
+    const idxList = await db.query<Row>(`PRAGMA index_list('${q(name)}')`);
+    const indexes: IndexIR[] = [];
+    for (const idx of idxList) {
+      // Only user-created indexes (origin "c"); skip implicit PK ("pk") and
+      // UNIQUE-constraint ("u") auto-indexes, which can't be dropped directly.
+      if (str(idx.origin) !== "c") continue;
+      const idxName = str(idx.name);
+      const info = await db.query<Row>(`PRAGMA index_info('${idxName.replace(/'/g, "''")}')`);
+      indexes.push({
+        name: idxName,
+        columns: info.map((i) => str(i.name)),
+        unique: truthy(idx.unique),
+      });
+    }
+
+    const fkList = await db.query<Row>(`PRAGMA foreign_key_list('${q(name)}')`);
+    const foreignKeys: ForeignKeyIR[] = fkList.map((f) => ({
+      name: `fk_${name}_${str(f.from)}`,
+      column: str(f.from),
+      refTable: str(f.table),
+      refColumn: str(f.to),
+      onUpdate: str(f.on_update).toUpperCase() || "NO ACTION",
+      onDelete: str(f.on_delete).toUpperCase() || "NO ACTION",
+    }));
+
+    ir[name] = { name, columns, indexes, foreignKeys };
+  }
+  return ir;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function groupIndexes(
+  rows: { index: string; column: string; unique: boolean }[],
+): IndexIR[] {
+  const map = new Map<string, IndexIR>();
+  for (const r of rows) {
+    const existing = map.get(r.index);
+    if (existing) existing.columns.push(r.column);
+    else map.set(r.index, { name: r.index, columns: [r.column], unique: r.unique });
+  }
+  return [...map.values()];
+}