@weft-js/cli 0.0.0-stage → 0.1.1

package/src/text-checks.mjs

@@ -0,0 +1,172 @@
+// Phase 2's X-codes in `weft check` (research 11 §8.5, research 26 §7): responsive type and zoom (X005, X006, X008),
+// the font build (X020–X023), media inside query boundaries (X030, X034), and refetches and streams (X033, X035,
+// research 31 §7). X031, X032 and X036 are reported at runtime in dev. Reads .css and .html files and the JSX of the checked files; X022 also reads the font build's
+// report in `.weft/fonts.json`.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { diagnostic, positions } from './diag.mjs'
+import { discover } from './files.mjs'
+import { scanJsx } from './jsx-scan.mjs'
+
+const FLUID = /(-?[\d.]+)(vw|vi|cqi|cqw|vmin|vmax)\b/
+const MAX_RATIO = 2.5
+
+/** Comments blanked out, so offsets stay those of the file. */
+const stripComments = css => css.replace(/\/\*[\s\S]*?\*\//g, m => m.replace(/[^\n]/g, ' '))
+
+/** `clamp(rem, rem + cqi, rem)` for a viewport/container-only size, from its px at 375 and 1280 (ratio ≤ 2.5). */
+export function fluidFor(n) {
+  const at = w => (n * w) / 100
+  const min = at(375)
+  const max = Math.min(at(1280), min * MAX_RATIO)
+  const slope = (max - min) / (1280 - 375)
+  const r = x => Math.round(x * 1000) / 1000
+  return `clamp(${r(min / 16)}rem, calc(${r((min - slope * 375) / 16)}rem + ${r(slope * 100)}cqi), ${r(max / 16)}rem)`
+}
+
+/** X005/X006 for one `font-size` value; `at` is its offset in the file. */
+function fontSize(value, at, report) {
+  if (/var\(/.test(value)) return // tokens: checked where they're defined
+  const fluid = FLUID.exec(value)
+  if (fluid && !/rem\b/.test(value)) {
+    const only = new RegExp(`^\\s*${fluid[0].replace(/[.]/g, '\\.')}\\s*$`).test(value)
+    report('X005', at, at + value.length, `\`font-size: ${value.trim()}\` scales with the ${fluid[2].startsWith('c') ? 'container' : 'viewport'} only: browser zoom and the user's font size don't change it (WCAG 1.4.4).`,
+      only ? { description: 'Use a fluid clamp with rem ends', safe: false, text: fluidFor(Number(fluid[1])) } : undefined)
+  }
+  const clamp = /^\s*clamp\(\s*([\d.]+)(rem|px)\s*,[\s\S]*,\s*([\d.]+)(rem|px)\s*\)\s*$/.exec(value)
+  if (clamp && clamp[2] === clamp[4] && Number(clamp[1]) > 0) {
+    const ratio = Number(clamp[3]) / Number(clamp[1])
+    if (ratio > MAX_RATIO) report('X006', at, at + value.length, `This fluid size grows ${ratio.toFixed(2)}× from its minimum to its maximum; above 2.5×, 200% zoom no longer doubles the text (WCAG 1.4.4).`)
+  }
+}
+
+const faceFamily = body => /font-family\s*:\s*(['"]?)([^;'"]+)\1/.exec(body)?.[2].trim()
+
+/** Every `@font-face` in a CSS text: family, body and offsets. */
+function faces(css) {
+  const out = []
+  for (const m of css.matchAll(/@font-face\s*\{([^}]*)\}/g)) out.push({ family: faceFamily(m[1]), body: m[1], start: m.index, bodyStart: m.index + m[0].indexOf('{') + 1, end: m.index + m[0].length })
+  return out
+}
+
+/**
+ * @param {string} root
+ * @param {{ files: { rel: string, text: string }[], exclude?: string[], fontBuild?: boolean }} options files: the checked .tsx/.jsx files
+ */
+export function textChecks(root, { files, exclude = [], fontBuild = false }) {
+  const out = []
+  const sheets = discover(root, { include: ['**/*.css'], exclude }).map(rel => ({ rel, text: readFileSync(join(root, rel), 'utf8') }))
+  const pages = discover(root, { include: ['**/*.html'], exclude }).map(rel => ({ rel, text: readFileSync(join(root, rel), 'utf8') }))
+  const fontsJson = join(root, '.weft', 'fonts.json')
+  const built = existsSync(fontsJson) ? JSON.parse(readFileSync(fontsJson, 'utf8')) : null
+
+  const reporter = file => {
+    const pos = positions(file.text)
+    /** `fix.at`: the replaced range when it isn't the flagged one. */
+    return (code, start, end, why, fix) => {
+      const [a, b] = fix?.at ?? [start, end]
+      out.push(diagnostic({ code, file: file.rel, span: pos.span(start, end), offset: [start, end], why, fix: fix && { description: fix.description, safe: fix.safe, edits: [{ file: file.rel, span: pos.span(a, b), offset: [a, b], text: fix.text }] } }))
+    }
+  }
+
+  // -- CSS: font sizes and font faces --
+  const allFaces = sheets.flatMap(s => faces(stripComments(s.text)).map(f => ({ ...f, sheet: s })))
+  const families = new Set(allFaces.map(f => f.family).filter(Boolean))
+  const faceUrls = new Set(allFaces.flatMap(f => [...f.body.matchAll(/url\(\s*['"]?([^'")]+)/g)].map(m => basename(m[1].split('?')[0]))))
+  for (const s of sheets) {
+    const css = stripComments(s.text)
+    const report = reporter(s)
+    for (const m of css.matchAll(/(?<![\w-])font-size\s*:\s*([^;}]+)/g)) fontSize(m[1], m.index + m[0].indexOf(m[1], m[0].indexOf(':')), report)
+    for (const f of faces(css)) {
+      const display = /font-display\s*:\s*(block|auto)\b/.exec(f.body)
+      if (display) {
+        const at = f.bodyStart + display.index + display[0].lastIndexOf(display[1])
+        report('X021', at, at + display[1].length, `\`font-display: ${display[1]}\` hides text for up to 3 s while the font loads; with a matched fallback face, \`swap\` shifts nothing.`, { description: 'Use swap', safe: true, text: 'swap' })
+      }
+      const local = /url\(\s*['"]?(?!https?:|data:)/.test(f.body)
+      if (!local || !f.family || f.family.endsWith('Fallback')) continue
+      if (!families.has(`${f.family} Fallback`)) {
+        const how = fontBuild ? 'declare it in `text({ fonts })`, which generates the fallback' : 'add `@weft-js/text` and declare it in `text({ fonts })`'
+        report('X020', f.start, f.start + '@font-face'.length, `\`@font-face\` for "${f.family}" has no "${f.family} Fallback" face: the swap from the system font shifts layout. Fix: ${how}.`)
+      }
+      if (!/unicode-range\s*:/.test(f.body)) report('X022', f.start, f.start + '@font-face'.length, `"${f.family}" ships the whole font file: no \`unicode-range\`, so it isn't subset.`)
+    }
+  }
+  for (const [code, why] of built?.report?.overBudget ?? []) {
+    if (code === 'X022') out.push(diagnostic({ code: 'X022', file: '.weft/fonts.json', why }))
+  }
+
+  // -- Markup: viewport meta, font preloads, media in boundaries, pending timers --
+  const viewport = (file, start, end, content, valueStart) => {
+    const parts = content.split(',').map(s => s.trim()).filter(Boolean)
+    const bad = parts.filter(p => /^user-scalable\s*=\s*(no|0)$/i.test(p) || (/^maximum-scale\s*=/i.test(p) && parseFloat(p.split('=')[1]) < 2))
+    if (!bad.length) return
+    const keep = parts.filter(p => !bad.includes(p)).join(', ')
+    reporter(file)('X008', start, end, `The viewport meta blocks zoom (\`${bad.join('`, `')}\`): people who need larger text can't pinch to get it (WCAG 1.4.4).`,
+      { description: 'Remove the zoom limits', safe: true, text: keep, at: [valueStart, valueStart + content.length] })
+  }
+  for (const p of pages) {
+    for (const m of p.text.matchAll(/<meta\b[^>]*name\s*=\s*["']viewport["'][^>]*>/gi)) {
+      const c = /content\s*=\s*(["'])([^"']*)\1/i.exec(m[0])
+      if (c) viewport(p, m.index, m.index + m[0].length, c[2], m.index + c.index + c[0].indexOf(c[2]))
+    }
+    for (const m of p.text.matchAll(/<link\b[^>]*rel\s*=\s*["']preload["'][^>]*>/gi)) {
+      if (/\bas\s*=\s*["']font["']/i.test(m[0])) preload(p, /href\s*=\s*["']([^"']+)/i.exec(m[0])?.[1], m.index, m.index + m[0].length)
+    }
+  }
+
+  /** X023: a font preload no `@font-face` uses (the font build's own preloads live under its asset URLs). */
+  function preload(file, href, start, end) {
+    if (href && !faceUrls.has(basename(href.split('?')[0])) && !href.includes('@weft-assets') && !href.startsWith('/assets/')) {
+      reporter(file)('X023', start, end, `This preloads \`${href}\`, which no \`@font-face\` uses: the bytes compete with the page's own critical requests.`)
+    }
+  }
+
+  for (const f of files) {
+    if (!/\.[jt]sx$/.test(f.rel)) continue
+    let scan
+    try {
+      scan = scanJsx(f.text, f.rel)
+    } catch {
+      continue // syntax errors are W000's
+    }
+    const report = reporter(f)
+    // X033: `x.pending ? <Skeleton /> : …`, with no `x.value` test beside it.
+    for (const m of f.text.matchAll(/\b([\w$]+)\.pending\s*(?:\?|&&)\s*\(?\s*<\s*(Shape|Skeleton|Spinner|Progress)\b/g)) {
+      const line = f.text.slice(f.text.lastIndexOf('\n', m.index) + 1, m.index)
+      if (!line.includes(`${m[1]}.value`)) report('X033', m.index, m.index + m[0].length, `\`${m[1]}.pending\` is true on every refetch too, so this <${m[2]}> flashes over a value that's already on screen.`)
+    }
+    for (const el of scan.elements) {
+      const style = el.attr('style')
+      if (style) {
+        if (style.kind === 'string') for (const m of style.value.matchAll(/font-size\s*:\s*([^;]+)/g)) fontSize(m[1], style.valueStart + 1 + m.index + m[0].indexOf(m[1]), report)
+        else for (const m of (style.expr ?? '').matchAll(/fontSize\s*:\s*(['"`])([^'"`]+)\1/g)) fontSize(m[2], style.valueStart + m.index + m[0].indexOf(m[2]), report)
+      }
+      if (el.name === 'meta' && el.attr('name')?.value === 'viewport' && el.attr('content')?.kind === 'string') {
+        const c = el.attr('content')
+        viewport(f, el.start, el.end, c.value, c.valueStart + 1)
+      }
+      if (el.name === 'link' && el.attr('rel')?.value === 'preload' && el.attr('as')?.value === 'font') {
+        preload(f, el.attr('href')?.value, el.start, el.end)
+      }
+      if (['img', 'video', 'iframe'].includes(el.name) && el.ancestors.includes('Boundary')) {
+        const sized = (el.attr('width') && el.attr('height')) || /aspect-?ratio/i.test(style?.value ?? style?.expr ?? '')
+        if (!sized) report('X030', el.start, el.tagEnd, `<${el.name}> inside a <Boundary> has no \`width\`/\`height\` or \`aspect-ratio\`: it renders 0 px tall, then pushes the content down when it loads.`)
+      }
+      if (/overflow(-[xy]|Y|X)?\s*:\s*['"]?(auto|scroll)/.test(style?.value ?? style?.expr ?? '')) {
+        const live = /\{\s*(\w+)\.value\b/.exec(el.children)?.[1]
+        if (live && new RegExp(`\\b${live}\\s*=\\s*[^\\n]*\\bstream\\b`).test(f.text)) report('X035', el.start, el.tagEnd, `\`${live}\` is streamed straight into a scroll container: as its tail reflows, the lines above it move.`)
+      }
+      const pending = el.name === 'Boundary' && el.attr('pending')
+      if (pending?.kind === 'expr') {
+        const tag = /^<\s*([A-Z][\w.]*)/.exec(pending.expr)?.[1]
+        const timers = /\b(setTimeout|setInterval)\s*\(/
+        if (timers.test(pending.expr) || (tag && timers.test(scan.functions.get(tag) ?? ''))) {
+          report('X034', pending.start, pending.end, `This \`pending\` fallback${tag ? ` (<${tag}>)` : ''} runs its own timers: <Boundary> already waits 150 ms before showing it and holds it 400 ms, and a second clock makes it flash.`)
+        }
+      }
+    }
+  }
+  return out
+}

package/src/tokens.mjs

@@ -0,0 +1,24 @@
+// `weft tokens`: warp's resolved tokens as DTCG 2025.10 (PLAN §6, research 37), for Figma, Style Dictionary and Terrazzo.
+// warp owns the values, so this asks the app's warp, with the app's seed and overrides, and writes what it returns.
+
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { loadConfig } from './load-config.mjs'
+
+export async function writeTokens(root) {
+  root = resolve(root)
+  let plugin
+  try {
+    plugin = await import(pathToFileURL(createRequire(join(root, 'package.json')).resolve('@weft-js/warp/plugin')).href)
+  } catch {
+    throw Object.assign(new Error('`weft tokens` exports warp\'s tokens, and this app has no @weft-js/warp'), { code: 'E_NO_WARP' })
+  }
+  const css = (await loadConfig(root)).contributions.find(c => c.name === '@weft-js/warp')?.manifest.tokens?.css ?? ''
+  const dir = join(root, '.weft', 'tokens')
+  mkdirSync(dir, { recursive: true })
+  const files = plugin.dtcg(css)
+  for (const [name, content] of Object.entries(files)) writeFileSync(join(dir, name), `${JSON.stringify(content, null, 2)}\n`)
+  return { ok: true, dir: '.weft/tokens', files: Object.keys(files) }
+}

package/src/trust.mjs

@@ -0,0 +1,282 @@
+// Plugin trust (PLAN §7c, research 13 §2.9): `.weft/plugins.lock.json` records what each plugin may do and hashes its
+// code, so a change is visible and blocked until `weft plugins approve`. It is a diff, not a sandbox: `contribute()` has
+// already run by the time any of this looks at a plugin, and the audit reads source, which code can hide from.
+
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import { builtinModules } from 'node:module'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import ts from 'typescript'
+import { diagnostic, locate } from './diag.mjs'
+
+export const lockFile = '.weft/plugins.lock.json'
+
+const refused = message => Object.assign(new Error(message), { code: 'E_TRUST' })
+const posix = p => p.split(sep).join('/')
+/** @param {string[]} list */
+const sorted = list => [...new Set(list)].sort()
+
+/** Permissions as flat strings, one per grant, so a lock diff reads line by line: `fs.read:fonts/**`, `native`. */
+export function grants(p = {}) {
+  const each = (kind, list) => (list ?? []).map(v => `${kind}:${v}`)
+  return sorted([...each('fs.read', p.fs?.read), ...each('fs.write', p.fs?.write), ...each('net', p.net), ...each('env', p.env), ...each('spawn', p.spawn), ...(p.native ? ['native'] : [])])
+}
+
+/** The lockfile, or `broken` when it can't be read: an unresolved merge shouldn't read as "nothing approved". */
+function readLock(root) {
+  const file = join(root, lockFile)
+  if (!existsSync(file)) return { found: false, plugins: {} }
+  try {
+    const data = JSON.parse(readFileSync(file, 'utf8'))
+    if (data?.version !== 1 || typeof data.plugins !== 'object' || data.plugins === null) return { found: true, plugins: {}, broken: 'it is not a version 1 lockfile' }
+    return { found: true, plugins: data.plugins }
+  } catch (error) {
+    return { found: true, plugins: {}, broken: String(error.message).split('\n')[0] }
+  }
+}
+
+/** The package a plugin name is in: `@weft-js/db/mongo` is a subpath of `@weft-js/db`. */
+export const packageOf = name => name.split('/').slice(0, name.startsWith('@') ? 2 : 1).join('/')
+
+/** Where a plugin is installed: the nearest `node_modules/<package>`, through its symlink. Null for one defined in the config. */
+function packageDir(root, name) {
+  for (let dir = root; ; dir = dirname(dir)) {
+    const at = join(dir, 'node_modules', packageOf(name))
+    if (existsSync(join(at, 'package.json'))) return realpathSync(at)
+    if (dirname(dir) === dir) return null
+  }
+}
+
+/** A hash of the package's files, the same from any installer. Its own dependencies are the package manager's lock's job. */
+function hashPackage(dir) {
+  const hash = createHash('sha512')
+  const files = readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter(f => f.isFile() && !relative(dir, f.parentPath).split(sep).includes('node_modules'))
+    .map(f => join(f.parentPath, f.name))
+    .sort()
+  for (const file of files) {
+    const bytes = readFileSync(file)
+    hash.update(`${posix(relative(dir, file))}\0${bytes.length}\0`).update(bytes)
+  }
+  return `sha512-${hash.digest('base64')}`
+}
+
+const builtins = new Set(builtinModules)
+const NEEDS = { fs: 'fs', 'fs/promises': 'fs', child_process: 'spawn', cluster: 'spawn', net: 'net', tls: 'net', dgram: 'net', dns: 'net', 'dns/promises': 'net', http: 'net', https: 'net', http2: 'net' }
+const NET_GLOBALS = new Set(['fetch', 'WebSocket', 'EventSource'])
+/** Bundlers inline it, and it says nothing about the machine. */
+const AMBIENT_ENV = new Set(['NODE_ENV'])
+
+/** What one file does directly, and what it imports. */
+function scanFile(text, file) {
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, /\.[cm]?tsx?$/.test(file) ? ts.ScriptKind.TSX : ts.ScriptKind.JSX)
+  const uses = []
+  const imports = []
+  const use = (need, node) => uses.push({ need, line: sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1 })
+  const specifier = (name, node) => {
+    const bare = name.replace(/^node:/, '')
+    if (name.endsWith('.node')) use('native', node)
+    else if (builtins.has(bare)) NEEDS[bare] && use(NEEDS[bare], node)
+    else imports.push(name)
+  }
+  const isProcess = node => ts.isIdentifier(node) && node.text === 'process'
+  const visit = node => {
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) {
+      if (!(node.importClause?.isTypeOnly || node.isTypeOnly)) specifier(node.moduleSpecifier.text, node)
+    } else if (ts.isCallExpression(node)) {
+      const callee = node.expression
+      const [first] = node.arguments
+      if ((callee.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(callee) && callee.text === 'require')) && first && ts.isStringLiteralLike(first)) specifier(first.text, node)
+      else if (ts.isIdentifier(callee) && NET_GLOBALS.has(callee.text)) use('net', node)
+      else if (ts.isPropertyAccessExpression(callee) && isProcess(callee.expression) && callee.name.text === 'dlopen') use('native', node)
+    } else if (ts.isNewExpression(node) && ts.isIdentifier(node.expression) && NET_GLOBALS.has(node.expression.text)) use('net', node)
+    else if (ts.isPropertyAccessExpression(node) && isProcess(node.expression) && node.name.text === 'env') {
+      const parent = node.parent
+      if (ts.isPropertyAccessExpression(parent) && parent.expression === node) AMBIENT_ENV.has(parent.name.text) || use(`env:${parent.name.text}`, node)
+      else if (ts.isElementAccessExpression(parent) && parent.expression === node && ts.isStringLiteralLike(parent.argumentExpression)) AMBIENT_ENV.has(parent.argumentExpression.text) || use(`env:${parent.argumentExpression.text}`, node)
+      else use('env:*', node)
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sf)
+  return { uses, imports }
+}
+
+const EXTENSIONS = ['', '.mjs', '.js', '.cjs', '.ts', '.tsx', '.mts', '/index.mjs', '/index.js', '/index.ts']
+const sourceFile = /\.(?:[cm]?[jt]s|[jt]sx)$/
+const onDisk = path => EXTENSIONS.map(e => path + e).find(p => sourceFile.test(p) && existsSync(p)) ?? null
+
+/** A package export's file for this runtime. */
+function exportTarget(value) {
+  if (typeof value === 'string') return value
+  if (!value || typeof value !== 'object') return null
+  return exportTarget(value.node ?? value.import ?? value.default ?? value.require)
+}
+
+function entryFile(dir, pkg, subpath) {
+  const map = pkg.exports
+  const keyed = map && typeof map === 'object' && Object.keys(map).some(k => k.startsWith('.'))
+  const target = exportTarget(keyed ? map[subpath] : subpath === '.' ? (map ?? pkg.main ?? 'index.js') : null)
+  return (target && onDisk(join(dir, target))) ?? (subpath === '.' ? null : onDisk(join(dir, subpath)))
+}
+
+/**
+ * The plugin's entry, and each module it names for the build or the server (a browser has no `fs` to reach). Only the
+ * package's own files are read; `dependencies` says what it stopped at.
+ */
+export function audit(root, dir, contribution) {
+  const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+  // A package can hold several plugins, `<package>/<sub>/plugin`, and each answers for its own files.
+  const sub = contribution.name?.startsWith(`${pkg.name}/`) ? contribution.name.slice(pkg.name.length) : ''
+  const roots = [entryFile(dir, pkg, `.${sub}/plugin`) ?? entryFile(dir, pkg, `.${sub}`)]
+  for (const ref of contribution.manifest.provides ?? []) {
+    for (const [side, { module }] of Object.entries(ref.sides ?? {})) {
+      if (side === 'client') continue
+      if (module === pkg.name || module.startsWith(`${pkg.name}/`)) roots.push(entryFile(dir, pkg, `.${module.slice(pkg.name.length)}`))
+      else if (isAbsolute(module) || module.startsWith('.')) roots.push(onDisk(isAbsolute(module) ? module : resolve(root, module)))
+    }
+  }
+  const seen = new Set()
+  const queue = roots.filter(f => f && !relative(dir, f).startsWith('..'))
+  const uses = []
+  /** @type {Set<string>} */
+  const dependencies = new Set()
+  while (queue.length) {
+    const file = queue.pop()
+    if (seen.has(file)) continue
+    seen.add(file)
+    const found = scanFile(readFileSync(file, 'utf8'), file)
+    for (const u of found.uses) uses.push({ ...u, file: posix(relative(dir, file)) })
+    for (const name of found.imports) {
+      if (!name.startsWith('.')) {
+        if (name !== pkg.name && !name.startsWith(`${pkg.name}/`)) dependencies.add(name.split('/').slice(0, name.startsWith('@') ? 2 : 1).join('/'))
+        continue
+      }
+      const next = onDisk(resolve(dirname(file), name))
+      if (next && !relative(dir, next).startsWith('..')) queue.push(next)
+    }
+  }
+  const granted = grants(contribution.permissions)
+  return {
+    uses: uses.sort((a, b) => a.need.localeCompare(b.need) || a.file.localeCompare(b.file) || a.line - b.line),
+    undeclared: sorted(uses.map(u => u.need).filter(need => !declared(need, granted))),
+    dependencies: [...dependencies].sort(),
+  }
+}
+
+/** Is `need` from the audit covered by what the plugin declared? */
+function declared(need, granted) {
+  if (need === 'env:*') return granted.some(g => g.startsWith('env:'))
+  if (need.startsWith('env:')) return granted.includes(need) || granted.includes('env:*')
+  if (need === 'native') return granted.includes('native')
+  const kind = { fs: 'fs.', net: 'net:', spawn: 'spawn:' }[need]
+  return granted.some(g => g.startsWith(kind))
+}
+
+/**
+ * Every plugin against the lock. A plugin whose code is pinned and unchanged has nothing new to find, so only `full`
+ * reads it again; one with nothing to pin (a workspace package) is read every time.
+ * @param {{ full?: boolean }} [options]
+ */
+export function trustStatus(root, loaded, { full = false } = {}) {
+  const lock = readLock(root)
+  const plugins = loaded.contributions.map(c => {
+    const entry = lock.plugins[c.name] ?? null
+    const dir = packageDir(root, c.name)
+    const source = !dir ? 'config' : dir.split(sep).includes('node_modules') ? 'package' : 'workspace'
+    const integrity = source === 'package' ? hashPackage(dir) : null
+    const permissions = grants(c.permissions)
+    const provides = sorted((c.manifest.provides ?? []).map(p => (p.key ? `${p.slot.id}[${p.key}]` : p.slot.id)))
+    // A scaffold approves permissions before there's an install to hash (`integrity: null`), and that's filled in by `approve`.
+    const changed = !!entry && (entry.integrity ?? null) !== integrity && !(entry.integrity == null && source === 'package')
+    const scanned = dir && (full || !entry || !integrity || !entry.integrity || changed) ? audit(root, dir, c) : null
+    const uses = scanned?.uses ?? []
+    // Without a scan the lock's own record stands: those are the same files.
+    const undeclared = scanned?.undeclared ?? entry?.undeclared ?? []
+    const added = permissions.filter(g => !entry?.permissions?.includes(g))
+    const removed = (entry?.permissions ?? []).filter(g => !permissions.includes(g))
+    const hidden = undeclared.filter(need => !entry?.undeclared?.includes(need))
+    return {
+      name: c.name, version: c.version ?? null, source, integrity, permissions, provides, uses, undeclared, dependencies: scanned?.dependencies ?? [],
+      locked: !!entry, lockedVersion: entry?.version ?? null, added, removed, hidden, integrityChanged: changed, blocked: added.length > 0 || hidden.length > 0 || changed,
+    }
+  })
+  return { lock: lockFile, found: lock.found, broken: lock.broken, plugins, stale: Object.keys(lock.plugins).filter(name => !plugins.some(p => p.name === name)).sort() }
+}
+
+/** P109 and P110 for what the lock doesn't cover. `trust: 'warn'` in the config makes them warnings. */
+export function trustDiagnostics(root, loaded, status = trustStatus(root, loaded)) {
+  const severity = loaded.config.trust === 'warn' ? 'warning' : 'error'
+  const rel = loaded.file ? posix(relative(root, loaded.file)) : 'weft.config.ts'
+  const text = loaded.file ? readFileSync(loaded.file, 'utf8') : ''
+  const out = []
+  const report = (code, name, why, help) => out.push(diagnostic({ code, severity, owner: name, file: rel, why, help, ...locate(text, name) }))
+  if (status.broken) out.push(diagnostic({ code: 'P110', severity, file: lockFile, why: `${lockFile} can't be read: ${status.broken}.`, help: 'Fix it, or delete it and approve each plugin again.' }))
+  for (const p of status.plugins) {
+    const approve = `Review it, then run \`weft plugins approve ${p.name}\`.`
+    if (p.added.length) report('P109', p.name, `\`${p.name}\` asks for permissions the lock doesn't give it: ${p.added.join(', ')}.`, approve)
+    if (p.hidden.length) report('P109', p.name, `\`${p.name}\` uses ${p.hidden.join(', ')} without declaring it (${p.uses.find(u => p.hidden.includes(u.need))?.file ?? 'see `weft plugins audit`'}).`, `Have it declared, or review it and run \`weft plugins approve ${p.name}\`.`)
+    if (p.integrityChanged) report('P110', p.name, `\`${p.name}\`${p.lockedVersion && p.lockedVersion !== p.version ? ` went from ${p.lockedVersion} to ${p.version} and its` : `'s installed`} code isn't what the lock recorded.`, `Reinstall the locked version, or review the update and run \`weft plugins approve ${p.name}\`.`)
+  }
+  return out
+}
+
+/** Stops `weft dev` and `weft build` before a blocked plugin's build hooks run. */
+export function requireTrust(root, loaded) {
+  if (loaded.diagnostics.some(d => d.code === 'P007')) return
+  const blocked = trustDiagnostics(root, loaded).filter(d => d.severity === 'error')
+  if (blocked.length) throw refused(blocked.map(d => `${d.code} ${d.why} ${d.fix.text}`).join('\n'))
+}
+
+/** `weft plugins audit --json`. */
+export function auditCommand(root, loaded) {
+  const status = trustStatus(root, loaded, { full: true })
+  const diagnostics = trustDiagnostics(root, loaded, status)
+  return { ok: !diagnostics.some(d => d.severity === 'error'), ...status, diagnostics: [...loaded.diagnostics, ...diagnostics] }
+}
+
+/** `.weft/` in a .gitignore hides the lock, and a lock nobody commits protects nobody. */
+function unignoreLock(root) {
+  const file = join(root, '.gitignore')
+  if (!existsSync(file)) return false
+  const text = readFileSync(file, 'utf8')
+  const next = text.replace(/^\/?\.weft\/?$/m, `.weft/*\n!${lockFile}`)
+  if (next === text) return false
+  writeFileSync(file, next)
+  return true
+}
+
+/**
+ * `weft plugins approve`: names, or `all`. With neither it only shows what's waiting, so approving is always something
+ * said out loud, one plugin at a time or all at once.
+ */
+export function approveCommand(root, loaded, { names = [], all = false } = {}) {
+  const failed = loaded.diagnostics.find(d => d.code === 'P007')
+  if (failed) throw refused(`The config doesn't load, so nothing can be approved: ${failed.why}`)
+  const status = trustStatus(root, loaded, { full: true })
+  if (status.broken) throw refused(`${lockFile} can't be read: ${status.broken}. Fix it, or delete it and approve each plugin again.`)
+  const pending = status.plugins.filter(p => p.blocked)
+  const unknown = names.filter(n => !status.plugins.some(p => p.name === n))
+  if (unknown.length) throw Object.assign(new Error(`not in \`plugins\`: ${unknown.join(', ')}`), { code: 'E_USAGE' })
+  if (!all && !names.length) return { ok: !pending.length, written: false, lock: lockFile, approved: [], pending, stale: status.stale }
+
+  const chosen = status.plugins.filter(p => all || names.includes(p.name))
+  const entries = { ...readLock(root).plugins }
+  if (all) for (const name of status.stale) delete entries[name]
+  for (const p of chosen) entries[p.name] = { version: p.version, integrity: p.integrity, permissions: p.permissions, provides: p.provides, undeclared: p.undeclared }
+  const ordered = Object.fromEntries(Object.keys(entries).sort().map(name => [name, entries[name]]))
+  mkdirSync(join(root, '.weft'), { recursive: true })
+  writeFileSync(join(root, lockFile), `${JSON.stringify({ version: 1, plugins: ordered }, null, 2)}\n`)
+  return { ok: true, written: true, lock: lockFile, approved: chosen, pending: pending.filter(p => !chosen.includes(p)), stale: all ? [] : status.stale, gitignore: unignoreLock(root) }
+}
+
+/** One line per plugin for the terminal. */
+export function formatTrust(p) {
+  const parts = [
+    ...p.added.map(g => `+${g}`),
+    ...p.removed.map(g => `-${g}`),
+    ...p.hidden.map(n => `undeclared ${n}`),
+    ...(p.integrityChanged ? [`code changed${p.lockedVersion && p.lockedVersion !== p.version ? ` (${p.lockedVersion} → ${p.version})` : ''}`] : []),
+  ]
+  return `${p.blocked ? '!' : ' '} ${p.name}@${p.version ?? '?'}  ${parts.join('  ') || (p.locked ? 'approved' : 'not locked, asks for nothing')}`
+}

package/src/weft.mjs

@@ -0,0 +1,66 @@
+// The installed weft: its compiler (only through the public `@weft-js/core/compiler` transform()), version and exports.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import ts from 'typescript'
+
+const own = createRequire(import.meta.url)
+
+/** The project's own weft wins; the CLI's weft (its dev/peer dependency) is the fallback. */
+export function resolveWeft(root) {
+  const tries = [() => createRequire(join(root, 'package.json')).resolve('@weft-js/core/compiler'), () => own.resolve('@weft-js/core/compiler')]
+  for (const [i, attempt] of tries.entries()) {
+    let path
+    try {
+      path = attempt()
+    } catch {
+      continue
+    }
+    let dir = dirname(path)
+    while (!existsSync(join(dir, 'package.json')) && dirname(dir) !== dir) dir = dirname(dir)
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+    return { from: i === 0 ? 'project' : 'cli', dir, version: pkg.version, pkg, compilerPath: path }
+  }
+  throw Object.assign(new Error('weft is not installed: `@weft-js/core/compiler` resolves neither from the project nor from @weft-js/cli'), { code: 'E_NO_WEFT' })
+}
+
+const compilers = new Map()
+
+/** @returns {{ transform(source: string, options?: object): { code: string | null, diagnostics: any[] } }} */
+export function loadCompiler(weft) {
+  if (!compilers.has(weft.compilerPath)) compilers.set(weft.compilerPath, own(weft.compilerPath))
+  return compilers.get(weft.compilerPath)
+}
+
+/** Exported names per public subpath, read from the installed package's entry files (no execution). */
+export function exportsOf(weft, subpaths = ['.', './dom', './ssr', './test', './browser', './interaction', './style', './surface']) {
+  const out = {}
+  for (const sub of subpaths) {
+    const target = weft.pkg.exports?.[sub]
+    const file = typeof target === 'string' ? join(weft.dir, target) : null
+    if (!file || !/\.[mc]?[jt]sx?$/.test(file) || !existsSync(file)) continue
+    /** @type {Set<string>} */
+    const names = new Set()
+    const read = path => {
+      const sf = ts.createSourceFile(path, readFileSync(path, 'utf8'), ts.ScriptTarget.Latest, true)
+      for (const node of sf.statements) {
+        const exported = ts.canHaveModifiers(node) && ts.getModifiers(node)?.some(m => m.kind === ts.SyntaxKind.ExportKeyword)
+        if (ts.isExportDeclaration(node) && !node.exportClause && !node.isTypeOnly) {
+          // `export * from './index'`: the `weft` entry is a thin one over the runtime.
+          const next = join(dirname(path), `${node.moduleSpecifier.text}.ts`)
+          if (existsSync(next)) read(next)
+        } else if (ts.isExportDeclaration(node) && node.exportClause && ts.isNamedExports(node.exportClause)) {
+          if (!node.isTypeOnly) for (const el of node.exportClause.elements) if (!el.isTypeOnly) names.add(el.name.text)
+        } else if (exported && (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) && node.name) {
+          names.add(node.name.text)
+        } else if (exported && ts.isVariableStatement(node)) {
+          for (const d of node.declarationList.declarations) if (ts.isIdentifier(d.name)) names.add(d.name.text)
+        }
+      }
+    }
+    read(file)
+    out[sub === '.' ? '@weft-js/core' : `@weft-js/core/${sub.slice(2)}`] = [...names].sort()
+  }
+  return out
+}

package/src/workspace.mjs

@@ -0,0 +1,105 @@
+// Scratch copies of a project for the gate, and vitest runs in them. A copy lives in `<root>/.weft/gate/<id>`, so
+// node_modules hoisted above the project still resolve; the project's own node_modules dirs are symlinked, not copied.
+
+import { spawn } from 'node:child_process'
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync, copyFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join, relative } from 'node:path'
+
+const skipDirs = new Set(['.git', '.weft', 'dist', 'coverage', '.turbo', 'target'])
+
+/**
+ * Copy `root` into a new scratch dir. `exclude(rel)` leaves a path out (relative to root, posix).
+ * @returns {string} the copy's real path
+ */
+export function copyProject(root, { exclude = () => false, id = Math.random().toString(36).slice(2, 8) } = {}) {
+  const dest = join(root, '.weft', 'gate', `${process.pid}-${id}`)
+  rmSync(dest, { recursive: true, force: true })
+  mkdirSync(dest, { recursive: true })
+  const go = (from, to, rel) => {
+    for (const e of readdirSync(from, { withFileTypes: true })) {
+      const r = rel ? `${rel}/${e.name}` : e.name
+      const src = join(from, e.name)
+      if (e.name === 'node_modules') { symlinkSync(realpathSync(src), join(to, e.name)); continue }
+      if (exclude(r)) continue
+      if (e.isDirectory()) {
+        if (skipDirs.has(e.name)) continue
+        mkdirSync(join(to, e.name))
+        go(src, join(to, e.name), r)
+      } else if (e.isFile()) copyFileSync(src, join(to, e.name))
+      else if (e.isSymbolicLink()) { try { symlinkSync(realpathSync(src), join(to, e.name)) } catch {} }
+    }
+  }
+  go(root, dest, '')
+  return realpathSync(dest)
+}
+
+/** Write (or with `null`, delete) files in a copy. */
+export function writeFiles(dir, files) {
+  for (const [rel, text] of Object.entries(files)) {
+    const abs = join(dir, rel)
+    if (text == null) rmSync(abs, { force: true })
+    else { mkdirSync(dirname(abs), { recursive: true }); writeFileSync(abs, text) }
+  }
+}
+
+export function removeCopy(dir) {
+  rmSync(dir, { recursive: true, force: true })
+  // Leave `.weft/gate` behind only when something else is in it.
+  const gateDir = dirname(dir)
+  try { if (!readdirSync(gateDir).length) rmSync(gateDir, { recursive: true }) } catch {}
+}
+
+/** The vitest CLI the project would run: its own, else the CLI's. */
+export function vitestBin(root) {
+  for (const req of [createRequire(join(root, 'package.json')), createRequire(import.meta.url)]) {
+    try {
+      let dir = dirname(req.resolve('vitest'))
+      while (!existsSync(join(dir, 'package.json')) || !/"name":\s*"vitest"/.test(readFileSync(join(dir, 'package.json'), 'utf8'))) {
+        if (dirname(dir) === dir) throw new Error('no vitest')
+        dir = dirname(dir)
+      }
+      return join(dir, 'vitest.mjs')
+    } catch {}
+  }
+  throw Object.assign(new Error('vitest is not installed in this project'), { code: 'E_NO_VITEST' })
+}
+
+/**
+ * Run vitest on `files` (relative to `dir`) and read its JSON report.
+ * @returns {Promise<{ tests: Map<string, { status: string, message?: string }>, loadErrors: Map<string, string>, timedOut: boolean, ms: number, stderr: string }>}
+ *   `tests` is keyed `<file>::<suite > test>`; `loadErrors` by file, for files that failed before running a test.
+ */
+export function runVitest(dir, files, { bin, timeoutMs = 120_000, config } = {}) {
+  const report = join(dir, `.weft-report-${Math.random().toString(36).slice(2, 8)}.json`)
+  const args = [bin, 'run', '--root', dir, '--reporter=json', `--outputFile=${report}`, '--passWithNoTests', ...(config ? ['--config', config] : []), ...files]
+  const started = performance.now()
+  return new Promise(resolve => {
+    const child = spawn(process.execPath, args, { cwd: dir, stdio: ['ignore', 'ignore', 'pipe'], env: { ...process.env, FORCE_COLOR: '0', CI: '1' }, detached: true })
+    let stderr = ''
+    child.stderr.on('data', d => { if (stderr.length < 20_000) stderr += d })
+    let timedOut = false
+    const timer = setTimeout(() => { timedOut = true; try { if (child.pid !== undefined) process.kill(-child.pid, 'SIGKILL') } catch {} }, timeoutMs)
+    child.on('close', () => {
+      clearTimeout(timer)
+      const tests = new Map(), loadErrors = new Map()
+      if (!timedOut && existsSync(report)) {
+        let data
+        try { data = JSON.parse(readFileSync(report, 'utf8')) } catch {}
+        rmSync(report, { force: true })
+        for (const f of data?.testResults ?? []) {
+          const file = relative(dir, safeReal(f.name)).split('\\').join('/')
+          if (!f.assertionResults.length) { loadErrors.set(file, firstLine(f.message) || 'the file failed to load'); continue }
+          for (const a of f.assertionResults)
+            tests.set(`${file}::${[...a.ancestorTitles, a.title].join(' > ')}`, { status: a.status, message: firstLine(a.failureMessages?.[0]) })
+        }
+      }
+      resolve({ tests, loadErrors, timedOut, ms: Math.round(performance.now() - started), stderr })
+    })
+  })
+}
+
+const safeReal = p => { try { return realpathSync(p) } catch { return p } }
+const firstLine = s => s?.split('\n').find(l => l.trim())?.trim().slice(0, 300)
+
+export const isDir = p => { try { return lstatSync(p).isDirectory() } catch { return false } }