@svgrid/enterprise 1.2.0 → 2.0.0

package/src/studio/cli.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, it } from 'vitest'
+import type { EntitySchema } from '../schema'
+import { resolveSchema, resolveSchemas, runStudioAdd, runStudioAddApp, type StudioIO } from './cli'
+import { MANAGED_END, MANAGED_START } from './scaffold'
+
+/** In-memory StudioIO for tests. */
+function memIO(seed: Record<string, string> = {}) {
+  const files = new Map<string, string>(Object.entries(seed))
+  const io: StudioIO = {
+    readFile: async (p) => (files.has(p) ? files.get(p)! : null),
+    writeFile: async (p, c) => {
+      files.set(p, c)
+    },
+  }
+  return { io, files }
+}
+
+const drizzle = `
+  import { pgTable, serial, text, integer, boolean } from 'drizzle-orm/pg-core'
+  export const users = pgTable('users', {
+    id: serial('id').primaryKey(),
+    name: text('name').notNull(),
+    active: boolean('active'),
+  })
+  export const orders = pgTable('orders', {
+    id: serial('id').primaryKey(),
+    total: integer('total'),
+  })
+`
+
+describe('runStudioAdd', () => {
+  it('introspects a Drizzle file, writes the 3 files, and verifies', async () => {
+    const { io, files } = memIO({ 'src/lib/db/schema.ts': drizzle })
+    const res = await runStudioAdd({ from: 'src/lib/db/schema.ts' }, io)
+
+    expect(res.schema.name).toBe('users') // first table
+    expect(res.written).toEqual([
+      'src/lib/users.schema.ts',
+      'src/routes/api/users/+server.ts',
+      'src/routes/users/+page.svelte',
+    ])
+    expect(res.verify.ok).toBe(true) // generated page compiles
+    expect(files.get('src/routes/users/+page.svelte')).toContain('<SvGrid')
+  })
+
+  it('selects a specific table with `table`', async () => {
+    const { io } = memIO({ 'schema.ts': drizzle })
+    const res = await runStudioAdd({ from: 'schema.ts', table: 'orders' }, io)
+    expect(res.schema.name).toBe('orders')
+    expect(res.schema.fields.map((f) => f.field)).toEqual(['id', 'total'])
+  })
+
+  it('scaffolds a real SQL data source when dataSource:"sql"', async () => {
+    const { io, files } = memIO({ 'schema.ts': drizzle })
+    await runStudioAdd({ from: 'schema.ts', dataSource: 'sql' }, io)
+    const server = files.get('src/routes/api/users/+server.ts')!
+    expect(server).toContain('createSqlDataSource')
+    expect(server).toContain("table: \"users\"")
+    expect(server).toContain('execute:')
+  })
+
+  it('regenerating preserves user edits outside the managed region', async () => {
+    const { io, files } = memIO({ 'schema.ts': drizzle })
+    await runStudioAdd({ from: 'schema.ts' }, io)
+
+    // User hand-edits the page outside the managed block.
+    const page = files.get('src/routes/users/+page.svelte')!
+    const edited = page.replace('<div class="page">', '<div class="page my-custom-class">')
+    files.set('src/routes/users/+page.svelte', edited)
+
+    // Regenerate.
+    await runStudioAdd({ from: 'schema.ts' }, io)
+    const after = files.get('src/routes/users/+page.svelte')!
+    expect(after).toContain('my-custom-class') // user edit survived
+    expect(after).toContain(MANAGED_START)
+    expect(after).toContain(MANAGED_END)
+  })
+
+  it('throws a helpful error when no input is given', async () => {
+    const { io } = memIO()
+    await expect(runStudioAdd({}, io)).rejects.toThrow(/provide `from`/)
+  })
+
+  it('accepts a ready EntitySchema directly', async () => {
+    const schema: EntitySchema = {
+      name: 'tags',
+      idField: 'id',
+      fields: [{ field: 'id', type: 'text', primaryKey: true }, { field: 'label', type: 'text' }],
+    }
+    const { io } = memIO()
+    const res = await runStudioAdd({ schema }, io)
+    expect(res.written).toHaveLength(3)
+    expect(res.verify.ok).toBe(true)
+  })
+})
+
+describe('runStudioAddApp', () => {
+  const companies: EntitySchema = {
+    name: 'companies', idField: 'id',
+    fields: [{ field: 'id', type: 'number', primaryKey: true }, { field: 'name', type: 'text' }],
+  }
+  const contacts: EntitySchema = {
+    name: 'contacts', idField: 'id',
+    fields: [
+      { field: 'id', type: 'number', primaryKey: true },
+      { field: 'name', type: 'text' },
+      { field: 'company_id', type: 'relation', relation: { entity: 'companies', foreignKey: 'company_id', labelField: 'name' } },
+    ],
+  }
+
+  it('writes every entity screen plus the app shell, and verifies', async () => {
+    const { io, files } = memIO()
+    const res = await runStudioAddApp([companies, contacts], {}, io)
+    expect(res.written).toContain('src/routes/+layout.svelte')
+    expect(res.written).toContain('src/routes/+page.svelte')
+    expect(res.written).toContain('src/routes/companies/+page.svelte')
+    expect(res.written).toContain('src/routes/contacts/+page.svelte')
+    expect(files.get('src/routes/+layout.svelte')).toContain('"href":"/contacts"')
+    expect(res.verify.ok).toBe(true)
+  })
+})
+
+// A linked Drizzle file (posts.authorId -> users) and the equivalent Prisma.
+const linkedDrizzle = `
+  import { pgTable, serial, text, integer } from 'drizzle-orm/pg-core'
+  export const users = pgTable('users', {
+    id: serial('id').primaryKey(),
+    name: text('name').notNull(),
+  })
+  export const posts = pgTable('posts', {
+    id: serial('id').primaryKey(),
+    title: text('title').notNull(),
+    authorId: integer('author_id').references(() => users.id),
+  })
+`
+
+const linkedPrisma = `
+  model User {
+    id    Int    @id @default(autoincrement())
+    name  String
+    posts Post[]
+  }
+  model Post {
+    id       Int    @id @default(autoincrement())
+    title    String
+    author   User   @relation(fields: [authorId], references: [id])
+    authorId Int
+  }
+`
+
+describe('resolveSchema (single, from a file)', () => {
+  it('detects Prisma by content and turns @relation into a relation field', async () => {
+    const { io } = memIO({ 'schema.prisma': linkedPrisma })
+    const schema = await resolveSchema({ from: 'schema.prisma', table: 'Post' }, io)
+    const rel = schema.fields.find((f) => f.field === 'authorId')!
+    expect(rel.type).toBe('relation')
+    expect(rel.relation?.entity).toBe('User')
+  })
+
+  it('parses a Drizzle .references() column as a relation', async () => {
+    const { io } = memIO({ 'schema.ts': linkedDrizzle })
+    const schema = await resolveSchema({ from: 'schema.ts', table: 'posts' }, io)
+    expect(schema.fields.find((f) => f.field === 'authorId')?.type).toBe('relation')
+  })
+})
+
+describe('resolveSchemas + runStudioAddApp (--all --from a file)', () => {
+  it('scaffolds a linked app from a Drizzle schema and verifies', async () => {
+    const { io, files } = memIO({ 'schema.ts': linkedDrizzle })
+    const schemas = await resolveSchemas('schema.ts', io)
+    expect(schemas.map((s) => s.name)).toEqual(['users', 'posts'])
+
+    const res = await runStudioAddApp(schemas, {}, io)
+    expect(res.written).toContain('src/routes/users/+page.svelte')
+    expect(res.written).toContain('src/routes/posts/+page.svelte')
+    expect(files.get('src/routes/+layout.svelte')).toContain('"href":"/posts"')
+    expect(res.verify.ok).toBe(true)
+  })
+
+  it('scaffolds a linked app from a Prisma schema and verifies', async () => {
+    const { io } = memIO({ 'schema.prisma': linkedPrisma })
+    const schemas = await resolveSchemas('schema.prisma', io)
+    expect(schemas.map((s) => s.name)).toEqual(['User', 'Post'])
+    const res = await runStudioAddApp(schemas, {}, io)
+    expect(res.verify.ok).toBe(true)
+  })
+})

package/src/studio/cli.ts

@@ -0,0 +1,112 @@
+/**
+ * runStudioAdd - the one-command pipeline behind `@svgrid/studio add`: read a
+ * schema, introspect it, scaffold the files, merge-write them (preserving user
+ * edits outside managed regions), and verify the output compiles. This is the
+ * whole "CRUD screen in seconds" flow.
+ *
+ * Filesystem access is injected (`StudioIO`), so the orchestration is pure and
+ * unit-testable; the actual CLI bin supplies node:fs. No process/fs imports
+ * here, so it also runs in the browser (e.g. the designer's future
+ * write-to-project action).
+ */
+import type { EntitySchema } from '../schema.js'
+import { introspectDrizzle, introspectDrizzleAll, introspectJson } from './introspect.js'
+import { introspectPrisma, introspectPrismaAll } from './introspect-prisma.js'
+import { mergeManaged, scaffold, type ScaffoldOptions } from './scaffold.js'
+import { scaffoldApp, type ScaffoldAppOptions } from './scaffold-app.js'
+import { verifyScaffold, type VerifyResult } from './verify.js'
+
+/** A `.prisma` file (by extension or a `model X {` block) parses as Prisma; otherwise Drizzle. */
+function isPrismaSource(path: string, source: string): boolean {
+  return /\.prisma$/i.test(path) || /\bmodel\s+\w+\s*\{/.test(source)
+}
+
+export type StudioIO = {
+  /** Read a file; resolve to null when it doesn't exist. */
+  readFile: (path: string) => Promise<string | null>
+  /** Write a file, creating parent directories as needed. */
+  writeFile: (path: string, contents: string) => Promise<void>
+}
+
+export type AddOptions = ScaffoldOptions & {
+  /** Path to a Drizzle schema file to introspect. */
+  from?: string
+  /** Which table in the Drizzle file to use (defaults to the first). */
+  table?: string
+  /** Sample JSON rows to infer from, as an alternative to `from`. */
+  rows?: Array<Record<string, unknown>>
+  /** Entity name (required with `rows`, ignored with `from`). */
+  name?: string
+  /** A ready EntitySchema, bypassing introspection. */
+  schema?: EntitySchema
+}
+
+export type AddResult = {
+  schema: EntitySchema
+  /** Paths written, in order. */
+  written: string[]
+  verify: VerifyResult
+}
+
+/** Resolve an EntitySchema from whichever input was provided. */
+export async function resolveSchema(options: AddOptions, io: StudioIO): Promise<EntitySchema> {
+  if (options.schema) return options.schema
+  if (options.from) {
+    const src = await io.readFile(options.from)
+    if (src == null) throw new Error(`runStudioAdd: schema file not found: ${options.from}`)
+    return isPrismaSource(options.from, src)
+      ? introspectPrisma(src, options.table)
+      : introspectDrizzle(src, options.table)
+  }
+  if (options.rows) {
+    return introspectJson(options.name ?? options.route ?? 'entity', options.rows)
+  }
+  throw new Error('runStudioAdd: provide `from` (a Drizzle or Prisma schema file), `rows`, or `schema`')
+}
+
+/**
+ * Resolve **every** entity from a Drizzle or Prisma schema file (the `--all
+ * --from` path), linked so foreign keys become working relation lookups.
+ */
+export async function resolveSchemas(from: string, io: StudioIO): Promise<EntitySchema[]> {
+  const src = await io.readFile(from)
+  if (src == null) throw new Error(`runStudioAddApp: schema file not found: ${from}`)
+  return isPrismaSource(from, src) ? introspectPrismaAll(src) : introspectDrizzleAll(src)
+}
+
+/** Merge-write a set of generated files, preserving user edits outside managed regions. */
+async function writeAll(files: { path: string; contents: string }[], io: StudioIO): Promise<string[]> {
+  const written: string[] = []
+  for (const file of files) {
+    const existing = await io.readFile(file.path)
+    // Regenerating? Replace only the managed region, keep the user's edits.
+    await io.writeFile(file.path, mergeManaged(existing, file.contents))
+    written.push(file.path)
+  }
+  return written
+}
+
+export async function runStudioAdd(options: AddOptions, io: StudioIO): Promise<AddResult> {
+  const schema = await resolveSchema(options, io)
+  const { files } = scaffold(schema, options)
+  const written = await writeAll(files, io)
+  const verify = await verifyScaffold(files)
+  return { schema, written, verify }
+}
+
+export type AddAppResult = { written: string[]; verify: VerifyResult }
+
+/**
+ * Scaffold a whole multi-entity app - every entity's screen plus a nav layout
+ * and home page - and merge-write it. The `--all` path behind `svgrid-studio`.
+ */
+export async function runStudioAddApp(
+  schemas: EntitySchema[],
+  options: ScaffoldAppOptions,
+  io: StudioIO,
+): Promise<AddAppResult> {
+  const { files } = scaffoldApp(schemas, options)
+  const written = await writeAll(files, io)
+  const verify = await verifyScaffold(files)
+  return { written, verify }
+}

package/src/studio/csv.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect } from 'vitest'
+import { parseCsv, detectDelimiter, csvToEntity } from './csv.js'
+
+describe('parseCsv', () => {
+  it('parses a simple grid', () => {
+    expect(parseCsv('a,b,c\n1,2,3\n4,5,6')).toEqual([
+      ['a', 'b', 'c'],
+      ['1', '2', '3'],
+      ['4', '5', '6'],
+    ])
+  })
+
+  it('handles quoted fields, commas, escaped quotes, and embedded newlines', () => {
+    const text = 'name,note\n"Doe, John","said ""hi"""\n"Ada","line1\nline2"'
+    expect(parseCsv(text)).toEqual([
+      ['name', 'note'],
+      ['Doe, John', 'said "hi"'],
+      ['Ada', 'line1\nline2'],
+    ])
+  })
+
+  it('auto-detects the delimiter (semicolon / tab / pipe), ignoring quoted separators', () => {
+    expect(detectDelimiter('a;b;c\n1;2;3')).toBe(';')
+    expect(detectDelimiter('a\tb\tc\n1\t2\t3')).toBe('\t')
+    expect(detectDelimiter('a|b|c')).toBe('|')
+    expect(detectDelimiter('a,b,c')).toBe(',')
+    // A comma inside a quoted header field must not sway a semicolon file.
+    expect(detectDelimiter('"a,x";b;c\n1;2;3')).toBe(';')
+  })
+
+  it('parses a semicolon-delimited (European/Excel) file', () => {
+    expect(parseCsv('name;amount\n"Doe; John";1.200')).toEqual([
+      ['name', 'amount'],
+      ['Doe; John', '1.200'],
+    ])
+  })
+
+  it('handles CRLF and a trailing newline, and strips a BOM', () => {
+    expect(parseCsv('a,b\r\n1,2\r\n')).toEqual([
+      ['a', 'b'],
+      ['1', '2'],
+    ])
+  })
+})
+
+describe('csvToEntity', () => {
+  it('infers types per column and coerces values', () => {
+    const csv = 'id,name,mrr,active,joined\n1,Ada,1200,true,2024-01-02\n2,Alan,240.5,no,2024-03-04'
+    const { schema, rows } = csvToEntity('customers', csv)
+    const t = Object.fromEntries(schema.fields.map((f) => [f.field, f.type]))
+    expect(t).toEqual({ id: 'number', name: 'text', mrr: 'number', active: 'boolean', joined: 'dateString' })
+    expect(rows[0]).toEqual({ id: 1, name: 'Ada', mrr: 1200, active: true, joined: '2024-01-02' })
+    expect(rows[1]!.mrr).toBe(240.5)
+    expect(rows[1]!.active).toBe(false)
+  })
+
+  it('marks an existing id column as the primary key', () => {
+    const { schema } = csvToEntity('t', 'id,name\n1,a')
+    const id = schema.fields.find((f) => f.field === 'id')!
+    expect(id.primaryKey).toBe(true)
+    expect(id.readonly).toBe(true)
+  })
+
+  it('synthesizes a string id when none is present', () => {
+    const { schema, rows } = csvToEntity('t', 'name,city\nAda,London\nAlan,Leeds')
+    const id = schema.fields.find((f) => f.field === 'id')!
+    expect(id.primaryKey).toBe(true)
+    expect(rows.map((r) => r.id)).toEqual(['1', '2'])
+    expect(rows[0]).toMatchObject({ id: '1', name: 'Ada', city: 'London' })
+  })
+
+  it('renames unsafe headers to safe keys and reports them', () => {
+    const { schema, renamed, rows } = csvToEntity('t', 'First Name,E-mail Address\nAda,ada@x.io')
+    const keys = schema.fields.map((f) => f.field)
+    expect(keys).toContain('first_name')
+    expect(keys).toContain('e_mail_address')
+    expect(renamed.map((r) => r.field)).toEqual(expect.arrayContaining(['first_name', 'e_mail_address']))
+    expect(rows[0]).toMatchObject({ first_name: 'Ada', e_mail_address: 'ada@x.io' })
+  })
+
+  it('treats empty cells as null and parses thousands separators', () => {
+    const { rows } = csvToEntity('t', 'id,amount\n1,"1,200"\n2,')
+    expect(rows[0]!.amount).toBe(1200)
+    expect(rows[1]!.amount).toBeNull()
+  })
+
+  it('returns an empty entity for empty input', () => {
+    expect(csvToEntity('t', '').rows).toEqual([])
+  })
+})

package/src/studio/csv.ts

@@ -0,0 +1,165 @@
+/**
+ * CSV / spreadsheet import - turn a pasted or uploaded CSV into a runnable
+ * entity: infer an `EntitySchema` from the header + values, and return the
+ * parsed rows (coerced to real JS types) so they can seed a data source.
+ *
+ * Pure and dependency-free: a hand-rolled RFC-4180-ish reader (quoted fields,
+ * escaped `""`, embedded newlines, CRLF), then per-column type inference. The
+ * Studio generator and the visual designer both call `csvToEntity` to add a
+ * table from a file the user drops in - no backend, no parsing library.
+ */
+import type { EntityField, EntityFieldType, EntitySchema } from '../schema.js'
+import { refineFields } from '../sources/field-inference.js'
+
+/**
+ * Sniff the field delimiter from the first (unquoted) line: whichever of
+ * `,` `;` `\t` `|` occurs most. Handles Excel/European exports (`;`) and TSV.
+ */
+export function detectDelimiter(text: string): ',' | ';' | '\t' | '|' {
+  const s = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text
+  const firstLine = s.slice(0, (s.indexOf('\n') + 1 || s.length + 1) - 1)
+  const candidates: Array<',' | ';' | '\t' | '|'> = [',', ';', '\t', '|']
+  let best: ',' | ';' | '\t' | '|' = ','
+  let bestCount = -1
+  for (const d of candidates) {
+    // Count only outside quotes so a comma inside "a,b" doesn't sway the guess.
+    let count = 0, inQ = false
+    for (const ch of firstLine) {
+      if (ch === '"') inQ = !inQ
+      else if (ch === d && !inQ) count++
+    }
+    if (count > bestCount) { bestCount = count; best = d }
+  }
+  return best
+}
+
+/** Parse CSV/TSV text into a matrix of string cells. Handles quotes, `""`, embedded
+ *  newlines, CRLF, and auto-detects the delimiter (comma / semicolon / tab / pipe). */
+export function parseCsv(text: string, delimiter?: string): string[][] {
+  const delim = delimiter ?? detectDelimiter(text)
+  const rows: string[][] = []
+  let row: string[] = []
+  let field = ''
+  let inQuotes = false
+  // Strip a UTF-8 BOM if present so the first header isn't polluted.
+  const s = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i]
+    if (inQuotes) {
+      if (c === '"') {
+        if (s[i + 1] === '"') { field += '"'; i++ } // escaped quote
+        else inQuotes = false
+      } else field += c
+    } else if (c === '"') {
+      inQuotes = true
+    } else if (c === delim) {
+      row.push(field); field = ''
+    } else if (c === '\n') {
+      row.push(field); field = ''; rows.push(row); row = []
+    } else if (c === '\r') {
+      // swallow; the paired \n (or EOF) ends the row
+    } else {
+      field += c
+    }
+  }
+  // Flush the trailing field/row (files without a final newline).
+  if (field !== '' || row.length > 0) { row.push(field); rows.push(row) }
+  // Drop fully-empty trailing rows (a blank final line).
+  return rows.filter((r) => !(r.length === 1 && r[0] === ''))
+}
+
+const TRUE_SET = new Set(['true', 'yes', 'y', '1'])
+const FALSE_SET = new Set(['false', 'no', 'n', '0'])
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/
+const DATETIME_RE = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/
+const NUMBER_RE = /^-?(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?$/ // 1200, -3.5, 1,200
+
+/** Coerce one raw cell to a JS value, given the column's inferred type. Empty -> null. */
+function coerce(raw: string, type: EntityFieldType): unknown {
+  const v = raw.trim()
+  if (v === '') return null
+  switch (type) {
+    case 'number': return Number(v.replace(/,/g, ''))
+    case 'boolean': return TRUE_SET.has(v.toLowerCase())
+    default: return v // text / date / datetime / json stay strings (grid + schema handle them)
+  }
+}
+
+/** Infer a column's type from all its non-empty raw values. Defaults to text. */
+function inferColumnType(values: string[]): EntityFieldType {
+  const nonEmpty = values.map((v) => v.trim()).filter((v) => v !== '')
+  if (nonEmpty.length === 0) return 'text'
+  const all = (pred: (v: string) => boolean) => nonEmpty.every(pred)
+  if (all((v) => NUMBER_RE.test(v))) return 'number'
+  if (all((v) => TRUE_SET.has(v.toLowerCase()) || FALSE_SET.has(v.toLowerCase()))) return 'boolean'
+  if (all((v) => DATETIME_RE.test(v))) return 'datetime'
+  if (all((v) => DATE_RE.test(v))) return 'dateString'
+  return 'text'
+}
+
+/** Turn a header string into a safe, camel-ish field key. */
+function toFieldKey(header: string, index: number, taken: Set<string>): string {
+  let key = header.trim().replace(/[^\w]+/g, '_').replace(/^_+|_+$/g, '').toLowerCase()
+  if (/^\d/.test(key)) key = 'col_' + key
+  if (!key) key = `col_${index + 1}`
+  let unique = key, n = 2
+  while (taken.has(unique)) unique = `${key}_${n++}`
+  taken.add(unique)
+  return unique
+}
+
+export type CsvEntity = {
+  schema: EntitySchema
+  rows: Array<Record<string, unknown>>
+  /** Fields whose header was renamed to a safe key (original -> key), for a UI note. */
+  renamed: Array<{ header: string; field: string }>
+}
+
+/**
+ * Parse CSV text into a ready-to-use entity: an `EntitySchema` (types inferred
+ * per column, an `id` primary key ensured) plus the coerced rows to seed with.
+ *
+ * If the file has no id-like column, a synthetic string `id` (`"1"`, `"2"`, ...)
+ * is added so the grid, edit form, and CRUD have a stable row key.
+ */
+export function csvToEntity(name: string, text: string): CsvEntity {
+  const matrix = parseCsv(text)
+  if (matrix.length === 0) return { schema: { name, fields: [] }, rows: [], renamed: [] }
+
+  const headers = matrix[0]!
+  const body = matrix.slice(1)
+  const taken = new Set<string>()
+  const renamed: Array<{ header: string; field: string }> = []
+  const cols = headers.map((h, i) => {
+    const field = toFieldKey(h, i, taken)
+    const values = body.map((r) => r[i] ?? '')
+    const type = inferColumnType(values)
+    if (field !== h.trim()) renamed.push({ header: h.trim() || `Column ${i + 1}`, field })
+    return { field, type, index: i }
+  })
+
+  const rows = body.map((r) => {
+    const obj: Record<string, unknown> = {}
+    for (const c of cols) obj[c.field] = coerce(r[c.index] ?? '', c.type)
+    return obj
+  })
+
+  // Ensure a primary key: reuse an existing id-like column, else synthesize one.
+  const idCol = cols.find((c) => c.field === 'id') ?? cols.find((c) => /(^|_)id$/.test(c.field))
+  if (!idCol) {
+    rows.forEach((row, i) => { row.id = String(i + 1) })
+    cols.unshift({ field: 'id', type: 'text', index: -1 })
+  }
+
+  const fields: EntityField[] = cols.map((c) => {
+    const f: EntityField = { field: c.field, type: c.type }
+    const isId = idCol ? c.field === idCol.field : c.field === 'id'
+    if (isId) { f.primaryKey = true; f.readonly = true }
+    return f
+  })
+
+  // Let introspectJson refine any 'json'/edge types from the actual coerced values,
+  // but keep our column types + pk decisions (they saw every row, not just the first).
+  const schema: EntitySchema = refineFields({ name, fields })
+  return { schema, rows, renamed }
+}

package/src/studio/db-connect-string.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildConnectionString,
+  parseConnectionString,
+  redactConnectionString,
+  isFileDialect,
+  DEFAULT_PORT,
+  DRIVER_PACKAGE,
+} from './db-connect-string'
+
+describe('buildConnectionString', () => {
+  it('builds a postgres URL with the default port', () => {
+    expect(buildConnectionString('postgres', { host: 'db.example.com', database: 'app', user: 'admin', password: 'secret' }))
+      .toBe('postgresql://admin:secret@db.example.com:5432/app')
+  })
+
+  it('percent-encodes credentials with reserved characters', () => {
+    const url = buildConnectionString('postgres', { host: 'h', database: 'd', user: 'a@b', password: 'p:w/d?' })
+    expect(url).toBe('postgresql://a%40b:p%3Aw%2Fd%3F@h:5432/d')
+    // ...and round-trips back to the raw values.
+    const parts = parseConnectionString('postgres', url)
+    expect(parts.user).toBe('a@b')
+    expect(parts.password).toBe('p:w/d?')
+  })
+
+  it('treats supabase as postgres', () => {
+    expect(buildConnectionString('supabase', { host: 'x', database: 'd', user: 'u', password: 'p' }))
+      .toBe('postgresql://u:p@x:5432/d')
+  })
+
+  it('uses mysql / mssql schemes and default ports', () => {
+    expect(buildConnectionString('mysql', { host: 'h', database: 'd', user: 'u', password: 'p' }))
+      .toBe('mysql://u:p@h:3306/d')
+    expect(buildConnectionString('mssql', { host: 'h', database: 'd', user: 'u', password: 'p' }))
+      .toBe('mssql://u:p@h:1433/d')
+  })
+
+  it('honours a custom port and omits empty auth / db', () => {
+    expect(buildConnectionString('postgres', { host: 'h', port: 6543 })).toBe('postgresql://h:6543')
+    expect(buildConnectionString('postgres', { host: 'h', port: '5432', user: 'u' })).toBe('postgresql://u@h:5432')
+  })
+
+  it('adds the correct SSL param per dialect', () => {
+    expect(buildConnectionString('postgres', { host: 'h', database: 'd', ssl: true })).toContain('?sslmode=require')
+    expect(buildConnectionString('mssql', { host: 'h', database: 'd', ssl: true })).toContain('encrypt=true')
+    expect(buildConnectionString('mysql', { host: 'h', database: 'd', ssl: true })).toContain('ssl=')
+  })
+
+  it('returns a bare file path for sqlite', () => {
+    expect(buildConnectionString('sqlite', { file: './data/app.db' })).toBe('./data/app.db')
+    expect(buildConnectionString('sqlite', { database: 'app.db' })).toBe('app.db')
+    expect(() => buildConnectionString('sqlite', {})).toThrow(/file path/)
+  })
+})
+
+describe('parseConnectionString', () => {
+  it('splits a URL back into form fields', () => {
+    expect(parseConnectionString('postgres', 'postgresql://u:p@host:5432/mydb?sslmode=require')).toEqual({
+      host: 'host', port: 5432, database: 'mydb', user: 'u', password: 'p', ssl: true,
+    })
+  })
+  it('treats a sqlite value as a file path', () => {
+    expect(parseConnectionString('sqlite', '/var/data/app.db')).toEqual({ file: '/var/data/app.db' })
+  })
+  it('returns {} for unparseable input', () => {
+    expect(parseConnectionString('postgres', 'not a url')).toEqual({})
+    expect(parseConnectionString('postgres', '')).toEqual({})
+  })
+})
+
+describe('redactConnectionString', () => {
+  it('masks the password in a URL', () => {
+    expect(redactConnectionString('postgresql://u:secret@h:5432/d')).toBe('postgresql://u:***@h:5432/d')
+  })
+  it('masks password= tokens in key/value strings', () => {
+    expect(redactConnectionString('Server=h;Database=d;User Id=u;Password=secret;'))
+      .toBe('Server=h;Database=d;User Id=u;Password=***;')
+  })
+  it('leaves passwordless strings untouched', () => {
+    expect(redactConnectionString('postgresql://h:5432/d')).toBe('postgresql://h:5432/d')
+    expect(redactConnectionString('./app.db')).toBe('./app.db')
+  })
+})
+
+describe('metadata tables', () => {
+  it('maps every dialect to a driver + default port', () => {
+    expect(DRIVER_PACKAGE.postgres).toBe('pg')
+    expect(DRIVER_PACKAGE.sqlite).toBe('better-sqlite3')
+    expect(DEFAULT_PORT.mysql).toBe(3306)
+    expect(DEFAULT_PORT.sqlite).toBeNull()
+    expect(isFileDialect('sqlite')).toBe(true)
+    expect(isFileDialect('postgres')).toBe(false)
+  })
+})