@weft-js/cli 0.0.0-stage → 0.1.0

package/src/infer/worker.cjs

@@ -0,0 +1,97 @@
+// The dev listener's thread (research 44 §7). It takes file names, waits out a burst of saves, and works out what they
+// changed. HMR never waits on it: the main thread only posts a name here, and TypeScript runs in its own process.
+
+const { createHash } = require('node:crypto')
+const { mkdirSync, readFileSync, renameSync, writeFileSync } = require('node:fs')
+const { join, relative } = require('node:path')
+const { parentPort, workerData } = require('node:worker_threads')
+const ts = require('typescript')
+const { Session } = require('./session.cjs')
+
+const { root, write, debounce = 25, settle = 400, rest = 120_000 } = workerData
+const session = new Session(ts, root)
+const pending = new Set()
+let timer = null, running = false, last = '', writes = null, resting = null
+
+function publish(list) {
+  const text = JSON.stringify(list)
+  if (text === last) return false
+  last = text
+  mkdirSync(join(root, '.weft'), { recursive: true })
+  const file = join(root, '.weft', 'props.json')
+  writeFileSync(`${file}.tmp`, `${JSON.stringify({ diagnostics: list }, null, 2)}\n`)
+  renameSync(`${file}.tmp`, file)
+  return true
+}
+
+const applyEdits = (text, edits) => [...edits].sort((a, b) => b.start - a.start).reduce((t, e) => t.slice(0, e.start) + e.text + t.slice(e.end), text)
+
+/** Exported types go into the source once the file has been quiet, and only if it's still the text they were made from. */
+function scheduleWrites(findings) {
+  clearTimeout(writes)
+  if (!write) return
+  const jobs = [...findings].flatMap(([file, list]) => { const edits = list.filter(f => f.safe && f.edits).flatMap(f => f.edits); return edits.length ? [{ file, edits, hash: session.engine.facts.get(file)?.hash, codes: list.map(f => f.code) }] : [] })
+  if (!jobs.length) return
+  writes = setTimeout(() => {
+    for (const job of jobs) {
+      const text = readFileSync(job.file, 'utf8')
+      if (createHash('sha1').update(text).digest('base64url').slice(0, 16) !== job.hash) continue
+      writeFileSync(job.file, applyEdits(text, job.edits))
+      parentPort.postMessage({ type: 'wrote', file: relative(root, job.file) })
+    }
+  }, settle)
+}
+
+/** The checker holds a few hundred MB, so it goes after two quiet minutes. The next save starts it again. */
+function rested() {
+  clearTimeout(resting)
+  resting = setTimeout(() => session.close(), rest)
+  resting.unref()
+}
+
+async function first() {
+  running = true
+  try { await report(performance.now()) } catch (e) { parentPort.postMessage({ type: 'failed', message: e.stack }) } finally { running = false }
+  await drain()
+}
+
+async function report(t, files) {
+  const { findings, errors } = await session.analyze(files)
+  const flat = []
+  for (const [file, list] of [...findings, ...errors]) for (const f of list) flat.push({ file: relative(root, file), line: session.engine.texts.get(file).slice(0, f.start).split('\n').length, code: f.code, severity: f.severity ?? 'error', why: f.why, help: f.help })
+  scheduleWrites(findings)
+  const changed = publish(flat)
+  rested()
+  parentPort.postMessage({ type: 'done', ms: performance.now() - t, at: Date.now(), changed, diagnostics: flat })
+}
+
+async function drain() {
+  if (running) return
+  running = true
+  try {
+    while (pending.size) {
+      const files = [...pending]
+      pending.clear()
+      const t = performance.now()
+      let changed = false
+      for (const f of files) if (session.engine.set(f)) changed = true
+      if (session.host) session.touch(files)
+      if (!changed || !files.some(f => session.engine.relevant(f))) { parentPort.postMessage({ type: 'idle', ms: performance.now() - t }); continue }
+      await report(t, files)
+    }
+  } catch (e) {
+    parentPort.postMessage({ type: 'failed', message: e.stack })
+  } finally {
+    running = false
+  }
+}
+
+parentPort.on('message', msg => {
+  if (msg === 'close') { clearTimeout(timer); clearTimeout(writes); session.close(); process.exit(0) }
+  pending.add(msg)
+  clearTimeout(timer)
+  timer = setTimeout(() => void drain(), debounce)
+})
+
+parentPort.postMessage({ type: 'ready', needed: session.engine.needed() })
+if (session.engine.needed()) void first()

package/src/jsx-scan.mjs

@@ -0,0 +1,86 @@
+// A small JSX view of one .tsx/.jsx file (research 26 §2.5, §7), shared by the X-code pass and plugin `check` hooks:
+// imports, every element with its attributes and ancestors, and the file's function bodies by name. TypeScript's
+// parser only, no type checking.
+
+import ts from 'typescript'
+
+/**
+ * @typedef {{ name: string, kind: 'string' | 'expr' | 'bool' | 'spread', value?: string, expr?: string, start: number, end: number, valueStart?: number, valueEnd?: number }} Attr
+ * @typedef {{ name: string, attrs: Attr[], attr: (n: string) => Attr | undefined, ancestors: string[], start: number, end: number, tagEnd: number, children: string }} Element
+ * @typedef {{ local: string, imported?: string, source: string, start: number, end: number }} Import
+ */
+
+/**
+ * @param {string} text
+ * @param {string} [file]
+ * @returns {{ imports: Import[], elements: Element[], functions: Map<string, string> }}
+ */
+export function scanJsx(text, file = 'file.tsx') {
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('.jsx') ? ts.ScriptKind.JSX : ts.ScriptKind.TSX)
+  const imports = []
+  const elements = []
+  const functions = new Map()
+  const stack = []
+
+  const attrsOf = attributes =>
+    attributes.properties.map(p => {
+      if (ts.isJsxSpreadAttribute(p)) return { name: '...', kind: 'spread', expr: p.expression.getText(sf), start: p.getStart(sf), end: p.end }
+      const name = p.name.getText(sf)
+      const base = { name, start: p.getStart(sf), end: p.end }
+      if (!p.initializer) return { ...base, kind: 'bool' }
+      if (ts.isStringLiteral(p.initializer)) return { ...base, kind: 'string', value: p.initializer.text, valueStart: p.initializer.getStart(sf), valueEnd: p.initializer.end }
+      const e = p.initializer.expression
+      if (e && (ts.isStringLiteral(e) || ts.isNoSubstitutionTemplateLiteral(e))) return { ...base, kind: 'string', value: e.text, valueStart: e.getStart(sf), valueEnd: e.end }
+      return { ...base, kind: 'expr', expr: e ? e.getText(sf) : '', valueStart: e?.getStart(sf), valueEnd: e?.end }
+    })
+
+  const record = (open, node) => {
+    const attrs = attrsOf(open.attributes)
+    const el = {
+      name: open.tagName.getText(sf),
+      attrs,
+      attr: n => attrs.find(a => a.name === n),
+      ancestors: [...stack],
+      start: node.getStart(sf),
+      end: node.end,
+      tagEnd: open.tagName.end,
+      children: ts.isJsxElement(node) ? node.children.map(c => c.getText(sf)).join('') : '',
+    }
+    elements.push(el)
+    return el
+  }
+
+  const visit = node => {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+      const source = node.moduleSpecifier.text
+      const c = node.importClause
+      const at = { source, start: node.getStart(sf), end: node.end }
+      if (c?.name) imports.push({ local: c.name.text, ...at })
+      if (c?.namedBindings && ts.isNamedImports(c.namedBindings)) for (const s of c.namedBindings.elements) imports.push({ local: s.name.text, imported: s.propertyName?.text ?? s.name.text, ...at })
+      if (!c) imports.push({ local: '', ...at })
+    }
+    if (ts.isFunctionDeclaration(node) && node.name && node.body) functions.set(node.name.text, node.body.getText(sf))
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer && (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer))) {
+      functions.set(node.name.text, node.initializer.body.getText(sf))
+    }
+    if (ts.isJsxSelfClosingElement(node)) {
+      record(node, node)
+    } else if (ts.isJsxElement(node)) {
+      const el = record(node.openingElement, node)
+      // attribute expressions (a `pending={<X />}`) see this element as an ancestor too
+      stack.push(el.name)
+      ts.forEachChild(node, visit)
+      stack.pop()
+      return
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sf)
+  return { imports, elements, functions }
+}
+
+/** The import an identifier in an expression (`{hero}`, `{hero.src}`) comes from, or undefined. */
+export function importOf(scan, expr) {
+  const id = /^\s*([A-Za-z_$][\w$]*)/.exec(expr ?? '')?.[1]
+  return id ? scan.imports.find(i => i.local === id) : undefined
+}

package/src/load-config.mjs

@@ -0,0 +1,274 @@
+// Find, load and validate weft.config (TypeScript, JSON or YAML, one schema: research 34 §2). Plugins run only their pure
+// `contribute()` (plugins.mjs); `slots` is data.
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import nodeModule, { createRequire } from 'node:module'
+import { join, relative } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import ts from 'typescript'
+import { z } from 'zod'
+import { diagnostic, locate } from './diag.mjs'
+import { checkSite } from './site.mjs'
+import { contributions } from './contributions.mjs'
+import { bindSlots } from './slots.mjs'
+
+export const configNames = ['weft.config.ts', 'weft.config.mts', 'weft.config.js', 'weft.config.mjs', 'weft.config.json', 'weft.config.yaml', 'weft.config.yml']
+export const builtinNames = ['add', 'map', 'dev', 'build', 'start', 'db', 'test', 'check', 'doctor', 'fix', 'tokens', 'browser', 'mcp', 'tasks', 'run', 'create', 'docs', 'agents-md', 'plugins']
+
+const configModule = pathToFileURL(join(fileURLToPath(new URL('.', import.meta.url)), 'config.mjs')).href
+const nativeRequire = createRequire(import.meta.url)
+/** Node's sync module hooks. Bun has none, and Deno's break `.node` requires, like Rolldown's; both read TypeScript without help (`importConfig`). */
+const registerHooks = process.versions.bun || process.versions.deno ? null : nodeModule.registerHooks
+/** `weft.config.ts.weft-load-<n>`: a fresh module id per load, so a long-lived `weft mcp` sees edits. */
+const tag = /\.weft-load-\d+$/
+let hooked = false
+
+const transpile = path =>
+  ts.transpileModule(readFileSync(path, 'utf8'), {
+    fileName: path,
+    compilerOptions: { module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ES2022 },
+  }).outputText
+
+/**
+ * Sync module hooks, so loading is Node's own `require(esm)` and works inside test runners' vm contexts too.
+ * `@weft-js/core/config` resolves to the project's weft when it ships one, else to ours; `.ts` is transpiled, not stripped.
+ */
+function hook() {
+  if (hooked) return
+  hooked = true
+  registerHooks({
+    resolve(specifier, context, next) {
+      if (tag.test(specifier)) return { url: pathToFileURL(specifier).href, format: 'module', shortCircuit: true }
+      if (specifier === '@weft-js/core/config' || specifier === '@weft-js/cli/config') {
+        try {
+          return next(specifier, context)
+        } catch {
+          return { url: configModule, shortCircuit: true }
+        }
+      }
+      return next(specifier, context)
+    },
+    load(url, context, next) {
+      if (!url.startsWith('file:')) return next(url, context)
+      const path = fileURLToPath(url)
+      if (tag.test(path)) {
+        const real = path.replace(tag, '')
+        return { format: 'module', source: /\.[mc]?ts$/.test(real) ? transpile(real) : readFileSync(real, 'utf8'), shortCircuit: true }
+      }
+      if (/\.[mc]?ts$/.test(path) && !path.includes('/node_modules/')) return { format: 'module', source: transpile(path), shortCircuit: true }
+      return next(url, context)
+    },
+  })
+}
+
+/**
+ * The config on Bun and Deno: their own TypeScript, with a query for a fresh module per load. When the project has no
+ * `@weft-js/core/config` of its own, a copy next to the config, so its relative imports still resolve, imports ours instead.
+ */
+async function importConfig(file) {
+  try {
+    return (await import(`${pathToFileURL(file).href}?weft-load=${generation++}`)).default ?? {}
+  } catch (error) {
+    if (!/weft\/config|@weft-js\/cli\/config/.test(error.message)) throw error
+  }
+  const copy = `${file}.weft-load-${generation++}.mjs`
+  writeFileSync(copy, transpile(file).replace(/(['"])(?:weft\/config|@weft-js\/cli\/config)\1/g, JSON.stringify(configModule)))
+  try {
+    return (await import(pathToFileURL(copy).href)).default ?? {}
+  } finally {
+    rmSync(copy, { force: true })
+  }
+}
+
+const zodSchema = z.custom(v => v != null && typeof v === 'object' && ('_zod' in v || '~standard' in v))
+const globs = z.array(z.string())
+
+const task = z.strictObject({
+  run: z.string().min(1),
+  description: z.string().optional(),
+  sideEffects: z.array(z.string()).optional(),
+  env: z.array(z.string()).optional(),
+  args: z.union([zodSchema, z.record(z.string(), z.unknown())]).optional(),
+})
+
+const pluginEntry = z.looseObject({
+  name: z.string().min(1),
+  version: z.string().optional(),
+  provides: z.array(z.union([z.string(), z.strictObject({ slot: z.string(), key: z.string() })])).optional(),
+})
+
+const image = z.strictObject({ url: z.string().min(1), width: z.int().positive().optional(), height: z.int().positive().optional(), alt: z.string().optional() })
+
+const hex = z.string().regex(/^#[0-9a-fA-F]{6}$/, { error: 'must be #rrggbb' })
+const colors = { background: hex.optional(), text: hex.optional(), subtle: hex.optional(), accent: hex.optional() }
+const cardFont = z.strictObject({ family: z.string().regex(/^[\w -]+$/, { error: 'must be a font family name' }), src: z.string().min(1), weight: z.number().optional() })
+const card = z.strictObject({ ...colors, scheme: z.enum(['dark', 'light']).optional(), dark: z.strictObject(colors).optional(), light: z.strictObject(colors).optional(), fonts: z.strictObject({ display: cardFont.optional(), body: cardFont.optional() }).optional() })
+
+const site = z.strictObject({
+  headers: z.record(z.string(), z.record(z.string(), z.string())).optional(),
+  name: z.string().min(1).optional(),
+  url: z.url({ protocol: /^https?$/, error: 'must be an absolute http(s) URL' }).optional(),
+  title: z.string().includes('%s', { error: 'must contain `%s` (the page title)' }).optional(),
+  description: z.string().optional(),
+  locale: z.string().regex(/^[a-z]{2,3}(_[A-Z]{2})?$/, { error: 'must look like `en_US`' }).optional(),
+  inlineCss: z.boolean().optional(),
+  criticalCss: z.boolean().optional(),
+  criticalKeep: z.array(z.string()).optional(),
+  image: z.union([z.literal('auto'), z.literal(false), z.string().min(1), image]).optional(),
+  card: card.optional(),
+  head: z.string().optional(),
+  twitter: z
+    .strictObject({ card: z.enum(['summary', 'summary_large_image', 'app', 'player']).optional(), site: z.string().optional(), creator: z.string().optional() })
+    .optional(),
+})
+
+export const configSchema = z.strictObject({
+  scope: z.strictObject({ write: globs.optional(), read: globs.optional(), forbid: globs.optional() }).optional(),
+  tasks: z.record(z.string(), task).optional(),
+  environments: z.record(z.string(), z.looseObject({ url: z.string().optional() })).optional(),
+  test: z
+    .strictObject({
+      include: globs.optional(),
+      lanes: z.array(z.enum(['fast', 'browser', 'e2e'])).optional(),
+      gate: z.strictObject({ mutationBudgetSec: z.number().positive().optional(), maxMutants: z.number().int().positive().optional() }).optional(),
+    })
+    .optional(),
+  build: z.strictObject({
+    audit: z.union([z.boolean(), z.strictObject({ routes: z.array(z.string()).optional(), all: z.boolean().optional(), max: z.number().int().positive().optional() })]).optional(),
+    unsafeAllow: z.record(z.string().regex(/^(all|[A-Z]|[A-Z]+\d{3})$/, 'a code (R002), a family (L) or all'), z.string().min(1, 'say why')).optional(),
+  }).optional(),
+  check: z.strictObject({ include: globs.optional(), exclude: globs.optional(), design: z.boolean().optional(), routes: z.boolean().optional(), props: z.union([z.boolean(), z.literal('manual')]).optional() }).optional(),
+  plugins: z.array(pluginEntry).optional(),
+  slots: z.record(z.string(), z.union([z.string(), z.record(z.string(), z.string())])).optional(),
+  site: site.optional(),
+  runtime: z.enum(['node', 'bun', 'deno']).optional(),
+  hydration: z.enum(['lazy', 'partial', 'full']).optional(),
+  rust: z.strictObject({
+    unions: z.literal('allow').optional(),
+    services: z.record(z.string(), z.strictObject({ crate: z.string().optional(), external: z.boolean().optional(), wasm: z.literal(false).optional() })).optional(),
+  }).optional(),
+  /** Named targets for a query's `live: { verify: 'staging' }`. `db` is an env var's name. */
+  live: z.strictObject({
+    targets: z.record(z.string(), z.strictObject({ url: z.string().optional(), db: z.string().optional(), production: z.boolean().optional() })).optional(),
+  }).optional(),
+  trust: z.enum(['enforce', 'warn']).optional(),
+})
+
+/** What a JSON or YAML file may hold: data, so a plugin is `name` or `[name, options]`. Also the editor schema. */
+const dataSchema = configSchema.extend({
+  $schema: z.string().optional(),
+  plugins: z.array(z.union([z.string(), z.tuple([z.string(), z.unknown()]), pluginEntry])).optional(),
+})
+
+export const isDataConfig = file => /\.(json|ya?ml)$/.test(file)
+
+const configFiles = root => configNames.map(name => join(root, name)).filter(existsSync)
+
+export function findConfig(root) {
+  return configFiles(root)[0] ?? null
+}
+
+/** The schema `$schema` points at, for completion in `weft.config.json` and `.yaml`. */
+export function writeConfigSchema(root) {
+  mkdirSync(join(root, '.weft'), { recursive: true })
+  writeFileSync(join(root, '.weft', 'config.schema.json'), `${JSON.stringify(z.toJSONSchema(dataSchema, { unrepresentable: 'any' }), null, 2)}\n`)
+}
+
+/** `@weft-js/text` → `text`, `@weft-js/db/plugin-native` → `native`: the name a plugin's named export goes by. */
+export const pluginName = pkg => pkg.replace(/^@[^/]+\/(?:[^/]+\/)?/, '').replace(/^plugin-/, '').replace(/[^a-zA-Z0-9]+(.)?/g, (_, c = '') => c.toUpperCase())
+
+/** A plugin module's factory, and its import name: the default, or a named export (`surface-keel` may export `keel`). */
+export function pluginFactory(mod, pkg) {
+  if (typeof mod.default === 'function') return { value: mod.default, name: pluginName(pkg), named: false }
+  const name = [pluginName(pkg), pkg.split('-').at(-1)].find(n => typeof mod[n] === 'function')
+  return name ? { value: mod[name], name, named: true } : null
+}
+
+/** A data plugin from the project's own install: `<name>/plugin` when the package has one, else its main entry. */
+function loadPlugin(root, entry) {
+  if (typeof entry !== 'string' && !Array.isArray(entry)) return entry
+  const [name, options] = [entry].flat()
+  const require = createRequire(join(root, 'package.json'))
+  for (const spec of [`${name}/plugin`, name]) {
+    let path
+    try {
+      path = require.resolve(spec)
+    } catch {
+      continue
+    }
+    const factory = pluginFactory(nativeRequire(path), name)
+    if (!factory) throw new Error(`plugin \`${name}\` exports no factory to call`)
+    return factory.value(options)
+  }
+  throw new Error(`plugin \`${name}\` isn't installed`)
+}
+
+/** A JSON or YAML config as what a `.ts` one evaluates to. */
+function readDataConfig(root, file, text) {
+  const data = file.endsWith('.json') ? JSON.parse(text) : nativeRequire('yaml').parse(text)
+  const { $schema: _schema, ...config } = data ?? {}
+  if (Array.isArray(config.plugins)) config.plugins = config.plugins.map(p => loadPlugin(root, p))
+  return config
+}
+
+let generation = 0
+
+/**
+ * @param {string} root project root
+ * @returns {Promise<{ file: string | null, config: import('./config').WeftConfig, diagnostics: object[], slots: object, contributions: ReturnType<typeof contributions> }>}
+ */
+export async function loadConfig(root) {
+  const file = findConfig(root)
+  const diagnostics = []
+  const rel = file ? relative(root, file).split('\\').join('/') : 'weft.config.ts'
+  const text = file ? readFileSync(file, 'utf8') : ''
+  const report = (code, why, near, extra) => diagnostics.push(diagnostic({ code, file: rel, why, ...locate(text, near), ...extra }))
+  const others = configFiles(root).slice(1).map(f => relative(root, f))
+  if (others.length) report('P010', `\`${rel}\` is the config in use, and \`${others.join('`, `')}\` would be ignored.`, null)
+
+  let config = {}
+  if (file) {
+    if (registerHooks) hook()
+    try {
+      config = isDataConfig(file) ? readDataConfig(root, file, text) : registerHooks ? (nativeRequire(`${file}.weft-load-${generation++}`).default ?? {}) : await importConfig(file)
+    } catch (error) {
+      // A plugin factory rejecting its options throws while the config module evaluates (@weft-js/core/plugin).
+      if (error?.code === 'P115') report('P115', error.message.split('\n')[0], error.message.match(/^`([^`]+)`/)?.[1] ?? null)
+      else report('P007', `weft.config could not be loaded: ${error.message.split('\n')[0]}`, null)
+      return { file, config: {}, diagnostics, slots: bindSlots({}, () => {}), contributions: [] }
+    }
+    const parsed = configSchema.safeParse(config)
+    if (!parsed.success) {
+      for (const issue of parsed.error.issues) {
+        const path = issue.path.join('.')
+        report('P007', `\`${path || '(root)'}\`: ${issue.message}`, String(issue.path.at(-1) ?? ''), { help: 'Fix the key at the path shown (see `weft docs config`).' })
+      }
+      return { file, config, diagnostics, slots: bindSlots({}, () => {}), contributions: [] }
+    }
+  }
+
+  const tasks = config.tasks ?? {}
+  const commands = new Map()
+  for (const [name, t] of Object.entries(tasks)) {
+    if (builtinNames.includes(name)) report('P003', `Task \`${name}\` has the same name as the built-in \`weft ${name}\`.`, name)
+    const twin = commands.get(t.run.trim())
+    if (twin) report('P003', `Task \`${name}\` runs the same command as \`${twin}\` (\`${t.run}\`).`, name)
+    else commands.set(t.run.trim(), name)
+    const missing = [!t.description?.trim() && '`description`', !t.sideEffects && '`sideEffects`'].filter(Boolean)
+    if (missing.length) report('P004', `Task \`${name}\` has no ${missing.join(' or ')}.`, name)
+    for (const env of t.env ?? []) {
+      if (config.environments && !(env in config.environments)) report('P007', `Task \`${name}\` allows environment \`${env}\`, which \`environments\` does not define.`, name)
+    }
+  }
+
+  const seen = new Set()
+  for (const p of config.plugins ?? []) {
+    if (seen.has(p.name)) report('P116', `Plugin \`${p.name}\` is listed twice in \`plugins\`.`, p.name)
+    seen.add(p.name)
+  }
+  const unique = (config.plugins ?? []).filter((p, i, all) => all.findIndex(q => q.name === p.name) === i)
+  const contributed = contributions(unique, report, { root })
+  const slots = bindSlots({ ...config, plugins: unique }, report)
+  if (config.site) checkSite(config.site, report)
+  return { file, config, diagnostics, slots, contributions: contributed }
+}

package/src/map.mjs

@@ -0,0 +1,110 @@
+// `weft map`: a matrix of what to call in this app, generated from its config and code (research 34 §8). It runs on every
+// `weft check`, so it reads files and never starts Vite. Rows point at where an answer lives instead of copying it, and
+// a system the app doesn't have gets no row.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { discover } from './files.mjs'
+import { loadConfig } from './load-config.mjs'
+import { dbLayer } from './db-layer.mjs'
+import { listSurfaces } from './surface-checks.mjs'
+
+const read = (root, rel) => (existsSync(join(root, rel)) ? readFileSync(join(root, rel), 'utf8') : '')
+const names = (text, re) => [...text.matchAll(re)].map(m => m[1])
+/** Up to `max` names: enough to recognise the app, while the row's call gives the whole list. */
+const sample = (list, max = 6) => (list.length > max ? `${list.slice(0, max).join(', ')}, +${list.length - max}` : list.join(', '))
+
+function serverFunctions(root) {
+  const files = discover(root, { include: ['src/server/**/*.{ts,mts}', 'src/**/*.server.{ts,mts}'], exclude: [] })
+  const out = { functions: [], channels: [] }
+  for (const rel of files) {
+    const found = [...read(root, rel).matchAll(/export\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*(query|mutation|stream|channel)\s*\(/g)]
+    const fns = found.filter(m => m[2] !== 'channel').map(m => m[1])
+    if (fns.length) out.functions.push(`\`${rel}\`: ${fns.join(', ')}`)
+    out.channels.push(...found.filter(m => m[2] === 'channel').map(m => m[1]))
+  }
+  return out
+}
+
+const sqlText = (root, dir) => (existsSync(join(root, dir)) ? readdirSync(join(root, dir)).filter(f => f.endsWith('.sql')).map(f => read(root, join(dir, f))).join('\n') : '')
+const ENGINE = { PrismaLibSql: 'sqlite', PrismaPg: 'postgres', PrismaMariaDb: 'mysql' }
+
+export function database(root, layer) {
+  if (!layer) return null
+  const entry = read(root, 'src/db/index.server.ts')
+  const engine = entry.match(/@weft-js\/(?:start\/db|db\/plugin-native)\/(\w+)/)?.[1] ?? ENGINE[entry.match(/Prisma(?:LibSql|Pg|MariaDb)/)?.[0]] ?? 'unknown'
+  const tables = layer.layer === 'prisma' ? names(read(root, layer.schema), /^model\s+(\w+)/gm)
+    : layer.layer === 'native' ? names(sqlText(root, layer.migrations), /create\s+table\s+(?:if\s+not\s+exists\s+)?["`]?(\w+)/gi)
+      : names(read(root, 'src/db/schema.ts'), /export\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*\w+Table\s*\(/g)
+  return { engine, layer: layer.layer, tables }
+}
+
+function routes(root) {
+  const files = discover(root, { include: ['src/routes/**/*.{ts,tsx}'], exclude: [] })
+  return files.map(f => f.replace(/^src\/routes\//, '').replace(/\.[jt]sx?$/, '')).filter(f => !/(^|\/)_/.test(f))
+}
+
+/** The map as data. */
+export async function agentMap(root) {
+  root = resolve(root)
+  const loaded = await loadConfig(root)
+  const { config } = loaded
+  const pages = routes(root)
+  const fns = serverFunctions(root)
+  const env = ['src/env.ts', 'src/env.server.ts'].find(f => existsSync(join(root, f)))
+  const layer = await dbLayer(root, loaded)
+  const db = database(root, layer)
+  const authFile = read(root, 'src/auth.server.ts')
+  const auth = authFile && (authFile.includes('better-auth') ? 'better-auth' : 'custom')
+  const surfaces = listSurfaces(root).map(s => s.name)
+  const styled = existsSync(join(root, '.weft/styles.json')) ? Object.keys(JSON.parse(read(root, '.weft/styles.json')).groups ?? {}) : []
+  const bound = Object.entries(loaded.slots ?? {}).filter(([, v]) => typeof v === 'string' && !v.startsWith('weft:default')).map(([slot]) => slot)
+  const tasks = Object.keys(config.tasks ?? {})
+  const row = (want, call, have) => ({ want, call, ...(have && { have }) })
+
+  const rows = [
+    pages.length && row('Pages, their data and metadata', '`weft routes --meta`', sample(pages)),
+    fns.functions.length && row('Server functions', 'The file named here; signatures in `.weft/contract.json` after a build', fns.functions.join('; ')),
+    fns.channels.length && row('Channels', '`weft docs start`', sample(fns.channels)),
+    db && row('Tables and migrations', layer.schema ? `\`${layer.schema}\`, then \`weft db generate\`` : `\`weft db generate <name>\`, then SQL in \`${layer.migrations}/\``, sample(db.tables)),
+    auth && row('Who the user is', '`ctx.user` on the server; `src/auth.server.ts`', auth),
+    row('Styles', 'Before writing one: `weft style find <what it is>`', styled.length ? sample(styled) : undefined),
+    env && row('Environment variables', `\`${env}\`; values in \`.env\``),
+    surfaces.length && row('Canvas and WebGL', '`weft surfaces`', sample(surfaces)),
+    ...loaded.contributions.flatMap(c => c.manifest.map ?? []).map(r => row(r.want, r.call, r.have)),
+    (config.plugins?.length || bound.length) && row('Plugins and slots', '`weft plugins`, `weft plugins explain <slot>`', sample(bound)),
+    tasks.length && row('Project tasks', '`weft tasks --json`', sample(tasks)),
+    row('A rule or a diagnostic', '`weft docs <topic or code>`'),
+    row('The running app', '`weft browser snapshot`'),
+  ].filter(Boolean)
+
+  return { version: 1, app: config.site?.name ?? null, stack: { runtime: config.runtime ?? 'node', ui: config.plugins?.map(p => p.name) ?? [], db, auth: auth || null }, rows }
+}
+
+export function formatMap(map) {
+  const { stack } = map
+  const parts = [`runtime ${stack.runtime}`, stack.db && `${stack.db.layer} on ${stack.db.engine}`, stack.auth, ...stack.ui].filter(Boolean)
+  const table = map.rows.map(r => `| ${r.want} | ${r.call} | ${r.have ?? ''} |`)
+  return [
+    `# ${map.app ?? 'This app'}: agent map`,
+    '',
+    '<!-- Generated by `weft map` from this app\'s config and code. Do not edit. -->',
+    '',
+    `Stack: ${parts.join(', ')}.`,
+    '',
+    '| To find or do | Call | In this app |',
+    '|---|---|---|',
+    ...table,
+    '',
+  ].join('\n')
+}
+
+/** Write `.weft/map.md` and `.weft/map.json`. */
+export async function writeMap(root) {
+  root = resolve(root)
+  const map = await agentMap(root)
+  mkdirSync(join(root, '.weft'), { recursive: true })
+  writeFileSync(join(root, '.weft/map.md'), formatMap(map))
+  writeFileSync(join(root, '.weft/map.json'), `${JSON.stringify(map, null, 2)}\n`)
+  return map
+}