@weft-js/create 0.1.0 → 0.1.2

package/src/stack.mjs

@@ -1,29 +1,81 @@
-// The `--db` and `--auth` part of a scaffold (research 28 §6): a database, a todo app on it, and with `--auth` a
+// The `--db` and `--auth` part of a scaffold: a database, a todo app on it, and with `--auth` a
 // sign-in/sign-up flow and a guarded `/todos`. Pinned versions, so a scaffold builds what the matrix tested.
 import { readFileSync } from 'node:fs'
-import { nativeAuthSql, nativeFiles, prismaAdapterPackage, prismaAuthModels, prismaFiles } from './data.mjs'
-
-const VERSIONS = {
+import {
+  nativeAuthSql,
+  nativeFiles,
+  prismaAdapterPackage,
+  prismaAuthModels,
+  prismaFiles,
+} from './data.mjs'
+import { authTablesFile, sqliteSchema, pgSchema, mysqlSchema } from './stack/schema.mjs'
+import { loginPage } from './stack/pages.mjs'
+export { sharedAuthTables } from './stack/schema.mjs'
+export {
+  tailwindPackages,
+  TAILWIND_VITE,
+  TAILWIND_CSS,
+  classes,
+  controls,
+  todosPage,
+  loginPage,
+} from './stack/pages.mjs'
+
+/** The version a scaffold pins for each package it adds that isn't weft's own: what the matrix tested. */
+export const VERSIONS = {
   '@types/node': '26.6.5',
-  '@t3-oss/env-core': '0.13.11', 'better-auth': '1.7.14', 'drizzle-kit': '0.31.11', 'drizzle-orm': '0.45.4', 'drizzle-zod': '0.8.3', kysely: '0.29.7', mysql2: '3.24.6', postgres: '4.0.0', zod: '4.6.7',
-  prisma: '7.10.1', '@prisma/client': '7.10.1', '@prisma/adapter-libsql': '7.10.1', '@prisma/adapter-pg': '7.10.1', '@prisma/adapter-mariadb': '7.10.1',
+  '@t3-oss/env-core': '0.13.11',
+  'better-auth': '1.7.14',
+  'drizzle-kit': '0.31.11',
+  'drizzle-orm': '0.45.4',
+  'drizzle-zod': '0.8.3',
+  kysely: '0.29.7',
+  mysql2: '3.24.6',
+  postgres: '4.0.0',
+  zod: '4.6.7',
+  prisma: '7.10.1',
+  '@prisma/client': '7.10.1',
+  '@prisma/adapter-libsql': '7.10.1',
+  '@prisma/adapter-pg': '7.10.1',
+  '@prisma/adapter-mariadb': '7.10.1',
 }
 
-const pin = (...names) => Object.fromEntries(names.map(n => [n, VERSIONS[n]]))
+const pin = (...names) => Object.fromEntries(names.map((n) => [n, VERSIONS[n]]))
 
-const drivers = db => (db === 'postgres' ? ['postgres'] : db === 'mysql' ? ['mysql2'] : [])
+const drivers = (db) => (db === 'postgres' ? ['postgres'] : db === 'mysql' ? ['mysql2'] : [])
 
 /** Every scaffold pins what it shipped with: this package and weft's others go out at one version. */
-export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+export const VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version
 
 /** The pinned dependencies of a database, data layer and auth choice. */
 export function stackDeps({ db, auth, layer = 'drizzle', version = VERSION }) {
   if (db === 'none') return { deps: {}, dev: {} }
   const base = pin('@t3-oss/env-core', 'zod', ...(auth ? ['better-auth'] : []))
-  if (layer === 'native') return { deps: { ...base, ...pin(...drivers(db), ...(auth ? ['kysely'] : [])), '@weft-js/db': version }, dev: pin('@types/node') }
-  if (layer === 'prisma') return { deps: { ...base, ...pin('@prisma/client', prismaAdapterPackage(db)), '@weft-js/db': version }, dev: pin('prisma', '@types/node') }
+  if (layer === 'native')
+    return {
+      deps: {
+        ...base,
+        ...pin(...drivers(db), ...(auth ? ['kysely'] : [])),
+        '@weft-js/db': version,
+      },
+      dev: pin('@types/node'),
+    }
+  if (layer === 'prisma')
+    return {
+      deps: { ...base, ...pin('@prisma/client', prismaAdapterPackage(db)), '@weft-js/db': version },
+      dev: pin('prisma', '@types/node'),
+    }
   return {
-    deps: pin('@t3-oss/env-core', 'drizzle-orm', 'drizzle-zod', 'zod', ...drivers(db), ...(auth ? ['better-auth'] : [])),
+    deps: pin(
+      '@t3-oss/env-core',
+      'drizzle-orm',
+      'drizzle-zod',
+      'zod',
+      ...drivers(db),
+      ...(auth ? ['better-auth'] : []),
+    ),
     dev: pin('drizzle-kit', '@types/node'),
   }
 }
@@ -31,16 +83,22 @@ export function stackDeps({ db, auth, layer = 'drizzle', version = VERSION }) {
 /** Sign-in on an app with a database, for `weft add auth`: new files only, and what to add to the existing ones. */
 export function authFiles({ db, layer, ui }) {
   const files = stackFiles({ db, layer, auth: true, name: 'app', secret: '' })
-  const out = { 'src/auth.server.ts': files['src/auth.server.ts'], 'src/server/session.ts': files['src/server/session.ts'], 'src/routes/login.tsx': loginPage(ui) }
-  return { files: out, context: files['src/context.server.ts'], tables: { drizzle: authTablesFile(db), prisma: prismaAuthModels(db), native: nativeAuthSql(db) }[layer] }
+  const out = {
+    'src/auth.server.ts': files['src/auth.server.ts'],
+    'src/server/session.ts': files['src/server/session.ts'],
+    'src/routes/login.tsx': loginPage(ui),
+  }
+  return {
+    files: out,
+    context: files['src/context.server.ts'],
+    tables: {
+      drizzle: authTablesFile(db),
+      prisma: prismaAuthModels(db),
+      native: nativeAuthSql(db),
+    }[layer],
+  }
 }
 
-const authTablesFile = db => ({
-  sqlite: () => `import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'\n${authTablesSqlite()}`,
-  postgres: () => `import { boolean, pgTable, text, timestamp } from 'drizzle-orm/pg-core'\n${authTablesPg()}`,
-  mysql: () => `import { boolean, mysqlTable, text, timestamp, varchar } from 'drizzle-orm/mysql-core'\n${authTablesMysql()}`,
-}[db]())
-
 /** The files of a database, data layer and auth choice, as `{ path: text }`. */
 export function stackFiles({ db, auth, name, secret, layer = 'drizzle' }) {
   const shared = {
@@ -49,7 +107,10 @@ export function stackFiles({ db, auth, name, secret, layer = 'drizzle' }) {
     'src/env.server.ts': envModule({ db, auth }),
     'src/context.server.ts': context(auth),
     'src/routes/todos/index.tsx': '', // filled by the caller, which knows the UI kit
-    ...(auth && { 'src/server/session.ts': sessionServer(), 'src/routes/todos/_layout.tsx': guard() }),
+    ...(auth && {
+      'src/server/session.ts': sessionServer(),
+      'src/routes/todos/_layout.tsx': guard(),
+    }),
   }
   if (layer === 'native') return { ...shared, ...nativeFiles({ db, auth }) }
   if (layer === 'prisma') return { ...shared, ...prismaFiles({ db, auth }) }
@@ -68,10 +129,13 @@ function drizzleFiles({ db, auth }) {
   }
 }
 
-const database = name => name.replace(/[^a-z0-9_]/g, '_')
+const database = (name) => name.replace(/[^a-z0-9_]/g, '_')
 const envFile = ({ db, auth, name, secret }) =>
-  ({ postgres: `DATABASE_URL=postgres://localhost:5432/${database(name)}\n`, mysql: `DATABASE_URL=mysql://root@localhost:3306/${database(name)}\n`, sqlite: 'DATABASE_URL=file:.data/app.db\n' }[db]) +
-  (auth ? `BETTER_AUTH_SECRET=${secret}\nBETTER_AUTH_URL=http://localhost:5173\n` : '')
+  ({
+    postgres: `DATABASE_URL=postgres://localhost:5432/${database(name)}\n`,
+    mysql: `DATABASE_URL=mysql://root@localhost:3306/${database(name)}\n`,
+    sqlite: 'DATABASE_URL=file:.data/app.db\n',
+  })[db] + (auth ? `BETTER_AUTH_SECRET=${secret}\nBETTER_AUTH_URL=http://localhost:5173\n` : '')
 
 const envModule = ({ db, auth }) => `import { createEnv } from '@t3-oss/env-core'
 import { z } from 'zod'
@@ -87,155 +151,10 @@ export const env = createEnv({
 })
 `
 
-function sqliteSchema(auth) {
-  const owner = auth ? `\n  userId: text('user_id').notNull().references(() => user.id, { onDelete: 'cascade' }),` : ''
-  return `import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'
-${auth ? authTablesSqlite() : ''}
-export const todos = sqliteTable('todos', {
-  id: text('id').primaryKey(),${owner}
-  title: text('title').notNull(),
-  done: integer('done', { mode: 'boolean' }).notNull().default(false),
-  createdAt: integer('created_at').notNull(),
-})
-`
-}
-
-function pgSchema(auth) {
-  const owner = auth ? `\n  userId: text('user_id').notNull().references(() => user.id, { onDelete: 'cascade' }),` : ''
-  return `import { bigint, boolean, pgTable, text${auth ? ', timestamp' : ''} } from 'drizzle-orm/pg-core'
-${auth ? authTablesPg() : ''}
-export const todos = pgTable('todos', {
-  id: text('id').primaryKey(),${owner}
-  title: text('title').notNull(),
-  done: boolean('done').notNull().default(false),
-  createdAt: bigint('created_at', { mode: 'number' }).notNull(),
-})
-`
-}
-
-// MySQL can't index a TEXT column, so ids, keys and anything unique are VARCHAR. Otherwise Postgres's tables hold.
-const authTablesMysql = () => authTablesPg()
-  .replaceAll('pgTable', 'mysqlTable')
-  .replace(/text\('(id|user_id|email|token|account_id|provider_id|identifier)'\)/g, "varchar('$1', { length: 255 })")
-  .replace(/timestamp\('(\w+)'\)/g, "timestamp('$1', { fsp: 3 })")
-
-function mysqlSchema(auth) {
-  const owner = auth ? `\n  userId: varchar('user_id', { length: 255 }).notNull().references(() => user.id, { onDelete: 'cascade' }),` : ''
-  return `import { bigint, boolean, mysqlTable, ${auth ? 'text, timestamp, ' : ''}varchar } from 'drizzle-orm/mysql-core'
-${auth ? authTablesMysql() : ''}
-export const todos = mysqlTable('todos', {
-  id: varchar('id', { length: 36 }).primaryKey(),${owner}
-  title: varchar('title', { length: 200 }).notNull(),
-  done: boolean('done').notNull().default(false),
-  createdAt: bigint('created_at', { mode: 'number' }).notNull(),
-})
-`
-}
-
-const authTablesSqlite = () => {
-  const when = (col, opts = '.notNull()') => `integer('${col}', { mode: 'timestamp_ms' })${opts}`
-  return `
-// Better Auth's tables: it reads and writes them through Drizzle, with these names.
-export const user = sqliteTable('user', {
-  id: text('id').primaryKey(),
-  name: text('name').notNull(),
-  email: text('email').notNull().unique(),
-  emailVerified: integer('email_verified', { mode: 'boolean' }).notNull(),
-  image: text('image'),
-  createdAt: ${when('created_at')},
-  updatedAt: ${when('updated_at')},
-})
-
-export const session = sqliteTable('session', {
-  id: text('id').primaryKey(),
-  expiresAt: ${when('expires_at')},
-  token: text('token').notNull().unique(),
-  createdAt: ${when('created_at')},
-  updatedAt: ${when('updated_at')},
-  ipAddress: text('ip_address'),
-  userAgent: text('user_agent'),
-  userId: text('user_id').notNull().references(() => user.id, { onDelete: 'cascade' }),
-})
-
-export const account = sqliteTable('account', {
-  id: text('id').primaryKey(),
-  accountId: text('account_id').notNull(),
-  providerId: text('provider_id').notNull(),
-  userId: text('user_id').notNull().references(() => user.id, { onDelete: 'cascade' }),
-  accessToken: text('access_token'),
-  refreshToken: text('refresh_token'),
-  idToken: text('id_token'),
-  accessTokenExpiresAt: ${when('access_token_expires_at', '')},
-  refreshTokenExpiresAt: ${when('refresh_token_expires_at', '')},
-  scope: text('scope'),
-  password: text('password'),
-  createdAt: ${when('created_at')},
-  updatedAt: ${when('updated_at')},
-})
-
-export const verification = sqliteTable('verification', {
-  id: text('id').primaryKey(),
-  identifier: text('identifier').notNull(),
-  value: text('value').notNull(),
-  expiresAt: ${when('expires_at')},
-  createdAt: ${when('created_at', '')},
-  updatedAt: ${when('updated_at', '')},
-})
-`
-}
-
-const authTablesPg = () => `
-// Better Auth's tables: it reads and writes them through Drizzle, with these names.
-export const user = pgTable('user', {
-  id: text('id').primaryKey(),
-  name: text('name').notNull(),
-  email: text('email').notNull().unique(),
-  emailVerified: boolean('email_verified').notNull(),
-  image: text('image'),
-  createdAt: timestamp('created_at').notNull(),
-  updatedAt: timestamp('updated_at').notNull(),
-})
-
-export const session = pgTable('session', {
-  id: text('id').primaryKey(),
-  expiresAt: timestamp('expires_at').notNull(),
-  token: text('token').notNull().unique(),
-  createdAt: timestamp('created_at').notNull(),
-  updatedAt: timestamp('updated_at').notNull(),
-  ipAddress: text('ip_address'),
-  userAgent: text('user_agent'),
-  userId: text('user_id').notNull().references(() => user.id, { onDelete: 'cascade' }),
-})
-
-export const account = pgTable('account', {
-  id: text('id').primaryKey(),
-  accountId: text('account_id').notNull(),
-  providerId: text('provider_id').notNull(),
-  userId: text('user_id').notNull().references(() => user.id, { onDelete: 'cascade' }),
-  accessToken: text('access_token'),
-  refreshToken: text('refresh_token'),
-  idToken: text('id_token'),
-  accessTokenExpiresAt: timestamp('access_token_expires_at'),
-  refreshTokenExpiresAt: timestamp('refresh_token_expires_at'),
-  scope: text('scope'),
-  password: text('password'),
-  createdAt: timestamp('created_at').notNull(),
-  updatedAt: timestamp('updated_at').notNull(),
-})
-
-export const verification = pgTable('verification', {
-  id: text('id').primaryKey(),
-  identifier: text('identifier').notNull(),
-  value: text('value').notNull(),
-  expiresAt: timestamp('expires_at').notNull(),
-  createdAt: timestamp('created_at'),
-  updatedAt: timestamp('updated_at'),
-})
-`
-
 /** `src/context.server.ts`: the database on `ctx`, and the session with auth. */
-export const context = auth => auth
-  ? `import { session } from '@weft-js/start/auth'
+export const context = (auth) =>
+  auth
+    ? `import { session } from '@weft-js/start/auth'
 import auth from '#/auth.server'
 import { db } from '#/db/index.server'
 
@@ -251,7 +170,7 @@ declare module '@weft-js/start' {
   }
 }
 `
-  : `import { db } from '#/db/index.server'
+    : `import { db } from '#/db/index.server'
 
 export default () => ({ db })
 
@@ -264,7 +183,9 @@ declare module '@weft-js/start' {
 
 function todosServer(auth, db) {
   const use = auth ? `\n  auth: 'user',` : ''
-  const mine = auth ? `and(eq(todos.id, input.id), eq(todos.userId, ctx.user.id))` : `eq(todos.id, input.id)`
+  const mine = auth
+    ? `and(eq(todos.id, input.id), eq(todos.userId, ctx.user.id))`
+    : `eq(todos.id, input.id)`
   // MySQL has no \`returning\`.
   const returning = db === 'mysql' ? '' : '.returning()'
   return `import { mutation, query } from '@weft-js/start'
@@ -288,10 +209,14 @@ export const addTodo = mutation({
   optimistic: ({ input }, cache) =>
     cache.update(listTodos, undefined, list => void list.push({ id: \`tmp:\${input.title}\`,${auth ? " userId: ''," : ''} title: input.title, done: false, createdAt: 0 })),
   run: async ({ input, ctx }) => {
-    ${db === 'mysql' ? `const row = { id: crypto.randomUUID(),${auth ? ' userId: ctx.user.id,' : ''} title: input.title, createdAt: Date.now() }
+    ${
+      db === 'mysql'
+        ? `const row = { id: crypto.randomUUID(),${auth ? ' userId: ctx.user.id,' : ''} title: input.title, createdAt: Date.now() }
     await ctx.db.insert(todos).values(row)
-    return { ...row, done: false }` : `const [row] = await ctx.db.insert(todos).values({ id: crypto.randomUUID(),${auth ? ' userId: ctx.user.id,' : ''} title: input.title, createdAt: Date.now() }).returning()
-    return row`}
+    return { ...row, done: false }`
+        : `const [row] = await ctx.db.insert(todos).values({ id: crypto.randomUUID(),${auth ? ' userId: ctx.user.id,' : ''} title: input.title, createdAt: Date.now() }).returning()
+    return row`
+    }
   },
 })
 
@@ -363,139 +288,3 @@ export default function TodosLayout(props: RouteProps) {
   return <>{props.children}</>
 }
 `
-
-// Tailwind: the same files `weft add tailwind` writes (packages/cli/src/tailwind.mjs, held equal by a test).
-/** What `--ui tailwind` adds, pinned. */
-export const tailwindPackages = { tailwindcss: '4.3.3', '@tailwindcss/vite': '4.3.3' }
-/** `vite.config.ts` for `--ui tailwind`. */
-export const TAILWIND_VITE = `import tailwindcss from '@tailwindcss/vite'
-
-export default { plugins: [tailwindcss()] }
-`
-/** The stylesheet for `--ui tailwind`. */
-export const TAILWIND_CSS = `@import "tailwindcss";
-`
-const tw = {
-  card: 'mx-auto max-w-2xl space-y-4 rounded-lg border border-current/15 p-6',
-  title: 'text-2xl font-semibold',
-  button: 'rounded-md border border-current/30 px-3 py-1.5 hover:bg-current/5',
-  input: 'rounded-md border border-current/30 px-3 py-1.5',
-}
-/** The class of a scaffold element: Tailwind's utilities, or the plain CSS in src/app.css. */
-export const classes = (ui, part) => (ui === 'tailwind' ? tw[part] : part === 'card' ? 'card' : '')
-const attr = (ui, part) => (ui === 'tailwind' ? ` class="${tw[part]}"` : '')
-
-/** The page's controls in each UI kit: warp's components, or plain elements with the same roles and names. */
-export const controls = ui => ui === 'warp'
-  ? {
-      imports: `import { Alert, Button, Card, Checkbox, Input } from '@weft-js/warp'\n`,
-      card: (title, body) => `<Card title=${JSON.stringify(title)}>${body}</Card>`,
-      input: (label, box, type = 'text') => `<Input label=${JSON.stringify(label)} type="${type}" value={${box}.value} onInput={e => (${box}.value = e.currentTarget.value)} />`,
-      submit: (label, pending) => `<Button type="submit" loading={${pending}}>${label}</Button>`,
-      button: (label, onClick, extra = '') => `<Button emphasis="ghost" ${extra}onClick={${onClick}}>${label}</Button>`,
-      error: box => `{${box}.value && <Alert tone="critical" live>{${box}.value}</Alert>}`,
-    }
-  : {
-      imports: '',
-      card: (title, body) => `<section class="${classes(ui, 'card')}"><h1${attr(ui, 'title')}>${title}</h1>${body}</section>`,
-      input: (label, box, type = 'text') => `<label>${label} <input${attr(ui, 'input')} type="${type}" value={${box}.value} onInput={e => (${box}.value = e.currentTarget.value)} /></label>`,
-      submit: (label, pending) => `<button${attr(ui, 'button')} type="submit" disabled={${pending}}>${label}</button>`,
-      button: (label, onClick, extra = '') => `<button${attr(ui, 'button')} type="button" ${extra}onClick={${onClick}}>${label}</button>`,
-      error: box => `{${box}.value && <p role="alert">{${box}.value}</p>}`,
-    }
-
-/** `/todos`: the list on the server functions, written for this `--ui`. */
-export function todosPage(ui) {
-  const c = controls(ui)
-  return `import type { Meta } from '@weft-js/start'
-import { Boundary, state } from '@weft-js/core'
-${c.imports}import { addTodo, deleteTodo, listTodos, toggleTodo } from '#/server/todos'
-
-export const meta: Meta = { title: 'Todos' }
-
-// The query is made in here, inside the Boundary, so the Boundary sees it: it shows \`pending\` until the list arrives.
-function TodoList() {
-  const todos = listTodos()
-  return (
-    <ul class="todos">
-      {(todos.value ?? []).map(t => (
-        <li key={t.id} class={t.done ? 'done' : 'open'}>
-          <label>
-            <input type="checkbox" checked={t.done} onChange={() => toggleTodo({ id: t.id })} /> {t.title}
-          </label>
-          <button type="button" aria-label={\`Delete \${t.title}\`} onClick={() => deleteTodo({ id: t.id })}>×</button>
-        </li>
-      ))}
-    </ul>
-  )
-}
-
-export default function Todos() {
-  const title = state('')
-  const problem = state('')
-  const add = async (e: SubmitEvent) => {
-    e.preventDefault()
-    const text = title.value.trim()
-    if (!text) return
-    title.value = ''
-    problem.value = ''
-    await addTodo({ title: text }).catch((err: Error) => (problem.value = err.message))
-  }
-  return (
-    ${c.card('Todos', `
-      <form onSubmit={add}>
-        ${c.input('New todo', 'title')}
-        ${c.submit('Add', 'addTodo.pending.value')}
-      </form>
-      ${c.error('problem')}
-      <Boundary pending={<p>Loading…</p>}>
-        <TodoList />
-      </Boundary>
-    `)}
-  )
-}
-`
-}
-
-/** `/login`: sign in and sign up, written for this `--ui`. */
-export function loginPage(ui) {
-  const c = controls(ui)
-  return `import { redirect, type LoadArgs, type Meta } from '@weft-js/start'
-import { state } from '@weft-js/core'
-${c.imports}import { signIn, signUp } from '#/server/session'
-
-export const load = ({ ctx }: LoadArgs) => {
-  if (ctx.user) redirect('/todos')
-}
-
-export const meta: Meta = { title: 'Sign in' }
-
-export default function Login() {
-  const creating = state(false)
-  const name = state('')
-  const email = state('')
-  const password = state('')
-  const problem = state('')
-  const submit = async (e: SubmitEvent) => {
-    e.preventDefault()
-    problem.value = ''
-    const done = creating.value
-      ? signUp({ name: name.value, email: email.value, password: password.value })
-      : signIn({ email: email.value, password: password.value })
-    await done.catch((err: Error) => (problem.value = err.message))
-  }
-  return (
-    ${c.card('Sign in', `
-      <form onSubmit={submit}>
-        {creating.value && ${c.input('Name', 'name')}}
-        ${c.input('Email', 'email', 'email')}
-        ${c.input('Password', 'password', 'password')}
-        ${c.submit(`{creating.value ? 'Create account' : 'Sign in'}`, 'signIn.pending.value || signUp.pending.value')}
-      </form>
-      ${c.error('problem')}
-      ${c.button(`{creating.value ? 'I have an account' : 'Create an account'}`, '() => (creating.value = !creating.value)')}
-    `)}
-  )
-}
-`
-}

package/src/templates.mjs

@@ -0,0 +1,174 @@
+// `--template`: a real app in `templates/<name>/`, laid over the scaffold. `template.json` holds what it
+// `requires` (db, auth), its `pages`, its `warp()` options and any `dependencies` of its own; `files/` is copied as it is.
+// A template's Drizzle schema is one dialect's, so it names that dialect, and its `drizzle/` ships with it
+// (scripts/template-migrations.mjs): the app runs on a fresh database, and on one that already has these tables.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** What `--template` takes: the apps a scaffold can start as. */
+export const TEMPLATES = ['landing', 'todo', 'admin', 'catalog']
+
+const templates = fileURLToPath(new URL('../templates/', import.meta.url))
+const utf8 = new TextDecoder('utf-8', { fatal: true })
+
+/** Text as a string, and an image or a font as the bytes it is. */
+function contents(file) {
+  const bytes = readFileSync(file)
+  try {
+    return utf8.decode(bytes)
+  } catch {
+    return bytes
+  }
+}
+
+function tree(dir, base = dir) {
+  return Object.fromEntries(
+    readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+      const path = join(dir, entry.name)
+      return entry.isDirectory()
+        ? Object.entries(tree(path, base))
+        : [[relative(base, path).split(sep).join('/'), contents(path)]]
+    }),
+  )
+}
+
+const needed = ({ db }) => [
+  'src/theme.css',
+  'src/routes/_layout.tsx',
+  'src/routes/index.tsx',
+  ...(db === 'none'
+    ? []
+    : ['src/db/schema.ts', 'drizzle/meta/_journal.json', 'drizzle/.schema-hash']),
+]
+
+export function loadTemplate(name) {
+  if (!TEMPLATES.includes(name))
+    throw new Error(`--template must be one of ${TEMPLATES.join(', ')} (got "${name}")`)
+  const manifest = join(templates, name, 'template.json')
+  if (!existsSync(manifest)) throw new Error(`the ${name} template isn't written yet`)
+  const {
+    requires = {},
+    pages = [],
+    warp,
+    dependencies = {},
+  } = JSON.parse(readFileSync(manifest, 'utf8'))
+  const { db = 'none', auth = false } = requires
+  if (!['postgres', 'none'].includes(db))
+    throw new Error(
+      `the ${name} template's requires.db must be postgres or none (got ${JSON.stringify(db)})`,
+    )
+  const files = tree(join(templates, name, 'files'))
+  const missing = needed({ db }).filter((file) => !(file in files))
+  if (missing.length) throw new Error(`the ${name} template has no ${missing.join(', ')}`)
+  return { name, requires: { db, auth }, pages, warp, dependencies, files }
+}
+
+/** The choices with what the template implies filled in. A choice it can't work with is refused, not ignored. */
+export function withTemplate(options) {
+  if (!options.template) return options
+  const {
+    requires: { db, auth },
+    files,
+  } = loadTemplate(options.template)
+  const refuse = (flag, wants) => {
+    throw new Error(`the ${options.template} template needs ${flag} ${wants}`)
+  }
+  if (![undefined, 'warp'].includes(options.ui)) refuse('--ui', 'warp')
+  if (![undefined, 'drizzle'].includes(options.layer)) refuse('--layer', 'drizzle')
+  if (![undefined, db].includes(options.db)) refuse('--db', db)
+  if (options.auth !== undefined && Boolean(options.auth) !== auth)
+    refuse('sign-in', auth ? 'on' : 'off')
+  // Its fonts and media are plugin options in code, which a json or yaml config has no place for.
+  const config = 'weft.config.ts' in files ? 'ts' : options.config
+  if (![undefined, config].includes(options.config)) refuse('--config', config)
+  return {
+    ...options,
+    ui: 'warp',
+    layer: 'drizzle',
+    db,
+    auth: options.auth ?? auth,
+    ...(config && { config }),
+  }
+}
+
+/**
+ * drizzle-kit's Postgres migration, made safe to run over tables that are already there: `create` only what's missing, and
+ * a foreign key only where the column has none, so an existing schema's differently named constraint isn't doubled.
+ */
+export function idempotent(sql) {
+  return sql
+    .replace(/^CREATE TABLE "/gm, 'CREATE TABLE IF NOT EXISTS "')
+    .replace(/^CREATE (UNIQUE )?INDEX "/gm, 'CREATE $1INDEX IF NOT EXISTS "')
+    .replace(
+      /^ALTER TABLE ("\w+") ADD CONSTRAINT "\w+" FOREIGN KEY \("(\w+)"\).*?;/gm,
+      (statement, table, column) =>
+        `DO $$ BEGIN\n  IF NOT EXISTS (SELECT 1 FROM pg_constraint c JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = c.conkey[1] WHERE c.conrelid = '${table}'::regclass AND c.contype = 'f' AND a.attname = '${column}') THEN\n    ${statement}\n  END IF;\nEND $$;`,
+    )
+}
+
+const DATA = {
+  drizzle: 'Tables are in `src/db/schema.ts`; after changing it run `npx weft db generate`.',
+  prisma: 'Tables are in `prisma/schema.prisma`; after changing it run `npx weft db generate`.',
+  native: 'Tables are SQL in `migrations/`; `npx weft db generate <name>` starts a new one.',
+}
+const LOOK = {
+  warp: "The look is `warp({ seed, dials, radius, fonts, tokens })` in the weft config; `weft check` fails with D010 if a pair can't pass.",
+  headless: "The look is `src/app.css`, over warp's `--warp-*` tokens.",
+  tailwind: 'The look is Tailwind utilities; `src/app.css` is the entry.',
+  none: 'The look is `src/app.css`.',
+}
+
+/** The scaffold's AGENTS.md: enough to start. `weft agents-md` writes the full reference over it. */
+export function agentsFile({ ui, db, layer, shipped, auth }) {
+  return [
+    '# AGENTS.md',
+    '',
+    "This is a **weft** app (fine-grained reactive TSX). It is not React: components run once, state is a box, and React hooks don't exist.",
+    '',
+    '## Run',
+    '',
+    '- `npx weft dev`: the dev server.',
+    '- `npx weft build`, then `npx weft start`: production.',
+    '- `npx weft check --json` after every change: each diagnostic has a code, a location, why, and a fix.',
+    '- `npx weft docs <topic>`: rules, props, lists, async, testing, config, diagnostics.',
+    ...(db !== 'none' && !shipped
+      ? [
+          '- `npx weft db generate` before the first run: the first migration. Migrations apply on the next request.',
+        ]
+      : []),
+    ...(shipped
+      ? [
+          '- Set `DATABASE_URL` in `.env` to an empty database. `drizzle/` applies on the first request; there is nothing to run.',
+        ]
+      : []),
+    '',
+    '## Where things go',
+    '',
+    "- `src/routes/`: pages, by file path. `_layout.tsx` wraps what's beside it.",
+    ...(shipped?.length
+      ? [`- This template's pages: ${shipped.map((p) => `\`${p}\``).join(', ')}.`]
+      : []),
+    ...(db === 'none'
+      ? []
+      : [
+          '- `src/server/`: `query` and `mutation` functions; call them from any component.',
+          `- ${DATA[layer]}`,
+          '- `.env`: secrets and `DATABASE_URL`, checked by `src/env.server.ts`.',
+        ]),
+    ...(auth === true
+      ? [
+          '- `src/auth.server.ts`: Better Auth. Login is an opaque session in the database, in an HTTP-only cookie, never a JWT. Pages may answer from its signed cookie cache for 5 minutes (`session.cookieCache`); mutations always read the database. JWTs are for API access only (`api` in `createAuth`, `npx weft docs start`).',
+        ]
+      : []),
+    '- `npx weft map` writes `.weft/map.md`: what this app has and what to call for each part.',
+    '',
+    '## Theming',
+    '',
+    shipped
+      ? "`src/theme.css` is this app's CSS: override `--warp-*` tokens and style `[data-scope]` parts there. The brand, dials and radius are `warp({ seed, dials, radius })` in the weft config."
+      : LOOK[ui],
+    '',
+  ].join('\n')
+}