@weft-js/cli 0.0.0-stage → 0.1.0

package/src/check.mjs

@@ -0,0 +1,328 @@
+// `weft check`: compile every project file in check mode, add the project view, the X-codes (text-checks.mjs), plugin
+// `check` hooks, the test T-codes, the config P-codes, the style D-codes (style.mjs) and the design D-codes (design-checks.mjs), and keep `.weft/styles.json`
+// current when the project has style groups.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { isAbsolute, join, relative, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { diagnostic, locate, positions, sortDiagnostics, summarize } from './diag.mjs'
+import { discover } from './files.mjs'
+import { isDataConfig, loadConfig, writeConfigSchema } from './load-config.mjs'
+import { sync } from './plugins.mjs'
+import { writeMap } from './map.mjs'
+import { projectView } from './project.mjs'
+import { designChecks, hasTokens } from './design-checks.mjs'
+import { classSoup, matrixDiagnostics, styleFiles, styleModule, usesTailwind, writeMatrixFile } from './style.mjs'
+import { checkTests, isTestFile, testGlobs } from './tests.mjs'
+import { pluginChecks } from './plugin-checks.mjs'
+import { propChecks } from './props-checks.mjs'
+import { reactChecks } from './react-checks.mjs'
+import { trustDiagnostics } from './trust.mjs'
+import { shareChecks } from './share-checks.mjs'
+import { stateChecks } from './state-checks.mjs'
+import { surfaceChecks } from './surface-checks.mjs'
+import { textChecks } from './text-checks.mjs'
+import { loadCompiler, resolveWeft } from './weft.mjs'
+import { dbLayer } from './db-layer.mjs'
+import { routeDiagnostics, schemaHash, siteOf, start } from './start.mjs'
+
+const posix = p => p.split('\\').join('/')
+
+/** Q015: the schema's hash against the one `weft db generate` recorded (research 28 §2). */
+function schemaDrift(root, layer) {
+  const schema = layer?.schema && join(root, layer.schema)
+  if (!schema || !existsSync(schema)) return []
+  const file = join(root, layer.migrations, '.schema-hash')
+  if (existsSync(file) && readFileSync(file, 'utf8').trim() === schemaHash(readFileSync(schema))) return []
+  return [diagnostic({ code: 'Q015', file: layer.schema, why: existsSync(file) ? 'The schema changed since the last `weft db generate`: the database will not match it.' : 'No migrations yet: the first request that reads a table fails with Q014.' })]
+}
+
+/** I001–I003: the walk a build does (@weft-js/warp-icons/compile), when the project has the package. */
+async function iconChecks(root) {
+  const require = createRequire(join(root, 'package.json'))
+  let compile
+  for (const from of [() => require.resolve('@weft-js/warp-icons/compile'), () => createRequire(require.resolve('@weft-js/warp'))
+    .resolve('@weft-js/warp-icons/compile')]) {
+    try { compile = from(); break } catch { /* not this way */ }
+  }
+  if (!compile) return []
+  const { findings } = await import(pathToFileURL(compile).href)
+  return findings(root).map(f => diagnostic({ code: f.code, file: f.file, span: [f.line, f.column, f.line, f.column], why: f.why }))
+}
+
+/** H010: what the last build or `weft dev` found keeps an island from waiting (`.weft/hydration.json`, @weft-js/core/hydration). */
+function hydrationChecks(root) {
+  const file = join(root, '.weft', 'hydration.json')
+  if (!existsSync(file)) return []
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')).diagnostics.filter(d => existsSync(join(root, d.file))).map(d => diagnostic({ code: d.code, file: d.file, span: [d.line, 1, d.line, 1], why: d.why, help: d.fix }))
+  } catch {
+    return []
+  }
+}
+
+/**
+ * H001–H007, H011–H016: page metadata, per route, on what the routes really produce (`inspect.mjs`). With `files`, only
+ * when a route is among them. An app that can't run here is still read: a check never fails for what it couldn't start.
+ */
+async function routeChecks(root, loaded, given, reported) {
+  if (!existsSync(join(root, 'src', 'routes')) || loaded.config?.check?.routes === false || loaded.diagnostics.some(d => d.code === 'P007')) return []
+  if (given?.length && !given.some(f => f.startsWith('src/routes/'))) return []
+  let inspect
+  try { inspect = await start(root, 'inspect') } catch { return [] }
+  const keep = list => routeDiagnostics(root, list).filter(d => !(d.code === 'H001' && reported.has('H001')))
+  try {
+    return keep((await inspect.routesMeta({ root, site: siteOf(loaded) })).diagnostics)
+  } catch (error) {
+    return keep([...inspect.staticRouteChecks(root), { code: 'H016', severity: 'info', file: 'src/routes', route: '*', why: `The routes didn't load here, so only their source was checked: ${String(error?.message ?? error).split('\n')[0]}` }])
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {{ files?: string[] }} [options] files relative to `root` (or absolute); default: discovered
+ */
+export async function check(root, options = {}) {
+  const started = performance.now()
+  root = resolve(root)
+  const weft = resolveWeft(root)
+  const compiler = loadCompiler(weft)
+  const loaded = await loadConfig(root)
+  const { config } = loaded
+  // Slot modules and plugin token files stay current with the config (research 13 §2.6).
+  if (!loaded.diagnostics.some(d => d.code === 'P007') && (config.plugins?.length || existsSync(join(root, '.weft', 'slots')))) sync(root, loaded)
+
+  if (loaded.file && isDataConfig(loaded.file)) writeConfigSchema(root)
+  if (existsSync(join(root, '.weft'))) await writeMap(root)
+
+  const exclude = [...(config.check?.exclude ?? []), ...(config.scope?.forbid ?? [])]
+  const given = options.files?.map(f => posix(relative(root, isAbsolute(f) ? f : join(root, f))))
+  const include = config.check?.include ?? ['**/*.{tsx,jsx}']
+  const rels = given?.length ? given.filter(f => /\.[jt]sx$/.test(f) || !isTestFile(f)) : discover(root, { include, exclude })
+  const testRels = given?.length ? given.filter(isTestFile) : discover(root, { include: config.test?.include ?? testGlobs, exclude })
+
+  // Style groups (research 23): the project's definitions first, so each file compiles with the groups it imports.
+  const style = await styleModule(weft)
+  const sfiles = style ? styleFiles(root, config) : []
+  const scan = sfiles.some(f => readFileSync(join(root, f), 'utf8').includes('@weft-js/core/style')) ? style.scanProject(root, sfiles, (...a) => compiler.transform(...a)) : null
+
+  const files = []
+  const posByAbs = new Map()
+  for (const rel of rels) {
+    const abs = join(root, rel)
+    const text = readFileSync(abs, 'utf8')
+    const pos = positions(text)
+    posByAbs.set(abs, pos)
+    const groups = scan ? style.importedGroups(abs, text, f => scan.groups.filter(g => join(root, g.file) === f)) : {}
+    const out = compiler.transform(text, Object.keys(groups).length ? { filename: abs, checkOnly: true, groups } : { filename: rel, checkOnly: true })
+    const diagnostics = out.diagnostics.map(d => {
+      const from = pos.fromByte(d.start)
+      const end = pos.fromByte(d.end)
+      const fix = d.fix && {
+        description: d.fix.description,
+        safe: d.fix.safe,
+        edits: d.fix.edits.map(e => {
+          const a = pos.fromByte(e.start)
+          const b = pos.fromByte(e.end)
+          return { file: rel, span: pos.span(a, b), offset: [a, b], text: e.text }
+        }),
+      }
+      return diagnostic({ code: d.code, severity: d.severity, file: rel, span: pos.span(from, end), offset: [from, end], why: d.message, help: d.help, fix })
+    })
+    files.push({ abs, rel, text, diagnostics })
+  }
+
+  projectView(files, file => posByAbs.get(file.abs))
+
+  const matrix = scan && style.buildMatrix(scan.groups, scan.uses)
+  if (matrix && scan.groups.length) writeMatrixFile(root, matrix)
+  const styles = [...(usesTailwind(root) ? [] : classSoup(files.filter(f => /\.[jt]sx$/.test(f.rel)))), ...(matrix ? matrixDiagnostics(root, matrix) : [])]
+
+  const fontBuild = typeof loaded.slots['font.build'] === 'string' && !loaded.slots['font.build'].startsWith('weft:default')
+  const diagnostics = [
+    ...loaded.diagnostics,
+    ...(loaded.diagnostics.some(d => d.code === 'P007') ? [] : trustDiagnostics(root, loaded)),
+    ...files.flatMap(f => f.diagnostics),
+    ...styles,
+    ...(config.check?.design === false ? [] : designChecks(root, { files, exclude, tokens: hasTokens(root) })),
+    ...textChecks(root, { files, exclude, fontBuild }),
+    ...stateChecks(root, { files, exclude }),
+    ...shareChecks(root, { files }),
+    ...reactChecks({ files }),
+    ...surfaceChecks(root, { files, exclude, slots: loaded.slots }),
+    ...(await pluginChecks(root, loaded, { files, exclude })),
+    ...(await propChecks(root, config)),
+    ...checkTests(root, testRels),
+    ...(await iconChecks(root)),
+    ...hydrationChecks(root),
+    ...hygiene(root),
+    ...(await socketChecks(root)),
+    ...schemaDrift(root, await dbLayer(root, loaded)),
+    ...(await rustChecks(root, loaded)),
+    ...(await liveChecks(root, loaded, options.preset)),
+  ]
+  diagnostics.push(...await routeChecks(root, loaded, given, new Set(loaded.diagnostics.map(d => d.code))))
+  sortDiagnostics(diagnostics)
+  const summary = { files: files.length, tests: testRels.length, ...summarize(diagnostics) }
+  return {
+    version: 1,
+    ok: summary.errors === 0,
+    root,
+    weft: { version: weft.version, from: weft.from, compiler: weft.compilerPath },
+    config: loaded.file ? posix(relative(root, loaded.file)) : null,
+    summary,
+    diagnostics,
+    slots: loaded.slots,
+    styles: matrix ? { groups: Object.keys(matrix.groups).length, matrix: '.weft/styles.json' } : null,
+    files: rels,
+    tests: testRels,
+    ms: Math.round(performance.now() - started),
+  }
+}
+
+/**
+ * R101, R102 from the contract, and R103, R109 from `cargo check`, for an app with a sidecar: an agent gets the same
+ * answer here as from `weft build`, with the function's id on it.
+ */
+async function rustChecks(root, loaded) {
+  let sidecar
+  try { sidecar = await start(root, 'sidecar') } catch { return [] }
+  if (!sidecar.usesRemote(root)) return []
+  const rust = loaded.config?.rust
+  const held = process.env.WEFT_BUILD
+  process.env.WEFT_BUILD = '1'
+  try {
+    const { writeContract } = await start(root, 'contract')
+    const preset = { node: 'node', bun: 'bun', deno: 'deno_server' }[loaded.config?.runtime ?? 'node']
+    const { contract, diagnostics } = await writeContract({ root, site: loaded.config?.site, rust, preset })
+    const out = diagnostics.filter(d => d.code.startsWith('R1')).map(d => diagnostic({ ...d, file: '.weft/contract.json' }))
+    if (out.some(d => d.severity === 'error')) return out
+    for (const service of Object.keys(contract.services ?? {})) {
+      if (rust?.services?.[service]?.external) continue
+      const dir = sidecar.crateDir(root, rust, service)
+      if (!existsSync(dir)) {
+        out.push(diagnostic({ code: 'R109', file: '.weft/contract.json', why: `\`rust://${service}\` has no crate at \`${posix(relative(root, dir))}\`.` }))
+        continue
+      }
+      const checked = await sidecar.cargo('check', { root, dir, service, contract })
+      out.push(...checked.diagnostics.map(({ rendered, ...d }) => diagnostic({ ...d, help: rendered })))
+      out.push(...untouchedQueries(root, dir, contract, service))
+      if (contract.services[service].kind !== 'native' || !checked.ok) continue
+      const wasm = await sidecar.checkWasm({ root, dir, service, contract, preset, rust })
+      out.push(...wasm.diagnostics.map(d => diagnostic(d)))
+    }
+    return out
+  } catch (e) {
+    return [diagnostic({ code: 'R109', severity: 'warning', file: '.weft/contract.json', why: `the contract couldn't be written, so the sidecars weren't checked: ${e.message.split('\n')[0]}` })]
+  } finally {
+    if (held === undefined) delete process.env.WEFT_BUILD
+    else process.env.WEFT_BUILD = held
+  }
+}
+
+/** R105 before anything runs: a cached query with tags whose Rust never mentions `touch`, or hands `ctx` to anything. */
+function untouchedQueries(root, dir, contract, service) {
+  const sources = readdirSync(join(dir, 'src'), { recursive: true, withFileTypes: true }).filter(f => f.isFile() && f.name.endsWith('.rs')).map(f => join(f.parentPath, f.name))
+  const out = []
+  for (const f of contract.functions) {
+    if (f.impl?.service !== service || !f.cache || !(f.tags === 'dynamic' || f.tags?.length)) continue
+    const method = f.name.replace(/[A-Z]/g, (c, i) => `${i ? '_' : ''}${c.toLowerCase()}`)
+    for (const file of sources) {
+      const text = readFileSync(file, 'utf8')
+      const at = text.search(new RegExp(`\\bfn\\s+${method}\\s*\\(`))
+      if (at < 0) continue
+      const open = text.indexOf('{', at)
+      let depth = 0, end = open
+      for (; end < text.length; end++) {
+        if (text[end] === '{') depth++
+        if (text[end] === '}' && --depth === 0) break
+      }
+      const body = text.slice(open, end)
+      const line = text.slice(0, at).split('\n').length
+      if (!/\.touch\(|\(\s*&?ctx\b|,\s*&?ctx\b/.test(body)) out.push(diagnostic({ code: 'R105', severity: 'warning', file: posix(relative(root, file)), span: [line, 1, line, 1], why: `\`${f.id}\` is cached under tags and reports no table: nothing can tell whether they cover what it reads. Call \`ctx.touch("table")\`, or drop \`tags\` if it reads none.` }))
+      break
+    }
+  }
+  return out
+}
+
+/** R013, R014 and R018: what the deploy target does to live data. Only an app with `changes` or `required` loads anything. */
+async function liveChecks(root, loaded, preset) {
+  const file = join(root, 'src/realtime.server.ts')
+  let target
+  try { target = await start(root, 'live-target') } catch { return [] }
+  const required = target.scanRequired(root)
+  if (!required.length && !target.literalSecrets(root).length && !(existsSync(file) && /\bchanges\s*[:,}]/.test(readFileSync(file, 'utf8')))) return []
+  const held = process.env.WEFT_BUILD
+  process.env.WEFT_BUILD = '1'
+  try {
+    const { readLivePlan } = await start(root, 'contract')
+    const plan = await readLivePlan({ root, site: loaded.config?.site, live: loaded.config?.live, preset: preset ?? { node: 'node', bun: 'bun', deno: 'deno_server' }[loaded.config?.runtime ?? 'node'] })
+    return plan.diagnostics.map(d => diagnostic({ ...d, file: d.file ?? required[0]?.file ?? 'src/realtime.server.ts' }))
+  } catch (e) {
+    return [diagnostic({ code: 'R014', severity: 'warning', file: 'src/realtime.server.ts', why: `the deploy target couldn't be checked: ${e.message.split('\n')[0]}` })]
+  } finally {
+    if (held === undefined) delete process.env.WEFT_BUILD
+    else process.env.WEFT_BUILD = held
+  }
+}
+
+/** R001 for a server module's `channel`, and R004 for a socket handler of the app's own (research 32 §1). */
+async function socketChecks(root) {
+  const src = join(root, 'src')
+  if (!existsSync(src)) return []
+  const out = []
+  let withIds
+  for (const f of readdirSync(src, { recursive: true, withFileTypes: true })) {
+    if (!f.isFile() || !/\.[cm]?[jt]sx?$/.test(f.name) || f.name.endsWith('.d.ts')) continue
+    const abs = join(f.parentPath, f.name), rel = relative(root, abs).replaceAll('\\', '/'), text = readFileSync(abs, 'utf8')
+    const hand = /from\s+['"]crossws|\bdefineWebSocketHandler\b/.exec(text)
+    if (hand) out.push(diagnostic({ code: 'R004', file: rel, ...locate(text, hand[0]), why: 'A WebSocket handler of its own skips the Origin check, `authorize`, the limits and resume. Use `channel`.' }))
+    if (!/\b(channel|sharedState)\s*[(<]/.test(text) || !/^src\/server\/|\.server\.[cm]?[jt]sx?$/.test(rel)) continue
+    if (withIds === undefined) {
+      try { withIds = (await import(pathToFileURL(createRequire(join(root, 'package.json')).resolve('@weft-js/start/vite')).href)).withIds } catch { withIds = null }
+    }
+    try { withIds?.(text, abs, rel) } catch (e) {
+      if (e.code !== 'R001') continue
+      const line = +/:(\d+) /.exec(e.message)?.[1]
+      out.push(diagnostic({ code: 'R001', file: rel, span: [line, 1, line, 1], why: e.message.split('\n')[0].replace(/^R001: \S+ /, '') }))
+    }
+  }
+  return out
+}
+
+/** weft owns the connection: these bypass reconnects, resume and the fake transport (research 30 §8). */
+const SOCKET_PACKAGES = ['ws', 'socket.io-client', 'reconnecting-websocket', '@microsoft/fetch-event-source']
+
+/** P002 (`package.json` scripts that aren't `weft …`), P120 (weft plugins wired straight into Vite), R007 (socket libraries). */
+function hygiene(root) {
+  const out = []
+  const pkgFile = join(root, 'package.json')
+  if (existsSync(pkgFile)) {
+    const text = readFileSync(pkgFile, 'utf8')
+    let scripts = {}, deps = {}
+    try {
+      const pkg = JSON.parse(text)
+      scripts = pkg.scripts ?? {}
+      deps = pkg.dependencies ?? {}
+    } catch {}
+    for (const name of SOCKET_PACKAGES) {
+      if (deps[name]) out.push(diagnostic({ code: 'R007', file: 'package.json', ...locate(text, `"${name}"`), why: `\`${name}\` is a dependency: its connection has no resume, no cleanup and no fake in @weft-js/core/test. Use \`stream\`, \`.live()\` or \`channel\`.` }))
+    }
+    for (const [name, cmd] of Object.entries(scripts)) {
+      if (!/^weft(\s|$)/.test(cmd.trim())) {
+        out.push(diagnostic({ code: 'P002', file: 'package.json', ...locate(text, `"${name}"`), why: `Script \`${name}\` runs \`${cmd}\`, not \`weft …\`: agents can't see what it does or what it touches.` }))
+      }
+    }
+  }
+  for (const name of ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs']) {
+    const file = join(root, name)
+    if (!existsSync(file)) continue
+    const text = readFileSync(file, 'utf8')
+    for (const m of text.matchAll(/from\s+['"](@weft-js\/(?:plugin-[\w-]+|text))/g)) {
+      out.push(diagnostic({ code: 'P120', file: name, ...locate(text, m[1]), why: `\`${m[1]}\` is registered in ${name}, which bypasses weft.config.ts.` }))
+    }
+  }
+  return out
+}

package/src/cli.mjs

@@ -0,0 +1,332 @@
+// 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 } from './start.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
+  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'])
+/** `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'])
+
+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
+        if (args.json) print({ ...result, live: plan })
+        else say(formatDoctor(result))
+        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 '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
+  }
+}