@weft-js/cli 0.0.0-stage → 0.1.1

package/src/mcp.mjs

@@ -0,0 +1,195 @@
+// `weft mcp`: an MCP server over stdio (newline-delimited JSON-RPC 2.0) with the tools `docs`, `check`, `routes_meta`, `tasks`,
+// `style_find`, `style_explain`, `test_gate` and the `browser_*` tools.
+// Every tool returns the same JSON as the CLI's `--json`, as text and as structuredContent.
+
+import { audit } from './audit.mjs'
+import { agentMap } from './map.mjs'
+import { once } from 'node:events'
+import { createInterface } from 'node:readline'
+import { check } from './check.mjs'
+import { docs, topics } from './docs.mjs'
+import { listSurfaces } from './surface-checks.mjs'
+import { routesCommand } from './start.mjs'
+import { tasks } from './tasks.mjs'
+import { browser, expectations, actions as browserActions } from './browser/commands.mjs'
+import { gate } from './gate.mjs'
+import { explainTarget, findGroups, styleMatrix } from './style.mjs'
+
+const versions = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05']
+
+const target = {
+  description: 'What the user sees: { role, name } (name exact), { label }, { text }, or a ref from the latest snapshot ("@e12")',
+  anyOf: [
+    { type: 'string', pattern: '^@?e\\d+$' },
+    { type: 'object', properties: { role: { type: 'string' }, name: { type: 'string' }, exact: { type: 'boolean' } }, required: ['role'] },
+    { type: 'object', properties: { label: { type: 'string' } }, required: ['label'] },
+    { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] },
+  ],
+}
+
+/** The `weft browser` commands as tools. The page is the app open in any browser; the dev server relays to it. */
+function browserTools() {
+  const tab = { url: { type: 'string', description: 'Dev server URL (default: .weft/dev.json, then environments.dev.url)' }, tab: { type: 'string', description: 'Tab id from browser_tabs (default: the focused or latest tab)' } }
+  const t = (name, description, properties = {}, required) => ({ name, description, inputSchema: { type: 'object', properties: { ...properties, ...tab }, ...(required ? { required } : {}) } })
+  return [
+    t('browser_tabs', 'Tabs of the app connected to the dev server. Any browser works (yours, the person\'s); with none, call browser_launch. If your own browser can run JS, `await __weft__.agent.run(command, args)` in the page does the same as these tools.'),
+    t('browser_launch', 'Start a headless Chrome on the app (only when you have no browser of your own)', { route: { type: 'string' }, headed: { type: 'boolean' } }),
+    t('browser_open', 'Navigate the tab to a route', { route: { type: 'string' } }, ['route']),
+    t('browser_snapshot', "The page as roles, names and refs (`- button \"Add Banana\" [ref=e15]`), plus weft's live reactive graph with real names (`Cart.total = 42.5 ← Cart.subtotal → 1 binding in <Cart>`), and errors since the last call. Big payloads come back as a file path.", {
+      interactive: { type: 'boolean', description: 'Only interactive elements' }, delta: { type: 'boolean', description: 'Only what changed since the last snapshot' },
+      scope: target, graph: { description: "false: no graph; 'only': only the graph; a string filters it by name", anyOf: [{ type: 'boolean' }, { type: 'string' }] },
+    }),
+    t('browser_act', `Act like a user (user-event, as in @weft-js/core/test) and get back what changed on the page. Actions: ${browserActions.join(', ')}`, { target, action: { type: 'string', enum: browserActions }, value: { type: 'string', description: 'fill/type text, press key (`{Enter}`), select option' } }, ['target', 'action']),
+    t('browser_assert', `Check what the user sees (retries up to timeout ms). Expectations: ${expectations.join(', ')}. Recorded for browser_record.`, { target, expect: { type: 'object', description: '{ text: "Total $4" } | { value: "SAVE10" } | { disabled: true } | { count: 3 } | { absent: true } | …' }, timeout: { type: 'number' } }, ['target', 'expect']),
+    t('browser_state', "Read the named reactive graph, or write a box by its graph name to reach a state fast (dev only)", { filter: { type: 'string', description: 'Name prefix (`Cart`, `cart.`)' }, set: { type: 'string', description: 'Graph name to write, e.g. Cart.coupon' }, value: { description: 'JSON value to write' } }),
+    t('browser_time', "The page's clock: pause (reload: from page load, so startup timers are faked too), advance ms (runs due timers in order), resume, status", { op: { type: 'string', enum: ['pause', 'advance', 'resume', 'status'] }, ms: { type: 'number' }, reload: { type: 'boolean' } }, ['op']),
+    t('browser_net', 'The network as the app sees it: offline (navigator.onLine false, offline event, fetch fails, sockets dropped), online, latency ms (fetch), drop (close open WebSockets/EventSources: a server restart), reset, status', { op: { type: 'string', enum: ['offline', 'online', 'latency', 'drop', 'reset', 'status'] }, ms: { type: 'number' } }, ['op']),
+    t('browser_record', 'Record what happens in the tab (your acts and asserts, and clicks/typing from any browser tool) and turn it into a @weft-js/core/test test, which then has to pass the gate', {
+      op: { type: 'string', enum: ['start', 'stop', 'steps', 'note', 'code'] }, text: { type: 'string' }, component: { type: 'string' }, from: { type: 'string' }, props: { type: 'string' }, name: { type: 'string' }, out: { type: 'string', description: 'Write the test to this file (relative to the project)' },
+    }, ['op']),
+    t('browser_logs', 'Console errors and warnings, and uncaught errors with the weft binding they came from, since the last call'),
+    t('browser_screenshot', 'PNG of the launched Chrome (browser_launch); in your own browser, use its screenshot tool', { out: { type: 'string' } }),
+  ]
+}
+
+/** What `weft mcp` offers an agent: each tool's name, its description and the arguments it takes. */
+export const tools = [
+  {
+    name: 'docs',
+    description: `weft docs for agents. Topics: ${Object.keys(topics).join(', ')}; or a diagnostic code such as W014. No topic: the index.`,
+    inputSchema: { type: 'object', properties: { topic: { type: 'string', description: 'Topic name or diagnostic code' } } },
+  },
+  {
+    name: 'check',
+    description: 'Run `weft check`: every W- and P-diagnostic with code, file, span, why and fix (edits when an autofix exists), plus slot bindings.',
+    inputSchema: { type: 'object', properties: { files: { type: 'array', items: { type: 'string' }, description: 'Files relative to the project root; default: all' } } },
+  },
+  {
+    name: 'routes_meta',
+    description: "Every route's metadata as a crawler gets it (`weft routes --meta --json`): title, description, image, every tag, where each came from (`route`, `layout`, `config`, `auto`, `card`), real samples of param routes, and H-diagnostics with text to apply. Every page sets `meta` from its own context as part of building it: call this after adding or changing a route.",
+    inputSchema: { type: 'object', properties: { preset: { type: 'string', description: "`static`: no server at runtime, so a param route's card needs `prerender`" } } },
+  },
+  {
+    name: 'audit',
+    description: "The pages as a browser renders them (`weft audit`): a clean Chrome at a phone's and a desktop's width, axe-core's WCAG rules (what Lighthouse grades), console errors, deprecations, the head a crawler reads, sideways scroll and layout shift, as L-diagnostics with fixes. Static checks read source; this catches what CSS and a breakpoint do to it. Default: the last build's pages.",
+    inputSchema: { type: 'object', properties: { url: { type: 'string', description: 'A running site to audit instead (a deploy, `weft start`, the dev server)' }, routes: { type: 'array', items: { type: 'string' }, description: 'Paths; default one page of each kind' } } },
+  },
+  {
+    name: 'map',
+    description: 'What this app has and what to call for each part: routes, server functions, data, styles, plugins',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'tasks',
+    description: "List the project's commands and tasks: what each does, its args schema, side effects and allowed environments.",
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'style_find',
+    description: "Before styling anything, find the style groups that already fit (`weft style find`): name, doc, axes and values, parts, states, how often it's used, and similar groups. Reuse or add an axis value; don't write a new group or class list for the same thing.",
+    inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'What the thing is: `card`, `status badge`, `nav`, or a token such as `critical`' } }, required: ['query'] },
+  },
+  {
+    name: 'style_explain',
+    description: 'Explain one variation of a style group (`weft style explain`): every declaration on its root and parts in cascade order with the token, axis, state, compound or accent it came from, the attributes it renders, the CSS it emits, and the call sites that produce it.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: { type: 'string', description: 'A group (`order-card`), a part (`order-card.title`), `order-card[status=late][selected]`, or a DOM selector (`[data-g="order-card"][data-status="late"]`)' },
+        axes: { type: 'object', additionalProperties: { type: 'string' }, description: 'Axis values, e.g. { "status": "late" } (defaults fill the rest)' },
+        states: { type: 'array', items: { type: 'string' }, description: 'States to apply: selected, hover…' },
+        accent: { type: 'object', additionalProperties: { type: 'string' }, description: 'A call-site accent, intent → token: { "radius": "round" }' },
+        part: { type: 'string', description: 'Only this part (and the root)' },
+      },
+      required: ['target'],
+    },
+  },
+  {
+    name: 'surfaces',
+    description: "List the project's canvas and WebGL surfaces (`weft surfaces`): each `defineSurface` with its name, kind, props and file, ready to drop in as `<Surface use={X} label=\"…\" />`.",
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'test_gate',
+    description: 'Run the test gate on the diff (`weft test --gate`): each new or changed test must fail on the old code (T010), kill a mutant of the changed lines (T011), and no existing test may get weaker (T020). Returns per-test results, surviving mutants with what to assert, and diagnostics.',
+    inputSchema: { type: 'object', properties: { base: { type: 'string', description: 'Git ref to diff against (default HEAD: the uncommitted change)' }, budgetSec: { type: 'number' }, maxMutants: { type: 'number' }, refactor: { type: 'boolean' } } },
+  },
+  ...browserTools(),
+]
+
+async function callBrowser(root, name, args) {
+  const o = { url: args.url, tab: args.tab }
+  const cmd = name.slice('browser_'.length)
+  if (cmd === 'state') return args.set ? browser(root, 'set', { name: args.set, value: args.value }, o) : browser(root, 'graph', { filter: args.filter }, o)
+  return browser(root, cmd, args, o)
+}
+
+/** Handle one JSON-RPC message. Returns the response, or undefined for notifications. */
+export async function handle(root, msg) {
+  const reply = result => ({ jsonrpc: '2.0', id: msg.id, result })
+  const fail = (code, message) => ({ jsonrpc: '2.0', id: msg.id ?? null, error: { code, message } })
+  if (msg?.jsonrpc !== '2.0' || typeof msg.method !== 'string') return fail(-32600, 'Invalid Request')
+  const notification = msg.id === undefined
+  switch (msg.method) {
+    case 'initialize': {
+      const asked = msg.params?.protocolVersion
+      return reply({
+        protocolVersion: versions.includes(asked) ? asked : versions[0],
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: 'weft', version: '0.1.1' },
+        instructions: 'weft is a fine-grained reactive TSX framework, not React. Read `docs` topic `rules` first, and run `check` after every edit. Every page sets `meta` from its own context as part of building it (`docs` topic `meta`). Style with groups from @weft-js/core/style, not class lists: `style_find` before you write one. Verify behavior in the running app with the browser_* tools (or `__weft__.agent` in your own browser), and run `test_gate` before you call a change done.',
+      })
+    }
+    case 'ping':
+      return reply({})
+    case 'tools/list':
+      return reply({ tools })
+    case 'tools/call': {
+      const { name, arguments: args = {} } = msg.params ?? {}
+      try {
+        let data
+        if (name === 'docs') {
+          const page = await docs(root, args.topic)
+          return reply({ content: [{ type: 'text', text: page.text }] })
+        }
+        if (name === 'check') data = await check(root, { files: args.files })
+        else if (name === 'tasks') data = await tasks(root)
+        else if (name === 'routes_meta') data = await routesCommand(root, { meta: true, preset: args.preset })
+        else if (name === 'audit') data = await audit(root, { url: args.url, routes: args.routes })
+        else if (name === 'map') data = await agentMap(root)
+        else if (name === 'style_find') data = findGroups((await styleMatrix(root)).matrix, args.query)
+        else if (name === 'style_explain') data = explainTarget(await styleMatrix(root), args.target, { axes: args.axes, states: args.states, accent: args.accent, part: args.part })
+        else if (name === 'surfaces') data = { surfaces: listSurfaces(root) }
+        else if (name === 'test_gate') data = await gate(root, { base: args.base, budgetSec: args.budgetSec, maxMutants: args.maxMutants, refactor: args.refactor })
+        else if (name.startsWith('browser_')) data = await callBrowser(root, name, args)
+        else return fail(-32602, `Unknown tool: ${name}`)
+        return reply({ content: [{ type: 'text', text: JSON.stringify(data) }], structuredContent: data, isError: false })
+      } catch (error) {
+        return reply({ content: [{ type: 'text', text: `${error.code ?? 'E_INTERNAL'}: ${error.message}` }], isError: true })
+      }
+    }
+    default:
+      return notification ? undefined : fail(-32601, `Method not found: ${msg.method}`)
+  }
+}
+
+/** Answer newline-delimited JSON-RPC from `input`, one message at a time; resolves once `input` has closed and the last answer is out. */
+export function serve(root, input = process.stdin, output = process.stdout) {
+  const rl = createInterface({ input, crlfDelay: Infinity })
+  const write = obj => output.write(`${JSON.stringify(obj)}\n`)
+  let queue = Promise.resolve()
+  rl.on('line', line => {
+    if (!line.trim()) return
+    queue = queue.then(async () => {
+      let msg
+      try {
+        msg = JSON.parse(line)
+      } catch {
+        return write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } })
+      }
+      const res = await handle(root, msg)
+      if (res) write(res)
+    })
+  })
+  return once(rl, 'close').then(() => queue)
+}

package/src/meta-table.mjs

@@ -0,0 +1,28 @@
+// The human form of `weft routes --meta`: one line per page, and one per sampled page of a param route, with where each
+// value came from. `--json` has everything else (every tag, the merged object).
+
+const short = (s, n) => {
+  const text = s ?? ''
+  return text.length > n ? text.slice(0, n - 1) + '…' : text
+}
+
+const cell = (s, n) => short(s, n).padEnd(n)
+
+/** `/_weft/og/users/42.png?v=abc` → `card: users/42.png`; an explicit image as it is. */
+const imageOf = url => (!url ? 'none' : url.replace(/^https?:\/\/[^/]+/, '').replace(/^\/_weft\/og\//, '/_weft/og/').replace(/\?v=.*/, ''))
+
+export function metaTable(result) {
+  const rows = []
+  for (const r of result.routes) {
+    if (r.kind !== 'page' || r.redirect !== undefined) continue
+    const add = (path, title, description, image, source) => rows.push({ path, title, description, image: imageOf(image), source: source ? `${source.title}/${source.description}/${source.image}` : 'source only' })
+    if (r.samples?.length) {
+      r.samples.slice(0, 3).forEach(s => add(s.url, s.title, s.description, s.image, s.source))
+      if (r.samples.length > 3) rows.push({ path: `  … ${r.samples.length - 3} more of ${r.path}`, title: '', description: '', image: '', source: '' })
+    } else add(r.url ?? r.path, r.meta?.title, r.meta?.description, r.meta?.og?.image?.url, r.source)
+  }
+  const width = { path: Math.min(30, Math.max(5, ...rows.map(r => r.path.length))), image: Math.min(34, Math.max(5, ...rows.map(r => r.image.length))) }
+  const line = r => `${cell(r.path, width.path)}  ${cell(r.title, 36)}  ${cell(r.description, 48)}  ${cell(r.image, width.image)}  ${r.source}`
+  const url = result.site?.url ? `site.url ${result.site.url}` : 'site.url not set'
+  return [`${url}. source: title/description/image, each route, layout, config, auto or card.`, line({ path: 'route', title: 'title', description: 'description', image: 'image', source: 'source' }), ...rows.map(line)].join('\n')
+}

package/src/mutate.mjs

@@ -0,0 +1,140 @@
+// Mutants on the changed lines of a source file (the gate's T011). weft mutates source text, not compiled output, so
+// each mutant goes through the weft compiler like any edit and its W-codes still apply. Operators follow Stryker's
+// common set: equality, boundaries, logic, arithmetic, negation, literals, conditions, removed calls, JSX text.
+
+import ts from 'typescript'
+import { positions } from './diag.mjs'
+import { parse } from './tests.mjs'
+
+const K = ts.SyntaxKind
+const swaps = new Map([
+  [K.EqualsEqualsEqualsToken, ['!==']], [K.ExclamationEqualsEqualsToken, ['===']],
+  [K.EqualsEqualsToken, ['!=']], [K.ExclamationEqualsToken, ['==']],
+  [K.LessThanToken, ['<=', '>=']], [K.LessThanEqualsToken, ['<', '>']],
+  [K.GreaterThanToken, ['>=', '<=']], [K.GreaterThanEqualsToken, ['>', '<']],
+  [K.AmpersandAmpersandToken, ['||']], [K.BarBarToken, ['&&']], [K.QuestionQuestionToken, ['&&']],
+  [K.PlusToken, ['-']], [K.MinusToken, ['+']], [K.AsteriskToken, ['/']], [K.SlashToken, ['*']], [K.PercentToken, ['*']],
+])
+
+/** Lines (1-based) of `after` that are new or changed since `before` (null: every line). LCS over lines. */
+export function changedLines(before, after) {
+  const b = after.split('\n')
+  if (before == null) return new Set(b.map((_, i) => i + 1))
+  const a = before.split('\n')
+  // Trim the common head and tail; the middle is usually small.
+  let start = 0
+  while (start < a.length && start < b.length && a[start] === b[start]) start++
+  let ea = a.length, eb = b.length
+  while (ea > start && eb > start && a[ea - 1] === b[eb - 1]) { ea--; eb-- }
+  const A = a.slice(start, ea), B = b.slice(start, eb)
+  const out = new Set()
+  if (A.length * B.length > 4e6) { for (let i = start; i < eb; i++) out.add(i + 1); return out }
+  const dp = Array.from({ length: A.length + 1 }, () => new Uint32Array(B.length + 1))
+  for (let i = A.length - 1; i >= 0; i--) for (let j = B.length - 1; j >= 0; j--) dp[i][j] = A[i] === B[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1])
+  let i = 0, j = 0
+  while (j < B.length) {
+    if (i < A.length && A[i] === B[j]) { i++; j++ }
+    else if (i < A.length && dp[i + 1][j] >= dp[i][j + 1]) i++
+    else out.add(start + ++j)
+  }
+  return out
+}
+
+/**
+ * Mutants whose code starts on one of `lines`.
+ * @returns {{ id: string, file: string, line: number, column: number, op: string, start: number, end: number, original: string, replacement: string }[]}
+ */
+export function mutants(text, rel, lines) {
+  const sf = parse(text, rel)
+  const pos = positions(text)
+  const out = []
+  const add = (node, op, replacement, start = node.getStart(sf), end = node.getEnd()) => {
+    const [line, column] = pos.lineCol(start)
+    if (!lines.has(line)) return
+    const original = text.slice(start, end)
+    if (original === replacement) return
+    out.push({ id: `${rel}:${line}:${column}:${op}:${out.length}`, file: rel, line, column, op, start, end, original, replacement })
+  }
+  const skip = n => ts.isImportDeclaration(n) || ts.isExportDeclaration(n) || ts.isTypeNode(n) || ts.isInterfaceDeclaration(n) || ts.isTypeAliasDeclaration(n) || ts.isEnumDeclaration(n)
+  const visit = n => {
+    if (skip(n)) return
+    if (ts.isBinaryExpression(n)) {
+      for (const r of swaps.get(n.operatorToken.kind) ?? []) add(n.operatorToken, 'operator', r)
+    } else if (ts.isPrefixUnaryExpression(n) && n.operator === K.ExclamationToken) {
+      add(n, 'negation', n.operand.getText(sf))
+    } else if (n.kind === K.TrueKeyword || n.kind === K.FalseKeyword) {
+      add(n, 'boolean', n.kind === K.TrueKeyword ? 'false' : 'true')
+    } else if (ts.isNumericLiteral(n)) {
+      const v = Number(n.text)
+      if (Number.isFinite(v)) add(n, 'number', String(v === 0 ? 1 : v + 1))
+    } else if ((ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n)) && n.text && !isKey(n)) {
+      add(n, 'string', '""')
+    } else if (ts.isConditionalExpression(n)) {
+      add(n.condition, 'condition', 'true')
+      add(n.condition, 'condition', 'false')
+    } else if (ts.isIfStatement(n)) {
+      add(n.expression, 'condition', 'true')
+      add(n.expression, 'condition', 'false')
+    } else if (ts.isExpressionStatement(n) && ts.isCallExpression(unparen(n.expression)) && !isDirective(n)) {
+      add(n, 'call', ';')
+    } else if (ts.isJsxText(n) && n.text.trim()) {
+      const start = n.pos + n.text.indexOf(n.text.trim()) // JSX text: `text` starts at `pos`, before any trivia
+      add(n, 'jsx-text', '', start, start + n.text.trim().length)
+    } else if (ts.isReturnStatement(n) && n.expression && isFn(n.parent?.parent) && !ts.isJsxElement(unparen(n.expression)) && !ts.isJsxFragment(unparen(n.expression))) {
+      add(n.expression, 'return', 'undefined')
+    }
+    ts.forEachChild(n, visit)
+  }
+  visit(sf)
+  return out
+}
+
+const unparen = n => { while (ts.isParenthesizedExpression(n)) n = n.expression; return n }
+const isFn = n => n && (ts.isFunctionDeclaration(n) || ts.isFunctionExpression(n) || ts.isArrowFunction(n) || ts.isMethodDeclaration(n))
+const isDirective = n => ts.isStringLiteral(n.expression)
+/** Strings that name things rather than being data: property keys, element-access keys, `import()` specifiers. */
+const isKey = n => {
+  const p = n.parent
+  return (ts.isPropertyAssignment(p) && p.name === n) || ts.isElementAccessExpression(p) || ts.isLiteralTypeNode(p) || ts.isExternalModuleReference(p) ||
+    (ts.isCallExpression(p) && p.expression.kind === K.ImportKeyword) || ts.isJsxAttribute(p) && /^(key|class|className|style|id|type|role|for|htmlFor|name)$/.test(p.name.getText())
+}
+
+export const apply = (text, m) => text.slice(0, m.start) + m.replacement + text.slice(m.end)
+
+/** Spread a sample over lines: one mutant per line in turn, deterministic. */
+export function sample(list, max) {
+  if (list.length <= max) return list
+  const byLine = new Map()
+  for (const m of list) {
+    const k = `${m.file}:${m.line}`
+    if (!byLine.has(k)) byLine.set(k, [])
+    byLine.get(k).push(m)
+  }
+  const queues = [...byLine.values()]
+  const out = []
+  for (let round = 0; out.length < max; round++) {
+    let any = false
+    for (const q of queues) if (q[round]) { out.push(q[round]); any = true; if (out.length >= max) break }
+    if (!any) break
+  }
+  return out
+}
+
+/** What a test that kills this mutant would check: the hint surviving mutants come back with (MUTGEN/ACH loop). */
+export function suggest(m) {
+  const at = `${m.file}:${m.line}`
+  switch (m.op) {
+    case 'operator':
+      if (/^[<>]=?$/.test(m.original)) return `${at}: \`${m.original}\` → \`${m.replacement}\` survives. Assert the boundary: the value exactly at the limit.`
+      if (/^(&&|\|\||\?\?)$/.test(m.original)) return `${at}: \`${m.original}\` → \`${m.replacement}\` survives. Assert a case where only one side of the condition holds.`
+      if (/^[!=]=/.test(m.original)) return `${at}: \`${m.original}\` → \`${m.replacement}\` survives. Assert both the matching and the non-matching case.`
+      return `${at}: \`${m.original}\` → \`${m.replacement}\` survives. Assert the computed value, not only that something rendered.`
+    case 'boolean': case 'condition': case 'negation':
+      return `${at}: \`${m.original}\` → \`${m.replacement}\` survives. Assert what the user sees on the branch this condition guards.`
+    case 'number': return `${at}: ${m.original} → ${m.replacement} survives. Assert the exact value this number produces.`
+    case 'string': case 'jsx-text': return `${at}: the text ${JSON.stringify(m.original.slice(0, 40))} can be blanked. Assert the text the user sees.`
+    case 'call': return `${at}: removing \`${m.original.slice(0, 60)}\` survives. Assert the effect of that call.`
+    case 'return': return `${at}: returning undefined survives. Assert what this function's result shows.`
+    default: return `${at}: ${m.op} survives`
+  }
+}

package/src/plugin-checks.mjs

@@ -0,0 +1,89 @@
+// Plugin `check` hooks (research 13 §2.3 `CheckHook`, research 26 §2.5): a plugin's manifest may carry
+// `check: { include: string[], run(ctx) }`. `weft check` runs it once over the matching files, never on HMR. The
+// hook reads through `ctx` (the files, a JSX view, other project files) and returns diagnostics in its namespace.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { entry } from './catalog.mjs'
+import { diagnostic, positions } from './diag.mjs'
+import { discover, matcher } from './files.mjs'
+import { importOf, scanJsx } from './jsx-scan.mjs'
+
+/**
+ * @param {string} root
+ * @param {{ contributions: { name: string, namespace: string, manifest: any }[] }} loaded
+ * @param {{ files: { rel: string, text: string }[], exclude?: string[] }} options the files `weft check` compiled
+ */
+export async function pluginChecks(root, loaded, { files, exclude = [] }) {
+  const out = []
+  const texts = new Map(files.map(f => [f.rel, f.text]))
+  const read = rel => {
+    if (!texts.has(rel)) texts.set(rel, existsSync(join(root, rel)) ? readFileSync(join(root, rel), 'utf8') : '')
+    return texts.get(rel)
+  }
+  const scans = new Map()
+  const jsx = rel => {
+    if (!scans.has(rel)) {
+      try {
+        scans.set(rel, scanJsx(read(rel), rel))
+      } catch {
+        scans.set(rel, { imports: [], elements: [], functions: new Map() })
+      }
+    }
+    return scans.get(rel)
+  }
+
+  for (const c of loaded.contributions) {
+    const hook = c.manifest.check
+    if (!hook || typeof hook.run !== 'function') continue
+    const include = hook.include ?? ['**/*.{tsx,jsx}']
+    const wanted = matcher(include)
+    /** @type {Set<string>} */
+    const chosen = new Set([...files.map(f => f.rel).filter(wanted), ...discover(root, { include, exclude })])
+    const rels = [...chosen].sort()
+    const declared = new Map((c.manifest.diagnostics ?? []).map(d => [d.code, d]))
+    const ctx = Object.freeze({
+      root,
+      files: rels,
+      read,
+      jsx,
+      importOf,
+      slots: loaded.slots ?? {},
+      exists: rel => existsSync(join(root, rel)),
+      bytes: rel => (existsSync(join(root, rel)) ? new Uint8Array(readFileSync(join(root, rel))) : undefined),
+    })
+    let found
+    try {
+      found = (await hook.run(ctx)) ?? []
+    } catch (error) {
+      out.push(diagnostic({ code: 'P119', owner: c.name, file: 'weft.config.ts', why: `\`${c.name}\`'s check hook threw: ${String(error?.message ?? error).split('\n')[0]}` }))
+      continue
+    }
+    for (const d of found) {
+      if (!d.code.startsWith(c.namespace)) {
+        out.push(diagnostic({ code: 'P111', file: 'weft.config.ts', why: `\`${c.name}\`'s check reported \`${d.code}\`, outside its namespace \`${c.namespace}\`.` }))
+        continue
+      }
+      const text = read(d.file)
+      const pos = positions(text)
+      const [start, end] = [d.start ?? 0, d.end ?? d.start ?? 0]
+      const meta = declared.get(d.code)
+      out.push(diagnostic({
+        code: d.code,
+        owner: c.name,
+        severity: d.severity ?? meta?.severity ?? 'error',
+        file: d.file,
+        span: pos.span(start, end),
+        offset: [start, end],
+        why: d.why,
+        help: d.help ?? (entry(d.code) ? undefined : meta?.fix), // a catalog code keeps the catalog's fix text
+        fix: d.fix && {
+          description: d.fix.description,
+          safe: d.fix.safe === true,
+          edits: d.fix.edits.map(e => ({ file: e.file ?? d.file, span: positions(read(e.file ?? d.file)).span(e.start, e.end), offset: [e.start, e.end], text: e.text })),
+        },
+      }))
+    }
+  }
+  return out
+}

package/src/plugins.mjs

@@ -0,0 +1,172 @@
+// Plugins (PLAN §7c, research 13 §2.6–2.8): run each plugin's pure `contribute()`, check what it declares, generate
+// `.weft/slots/<id>.ts` + `.weft/slots.d.ts` + `.weft/tokens/<ns>.css`, and serve `weft plugins list|explain|sync`.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve } from 'node:path'
+import { loadConfig } from './load-config.mjs'
+import { slotDef } from './slots.mjs'
+
+const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)
+const header = '// Generated from weft.config.ts. Do not edit: change weft.config.ts and run `weft plugins sync`.'
+
+const posix = p => p.split('\\').join('/')
+const slotFile = id => `.weft/slots/${id}.ts`
+
+/** The ProviderRef a bound plugin declared for `slot` (and `key`). */
+function providerRef(loaded, plugin, slot, key = '') {
+  const c = loaded.contributions.find(x => x.name === plugin)
+  return c?.manifest.provides?.find(p => p.slot.id === slot && (p.key ?? '') === key) ?? null
+}
+
+/** `module` relative to `.weft/slots/` when the plugin gave a relative path from the project root. */
+function specifier(root, module) {
+  if (!module.startsWith('.') && !isAbsolute(module)) return module
+  const abs = isAbsolute(module) ? module : resolve(root, module)
+  const rel = posix(relative(join(root, '.weft', 'slots'), abs))
+  return rel.startsWith('.') ? rel : `./${rel}`
+}
+
+function loader(root, ref) {
+  const side = ref.sides.client ?? ref.sides[Object.keys(ref.sides).sort()[0]]
+  if (!side) return { comment: 'no sides', code: `() => Promise.reject(new Error('provider declares no module'))` }
+  const call = side.options === undefined ? `m[${JSON.stringify(side.export)}]` : `m[${JSON.stringify(side.export)}](${JSON.stringify(side.options)})`
+  return { comment: Object.keys(ref.sides).sort().join(', '), code: `() => import(${JSON.stringify(specifier(root, side.module))}).then(m => ${call})` }
+}
+
+const unbound = id =>
+  `export const provider = null\nexport const load = (): never => {\n  throw Object.assign(new Error(${JSON.stringify(`P101 ${id}: nothing provides this slot. Add a plugin that provides it to \`plugins\` in weft.config.ts.`)}), { code: 'P101' })\n}\n`
+const builtin = (id, name) =>
+  `export const provider = ${JSON.stringify(name)}\nexport const load = (): never => {\n  throw new Error(${JSON.stringify(`${id}: built in, provided by weft (${name}).`)})\n}\n`
+
+/** File contents for every slot module, the slots.d.ts and token CSS, keyed by path relative to the root. */
+export function generated(root, loaded) {
+  const files = {}
+  const typed = []
+  for (const [id, binding] of Object.entries(loaded.slots).sort(([a], [b]) => (a < b ? -1 : 1))) {
+    const def = slotDef(id) ?? { version: 1, cardinality: typeof binding === 'object' && binding ? 'keyed' : 'one' }
+    let body
+    if (def.cardinality === 'one') {
+      const ref = binding && !binding.startsWith('weft:default') ? providerRef(loaded, binding, id) : null
+      if (ref) {
+        const l = loader(root, ref)
+        const plugin = loaded.contributions.find(x => x.name === binding)
+        body = `// provider: ${binding}@${plugin.version} · implements ${id}@${ref.versions.join(',')} · sides: ${l.comment}\nexport const provider = ${JSON.stringify({ plugin: binding, version: plugin.version, interface: Math.max(...ref.versions) })} as const\nexport const load = ${l.code}\n`
+        typed.push(id)
+      } else if (binding?.startsWith('weft:default')) body = builtin(id, binding)
+      else body = unbound(id)
+    } else {
+      const lines = []
+      const providers = {}
+      for (const [key, name] of Object.entries(binding ?? {})) {
+        const ref = name && !name.startsWith('weft:default') ? providerRef(loaded, name, id, key) : null
+        providers[key] = ref ? name : name ?? null
+        if (ref) lines.push(`  ${JSON.stringify(key)}: ${loader(root, ref).code},`)
+      }
+      body = `export const providers = ${JSON.stringify(providers)} as const\nconst loaders: Record<string, () => Promise<unknown>> = {\n${lines.join('\n')}${lines.length ? '\n' : ''}}\nexport const load = (key: string): Promise<unknown> => {\n  const l = loaders[key]\n  if (l) return l()\n  throw Object.assign(new Error(\`P101 ${id} key \${key}: \${providers[key as keyof typeof providers] ? 'built in, provided by weft' : 'nothing provides it'}.\`), { code: 'P101' })\n}\n`
+      if (lines.length) typed.push(id)
+    }
+    files[slotFile(id)] = `${header}\n${body}`
+  }
+  // Build-side providers, for @weft-js/core/vite to import in Node (it can't load the generated .ts): research 26 §3.1.
+  for (const [id, binding] of Object.entries(loaded.slots)) {
+    if (binding && typeof binding === 'object') {
+      const keys = {}
+      for (const [key, name] of Object.entries(binding)) {
+        const side = name && !name.startsWith('weft:default') ? providerRef(loaded, name, id, key)?.sides.build : null
+        if (side) keys[key] = { plugin: name, module: side.module, export: side.export, options: side.options }
+      }
+      if (Object.keys(keys).length) files[`.weft/slots/${id}.build.json`] = `${JSON.stringify({ keys }, null, 2)}\n`
+      continue
+    }
+    if (typeof binding !== 'string' || binding.startsWith('weft:default')) continue
+    const side = providerRef(loaded, binding, id)?.sides.build
+    if (!side) continue
+    const plugin = loaded.contributions.find(x => x.name === binding)
+    const module = side.module.startsWith('.') ? posix(resolve(root, side.module)) : side.module
+    files[`.weft/slots/${id}.build.json`] = `${JSON.stringify({ plugin: binding, version: plugin.version, module, export: side.export, ...(side.options === undefined ? {} : { options: side.options }) }, null, 2)}\n`
+  }
+  files['.weft/slots.d.ts'] = `${header}\n// Only bound slots are declared: importing an unbound one is a type error (P101).\n${typed
+    .map(id => `declare module 'weft:slot/${id}' {\n  export const provider: unknown\n  export const providers: Record<string, unknown>\n  export const load: (key?: string) => Promise<any>\n}\n`)
+    .join('')}`
+  for (const c of loaded.contributions) {
+    const t = c.manifest.tokens
+    if (t?.css) files[`.weft/tokens/${t.namespace}.css`] = `/* Generated from weft.config.ts (${c.name}). Do not edit. */\n${t.css}`
+    if (t?.alias) files[`.weft/tokens/${t.namespace}.alias.json`] = `${JSON.stringify(t.alias, null, 2)}\n`
+  }
+  return files
+}
+
+/** Write generated files whose content changed; remove stale slot/token files. Returns written paths. */
+export function sync(root, loaded) {
+  const files = generated(root, loaded)
+  const written = []
+  for (const [rel, text] of Object.entries(files)) {
+    const abs = join(root, rel)
+    if (existsSync(abs) && readFileSync(abs, 'utf8') === text) continue
+    mkdirSync(join(abs, '..'), { recursive: true })
+    writeFileSync(abs, text)
+    written.push(rel)
+  }
+  for (const dir of ['.weft/slots', '.weft/tokens']) {
+    if (!existsSync(join(root, dir))) continue
+    for (const f of readdirSync(join(root, dir))) {
+      if (!(`${dir}/${f}` in files)) rmSync(join(root, dir, f))
+    }
+  }
+  return written
+}
+
+/** `weft plugins list --json`. */
+export async function list(root) {
+  root = resolve(root)
+  const loaded = await loadConfig(root)
+  const unique = (loaded.config.plugins ?? []).filter((p, i, all) => all.findIndex(q => q.name === p.name) === i)
+  const plugins = [...unique].sort(byName).map(p => {
+    const c = loaded.contributions.find(x => x.name === p.name)
+    const provides = (p.provides ?? []).map(item => {
+      const { slot, key } = typeof item === 'string' ? { slot: item } : item
+      const binding = loaded.slots[slot]
+      const bound = key ? binding?.[key] === p.name : binding === p.name
+      return { slot, ...(key ? { key } : {}), interface: providerRef(loaded, p.name, slot, key)?.versions ?? null, bound }
+    })
+    return {
+      name: p.name,
+      version: p.version ?? null,
+      provides,
+      permissions: c?.permissions ?? {},
+      namespace: c?.namespace ?? null,
+      diagnostics: (c?.manifest.diagnostics ?? []).map(d => d.code),
+      tokens: c?.manifest.tokens?.namespace ?? null,
+      catalog: (c?.manifest.catalog ?? []).map(e => e.name),
+      agents: c?.manifest.agents?.title ?? null,
+    }
+  })
+  return { ok: !loaded.diagnostics.some(d => d.severity === 'error'), plugins, slots: loaded.slots, diagnostics: loaded.diagnostics }
+}
+
+/** `weft plugins explain <slot> --json`: config entry → plugin → module → generated file. */
+export async function explain(root, id) {
+  root = resolve(root)
+  const loaded = await loadConfig(root)
+  if (!id || !(id in loaded.slots)) throw Object.assign(new Error(`unknown slot ${id ?? '(none)'}; known: ${Object.keys(loaded.slots).join(', ')}`), { code: 'E_USAGE' })
+  const binding = loaded.slots[id]
+  const def = slotDef(id) ?? null
+  const chain = key => {
+    const name = key === undefined ? binding : binding?.[key]
+    if (!name) return { provider: null, why: 'nothing provides it (P101 for consumers)' }
+    if (name.startsWith('weft:default')) return { provider: name, why: 'built in, provided by weft' }
+    const ref = providerRef(loaded, name, id, key ?? '')
+    const side = ref && (ref.sides.client ?? ref.sides[Object.keys(ref.sides).sort()[0]])
+    return {
+      config: loaded.file ? posix(relative(root, loaded.file)) : null,
+      chosenBy: loaded.config.slots?.[id] ? 'slots' : 'only provider',
+      plugin: name,
+      version: loaded.contributions.find(c => c.name === name)?.version ?? null,
+      interface: ref?.versions ?? null,
+      sides: ref ? Object.keys(ref.sides).sort() : [],
+      module: side ? { module: side.module, export: side.export, ...(side.options === undefined ? {} : { options: side.options }) } : null,
+    }
+  }
+  const bindings = def?.cardinality === 'keyed' || (binding && typeof binding === 'object') ? Object.fromEntries(Object.keys(binding ?? {}).sort().map(k => [k, chain(k)])) : chain()
+  return { slot: id, version: def?.version ?? null, cardinality: def?.cardinality ?? 'one', sides: def?.sides ?? [], binding: bindings, file: slotFile(id), import: `weft:slot/${id}` }
+}