@svgrid/enterprise 2.2.1 → 2.3.1

package/src/studio/init-flow.test.ts

@@ -0,0 +1,239 @@
+import { describe, it, expect } from 'vitest'
+import { runStudioInit, parseSelection, type DbGateway, type PromptIO } from './init-flow.js'
+import type { StudioIO } from './cli.js'
+import { parseProject, validateProject, type GridConfig } from './project.js'
+
+/** A scripted terminal: answers are consumed in order, defaults fill the rest. */
+function scriptedPrompts(answers: string[]) {
+  const asked: string[] = []
+  const said: string[] = []
+  const queue = [...answers]
+  const io: PromptIO = {
+    ask: async (question, def) => {
+      asked.push(question)
+      const next = queue.shift()
+      return next === undefined ? (def ?? '') : next
+    },
+    say: (line) => said.push(line),
+  }
+  return { io, asked, said, get remaining() { return queue.length } }
+}
+
+/** An in-memory filesystem. */
+function memoryIo() {
+  const files = new Map<string, string>()
+  const io: StudioIO = {
+    readFile: async (path) => files.get(path) ?? null,
+    writeFile: async (path, contents) => { files.set(path, contents) },
+  }
+  return { io, files }
+}
+
+/** A fake Postgres holding two tables, answering the real catalog queries
+ *  (which alias their columns to name / type / nullable / pk). */
+function fakeDb(): DbGateway {
+  const columns: Record<string, { name: string; type: string; nullable: number; pk: number }[]> = {
+    customers: [
+      { name: 'id', type: 'integer', nullable: 0, pk: 1 },
+      { name: 'name', type: 'text', nullable: 0, pk: 0 },
+      { name: 'city', type: 'text', nullable: 1, pk: 0 },
+    ],
+    orders: [
+      { name: 'id', type: 'integer', nullable: 0, pk: 1 },
+      { name: 'total', type: 'numeric', nullable: 1, pk: 0 },
+    ],
+  }
+  return {
+    ensureDriver: async () => ({ ok: true }),
+    connect: async () => async (sql: string, params: unknown[]) => {
+      if (/count\(\*\)/i.test(sql)) return [{ n: 7 }]
+      if (/information_schema\.tables/i.test(sql)) return Object.keys(columns).map((name) => ({ name }))
+      if (/information_schema\.columns/i.test(sql)) return columns[String(params[0] ?? '')] ?? []
+      return [] // no foreign keys
+    },
+  }
+}
+
+describe('parseSelection', () => {
+  const items = ['customers', 'orders', 'invoices']
+
+  it('takes everything by default', () => {
+    expect(parseSelection('', items)).toEqual(items)
+    expect(parseSelection('all', items)).toEqual(items)
+    expect(parseSelection('*', items)).toEqual(items)
+  })
+
+  it('takes nothing for "none"', () => {
+    expect(parseSelection('none', items)).toEqual([])
+  })
+
+  it('accepts names, numbers, and a mix - without duplicates', () => {
+    expect(parseSelection('orders', items)).toEqual(['orders'])
+    expect(parseSelection('1, 3', items)).toEqual(['customers', 'invoices'])
+    expect(parseSelection('2, invoices', items)).toEqual(['orders', 'invoices'])
+    expect(parseSelection('orders, 2', items)).toEqual(['orders'])
+  })
+
+  it('ignores names and numbers that do not exist', () => {
+    expect(parseSelection('nope, 9, orders', items)).toEqual(['orders'])
+  })
+})
+
+describe('runStudioInit', () => {
+  it('builds a runnable app from a starter dataset with all defaults', async () => {
+    const prompts = scriptedPrompts([])
+    const fs = memoryIo()
+    const result = await runStudioInit({ yes: true }, prompts.io, null, fs.io)
+
+    expect(result.project.entities.length).toBeGreaterThanOrEqual(2)
+    expect(validateProject(result.project).filter((i) => i.level === 'error')).toEqual([])
+    expect(result.written).toContain('studio.config.json')
+    expect(result.written.some((p) => p.endsWith('package.json'))).toBe(true)
+    expect(result.written.some((p) => p.includes('+page.svelte'))).toBe(true)
+    // --yes asks nothing.
+    expect(prompts.asked).toEqual([])
+    // The written config re-parses into the same project.
+    expect(parseProject(fs.files.get('studio.config.json')!)).toEqual(result.project)
+  })
+
+  it('asks the questions in order when driven interactively', async () => {
+    const prompts = scriptedPrompts([
+      '1',        // source: sample data
+      '2',        // dataset: products & categories
+      'y',        // full CRUD suite
+      '1',        // editing: popup form
+      '1',        // theme
+      'n',        // dark mode
+      'Catalog',  // app name
+      '.',        // out dir
+    ])
+    const fs = memoryIo()
+    const result = await runStudioInit({}, prompts.io, null, fs.io)
+
+    expect(prompts.asked).toEqual([
+      'Pick a number:',   // source
+      'Pick a number:',   // dataset
+      '\nGenerate a list, an edit form and a record page for each table? (Y/n)',
+      'Pick a number:',   // editing mode
+      'Pick a number:',   // theme
+      'Dark mode? (y/N)',
+      '\nApp name:',
+      'Write it where?',
+    ])
+    expect(result.project.title).toBe('Catalog')
+    expect(result.project.entities.map((e) => e.name)).toEqual(['categories', 'products'])
+  })
+
+  it('honours the out directory', async () => {
+    const prompts = scriptedPrompts([])
+    const fs = memoryIo()
+    const result = await runStudioInit({ yes: true, out: 'apps/shop' }, prompts.io, null, fs.io)
+
+    expect(result.written.every((p) => p.startsWith('apps/shop/'))).toBe(true)
+    expect(result.nextSteps[0]).toBe('cd apps/shop')
+    expect(fs.files.has('apps/shop/studio.config.json')).toBe(true)
+  })
+
+  it('stores a dataset in PGlite when that source is picked', async () => {
+    const prompts = scriptedPrompts(['3', '1', 'y', '1', '1', 'n', 'Shop', '.'])
+    const fs = memoryIo()
+    const result = await runStudioInit({}, prompts.io, null, fs.io)
+
+    expect(result.project.dataSource).toBe('pglite')
+    const first = result.project.entities[0]!.name
+    expect(result.project.dataSources?.[first]).toMatchObject({ kind: 'pglite', table: first })
+    // The seed rides along, so the generated app boots with data.
+    expect((result.project.dataSources?.[first] as { seed?: unknown[] }).seed?.length).toBeGreaterThan(0)
+  })
+
+  it('reads tables from a live database', async () => {
+    const prompts = scriptedPrompts(['all', 'y', '1', '1', 'n', 'Ops', '.'])
+    const fs = memoryIo()
+    const result = await runStudioInit(
+      { db: 'postgres', url: 'postgres://localhost/app' },
+      prompts.io,
+      fakeDb(),
+      fs.io,
+    )
+
+    expect(result.project.entities.map((e) => e.name)).toEqual(['customers', 'orders'])
+    expect(result.project.dataSource).toBe('sql')
+    expect(result.project.dataSources?.customers).toEqual({ kind: 'sql', table: 'customers', dialect: 'postgres' })
+    // --db + --url skip the connection questions entirely.
+    expect(prompts.asked[0]).toBe('Which tables? (all, or a comma list of names/numbers)')
+  })
+
+  it('imports only the picked tables', async () => {
+    const prompts = scriptedPrompts(['orders', 'y', '1', '1', 'n', 'Ops', '.'])
+    const fs = memoryIo()
+    const result = await runStudioInit({ db: 'postgres', url: 'postgres://x' }, prompts.io, fakeDb(), fs.io)
+    expect(result.project.entities.map((e) => e.name)).toEqual(['orders'])
+  })
+
+  it('fails clearly when the driver cannot be installed', async () => {
+    const prompts = scriptedPrompts(['all'])
+    const fs = memoryIo()
+    const db: DbGateway = { ...fakeDb(), ensureDriver: async () => ({ ok: false, message: 'pg is not installed' }) }
+    await expect(runStudioInit({ db: 'postgres', url: 'postgres://x' }, prompts.io, db, fs.io))
+      .rejects.toThrow('pg is not installed')
+  })
+
+  it('fails clearly when no table is picked', async () => {
+    const prompts = scriptedPrompts(['none'])
+    const fs = memoryIo()
+    await expect(runStudioInit({ db: 'postgres', url: 'postgres://x' }, prompts.io, fakeDb(), fs.io))
+      .rejects.toThrow('No tables picked')
+  })
+
+  it('refuses a database when no gateway is available', async () => {
+    const prompts = scriptedPrompts([])
+    const fs = memoryIo()
+    await expect(runStudioInit({ db: 'postgres', url: 'postgres://x' }, prompts.io, null, fs.io))
+      .rejects.toThrow('not available here')
+  })
+
+  it('rejects an unknown dataset id by name', async () => {
+    const prompts = scriptedPrompts([])
+    const fs = memoryIo()
+    await expect(runStudioInit({ yes: true, dataset: 'nope' }, prompts.io, null, fs.io))
+      .rejects.toThrow(/Unknown dataset "nope"/)
+  })
+
+  it('builds an app from a REST endpoint', async () => {
+    const prompts = scriptedPrompts(['4', 'https://api.example.com/widgets', 'widgets', 'y', '1', '1', 'n', 'API app', '.'])
+    const fs = memoryIo()
+    const rows = JSON.stringify({ data: [{ id: 1, name: 'Widget', price: 9.5 }] })
+    const result = await runStudioInit({}, prompts.io, null, fs.io, async () => rows)
+
+    expect(result.project.entities.map((e) => e.name)).toEqual(['widgets'])
+    expect(result.project.dataSources?.widgets).toMatchObject({ kind: 'rest', baseUrl: 'https://api.example.com', path: 'widgets' })
+  })
+
+  it('applies the picked editing mode to the generated grids', async () => {
+    const prompts = scriptedPrompts(['1', '1', 'y', '2', '1', 'n', 'Inline', '.'])
+    const fs = memoryIo()
+    const result = await runStudioInit({}, prompts.io, null, fs.io)
+
+    const listScreen = result.project.screens.find((s) => s.id === result.project.entities[0]!.name)!
+    const grid = listScreen.blocks.find((b) => b.config.kind === 'grid')!.config as GridConfig
+    expect(grid.editing).toBe('inline')
+  })
+
+  it('applies the chosen theme', async () => {
+    const prompts = scriptedPrompts([])
+    const fs = memoryIo()
+    const result = await runStudioInit({ yes: true, theme: 'material', dark: true }, prompts.io, null, fs.io)
+    expect(result.project.theme?.preset).toBe('material')
+    expect(result.project.theme?.mode).toBe('dark')
+  })
+
+  it('keeps user-owned files that already exist', async () => {
+    const fs = memoryIo()
+    await runStudioInit({ yes: true }, scriptedPrompts([]).io, null, fs.io)
+    const handlers = [...fs.files.keys()].find((p) => p.endsWith('handlers.ts'))
+    if (!handlers) return // no user-owned companion in this project shape
+    fs.files.set(handlers, '// my own code')
+    await runStudioInit({ yes: true }, scriptedPrompts([]).io, null, fs.io)
+    expect(fs.files.get(handlers)).toBe('// my own code')
+  })
+})

package/src/studio/init-flow.ts

@@ -0,0 +1,358 @@
+/**
+ * runStudioInit - the guided "build a CRUD app" flow behind `svgrid-studio init`.
+ *
+ * Asks a handful of questions (where the data lives, which tables, which pages,
+ * what it looks like), then builds a project with `crudAppFromSchemas` - the same
+ * generator the designer's "New app" wizard uses - and writes a runnable app plus
+ * its `studio.config.json`.
+ *
+ * Prompts, the filesystem, and the database are all injected, so the orchestration
+ * is pure and unit-testable and this file stays node-free (no process / fs / driver
+ * imports). The CLI bin supplies readline, node:fs, and the DB drivers.
+ */
+import type { EntitySchema } from '../schema.js'
+import type { StudioIO } from './cli.js'
+import { crudAppFromSchemas, type CrudEditingMode, type CrudScreenKind, type CrudSuiteOptions } from './screen-suites.js'
+import { starterDatasets, getStarterDataset } from './samples/datasets.js'
+import { introspectDatabase, listDatabaseTables, countTableRows, type DbExecute, type SqlDialectName } from './introspect-db.js'
+import { introspectOpenApi } from './introspect-openapi.js'
+import { introspectJson } from './introspect.js'
+import { buildConnectionString, isFileDialect, type SqlConnectionParts } from './db-connect-string.js'
+import { emitStudioAppBundle } from './emit-project.js'
+import { mergeManaged, skipUserOwned } from './scaffold.js'
+import { getStudioTheme, studioThemes } from './themes.js'
+import { serializeProject, type DataSourceKind, type EntityDataSource, type ProjectTheme, type StudioProject } from './project.js'
+
+/** Terminal I/O, injected so the flow can be scripted in tests. */
+export type PromptIO = {
+  /** Ask a question; `def` is used when the user just hits Enter. */
+  ask: (question: string, def?: string) => Promise<string>
+  /** Print a line (progress, headings, results). */
+  say: (line: string) => void
+}
+
+/** Live-database access, injected by the bin (drivers are node-only). */
+export type DbGateway = {
+  /** Make sure the dialect's driver is installed; report why not if it isn't. */
+  ensureDriver: (dialect: SqlDialectName) => Promise<{ ok: boolean; message?: string }>
+  connect: (dialect: SqlDialectName, url: string) => Promise<DbExecute>
+}
+
+/** Read a REST endpoint or an OpenAPI document (injected: the bin uses fetch/fs). */
+export type FetchText = (source: string) => Promise<string>
+
+export type InitFlags = {
+  /** Where to write the app. Default `.`. */
+  out?: string
+  /** Skip the source question and go straight to a live database. */
+  db?: SqlDialectName
+  /** Connection string for `db`. */
+  url?: string
+  /** Pick a starter dataset by id, skipping the source question. */
+  dataset?: string
+  /** Theme preset id. */
+  theme?: string
+  dark?: boolean
+  /** App title (skips the question). */
+  title?: string
+  /** Take every default; ask nothing that has one. */
+  yes?: boolean
+}
+
+export type InitResult = {
+  project: StudioProject
+  /** Paths written, in order. */
+  written: string[]
+  /** What to tell the user to do next. */
+  nextSteps: string[]
+}
+
+const SOURCES = [
+  { key: 'sample', label: 'Sample data', hint: 'a seeded pair of related tables - see a working app immediately' },
+  { key: 'db', label: 'An existing database', hint: 'Postgres, MySQL, SQL Server or SQLite - reads your tables' },
+  { key: 'pglite', label: 'Local Postgres in the browser (PGlite)', hint: 'real SQL, persists, no server to set up' },
+  { key: 'rest', label: 'A REST API or OpenAPI spec', hint: 'infers the tables from the endpoint' },
+] as const
+type SourceKey = (typeof SOURCES)[number]['key']
+
+const DIALECTS: SqlDialectName[] = ['postgres', 'supabase', 'mysql', 'mssql', 'sqlite']
+
+/** Ask a numbered-list question; returns the chosen index. */
+async function pick(prompts: PromptIO, heading: string, items: { label: string; hint?: string }[], def = 1): Promise<number> {
+  prompts.say('')
+  prompts.say(heading)
+  items.forEach((item, i) => prompts.say(`  ${i + 1}. ${item.label}${item.hint ? ` - ${item.hint}` : ''}`))
+  const answer = (await prompts.ask('Pick a number:', String(def))).trim()
+  const n = Number(answer)
+  return Number.isFinite(n) && n >= 1 && n <= items.length ? n - 1 : def - 1
+}
+
+const isYes = (answer: string, def: boolean): boolean => {
+  const a = answer.trim().toLowerCase()
+  if (!a) return def
+  return a === 'y' || a === 'yes'
+}
+
+/** Parse "all", "none", a comma list of names, or a list of 1-based numbers. */
+export function parseSelection(answer: string, items: string[]): string[] {
+  const raw = answer.trim()
+  if (!raw || raw.toLowerCase() === 'all' || raw === '*') return items
+  if (raw.toLowerCase() === 'none') return []
+  const picked: string[] = []
+  for (const part of raw.split(',').map((p) => p.trim()).filter(Boolean)) {
+    const n = Number(part)
+    if (Number.isFinite(n) && n >= 1 && n <= items.length) {
+      const item = items[n - 1]!
+      if (!picked.includes(item)) picked.push(item)
+      continue
+    }
+    const match = items.find((i) => i.toLowerCase() === part.toLowerCase())
+    if (match && !picked.includes(match)) picked.push(match)
+  }
+  return picked
+}
+
+/** The rows of a REST response: a bare array, or the usual wrapper key. */
+function unwrapRows(body: unknown): Record<string, unknown>[] {
+  if (Array.isArray(body)) return body as Record<string, unknown>[]
+  if (body && typeof body === 'object') {
+    for (const key of ['data', 'items', 'results', 'rows', 'records']) {
+      const v = (body as Record<string, unknown>)[key]
+      if (Array.isArray(v)) return v as Record<string, unknown>[]
+    }
+    return [body as Record<string, unknown>]
+  }
+  return []
+}
+
+type Gathered = {
+  schemas: EntitySchema[]
+  sources: Record<string, EntityDataSource>
+  seed: Record<string, Record<string, unknown>[]>
+  kind: DataSourceKind
+  title?: string
+}
+
+/** Step 1-2: where does the data come from, and what tables does it have? */
+async function gatherData(flags: InitFlags, prompts: PromptIO, db: DbGateway | null, fetchText: FetchText | null): Promise<Gathered> {
+  let source: SourceKey = 'sample'
+  if (flags.db) source = 'db'
+  else if (flags.dataset) source = 'sample'
+  else if (!flags.yes) source = SOURCES[await pick(prompts, 'Where should the app get its data?', [...SOURCES])]!.key
+
+  if (source === 'db') return gatherFromDatabase(flags, prompts, db)
+  if (source === 'rest') return gatherFromRest(prompts, fetchText)
+
+  // Sample data, stored in memory or in PGlite.
+  let datasetId = flags.dataset ?? starterDatasets[0]!.id
+  if (!flags.dataset && !flags.yes) {
+    const i = await pick(prompts, 'Pick a starter dataset:', starterDatasets.map((d) => ({ label: d.name, hint: d.description })))
+    datasetId = starterDatasets[i]!.id
+  }
+  const dataset = getStarterDataset(datasetId)
+  if (!dataset) throw new Error(`Unknown dataset "${datasetId}". Try: ${starterDatasets.map((d) => d.id).join(', ')}`)
+  const { entities, seed } = dataset.build()
+  const kind: DataSourceKind = source === 'pglite' ? 'pglite' : 'memory'
+  const sources: Record<string, EntityDataSource> = {}
+  for (const e of entities) sources[e.name] = kind === 'pglite' ? { kind: 'pglite', table: e.name } : { kind: 'memory' }
+  prompts.say(`  Using ${dataset.name} (${entities.length} tables).`)
+  return { schemas: entities, sources, seed, kind, title: dataset.name }
+}
+
+async function gatherFromDatabase(flags: InitFlags, prompts: PromptIO, db: DbGateway | null): Promise<Gathered> {
+  if (!db) throw new Error('Connecting to a database is not available here.')
+  let dialect = flags.db
+  if (!dialect) {
+    const i = await pick(prompts, 'Which database?', DIALECTS.map((d) => ({ label: d })))
+    dialect = DIALECTS[i]!
+  }
+  let url = flags.url ?? ''
+  if (!url) {
+    if (isFileDialect(dialect)) {
+      url = (await prompts.ask('Database file:', './data.db')).trim()
+    } else {
+      const answer = (await prompts.ask('Connection string (blank to enter host/port instead):', '')).trim()
+      url = answer || buildConnectionString(dialect, await askConnectionParts(prompts))
+    }
+  }
+  if (!url) throw new Error('A connection string is required.')
+
+  const driver = await db.ensureDriver(dialect)
+  if (!driver.ok) throw new Error(driver.message ?? `Could not install the ${dialect} driver.`)
+
+  prompts.say('  Connecting...')
+  const execute = await db.connect(dialect, url)
+  const tables = await listDatabaseTables(dialect, execute)
+  if (tables.length === 0) throw new Error('Connected, but the database has no tables.')
+
+  const counts = await countTableRows(dialect, execute, tables)
+  prompts.say('')
+  prompts.say(`Found ${tables.length} ${tables.length === 1 ? 'table' : 'tables'}:`)
+  counts.forEach((t, i) => prompts.say(`  ${i + 1}. ${t.name}${t.rows == null ? '' : ` (${t.rows} rows)`}`))
+  const answer = flags.yes ? 'all' : await prompts.ask('Which tables? (all, or a comma list of names/numbers)', 'all')
+  const picked = parseSelection(answer, tables)
+  if (picked.length === 0) throw new Error('No tables picked - nothing to build.')
+
+  const schemas: EntitySchema[] = []
+  const sources: Record<string, EntityDataSource> = {}
+  for (const table of picked) {
+    try {
+      const schema = await introspectDatabase({ dialect, table, execute })
+      schemas.push(schema)
+      sources[schema.name] = { kind: 'sql', table, dialect }
+    } catch (e) {
+      // One unreadable table must never sink the run.
+      prompts.say(`  ! Skipped ${table}: ${e instanceof Error ? e.message : String(e)}`)
+    }
+  }
+  if (schemas.length === 0) throw new Error('None of the picked tables could be read.')
+  prompts.say(`  Read ${schemas.length} ${schemas.length === 1 ? 'table' : 'tables'}.`)
+  return { schemas, sources, seed: {}, kind: 'sql' }
+}
+
+async function askConnectionParts(prompts: PromptIO): Promise<SqlConnectionParts> {
+  return {
+    host: (await prompts.ask('Host:', 'localhost')).trim(),
+    port: (await prompts.ask('Port:', '')).trim(),
+    database: (await prompts.ask('Database:', 'app')).trim(),
+    user: (await prompts.ask('User:', 'postgres')).trim(),
+    password: (await prompts.ask('Password:', '')).trim(),
+  }
+}
+
+async function gatherFromRest(prompts: PromptIO, fetchText: FetchText | null): Promise<Gathered> {
+  if (!fetchText) throw new Error('Reading a REST endpoint is not available here.')
+  const src = (await prompts.ask('OpenAPI spec (file or URL), or a REST endpoint returning rows:', '')).trim()
+  if (!src) throw new Error('A spec path/URL or endpoint is required.')
+  const text = await fetchText(src)
+
+  // An OpenAPI document describes every resource; a plain endpoint gives one.
+  if (/"(openapi|swagger|paths)"\s*:/.test(text)) {
+    const { entities, sources, warnings } = introspectOpenApi(text)
+    for (const w of warnings) prompts.say(`  ! ${w}`)
+    if (entities.length === 0) throw new Error('The spec described no collection resources.')
+    prompts.say(`  Read ${entities.length} REST ${entities.length === 1 ? 'resource' : 'resources'}.`)
+    return { schemas: entities, sources, seed: {}, kind: 'rest' }
+  }
+
+  const rows = unwrapRows(JSON.parse(text) as unknown)
+  if (rows.length === 0) throw new Error('The endpoint returned no rows to read a shape from.')
+  const url = new URL(src)
+  const path = url.pathname.replace(/^\/+|\/+$/g, '')
+  const suggested = path.split('/').filter(Boolean).pop() || 'items'
+  const name = ((await prompts.ask('Table name:', suggested)).trim() || suggested).replace(/\W+/g, '_')
+  const schema = introspectJson(name, rows)
+  prompts.say(`  Read ${schema.fields.length} fields from ${rows.length} rows.`)
+  return {
+    schemas: [schema],
+    sources: { [name]: { kind: 'rest', baseUrl: url.origin, path, method: 'GET', params: [] } },
+    seed: {},
+    kind: 'rest',
+  }
+}
+
+/** Step 3: which pages does each table get, and how are rows edited? */
+async function askScreens(schemas: EntitySchema[], flags: InitFlags, prompts: PromptIO): Promise<Record<string, CrudSuiteOptions>> {
+  const perEntity: Record<string, CrudSuiteOptions> = {}
+  let editing: CrudEditingMode = 'form'
+  let full = true
+
+  if (!flags.yes) {
+    full = isYes(await prompts.ask('\nGenerate a list, an edit form and a record page for each table? (Y/n)', 'y'), true)
+    const modes: { label: string; value: CrudEditingMode }[] = [
+      { label: 'A popup form', value: 'form' },
+      { label: 'In the grid (like a spreadsheet)', value: 'inline' },
+      { label: 'On the record page', value: 'detail' },
+    ]
+    editing = modes[await pick(prompts, 'How should rows be edited?', modes)]!.value
+  }
+
+  for (const schema of schemas) {
+    const hasChildren = schemas.some((e) => e.fields.some((f) => f.type === 'relation' && f.relation?.entity === schema.name))
+    const screens: CrudScreenKind[] = full
+      ? hasChildren || editing === 'detail' ? ['list', 'form', 'detail'] : ['list', 'form']
+      : ['list']
+    perEntity[schema.name] = { screens, editing }
+  }
+  return perEntity
+}
+
+/** Step 4: the app's look. */
+async function askTheme(flags: InitFlags, prompts: PromptIO): Promise<ProjectTheme | undefined> {
+  let preset = flags.theme?.trim().toLowerCase()
+  if (preset && !getStudioTheme(preset)) {
+    prompts.say(`  ! Unknown theme "${preset}" - using tailwind.`)
+    preset = undefined
+  }
+  if (!preset && !flags.yes) {
+    const i = await pick(prompts, 'Theme:', studioThemes.map((t) => ({ label: t.name, hint: t.id })))
+    preset = studioThemes[i]?.id
+  }
+  preset ??= 'tailwind'
+  const dark = flags.dark ?? (flags.yes ? false : isYes(await prompts.ask('Dark mode? (y/N)', 'n'), false))
+  return { preset, mode: dark ? 'dark' : 'light' }
+}
+
+/** Merge-write the generated files, preserving edits outside managed regions. */
+async function writeAll(files: { path: string; contents: string; userOwned?: boolean }[], outDir: string, io: StudioIO): Promise<string[]> {
+  const written: string[] = []
+  const prefix = !outDir || outDir === '.' ? '' : outDir.replace(/[\\/]+$/, '') + '/'
+  for (const file of files) {
+    const path = prefix + file.path
+    const existing = await io.readFile(path)
+    if (skipUserOwned(file, existing != null)) continue
+    await io.writeFile(path, mergeManaged(existing, file.contents))
+    written.push(path)
+  }
+  return written
+}
+
+/**
+ * The whole guided flow: ask, build, write. Returns the project and what was
+ * written so the caller can print next steps (or assert them in a test).
+ */
+export async function runStudioInit(
+  flags: InitFlags,
+  prompts: PromptIO,
+  db: DbGateway | null,
+  io: StudioIO,
+  fetchText: FetchText | null = null,
+): Promise<InitResult> {
+  prompts.say('SvGrid Studio - let\'s build your app.')
+
+  const data = await gatherData(flags, prompts, db, fetchText)
+  const perEntity = await askScreens(data.schemas, flags, prompts)
+  const theme = await askTheme(flags, prompts)
+
+  const defaultTitle = flags.title ?? data.title ?? 'My app'
+  const title = flags.yes || flags.title ? defaultTitle : (await prompts.ask('\nApp name:', defaultTitle)).trim() || defaultTitle
+  const outDir = flags.out ?? (flags.yes ? '.' : (await prompts.ask('Write it where?', '.')).trim() || '.')
+
+  const project = crudAppFromSchemas(data.schemas, {
+    title,
+    dataSource: data.kind,
+    sources: data.sources,
+    seed: data.seed,
+    perEntity,
+    overviewDashboard: true,
+    ...(theme ? { theme } : {}),
+  })
+
+  const files = emitStudioAppBundle(project)
+  const written = await writeAll(files, outDir, io)
+  // The design itself, so `svgrid-studio designer` reopens exactly this app.
+  const configPath = (!outDir || outDir === '.' ? '' : outDir.replace(/[\\/]+$/, '') + '/') + 'studio.config.json'
+  await io.writeFile(configPath, serializeProject(project))
+  written.push(configPath)
+
+  prompts.say('')
+  prompts.say(`Built "${title}": ${data.schemas.length} ${data.schemas.length === 1 ? 'table' : 'tables'}, ${project.screens.length} screens, ${written.length} files.`)
+
+  const nextSteps = [
+    ...(outDir && outDir !== '.' ? [`cd ${outDir}`] : []),
+    'npm install',
+    'npm run dev',
+    'svgrid-studio designer   # keep editing it visually',
+  ]
+  return { project, written, nextSteps }
+}