@svgrid/enterprise 2.3.0 → 2.3.2

package/src/studio/emit-schema.ts

@@ -10,7 +10,7 @@
  * build. It targets the template's conventions: `$lib/EntityScreen.svelte`,
  * `$lib/schemas`, `$lib/data`, and the `st-*` / `.home` CSS classes.
  */
-import { resolveIdField, titleCase, type EntityField, type EntityFieldType, type EntitySchema, type ValidationRuleSpec } from '../schema.js'
+import { resolveIdField, titleCase, type EntityField, type EntitySchema, type ValidationRuleSpec } from '../schema.js'
 import type { GeneratedFile } from './scaffold.js'
 import type { EntityDataSource, RestAdapterConfig, RestSource, ShellConfig, ShellStyle, SqlDialectKind, SqlSource, EntityTriggers, TriggerEvent } from './project.js'
 import { sanitizeClassName, compileTriggerSteps, TRIGGER_EVENTS } from './project.js'
@@ -362,17 +362,19 @@ const SQL_DRIVERS: Record<'postgres' | 'mysql' | 'mssql' | 'sqlite' | 'turso', {
  *  the route imports the shared access policy and rejects unauthorized writes -
  *  server-enforced, so a tampered client can't bypass it. When audit is on, every
  *  successful write is recorded. */
-function sqlRouteFile(schema: EntitySchema, table: string, dialect?: SqlDialectKind, feat: { access?: boolean; audit?: boolean; screenIds?: string[]; triggers?: EntityTriggers; dbSchema?: string } = {}): GeneratedFile {
+function sqlRouteFile(schema: EntitySchema, table: string, dialect?: SqlDialectKind, feat: { access?: boolean; audit?: boolean; screenIds?: string[]; triggers?: EntityTriggers; dbSchema?: string; tenantField?: string } = {}): GeneratedFile {
   const n = namesFor(schema)
   const key = (dialect === 'supabase' ? 'postgres' : (dialect ?? 'postgres')) as 'postgres' | 'mysql' | 'mssql' | 'sqlite' | 'turso'
   const driver = SQL_DRIVERS[key]
   const dialectLiteral = sqlDialectExpr(dialect)
   const accessImport = feat.access ? `\nimport { authorizeAction, getServerRole } from '$lib/access'` : ''
   const auditImport = feat.audit ? `\nimport { recordAudit } from '$lib/audit'` : ''
+  const tenantImport = feat.tenantField ? `\nimport { requireTenant } from '$lib/server/tenant'` : ''
   // Every connected route validates writes against the schema server-side, and
   // (when enabled) authorizes them by role + records an audit entry.
   const opts = [`schema: ${n.schemaVar}`, `source`, `validate: true`]
   if (feat.access) opts.push(`// Server-enforced RBAC: the caller's role comes from the session (event.locals). Reads\n  // are allowed only if the role can open one of this entity's own screens.\n  authorize: ({ action, event }) => authorizeAction(getServerRole(event), action, ${JSON.stringify(feat.screenIds ?? [])})`)
+  if (feat.tenantField) opts.push(`// Multi-tenancy, enforced server-side: reads are filtered to the caller's tenant,\n  // creates are stamped with it, and update/delete re-read the target under the\n  // scope first - so a guessed id cannot reach another tenant's row.\n  scope: ({ event }) => ({ field: ${JSON.stringify(feat.tenantField)}, value: requireTenant(event) })`)
   if (feat.audit) opts.push(`// Record every successful write to the audit trail.\n  audit: (e) => recordAudit({ entity: ${JSON.stringify(schema.name)}, action: e.action, recordId: e.id, values: e.values as Record<string, unknown> | undefined, actor: String(e.event.locals?.role ?? e.event.locals?.user ?? 'system') })`)
   // Server-enforced business rules: the entity's triggers compiled to lifecycle hooks.
   const hooks = triggerHooksOpt(feat.triggers)
@@ -384,7 +386,7 @@ function sqlRouteFile(schema: EntitySchema, table: string, dialect?: SqlDialectK
     contents: `${driver.imports}
 import { env } from '$env/dynamic/private'
 import { createKitHandlers, createSqlDataSource } from '@svgrid/enterprise'
-import { ${n.schemaVar}, type ${n.type} } from '$lib/schemas'${accessImport}${auditImport}
+import { ${n.schemaVar}, type ${n.type} } from '$lib/schemas'${accessImport}${auditImport}${tenantImport}
 
 ${driver.setup}
 
@@ -737,7 +739,7 @@ export function layoutFile(nav: NavItem[], opts: { accent?: string; shell?: Shel
 
   // i18n: translate nav labels via `nav.<id>` keys (Home has no id -> literal).
   const navLabel = opts.i18n ? `{item.id ? $t('nav.' + item.id, item.label) : item.label}` : '{item.label}'
-  const anchor = `<a class="sv-app__link" class:is-active={$page.url.pathname === item.href} href={item.href}>${navLabel}</a>`
+  const anchor = `<a class="sv-app__link" class:is-active={page.url.pathname === item.href} href={item.href}>${navLabel}</a>`
   // When RBAC is on, hide nav links the current role can't open.
   const linkGate = opts.access
     ? `{#if !item.id || canScreen($currentRole, item.id)}${anchor}{/if}`
@@ -968,14 +970,14 @@ export function layoutFile(nav: NavItem[], opts: { accent?: string; shell?: Shel
     contents: `<script lang="ts">
   import '../app.css'
   import '../custom.css'
-  import { page } from '$app/stores'${opts.access ? `\n  import { currentRole, canScreen } from '$lib/access'` : ''}${opts.i18n ? `\n  import { t, currentLocale, locales } from '$lib/i18n'` : ''}${opts.auth ? `\n  import type { LayoutData } from './$types'` : ''}${opts.supabaseAuth ? `\n  import { SvAuthGate, type SupabaseAuthClientLike } from '@svgrid/enterprise'\n  import { supabaseClient } from '$lib/connections'` : ''}
+  import { page } from '$app/state'${opts.access ? `\n  import { currentRole, canScreen } from '$lib/access'` : ''}${opts.i18n ? `\n  import { t, currentLocale, locales } from '$lib/i18n'` : ''}${opts.auth ? `\n  import type { LayoutData } from './$types'` : ''}${opts.supabaseAuth ? `\n  import { SvAuthGate, type SupabaseAuthClientLike } from '@svgrid/enterprise'\n  import { supabaseClient } from '$lib/connections'` : ''}
 
   let { children${opts.auth ? ', data' : ''} }${opts.auth ? ": { children: import('svelte').Snippet; data: LayoutData }" : ''} = $props()
   const nav = ${JSON.stringify(links)}
   const brand = ${JSON.stringify(brand)}${footConst}${logoConst}
   let navOpen = $state(false)${opts.auth && opts.access ? `\n  // Seed the client role store from the signed-in session (server-resolved).\n  $effect(() => { if (data?.role) currentRole.set(data.role as never) })` : ''}
   // Close the mobile drawer whenever the route changes.
-  $effect(() => { void $page.url.pathname; navOpen = false })${hasSwitch ? `
+  $effect(() => { void page.url.pathname; navOpen = false })${hasSwitch ? `
   // Light/dark switcher: defaults to the mode picked in Studio, then honours the
   // visitor's saved choice. Applies via [data-theme] on <html> (see the token
   // sets in <svelte:head>), and persists per browser.
@@ -1014,11 +1016,11 @@ export function layoutFile(nav: NavItem[], opts: { accent?: string; shell?: Shel
     return () => window.removeEventListener('keydown', onKey)
   })
   // Close both menus on route change.
-  $effect(() => { void $page.url.pathname; bellOpen = false; menuOpen = false })` : ''}
+  $effect(() => { void page.url.pathname; bellOpen = false; menuOpen = false })` : ''}
 </script>
 ${themeHead}
 
-${opts.auth ? `{#if ${JSON.stringify(opts.authRoutes ?? ['/login'])}.includes($page.url.pathname)}
+${opts.auth ? `{#if ${JSON.stringify(opts.authRoutes ?? ['/login'])}.includes(page.url.pathname)}
 {@render children()}
 {:else}
 ${body}
@@ -1137,7 +1139,7 @@ export function prepareEntities(schemas: EntitySchema[]): { entries: Prepared[];
 /** Emit the shared entity modules: `src/lib/schemas.ts` + `src/lib/data.ts` (+ `connections.ts`). */
 export function emitEntityModules(
   schemas: EntitySchema[],
-  opts: { sources?: Record<string, EntityDataSource>; accessEnabled?: boolean; auditEnabled?: boolean; screensByEntity?: Map<string, string[]>; triggers?: Record<string, EntityTriggers>; supabaseConn?: { url?: string; key?: string }; supabaseAuth?: boolean } = {},
+  opts: { sources?: Record<string, EntityDataSource>; accessEnabled?: boolean; auditEnabled?: boolean; screensByEntity?: Map<string, string[]>; triggers?: Record<string, EntityTriggers>; supabaseConn?: { url?: string; key?: string }; supabaseAuth?: boolean; tenantField?: string; tenantScoped?: (entity: string) => boolean } = {},
 ): { files: GeneratedFile[]; prepared: EntitySchema[] } {
   const { entries, seed } = prepareEntities(schemas)
   const { file: data, needs } = dataModule(entries, seed, opts.sources, opts.supabaseConn)
@@ -1148,7 +1150,15 @@ export function emitEntityModules(
     needs.supabaseUrl = opts.supabaseConn.url; needs.supabaseKey = opts.supabaseConn.key
   }
   if (needs.supabase || opts.supabaseAuth) files.push(connectionsModule(needs))
-  for (const r of needs.sqlRoutes) files.push(sqlRouteFile(r.schema, r.table, r.dialect, { access: opts.accessEnabled, audit: opts.auditEnabled, screenIds: opts.screensByEntity?.get(r.schema.name) ?? [], triggers: opts.triggers?.[r.schema.name], dbSchema: r.dbSchema }))
+  for (const r of needs.sqlRoutes) files.push(sqlRouteFile(r.schema, r.table, r.dialect, {
+    access: opts.accessEnabled,
+    audit: opts.auditEnabled,
+    screenIds: opts.screensByEntity?.get(r.schema.name) ?? [],
+    triggers: opts.triggers?.[r.schema.name],
+    dbSchema: r.dbSchema,
+    // A shared (reference-data) entity stays global - no scope on its route.
+    tenantField: opts.tenantField && opts.tenantScoped?.(r.schema.name) !== false ? opts.tenantField : undefined,
+  }))
   return { files, prepared: entries.map((e) => e.schema) }
 }
 

package/src/studio/index.ts

@@ -44,6 +44,33 @@ export { emitStudioProject, emitStudioAppBundle, emitStudioFragment, runtimeDeps
 export { sampleApps, getSampleApp, type SampleApp } from './samples/index.js'
 export { starterProject } from './samples/starter.js'
 export { liveDataSamples, getLiveDataSample } from './samples/live-data.js'
+export { starterDatasets, getStarterDataset, type StarterDataset } from './samples/datasets.js'
+export {
+  runStudioInit,
+  parseSelection,
+  type PromptIO,
+  type DbGateway,
+  type FetchText,
+  type InitFlags,
+  type InitResult,
+} from './init-flow.js'
+export {
+  crudSuiteScreens,
+  addCrudSuite,
+  crudAppFromSchemas,
+  listScreen,
+  formScreen,
+  detailScreen,
+  dashScreen,
+  statusPills,
+  gridConfig,
+  type CrudScreenKind,
+  type CrudEditingMode,
+  type CrudSuiteOptions,
+  type CrudAppOptions,
+  type GridOpts,
+  type Tile,
+} from './screen-suites.js'
 export {
   sanitizeStudioProject,
   buildStudioBugReport,
@@ -134,6 +161,13 @@ export {
   type TriggerStep,
   type TriggerEvent,
   type EntityTriggers,
+  setJob,
+  type ScheduledJob,
+  type ScheduledJobKind,
+  setTenancy,
+  tenantField,
+  isTenantScoped,
+  type TenancyConfig,
   clickSlot,
   ssrScreenShape,
   ssrEligible,

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

@@ -0,0 +1,364 @@
+import { describe, it, expect, vi, afterEach } 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
+    },
+  }
+}
+
+/** Stand in for a Supabase project: PostgREST serves its OpenAPI doc at /rest/v1/. */
+function stubSupabase(definitions: Record<string, unknown> | null) {
+  vi.stubGlobal('fetch', async (input: string | URL) => {
+    const href = String(input)
+    if (href.endsWith('/rest/v1/')) {
+      if (!definitions) return new Response('nope', { status: 401 })
+      return new Response(JSON.stringify({ definitions }), { status: 200, headers: { 'content-type': 'application/json' } })
+    }
+    // Row-sample and CSV fallbacks: answer empty so only the OpenAPI path counts.
+    return new Response('[]', { status: 200, headers: { 'content-type': 'application/json' } })
+  })
+}
+
+const SUPABASE_DEFS = {
+  customers: {
+    required: ['id', 'name'],
+    properties: {
+      id: { type: 'integer', description: 'Note:\nThis is a Primary Key.<pk/>' },
+      name: { type: 'string' },
+      tier: { type: 'string', enum: ['free', 'pro'] },
+    },
+  },
+  orders: {
+    required: ['id'],
+    properties: {
+      id: { type: 'integer', description: '<pk/>' },
+      total: { type: 'number' },
+      customer_id: { type: 'integer', description: "<fk table='customers' column='id'/>" },
+    },
+  },
+}
+
+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 () => {
+    // Source menu: 1 sample, 2 database, 3 supabase, 4 pglite, 5 rest.
+    const prompts = scriptedPrompts(['4', '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(['5', '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')
+  })
+
+  describe('supabase', () => {
+    afterEach(() => vi.unstubAllGlobals())
+
+    it('reads a project over the REST API and binds each table to it', async () => {
+      stubSupabase(SUPABASE_DEFS)
+      const prompts = scriptedPrompts(['all', 'y', '1', '1', 'n', 'Shop', '.'])
+      const fs = memoryIo()
+      const result = await runStudioInit(
+        { supabaseUrl: 'https://abc.supabase.co', supabaseKey: 'anon-key' },
+        prompts.io,
+        null, // no DbGateway: the point is that Supabase needs no driver
+        fs.io,
+      )
+
+      expect(result.project.entities.map((e) => e.name)).toEqual(['customers', 'orders'])
+      expect(result.project.dataSource).toBe('supabase')
+      expect(result.project.dataSources?.customers).toEqual({
+        kind: 'supabase', table: 'customers', url: 'https://abc.supabase.co', key: 'anon-key',
+      })
+      expect(validateProject(result.project).filter((i) => i.level === 'error')).toEqual([])
+      // The URL + key flags skip straight to the table question.
+      expect(prompts.asked[0]).toBe('Which tables? (all, or a comma list of names/numbers)')
+    })
+
+    it('picks up the primary key and the foreign key from the API doc', async () => {
+      stubSupabase(SUPABASE_DEFS)
+      const prompts = scriptedPrompts(['all', 'y', '1', '1', 'n', 'Shop', '.'])
+      const fs = memoryIo()
+      const { project } = await runStudioInit(
+        { supabaseUrl: 'https://abc.supabase.co', supabaseKey: 'k' }, prompts.io, null, fs.io,
+      )
+      const orders = project.entities.find((e) => e.name === 'orders')!
+      expect(orders.fields.find((f) => f.field === 'id')?.primaryKey).toBe(true)
+      expect(orders.fields.find((f) => f.field === 'customer_id')?.relation?.entity).toBe('customers')
+      // A relation means the customers detail page gets an orders tab.
+      expect(project.screens.some((s) => s.id === 'customers-detail')).toBe(true)
+    })
+
+    it('imports only the picked tables', async () => {
+      stubSupabase(SUPABASE_DEFS)
+      const prompts = scriptedPrompts(['orders', 'y', '1', '1', 'n', 'Shop', '.'])
+      const fs = memoryIo()
+      const { project } = await runStudioInit(
+        { supabaseUrl: 'https://abc.supabase.co', supabaseKey: 'k' }, prompts.io, null, fs.io,
+      )
+      expect(project.entities.map((e) => e.name)).toEqual(['orders'])
+    })
+
+    it('falls back to typed table names when the API doc is restricted', async () => {
+      // 401 on the doc, but each table still introspects from a sample row.
+      let calls = 0
+      vi.stubGlobal('fetch', async (input: string | URL) => {
+        const href = String(input)
+        calls++
+        if (href.endsWith('/rest/v1/')) return new Response('no', { status: 401 })
+        return new Response(JSON.stringify([{ id: 1, name: 'Acme' }]), {
+          status: 200, headers: { 'content-type': 'application/json' },
+        })
+      })
+      const prompts = scriptedPrompts(['customers', 'y', '1', '1', 'n', 'Shop', '.'])
+      const fs = memoryIo()
+      const { project } = await runStudioInit(
+        { supabaseUrl: 'https://abc.supabase.co', supabaseKey: 'k' }, prompts.io, null, fs.io,
+      )
+      expect(calls).toBeGreaterThan(0)
+      expect(project.entities.map((e) => e.name)).toEqual(['customers'])
+      expect(project.entities[0]!.fields.map((f) => f.field)).toContain('name')
+      expect(prompts.asked).toContain('Table names (comma separated):')
+    })
+
+    it('requires both the URL and the key', async () => {
+      const prompts = scriptedPrompts(['', ''])
+      const fs = memoryIo()
+      await expect(runStudioInit({ supabaseUrl: 'https://abc.supabase.co' }, prompts.io, null, fs.io))
+        .rejects.toThrow('project URL and the anon key are required')
+    })
+
+    it('fails clearly when no picked table can be read', async () => {
+      // Doc lists nothing AND every per-table fallback 404s.
+      vi.stubGlobal('fetch', async (input: string | URL) =>
+        String(input).endsWith('/rest/v1/')
+          ? new Response(JSON.stringify({ definitions: {} }), { status: 200, headers: { 'content-type': 'application/json' } })
+          : new Response('missing', { status: 404 }),
+      )
+      const prompts = scriptedPrompts(['ghosts'])
+      const fs = memoryIo()
+      await expect(runStudioInit(
+        { supabaseUrl: 'https://abc.supabase.co', supabaseKey: 'k' }, prompts.io, null, fs.io,
+      )).rejects.toThrow('None of the picked tables could be read')
+    })
+  })
+
+  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')
+  })
+})