@svgrid/enterprise 2.3.0 → 2.3.2

package/src/studio/init-flow.ts

@@ -0,0 +1,409 @@
+/**
+ * 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 { introspectSupabaseTable, listSupabaseTables } from '../sources/introspect-supabase.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
+  /** Supabase project URL - skips the source question and both prompts. */
+  supabaseUrl?: string
+  /** Supabase anon key. */
+  supabaseKey?: 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: 'supabase', label: 'Supabase', hint: 'project URL + anon key, read over the REST API - no driver needed' },
+  { 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.supabaseUrl) source = 'supabase'
+  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 === 'supabase') return gatherFromSupabase(flags, prompts)
+  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' }
+}
+
+/**
+ * Supabase reads over its own REST API, so this needs no driver and no
+ * DbGateway - just the project URL and the anon key.
+ */
+async function gatherFromSupabase(flags: InitFlags, prompts: PromptIO): Promise<Gathered> {
+  const url = (flags.supabaseUrl ?? (await prompts.ask('Project URL:', ''))).trim()
+  const key = (flags.supabaseKey ?? (await prompts.ask('Anon key:', ''))).trim()
+  if (!url || !key) throw new Error('Both the project URL and the anon key are required.')
+
+  prompts.say('  Reading the API...')
+  const tables = await listSupabaseTables(url, key)
+  let picked: string[]
+  if (tables.length) {
+    prompts.say('')
+    prompts.say(`Found ${tables.length} ${tables.length === 1 ? 'table' : 'tables'}:`)
+    tables.forEach((t, i) => prompts.say(`  ${i + 1}. ${t}`))
+    const answer = flags.yes ? 'all' : await prompts.ask('Which tables? (all, or a comma list of names/numbers)', 'all')
+    picked = parseSelection(answer, tables)
+  } else {
+    // The API doc is often CORS-blocked or restricted; naming the tables by hand
+    // still works because each one is introspected individually.
+    prompts.say("  Couldn't list the tables (the API doc may be restricted for this key).")
+    const typed = await prompts.ask('Table names (comma separated):', '')
+    picked = typed.split(',').map((t) => t.trim()).filter(Boolean)
+  }
+  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) {
+    const schema = await introspectSupabaseTable({ url, key, table })
+    if (!schema?.fields.length) {
+      prompts.say(`  ! Skipped ${table}: no columns could be read.`)
+      continue
+    }
+    schemas.push(schema as EntitySchema)
+    sources[schema.name] = { kind: 'supabase', table, url, key }
+  }
+  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: 'supabase' }
+}
+
+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 }
+}

package/src/studio/project.test.ts

@@ -39,7 +39,6 @@ import {
   blockPalette,
   createProject,
   defaultBlockConfig,
-  defaultScreenFor,
   gridColumns,
   moveBlock,
   removeBlock,

package/src/studio/project.ts

@@ -203,7 +203,20 @@ export type SchedulerViewConfig = {
 export type TreeDataConfig = { parentField: string; labelField: string }
 /** Which export affordances the grid toolbar shows. All go through the grid's built-in
  *  export API (dependency-free). Empty / all-false = no toolbar. */
-export type GridExportConfig = { csv?: boolean; json?: boolean; copy?: boolean }
+/** Export buttons on a grid's toolbar.
+ *
+ *  `csv` / `json` / `copy` use the free grid API. `xlsx` / `pdf` / `print` go
+ *  through `@svgrid/enterprise` (real OOXML, pdfmake, paginated print) and pull
+ *  in their optional peer deps - jszip for xlsx, pdfmake for pdf - which the
+ *  generated package.json declares only when the button is switched on. */
+export type GridExportConfig = {
+  csv?: boolean
+  json?: boolean
+  copy?: boolean
+  xlsx?: boolean
+  pdf?: boolean
+  print?: boolean
+}
 /** Which filtering surfaces the grid shows (when `filterable`). `global` = the search-all
  *  box, `row` = a filter input under each header, `menu` = the column header filter menu. */
 export type GridFilterUi = { global?: boolean; row?: boolean; menu?: boolean }
@@ -817,6 +830,68 @@ export type StudioProject = {
   /** Server-side business-rule triggers, keyed by entity name. Enforced on the
    *  SQL route (compiled into createKitHandlers `hooks`). */
   triggers?: Record<string, EntityTriggers>
+  /** Scheduled background jobs: a guarded `/api/cron` endpoint plus the schedule
+   *  config for the deploy target. Empty / omitted emits nothing. */
+  jobs?: ScheduledJob[]
+  /** Multi-tenancy: scope every row to the signed-in user's tenant. */
+  tenancy?: TenancyConfig
+}
+
+/**
+ * Multi-tenancy for the generated app: one database, one deployment, rows
+ * partitioned by a tenant column.
+ *
+ * Enforced on the SERVER, in the API route's `scope` option - reads are
+ * filtered, creates are stamped, and updates/deletes re-read the target under
+ * the scope first. A client that skips the UI still cannot reach another
+ * tenant's rows.
+ *
+ * Requires the [auth starter](./auth.md) (the tenant comes from the session)
+ * and the typed data layer (the column has to exist in the schema). Without
+ * both it degrades to off rather than emitting a half-enforced scope.
+ */
+export type TenancyConfig = {
+  enabled: boolean
+  /** Column holding the tenant key on every scoped entity. Default `tenantId`. */
+  field?: string
+  /** Entities to leave GLOBAL (shared across tenants) - reference/lookup tables
+   *  like currencies or countries that every tenant reads. */
+  sharedEntities?: string[]
+}
+
+/** What a scheduled job does when it fires.
+ *  - `email`: send a summary of an entity (row count + the newest rows).
+ *  - `code`: run a body you write, with `db` / `sendEmail` in scope. */
+export type ScheduledJobKind = 'email' | 'code'
+
+/**
+ * One scheduled background job.
+ *
+ * Jobs run on the SERVER via a generated `/api/cron` route, not in a browser
+ * tab - unlike the client-side `createScheduler` in `@svgrid/enterprise`, which
+ * only fires while the app is open. The route is secret-guarded and invoked by
+ * the platform's scheduler (Vercel Cron, a GitHub Actions schedule, or your own
+ * crontab hitting the URL).
+ */
+export type ScheduledJob = {
+  /** Stable id - the `?job=` selector and the handler name. */
+  id: string
+  /** Human label used in comments + the DEPLOY.md table. */
+  name: string
+  /** Standard 5-field cron expression, interpreted in UTC. */
+  cron: string
+  /** Off by default is surprising for something you explicitly added, so a job
+   *  runs unless `enabled` is explicitly false. */
+  enabled?: boolean
+  kind: ScheduledJobKind
+  /** `email`: the entity to summarize. */
+  entity?: string
+  /** `email`: recipient address. */
+  to?: string
+  /** `email`: subject line. Defaults to the job name. */
+  subject?: string
+  /** `code`: the handler body (TypeScript). */
+  code?: string
 }
 
 /** The render mode for a screen. `'ssr'` emits idiomatic SvelteKit (`+page.server.ts`
@@ -884,6 +959,32 @@ export function setTrigger(project: StudioProject, entity: string, event: Trigge
   return { ...project, triggers: Object.keys(triggers).length ? triggers : undefined }
 }
 
+/** Turn multi-tenancy on/off and configure the scoping column. */
+export function setTenancy(project: StudioProject, tenancy: TenancyConfig | null): StudioProject {
+  if (!tenancy || !tenancy.enabled) {
+    const { tenancy: _drop, ...rest } = project
+    return rest
+  }
+  return { ...project, tenancy }
+}
+
+/** The tenant column name, defaulted. */
+export const tenantField = (project: StudioProject): string => project.tenancy?.field || 'tenantId'
+
+/** True when `entity` is scoped to a tenant (i.e. tenancy is on and it is not
+ *  listed as shared). Shared entities stay global reference data. */
+export function isTenantScoped(project: StudioProject, entity: string): boolean {
+  if (project.tenancy?.enabled !== true) return false
+  return !(project.tenancy.sharedEntities ?? []).includes(entity)
+}
+
+/** Add or replace a scheduled job (matched by `id`). Pass `null` to remove one. */
+export function setJob(project: StudioProject, id: string, job: Omit<ScheduledJob, 'id'> | null): StudioProject {
+  const rest = (project.jobs ?? []).filter((j) => j.id !== id)
+  const next = job ? [...rest, { ...job, id }] : rest
+  return { ...project, jobs: next.length ? next : undefined }
+}
+
 /** Where the generated app deploys. Drives the emitted SvelteKit adapter + config. */
 export type DeployTarget = 'auto' | 'vercel' | 'netlify' | 'cloudflare' | 'node'
 
@@ -1378,7 +1479,13 @@ export function removeScreen(project: StudioProject, screenId: string): StudioPr
   return { ...project, screens: project.screens.filter((s) => s.id !== screenId) }
 }
 
-export function updateScreen(project: StudioProject, screenId: string, patch: Partial<Pick<Screen, 'title' | 'route' | 'entity' | 'nav' | 'actions' | 'className'>>): StudioProject {
+export function updateScreen(
+  project: StudioProject,
+  screenId: string,
+  // `renderMode` is patchable here so SSR output is reachable without the
+  // designer - the CLI and the MCP tools drive the model through this function.
+  patch: Partial<Pick<Screen, 'title' | 'route' | 'entity' | 'nav' | 'actions' | 'className' | 'renderMode'>>,
+): StudioProject {
   return mapScreen(project, screenId, (s) => ({ ...s, ...patch }))
 }
 

package/src/studio/samples/datasets.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest'
+import { starterDatasets, getStarterDataset } from './datasets.js'
+import { crudAppFromSchemas } from '../screen-suites.js'
+import { validateProject, parseProject, serializeProject } from '../project.js'
+
+describe('starter datasets', () => {
+  it('ships a picker-ready gallery with unique ids', () => {
+    expect(starterDatasets.length).toBeGreaterThanOrEqual(4)
+    const ids = starterDatasets.map((d) => d.id)
+    expect(new Set(ids).size).toBe(ids.length)
+    for (const d of starterDatasets) {
+      expect(d.name).toBeTruthy()
+      expect(d.description).toBeTruthy()
+      expect(d.emoji).toBeTruthy()
+    }
+  })
+
+  it('getStarterDataset resolves by id', () => {
+    expect(getStarterDataset('customers-orders')?.name).toBe('Customers & orders')
+    expect(getStarterDataset('nope')).toBeUndefined()
+  })
+
+  it('build() returns fresh data each call (never a shared mutable seed)', () => {
+    const dataset = starterDatasets[0]!
+    const a = dataset.build()
+    const b = dataset.build()
+    expect(a).toEqual(b)
+    expect(a.seed).not.toBe(b.seed)
+    expect(a.entities[0]).not.toBe(b.entities[0])
+  })
+
+  for (const dataset of starterDatasets) {
+    describe(dataset.id, () => {
+      const { entities, seed } = dataset.build()
+
+      it('pairs a parent and a child linked by a real relation', () => {
+        expect(entities).toHaveLength(2)
+        const names = new Set(entities.map((e) => e.name))
+        const relations = entities.flatMap((e) => e.fields.filter((f) => f.type === 'relation'))
+        expect(relations.length).toBeGreaterThanOrEqual(1)
+        for (const r of relations) expect(names.has(r.relation!.entity)).toBe(true)
+      })
+
+      it('has a colored enum (so the generated app gets status pills and a chart)', () => {
+        const colored = entities.flatMap((e) => e.fields).filter((f) => f.type === 'enum' && f.options?.some((o) => o.color))
+        expect(colored.length).toBeGreaterThanOrEqual(1)
+      })
+
+      it('seeds every entity with enough rows to scroll', () => {
+        for (const e of entities) {
+          expect(seed[e.name], `${e.name} has no seed`).toBeTruthy()
+          expect(seed[e.name]!.length).toBeGreaterThanOrEqual(10)
+        }
+      })
+
+      it('seed rows carry unique ids and resolvable foreign keys', () => {
+        for (const e of entities) {
+          const pk = e.idField ?? 'id'
+          const values = seed[e.name]!.map((r) => r[pk])
+          expect(values.every((v) => v != null && v !== '')).toBe(true)
+          expect(new Set(values).size).toBe(values.length)
+        }
+        for (const child of entities) {
+          for (const f of child.fields) {
+            if (f.type !== 'relation') continue
+            const parent = entities.find((e) => e.name === f.relation!.entity)!
+            const parentPk = parent.idField ?? 'id'
+            const pool = new Set(seed[parent.name]!.map((r) => String(r[parentPk])))
+            for (const row of seed[child.name]!) {
+              expect(pool.has(String(row[f.field])), `${child.name}.${f.field} -> ${row[f.field]}`).toBe(true)
+            }
+          }
+        }
+      })
+
+      it('generates a valid app through crudAppFromSchemas', () => {
+        const app = crudAppFromSchemas(entities, { title: dataset.name, seed })
+        expect(validateProject(app).filter((i) => i.level === 'error')).toEqual([])
+        expect(app.screens.length).toBeGreaterThanOrEqual(3)
+        expect(parseProject(serializeProject(app))).toEqual(app)
+      })
+    })
+  }
+})