heartcode 0.0.0-stage → 0.1.0

package/src/context.js

@@ -0,0 +1,91 @@
+// How big a model's context window is, from the most to the least trusted:
+//   measured        the server's own limit, from one oversized request sent on purpose (the
+//                   settings page's Measure)
+//   context         what the running server says (llama.cpp, LM Studio, Ollama, vLLM, a /models
+//                   list), unless contextGuessed (it didn't say)
+//   known           models.dev's published limits for the model: { context, output }
+//   inputLimit      a limit a "too large" error stated, or a silent cut seen twice (inputLimitAt:
+//                   when); dropped when a bigger request works, and after a week (it's learned
+//                   again if it's still so: a refused request costs nothing)
+//   rateCap         a per-minute token cap the provider stated ({ tokens, until }): your account's,
+//                   not the model's, so it lasts a day
+// None of them: a local model server (server: llama.cpp, lmstudio, ollama) keeps the small size
+// it's assumed to run with; anything else (a provider, a proxy on your network) is assumed to take
+// 128k, or twice its largest request so far (up to 1M), growing as conversations do.
+// Also in the profile: server (what answered the probe), largestAccepted (the biggest request,
+// in tokens the server counted, that worked), tokenRatio (the server's count / HeartCode's
+// estimate), cutAt (a silent cut seen once).
+
+export const ASSUMED_REMOTE = 128_000
+export const ASSUMED_MAX = 1_000_000
+export const LOCAL_SERVERS = ['llama.cpp', 'lmstudio', 'ollama']
+export const RATE_CAP_MS = 86_400_000
+export const LIMIT_MS = 7 * 86_400_000
+
+// { size, sure, from }: from is measured, server, models.dev, learned, rate or assumed.
+export function contextWindow(p, now = Date.now()) {
+  let size
+  let from
+  if (p.measured > 0) [size, from] = [p.measured, 'measured']
+  else if (!p.contextGuessed && p.context > 0) [size, from] = [p.context, 'server']
+  else if (p.known?.context > 0) [size, from] = [p.known.context, 'models.dev']
+  if (p.inputLimit > 0 && !(now - p.inputLimitAt > LIMIT_MS) && !(size <= p.inputLimit)) [size, from] = [p.inputLimit, 'learned']
+  if (p.rateCap?.until > now && !(size <= p.rateCap.tokens)) [size, from] = [p.rateCap.tokens, 'rate']
+  if (size) return { size, sure: true, from }
+  const base = LOCAL_SERVERS.includes(p.server) ? p.context : ASSUMED_REMOTE
+  return { size: Math.min(ASSUMED_MAX, Math.max(base, 2 * (p.largestAccepted ?? 0))), sure: false, from: 'assumed' }
+}
+
+// After a reply: `used` is what the server says the request had (prompt tokens), `estimate` what
+// HeartCode thought it sent (images not counted as text). Updates the profile; returns what
+// changed: 'cut' (a limit learned from a silent cut), 'grew' (a bigger request worked), or null.
+export function learnFromUsage(p, used, estimate) {
+  if (!(used > 0) || !(estimate > 0)) return null
+  const expected = estimate * (p.tokenRatio ?? 1)
+  // Far fewer tokens than sent: the server dropped the start (Ollama beyond its num_ctx does).
+  // Seen twice at about the same size before it counts, so a provider that leaves out cached
+  // tokens, or one odd count, doesn't set a wrong limit.
+  if (estimate > 3000 && used >= 1024 && used < expected * 0.5) {
+    if (p.cutAt && Math.abs(used - p.cutAt) / p.cutAt < 0.15) {
+      p.inputLimit = Math.min(p.inputLimit ?? Infinity, Math.max(used, p.cutAt))
+      p.inputLimitAt = Date.now()
+      delete p.cutAt
+      return 'cut'
+    }
+    p.cutAt = used
+    return null
+  }
+  if (estimate > 500) {
+    const r = Math.min(3, Math.max(0.3, used / estimate))
+    p.tokenRatio = Math.round(((p.tokenRatio ?? r) * 0.7 + r * 0.3) * 1000) / 1000
+  }
+  let change = null
+  // a bigger request than a learned limit worked: that limit was wrong (or is gone)
+  if (p.inputLimit && used > p.inputLimit * 1.05) {
+    delete p.inputLimit
+    delete p.inputLimitAt
+    change = 'grew'
+  }
+  if (p.rateCap && used > p.rateCap.tokens) {
+    delete p.rateCap
+    change = 'grew'
+  }
+  if (used > (p.largestAccepted ?? 0) * 1.1) {
+    p.largestAccepted = used
+    change = 'grew'
+  }
+  return change
+}
+
+// What the window size is based on, for /model_info and the settings page.
+export function contextSource(p, cfg = {}) {
+  if (cfg.context) return 'set with --context'
+  const { from } = contextWindow(p)
+  if (from === 'measured') return 'measured: the server said its limit when sent an oversized request'
+  if (from === 'server') return `reported by the server${p.server ? ` (${p.server})` : ''}`
+  if (from === 'models.dev') return "models.dev's published limit for this model"
+  if (from === 'learned') return 'learned from the server refusing or cutting a bigger request'
+  if (from === 'rate') return `your per-minute token cap at this provider, until ${new Date(p.rateCap.until).toLocaleString()}`
+  if (LOCAL_SERVERS.includes(p.server)) return `the ${p.server} server doesn't say; assumed`
+  return `the server doesn't say; assumed${p.largestAccepted ? `, and seen working up to ${p.largestAccepted} tokens` : ''} (grows as bigger requests work)`
+}

package/src/director.js

@@ -0,0 +1,143 @@
+// Director mode: the main chat can set HeartCode itself up (skills, MCP servers, settings) when
+// asked in plain words, with one tool, manage. The settings page (General → Features) turns it off.
+import fs from 'node:fs'
+import path from 'node:path'
+import { HOME, readJson, writeJson } from './config.js'
+import { log } from './log.js'
+import { DEFAULT_SERVERS } from './mcp.js'
+import { prompt } from './prompts.js'
+import { frontMatter, loadSkills, skillDirs } from './skills.js'
+import { c, diffLines, renderDiff } from './ui.js'
+
+const KINDS = ['skill', 'mcp', 'setting']
+const safeName = (n) => String(n ?? '').toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '')
+
+export class Director {
+  // app: { root, ui, cfg, reload(kind), applySetting(name, value), settings() }
+  constructor(app) {
+    this.app = app
+  }
+
+  toolDefs(s) {
+    if (this.app.cfg.director === false) return []
+    const str = { type: 'string' }
+    const obj = (properties, required = []) => ({ type: 'object', properties, required })
+    return [
+      {
+        name: 'manage',
+        description: prompt('agent/tool-manage'),
+        parameters: obj({ action: { type: 'string', enum: ['help', 'list', 'show', 'save', 'delete'] }, kind: { type: 'string', enum: KINDS }, name: str, scope: { type: 'string', enum: ['project', 'global'] }, content: str, config: { type: 'object' }, value: str }, ['action']),
+      },
+    ]
+  }
+
+  // A tool call for manage: its result, or undefined when the tool isn't manage.
+  async tool(name, args, s) {
+    return name === 'manage' ? this.manage(args, s) : undefined
+  }
+
+  // --- manage: skills, MCP servers and settings ---
+
+  async manage(args, s) {
+    const { app } = this
+    const kind = args.kind
+    const scope = args.scope === 'global' ? 'global' : 'project'
+    const name = safeName(args.name)
+    if (args.action === 'help') return prompt('agent/director-help', Object.fromEntries(['args', '1', '2'].map((k) => [k, `{{${k}}}`]))) // the formats show these holes as they are
+    if (!KINDS.includes(kind)) return `error: kind must be one of ${KINDS.join(', ')}`
+    if (kind === 'setting') {
+      if (args.action === 'list' || args.action === 'show') return app.settings()
+      if (args.action === 'save') return app.applySetting(String(args.name ?? ''), String(args.value ?? args.content ?? ''))
+      return 'error: settings can be listed or saved'
+    }
+    if (args.action === 'list') return this.#list(kind)
+    if (!name) return `error: give the ${kind}'s name`
+    if (kind === 'mcp') return this.#mcp(args.action, name, scope, args.config ?? args.content, s)
+    const dirs = skillDirs(app.root)
+    const existing = loadSkills(app.root).get(name)
+    const dir = dirs[scope === 'global' ? 0 : 1]
+    // saving changes the existing file, unless a scope is given that it isn't in (then a new one there)
+    const file = existing && (!args.scope || existing.file.startsWith(dir + path.sep)) ? existing.file : path.join(dir, `${name}.md`)
+    if (args.action === 'show') return existing ? `${existing.file}\n\n${fs.readFileSync(existing.file, 'utf8')}` : `error: no ${kind} "${name}"`
+    if (args.action === 'delete') {
+      if (!existing) return `error: no ${kind} "${name}"`
+      const ok = await s.ui.confirm(`Delete the ${kind} ${name} (${existing.file})?`, 'edit')
+      if (ok !== true) return declined(ok)
+      const isFolder = /SKILL\.md$/.test(existing.file)
+      fs.rmSync(isFolder ? path.dirname(existing.file) : existing.file, { recursive: true, force: true })
+      app.reload(kind)
+      return `Deleted the ${kind} ${name}.`
+    }
+    if (args.action !== 'save') return 'error: action must be help, list, show, save or delete'
+    const content = String(args.content ?? '').trim()
+    if (!content) return `error: save needs content: the whole ${kind} file (front matter and text); manage help shows the format`
+    if (!frontMatter(content).meta.description) return `error: the ${kind} needs "description:" in its front matter (between --- lines at the top); manage help shows the format`
+    const old = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : ''
+    s.ui.print(renderDiff(diffLines(old, content + '\n'), tilde(file)))
+    const ok = await s.ui.confirm(`${old ? 'Update' : 'Save'} the ${kind} ${name}?`, 'edit')
+    if (ok !== true) return declined(ok)
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, content + '\n')
+    app.reload(kind)
+    log('director', `saved ${kind} ${name}: ${file}`)
+    const how = frontMatter(content).meta.use === 'model' ? '' : `The user can type it as /${name}.`
+    return `Saved the ${kind} ${name} (${tilde(file)}). ${how}`.trim()
+  }
+
+  #list(kind) {
+    const { app } = this
+    if (kind === 'skill') {
+      const all = [...loadSkills(app.root).values()]
+      return all.length ? all.map((k) => `${k.name} (use: ${k.use}; ${k.file.startsWith(HOME) ? 'global' : 'project'}): ${k.description}`).join('\n') : 'no skills yet'
+    }
+    const servers = { ...DEFAULT_SERVERS }
+    for (const f of mcpFiles(app.root)) Object.assign(servers, ...Object.entries(readJson(f.file, {}).mcpServers ?? {}).map(([n, cfg]) => ({ [n]: { ...servers[n], ...cfg, scope: f.scope } })))
+    return Object.entries(servers).map(([n, cfg]) => `${n}${cfg.disabled ? ' (disabled)' : ''}${DEFAULT_SERVERS[n] ? ' (built in)' : ` (${cfg.scope})`}: ${cfg.description ?? ''} [${cfg.command} ${(cfg.args ?? []).join(' ')}]`).join('\n')
+  }
+
+  async #mcp(action, name, scope, config, s) {
+    const files = mcpFiles(this.app.root)
+    const where = files.find((f) => readJson(f.file, {}).mcpServers?.[name])
+    if (action === 'show') {
+      const cfg = where ? readJson(where.file, {}).mcpServers[name] : DEFAULT_SERVERS[name]
+      return cfg ? JSON.stringify({ [name]: cfg }, null, 2) : `error: no MCP server "${name}"`
+    }
+    const file = (action === 'delete' && where ? where : files.find((f) => f.scope === scope)).file
+    const data = readJson(file, {})
+    data.mcpServers ??= {}
+    if (action === 'delete') {
+      if (!where && !DEFAULT_SERVERS[name]) return `error: no MCP server "${name}"`
+      const ok = await s.ui.confirm(`${DEFAULT_SERVERS[name] ? 'Turn off' : 'Delete'} the MCP server ${name}?`, 'edit')
+      if (ok !== true) return declined(ok)
+      if (DEFAULT_SERVERS[name]) data.mcpServers[name] = { disabled: true } // built in: turned off, not gone
+      else delete data.mcpServers[name]
+      writeJson(file, data)
+      this.app.reload('mcp')
+      return `${DEFAULT_SERVERS[name] ? 'Turned off' : 'Deleted'} the MCP server ${name}.`
+    }
+    if (action !== 'save') return 'error: action must be help, list, show, save or delete'
+    let cfg = config
+    if (typeof cfg === 'string') {
+      try {
+        cfg = JSON.parse(cfg)
+      } catch {
+        return 'error: config must be a JSON object like {"command": "npx", "args": ["-y", "some-mcp"]}'
+      }
+    }
+    if (cfg?.mcpServers) cfg = cfg.mcpServers[name] ?? Object.values(cfg.mcpServers)[0] // pasted a whole mcp.json
+    else if (cfg && !cfg.command && Object.keys(cfg).length === 1 && typeof Object.values(cfg)[0] === 'object') cfg = Object.values(cfg)[0] // { "name": { … } }
+    if (!cfg?.command && !(DEFAULT_SERVERS[name] && cfg)) return 'error: config needs "command" (and usually "args"), like {"command": "npx", "args": ["-y", "some-mcp"]}'
+    const clean = Object.fromEntries(['command', 'args', 'env', 'description', 'disabled'].filter((k) => cfg[k] !== undefined).map((k) => [k, cfg[k]]))
+    s.ui.print(`${c.bold(name)} ${c.faint(`→ ${tilde(file)}`)}\n  ${c.muted(JSON.stringify(clean))}`)
+    const ok = await s.ui.confirm(`Save the MCP server ${name}? HeartCode will run: ${clean.command ?? ''} ${(clean.args ?? []).join(' ')}`, 'command')
+    if (ok !== true) return declined(ok)
+    data.mcpServers[name] = { ...data.mcpServers[name], ...clean }
+    writeJson(file, data)
+    this.app.reload('mcp')
+    return `Saved the MCP server ${name} (${tilde(file)}). Its tools are available through the mcp tool now.`
+  }
+}
+
+const declined = (ok) => `The user declined.${typeof ok === 'string' ? ` User feedback: ${ok}` : ''}`
+const tilde = (f) => (process.env.HOME && f.startsWith(process.env.HOME) ? '~' + f.slice(process.env.HOME.length) : f)
+const mcpFiles = (root) => [{ scope: 'global', file: path.join(HOME, 'mcp.json') }, { scope: 'project', file: path.join(root, '.heartcode', 'mcp.json') }]

package/src/edit.js

@@ -0,0 +1,127 @@
+// Applying model edits, forgiving about the usual small-model mistakes.
+
+const lead = (l) => /^\s*/.exec(l)[0]
+const key = (l) => l.trim().replace(/\s+/g, ' ')
+
+function trimBlank(lines) {
+  let a = 0
+  let b = lines.length
+  while (a < b && !lines[a].trim()) a++
+  while (b > a && !lines[b - 1].trim()) b--
+  return lines.slice(a, b)
+}
+
+// Replace `search` with `replace` in `text`. Exact match first, then a
+// whitespace-insensitive line match (re-indenting the replacement).
+export function applyEdit(text, search, replace) {
+  if (!search.trim()) return { error: 'the SEARCH text is empty' }
+  const exact = text.split(search).length - 1
+  if (exact === 1) return { text: text.replace(search, () => replace) }
+  if (exact > 1) return { error: `the SEARCH text matches ${exact} places; include more surrounding lines so it matches only one` }
+
+  const lines = text.split('\n')
+  const s = trimBlank(search.split('\n'))
+  const sk = s.map(key)
+  const hits = []
+  for (let i = 0; i + s.length <= lines.length; i++) {
+    if (sk.every((k, j) => key(lines[i + j]) === k)) hits.push(i)
+  }
+  if (hits.length > 1) return { error: `the SEARCH text matches ${hits.length} places; include more surrounding lines so it matches only one` }
+  if (!hits.length) return { error: notFound(lines, sk) }
+
+  const i = hits[0]
+  lines.splice(i, s.length, ...reindent(s, trimBlank(replace.split('\n')), lines.slice(i, i + s.length)))
+  return { text: lines.join('\n') }
+}
+
+// The model's lines `repl` replace `orig` (as it saw them, `seen`). If the
+// model shifted the indentation, shift its replacement back.
+export function reindent(seen, repl, orig = seen) {
+  const j = seen.findIndex((l) => l.trim())
+  const k = repl.findIndex((l) => l.trim())
+  if (j < 0 || k < 0) return repl
+  const to = lead(orig[j])
+  const from = lead(repl[k])
+  if (from === to) return repl
+  return repl.map((l) => (l.trim() && l.startsWith(from) ? to + l.slice(from.length) : l))
+}
+
+function notFound(lines, sk) {
+  const words = new Set(sk.join(' ').split(/\W+/).filter((w) => w.length > 2))
+  let best = -1
+  let score = 0
+  lines.forEach((l, i) => {
+    const sc = l.split(/\W+/).filter((w) => words.has(w)).length
+    if (sc > score) [best, score] = [i, sc]
+  })
+  const msg = 'the SEARCH text was not found in the file'
+  if (best < 0) return msg
+  return `${msg}. The closest lines are around line ${best + 1}:\n${lines.slice(Math.max(0, best - 2), best + 3).join('\n')}`
+}
+
+// Parses git-conflict-style blocks. Accepts 5-9 marker chars, missing
+// SEARCH/REPLACE words and a missing final marker.
+export function parseBlocks(reply) {
+  const blocks = []
+  let cur = null
+  let part = null
+  for (const line of String(reply).replace(/\r\n/g, '\n').split('\n')) {
+    // Markers may carry any label ("<<<<<<< SEARCH", "<<<<<<< num.js", or none).
+    if (/^\s*<{5,9}(\s.*)?$/.test(line)) {
+      cur = { search: [], replace: [] }
+      part = 'search'
+    } else if (cur && part === 'search' && /^\s*={5,9}\s*$/.test(line)) {
+      part = 'replace'
+    } else if (cur && /^\s*>{5,9}(\s.*)?$/.test(line)) {
+      if (part === 'replace') blocks.push(join(cur))
+      cur = null
+    } else if (cur) {
+      cur[part].push(line)
+    }
+  }
+  if (cur && part === 'replace') blocks.push(join(cur))
+  return blocks
+}
+
+const join = (b) => ({ search: b.search.join('\n'), replace: b.replace.join('\n') })
+
+const isFence = (l) => /^\s*(`{3,}|~{3,})/.test(l)
+const firstReal = (lines) => (lines.find((l) => l.trim()) ?? '').trim()
+const numbered = (lines) => {
+  const real = lines.filter((l) => l.trim())
+  return real.length > 0 && real.every((l) => /^\s*\d+\s*\|/.test(l))
+}
+
+// The whole reply is meant to be code. Remove what models wrap around it:
+// a fence, a line of prose before it, notes after it, copied line numbers.
+export function cleanCode(reply, original = '') {
+  let lines = String(reply).replace(/\r\n/g, '\n').split('\n')
+  const orig = original.split('\n')
+  if (firstReal(lines) !== firstReal(orig)) {
+    const open = lines.findIndex(isFence)
+    if (open !== -1 && lines.slice(0, open).filter((l) => l.trim()).length <= 3) {
+      let close = -1
+      for (let i = lines.length - 1; i > open; i--) {
+        if (isFence(lines[i])) {
+          close = i
+          break
+        }
+      }
+      lines = lines.slice(open + 1, close === -1 ? undefined : close)
+    }
+  }
+  if (numbered(lines) && !numbered(orig)) lines = lines.map((l) => l.replace(/^\s*\d+\s*\| ?/, ''))
+  const t = lines.join('\n').replace(/^\s*\n/, '').replace(/\s+$/, '')
+  return !original || original.endsWith('\n') ? t + '\n' : t
+}
+
+const DEF = /\b(?:function|def|class|fn|func|interface|struct|enum)\s+([A-Za-z_]\w*)|\b(?:const|let|var)\s+([A-Za-z_]\w*)\s*=/g
+const defNames = (t) => new Set([...t.matchAll(DEF)].map((m) => m[1] ?? m[2]))
+
+// Definitions an edit deleted although the task never asked for it — the
+// typical small-model rewrite accident.
+export function lostNames(old, next, task) {
+  if (/\b(remove|delete|drop|rename|replace|rewrite|refactor|clean ?up|merge)\b/i.test(task)) return []
+  const now = defNames(next)
+  return [...defNames(old)].filter((n) => !now.has(n) && !task.includes(n))
+}

package/src/format.js

@@ -0,0 +1,74 @@
+// After HeartCode writes a file, the project's formatter runs on it, so its edits look like the rest
+// of the code (and the user's own format-on-save doesn't turn every edit into a second diff).
+// Only formatters the project already uses: prettier or biome from its node_modules, ruff or black
+// when its pyproject/ruff.toml sets them up, clang-format with a .clang-format; and the languages'
+// own (gofmt, rustfmt, dart format, zig fmt) when they're installed.
+// ~/.heart/format.json or .heartcode/format.json (wins) change it, by file pattern:
+//   { "*.py": "black -q $FILE", "*.md": false }   (false: never for those files)
+// The settings page (General → Features) turns it all off.
+import fs from 'node:fs'
+import path from 'node:path'
+import { HOME, readJson } from './config.js'
+import { runCommand } from './tools.js'
+import { log } from './log.js'
+
+const has = (root, f) => fs.existsSync(path.join(root, f))
+const read = (root, f) => {
+  try {
+    return fs.readFileSync(path.join(root, f), 'utf8')
+  } catch {
+    return ''
+  }
+}
+const onPath = (cmd) => (process.env.PATH ?? '').split(path.delimiter).some((d) => d && fs.existsSync(path.join(d, cmd)))
+const local = (root, cmd) => (has(root, `node_modules/.bin/${cmd}`) ? path.join(root, 'node_modules/.bin', cmd) : null)
+const q = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`
+
+// [file pattern, (root) → the command (the file's path is added at the end), or null]
+const BUILTIN = [
+  [/\.(m?[jt]sx?|cjs|cts|json|jsonc|css|scss|less|html|vue|svelte|astro|graphql|md|mdx|ya?ml)$/, (root) => {
+    const biome = local(root, 'biome')
+    if (biome && (has(root, 'biome.json') || has(root, 'biome.jsonc'))) return `${q(biome)} format --write`
+    const prettier = local(root, 'prettier')
+    return prettier && `${q(prettier)} --write --log-level=warn`
+  }],
+  [/\.pyi?$/, (root) => {
+    const py = read(root, 'pyproject.toml')
+    if (onPath('ruff') && (has(root, 'ruff.toml') || has(root, '.ruff.toml') || /^\[tool\.ruff/m.test(py))) return 'ruff format -q'
+    return onPath('black') && /^\[tool\.black\]/m.test(py) ? 'black -q' : null
+  }],
+  [/\.go$/, () => onPath('gofmt') && 'gofmt -w'],
+  [/\.rs$/, () => onPath('rustfmt') && 'rustfmt --edition 2021'], // rustfmt.toml in the project still applies
+  [/\.dart$/, () => onPath('dart') && 'dart format -o write'],
+  [/\.zig$/, () => onPath('zig') && 'zig fmt'],
+  [/\.(c|cc|cpp|cxx|h|hh|hpp|m|mm)$/, (root) => onPath('clang-format') && has(root, '.clang-format') && 'clang-format -i'],
+]
+
+const glob = (pattern) => new RegExp(`^${pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.')}$`)
+
+// The command for a file ("…$FILE…" or one the path goes after), or null.
+export function formatterFor(root, rel) {
+  const own = { ...readJson(path.join(HOME, 'format.json'), {}), ...readJson(path.join(root, '.heartcode', 'format.json'), {}) }
+  const base = path.basename(rel)
+  for (const [pattern, cmd] of Object.entries(own)) {
+    if (glob(pattern).test(base) || glob(pattern).test(rel)) return cmd || null
+  }
+  for (const [re, pick] of BUILTIN) if (re.test(rel)) return pick(root) || null
+  return null
+}
+
+// Formats the file HeartCode just wrote. Returns its new text when the formatter changed it, else
+// null. A formatter that fails (a syntax error it can't parse) is left at that: the file stays as
+// written, and the language server or the model's next run says what's wrong.
+export async function formatFile(root, rel) {
+  const cmd = formatterFor(root, rel)
+  if (!cmd) return null
+  const abs = path.join(root, rel)
+  const before = fs.readFileSync(abs, 'utf8')
+  const line = cmd.includes('$FILE') ? cmd.replaceAll('$FILE', q(rel)) : `${cmd} ${q(rel)}`
+  const { code, output } = await runCommand(root, line, { timeout: 20_000 })
+  log('format', `${line} → exit ${code}`, code ? output.slice(0, 1000) : '')
+  if (code !== 0) return null
+  const after = fs.readFileSync(abs, 'utf8')
+  return after === before ? null : { text: after, by: cmd.split(/\s+/)[0].split('/').pop().replace(/'$/, '') }
+}