@weft-js/cli 0.1.0 → 0.1.2

package/src/surface-checks.mjs

@@ -14,20 +14,37 @@ const SYSTEM = /(^|,)\s*["']?(system-ui|-apple-system|BlinkMacSystemFont)["']?\s
 const GENERIC_ONLY = /^\s*(serif|sans-serif|monospace|cursive|fantasy)\s*$/i
 const GLYPHS = 200
 
-const parse = (rel, text) => ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true, /\.[jt]sx$/.test(rel) ? ts.ScriptKind.TSX : ts.ScriptKind.TS)
+const parse = (rel, text) =>
+  ts.createSourceFile(
+    rel,
+    text,
+    ts.ScriptTarget.Latest,
+    true,
+    /\.[jt]sx$/.test(rel) ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  )
 
-const prop = (object, name) => object.properties.find(p => (ts.isPropertyAssignment(p) || ts.isMethodDeclaration(p) || ts.isShorthandPropertyAssignment(p)) && p.name.getText() === name)
-const stringOf = node => (node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) ? node.text : undefined)
+const prop = (object, name) =>
+  object.properties.find(
+    (p) =>
+      (ts.isPropertyAssignment(p) ||
+        ts.isMethodDeclaration(p) ||
+        ts.isShorthandPropertyAssignment(p)) &&
+      p.name.getText() === name,
+  )
+const stringOf = (node) =>
+  node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+    ? node.text
+    : undefined
 
 function walk(node, visit) {
   visit(node)
-  ts.forEachChild(node, c => walk(c, visit))
+  ts.forEachChild(node, (c) => walk(c, visit))
 }
 
 /** Every `defineSurface({ ... })` call in a file: the call, its options and the name of `setup`'s `s`. */
 function surfaceCalls(sf) {
   const out = []
-  walk(sf, node => {
+  walk(sf, (node) => {
     if (!ts.isCallExpression(node) || node.expression.getText() !== 'defineSurface') return
     const def = node.arguments[0]
     if (!def || !ts.isObjectLiteralExpression(def)) return
@@ -40,9 +57,16 @@ function surfaceCalls(sf) {
 
 function propNames(call) {
   const schema = prop(call.def, 'props')?.initializer
-  if (schema && ts.isCallExpression(schema) && schema.expression.getText().endsWith('.object') && ts.isObjectLiteralExpression(schema.arguments[0] ?? schema)) return schema.arguments[0].properties.map(p => p.name.getText())
+  if (
+    schema &&
+    ts.isCallExpression(schema) &&
+    schema.expression.getText().endsWith('.object') &&
+    ts.isObjectLiteralExpression(schema.arguments[0] ?? schema)
+  )
+    return schema.arguments[0].properties.map((p) => p.name.getText())
   const type = call.node.typeArguments?.[0]
-  if (type && ts.isTypeLiteralNode(type)) return type.members.map(m => m.name?.getText()).filter(Boolean)
+  if (type && ts.isTypeLiteralNode(type))
+    return type.members.map((m) => m.name?.getText()).filter(Boolean)
   return []
 }
 
@@ -55,7 +79,14 @@ export function listSurfaces(root, { exclude = [] } = {}) {
     const sf = parse(rel, text)
     for (const call of surfaceCalls(sf)) {
       const line = sf.getLineAndCharacterOfPosition(call.node.getStart(sf)).line + 1
-      out.push({ name: stringOf(prop(call.def, 'name')?.initializer) ?? null, kind: stringOf(prop(call.def, 'kind')?.initializer) ?? null, props: propNames(call), file: rel, line, ...(prop(call.def, 'pixel') ? { pixel: true } : {}) })
+      out.push({
+        name: stringOf(prop(call.def, 'name')?.initializer) ?? null,
+        kind: stringOf(prop(call.def, 'kind')?.initializer) ?? null,
+        props: propNames(call),
+        file: rel,
+        line,
+        ...(prop(call.def, 'pixel') ? { pixel: true } : {}),
+      })
     }
   }
   return out.sort((a, b) => String(a.name).localeCompare(String(b.name)))
@@ -63,27 +94,47 @@ export function listSurfaces(root, { exclude = [] } = {}) {
 
 /** `[...x]`, `x.split('')` or `Array.from(x)`: the string being spread, or undefined. */
 function glyphSource(node) {
-  if (ts.isArrayLiteralExpression(node) && node.elements.length === 1 && ts.isSpreadElement(node.elements[0])) return node.elements[0].expression
+  if (
+    ts.isArrayLiteralExpression(node) &&
+    node.elements.length === 1 &&
+    ts.isSpreadElement(node.elements[0])
+  )
+    return node.elements[0].expression
   if (!ts.isCallExpression(node)) return undefined
   const callee = node.expression.getText()
-  if (callee === 'Array.from' && node.arguments.length === 1 && !ts.isObjectLiteralExpression(node.arguments[0])) return node.arguments[0]
-  if (ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'split' && stringOf(node.arguments[0]) === '') return node.expression.expression
+  if (
+    callee === 'Array.from' &&
+    node.arguments.length === 1 &&
+    !ts.isObjectLiteralExpression(node.arguments[0])
+  )
+    return node.arguments[0]
+  if (
+    ts.isPropertyAccessExpression(node.expression) &&
+    node.expression.name.text === 'split' &&
+    stringOf(node.arguments[0]) === ''
+  )
+    return node.expression.expression
   return undefined
 }
 
 /** The first `<span>` a `.map` callback returns. */
 function returnedSpan(fn) {
   let span
-  walk(fn.body, n => {
+  walk(fn.body, (n) => {
     if (span) return
-    const open = ts.isJsxElement(n) ? n.openingElement : ts.isJsxSelfClosingElement(n) ? n : undefined
+    const open = ts.isJsxElement(n)
+      ? n.openingElement
+      : ts.isJsxSelfClosingElement(n)
+        ? n
+        : undefined
     if (open?.tagName.getText() === 'span') span = open
   })
   return span
 }
 
-const attrOf = (open, name) => open.attributes.properties.some(p => !ts.isJsxSpreadAttribute(p) && p.name.getText() === name)
-const spreads = open => open.attributes.properties.some(ts.isJsxSpreadAttribute)
+const attrOf = (open, name) =>
+  open.attributes.properties.some((p) => !ts.isJsxSpreadAttribute(p) && p.name.getText() === name)
+const spreads = (open) => open.attributes.properties.some(ts.isJsxSpreadAttribute)
 
 /** The JSX element a child expression sits in. */
 function jsxParent(node) {
@@ -97,15 +148,26 @@ function knownString(sf, node) {
   if (direct !== undefined) return direct
   if (!ts.isIdentifier(node)) return undefined
   let found
-  walk(sf, n => {
-    if (ts.isVariableDeclaration(n) && n.name.getText() === node.text && ts.isVariableDeclarationList(n.parent) && n.parent.flags & ts.NodeFlags.Const) found ??= stringOf(n.initializer)
+  walk(sf, (n) => {
+    if (
+      ts.isVariableDeclaration(n) &&
+      n.name.getText() === node.text &&
+      ts.isVariableDeclarationList(n.parent) &&
+      n.parent.flags & ts.NodeFlags.Const
+    )
+      found ??= stringOf(n.initializer)
   })
   return found
 }
 
 function glyphChecks(sf, report) {
-  walk(sf, node => {
-    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression) || node.expression.name.text !== 'map') return
+  walk(sf, (node) => {
+    if (
+      !ts.isCallExpression(node) ||
+      !ts.isPropertyAccessExpression(node.expression) ||
+      node.expression.name.text !== 'map'
+    )
+      return
     const source = glyphSource(node.expression.expression)
     const fn = node.arguments[0]
     if (!source || !fn || !(ts.isArrowFunction(fn) || ts.isFunctionExpression(fn))) return
@@ -113,11 +175,25 @@ function glyphChecks(sf, report) {
     if (!span) return
     const text = knownString(sf, source)
     const count = text === undefined ? 0 : Array.from(text).length
-    if (count > GLYPHS) report('X040', node, `Per-grapheme spans over ${count} graphemes: each is a DOM node, a style and a composited layer once it animates. Use word-level motion or a Surface.`)
+    if (count > GLYPHS)
+      report(
+        'X040',
+        node,
+        `Per-grapheme spans over ${count} graphemes: each is a DOM node, a style and a composited layer once it animates. Use word-level motion or a Surface.`,
+      )
     const hidden = attrOf(span, 'aria-hidden') || spreads(span)
     const parent = jsxParent(node)
-    const named = !parent || attrOf(parent, 'aria-label') || attrOf(parent, 'aria-labelledby') || spreads(parent)
-    if (!hidden || !named) report('X041', span, `Per-character spans read as separate letters to a screen reader${hidden ? '' : ': add `aria-hidden` to each span'}${named ? '' : `${hidden ? ':' : ', and'} give the parent an \`aria-label\` with the whole text`}.`)
+    const named =
+      !parent ||
+      attrOf(parent, 'aria-label') ||
+      attrOf(parent, 'aria-labelledby') ||
+      spreads(parent)
+    if (!hidden || !named)
+      report(
+        'X041',
+        span,
+        `Per-character spans read as separate letters to a screen reader${hidden ? '' : ': add `aria-hidden` to each span'}${named ? '' : `${hidden ? ':' : ', and'} give the parent an \`aria-label\` with the whole text`}.`,
+      )
   })
 }
 
@@ -125,28 +201,68 @@ function surfaceFileChecks(sf, slots, report) {
   const calls = surfaceCalls(sf)
   if (!calls.length) return
   const decorative = new Set()
-  walk(sf, n => {
-    if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression) && n.expression.name.text === 'decorative') decorative.add(n)
+  walk(sf, (n) => {
+    if (
+      ts.isCallExpression(n) &&
+      ts.isPropertyAccessExpression(n.expression) &&
+      n.expression.name.text === 'decorative'
+    )
+      decorative.add(n)
   })
-  const inside = n => { for (let p = n.parent; p; p = p.parent) if (decorative.has(p)) return true; return false }
-  walk(sf, n => {
+  const inside = (n) => {
+    for (let p = n.parent; p; p = p.parent) if (decorative.has(p)) return true
+    return false
+  }
+  walk(sf, (n) => {
     if (!ts.isCallExpression(n) || !ts.isPropertyAccessExpression(n.expression)) return
     const method = n.expression.name.text
-    if ((method === 'fillText' || method === 'strokeText') && !inside(n)) report('X010', n, `\`${method}\` in a surface draws text only the canvas knows about: no selection, find, translation or screen reader. Use \`s.text()\`, or \`s.decorative()\` for text that is truly decoration.`)
-    if (method === 'setAttribute' && stringOf(n.arguments[0]) === 'aria-hidden' && n.expression.expression.getText().endsWith('.el')) report('X011', n, 'This hides the surface or its text mirror from assistive tech. Leave the mirror to weft.')
+    if ((method === 'fillText' || method === 'strokeText') && !inside(n))
+      report(
+        'X010',
+        n,
+        `\`${method}\` in a surface draws text only the canvas knows about: no selection, find, translation or screen reader. Use \`s.text()\`, or \`s.decorative()\` for text that is truly decoration.`,
+      )
+    if (
+      method === 'setAttribute' &&
+      stringOf(n.arguments[0]) === 'aria-hidden' &&
+      n.expression.expression.getText().endsWith('.el')
+    )
+      report(
+        'X011',
+        n,
+        'This hides the surface or its text mirror from assistive tech. Leave the mirror to weft.',
+      )
   })
   for (const call of calls) {
     const kindNode = prop(call.def, 'kind')?.initializer
     const kind = stringOf(kindNode)
-    if (kind && slots && slots['surface.renderer'] && !slots['surface.renderer'][kind]) report('P101', kindNode, `Surface kind \`${kind}\` has no provider: add the plugin that provides it to \`plugins\` in weft.config.ts.`)
+    if (kind && slots && slots['surface.renderer'] && !slots['surface.renderer'][kind])
+      report(
+        'P101',
+        kindNode,
+        `Surface kind \`${kind}\` has no provider: add the plugin that provides it to \`plugins\` in weft.config.ts.`,
+      )
     if (!call.param || !call.fn) continue
-    walk(call.fn, n => {
+    walk(call.fn, (n) => {
       if (!ts.isCallExpression(n) || n.expression.getText() !== `${call.param}.text`) return
       const options = n.arguments[1]
-      const font = options && ts.isObjectLiteralExpression(options) ? stringOf(prop(options, 'font')?.initializer) : undefined
+      const font =
+        options && ts.isObjectLiteralExpression(options)
+          ? stringOf(prop(options, 'font')?.initializer)
+          : undefined
       const family = font?.replace(/^.*?\d[\d.]*px(\/\S+)?\s*/, '')
-      if (family !== undefined && (SYSTEM.test(family) || GENERIC_ONLY.test(family))) report('X002', n.arguments[1], `\`${font}\` can't be measured safely: \`system-ui\`, \`-apple-system\` and generic-only families resolve differently in canvas and CSS. Name a family.`)
-      if (kind === 'canvas2d' && slots && slots['text.measure'] === null) report('P101', n, 'Canvas `s.text()` needs `text.measure`, and nothing provides it: add `text()` from `@weft-js/text` to `plugins` in weft.config.ts.')
+      if (family !== undefined && (SYSTEM.test(family) || GENERIC_ONLY.test(family)))
+        report(
+          'X002',
+          n.arguments[1],
+          `\`${font}\` can't be measured safely: \`system-ui\`, \`-apple-system\` and generic-only families resolve differently in canvas and CSS. Name a family.`,
+        )
+      if (kind === 'canvas2d' && slots && slots['text.measure'] === null)
+        report(
+          'P101',
+          n,
+          'Canvas `s.text()` needs `text.measure`, and nothing provides it: add `text()` from `@weft-js/text` to `plugins` in weft.config.ts.',
+        )
     })
   }
 }
@@ -155,16 +271,38 @@ const HIDES = /(?:display\s*:\s*none|visibility\s*:\s*hidden)/
 
 /** X011/X012 in a stylesheet: rules aimed at the host or the mirror. */
 function cssChecks(file, report) {
-  const css = file.text.replace(/\/\*[\s\S]*?\*\//g, m => m.replace(/[^\n]/g, ' '))
+  const css = file.text.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
   const rule = /([^{}]*\[data-surface(-text)?\b[^{}]*)\{([^}]*)\}/g
   for (const m of css.matchAll(rule)) {
     const at = m.index + m[0].indexOf('[data-surface')
     const before = css.slice(0, m.index)
     const open = before.lastIndexOf('@media')
-    const inPrint = open >= 0 && /^@media[^{]*\bprint\b/.test(before.slice(open)) && (before.slice(open).match(/\{/g) ?? []).length > (before.slice(open).match(/\}/g) ?? []).length
-    if (/forced-color-adjust\s*:\s*none/.test(m[3])) report('X012', at, at + 13, '`forced-color-adjust: none` on a surface keeps its author colours in forced-colours mode, where the mirror must take over.')
-    else if (inPrint && HIDES.test(m[3])) report('X012', at, at + 13, 'This hides surface text when printing, where the mirror is the only copy that prints sharply.')
-    else if (m[2] && HIDES.test(m[3])) report('X011', at, at + 18, 'This hides the text mirror from assistive tech, and it is the only copy a screen reader can read. Leave the mirror to weft.')
+    const inPrint =
+      open >= 0 &&
+      /^@media[^{]*\bprint\b/.test(before.slice(open)) &&
+      (before.slice(open).match(/\{/g) ?? []).length >
+        (before.slice(open).match(/\}/g) ?? []).length
+    if (/forced-color-adjust\s*:\s*none/.test(m[3]))
+      report(
+        'X012',
+        at,
+        at + 13,
+        '`forced-color-adjust: none` on a surface keeps its author colours in forced-colours mode, where the mirror must take over.',
+      )
+    else if (inPrint && HIDES.test(m[3]))
+      report(
+        'X012',
+        at,
+        at + 13,
+        'This hides surface text when printing, where the mirror is the only copy that prints sharply.',
+      )
+    else if (m[2] && HIDES.test(m[3]))
+      report(
+        'X011',
+        at,
+        at + 18,
+        'This hides the text mirror from assistive tech, and it is the only copy a screen reader can read. Leave the mirror to weft.',
+      )
   }
 }
 
@@ -174,11 +312,14 @@ function cssChecks(file, report) {
  */
 export function surfaceChecks(root, { files, exclude = [], slots }) {
   const out = []
-  const reporter = file => {
+  const reporter = (file) => {
     const pos = positions(file.text)
-    return (code, start, end, why) => out.push(diagnostic({ code, file: file.rel, span: pos.span(start, end), offset: [start, end], why }))
+    return (code, start, end, why) =>
+      out.push(
+        diagnostic({ code, file: file.rel, span: pos.span(start, end), offset: [start, end], why }),
+      )
   }
-  const sources = new Map(files.filter(f => CODE.test(f.rel)).map(f => [f.rel, f]))
+  const sources = new Map(files.filter((f) => CODE.test(f.rel)).map((f) => [f.rel, f]))
   for (const rel of discover(root, { include: ['src/**/*.{ts,tsx,js,jsx}'], exclude })) {
     if (!sources.has(rel)) sources.set(rel, { rel, text: readFileSync(join(root, rel), 'utf8') })
   }
@@ -199,15 +340,40 @@ export function surfaceChecks(root, { files, exclude = [], slots }) {
     surfaceFileChecks(sf, slots, report)
     if (!/\.[jt]sx$/.test(f.rel)) continue
     const scan = scanJsx(f.text, f.rel)
-    const local = scan.imports.find(i => i.source === '@weft-js/core/surface' && i.imported === 'Surface')?.local
+    const local = scan.imports.find(
+      (i) => i.source === '@weft-js/core/surface' && i.imported === 'Surface',
+    )?.local
     for (const el of scan.elements) {
       if (el.name !== local) continue
-      const spread = el.attrs.some(a => a.kind === 'spread')
-      if (!el.attr('label') && !el.attr('decorative') && !spread) raw('X009', el.start, el.tagEnd, `<${el.name}> has no accessible name: a screen reader finds an unnamed image. Add \`label\`, or \`decorative\` if it shows nothing a reader needs.`)
+      const spread = el.attrs.some((a) => a.kind === 'spread')
+      if (!el.attr('label') && !el.attr('decorative') && !spread)
+        raw(
+          'X009',
+          el.start,
+          el.tagEnd,
+          `<${el.name}> has no accessible name: a screen reader finds an unnamed image. Add \`label\`, or \`decorative\` if it shows nothing a reader needs.`,
+        )
       const hidden = el.attr('aria-hidden')
-      if (hidden && hidden.value !== 'false') raw('X011', hidden.start, hidden.end, 'This hides the surface and its text mirror from assistive tech. For a surface with nothing to read use `decorative`, which leaves mirrors alone.')
+      if (hidden && hidden.value !== 'false')
+        raw(
+          'X011',
+          hidden.start,
+          hidden.end,
+          'This hides the surface and its text mirror from assistive tech. For a surface with nothing to read use `decorative`, which leaves mirrors alone.',
+        )
       const style = el.attr('style')
-      if (style && /forced-color-adjust\s*:\s*none|forcedColorAdjust\s*:\s*['"]none/.test(style.value ?? style.expr ?? '')) raw('X012', style.start, style.end, '`forced-color-adjust: none` on a surface keeps its author colours in forced-colours mode, where the mirror must take over.')
+      if (
+        style &&
+        /forced-color-adjust\s*:\s*none|forcedColorAdjust\s*:\s*['"]none/.test(
+          style.value ?? style.expr ?? '',
+        )
+      )
+        raw(
+          'X012',
+          style.start,
+          style.end,
+          '`forced-color-adjust: none` on a surface keeps its author colours in forced-colours mode, where the mirror must take over.',
+        )
     }
   }
   for (const rel of discover(root, { include: ['**/*.css'], exclude })) {

package/src/tailwind.mjs

@@ -12,11 +12,12 @@ export default { plugins: [tailwindcss()] }
  * The top of the app's CSS. With warp, Tailwind's reset stays out: its `base` layer comes after `warp`, so it would
  * beat every warp component. warp brings its own base. Layer order has to be declared before any import.
  */
-export const cssEntry = warp => (warp
-  ? `@layer warp, theme, base, components, utilities;
+export const cssEntry = (warp) =>
+  warp
+    ? `@layer warp, theme, base, components, utilities;
 @import "tailwindcss/theme.css" layer(theme);
 @import "tailwindcss/utilities.css" layer(utilities);
 @import "@weft-js/warp/tailwind.css";
 `
-  : `@import "tailwindcss";
-`)
+    : `@import "tailwindcss";
+`

package/src/tasks.mjs

@@ -6,30 +6,179 @@ import { join, relative, resolve } from 'node:path'
 import { z } from 'zod'
 import { loadConfig } from './load-config.mjs'
 
-const files = { type: 'array', items: { type: 'string' }, description: 'Files relative to the project root; default: the whole project' }
+const files = {
+  type: 'array',
+  items: { type: 'string' },
+  description: 'Files relative to the project root; default: the whole project',
+}
 
 /** `available: false` marks commands PLAN names that this CLI does not ship yet; `stack` ones ship for apps with src/routes. */
 export const builtins = [
-  { name: 'check', description: 'Compile every component in check mode and report W- and P-diagnostics with fixes', args: { type: 'object', properties: { files } }, sideEffects: [], available: true },
-  { name: 'tasks', description: 'List every command and project task with args, side effects and environments', args: { type: 'object', properties: {} }, sideEffects: [], available: true },
-  { name: 'docs', description: 'Print a docs topic or a diagnostic code (`weft docs W014`)', args: { type: 'object', properties: { topic: { type: 'string' } } }, sideEffects: [], available: true },
-  { name: 'agents-md', description: 'Regenerate AGENTS.md (`--check` fails if stale)', args: { type: 'object', properties: { check: { type: 'boolean' } } }, sideEffects: ['fs:AGENTS.md'], available: true },
-  { name: 'mcp', description: 'These commands as MCP tools (stdio)', args: { type: 'object', properties: {} }, sideEffects: [], available: true, longRunning: true },
-  { name: 'style', description: 'Style groups: `find <query>`, `explain <group|selector>`, `matrix` (writes .weft/styles.json)', args: { type: 'object', properties: { subcommand: { type: 'string', enum: ['find', 'explain', 'matrix'] }, query: { type: 'string' }, target: { type: 'string' } } }, sideEffects: ['fs:.weft/styles.json'], available: true },
-  { name: 'map', description: 'Write `.weft/map.md`: a matrix of what to call in this app', args: { type: 'object', properties: {} }, sideEffects: ['fs:.weft/map.*'], available: true },
-  { name: 'add', description: 'Install a plugin and wire it into the config (`--dry-run` shows the changes)', args: { type: 'object', properties: { plugin: { type: 'string' }, 'dry-run': { type: 'boolean' } } }, sideEffects: ['fs:weft.config.*', 'fs:package.json', 'network:install'], available: true },
-  { name: 'dev', description: 'Dev server', sideEffects: ['network:listen'], available: false, stack: true, longRunning: true },
-  { name: 'build', description: 'Production build and contract', sideEffects: ['fs:.output/**'], available: false, stack: true },
-  { name: 'start', description: 'Serve the build', sideEffects: ['network:listen'], available: false, stack: true, longRunning: true },
-  { name: 'db', description: '`generate`: new migrations', sideEffects: ['fs:drizzle/**', 'fs:migrations/**', 'fs:prisma/**'], available: false, stack: true },
-  { name: 'test', description: 'The test gate on the diff (`--gate`)', args: { type: 'object', properties: { gate: { type: 'boolean' }, base: { type: 'string' }, budget: { type: 'number' }, refactor: { type: 'boolean' } } }, sideEffects: ['fs:.weft/gate'], available: true },
-  { name: 'fix', description: 'Apply the safe autofixes from `weft check`', args: { type: 'object', properties: { files } }, sideEffects: ['fs:scope.write'], available: true },
-  { name: 'tokens', description: "warp's resolved tokens as DTCG 2025.10 in `.weft/tokens/` (Figma, Style Dictionary, Terrazzo)", args: { type: 'object', properties: {} }, sideEffects: ['fs:.weft/tokens/**'], available: true },
-  { name: 'browser', description: 'Drive the running app in any open browser by role/label/text (`weft browser help`)', args: { type: 'object', properties: { command: { type: 'string' } } }, sideEffects: ['network:dev-server', 'fs:.weft/browser'], available: true },
-  { name: 'run', description: 'Run a project task by name', args: { type: 'object', properties: { name: { type: 'string' } } }, sideEffects: ['task'], available: true },
+  {
+    name: 'check',
+    description: 'Compile every component in check mode and report W- and P-diagnostics with fixes',
+    args: { type: 'object', properties: { files } },
+    sideEffects: [],
+    available: true,
+  },
+  {
+    name: 'tasks',
+    description: 'List every command and project task with args, side effects and environments',
+    args: { type: 'object', properties: {} },
+    sideEffects: [],
+    available: true,
+  },
+  {
+    name: 'docs',
+    description: 'Print a docs topic or a diagnostic code (`weft docs W014`)',
+    args: { type: 'object', properties: { topic: { type: 'string' } } },
+    sideEffects: [],
+    available: true,
+  },
+  {
+    name: 'agents-md',
+    description: 'Regenerate AGENTS.md (`--check` fails if stale)',
+    args: { type: 'object', properties: { check: { type: 'boolean' } } },
+    sideEffects: ['fs:AGENTS.md'],
+    available: true,
+  },
+  {
+    name: 'mcp',
+    description: 'These commands as MCP tools (stdio)',
+    args: { type: 'object', properties: {} },
+    sideEffects: [],
+    available: true,
+    longRunning: true,
+  },
+  {
+    name: 'style',
+    description:
+      'Style groups: `find <query>`, `explain <group|selector>`, `matrix` (writes .weft/styles.json)',
+    args: {
+      type: 'object',
+      properties: {
+        subcommand: { type: 'string', enum: ['find', 'explain', 'matrix'] },
+        query: { type: 'string' },
+        target: { type: 'string' },
+      },
+    },
+    sideEffects: ['fs:.weft/styles.json'],
+    available: true,
+  },
+  {
+    name: 'map',
+    description: 'Write `.weft/map.md`: a matrix of what to call in this app',
+    args: { type: 'object', properties: {} },
+    sideEffects: ['fs:.weft/map.*'],
+    available: true,
+  },
+  {
+    name: 'add',
+    description: 'Install a plugin and wire it into the config (`--dry-run` shows the changes)',
+    args: {
+      type: 'object',
+      properties: { plugin: { type: 'string' }, 'dry-run': { type: 'boolean' } },
+    },
+    sideEffects: ['fs:weft.config.*', 'fs:package.json', 'network:install'],
+    available: true,
+  },
+  {
+    name: 'dev',
+    description: 'Dev server',
+    sideEffects: ['network:listen'],
+    available: false,
+    stack: true,
+    longRunning: true,
+  },
+  {
+    name: 'build',
+    description: 'Production build and contract',
+    sideEffects: ['fs:.output/**'],
+    available: false,
+    stack: true,
+  },
+  {
+    name: 'start',
+    description: 'Serve the build',
+    sideEffects: ['network:listen'],
+    available: false,
+    stack: true,
+    longRunning: true,
+  },
+  {
+    name: 'db',
+    description: '`generate`: new migrations',
+    sideEffects: ['fs:drizzle/**', 'fs:migrations/**', 'fs:prisma/**'],
+    available: false,
+    stack: true,
+  },
+  {
+    name: 'test',
+    description: 'The test gate on the diff (`--gate`)',
+    args: {
+      type: 'object',
+      properties: {
+        gate: { type: 'boolean' },
+        base: { type: 'string' },
+        budget: { type: 'number' },
+        refactor: { type: 'boolean' },
+      },
+    },
+    sideEffects: ['fs:.weft/gate'],
+    available: true,
+  },
+  {
+    name: 'fix',
+    description: 'Apply the safe autofixes from `weft check`',
+    args: { type: 'object', properties: { files } },
+    sideEffects: ['fs:scope.write'],
+    available: true,
+  },
+  {
+    name: 'tokens',
+    description:
+      "warp's resolved tokens as DTCG 2025.10 in `.weft/tokens/` (Figma, Style Dictionary, Terrazzo)",
+    args: { type: 'object', properties: {} },
+    sideEffects: ['fs:.weft/tokens/**'],
+    available: true,
+  },
+  {
+    name: 'browser',
+    description:
+      'Drive the running app in any open browser by role/label/text (`weft browser help`)',
+    args: { type: 'object', properties: { command: { type: 'string' } } },
+    sideEffects: ['network:dev-server', 'fs:.weft/browser'],
+    available: true,
+  },
+  {
+    name: 'run',
+    description: 'Run a project task by name',
+    args: { type: 'object', properties: { name: { type: 'string' } } },
+    sideEffects: ['task'],
+    available: true,
+  },
   { name: 'create', description: 'Scaffold a weft app', sideEffects: ['fs'], available: false },
-  { name: 'surfaces', description: "List the project's surfaces: name, kind, props and file", sideEffects: [], available: true },
-  { name: 'plugins', description: 'List and explain plugins and slot bindings; `sync` regenerates .weft/slots and plugin tokens; `audit` and `approve` check and write the permissions lock', args: { type: 'object', properties: { subcommand: { type: 'string', enum: ['list', 'explain', 'sync', 'audit', 'approve'] }, slot: { type: 'string' }, all: { type: 'boolean' } } }, sideEffects: ['fs:.weft/**', 'fs:.gitignore'], available: true },
+  {
+    name: 'surfaces',
+    description: "List the project's surfaces: name, kind, props and file",
+    sideEffects: [],
+    available: true,
+  },
+  {
+    name: 'plugins',
+    description:
+      'List and explain plugins and slot bindings; `sync` regenerates .weft/slots and plugin tokens; `audit` and `approve` check and write the permissions lock',
+    args: {
+      type: 'object',
+      properties: {
+        subcommand: { type: 'string', enum: ['list', 'explain', 'sync', 'audit', 'approve'] },
+        slot: { type: 'string' },
+        all: { type: 'boolean' },
+      },
+    },
+    sideEffects: ['fs:.weft/**', 'fs:.gitignore'],
+    available: true,
+  },
 ]
 
 function jsonSchema(args) {
@@ -49,11 +198,17 @@ export async function runTask(root, name) {
   root = resolve(root)
   const { config } = await loadConfig(root)
   const task = config.tasks?.[name]
-  if (!task) throw Object.assign(new Error(`no task "${name}" (tasks: ${Object.keys(config.tasks ?? {}).join(', ') || 'none'})`), { code: 'E_USAGE' })
+  if (!task)
+    throw Object.assign(
+      new Error(
+        `no task "${name}" (tasks: ${Object.keys(config.tasks ?? {}).join(', ') || 'none'})`,
+      ),
+      { code: 'E_USAGE' },
+    )
   return new Promise((ok, fail) => {
     const child = spawn(task.run, { cwd: root, shell: true, stdio: 'inherit' })
     child.on('error', fail)
-    child.on('close', code => ok(code ?? 1))
+    child.on('close', (code) => ok(code ?? 1))
   })
 }
 
@@ -63,10 +218,13 @@ export async function tasks(root) {
   const { file, config, diagnostics } = await loadConfig(root)
   const environments = Object.keys(config.environments ?? {})
   const stack = existsSync(join(root, 'src', 'routes'))
-  const list = builtins.map(b => ({
+  const list = builtins.map((b) => ({
     name: b.name,
     kind: 'builtin',
-    command: { check: 'weft check --json', tasks: 'weft tasks --json', docs: 'weft docs <topic>' }[b.name] ?? `weft ${b.name}`,
+    command:
+      { check: 'weft check --json', tasks: 'weft tasks --json', docs: 'weft docs <topic>' }[
+        b.name
+      ] ?? `weft ${b.name}`,
     description: b.description,
     args: b.args ?? { type: 'object', properties: {} },
     sideEffects: b.sideEffects,
@@ -88,12 +246,16 @@ export async function tasks(root) {
   }
   return {
     version: 1,
-    ok: !diagnostics.some(d => d.severity === 'error'),
+    ok: !diagnostics.some((d) => d.severity === 'error'),
     root,
     config: file ? relative(root, file).split('\\').join('/') : null,
     tasks: list,
-    scope: { write: config.scope?.write ?? null, read: config.scope?.read ?? null, forbid: config.scope?.forbid ?? [] },
+    scope: {
+      write: config.scope?.write ?? null,
+      read: config.scope?.read ?? null,
+      forbid: config.scope?.forbid ?? [],
+    },
     environments,
-    diagnostics: diagnostics.filter(d => ['P003', 'P004', 'P007'].includes(d.code)),
+    diagnostics: diagnostics.filter((d) => ['P003', 'P004', 'P007'].includes(d.code)),
   }
 }