@weft-js/create 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 ravonus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @weft-js/create
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Early release (0.1.0).** APIs will change between minor versions.
+
+Starts a new weft app.
+
+```bash
+npm create @weft-js my-app
+```
+
+In a terminal it asks what the flags don't answer. `--yes` takes the defaults.
+
+| Flag | Values | Default |
+|---|---|---|
+| `--ui` | `warp`, `headless` (warp-core only), `tailwind`, `none` | `warp` |
+| `--db` | `sqlite`, `postgres`, `mysql`, `none` | `sqlite` |
+| `--layer` | `drizzle`, `prisma`, `native` | `drizzle` |
+| `--auth`, `--no-auth` | Sign-in, when there's a database | on |
+| `--auth-provider` | `better-auth`, `custom` | `better-auth` |
+| `--runtime` | `node`, `bun`, `deno` | the one running it |
+| `--config` | `ts`, `json`, `yaml`: the format of the weft config | `ts` |
+| `--pm` | `npm`, `pnpm`, `bun`, `deno`, `yarn` | the one you ran it with |
+| `--git`, `--no-git`, `--install`, `--no-install` | Start a git repository; install dependencies | on, or off with no terminal and no `--yes` |
+| `--name` | The package name | the folder's name |
+
+With npm, flags go after `--`: `npm create @weft-js my-app -- --ui tailwind --db none`.
+
+Until weft is on npm, make an app from a checkout instead: [Installation](../../site/content/learn/installation.md).

package/bin/create-weft.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// create-weft [dir] [--ui warp|headless|tailwind|none] [--db sqlite|postgres|mysql|none] [--layer drizzle|prisma|native] [--[no-]auth] [--auth-provider better-auth|custom] [--runtime node|bun|deno]
+//   [--config ts|json|yaml] [--pm npm|pnpm|bun|deno|yarn] [--[no-]git] [--[no-]install] [--name <name>] [--tarballs <dir>] [--yes]
+// In a terminal it asks what the flags don't answer; --yes, or no terminal, takes the defaults.
+import { execFileSync } from 'node:child_process'
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { createInterface } from 'node:readline/promises'
+import { parseArgs } from 'node:util'
+import { CONFIGS, DB, LAYERS, RUNTIMES, scaffold, UI } from '../src/index.mjs'
+import { resolveChoices } from '../src/wizard.mjs'
+import { pin } from '../scripts/tarballs.mjs'
+
+const usage = `Usage: npm create @weft-js -- [dir] [--ui ${UI.join('|')}] [--db ${DB.join('|')}] [--layer ${LAYERS.join('|')}] [--[no-]auth] [--auth-provider better-auth|custom] [--runtime ${RUNTIMES.join('|')}] [--config ${CONFIGS.join('|')}] [--pm <manager>] [--[no-]git] [--[no-]install] [--name <name>] [--tarballs <dir>] [--yes]`
+const string = { type: 'string' }, boolean = { type: 'boolean' }
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  allowNegative: true,
+  options: { ui: string, db: string, layer: string, auth: boolean, 'auth-provider': string, runtime: string, config: string, pm: string, git: boolean, install: boolean, name: string, tarballs: string, yes: { ...boolean, short: 'y' }, help: { ...boolean, short: 'h' } },
+})
+const interactive = process.stdin.isTTY && process.stdout.isTTY
+if (values.help || positionals.length > 1 || (!positionals.length && !interactive)) {
+  console.log(usage)
+  process.exit(values.help ? 0 : 1)
+}
+
+async function directory() {
+  if (positionals.length) return positionals[0]
+  if (values.yes) return 'my-weft-app'
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  const answer = await rl.question('App directory (my-weft-app) ')
+  rl.close()
+  return answer.trim() || 'my-weft-app'
+}
+
+/** Git and the install are conveniences: the app is already written, so a failure here only leaves a step for later. */
+function step(what, command, args, cwd) {
+  try {
+    execFileSync(command, args, { cwd, stdio: ['ignore', 'ignore', 'inherit'], shell: process.platform === 'win32' }) // npm is npm.cmd there
+    return true
+  } catch {
+    console.error(`create-weft: ${what} didn't finish; run \`${[command, ...args].join(' ')}\` yourself.`)
+    return false
+  }
+}
+
+try {
+  const { yes, help: _help, name, tarballs, 'auth-provider': authProvider, ...flags } = values
+  if (authProvider && !['better-auth', 'custom'].includes(authProvider)) throw new Error('--auth-provider must be better-auth or custom')
+  if (authProvider) flags.auth = authProvider === 'custom' ? 'custom' : true
+  const where = await directory()
+  const dir = resolve(where)
+  const choices = await resolveChoices(flags, { interactive, yes, io: { input: process.stdin, output: process.stdout } })
+  const { files } = scaffold(dir, { ...choices, ...(name && { name }) })
+  // Before the install: a checkout's packages aren't on npm, so `local.mjs new` needs them wired in from the start.
+  if (tarballs) {
+    const file = join(dir, 'package.json')
+    writeFileSync(file, JSON.stringify(pin(JSON.parse(readFileSync(file, 'utf8')), JSON.parse(readFileSync(join(tarballs, 'tarballs.json'), 'utf8'))), null, 2))
+  }
+  console.log(`\nCreated ${files.length} files in ${dir}`)
+  if (choices.git) step('git init', 'git', ['init', '--quiet'], dir)
+  const installed = choices.install && step('The install', choices.pm, ['install'], dir)
+  const weft = { npm: 'npx weft', pnpm: 'pnpm exec weft', bun: 'bunx --bun weft', deno: 'deno run -A npm:@weft-js/cli', yarn: 'yarn weft' }[choices.pm]
+  // AGENTS.md comes from the weft just installed, so it always matches the compiler the app runs.
+  if (installed) {
+    const [command, ...args] = weft.split(' ')
+    step('AGENTS.md', command, [...args, 'agents-md'], dir)
+  }
+  console.log(`\n  cd ${where}${installed ? '' : `\n  ${choices.pm} install\n  ${weft} agents-md`}${choices.db === 'none' ? '' : `\n  ${weft} db generate`}\n  ${weft} dev\n`)
+} catch (e) {
+  console.error(`create-weft: ${e.message}`)
+  process.exit(1)
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@weft-js/create",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Scaffold a weft app: npm create @weft-js",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-weft": "./bin/create-weft.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./stack": "./src/stack.mjs"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "weft"
+  ],
+  "files": [
+    "bin",
+    "src",
+    "scripts/tarballs.mjs",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/scripts/tarballs.mjs

@@ -0,0 +1,27 @@
+// Every package as a tarball, and an app's package.json pointed at them: what the packed gates and `local.mjs` share.
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const pkgs = fileURLToPath(new URL('../../', import.meta.url))
+
+/** Pack each package into `dest`. Returns `{ name: 'file:…tgz' }`. */
+export function packAll(dest) {
+  mkdirSync(dest, { recursive: true })
+  const tarballs = {}
+  for (const dir of readdirSync(pkgs)) {
+    const file = join(pkgs, dir, 'package.json')
+    if (!existsSync(file)) continue
+    const { name } = JSON.parse(readFileSync(file, 'utf8'))
+    const packed = execFileSync('npm', ['pack', '--silent', '--pack-destination', dest], { cwd: join(pkgs, dir), encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'] })
+    tarballs[name] = `file:${join(dest, packed.trim().split('\n').pop())}`
+  }
+  return tarballs
+}
+
+/** `pkg` with its weft dependencies on the tarballs. The overrides reach the ones packages declare for each other. */
+export function pin(pkg, tarballs) {
+  for (const deps of [pkg.dependencies, pkg.devDependencies]) for (const name in deps) if (tarballs[name]) deps[name] = tarballs[name]
+  return { ...pkg, overrides: { ...pkg.overrides, ...tarballs } }
+}

package/src/data.mjs

@@ -0,0 +1,288 @@
+// The Native and Prisma data layers of a scaffold (research 34 §4), beside Drizzle's in stack.mjs. Each writes the same
+// todo app, so the same e2e holds for every layer. `weft add db` writes these files too.
+
+const engineSql = {
+  sqlite: { bool: 'integer not null default 0', big: 'integer' },
+  postgres: { bool: 'boolean not null default false', big: 'bigint' },
+  mysql: { bool: 'boolean not null default false', big: 'bigint' },
+}
+
+// Better Auth's tables under its default names, which are camelCase, so they're quoted. MySQL can't key a TEXT column.
+export function nativeAuthSql(db) {
+  const q = name => (db === 'mysql' ? `\`${name}\`` : `"${name}"`)
+  const key = 'varchar(255)'
+  const text = 'text'
+  const when = { sqlite: 'date', postgres: 'timestamptz', mysql: 'datetime(3)' }[db]
+  const bool = { sqlite: 'integer', postgres: 'boolean', mysql: 'boolean' }[db]
+  const table = (name, columns) => `create table ${q(name)} (\n${columns.map(([c, type]) => `  ${q(c)} ${type}`).join(',\n')}\n);\n`
+  const ref = to => `references ${q(to)} (${q('id')}) on delete cascade`
+  const stamps = [['createdAt', `${when} not null`], ['updatedAt', `${when} not null`]]
+  return [
+    table('user', [['id', `${key} primary key`], ['name', `${text} not null`], ['email', `${key} not null unique`], ['emailVerified', `${bool} not null`], ['image', text], ...stamps]),
+    table('session', [['id', `${key} primary key`], ['expiresAt', `${when} not null`], ['token', `${key} not null unique`], ...stamps, ['ipAddress', text], ['userAgent', text], ['userId', `${key} not null ${ref('user')}`]]),
+    table('account', [['id', `${key} primary key`], ['accountId', `${text} not null`], ['providerId', `${text} not null`], ['userId', `${key} not null ${ref('user')}`], ['accessToken', text], ['refreshToken', text], ['idToken', text], ['accessTokenExpiresAt', when], ['refreshTokenExpiresAt', when], ['scope', text], ['password', text], ...stamps]),
+    table('verification', [['id', `${key} primary key`], ['identifier', `${text} not null`], ['value', `${text} not null`], ['expiresAt', `${when} not null`], ['createdAt', when], ['updatedAt', when]]),
+  ].join('\n')
+}
+
+const nativeTodos = auth => {
+  const use = auth ? `\n  auth: 'user',` : ''
+  const mine = auth ? ` and user_id = \${ctx.user.id}` : ''
+  return `import { mutation, query } from '@weft-js/start'
+import { z } from 'zod'
+
+interface Todo { id: string; title: string; done: boolean }
+const byId = z.object({ id: z.string() })
+
+export const listTodos = query({
+  tags: ['todos'],${use}
+  run: async ({ ctx }) => {
+    const rows = await ctx.db.sql\`select id, title, done from todos${auth ? ` where user_id = \${ctx.user.id}` : ''} order by created_at\`
+    return (rows as unknown as Todo[]).map(t => ({ ...t, done: Boolean(t.done) }))
+  },
+})
+
+export const addTodo = mutation({
+  input: z.object({ title: z.string().trim().min(1).max(200) }),${use}
+  invalidates: ['todos'],
+  optimistic: ({ input }, cache) =>
+    cache.update(listTodos, undefined, list => void list.push({ id: \`tmp:\${input.title}\`, title: input.title, done: false })),
+  run: async ({ input, ctx }) => {
+    await ctx.db.sql\`insert into todos (id, title, done, created_at${auth ? ', user_id' : ''}) values (\${crypto.randomUUID()}, \${input.title}, \${false}, \${Date.now()}${auth ? `, \${ctx.user.id}` : ''})\`
+  },
+})
+
+export const toggleTodo = mutation({
+  input: byId,${use}
+  invalidates: ['todos'],
+  optimistic: ({ input }, cache) =>
+    cache.update(listTodos, undefined, list => {
+      const t = list.find(x => x.id === input.id)
+      if (t) t.done = !t.done
+    }),
+  run: async ({ input, ctx }) => {
+    await ctx.db.sql\`update todos set done = not done where id = \${input.id}${mine}\`
+  },
+})
+
+export const deleteTodo = mutation({
+  input: byId,${use}
+  invalidates: ['todos'],
+  optimistic: ({ input }, cache) => cache.update(listTodos, undefined, list => list.filter(x => x.id !== input.id)),
+  run: async ({ input, ctx }) => {
+    await ctx.db.sql\`delete from todos where id = \${input.id}${mine}\`
+  },
+})
+`
+}
+
+export const nativeFiles = ({ db, auth }) => ({
+  'migrations/0000_todos.sql': `${auth ? `${nativeAuthSql(db)}\n` : ''}create table todos (
+  id varchar(36) primary key,
+  title varchar(200) not null,
+  done ${engineSql[db].bool},
+  created_at ${engineSql[db].big} not null${auth ? `,\n  user_id varchar(255) not null references ${db === 'mysql' ? '`user`' : '"user"'} (id) on delete cascade` : ''}
+);
+`,
+  'src/db/index.server.ts': `import { createDb } from '@weft-js/db/plugin-native/${db}'
+import { env } from '../env.server'
+
+export const db = createDb({ url: env.DATABASE_URL })
+`,
+  ...(auth && {
+    'src/auth.server.ts': `import { createAuth } from '@weft-js/start/auth/better-auth'
+import { nativeAuth } from '@weft-js/db/plugin-native/auth'
+import { db } from '#/db/index.server'
+import { env } from './env.server'
+
+export default createAuth({ db, secret: env.BETTER_AUTH_SECRET, options: { database: nativeAuth(db) } })
+`,
+  }),
+  'src/server/todos.ts': nativeTodos(auth),
+})
+
+const PROVIDER = { sqlite: 'sqlite', postgres: 'postgresql', mysql: 'mysql' }
+const ADAPTER = {
+  sqlite: { pkg: '@prisma/adapter-libsql', name: 'PrismaLibSql', make: "{ url: env.DATABASE_URL }" },
+  postgres: { pkg: '@prisma/adapter-pg', name: 'PrismaPg', make: "{ connectionString: env.DATABASE_URL }" },
+  mysql: { pkg: '@prisma/adapter-mariadb', name: 'PrismaMariaDb', make: 'env.DATABASE_URL' },
+}
+export const prismaAdapterPackage = db => ADAPTER[db].pkg
+
+const authModels = db => {
+  const long = db === 'mysql' ? ' @db.Text' : ''
+  return `
+// Better Auth's tables: it reads and writes them through Prisma, with these names.
+model User {
+  id            String    @id
+  name          String
+  email         String    @unique
+  emailVerified Boolean   @map("email_verified")
+  image         String?${long}
+  createdAt     DateTime  @map("created_at")
+  updatedAt     DateTime  @map("updated_at")
+  sessions      Session[]
+  accounts      Account[]
+  todos         Todo[]
+
+  @@map("user")
+}
+
+model Session {
+  id        String   @id
+  expiresAt DateTime @map("expires_at")
+  token     String   @unique
+  createdAt DateTime @map("created_at")
+  updatedAt DateTime @map("updated_at")
+  ipAddress String?  @map("ip_address")
+  userAgent String?  @map("user_agent")${long}
+  userId    String   @map("user_id")
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@map("session")
+}
+
+model Account {
+  id                    String    @id
+  accountId             String    @map("account_id")
+  providerId            String    @map("provider_id")
+  userId                String    @map("user_id")
+  user                  User      @relation(fields: [userId], references: [id], onDelete: Cascade)
+  accessToken           String?   @map("access_token")${long}
+  refreshToken          String?   @map("refresh_token")${long}
+  idToken               String?   @map("id_token")${long}
+  accessTokenExpiresAt  DateTime? @map("access_token_expires_at")
+  refreshTokenExpiresAt DateTime? @map("refresh_token_expires_at")
+  scope                 String?
+  password              String?
+  createdAt             DateTime  @map("created_at")
+  updatedAt             DateTime  @map("updated_at")
+
+  @@map("account")
+}
+
+model Verification {
+  id         String    @id
+  identifier String
+  value      String${long}
+  expiresAt  DateTime  @map("expires_at")
+  createdAt  DateTime? @map("created_at")
+  updatedAt  DateTime? @map("updated_at")
+
+  @@map("verification")
+}
+`
+}
+
+export const prismaAuthModels = db => authModels(db).replace('  todos         Todo[]\n', '')
+
+const prismaTodos = auth => {
+  const use = auth ? `\n  auth: 'user',` : ''
+  const mine = auth ? `, userId: ctx.user.id` : ''
+  return `import { mutation, query } from '@weft-js/start'
+import { z } from 'zod'
+
+const byId = z.object({ id: z.string() })
+
+export const listTodos = query({
+  tags: ['todos'],${use}
+  run: ({ ctx }) => ctx.db.todo.findMany({ where: {${mine.slice(1)} }, orderBy: { createdAt: 'asc' }, select: { id: true, title: true, done: true } }),
+})
+
+export const addTodo = mutation({
+  input: z.object({ title: z.string().trim().min(1).max(200) }),${use}
+  invalidates: ['todos'],
+  optimistic: ({ input }, cache) =>
+    cache.update(listTodos, undefined, list => void list.push({ id: \`tmp:\${input.title}\`, title: input.title, done: false })),
+  run: async ({ input, ctx }) => {
+    await ctx.db.todo.create({ data: { id: crypto.randomUUID(), title: input.title${mine} } })
+  },
+})
+
+export const toggleTodo = mutation({
+  input: byId,${use}
+  invalidates: ['todos'],
+  optimistic: ({ input }, cache) =>
+    cache.update(listTodos, undefined, list => {
+      const t = list.find(x => x.id === input.id)
+      if (t) t.done = !t.done
+    }),
+  run: async ({ input, ctx }) => {
+    const todo = await ctx.db.todo.findFirst({ where: { id: input.id${mine} } })
+    if (todo) await ctx.db.todo.update({ where: { id: todo.id }, data: { done: !todo.done } })
+  },
+})
+
+export const deleteTodo = mutation({
+  input: byId,${use}
+  invalidates: ['todos'],
+  optimistic: ({ input }, cache) => cache.update(listTodos, undefined, list => list.filter(x => x.id !== input.id)),
+  run: async ({ input, ctx }) => {
+    await ctx.db.todo.deleteMany({ where: { id: input.id${mine} } })
+  },
+})
+`
+}
+
+export const prismaFiles = ({ db, auth }) => ({
+  'prisma/schema.prisma': `generator client {
+  provider = "prisma-client"
+  output   = "../src/generated/prisma"
+}
+
+datasource db {
+  provider = "${PROVIDER[db]}"
+}
+${auth ? authModels(db) : ''}
+model Todo {
+  id        String   @id
+  title     String
+  done      Boolean  @default(false)
+  createdAt DateTime @default(now()) @map("created_at")${auth ? `
+  userId    String   @map("user_id")
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)` : ''}
+
+  @@map("todos")
+}
+`,
+  'prisma.config.ts': `import { existsSync } from 'node:fs'
+import { defineConfig } from 'prisma/config'
+
+if (existsSync('.env')) process.loadEnvFile()
+
+export default defineConfig({ schema: 'prisma/schema.prisma', datasource: { url: process.env.DATABASE_URL ?? '' } })
+`,
+  'src/db/index.server.ts': `${db === 'sqlite' ? "import { mkdirSync } from 'node:fs'\n" : ''}import { ${ADAPTER[db].name} } from '${ADAPTER[db].pkg}'
+import { withWeft } from '@weft-js/db/plugin-prisma'
+import { PrismaClient } from '../generated/prisma/client'
+import { env } from '../env.server'
+${db === 'sqlite' ? "\nmkdirSync('.data', { recursive: true })\n" : ''}
+const adapter = new ${ADAPTER[db].name}(${ADAPTER[db].make})
+export const db = withWeft(new PrismaClient({ adapter, log: [{ emit: 'event', level: 'query' }] }), '${PROVIDER[db]}')
+`,
+  ...(auth && {
+    'src/auth.server.ts': `import { createAuth } from '@weft-js/start/auth/better-auth'
+import { prismaAdapter } from 'better-auth/adapters/prisma'
+import { db } from '#/db/index.server'
+import { env } from './env.server'
+
+export default createAuth({ db, secret: env.BETTER_AUTH_SECRET, options: { database: prismaAdapter(db, { provider: '${PROVIDER[db]}' }) } })
+`,
+  }),
+  'src/server/todos.ts': prismaTodos(auth),
+})
+
+/** `--auth-provider custom`: the seam, with nothing behind it yet. An app that compiles, with no one signed in. */
+export const customAuth = `import { defineAuth } from '@weft-js/start/auth'
+
+// Your auth provider. weft needs only these: \`handler\` serves everything under /api/auth, and \`session\` says who a
+// request is, which is \`ctx.user\`. \`auth: 'user'\` on a query or mutation works with whatever you return here.
+export default defineAuth<{ id: string }, { id: string }>({
+  async session(request) {
+    return { user: null, session: null }
+  },
+  async handler(request) {
+    return new Response('Not found', { status: 404 })
+  },
+})
+`

package/src/index.mjs

@@ -0,0 +1,241 @@
+// create-weft: write a new app's files (research 26 §6, research 28 §6). `--ui`: `warp` adds @weft-js/warp and `warp()` in
+// weft.config.ts, `headless` adds @weft-js/warp-core's spec CSS under the app's own markup, `tailwind` adds Tailwind and its Vite plugin,
+// `none` adds nothing. `--db`, `--layer`
+// and `--auth` add a database, a todo app and a sign-in flow (stack.mjs); `--runtime` is what `weft build` targets.
+// AGENTS.md needs the installed weft, so bin/create-weft.mjs runs `weft agents-md` right after the install. Everything
+// else (.weft/, the slot modules) is generated by `weft` itself on the first `weft dev` or `weft check`, so a scaffold
+// never goes stale against the CLI.
+
+import { randomBytes } from 'node:crypto'
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { customAuth } from './data.mjs'
+import { classes, context, loginPage, stackDeps, stackFiles, TAILWIND_CSS, TAILWIND_VITE, tailwindPackages, todosPage, VERSION } from './stack.mjs'
+
+/** What `--ui` takes. */
+export const UI = ['warp', 'headless', 'tailwind', 'none']
+/** What `--db` takes. */
+export const DB = ['sqlite', 'postgres', 'mysql', 'none']
+/** What `--layer` takes. */
+export const LAYERS = ['drizzle', 'prisma', 'native']
+/** What `--runtime` takes. */
+export const RUNTIMES = ['node', 'bun', 'deno']
+/** What `--config` takes. */
+export const CONFIGS = ['ts', 'json', 'yaml']
+
+
+const json = v => JSON.stringify(v, null, 2) + '\n'
+const title = name => name.replace(/[-_]+/g, ' ').replace(/\b\w/g, c => c.toUpperCase())
+
+/** `weft.config.ts`, `.json` or `.yaml`: one schema, so the same app in each (research 34 §2). */
+const LAYER_PLUGIN = { prisma: { pkg: '@weft-js/db/plugin-prisma', name: 'prisma' }, native: { pkg: '@weft-js/db/plugin-native', name: 'native' } }
+
+const appPlugins = ({ ui, layer }) => [...(ui === 'warp' ? [{ pkg: '@weft-js/warp', name: 'warp' }] : []), ...(LAYER_PLUGIN[layer] ? [LAYER_PLUGIN[layer]] : [])]
+
+/** What each plugin a scaffold picks declares. `weft check` fails a scaffold where these fall behind the plugin. */
+const GRANTS = {
+  '@weft-js/warp': ['fs.read:node_modules/@weft-js/warp-core/**', 'fs.write:$TMPDIR/warp-seed-*', 'spawn:node'],
+  '@weft-js/db/plugin-prisma': ['fs.read:prisma/**', 'fs.write:prisma/migrations/**', 'spawn:node'],
+  '@weft-js/db/plugin-native': ['fs.read:migrations/**', 'fs.write:migrations/**'],
+}
+
+/** Choosing a plugin here is approving it. There's no install yet, so `weft plugins approve --all` pins the code later. */
+function pluginLock(options) {
+  const plugins = Object.fromEntries(appPlugins(options).map(p => [p.pkg, { version: null, integrity: null, permissions: GRANTS[p.pkg], provides: [], undeclared: [] }]))
+  return Object.keys(plugins).length ? { '.weft/plugins.lock.json': json({ version: 1, plugins }) } : {}
+}
+
+function configFile(format, { ui, label, runtime, layer }) {
+  const plugins = appPlugins({ ui, layer })
+  const site = { name: label, title: `%s · ${label}`, description: 'Made with weft.' }
+  if (format === 'json') {
+    const config = { $schema: './.weft/config.schema.json', site, ...(plugins.length && { plugins: plugins.map(p => p.pkg) }), ...(runtime !== 'node' && { runtime }) }
+    return { 'weft.config.json': json(config) }
+  }
+  if (format === 'yaml') {
+    return {
+      'weft.config.yaml':
+        `# yaml-language-server: $schema=./.weft/config.schema.json\nsite:\n` +
+        Object.entries(site).map(([k, v]) => `  ${k}: ${JSON.stringify(v)}\n`).join('') +
+        (plugins.length ? `plugins:\n${plugins.map(p => `  - "${p.pkg}"\n`).join('')}` : '') +
+        (runtime !== 'node' ? `runtime: ${runtime}\n` : ''),
+    }
+  }
+  return {
+    'weft.config.ts':
+      `import { defineConfig } from '@weft-js/core/config'\n` +
+      plugins.map(p => `import { ${p.name} } from '${p.pkg}/plugin'\n`).join('') +
+      `\nexport default defineConfig({\n` +
+      `  site: { name: ${JSON.stringify(label)}, title: ${JSON.stringify(site.title)}, description: 'Made with weft.' },\n` +
+      (plugins.length ? `  plugins: [${plugins.map(p => `${p.name}()`).join(', ')}],\n` : '') +
+      (runtime !== 'node' ? `  runtime: '${runtime}',\n` : '') +
+      `})\n`,
+  }
+}
+
+/**
+ * The files for an app, as `{ path: text }`.
+ * @param {{ ui?: string, name?: string, version?: string, db?: string, layer?: string, auth?: boolean | 'custom', runtime?: string, config?: string, secret?: string }} [options]
+ */
+export function template({ ui = 'warp', name = 'weft-app', version = VERSION, db = 'none', layer = 'drizzle', auth = false, runtime = 'node', config = 'ts', secret = randomBytes(32).toString('base64') } = {}) {
+  if (!UI.includes(ui)) throw new Error(`--ui must be one of ${UI.join(', ')} (got "${ui}")`)
+  if (!DB.includes(db)) throw new Error(`--db must be one of ${DB.join(', ')} (got "${db}")`)
+  if (!RUNTIMES.includes(runtime)) throw new Error(`--runtime must be one of ${RUNTIMES.join(', ')} (got "${runtime}")`)
+  if (!CONFIGS.includes(config)) throw new Error(`--config must be one of ${CONFIGS.join(', ')} (got "${config}")`)
+  if (!LAYERS.includes(layer)) throw new Error(`--layer must be one of ${LAYERS.join(', ')} (got "${layer}")`)
+  if (auth && db === 'none') throw new Error('--auth keeps users in a database: add --db sqlite, postgres or mysql')
+  const label = title(name)
+  const stack = stackDeps({ db, auth: auth === true, layer, version })
+  const deps = { '@weft-js/core': version, '@weft-js/start': version }
+  if (ui === 'warp') deps['@weft-js/warp'] = version
+  if (ui === 'headless') deps['@weft-js/warp-core'] = version
+  if (ui === 'tailwind') Object.assign(stack.dev, tailwindPackages)
+
+  const files = {
+    'package.json': json({
+      name,
+      private: true,
+      type: 'module',
+      scripts: { dev: 'weft dev', build: 'weft build', check: 'weft check', typecheck: 'weft tsc', start: 'weft start', ...(db !== 'none' && { 'db:generate': 'weft db generate' }), ...(db !== 'none' && layer === 'prisma' && { postinstall: 'prisma generate' }) },
+      dependencies: { ...deps, ...stack.deps },
+      devDependencies: { '@weft-js/cli': version, typescript: '7.0.2', ...stack.dev },
+    }),
+    ...configFile(config, { ui, label, runtime, layer: db === 'none' ? 'drizzle' : layer }),
+    'tsconfig.json': json({
+      compilerOptions: {
+        target: 'es2022', module: 'esnext', moduleResolution: 'bundler', strict: true, noEmit: true, skipLibCheck: true,
+        jsx: 'preserve', jsxImportSource: '@weft-js/core', lib: ['es2023', 'dom', 'dom.iterable'], paths: { '#/*': ['./src/*'] }, types: db === 'none' ? ['@weft-js/core/client'] : ['@weft-js/core/client', 'node'], plugins: [{ name: '@weft-js/cli/ts-plugin' }],
+      },
+      include: ['src', ...(config === 'ts' ? ['weft.config.ts'] : []), '.weft/*.d.ts'],
+    }),
+    // VS Code's own tsserver only looks for plugins where it's told, and TypeScript 7 ships no tsserver to select instead.
+    '.vscode/settings.json': json({ 'typescript.tsserver.pluginPaths': ['.'] }),
+    '.gitignore': `node_modules/\n.weft/*\n!.weft/plugins.lock.json\n.output/\ndist/\n${db === 'none' ? '' : '.env\n.data/\n'}${layer === 'prisma' ? 'src/generated/\n' : ''}`,
+    'src/routes/_layout.tsx': layout(ui, { db, auth }),
+    'src/routes/index.tsx': home(ui, label),
+    'src/routes/about.tsx': `export const meta = { title: 'About', description: 'What this app is.' }\n\nexport default function About() {\n  return <h1>About</h1>\n}\n`,
+  }
+  Object.assign(files, pluginLock({ ui, layer }))
+  if (ui !== 'warp') files['src/app.css'] = css(ui)
+  if (ui === 'tailwind') files['vite.config.ts'] = TAILWIND_VITE
+  if (db !== 'none') {
+    Object.assign(files, stackFiles({ db, auth: auth === true, name, secret, layer }), { 'src/routes/todos/index.tsx': todosPage(ui) })
+    if (auth === true) files['src/routes/login.tsx'] = loginPage(ui)
+    if (auth === 'custom') Object.assign(files, { 'src/auth.server.ts': customAuth, 'src/context.server.ts': context(true) })
+  }
+  return files
+}
+
+/** Write the app into `dir` (which must be missing or empty). */
+export function scaffold(dir, options = {}) {
+  if (existsSync(dir) && readdirSync(dir).length) throw new Error(`${dir} is not empty`)
+  const files = template({ name: basename(dir).toLowerCase().replace(/[^a-z0-9-_.]/g, '-'), ...options })
+  for (const [rel, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(dir, rel)), { recursive: true })
+    writeFileSync(join(dir, rel), text)
+  }
+  return { dir, files: Object.keys(files) }
+}
+
+function layout(ui, options) {
+  const text = shell(ui, options)
+  return ui === 'tailwind' ? text.replace('<nav>', '<nav class="flex gap-4 p-4">').replace('<main>', '<main class="p-4">') : text
+}
+
+function shell(ui, { db, auth: which }) {
+  const auth = which === true
+  const imports = ui === 'warp' ? '' : (ui === 'headless' ? `import '@weft-js/warp-core/styles/warp.css'\n` : '') + `import '../app.css'\n`
+  const links = db === 'none' ? '' : `\n        <Link href="/todos">Todos</Link>`
+  if (!auth) {
+    return `${imports}import { Link, type RouteProps } from '@weft-js/start'
+
+export default function Root(props: RouteProps) {
+  return (
+    <>
+      <nav>
+        <Link href="/">Home</Link>
+        <Link href="/about">About</Link>${links}
+      </nav>
+      <main>{props.children}</main>
+    </>
+  )
+}
+`
+  }
+  return `${imports}import { Link, type LoadArgs, type RouteProps } from '@weft-js/start'
+import { me, signOut } from '#/server/session'
+
+export const load = ({ ctx }: LoadArgs) => me.fetch()
+
+export default function Root(props: RouteProps<typeof load>) {
+  return (
+    <>
+      <nav>
+        <Link href="/">Home</Link>
+        <Link href="/about">About</Link>${links}
+        {props.data ? <button type="button" onClick={() => signOut()}>Sign out</button> : <Link href="/login">Sign in</Link>}
+      </nav>
+      <main>{props.children}</main>
+    </>
+  )
+}
+`
+}
+
+function home(ui, label) {
+  if (ui === 'warp') {
+    return `import type { Meta } from '@weft-js/start'
+import { state } from '@weft-js/core'
+import { Badge, Button, Card } from '@weft-js/warp'
+
+export const meta: Meta = { title: { absolute: ${JSON.stringify(label)} }, description: ${JSON.stringify(`${label}, made with weft.`)} }
+
+export default function Home() {
+  const count = state(0)
+  return (
+    <Card eyebrow="weft + warp" title=${JSON.stringify(`Welcome to ${label}`)}>
+      <p>
+        Clicked <Badge>{count.value}</Badge> times.
+      </p>
+      <Button onClick={() => count.value++}>Click</Button>
+    </Card>
+  )
+}
+`
+  }
+  return `import type { Meta } from '@weft-js/start'
+import { state } from '@weft-js/core'
+
+export const meta: Meta = { title: { absolute: ${JSON.stringify(label)} }, description: ${JSON.stringify(`${label}, made with weft.`)} }
+
+export default function Home() {
+  const count = state(0)
+  return (
+    <section class=${JSON.stringify(classes(ui, 'card'))}>
+      <h1${named(ui, 'title')}>Welcome to ${label}</h1>
+      <button${named(ui, 'button')} type="button" onClick={() => count.value++}>
+        Clicked {count.value} times
+      </button>
+    </section>
+  )
+}
+`
+}
+
+const named = (ui, part) => (classes(ui, part) ? ` class="${classes(ui, part)}"` : '')
+
+function css(ui) {
+  if (ui === 'tailwind') return TAILWIND_CSS
+  // headless rides warp's tokens (warp-core's warp.css, the fluid title size included); none brings its own.
+  const v = ui === 'headless'
+    ? { bg: 'var(--warp-color-page)', fg: 'var(--warp-color-text)', accent: 'var(--warp-color-accent-solid)', radius: 'var(--warp-radius-surface)', title: 'var(--warp-text-title-size)' }
+    : { bg: 'Canvas', fg: 'CanvasText', accent: 'LinkText', radius: '8px', title: 'clamp(1.5rem, 1.2rem + 2cqi, 2.5rem)' }
+  return `:root { color-scheme: light dark; }
+body { margin: 0; font-family: system-ui, sans-serif; background: ${v.bg}; color: ${v.fg}; }
+nav { display: flex; gap: 1rem; padding: 1rem; }
+main { padding: 1rem; max-inline-size: 60rem; margin-inline: auto; }
+.card { container-type: inline-size; padding: 1.5rem; border-radius: ${v.radius}; border: 1px solid color-mix(in oklab, currentColor 15%, transparent); }
+.card h1 { font-size: ${v.title}; }
+button { font: inherit; padding: 0.5rem 1rem; border-radius: ${v.radius}; border: 1px solid ${v.accent}; background: none; color: inherit; }
+`
+}

package/src/stack.mjs

@@ -0,0 +1,501 @@
+// The `--db` and `--auth` part of a scaffold (research 28 §6): 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 = {
+  '@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',
+}
+
+const pin = (...names) => Object.fromEntries(names.map(n => [n, VERSIONS[n]]))
+
+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
+
+/** 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') }
+  return {
+    deps: pin('@t3-oss/env-core', 'drizzle-orm', 'drizzle-zod', 'zod', ...drivers(db), ...(auth ? ['better-auth'] : [])),
+    dev: pin('drizzle-kit', '@types/node'),
+  }
+}
+
+/** 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 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 = {
+    '.env': envFile({ db, auth, name, secret }),
+    '.env.example': envFile({ db, auth, name, secret: '' }),
+    '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() }),
+  }
+  if (layer === 'native') return { ...shared, ...nativeFiles({ db, auth }) }
+  if (layer === 'prisma') return { ...shared, ...prismaFiles({ db, auth }) }
+  return { ...shared, ...drizzleFiles({ db, auth }) }
+}
+
+function drizzleFiles({ db, auth }) {
+  return {
+    'drizzle.config.ts': `import { defineConfig } from 'drizzle-kit'\n\nexport default defineConfig({ dialect: '${{ postgres: 'postgresql', sqlite: 'sqlite', mysql: 'mysql' }[db]}', schema: './src/db/schema.ts', out: './drizzle' })\n`,
+    'src/db/schema.ts': { postgres: pgSchema, sqlite: sqliteSchema, mysql: mysqlSchema }[db](auth),
+    'src/db/index.server.ts': `import { createDb } from '@weft-js/start/db/${db}'\nimport { env } from '../env.server'\nimport * as schema from './schema'\n\nexport const db = createDb({ schema, url: env.DATABASE_URL })\n`,
+    'src/server/todos.ts': todosServer(auth, db),
+    ...(auth && {
+      'src/auth.server.ts': `import { createAuth } from '@weft-js/start/auth/better-auth'\nimport { drizzleAuth } from '@weft-js/start/auth/drizzle'\nimport { db } from '#/db/index.server'\nimport * as schema from './db/schema'\nimport { env } from './env.server'\n\nexport default createAuth({ db, secret: env.BETTER_AUTH_SECRET, options: { database: drizzleAuth(db, schema) } })\n`,
+    }),
+  }
+}
+
+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` : '')
+
+const envModule = ({ db, auth }) => `import { createEnv } from '@t3-oss/env-core'
+import { z } from 'zod'
+
+// Checked when the server starts. A build holds no secrets, so \`weft build\` skips it.
+export const env = createEnv({
+  server: {
+    DATABASE_URL: ${db !== 'sqlite' ? 'z.url()' : "z.string().min(1).default('file:.data/app.db')"},${auth ? '\n    BETTER_AUTH_SECRET: z.string().min(32),' : ''}
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+  skipValidation: !!process.env.WEFT_BUILD,
+})
+`
+
+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'
+import auth from '#/auth.server'
+import { db } from '#/db/index.server'
+
+export default async ({ request }: { request: Request }) => ({ db, ...(await session(auth, request)) })
+
+type Session = Awaited<ReturnType<typeof auth.session>>
+
+declare module '@weft-js/start' {
+  interface Context {
+    db: typeof db
+    user: Session['user']
+    session: Session['session']
+  }
+}
+`
+  : `import { db } from '#/db/index.server'
+
+export default () => ({ db })
+
+declare module '@weft-js/start' {
+  interface Context {
+    db: typeof db
+  }
+}
+`
+
+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)`
+  // MySQL has no \`returning\`.
+  const returning = db === 'mysql' ? '' : '.returning()'
+  return `import { mutation, query } from '@weft-js/start'
+import { schemasOf } from '@weft-js/start/db'
+import { ${auth ? 'and, ' : ''}asc, eq, not } from 'drizzle-orm'
+import { z } from 'zod'
+import * as schema from '#/db/schema'
+
+const { todos } = schema
+const schemas = schemasOf(schema, { todos: { title: (s: z.ZodString) => s.trim().min(1).max(200) } })
+const byId = z.object({ id: z.string() })
+
+export const listTodos = query({
+  tags: ['todos'],${use}
+  run: ({ ctx }) => ctx.db.select().from(todos)${auth ? '.where(eq(todos.userId, ctx.user.id))' : ''}.orderBy(asc(todos.createdAt)),
+})
+
+export const addTodo = mutation({
+  input: schemas.todos.insert.pick({ title: true }),${use}
+  invalidates: ['todos'],
+  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() }
+    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`}
+  },
+})
+
+export const toggleTodo = mutation({
+  input: byId,${use}
+  invalidates: ['todos'],
+  optimistic: ({ input }, cache) =>
+    cache.update(listTodos, undefined, list => {
+      const t = list.find(x => x.id === input.id)
+      if (t) t.done = !t.done
+    }),
+  run: ({ input, ctx }) => ctx.db.update(todos).set({ done: not(todos.done) }).where(${mine})${returning},
+})
+
+export const deleteTodo = mutation({
+  input: byId,${use}
+  invalidates: ['todos'],
+  optimistic: ({ input }, cache) => cache.update(listTodos, undefined, list => list.filter(x => x.id !== input.id)),
+  run: ({ input, ctx }) => ctx.db.delete(todos).where(${mine})${returning},
+})
+`
+}
+
+const sessionServer = () => `import { mutation, query, redirect } from '@weft-js/start'
+import { forward } from '@weft-js/start/auth'
+import { z } from 'zod'
+import auth from '#/auth.server'
+
+const credentials = z.object({ email: z.email(), password: z.string().min(8) })
+
+/** Who is signed in, or null. */
+export const me = query({
+  tags: ['session'],
+  run: ({ ctx }) => (ctx.user ? { id: ctx.user.id, name: ctx.user.name, email: ctx.user.email } : null),
+})
+
+export const signUp = mutation({
+  input: credentials.extend({ name: z.string().trim().min(1) }),
+  run: async ({ input, ctx }) => {
+    await forward(ctx, auth.api.signUpEmail({ body: input, headers: ctx.request.headers, asResponse: true }))
+    redirect('/todos')
+  },
+})
+
+export const signIn = mutation({
+  input: credentials,
+  run: async ({ input, ctx }) => {
+    await forward(ctx, auth.api.signInEmail({ body: input, headers: ctx.request.headers, asResponse: true }))
+    redirect('/todos')
+  },
+})
+
+export const signOut = mutation({
+  run: async ({ ctx }) => {
+    await forward(ctx, auth.api.signOut({ headers: ctx.request.headers, asResponse: true }))
+    redirect('/login')
+  },
+})
+`
+
+const guard = () => `import { redirect, type LoadArgs, type RouteProps } from '@weft-js/start'
+
+// The guard: a layout's \`load\` runs before its pages', so nothing under /todos runs for a visitor.
+export const load = ({ ctx }: LoadArgs) => {
+  if (!ctx.user) redirect('/login')
+}
+
+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/wizard.mjs

@@ -0,0 +1,78 @@
+// The create-weft wizard (research 34 §3): each choice is a list with the default selected. A flag answers its question,
+// and with no terminal or with --yes every unanswered question takes its default, so agents and CI never see a prompt.
+import { emitKeypressEvents } from 'node:readline'
+import { CONFIGS, DB, LAYERS, RUNTIMES, UI } from './index.mjs'
+
+const PMS = ['npm', 'pnpm', 'bun', 'deno', 'yarn']
+const LABELS = {
+  warp: 'warp', headless: 'Headless (warp behaviour, your markup)', tailwind: 'Tailwind', none: 'None',
+  sqlite: 'SQLite', postgres: 'Postgres', mysql: 'MySQL', drizzle: 'Drizzle', prisma: 'Prisma', native: 'Native (no ORM)', node: 'Node', bun: 'Bun', deno: 'Deno', npm: 'npm', pnpm: 'pnpm', yarn: 'Yarn',
+  ts: 'TypeScript', json: 'JSON', yaml: 'YAML',
+}
+const list = values => values.map(value => ({ value, label: LABELS[value] ?? value }))
+const yesNo = [{ value: true, label: 'Yes' }, { value: false, label: 'No' }]
+/** Whichever of Node, Bun and Deno is running this: a machine may have only that one. */
+const host = process.versions.deno ? 'deno' : process.versions.bun ? 'bun' : 'node'
+const packageManager = env => (host === 'node' ? PMS.find(pm => env.npm_config_user_agent?.startsWith(pm)) ?? 'npm' : host)
+
+/** In order. `when` skips a question that doesn't apply. `sideEffect` questions default to off with no terminal. */
+export const questions = env => [
+  { key: 'ui', label: 'UI', default: 'warp', options: list(UI) },
+  { key: 'db', label: 'Database', default: 'sqlite', options: list(DB) },
+  { key: 'layer', label: 'Data layer', default: 'drizzle', skip: 'drizzle', options: list(LAYERS), when: a => a.db !== 'none' },
+  { key: 'auth', label: 'Sign-in', default: true, options: [{ value: true, label: 'Better Auth' }, { value: 'custom', label: 'Bring your own' }, { value: false, label: 'None' }], when: a => a.db !== 'none' },
+  { key: 'runtime', label: 'Runtime', default: host, options: list(RUNTIMES) },
+  { key: 'config', label: 'Config file', default: 'ts', options: list(CONFIGS) },
+  { key: 'pm', label: 'Package manager', default: packageManager(env), options: list(PMS) },
+  { key: 'git', label: 'Start a git repository', default: true, options: yesNo, sideEffect: true },
+  { key: 'install', label: 'Install dependencies', default: true, options: yesNo, sideEffect: true },
+]
+
+/** One list on a terminal: arrows move, Enter picks. Resolves with the option's value. */
+export function select({ label, options, default: initial }, { input, output }) {
+  let at = Math.max(0, options.findIndex(o => o.value === initial))
+  const draw = first => {
+    if (!first) output.write(`\x1b[${options.length}A`)
+    options.forEach((o, i) => output.write(`\x1b[2K${i === at ? '› ' : '  '}${o.label}\n`))
+  }
+  return new Promise(ok => {
+    output.write(`${label}\n`)
+    draw(true)
+    emitKeypressEvents(input)
+    input.setRawMode?.(true)
+    input.resume()
+    const done = value => {
+      input.off('keypress', onKey)
+      input.setRawMode?.(false)
+      input.pause()
+      ok(value)
+    }
+    const onKey = (_, key) => {
+      if (key?.ctrl && key.name === 'c') {
+        input.setRawMode?.(false)
+        process.exit(130)
+      }
+      if (key?.name === 'return' || key?.name === 'enter') return done(options[at].value)
+      if (key?.name === 'up') at = (at + options.length - 1) % options.length
+      else if (key?.name === 'down') at = (at + 1) % options.length
+      else return
+      draw(false)
+    }
+    input.on('keypress', onKey)
+  })
+}
+
+/** Every choice, from flags, then the terminal if there is one, then the defaults. */
+export async function resolveChoices(given, { interactive, yes = false, env = process.env, io } = {}) {
+  const choices = { ...given }
+  for (const q of questions(env)) {
+    if (q.when && !q.when(choices)) {
+      choices[q.key] ??= q.skip ?? false
+      continue
+    }
+    if (choices[q.key] !== undefined) continue
+    if (interactive && !yes) choices[q.key] = await select(q, io)
+    else choices[q.key] = q.sideEffect && !interactive && !yes ? false : q.default
+  }
+  return choices
+}