@svgrid/enterprise 1.2.0 → 2.0.0

package/src/studio/index.ts

@@ -0,0 +1,195 @@
+/**
+ * `@svgrid/enterprise/studio` - the pure, Svelte-free Studio core. Introspect a
+ * data source into an `EntitySchema`, then scaffold runnable SvelteKit code
+ * from it. Importable from Node (the MCP generator) as well as bundlers (the
+ * visual designer), since nothing here touches Svelte or the DOM.
+ */
+export { inferType, introspectJson, introspectDrizzle, introspectDrizzleAll } from './introspect.js'
+export { refineField, refineFields } from '../sources/field-inference.js'
+export { parseCsv, detectDelimiter, csvToEntity, type CsvEntity } from './csv.js'
+export { introspectPrisma, introspectPrismaAll } from './introspect-prisma.js'
+export {
+  introspectDatabase,
+  listDatabaseTables,
+  countTableRows,
+  probeConnection,
+  mapSqlType,
+  type SqlDialectName,
+  type DbExecute,
+  type IntrospectDbOptions,
+  type TableRowCount,
+} from './introspect-db.js'
+export {
+  buildConnectionString,
+  parseConnectionString,
+  redactConnectionString,
+  isFileDialect,
+  DRIVER_PACKAGE,
+  DEFAULT_PORT,
+  type SqlConnectionParts,
+} from './db-connect-string.js'
+export {
+  scaffold,
+  mergeManaged,
+  MANAGED_START,
+  MANAGED_END,
+  type GeneratedFile,
+  type ScaffoldOptions,
+} from './scaffold.js'
+export { scaffoldApp, type ScaffoldAppOptions } from './scaffold-app.js'
+export { emitStudioApp, emitEntityModules, entityScreenPage, prepareEntities } from './emit-schema.js'
+export { emitStudioProject, emitStudioAppBundle, studioDeployInfo } from './emit-project.js'
+export { sampleApps, getSampleApp, type SampleApp } from './samples/index.js'
+export { liveDataSamples, getLiveDataSample } from './samples/live-data.js'
+export {
+  sanitizeStudioProject,
+  buildStudioBugReport,
+  type SanitizeResult,
+  type BugReport,
+  type BugReportInput,
+  type StudioEnv,
+} from './bug-report.js'
+export { generateValue, generateRows } from './sample-data.js'
+export { studioThemes, defaultStudioTheme, getStudioTheme, resolveThemeTokens, isDarkTheme, themeStyleString, type StudioTheme } from './themes.js'
+export {
+  createProject,
+  defaultScreenFor,
+  defaultBlockConfig,
+  gridColumns,
+  entityOf,
+  blockPalette,
+  addBlock,
+  addBlockAt,
+  removeBlock,
+  duplicateBlock,
+  moveBlock,
+  reorderBlock,
+  updateBlock,
+  addEntity,
+  removeEntity,
+  updateEntity,
+  addScreen,
+  removeScreen,
+  updateScreen,
+  duplicateScreen,
+  reorderScreen,
+  insertBlock,
+  setDataSource,
+  setDeployTarget,
+  defaultEntitySource,
+  flattenBlocks,
+  TAB_CHILD_KINDS,
+  addTab,
+  removeTab,
+  renameTab,
+  addTabBlock,
+  removeTabBlock,
+  setEntityDataSource,
+  entityDataSource,
+  setTheme,
+  setThemePreset,
+  setShell,
+  sanitizeProject,
+  screenFromTemplate,
+  addScreenFromTemplate,
+  serializeProject,
+  parseProject,
+  validateProject,
+  isProjectValid,
+  blockColumns,
+  roleCanScreen,
+  roleCanAction,
+  CRUD_ACTIONS,
+  type CrudAction,
+  type RoleAccess,
+  type AccessControl,
+  type I18nConfig,
+  type DeployTarget,
+  type StudioProject,
+  type Screen,
+  type ScreenNav,
+  type Block,
+  type BlockKind,
+  type BlockConfig,
+  type GridConfig,
+  type GridColumnConfig,
+  type RowLink,
+  type RowAction,
+  type RowActionKind,
+  type FormatOp,
+  type FormatRule,
+  type GridEditing,
+  type GridDensity,
+  type GridAlign,
+  type PagerPosition,
+  type FormConfig,
+  type ChartConfig,
+  type KpiConfig,
+  type KpiFormat,
+  type GaugeConfig,
+  type TreeConfig,
+  type TabsConfig,
+  type StudioTab,
+  type DashboardConfig,
+  type MasterDetailConfig,
+  type LookupConfig,
+  type PivotConfig,
+  type FilterPanelConfig,
+  type RecordConfig,
+  type BoardConfig,
+  type CalendarConfig,
+  type DetailConfig,
+  type DetailRelated,
+  type Reduce,
+  type DataSourceKind,
+  type EntityDataSource,
+  type MemorySource,
+  type RestSource,
+  type SqlSource,
+  type SupabaseSource,
+  type PgliteSource,
+  type RestMethod,
+  type ParamLocation,
+  type ParamType,
+  type RequestParam,
+  type SqlDialectKind,
+  type ProjectTheme,
+  type ShellConfig,
+  type ShellStyle,
+  type ScreenTemplate,
+  type PaletteItem,
+  type ProjectIssue,
+} from './project.js'
+export {
+  verifyScaffold,
+  summarizeVerify,
+  type VerifyResult,
+  type VerifyIssue,
+  type VerifySeverity,
+} from './verify.js'
+export {
+  runStudioAdd,
+  runStudioAddApp,
+  resolveSchema,
+  resolveSchemas,
+  type StudioIO,
+  type AddOptions,
+  type AddResult,
+  type AddAppResult,
+} from './cli.js'
+
+// Re-export the schema surface so consumers get everything from one entry.
+export {
+  resolveIdField,
+  schemaToColumns,
+  schemaToFormFields,
+  linkRelationLabels,
+  pickLabelField,
+  type EntitySchema,
+  type EntityField,
+  type EntityFieldType,
+} from '../schema.js'
+
+// Pure license classification, so the Node/MCP generator can soft-gate with the
+// same rules as the browser (see license-core.ts). No DOM, safe in Node.
+export { checkLicenseKey, type LicenseInfo, type LicenseStatus } from '../license-core.js'

package/src/studio/introspect-db.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from 'vitest'
+import { introspectDatabase, listDatabaseTables, countTableRows, probeConnection, mapSqlType, type DbExecute } from './introspect-db'
+
+describe('mapSqlType', () => {
+  it('maps common SQL types across dialects', () => {
+    expect(mapSqlType('integer')).toBe('number')
+    expect(mapSqlType('bigint')).toBe('number') // not confused with bit
+    expect(mapSqlType('numeric')).toBe('number')
+    expect(mapSqlType('boolean')).toBe('boolean')
+    expect(mapSqlType('bit')).toBe('boolean')
+    expect(mapSqlType('timestamp with time zone')).toBe('datetime')
+    expect(mapSqlType('datetime2')).toBe('datetime')
+    expect(mapSqlType('date')).toBe('dateString')
+    expect(mapSqlType('jsonb')).toBe('json')
+    expect(mapSqlType('varchar')).toBe('text')
+  })
+})
+
+/** Fake executor: returns canned catalog rows and records the SQL it was asked. */
+function fakeExec(rowsByCall: Array<Array<Record<string, unknown>>>) {
+  const calls: Array<{ sql: string; params: unknown[] }> = []
+  let i = 0
+  const execute: DbExecute = async (sql, params) => {
+    calls.push({ sql, params })
+    return rowsByCall[i++] ?? []
+  }
+  return { execute, calls }
+}
+
+describe('introspectDatabase (information_schema dialects)', () => {
+  const catalog = [
+    { name: 'id', type: 'integer', nullable: 0, pk: 1 },
+    { name: 'email', type: 'varchar', nullable: 0, pk: 0 },
+    { name: 'age', type: 'integer', nullable: 1, pk: 0 },
+    { name: 'active', type: 'boolean', nullable: 1, pk: 0 },
+  ]
+
+  it('postgres: maps columns, primary key, and NOT NULL -> required', async () => {
+    const { execute, calls } = fakeExec([catalog])
+    const schema = await introspectDatabase({ dialect: 'postgres', table: 'users', execute })
+    expect(schema.name).toBe('users')
+    const byField = Object.fromEntries(schema.fields.map((f) => [f.field, f]))
+    expect(byField.id!).toMatchObject({ type: 'number', primaryKey: true, readonly: true })
+    expect(byField.email!).toMatchObject({ type: 'text', required: true })
+    expect(byField.age!.required).toBeUndefined() // nullable
+    expect(byField.active!.type).toBe('boolean')
+    expect(calls[0]!.sql).toContain('information_schema.columns')
+    expect(calls[0]!.params).toEqual(['users'])
+  })
+
+  it('supabase is treated as postgres', async () => {
+    const { execute, calls } = fakeExec([catalog])
+    await introspectDatabase({ dialect: 'supabase', table: 'users', execute })
+    expect(calls[0]!.sql).toContain('information_schema.columns')
+  })
+
+  it('mssql uses @p1 placeholders', async () => {
+    const { execute, calls } = fakeExec([catalog])
+    await introspectDatabase({ dialect: 'mssql', table: 'Users', execute })
+    expect(calls[0]!.sql).toContain('@p1')
+  })
+
+  it('throws when the table has no columns', async () => {
+    const { execute } = fakeExec([[]])
+    await expect(introspectDatabase({ dialect: 'postgres', table: 'ghost', execute })).rejects.toThrow(
+      /no columns/,
+    )
+  })
+
+  it('turns a foreign-key column into a relation field', async () => {
+    const cols = [
+      { name: 'id', type: 'integer', nullable: 0, pk: 1 },
+      { name: 'name', type: 'varchar', nullable: 0, pk: 0 },
+      { name: 'company_id', type: 'integer', nullable: 0, pk: 0 },
+    ]
+    const fks = [{ column: 'company_id', ref_table: 'companies', ref_column: 'id' }]
+    const { execute, calls } = fakeExec([cols, fks])
+    const schema = await introspectDatabase({ dialect: 'postgres', table: 'contacts', execute })
+    const byField = Object.fromEntries(schema.fields.map((f) => [f.field, f]))
+    expect(byField.company_id!).toMatchObject({
+      type: 'relation',
+      required: true,
+      relation: { entity: 'companies', foreignKey: 'company_id', labelField: 'name' },
+    })
+    expect(calls[1]!.sql).toContain('FOREIGN KEY')
+  })
+
+  it('degrades gracefully when the FK query fails', async () => {
+    let call = 0
+    const execute: DbExecute = async () => {
+      call += 1
+      if (call === 1) return [{ name: 'id', type: 'integer', nullable: 0, pk: 1 }]
+      throw new Error('permission denied')
+    }
+    const schema = await introspectDatabase({ dialect: 'postgres', table: 't', execute })
+    expect(schema.fields[0]!.type).toBe('number') // no throw, no relation
+  })
+})
+
+describe('introspectDatabase (sqlite PRAGMA)', () => {
+  it('reads PRAGMA table_info rows (notnull + pk-as-index)', async () => {
+    const pragma = [
+      { cid: 0, name: 'id', type: 'INTEGER', notnull: 1, dflt_value: null, pk: 1 },
+      { cid: 1, name: 'title', type: 'TEXT', notnull: 1, dflt_value: null, pk: 0 },
+      { cid: 2, name: 'done', type: 'INTEGER', notnull: 0, dflt_value: null, pk: 0 },
+    ]
+    const { execute, calls } = fakeExec([pragma])
+    const schema = await introspectDatabase({ dialect: 'sqlite', table: 'todos', execute })
+    const byField = Object.fromEntries(schema.fields.map((f) => [f.field, f]))
+    expect(calls[0]!.sql).toBe('PRAGMA table_info("todos")')
+    expect(byField.id!).toMatchObject({ type: 'number', primaryKey: true })
+    expect(byField.title!.required).toBe(true)
+    expect(byField.done!.required).toBeUndefined()
+  })
+
+  it('reads PRAGMA foreign_key_list into a relation field', async () => {
+    const pragma = [
+      { cid: 0, name: 'id', type: 'INTEGER', notnull: 1, pk: 1 },
+      { cid: 1, name: 'company_id', type: 'INTEGER', notnull: 1, pk: 0 },
+    ]
+    const fkList = [{ id: 0, seq: 0, table: 'companies', from: 'company_id', to: 'id' }]
+    const { execute, calls } = fakeExec([pragma, fkList])
+    const schema = await introspectDatabase({ dialect: 'sqlite', table: 'contacts', execute })
+    expect(schema.fields.find((f) => f.field === 'company_id')).toMatchObject({
+      type: 'relation',
+      relation: { entity: 'companies', foreignKey: 'company_id', labelField: 'name' },
+    })
+    expect(calls[1]!.sql).toBe('PRAGMA foreign_key_list("contacts")')
+  })
+})
+
+describe('listDatabaseTables', () => {
+  it('returns base table names', async () => {
+    const { execute } = fakeExec([[{ name: 'users' }, { name: 'orders' }]])
+    expect(await listDatabaseTables('postgres', execute)).toEqual(['users', 'orders'])
+  })
+})
+
+describe('countTableRows', () => {
+  it('counts each table with dialect-correct quoting', async () => {
+    const { execute, calls } = fakeExec([[{ n: 42 }], [{ n: 7 }]])
+    const counts = await countTableRows('mysql', execute, ['users', 'orders'])
+    expect(counts).toEqual([{ name: 'users', rows: 42 }, { name: 'orders', rows: 7 }])
+    expect(calls[0]!.sql).toBe('SELECT COUNT(*) AS n FROM `users`')
+  })
+
+  it('quotes identifiers per dialect (mssql brackets, pg double-quotes)', async () => {
+    const { execute: e1, calls: c1 } = fakeExec([[{ n: 1 }]])
+    await countTableRows('mssql', e1, ['Orders'])
+    expect(c1[0]!.sql).toBe('SELECT COUNT(*) AS n FROM [Orders]')
+    const { execute: e2, calls: c2 } = fakeExec([[{ n: 1 }]])
+    await countTableRows('postgres', e2, ['orders'])
+    expect(c2[0]!.sql).toBe('SELECT COUNT(*) AS n FROM "orders"')
+  })
+
+  it('reports null (not a throw) for a table it cannot count', async () => {
+    let call = 0
+    const execute: DbExecute = async () => {
+      call += 1
+      if (call === 1) return [{ n: 5 }]
+      throw new Error('permission denied')
+    }
+    expect(await countTableRows('postgres', execute, ['ok', 'denied'])).toEqual([
+      { name: 'ok', rows: 5 },
+      { name: 'denied', rows: null },
+    ])
+  })
+})
+
+describe('probeConnection', () => {
+  it('lists tables and (with counts) reports row totals in one probe', async () => {
+    // call 1: table list; calls 2-3: per-table COUNT(*)
+    const { execute } = fakeExec([[{ name: 'users' }, { name: 'orders' }], [{ n: 3 }], [{ n: 9 }]])
+    expect(await probeConnection('postgres', execute, { counts: true })).toEqual({
+      ok: true,
+      tables: [{ name: 'users', rows: 3 }, { name: 'orders', rows: 9 }],
+    })
+  })
+
+  it('skips counting when counts are off', async () => {
+    const { execute, calls } = fakeExec([[{ name: 'users' }]])
+    const probe = await probeConnection('postgres', execute)
+    expect(probe.tables).toEqual([{ name: 'users', rows: null }])
+    expect(calls).toHaveLength(1) // no COUNT(*) queries
+  })
+})

package/src/studio/introspect-db.ts

@@ -0,0 +1,312 @@
+/**
+ * Live-database introspection - "connect to your database and scaffold". Reads
+ * a table's columns straight from the database catalog and maps them to an
+ * `EntitySchema`. Covers PostgreSQL (and Supabase, which is Postgres), MySQL,
+ * SQL Server, and SQLite.
+ *
+ * Driver-free, like `createSqlDataSource`: you pass an `execute(sql, params)`
+ * backed by your own connected client (pg, postgres.js, mysql2, mssql,
+ * better-sqlite3, the Supabase client, ...). Nothing here imports a driver, so
+ * it's testable and adds no dependencies.
+ */
+import type { EntityField, EntityFieldType, EntitySchema } from '../schema.js'
+import { refineField } from '../sources/field-inference.js'
+
+export type SqlDialectName = 'postgres' | 'supabase' | 'mysql' | 'mssql' | 'sqlite'
+export type DbExecute = (sql: string, params: unknown[]) => Promise<Array<Record<string, unknown>>>
+
+function truthy(v: unknown): boolean {
+  return v === 1 || v === '1' || v === true
+}
+
+function identQuote(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`
+}
+
+/** Dialect-correct identifier quoting for ad-hoc queries (COUNT etc). */
+function quoteIdent(dialect: SqlDialectName, name: string): string {
+  if (dialect === 'mysql') return `\`${name.replace(/`/g, '``')}\``
+  if (dialect === 'mssql') return `[${name.replace(/]/g, ']]')}]`
+  return identQuote(name) // postgres, supabase, sqlite
+}
+
+/** Best-effort SQL type -> entity field type. The designer can refine edge cases. */
+export function mapSqlType(raw: string): EntityFieldType {
+  const t = raw.toLowerCase()
+  if (/\b(bool|bit)\b/.test(t) || t === 'boolean') return 'boolean'
+  if (/int|serial|numeric|decimal|real|double|float|money|number/.test(t)) return 'number'
+  if (/timestamp|datetime/.test(t)) return 'datetime'
+  if (/date/.test(t)) return 'dateString'
+  if (/json/.test(t)) return 'json'
+  return 'text'
+}
+
+function fieldFrom(name: string, rawType: string, pk: boolean, notNull: boolean): EntityField {
+  const field: EntityField = { field: name, type: mapSqlType(rawType) }
+  if (pk) {
+    field.primaryKey = true
+    field.readonly = true
+  } else if (notNull) {
+    field.required = true
+  }
+  return field
+}
+
+/** Map catalog rows (aliased name/type/nullable/pk) from information_schema dialects. */
+function infoSchemaFields(rows: Array<Record<string, unknown>>): EntityField[] {
+  return rows.map((r) =>
+    fieldFrom(String(r.name), String(r.type ?? ''), truthy(r.pk), !truthy(r.nullable)),
+  )
+}
+
+/** Map SQLite `PRAGMA table_info` rows (name/type/notnull/pk-as-index). */
+function sqliteFields(rows: Array<Record<string, unknown>>): EntityField[] {
+  return rows.map((r) =>
+    fieldFrom(String(r.name), String(r.type ?? ''), Number(r.pk) > 0, Number(r.notnull) === 1),
+  )
+}
+
+/** A discovered foreign key: local `column` references `table`.`refColumn`. */
+type FkInfo = { column: string; table: string; refColumn?: string }
+
+/** Map information_schema FK rows (aliased column/ref_table/ref_column) - pg / mysql / mssql. */
+function infoSchemaFks(rows: Array<Record<string, unknown>>): FkInfo[] {
+  return rows
+    .filter((r) => r.ref_table)
+    .map((r) => ({ column: String(r.column), table: String(r.ref_table), refColumn: r.ref_column ? String(r.ref_column) : undefined }))
+}
+
+/** Map SQLite `PRAGMA foreign_key_list` rows (from/table/to). */
+function sqliteFks(rows: Array<Record<string, unknown>>): FkInfo[] {
+  return rows.map((r) => ({ column: String(r.from), table: String(r.table), refColumn: r.to ? String(r.to) : undefined }))
+}
+
+type DialectDef = {
+  columns: (table: string) => { sql: string; params: unknown[] }
+  toFields: (rows: Array<Record<string, unknown>>) => EntityField[]
+  tables: { sql: string; params: unknown[] }
+  foreignKeys: (table: string) => { sql: string; params: unknown[] }
+  toForeignKeys: (rows: Array<Record<string, unknown>>) => FkInfo[]
+}
+
+const POSTGRES: DialectDef = {
+  columns: (table) => ({
+    sql: `SELECT c.column_name AS name, c.data_type AS type,
+       CASE WHEN c.is_nullable = 'YES' THEN 1 ELSE 0 END AS nullable,
+       CASE WHEN pk.column_name IS NOT NULL THEN 1 ELSE 0 END AS pk
+FROM information_schema.columns c
+LEFT JOIN (
+  SELECT kcu.column_name
+  FROM information_schema.table_constraints tc
+  JOIN information_schema.key_column_usage kcu
+    ON kcu.constraint_name = tc.constraint_name AND kcu.table_name = tc.table_name
+  WHERE tc.constraint_type = 'PRIMARY KEY' AND tc.table_name = $1
+) pk ON pk.column_name = c.column_name
+WHERE c.table_name = $1
+ORDER BY c.ordinal_position`,
+    params: [table],
+  }),
+  toFields: infoSchemaFields,
+  tables: {
+    sql: `SELECT table_name AS name FROM information_schema.tables
+WHERE table_schema = 'public' AND table_type = 'BASE TABLE' ORDER BY table_name`,
+    params: [],
+  },
+  foreignKeys: (table) => ({
+    sql: `SELECT kcu.column_name AS "column", ccu.table_name AS ref_table, ccu.column_name AS ref_column
+FROM information_schema.table_constraints tc
+JOIN information_schema.key_column_usage kcu
+  ON kcu.constraint_name = tc.constraint_name AND kcu.table_name = tc.table_name
+JOIN information_schema.constraint_column_usage ccu
+  ON ccu.constraint_name = tc.constraint_name
+WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_name = $1`,
+    params: [table],
+  }),
+  toForeignKeys: infoSchemaFks,
+}
+
+const MYSQL: DialectDef = {
+  columns: (table) => ({
+    sql: `SELECT COLUMN_NAME AS name, DATA_TYPE AS type,
+       CASE WHEN IS_NULLABLE = 'YES' THEN 1 ELSE 0 END AS nullable,
+       CASE WHEN COLUMN_KEY = 'PRI' THEN 1 ELSE 0 END AS pk
+FROM information_schema.columns
+WHERE TABLE_NAME = ? AND TABLE_SCHEMA = DATABASE()
+ORDER BY ORDINAL_POSITION`,
+    params: [table],
+  }),
+  toFields: infoSchemaFields,
+  tables: {
+    sql: `SELECT TABLE_NAME AS name FROM information_schema.tables
+WHERE TABLE_SCHEMA = DATABASE() AND TABLE_TYPE = 'BASE TABLE' ORDER BY TABLE_NAME`,
+    params: [],
+  },
+  foreignKeys: (table) => ({
+    sql: `SELECT COLUMN_NAME AS \`column\`, REFERENCED_TABLE_NAME AS ref_table, REFERENCED_COLUMN_NAME AS ref_column
+FROM information_schema.KEY_COLUMN_USAGE
+WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND REFERENCED_TABLE_NAME IS NOT NULL`,
+    params: [table],
+  }),
+  toForeignKeys: infoSchemaFks,
+}
+
+const MSSQL: DialectDef = {
+  columns: (table) => ({
+    sql: `SELECT c.COLUMN_NAME AS name, c.DATA_TYPE AS type,
+       CASE WHEN c.IS_NULLABLE = 'YES' THEN 1 ELSE 0 END AS nullable,
+       CASE WHEN pk.COLUMN_NAME IS NOT NULL THEN 1 ELSE 0 END AS pk
+FROM INFORMATION_SCHEMA.COLUMNS c
+LEFT JOIN (
+  SELECT ku.COLUMN_NAME
+  FROM INFORMATION_SCHEMA.TABLE_CONSTRAINTS tc
+  JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE ku ON tc.CONSTRAINT_NAME = ku.CONSTRAINT_NAME
+  WHERE tc.CONSTRAINT_TYPE = 'PRIMARY KEY' AND tc.TABLE_NAME = @p1
+) pk ON pk.COLUMN_NAME = c.COLUMN_NAME
+WHERE c.TABLE_NAME = @p1
+ORDER BY c.ORDINAL_POSITION`,
+    params: [table],
+  }),
+  toFields: infoSchemaFields,
+  tables: {
+    sql: `SELECT TABLE_NAME AS name FROM INFORMATION_SCHEMA.TABLES
+WHERE TABLE_TYPE = 'BASE TABLE' ORDER BY TABLE_NAME`,
+    params: [],
+  },
+  foreignKeys: (table) => ({
+    sql: `SELECT cu.COLUMN_NAME AS [column], pk.TABLE_NAME AS ref_table, pt.COLUMN_NAME AS ref_column
+FROM INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS rc
+JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE cu ON cu.CONSTRAINT_NAME = rc.CONSTRAINT_NAME
+JOIN INFORMATION_SCHEMA.TABLE_CONSTRAINTS pk ON pk.CONSTRAINT_NAME = rc.UNIQUE_CONSTRAINT_NAME
+JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE pt
+  ON pt.CONSTRAINT_NAME = pk.CONSTRAINT_NAME AND pt.ORDINAL_POSITION = cu.ORDINAL_POSITION
+WHERE cu.TABLE_NAME = @p1`,
+    params: [table],
+  }),
+  toForeignKeys: infoSchemaFks,
+}
+
+const SQLITE: DialectDef = {
+  columns: (table) => ({ sql: `PRAGMA table_info(${identQuote(table)})`, params: [] }),
+  toFields: sqliteFields,
+  tables: {
+    sql: `SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name`,
+    params: [],
+  },
+  foreignKeys: (table) => ({ sql: `PRAGMA foreign_key_list(${identQuote(table)})`, params: [] }),
+  toForeignKeys: sqliteFks,
+}
+
+const DIALECTS: Record<Exclude<SqlDialectName, 'supabase'>, DialectDef> = {
+  postgres: POSTGRES,
+  mysql: MYSQL,
+  mssql: MSSQL,
+  sqlite: SQLITE,
+}
+
+function defFor(dialect: SqlDialectName): DialectDef {
+  const key = dialect === 'supabase' ? 'postgres' : dialect
+  const def = DIALECTS[key]
+  if (!def) throw new Error(`introspectDatabase: unknown dialect "${dialect}"`)
+  return def
+}
+
+export type IntrospectDbOptions = {
+  dialect: SqlDialectName
+  table: string
+  execute: DbExecute
+}
+
+/** Convert FK columns into `relation` fields so the form gets a lookup + master-detail is inferable. */
+function applyForeignKeys(fields: EntityField[], fks: FkInfo[]): EntityField[] {
+  if (fks.length === 0) return fields
+  const byColumn = new Map(fks.map((fk) => [fk.column, fk]))
+  return fields.map((f) => {
+    const fk = byColumn.get(f.field)
+    if (!fk || f.primaryKey) return f
+    const rel: EntityField = {
+      field: f.field,
+      type: 'relation',
+      relation: { entity: fk.table, foreignKey: f.field, labelField: 'name' },
+    }
+    if (f.required) rel.required = true
+    return rel
+  })
+}
+
+/** Read one table's columns (and foreign keys) from the live database into an EntitySchema. */
+export async function introspectDatabase(options: IntrospectDbOptions): Promise<EntitySchema> {
+  const def = defFor(options.dialect)
+  const { sql, params } = def.columns(options.table)
+  const rows = await options.execute(sql, params)
+  const fields = def.toFields(rows)
+  if (fields.length === 0) {
+    throw new Error(`introspectDatabase: table "${options.table}" has no columns (does it exist?)`)
+  }
+
+  // Foreign keys are best-effort: if the catalog query fails (permissions,
+  // unusual setup), degrade to a schema without relations rather than throw.
+  let fks: FkInfo[] = []
+  try {
+    const fk = def.foreignKeys(options.table)
+    fks = def.toForeignKeys(await options.execute(fk.sql, fk.params))
+  } catch {
+    fks = []
+  }
+
+  // Infer rich editors (phone / email / rating / mask / ...) from column names,
+  // after FK columns became relations so those are left untouched.
+  return { name: options.table, fields: applyForeignKeys(fields, fks).map(refineField) }
+}
+
+/** List the base tables in the connected database. */
+export async function listDatabaseTables(
+  dialect: SqlDialectName,
+  execute: DbExecute,
+): Promise<string[]> {
+  const def = defFor(dialect)
+  const rows = await execute(def.tables.sql, def.tables.params)
+  return rows.map((r) => String(r.name)).filter(Boolean)
+}
+
+export type TableRowCount = { name: string; rows: number | null }
+
+/**
+ * Count rows in each table - powers the designer's "Test connection" step, which
+ * shows the user their real data volumes before they commit to importing. Fully
+ * resilient: a table that can't be counted (permissions, a view) yields
+ * `rows: null` instead of failing the whole probe.
+ */
+export async function countTableRows(
+  dialect: SqlDialectName,
+  execute: DbExecute,
+  tables: string[],
+): Promise<TableRowCount[]> {
+  const out: TableRowCount[] = []
+  for (const table of tables) {
+    try {
+      const rows = await execute(`SELECT COUNT(*) AS n FROM ${quoteIdent(dialect, table)}`, [])
+      const n = rows[0]?.n
+      out.push({ name: table, rows: n == null ? null : Number(n) })
+    } catch {
+      out.push({ name: table, rows: null })
+    }
+  }
+  return out
+}
+
+/**
+ * One round-trip "test connection": confirm we can talk to the database, list
+ * its tables, and (optionally) report each table's row count. Throws only if the
+ * connection itself is unusable (the caller maps that to a friendly message).
+ */
+export async function probeConnection(
+  dialect: SqlDialectName,
+  execute: DbExecute,
+  opts: { counts?: boolean } = {},
+): Promise<{ ok: true; tables: TableRowCount[] }> {
+  const names = await listDatabaseTables(dialect, execute)
+  const tables = opts.counts
+    ? await countTableRows(dialect, execute, names)
+    : names.map((name) => ({ name, rows: null }))
+  return { ok: true, tables }
+}