opencode-agent-skill 7.7.0

package/lib/learning-engine.mjs

@@ -0,0 +1,161 @@
+import { existsSync } from "node:fs"
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises"
+import { createHash } from "node:crypto"
+import path from "node:path"
+
+const LEARNING_DIR = ".ues-learning"
+const STATE_FILE = "LEARNINGS.json"
+
+function idFor(type, key) {
+  return createHash("sha256").update(type + ":" + key).digest("hex").slice(0, 16)
+}
+
+async function walkJson(dir, limit = 500) {
+  const files = []
+  async function visit(current) {
+    if (files.length >= limit) return
+    const entries = await readdir(current, { withFileTypes: true }).catch(() => [])
+    for (const entry of entries) {
+      if (files.length >= limit) break
+      const full = path.join(current, entry.name)
+      if (entry.isDirectory()) await visit(full)
+      else if (entry.isFile() && entry.name.endsWith(".json")) files.push(full)
+    }
+  }
+  await visit(dir)
+  return files
+}
+
+function proposal(type, key, title, evidence, recommendation) {
+  return { id: idFor(type, key), type, key, title, evidence, recommendation, status: "proposed" }
+}
+
+export async function analyzeEvalTraces(evalDir) {
+  const files = await walkJson(path.resolve(evalDir))
+  const results = []
+  for (const file of files) {
+    try {
+      const payload = JSON.parse(await readFile(file, "utf8"))
+      for (const item of payload.results || []) results.push({ ...item, source: file })
+    } catch {}
+  }
+
+  const counters = new Map()
+  const bump = (key, item) => {
+    const value = counters.get(key) || { count: 0, tasks: new Set(), modes: new Set() }
+    value.count += 1
+    if (item.task) value.tasks.add(item.task)
+    if (item.mode) value.modes.add(item.mode)
+    counters.set(key, value)
+  }
+
+  for (const item of results) {
+    if (item.timedOut) bump("hard-timeout", item)
+    if (item.idleTimedOut) bump("idle-timeout", item)
+    if (Number(item.agentExit) !== 0) bump("agent-exit", item)
+    if (Number(item.graderExit) !== 0) bump("grader-failure", item)
+    if (item.orchestration?.required && !item.orchestration?.valid) bump("orchestration-failure", item)
+    if ((item.telemetry?.parseErrors || 0) > 0) bump("telemetry-parse-errors", item)
+  }
+
+  const proposals = []
+  for (const [key, value] of counters) {
+    if (value.count < 1) continue
+    const details = {
+      count: value.count,
+      tasks: [...value.tasks].sort(),
+      modes: [...value.modes].sort(),
+      samples: results.length,
+    }
+    const recommendations = {
+      "hard-timeout": "Inspect task decomposition and model/runtime latency; shorten tasks or raise a justified hard timeout.",
+      "idle-timeout": "Inspect tool/session deadlocks and add progress-producing boundaries or recovery.",
+      "agent-exit": "Classify process/provider failures before retrying; avoid blind model escalation.",
+      "grader-failure": "Mine failing task contracts for missing domain guidance or context selection, then add a regression before changing skills.",
+      "orchestration-failure": "Strengthen durable workflow instructions/gates or runtime support; do not count direct patches as UES success.",
+      "telemetry-parse-errors": "Update telemetry parsing against the observed OpenCode event shape with a fixture-backed test.",
+    }
+    proposals.push(proposal(
+      "eval-pattern",
+      key,
+      "Recurring evaluation pattern: " + key,
+      details,
+      recommendations[key] || "Review the repeated pattern and add a regression before promoting a reusable lesson.",
+    ))
+  }
+
+  return {
+    schemaVersion: 1,
+    analyzedAt: new Date().toISOString(),
+    files: files.length,
+    results: results.length,
+    proposals: proposals.sort((a, b) => b.evidence.count - a.evidence.count || a.key.localeCompare(b.key)),
+  }
+}
+
+export function learningFile(root) {
+  return path.join(path.resolve(root), LEARNING_DIR, STATE_FILE)
+}
+
+export async function readLearningState(root) {
+  const file = learningFile(root)
+  if (!existsSync(file)) return { schemaVersion: 1, updatedAt: null, proposals: [], accepted: [] }
+  try {
+    const parsed = JSON.parse(await readFile(file, "utf8"))
+    return {
+      schemaVersion: 1,
+      updatedAt: parsed.updatedAt || null,
+      proposals: Array.isArray(parsed.proposals) ? parsed.proposals : [],
+      accepted: Array.isArray(parsed.accepted) ? parsed.accepted : [],
+    }
+  } catch {
+    return { schemaVersion: 1, updatedAt: null, proposals: [], accepted: [], invalid: true }
+  }
+}
+
+export async function saveLearningAnalysis(root, analysis) {
+  const dir = path.dirname(learningFile(root))
+  await mkdir(dir, { recursive: true })
+  const current = await readLearningState(root)
+  const acceptedIDs = new Set(current.accepted.map((item) => item.id))
+  const proposals = analysis.proposals.filter((item) => !acceptedIDs.has(item.id))
+  const next = {
+    schemaVersion: 1,
+    updatedAt: new Date().toISOString(),
+    proposals,
+    accepted: current.accepted,
+  }
+  await writeFile(learningFile(root), JSON.stringify(next, null, 2) + "\n", "utf8")
+  return next
+}
+
+export async function acceptLearning(root, id) {
+  const current = await readLearningState(root)
+  const item = current.proposals.find((entry) => entry.id === id)
+  if (!item) throw new Error("unknown learning proposal: " + id)
+  const accepted = { ...item, status: "accepted", acceptedAt: new Date().toISOString() }
+  const next = {
+    schemaVersion: 1,
+    updatedAt: accepted.acceptedAt,
+    proposals: current.proposals.filter((entry) => entry.id !== id),
+    accepted: [...current.accepted.filter((entry) => entry.id !== id), accepted],
+  }
+  await mkdir(path.dirname(learningFile(root)), { recursive: true })
+  await writeFile(learningFile(root), JSON.stringify(next, null, 2) + "\n", "utf8")
+  return accepted
+}
+
+export async function relevantAcceptedLearnings(root, text, limit = 5) {
+  const state = await readLearningState(root)
+  const terms = new Set(String(text || "").toLowerCase().split(/[^a-z0-9_-]+/).filter((term) => term.length >= 4))
+  return state.accepted
+    .map((item) => {
+      const haystack = JSON.stringify(item).toLowerCase()
+      const score = [...terms].reduce((sum, term) => sum + (haystack.includes(term) ? 1 : 0), 0)
+      return { item, score }
+    })
+    .filter((entry) => entry.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map((entry) => entry.item)
+}

package/lib/model-config.mjs

@@ -0,0 +1,88 @@
+import { existsSync } from "node:fs"
+import { mkdir, readFile, writeFile } from "node:fs/promises"
+import path from "node:path"
+import { defaultModelPolicy, resolveModel } from "./model-policy.mjs"
+
+const TIERS = new Set(["light", "standard", "heavy"])
+
+function validModelID(value) {
+  return typeof value === "string" && /^[^\s/]+\/[^\s#]+(?:#[^\s]+)?$/.test(value)
+}
+
+function normalize(policy) {
+  const base = defaultModelPolicy()
+  const input = policy && typeof policy === "object" ? policy : {}
+  const tiers = { ...base.tiers }
+  for (const tier of TIERS) {
+    const value = input.tiers?.[tier]
+    if (value === null || validModelID(value)) tiers[tier] = value
+  }
+
+  const roleTiers = { ...base.roleTiers }
+  for (const [role, tier] of Object.entries(input.roleTiers || {})) {
+    if (TIERS.has(tier)) roleTiers[role] = tier
+  }
+
+  return {
+    schemaVersion: 1,
+    enabled: input.enabled === true,
+    maxEscalations: Number.isInteger(input.maxEscalations)
+      ? Math.max(0, Math.min(input.maxEscalations, 2))
+      : base.maxEscalations,
+    tiers,
+    roleTiers,
+  }
+}
+
+export function modelPolicyFile(configDir) {
+  return path.join(path.resolve(configDir), ".ues", "model-policy.json")
+}
+
+export async function readModelPolicy(configDir) {
+  const file = modelPolicyFile(configDir)
+  if (!existsSync(file)) return { ...defaultModelPolicy(), file }
+  try {
+    const parsed = JSON.parse(await readFile(file, "utf8"))
+    return { ...normalize(parsed), file }
+  } catch {
+    return { ...defaultModelPolicy(), file, invalid: true }
+  }
+}
+
+export async function writeModelPolicy(configDir, patch = {}) {
+  const current = await readModelPolicy(configDir)
+  const merged = normalize({
+    ...current,
+    ...patch,
+    tiers: { ...current.tiers, ...(patch.tiers || {}) },
+    roleTiers: { ...current.roleTiers, ...(patch.roleTiers || {}) },
+  })
+  const file = modelPolicyFile(configDir)
+  await mkdir(path.dirname(file), { recursive: true })
+  await writeFile(file, JSON.stringify(merged, null, 2) + "\n", "utf8")
+  return { ...merged, file }
+}
+
+export function validateModelID(value) {
+  return validModelID(value)
+}
+
+export function applyConfiguredModel(source, role, policy) {
+  if (!policy?.enabled) return source
+  const resolved = resolveModel(role, 1, policy)
+  if (!resolved.model) return source
+
+  const lines = String(source).split(/\r?\n/)
+  const start = lines.indexOf("---")
+  const end = lines.indexOf("---", start + 1)
+  if (start < 0 || end < 0) return source
+
+  const existing = lines.findIndex((line, index) => index > start && index < end && /^model:\s*/.test(line))
+  if (existing >= 0) {
+    lines[existing] = "model: " + resolved.model
+  } else {
+    const mode = lines.findIndex((line, index) => index > start && index < end && /^mode:\s*/.test(line))
+    lines.splice(mode >= 0 ? mode + 1 : start + 1, 0, "model: " + resolved.model)
+  }
+  return lines.join("\n")
+}

package/lib/model-policy.mjs

@@ -0,0 +1,71 @@
+const ROLE_TIERS = {
+  "codebase-mapper": "standard",
+  architect: "heavy",
+  "plan-checker": "heavy",
+  executor: "standard",
+  debugger: "standard",
+  researcher: "standard",
+  reviewer: "standard",
+  critic: "heavy",
+  verifier: "standard",
+  "integration-verifier": "heavy",
+}
+
+const ORDER = ["light", "standard", "heavy"]
+
+function tierIndex(value) {
+  const index = ORDER.indexOf(value)
+  return index < 0 ? 1 : index
+}
+
+export function defaultTier(role) {
+  return ROLE_TIERS[role] || "standard"
+}
+
+export function resolveTier(role, attempt = 1, options = {}) {
+  const base = options.baseTier || defaultTier(role)
+  const index = Math.max(0, ORDER.indexOf(base))
+  const maxEscalations = Number.isInteger(options.maxEscalations) ? Math.max(0, options.maxEscalations) : 2
+  const escalation = Math.min(Math.max(0, Number(attempt || 1) - 1), maxEscalations)
+  return ORDER[Math.min(ORDER.length - 1, index + escalation)]
+}
+
+export function resolveModel(role, attempt, config = {}) {
+  const tier = resolveTier(role, attempt, {
+    baseTier: config.roleTiers?.[role],
+    maxEscalations: config.maxEscalations,
+  })
+  const model = config.tiers?.[tier] || null
+  return { role, attempt: Number(attempt || 1), tier, model }
+}
+
+export function defaultModelPolicy() {
+  return {
+    schemaVersion: 1,
+    enabled: false,
+    maxEscalations: 2,
+    tiers: { light: null, standard: null, heavy: null },
+    roleTiers: { ...ROLE_TIERS },
+  }
+}
+
+
+export function resolveAdaptiveModel(role, attempt, taskPolicy = {}, config = {}) {
+  const configuredBase = config.roleTiers?.[role] || defaultTier(role)
+  const policyBase = taskPolicy.modelTier || configuredBase
+  const baseTier = ORDER[Math.max(tierIndex(configuredBase), tierIndex(policyBase))]
+  const resolved = resolveModel(role, attempt, {
+    ...config,
+    roleTiers: { ...(config.roleTiers || {}), [role]: baseTier },
+  })
+  return {
+    ...resolved,
+    policy: {
+      mode: taskPolicy.mode || null,
+      risk: taskPolicy.risk || null,
+      score: Number(taskPolicy.score || 0),
+      maxAttempts: Number(taskPolicy.maxAttempts || 0) || null,
+      contextBudget: Number(taskPolicy.contextBudget || 0) || null,
+    },
+  }
+}

package/lib/opencode-compat.mjs

@@ -0,0 +1,86 @@
+import { spawnSync } from "node:child_process"
+
+export function parseOpenCodeMajor(value) {
+  const match = String(value || "").match(/(\d+)\.(\d+)\.(\d+)/)
+  return match ? Number(match[1]) : null
+}
+
+export function detectOpenCodeMajor() {
+  const forced = process.env.UES_OPENCODE_MAJOR
+  if (forced && /^\d+$/.test(forced)) return Number(forced)
+
+  const candidates = process.platform === "win32"
+    ? [
+        () => spawnSync(process.env.ComSpec || "cmd.exe", ["/d", "/s", "/c", "opencode --version"], { encoding: "utf8" }),
+        () => spawnSync("opencode", ["--version"], { encoding: "utf8" }),
+      ]
+    : [() => spawnSync("opencode", ["--version"], { encoding: "utf8" })]
+
+  for (const run of candidates) {
+    const result = run()
+    if (result.status !== 0) continue
+    const major = parseOpenCodeMajor(result.stdout || result.stderr)
+    if (major !== null) return major
+  }
+  return 1
+}
+
+export function buildOpenCodeRunArgs({ major = 1, model, workspace, variant = null, prompt }) {
+  const args = ["run"]
+  if (Number(major) >= 2) args.push("--standalone")
+  args.push(
+    "--format",
+    "json",
+    "--auto",
+    "--agent",
+    "build",
+    "--model",
+    model,
+    "--dir",
+    workspace,
+  )
+  if (variant) args.push("--variant", variant)
+  args.push(prompt)
+  return args
+}
+
+export function adaptAgentForOpenCode(source, major) {
+  if (major < 2) return source
+
+  const lines = String(source).split(/\r?\n/)
+  const start = lines.findIndex((line) => /^permission:\s*$/.test(line))
+  if (start < 0) return source
+
+  const mappings = {
+    bash: "shell",
+    task: "subagent",
+    write: "edit",
+  }
+  const rules = []
+  const seen = new Set()
+  let end = start + 1
+
+  for (; end < lines.length; end += 1) {
+    const match = lines[end].match(/^\s{2}([A-Za-z0-9_-]+):\s*(allow|ask|deny)\s*$/)
+    if (!match) break
+    const action = mappings[match[1]] || match[1]
+    const effect = match[2]
+    const key = action + ":" + effect
+    if (seen.has(key)) continue
+    seen.add(key)
+    rules.push({ action, effect })
+  }
+
+  if (rules.length === 0) return source
+
+  const replacement = ["permissions:"]
+  for (const rule of rules) {
+    replacement.push(
+      "  - action: " + rule.action,
+      '    resource: "*"',
+      "    effect: " + rule.effect,
+    )
+  }
+
+  return [...lines.slice(0, start), ...replacement, ...lines.slice(end)].join("\n")
+}

package/lib/orchestrator-policy.mjs

@@ -0,0 +1,35 @@
+const HIGH_RISK = /(auth|security|permission|payment|migration|schema|database|production|deploy|public api|breaking|secret|credential)/i
+const LONG = /(whole repo|whole repository|entire repo|entire project|long[- ]running|multi[- ]file|cross[- ]module|resume|migration|refactor all)/i
+
+export function classifyEngineeringTask(text, facts = {}) {
+  const value = String(text || "")
+  let score = 0
+  if (value.length > 250) score += 1
+  if (value.length > 700) score += 1
+  if (HIGH_RISK.test(value)) score += 2
+  if (LONG.test(value)) score += 2
+  if (Number(facts.changedFiles || 0) > 5) score += 1
+  if (Number(facts.changedFiles || 0) > 12) score += 1
+  if (facts.hasMigration || facts.hasPublicContract) score += 2
+
+  const risk = HIGH_RISK.test(value) || facts.hasMigration || facts.hasPublicContract
+    ? "high"
+    : score >= 3 ? "medium" : "low"
+
+  const mode = score >= 4 ? "long-horizon" : score >= 2 ? "standard" : "inline"
+  const modelTier = risk === "high" || score >= 4 ? "heavy" : score >= 2 ? "standard" : "light"
+  const maxAttempts = risk === "high" ? 2 : 3
+  const contextBudget = mode === "long-horizon" ? 48_000 : mode === "standard" ? 32_000 : 16_000
+
+  return {
+    schemaVersion: 1,
+    score,
+    risk,
+    mode,
+    modelTier,
+    maxAttempts,
+    contextBudget,
+    requirePlanCheck: mode === "long-horizon" || risk === "high",
+    requireIntegrationVerification: mode !== "inline" || risk === "high",
+  }
+}

package/lib/process-runner.mjs

@@ -0,0 +1,117 @@
+import { spawn, spawnSync } from "node:child_process"
+
+function appendBounded(current, chunk, limit) {
+  const next = current + String(chunk || "")
+  if (next.length <= limit) return next
+  return next.slice(next.length - limit)
+}
+
+function killTree(child) {
+  if (!child?.pid) return
+  if (process.platform === "win32") {
+    spawnSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" })
+    return
+  }
+  try {
+    process.kill(-child.pid, "SIGTERM")
+  } catch {
+    try { child.kill("SIGTERM") } catch {}
+  }
+}
+
+export function runProcess(executable, args = [], options = {}) {
+  const startedAt = Date.now()
+  const heartbeatMs = Math.max(0, Number(options.heartbeatMs ?? 30_000))
+  const timeoutMs = Math.max(0, Number(options.timeoutMs ?? 0))
+  const idleTimeoutMs = Math.max(0, Number(options.idleTimeoutMs ?? 0))
+  const maxBuffer = Math.max(1024, Number(options.maxBuffer ?? 4 * 1024 * 1024))
+
+  return new Promise((resolve) => {
+    let stdout = ""
+    let stderr = ""
+    let lastOutputAt = Date.now()
+    let timedOut = false
+    let idleTimedOut = false
+    let aborted = false
+    let finished = false
+
+    const child = spawn(executable, args, {
+      cwd: options.cwd,
+      env: options.env,
+      windowsHide: true,
+      detached: process.platform !== "win32",
+      stdio: ["ignore", "pipe", "pipe"],
+    })
+
+    const cleanup = () => {
+      clearInterval(heartbeatTimer)
+      clearInterval(watchdogTimer)
+      if (options.signal) options.signal.removeEventListener("abort", onAbort)
+    }
+
+    const finish = (status, signal, spawnError = null) => {
+      if (finished) return
+      finished = true
+      cleanup()
+      resolve({
+        status: Number.isInteger(status) ? status : (spawnError || signal || timedOut || idleTimedOut || aborted) ? 1 : 0,
+        signal: signal || null,
+        stdout,
+        stderr: spawnError ? appendBounded(stderr, String(spawnError.message || spawnError), maxBuffer) : stderr,
+        durationMs: Date.now() - startedAt,
+        timedOut,
+        idleTimedOut,
+        aborted,
+      })
+    }
+
+    child.stdout?.on("data", (chunk) => {
+      lastOutputAt = Date.now()
+      stdout = appendBounded(stdout, chunk, maxBuffer)
+      options.onStdout?.(String(chunk))
+    })
+    child.stderr?.on("data", (chunk) => {
+      lastOutputAt = Date.now()
+      stderr = appendBounded(stderr, chunk, maxBuffer)
+      options.onStderr?.(String(chunk))
+    })
+
+    child.on("error", (error) => finish(1, null, error))
+    child.on("close", (code, signal) => finish(code ?? 1, signal))
+
+    const heartbeatTimer = heartbeatMs > 0
+      ? setInterval(() => {
+          options.onHeartbeat?.({
+            pid: child.pid,
+            elapsedMs: Date.now() - startedAt,
+            idleMs: Date.now() - lastOutputAt,
+          })
+        }, heartbeatMs)
+      : null
+
+    const watchdogTimer = (timeoutMs > 0 || idleTimeoutMs > 0)
+      ? setInterval(() => {
+          const now = Date.now()
+          if (timeoutMs > 0 && now - startedAt >= timeoutMs) {
+            timedOut = true
+            killTree(child)
+            return
+          }
+          if (idleTimeoutMs > 0 && now - lastOutputAt >= idleTimeoutMs) {
+            idleTimedOut = true
+            killTree(child)
+          }
+        }, 500)
+      : null
+
+    function onAbort() {
+      aborted = true
+      killTree(child)
+    }
+
+    if (options.signal) {
+      if (options.signal.aborted) onAbort()
+      else options.signal.addEventListener("abort", onAbort, { once: true })
+    }
+  })
+}

package/lib/repo-graph.mjs

@@ -0,0 +1,135 @@
+import { readFile, readdir, stat } from "node:fs/promises"
+import path from "node:path"
+
+const SKIP = new Set([
+  ".git", "node_modules", ".next", "dist", "build", "coverage", ".venv", "venv",
+  "Pods", "DerivedData", ".gradle", ".idea", ".cache", ".turbo", "target", "bin", "obj",
+  ".ues-work",
+])
+
+const SOURCE_EXTENSIONS = new Set([
+  ".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".py", ".java", ".kt", ".kts",
+  ".cs", ".go", ".rs", ".rb", ".php", ".vue", ".svelte",
+])
+
+async function walk(root, maxFiles = 2500, maxDepth = 8) {
+  const files = []
+  async function visit(dir, depth) {
+    if (depth > maxDepth || files.length >= maxFiles) return
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])
+    for (const entry of entries) {
+      if (files.length >= maxFiles) break
+      if (SKIP.has(entry.name)) continue
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) await visit(full, depth + 1)
+      else if (entry.isFile() && SOURCE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) files.push(full)
+    }
+  }
+  await visit(root, 0)
+  return files
+}
+
+function rel(root, file) {
+  return path.relative(root, file).replaceAll("\\", "/")
+}
+
+function importsFor(source, ext) {
+  const imports = []
+  const push = (value) => {
+    const clean = String(value || "").trim()
+    if (clean && !imports.includes(clean)) imports.push(clean)
+  }
+
+  if ([".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".vue", ".svelte"].includes(ext)) {
+    for (const match of source.matchAll(/\b(?:import|export)\s+(?:[^"'\n]+?\s+from\s+)?["']([^"']+)["']/g)) push(match[1])
+    for (const match of source.matchAll(/\brequire\(\s*["']([^"']+)["']\s*\)/g)) push(match[1])
+    for (const match of source.matchAll(/\bimport\(\s*["']([^"']+)["']\s*\)/g)) push(match[1])
+  } else if (ext === ".py") {
+    for (const match of source.matchAll(/^\s*from\s+([A-Za-z0-9_\.]+)\s+import\s+/gm)) push(match[1])
+    for (const match of source.matchAll(/^\s*import\s+([A-Za-z0-9_\.]+)/gm)) push(match[1])
+  } else if ([".java", ".kt", ".kts"].includes(ext)) {
+    for (const match of source.matchAll(/^\s*import\s+([A-Za-z0-9_.*]+)/gm)) push(match[1])
+  } else if (ext === ".cs") {
+    for (const match of source.matchAll(/^\s*using\s+([A-Za-z0-9_.]+)/gm)) push(match[1])
+  } else if (ext === ".go") {
+    for (const match of source.matchAll(/import\s+(?:\([^)]*?["']([^"']+)["']|["']([^"']+)["'])/gs)) push(match[1] || match[2])
+  } else if (ext === ".rs") {
+    for (const match of source.matchAll(/^\s*use\s+([^;]+);/gm)) push(match[1])
+  }
+  return imports
+}
+
+function resolveRelativeImport(root, importer, specifier, fileSet) {
+  if (!specifier.startsWith(".")) return null
+  const base = path.resolve(path.dirname(importer), specifier)
+  const candidates = [
+    base,
+    ...[...SOURCE_EXTENSIONS].map((ext) => base + ext),
+    ...[...SOURCE_EXTENSIONS].map((ext) => path.join(base, "index" + ext)),
+  ]
+  for (const candidate of candidates) {
+    const relative = rel(root, candidate)
+    if (fileSet.has(relative)) return relative
+  }
+  return null
+}
+
+export async function buildRepoGraph(root = process.cwd(), options = {}) {
+  root = path.resolve(root)
+  const maxFiles = options.maxFiles ?? 2500
+  const files = await walk(root, maxFiles, options.maxDepth ?? 8)
+  const fileSet = new Set(files.map((file) => rel(root, file)))
+  const nodes = []
+  const edges = []
+  const external = new Map()
+
+  for (const file of files) {
+    const info = await stat(file).catch(() => null)
+    if (!info || info.size > 768 * 1024) continue
+    const source = await readFile(file, "utf8").catch(() => "")
+    const relative = rel(root, file)
+    const ext = path.extname(file).toLowerCase()
+    const imports = importsFor(source, ext)
+    const local = []
+
+    for (const specifier of imports) {
+      const resolved = resolveRelativeImport(root, file, specifier, fileSet)
+      if (resolved) {
+        local.push(resolved)
+        edges.push({ from: relative, to: resolved, kind: "local-import" })
+      } else {
+        const parts = specifier.split("/")
+        const key = parts[0].startsWith("@") ? parts.slice(0, 2).join("/") : parts[0]
+        external.set(key, (external.get(key) || 0) + 1)
+      }
+    }
+
+    nodes.push({ path: relative, imports: imports.length, localImports: [...new Set(local)].sort() })
+  }
+
+  const incoming = new Map()
+  for (const edge of edges) incoming.set(edge.to, (incoming.get(edge.to) || 0) + 1)
+  const hotspots = nodes
+    .map((node) => ({
+      path: node.path,
+      incoming: incoming.get(node.path) || 0,
+      outgoing: node.localImports.length,
+      score: (incoming.get(node.path) || 0) + node.localImports.length,
+    }))
+    .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
+    .slice(0, 30)
+
+  return {
+    schemaVersion: 1,
+    root,
+    scannedFiles: files.length,
+    truncated: files.length >= maxFiles,
+    nodes,
+    edges,
+    hotspots,
+    externalImports: [...external.entries()]
+      .map(([name, count]) => ({ name, count }))
+      .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name))
+      .slice(0, 50),
+  }
+}