@weft-js/cli 0.0.0-stage → 0.1.1

package/src/cli.mjs

@@ -0,0 +1,364 @@
+// Argument parsing and output for `weft`. JSON on stdout with --json, human text on stderr.
+// Exit codes: 0 ok, 1 diagnostics with errors (a build refused on one, or a stale AGENTS.md under --check), 2 usage or internal error.
+
+import { fix } from './fix.mjs'
+import { writeTokens } from './tokens.mjs'
+import { createRequire } from 'node:module'
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { addCommand } from './add.mjs'
+import { writeAgentsMd } from './agents-md.mjs'
+import { check } from './check.mjs'
+import { formatHuman, sortDiagnostics } from './diag.mjs'
+import { docs } from './docs.mjs'
+import { compilerLine, doctor, formatDoctor } from './doctor.mjs'
+import { formatMap, writeMap } from './map.mjs'
+import { serve } from './mcp.mjs'
+import { explain, list, sync } from './plugins.mjs'
+import { approveCommand, auditCommand, formatTrust } from './trust.mjs'
+import { loadConfig } from './load-config.mjs'
+import { listSurfaces } from './surface-checks.mjs'
+import { runTask, tasks } from './tasks.mjs'
+import { formatGate, gate } from './gate.mjs'
+import { browserCommand } from './browser/cli.mjs'
+import { metaTable } from './meta-table.mjs'
+import { audit } from './audit.mjs'
+import { buildCommand, dbCommand, devCommand, doctorCommand, routesCommand, startCommand, unsafeAllowed } from './start.mjs'
+import { deployCommand, formatHosts, hostsCommand, initCommand } from './deploy/index.mjs'
+import { explainTarget, findGroups, formatExplain, formatFind, styleMatrix, writeMatrixFile } from './style.mjs'
+
+const usage = `usage: weft <command> [--json] [--root <dir>]
+
+  check [files…] [--preset <p>]  compile in check mode; W-, P- and D-diagnostics with fixes (--verbose: which compiler ran)
+  doctor [--preset <p>]  which compiler this install uses, whether Rust is around (it's optional), and what live data does on the target
+  fix [files…]        apply the safe autofixes
+  tokens              warp's resolved tokens as DTCG, in .weft/tokens/
+  test --gate         the test gate on the diff: fail-before (T010), mutants on changed lines (T011), no weakening (T020)
+                      [--base <ref>] [--budget <sec>] [--max-mutants <n>] [--refactor] [--no-mutation]
+  browser <cmd>       drive the running app (\`weft browser help\`): open, snapshot, act, assert, net, time, record…
+  lsp                 a language server for editors on TypeScript 7: tsc --lsp with inferred props
+  tsc                 type-check the whole project with inferred props (tsc or tsgo; for CI)
+  dev [--port <n>]    the dev server for an app with src/routes (Vite + Nitro)
+  build [--runtime node|bun|deno] [--preset <p>]  production build to .output, and .weft/contract.json; then the
+                      built pages are audited (L-codes) and an error fails the build
+                      [--unsafe-allow <codes>]  go past these codes (R002, L003, a family like L, or all): forces a deploy
+  audit [routes…] [--url <u>] [--all] [--max <n>]  the built pages, or a running site, in a clean Chrome at a phone's
+                      and a desktop's width: axe-core's WCAG rules, console, deprecations, head, sideways scroll, shift
+  deploy [--prod] [--yes] [--target t]  fit check, build for the target, then the host's own CLI; without --yes a dry
+                      run that prints what would run. Netlify, Vercel, Cloudflare, Fly, Render; the live URL at the end
+  deploy hosts        which hosts can run this app, why not, what each costs, and the one weft suggests
+  deploy init [target] [--dry-run] [--force]  the host's files (netlify.toml, fly.toml + Dockerfile…), a GitHub
+                      workflow that checks and deploys on push, and \`deploy\` in the config
+  start [--runtime r] run .output/ on its runtime (the config's \`runtime\`, node by default)
+  db generate [name]  a migration for the schema's changes (it applies on the next request)
+  db live             a migration with change triggers for the tables in \`changes\`
+  db listen           the change feed as its own process, for an app on functions
+  routes [--meta]     the route table; --meta: every route's merged metadata, tags, card mode and H-diagnostics
+  tasks               commands and project tasks
+  run <task>          run a project task from weft.config.ts
+  docs [topic|code]   docs for agents (rules, props, lists, async, testing, config, diagnostics, commands, W014…)
+  agents-md [--check] write AGENTS.md (--check: exit 1 when stale; --stdout: print it)
+  map [--stdout]      write .weft/map.md and .json: a matrix of what to call in this app
+  add <feature>       install a plugin and wire it into the config; also tailwind, auth, db [engine] [--layer drizzle|prisma|native], and rust [name] [--remote] [--dry-run] [--no-install]
+  plugins [list]      plugins, the slots they provide and bind, permissions, diagnostics
+  plugins explain <slot>  binding chain: config → plugin → module → .weft/slots/<id>.ts
+  plugins sync        regenerate .weft/slots/*, .weft/slots.d.ts and .weft/tokens/*
+  plugins audit       each plugin's permissions and code against .weft/plugins.lock.json, and what it uses undeclared
+  plugins approve [name…] [--all]  record them in the lock; with no names, show what's waiting and write nothing
+  style find <query>  style groups that fit what you're about to style (\`card\`, \`status badge\`): reuse before you write
+  style explain <group|selector> [--<axis> <value>] [--states a,b] [--accent intent:token] [--part p]
+                      resolved CSS for one variation, and where each value came from
+  style matrix        write .weft/styles.json (every group: axes, parts, accents, resolved CSS, uses)
+  mcp                 MCP server on stdio: docs, check, tasks, style_find, style_explain, test_gate, browser_*`
+
+/** Flags that take a value (`--base main` or `--base=main`), and boolean flags, beyond the global ones. */
+const valued = new Set(['layer', 'base', 'budget', 'max-mutants', 'concurrency', 'url', 'tab', 'out', 'component', 'from', 'props', 'name', 'scope', 'timeout', 'preset', 'port', 'runtime', 'unsafe-allow', 'max', 'target'])
+/** `weft style explain` takes the group's own axes as flags (`--status late`); these are its fixed ones. */
+const styleFlags = new Set(['states', 'accent', 'part'])
+const booleans = new Set(['dry-run', 'no-install', 'remote', 'gate', 'refactor', 'no-mutation', 'interactive', 'delta', 'graph-only', 'no-graph', 'headed', 'full', 'reload', 'meta', 'all', 'verbose', 'prod', 'yes', 'force'])
+
+export function parse(argv) {
+  const out = { command: argv[0], positional: [], json: false, root: process.cwd(), check: false, stdout: false, flags: {} }
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--json') out.json = true
+    else if (a === '--check') out.check = true
+    else if (a === '--stdout') out.stdout = true
+    else if (a === '--root') out.root = resolve(argv[++i] ?? '.')
+    else if (a.startsWith('--root=')) out.root = resolve(a.slice(7))
+    else if (a.startsWith('--')) {
+      const [name, inline] = a.slice(2).split(/=(.*)/s)
+      if (valued.has(name)) out.flags[name] = inline ?? argv[++i]
+      else if (booleans.has(name) && inline === undefined) out.flags[name] = true
+      else if (out.command === 'style' && styleFlags.has(name)) out.flags[name] = inline ?? argv[++i]
+      else if (out.command === 'style' && /^[a-z][\w-]*$/i.test(name) && (inline ?? argv[i + 1]) !== undefined) (out.flags.axes ??= {})[name] = inline ?? argv[++i]
+      else throw Object.assign(new Error(`unknown flag ${a}`), { code: 'E_USAGE' })
+    } else out.positional.push(a)
+  }
+  return out
+}
+
+export async function main(argv, io = { stdout: process.stdout, stderr: process.stderr }) {
+  const print = data => io.stdout.write(`${JSON.stringify(data, null, 2)}\n`)
+  const say = text => text && io.stderr.write(`${text}\n`)
+  let args
+  try {
+    args = parse(argv)
+    switch (args.command) {
+      case 'lsp': {
+        const { lsp } = await import('./infer/lsp.mjs')
+        const out = lsp(args.root)
+        return await new Promise(ok => { out.server.on('exit', () => ok(0)) })
+      }
+      case 'tsc': {
+        const { propTsc } = await import('./props-checks.mjs')
+        const diagnostics = sortDiagnostics(await propTsc(args.root))
+        if (args.json) print({ ok: !diagnostics.some(d => d.severity === 'error'), diagnostics })
+        say(formatHuman(diagnostics))
+        say(`weft tsc: ${diagnostics.filter(d => d.severity === 'error').length} errors`)
+        return diagnostics.some(d => d.severity === 'error') ? 1 : 0
+      }
+      case 'check': {
+        const result = await check(args.root, { files: args.positional, preset: args.flags.preset })
+        if (args.json) print(result)
+        say(formatHuman(result.diagnostics))
+        if (args.flags.verbose) say(compilerLine(doctor(args.root).compiler))
+        say(`weft check: ${result.summary.files} files, ${result.summary.errors} errors, ${result.summary.warnings} warnings (${result.ms} ms)`)
+        return result.ok ? 0 : 1
+      }
+      case 'doctor': {
+        // What this install compiles with, always; what live data does on the target, for an app that has any.
+        const result = doctor(args.root)
+        const plan = args.flags.preset || existsSync(join(args.root, 'src/realtime.server.ts')) ? await doctorCommand(args.root, { preset: args.flags.preset, runtime: args.flags.runtime }) : undefined
+        const hosts = hostsCommand(args.root, (await loadConfig(args.root)).config)
+        if (args.json) print({ ...result, live: plan, deploy: hosts })
+        else say(`${formatDoctor(result)}\n\nweft doctor: deploy${hosts.target ? ` (target ${hosts.target})` : ''}\n${formatHosts(hosts).replace(/^/gm, '  ')}`)
+        if (!plan) return 0
+        say(`weft doctor: ${plan.preset} (${plan.host})\n  live mode: ${plan.mode}\n  ${plan.says}${plan.required.length ? `\n  required: ${plan.required.join(', ')}` : ''}${plan.options.length ? `\n  options:\n${plan.options.map(o => `    - ${o}`).join('\n')}` : ''}`)
+        say(formatHuman(plan.diagnostics))
+        return plan.diagnostics.some(d => d.severity === 'error') ? 1 : 0
+      }
+      case 'test': {
+        if (!args.flags.gate) throw Object.assign(new Error('`weft test` runs the gate with --gate; run the suite itself with vitest'), { code: 'E_USAGE' })
+        const num = name => (args.flags[name] === undefined ? undefined : Number(args.flags[name]))
+        const result = await gate(args.root, {
+          base: args.flags.base, budgetSec: num('budget'), maxMutants: num('max-mutants'), concurrency: num('concurrency'),
+          refactor: !!args.flags.refactor, mutation: !args.flags['no-mutation'], log: line => say(line),
+        })
+        if (args.json) print(result)
+        say(formatHuman(result.diagnostics))
+        say(formatGate(result))
+        say(`weft test --gate: ${result.ok ? 'pass' : 'fail'}, ${result.summary.changedTests} changed tests, ${result.summary.errors} errors, ${result.summary.warnings} warnings (${result.ms} ms)`)
+        return result.ok ? 0 : 1
+      }
+      case 'browser':
+        return await browserCommand(args, { print, say, io })
+      case 'dev': {
+        const server = await devCommand(args.root, { port: args.flags.port && Number(args.flags.port) })
+        say(`weft dev: ${server.resolvedUrls.local[0]}`)
+        await new Promise(ok => { process.once('SIGINT', ok) })
+        await server.close()
+        return 0
+      }
+      case 'build': {
+        const result = await buildCommand(args.root, { preset: args.flags.preset, runtime: args.flags.runtime, unsafeAllow: args.flags['unsafe-allow'] })
+        if (args.json) print(result)
+        say(formatHuman(result.diagnostics))
+        say(`weft build: ${result.preset} → ${result.output}, ${result.functions} functions in the contract, ${result.audited} pages audited (${result.ms} ms)`)
+        if (!result.ok) say('weft build: failed. The output is written, but fix the errors above before it ships, or `--unsafe-allow <code>` to force it.')
+        return result.ok ? 0 : 1
+      }
+      case 'audit': {
+        const result = await audit(args.root, { url: args.flags.url, routes: args.positional.length ? args.positional : undefined, all: !!args.flags.all, max: args.flags.max && Number(args.flags.max) })
+        if (args.json) print(result)
+        say(formatHuman(result.diagnostics))
+        say(`weft audit: ${result.skipped ?? `${result.pages.length} pages at a phone's and a desktop's width, ${result.diagnostics.length} findings (${result.ms} ms)`}`)
+        return result.ok ? 0 : 1
+      }
+      case 'deploy': {
+        const loaded = await loadConfig(args.root)
+        const sub = args.positional[0]
+        if (sub === 'hosts') {
+          const result = hostsCommand(args.root, loaded.config)
+          if (args.json) print(result)
+          else say(formatHosts(result))
+          return 0
+        }
+        const unsafe = unsafeAllowed(args.flags['unsafe-allow'], loaded.config)
+        if (sub === 'init') {
+          const result = initCommand(args.root, loaded.config, { target: args.positional[1] ?? args.flags.target, dryRun: !!args.flags['dry-run'], force: !!args.flags.force, unsafe })
+          if (args.json) print(result)
+          say(formatHuman(result.findings))
+          say([`weft deploy init ${result.target}${result.dryRun ? ' (dry run: nothing written)' : ''}:`, ...result.actions.map(a => `  ${a}`), '', 'then, once:', ...result.next.map(n => `  ${n}`)].join('\n'))
+          return 0
+        }
+        if (sub !== undefined) throw Object.assign(new Error(`weft deploy ${sub}: use \`weft deploy\`, \`weft deploy hosts\` or \`weft deploy init [target]\``), { code: 'E_USAGE' })
+        const result = await deployCommand(args.root, loaded.config, { target: args.flags.target, prod: !!args.flags.prod, yes: !!args.flags.yes, unsafe, build: (root, o) => buildCommand(root, { ...o, unsafeAllow: args.flags['unsafe-allow'] }) })
+        if (args.json) print(result)
+        say(formatHuman(result.diagnostics))
+        if (result.dryRun) say([`weft deploy: a dry run for ${result.target}${result.prod ? ' (production)' : ' (a preview)'}. With --yes it runs:`, ...result.steps.map(s => `  ${s.what}${s.reads.length ? `\n      reads ${s.reads.join(', ')} from the environment` : ''}`)].join('\n'))
+        else say(`weft deploy: ${result.target}${result.prod ? ' (production)' : ''} → ${result.url ?? 'deployed; the host printed no URL'}`)
+        return 0
+      }
+      case 'start':
+        return await startCommand(args.root, { runtime: args.flags.runtime })
+      case 'db': {
+        const result = await dbCommand(args.root, args.positional[0], args.positional[1])
+        if (args.json) print(result)
+        say(result.output)
+        return 0
+      }
+      case 'routes': {
+        const result = await routesCommand(args.root, { meta: !!args.flags.meta, preset: args.flags.preset })
+        if (args.json) print(result)
+        else say(args.flags.meta ? metaTable(result) : result.routes.map(r => `${r.path.padEnd(24)} ${r.file}`).join('\n'))
+        say(formatHuman(result.diagnostics))
+        return result.ok ? 0 : 1
+      }
+      case 'surfaces': {
+        const surfaces = listSurfaces(args.root)
+        if (args.json) print({ surfaces })
+        else say(surfaces.length ? surfaces.map(x => `${String(x.name).padEnd(20)} ${String(x.kind).padEnd(10)} ${x.file}:${x.line}  props: ${x.props.join(', ') || '(none)'}`).join('\n') : 'No surfaces yet: `weft docs surface`.')
+        return 0
+      }
+      case 'tasks': {
+        const result = await tasks(args.root)
+        if (args.json) print(result)
+        else say(result.tasks.map(t => `${t.available ? ' ' : '·'} ${t.name.padEnd(10)} ${t.description ?? ''}`).join('\n'))
+        say(formatHuman(result.diagnostics))
+        return result.ok ? 0 : 1
+      }
+      case 'run': {
+        if (!args.positional[0]) throw Object.assign(new Error('weft run <task>'), { code: 'E_USAGE' })
+        return await runTask(args.root, args.positional[0])
+      }
+      case 'docs': {
+        const page = await docs(args.root, args.positional[0])
+        if (args.json) print(page)
+        else io.stdout.write(`${page.text}\n`)
+        return 0
+      }
+      case 'agents-md': {
+        const out = await writeAgentsMd(args.root, { check: args.check || args.stdout })
+        if (args.stdout) io.stdout.write(out.text)
+        if (args.json) print({ path: out.path, bytes: out.bytes, limit: 8192, overLimit: out.overLimit, current: out.current, written: out.written })
+        say(`AGENTS.md: ${out.bytes} bytes${out.overLimit ? ' (over the 8 KB limit)' : ''}, ${out.written ? 'written' : out.current ? 'current' : 'stale'}`)
+        return (args.check && !out.current) || out.overLimit ? 1 : 0
+      }
+      case 'map': {
+        const map = await writeMap(args.root)
+        if (args.json) print(map)
+        else if (args.stdout) process.stdout.write(formatMap(map))
+        else say(`.weft/map.md: ${map.rows.length} rows`)
+        return 0
+      }
+      case 'icons': {
+        if (args.positional[0] !== 'publish' || !args.positional[1]) { say('usage: weft icons publish <dir>'); return 1 }
+        const { publish } = await import(pathToFileURL(createRequire(join(args.root, 'package.json')).resolve('@weft-js/warp-icons/compile')).href)
+        const out = await publish(resolve(args.root, args.positional[1]))
+        if (args.json) print(out)
+        else say(`${out.files} files for ${out.icons} icons in ${out.dir}. Nothing was uploaded: host that folder, then set icons({ source }).`)
+        return 0
+      }
+      case 'add': {
+        const result = await addCommand(args.root, args.positional[0], { dryRun: args.flags['dry-run'], install: !args.flags['no-install'], engine: args.positional[1], layer: args.flags.layer, remote: args.flags.remote })
+        if (args.json) print(result)
+        else say(result.already ? `${result.package} is already in ${result.config}` : result.actions.map(a => `${args.flags['dry-run'] ? 'would ' : ''}${a}`).join('\n'))
+        return 0
+      }
+      case 'plugins': {
+        const sub = args.positional[0] ?? 'list'
+        if (sub === 'list') {
+          const result = await list(args.root)
+          if (args.json) print(result)
+          else say(result.plugins.map(p => `${p.name}@${p.version ?? '?'}  ${p.provides.map(s => `${s.slot}${s.key ? `[${s.key}]` : ''}${s.bound ? '' : ' (not bound)'}`).join(', ') || 'no slots'}${p.tokens ? `  tokens --${p.tokens}-*` : ''}`).join('\n') || 'no plugins')
+          say(formatHuman(result.diagnostics))
+          return result.ok ? 0 : 1
+        }
+        if (sub === 'explain') {
+          const result = await explain(args.root, args.positional[1])
+          if (args.json) print(result)
+          else say(JSON.stringify(result.binding, null, 2))
+          return 0
+        }
+        if (sub === 'sync') {
+          const loaded = await loadConfig(args.root)
+          const errors = loaded.diagnostics.filter(d => d.severity === 'error')
+          const written = loaded.diagnostics.some(d => d.code === 'P007') ? [] : sync(args.root, loaded)
+          if (args.json) print({ ok: errors.length === 0, written, diagnostics: loaded.diagnostics })
+          say(formatHuman(loaded.diagnostics))
+          say(`weft plugins sync: ${written.length} files written`)
+          return errors.length ? 1 : 0
+        }
+        if (sub === 'audit') {
+          const loaded = await loadConfig(args.root)
+          const result = auditCommand(args.root, loaded)
+          if (args.json) print(result)
+          else say(result.plugins.map(formatTrust).join('\n') || 'no plugins')
+          say(formatHuman(result.diagnostics))
+          return result.ok ? 0 : 1
+        }
+        if (sub === 'approve') {
+          const result = approveCommand(args.root, await loadConfig(args.root), { names: args.positional.slice(1), all: !!args.flags.all })
+          if (args.json) print(result)
+          else say([...(result.written ? result.approved : result.pending).map(formatTrust), result.written ? `${result.lock}: ${result.approved.length} approved` : result.pending.length ? 'nothing written: name a plugin, or pass --all' : 'nothing waiting', ...result.written ? result.pending.map(p => `still waiting: ${p.name}`) : [], ...(result.gitignore ? ['.gitignore: the lock is no longer ignored, so commit it'] : [])].join('\n'))
+          return result.ok ? 0 : 1
+        }
+        throw Object.assign(new Error(`unknown plugins subcommand ${String(sub)}`), { code: 'E_USAGE' })
+      }
+      case 'fix': {
+        const result = await fix(args.root, { files: args.positional })
+        if (args.json) print(result)
+        else say(result.applied.length ? result.applied.map(a => `${a.file}:${a.span[0]}:${a.span[1]}  ${a.code}`).join('\n') : 'nothing to fix')
+        return 0
+      }
+      case 'tokens': {
+        const result = await writeTokens(args.root)
+        if (args.json) print(result)
+        else say(`${result.dir}: ${result.files.length} files`)
+        return 0
+      }
+      case 'style': {
+        const sub = args.positional[0]
+        if (sub === 'find') {
+          const result = findGroups((await styleMatrix(args.root)).matrix, args.positional.slice(1).join(' '))
+          if (args.json) print(result)
+          else say(formatFind(result))
+          return 0
+        }
+        if (sub === 'explain') {
+          const accent = args.flags.accent ? Object.fromEntries(args.flags.accent.split(/[\s,]+/).filter(Boolean).map(w => w.split(':'))) : undefined
+          const states = args.flags.states?.split(',').map(s => s.trim()).filter(Boolean)
+          const result = explainTarget(await styleMatrix(args.root), args.positional.slice(1).join(' '), { axes: args.flags.axes, states, accent, part: args.flags.part })
+          if (args.json) print(result)
+          else say(formatExplain(result))
+          return 0
+        }
+        if (sub === 'matrix') {
+          const { matrix } = await styleMatrix(args.root)
+          const written = args.stdout ? false : writeMatrixFile(args.root, matrix)
+          if (args.stdout || args.json) print(matrix)
+          say(`.weft/styles.json: ${Object.keys(matrix.groups).length} groups, ${matrix.diagnostics.length} diagnostics, ${args.stdout ? 'not written' : written ? 'written' : 'current'}`)
+          return 0
+        }
+        throw Object.assign(new Error(`weft style ${sub ?? ''}: use find <query>, explain <group|selector> or matrix`), { code: 'E_USAGE' })
+      }
+      case 'mcp':
+        await serve(args.root)
+        return 0
+      case undefined:
+      case 'help':
+      case '--help':
+        say(usage)
+        return args.command ? 0 : 2
+      default:
+        throw Object.assign(new Error(`unknown command ${args.command}`), { code: 'E_USAGE' })
+    }
+  } catch (error) {
+    const code = error.code ?? 'E_INTERNAL'
+    if (args?.json || argv.includes('--json')) print({ ok: false, error: { code, message: error.message } })
+    say(`weft: ${error.message}${code === 'E_USAGE' ? `\n\n${usage}` : ''}`)
+    return code === 'E_REFUSED' ? 1 : 2
+  }
+}

package/src/config.d.ts

@@ -0,0 +1 @@
+export * from '@weft-js/core/config'

package/src/config.mjs

@@ -0,0 +1,5 @@
+// `defineConfig` for weft.config.ts. Identity at runtime; the types (config.d.ts) are the point.
+// Apps import it from `@weft-js/core/config`; the CLI's loader falls back here when a project's weft doesn't resolve.
+
+/** @type {import('@weft-js/core/config').defineConfig} */
+export const defineConfig = config => config

package/src/contributions.mjs

@@ -0,0 +1,69 @@
+// What each plugin's `contribute()` returned, checked against the limits. Apart from plugins.mjs because loading a config needs it and the plugin commands load configs.
+
+export const agentsLimit = 1024
+/** Rows a plugin may add to the agent map. */
+const mapLimit = 5
+const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+
+/** JSON with sorted keys and functions named, so two runs of a pure `contribute()` compare equal. */
+function stable(value) {
+  return JSON.stringify(value, (_, v) => {
+    if (typeof v === 'function') return `[function ${v.name}]`
+    if (v && typeof v === 'object' && !Array.isArray(v)) return Object.fromEntries(Object.keys(v).sort().map(k => [k, v[k]]))
+    return v
+  })
+}
+
+/**
+ * Run `contribute()` for every plugin instance that has one (data-only entries are skipped), in name order.
+ * @param {object[]} plugins unique entries from `plugins`
+ * @param {(code: string, why: string, near: string, extra?: object) => void} report
+ * @param {{ root: string, command?: string }} env
+ * @returns {{ name: string, version?: string, namespace?: string, permissions?: object, manifest: object }[]}
+ */
+export function contributions(plugins, report, env) {
+  const out = []
+  const tokenOwner = new Map()
+  const catalogOwner = new Map()
+  for (const p of [...plugins].sort(byName)) {
+    if (typeof p.contribute !== 'function') continue
+    const run = () => p.contribute({ command: env.command ?? 'check', mode: 'development', root: env.root })
+    let manifest
+    try {
+      manifest = run()
+    } catch (error) {
+      const code = typeof error?.code === 'string' ? error.code : 'P007'
+      report(code, `\`${p.name}\`: ${String(error?.message ?? error).split('\n')[0]}`, p.name, { owner: code === 'P007' ? 'core' : p.name, help: error?.help })
+      continue
+    }
+    let again
+    try {
+      again = run()
+    } catch {}
+    if (!again || stable(again) !== stable(manifest)) report('P117', `\`${p.name}\`'s contribute() returned a different manifest on a second call.`, p.name)
+
+    const ns = p.namespace ?? `${p.name.replace(/^@[^/]+\//, '').replace(/^plugin-/, '')}/`
+    for (const d of manifest.diagnostics ?? []) {
+      if (!d.code.startsWith(ns)) report('P111', `\`${p.name}\` declares \`${d.code}\`, outside its namespace \`${ns}\`.`, p.name)
+    }
+    const agents = manifest.agents
+    if (agents) {
+      const bytes = Buffer.byteLength(agentsSection(agents))
+      if (bytes > agentsLimit) report('P112', `\`${p.name}\`'s AGENTS section is ${bytes} bytes (limit ${agentsLimit}).`, p.name)
+    }
+    if ((manifest.map?.length ?? 0) > mapLimit) report('P112', `\`${p.name}\` adds ${manifest.map.length} map rows (limit ${mapLimit}).`, p.name)
+    const tns = manifest.tokens?.namespace
+    if (tns) {
+      if (tokenOwner.has(tns)) report('P113', `Token namespace \`${tns}\` is contributed by both \`${tokenOwner.get(tns)}\` and \`${p.name}\`.`, p.name)
+      else tokenOwner.set(tns, p.name)
+    }
+    for (const c of manifest.catalog ?? []) {
+      if (catalogOwner.has(c.name)) report('P113', `Catalog entry \`${c.name}\` is contributed by both \`${catalogOwner.get(c.name)}\` and \`${p.name}\`.`, p.name)
+      else catalogOwner.set(c.name, p.name)
+    }
+    out.push({ name: p.name, version: p.version, namespace: ns, permissions: p.permissions ?? {}, manifest })
+  }
+  return out
+}
+
+export const agentsSection = agents => `### ${agents.title}\n\n${agents.text.trim()}\n`

package/src/db-layer.mjs

@@ -0,0 +1,33 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { loadConfig } from './load-config.mjs'
+
+/** The app's data layer: the plugin that declares one, or Drizzle, which is built in. Null with no database. */
+export async function dbLayer(root, loaded) {
+  const { contributions = [] } = loaded ?? await loadConfig(root)
+  const plugin = contributions.find(c => c.manifest.db)?.manifest.db
+  if (plugin) return plugin
+  // Drizzle has no plugin to say so: its config file, or a client from `@weft-js/start/db/*`, does.
+  const entry = join(root, 'src/db/index.server.ts')
+  return existsSync(join(root, 'drizzle.config.ts')) || (existsSync(entry) && readFileSync(entry, 'utf8').includes('@weft-js/start/db/')) ? DRIZZLE : null
+}
+
+const DRIZZLE = {
+  layer: 'drizzle',
+  schema: 'src/db/schema.ts',
+  migrations: 'drizzle',
+  generate(root) {
+    let bin
+    try {
+      const req = createRequire(join(root, 'package.json'))
+      bin = join(dirname(req.resolve('drizzle-kit')), 'bin.cjs')
+    } catch {
+      throw Object.assign(new Error('drizzle-kit is not installed in this project'), { code: 'E_USAGE' })
+    }
+    const r = spawnSync(process.execPath, [bin, 'generate'], { cwd: root, encoding: 'utf8' })
+    if (r.status !== 0) throw Object.assign(new Error(`drizzle-kit generate failed:\n${r.stdout}${r.stderr}`), { code: 'E_INTERNAL' })
+    return r.stdout.trim()
+  },
+}

package/src/deploy/cdn.mjs

@@ -0,0 +1,64 @@
+// What a half-set-up deploy looks like, without touching a provider (research 46 §8, §9): a credential written into a
+// file (E008), Cloudflare in front of nothing or in front of a CDN (E010, E011), and Cloudinary without what it needs
+// (E012–E014).
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { host } from './hosts.mjs'
+
+/** Credentials with a shape of their own, and a value assigned to a key that names one. */
+const SHAPED = [
+  [/\bnfp_[A-Za-z0-9]{20,}/, 'a Netlify token'],
+  [/\bFlyV1\s+fm\d_[A-Za-z0-9+/=_-]{20,}/, 'a Fly token'],
+  [/api\.render\.com\/deploy\/srv-[\w-]+\?key=[\w-]+/, 'a Render deploy hook (its key deploys the service)'],
+  [/cloudinary:\/\/\d+:[^@\s'"]+@/, 'a Cloudinary URL with its secret'],
+]
+const KEYED = /\b[\w-]*(token|secret|api[_-]?key|password)[\w-]*["']?\s*[:=]\s*["']([^"'\s$]{16,})["']/i
+
+const FILES = ['weft.config.ts', 'weft.config.mts', 'weft.config.js', 'weft.config.mjs', 'weft.config.json', 'weft.config.yaml', 'weft.config.yml', 'netlify.toml', 'vercel.json', 'wrangler.toml', 'fly.toml', 'render.yaml', 'Dockerfile']
+
+/** E008: a credential in a file that gets committed, comments included. An env var's name, or `${{ secrets.X }}`, is never one. */
+export function writtenSecrets(root) {
+  const out = []
+  const wf = join(root, '.github/workflows')
+  const files = [...FILES, ...(existsSync(wf) ? readdirSync(wf).filter(f => /\.ya?ml$/.test(f)).map(f => `.github/workflows/${f}`) : [])]
+  for (const file of files) {
+    let text
+    try { text = readFileSync(join(root, file), 'utf8') } catch { continue }
+    text.split('\n').forEach((line, i) => {
+      const shaped = SHAPED.find(([re]) => re.test(line))
+      const keyed = !shaped && KEYED.exec(line)
+      if (shaped || keyed) out.push({ file, line: i + 1, what: shaped ? shaped[1] : `a value for \`${keyed[0].split(/["':=\s]/)[0]}\`` })
+    })
+  }
+  return out
+}
+
+/** Hosts whose own domain says the proxy isn't in front. */
+const OWN = /\.(fly\.dev|onrender\.com|netlify\.app|vercel\.app|workers\.dev|pages\.dev)$/
+
+/** E010–E014 from the config, and the environment when `env` is given (a deploy or `weft doctor`). */
+export function cdnFindings(config = {}, { env } = {}) {
+  const out = []
+  const cdn = config.deploy?.cdn ?? {}
+  const target = config.deploy?.target && host(config.deploy.target)
+  const add = (code, severity, why, fix) => out.push({ code, severity, file: 'weft.config.ts', why, fix })
+  if (cdn.proxy === 'cloudflare') {
+    let url
+    try { url = config.site?.url && new URL(config.site.url).hostname } catch {}
+    if (url && OWN.test(url)) add('E010', 'warning', `\`deploy.cdn.proxy\` is Cloudflare, and \`site.url\` is \`${url}\`, the host's own domain: nothing goes through the proxy, and canonical URLs point past it`, 'Set `site.url` to the domain Cloudflare proxies, with its DNS record proxied (orange cloud) to the host')
+    if (target && target.kind !== 'server') add('E011', 'warning', `\`deploy.cdn.proxy\` puts Cloudflare in front of ${target.name}, which is a CDN already: two caches, and a deploy purges only its own`, 'Drop `cdn.proxy`, or deploy to a server host (`fly`, `render`) behind it')
+  }
+  const images = cdn.images
+  if (images?.provider === 'cloudinary') {
+    const plugins = (config.plugins ?? []).map(p => p?.name ?? p)
+    if (!plugins.some(n => typeof n === 'string' && n.includes('plugin-media'))) add('E012', 'error', '`deploy.cdn.images` is Cloudinary, and `@weft-js/plugin-media` is not in `plugins`: nothing would send it an image', '`weft add media`, or drop `cdn.images`')
+    const given = env?.CLOUDINARY_URL
+    const cloud = given && /@([\w-]+)\/?$/.exec(given)?.[1]
+    if (!images.cloud && !given) add('E013', 'error', '`deploy.cdn.images` names no `cloud`, and `CLOUDINARY_URL` is unset: there is no account to send images to', "Set `cdn.images.cloud` to the cloud's name, and `CLOUDINARY_URL` in the host's environment (never in a file)")
+    else if (cloud && images.cloud && cloud !== images.cloud) add('E013', 'error', `\`cdn.images.cloud\` is \`${images.cloud}\`, and \`CLOUDINARY_URL\` here names \`${cloud}\`: one of them is another account`, 'Make them name the same cloud')
+    else if (env && !given) add('E013', 'warning', '`CLOUDINARY_URL` is unset here: the server needs it in the host\'s environment', 'Set it in the host\'s environment settings, never in a file')
+    add('E014', 'info', '`cdn.images` is checked, but this weft doesn\'t send uploads to Cloudinary yet: they still go to `media({ server: { dir } })`', 'Nothing yet: research 46 §9 is the plan. On a function host, uploads need a server host with a disk until then (E003)')
+  }
+  return out
+}