aihand 0.0.1 → 0.1.0

package/src/read/cli.ts

@@ -0,0 +1,650 @@
+#!/usr/bin/env node
+import type { Node } from 'web-tree-sitter'
+import type { Config, RepodexData } from './types.js'
+import { existsSync, readFileSync, watch, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { createJiti } from 'jiti'
+import pc from 'picocolors'
+import { Parser } from 'web-tree-sitter'
+import pkg from '../../package.json'
+import { getLang } from './compact.js'
+import { buildCallGraph } from './graph.js'
+import { ensureMarkers, injectAll, renderSections } from './inject.js'
+import { locate, parseInspPath, renderLocate } from './locate.js'
+import { buildPanel, fmtTransitions, formatPanel } from './panel.js'
+import { buildState, formatState } from './state.js'
+import { fetchRuntimeKnobs, joinPanel } from './seam.js'
+import {
+    computeOverviewTokens,
+    computePinnedSet,
+    computeSignaturesBudget,
+    estimateTokens,
+    formatOverview,
+    selectFullBlocks,
+    selectSignatureBlocks,
+} from './pipeline.js'
+import { buildBlocks, buildClassifier, formatStarredTree, formatTree, formatXml } from './render.js'
+import { scan } from './scan.js'
+import { scanSecrets } from './security.js'
+import { allocate, buildImportGraph, computeCentrality, computeRecency, expandByBudget } from './signals.js'
+import { configTemplate, DEFAULT_CONFIG } from './types.js'
+import { CONFIG_PATH, isTsFile, loadConfig } from './config.js'
+
+// aihand fusion: argv is injected by the unified router (src/cli.ts) after it
+// strips the leading `read`/`refactor` segment. Falls back to process.argv when
+// this module is run directly (dev: `tsx read/cli.ts`).
+let args = process.argv.slice(2)
+
+const ESC = String.fromCharCode(27)
+// Visible length: skip ANSI color codes (ESC [ digits m).
+function visibleLen(s: string): number {
+    let n = 0
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] === ESC && s[i + 1] === '[') {
+            i += 2
+            while (i < s.length && s[i] >= '0' && s[i] <= '9') i++
+            // i now at 'm' (or wherever the run ended); loop's i++ skips it
+            continue
+        }
+        n++
+    }
+    return n
+}
+function pad(s: string, len: number): string {
+    return s + ' '.repeat(Math.max(0, len - visibleLen(s)))
+}
+
+// A watch root is a file (not a dir) if its last path segment contains a dot.
+const looksLikeFile = (root: string) => !root.endsWith('/') && (root.split('/').pop() ?? '').includes('.')
+
+const SELF_PATH = fileURLToPath(import.meta.url)
+// Running from src/ (tsx) vs dist/ (compiled): mark source runs so logs reveal which code is live.
+const VERSION = `v${pkg.version}${SELF_PATH.includes('/src/') ? '+src' : ''}`
+const BANNER = `${pc.bold(pc.magenta('aihand'))} ${pc.dim(VERSION)}`
+
+/** Walk up from cwd until finding aihand.config.ts; chdir there so all paths resolve correctly */
+function cdToRoot(): void {
+    let dir = process.cwd()
+    while (true) {
+        if (existsSync(join(dir, CONFIG_PATH))) {
+            if (dir !== process.cwd())
+                process.chdir(dir)
+            return
+        }
+        const parent = dirname(dir)
+        if (parent === dir)
+            return // filesystem root, no config found
+        dir = parent
+    }
+}
+
+async function initConfig(): Promise<string[]> {
+    console.log(`\n${BANNER} ${pc.dim('first run setup')}`)
+
+    // Detect existing AI context files; fall back to creating CLAUDE.md if none found
+    const ALL_TARGETS = ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md', '.cursorrules', '.github/copilot-instructions.md', '.windsurfrules']
+    const existing = ALL_TARGETS.filter(f => existsSync(f))
+    const targets = existing.length ? existing : ['CLAUDE.md']
+
+    const rows: Row[] = []
+    for (const file of targets) {
+        const result = ensureMarkers(file)
+        const meta = result === 'created' ? 'created with markers' : result === 'marked' ? 'markers added' : 'already has markers'
+        rows.push({ file, meta })
+    }
+    printTable(rows)
+
+    // Write config
+    const body = configTemplate()
+    writeFileSync(CONFIG_PATH, `import { defineConfig } from 'aihand'\n\nexport default defineConfig({\n${body}\n})\n`)
+    console.log(`  ${pc.green('✓')} Created ${CONFIG_PATH}`)
+
+    await bindVitePlugin()
+
+    // Set expectations before the first inject糊脸: what's about to land, who it's for, how to undo/shrink.
+    const list = targets.map(f => pc.cyan(f)).join(', ')
+    console.log(`
+  ${pc.bold('About to inject a codemap')} into ${list}
+  ${pc.dim('— a compact repo index for your AI assistant, not for you to read.')}
+
+  ${pc.dim('It lives between')} ${pc.yellow('<!-- AIDEV:START -->')} ${pc.dim('…')} ${pc.yellow('END')} ${pc.dim('markers — safe to delete anytime; it regenerates.')}
+  ${pc.dim('Too big? Lower')} ${pc.cyan('maxTokens')} ${pc.dim('in')} ${pc.cyan(CONFIG_PATH)}${pc.dim(', or set')} ${pc.cyan('injectDetailLevel: \'tree\'')} ${pc.dim('for names only.')}
+`)
+
+    return targets
+}
+
+// Auto-wire the plugin into vite.config by parsing it with tree-sitter (same AST stack aihand
+// already uses for signatures) — no regex, no string guessing. We locate the `plugins:` array and
+// the last import via real syntax nodes, then splice at their byte offsets. Anything we can't pin
+// down structurally falls back to printing a copy-paste snippet, because silently breaking a user's
+// build config is a far worse first impression than a manual step.
+async function bindVitePlugin(): Promise<void> {
+    const snippet = `${pc.dim('Add to your')} ${pc.cyan('vite.config')}${pc.dim(':')}
+    ${pc.cyan('import { aihand } from \'aihand/vite\'')}
+    ${pc.dim('// then inside plugins: [ ... ]')}
+    ${pc.cyan('aihand(),')} ${pc.dim('// apply: \'serve\' built in — no isServe guard needed')}`
+    const fail = (cfg: string) => console.log(`  ${pc.yellow('!')} couldn't auto-wire ${cfg}.\n  ${snippet}\n`)
+
+    const cfg = ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs'].find(existsSync)
+    if (!cfg)
+        return // not a vite project — nothing to bind
+
+    const src = readFileSync(cfg, 'utf-8')
+    if (src.includes('aihand')) {
+        console.log(`  ${pc.green('✓')} vite plugin already wired in ${cfg}`)
+        return
+    }
+
+    await Parser.init()
+    const parser = new Parser()
+    const lang = await getLang(cfg.slice(cfg.lastIndexOf('.')))
+    if (!lang)
+        return fail(cfg)
+    parser.setLanguage(lang)
+    const tree = parser.parse(src)
+    if (!tree)
+        return fail(cfg)
+
+    // Walk the whole tree: remember the last import_statement, and the array that is the value of a
+    // `plugins:` pair. tree-sitter gives us exact byte offsets — no positional guessing.
+    let lastImportEnd = -1
+    let pluginsBracketEnd = -1
+    const visit = (node: Node) => {
+        if (node.type === 'import_statement')
+            lastImportEnd = node.endIndex
+        if (node.type === 'pair') {
+            const key = node.childForFieldName('key')
+            const value = node.childForFieldName('value')
+            if (key?.text === 'plugins' && value?.type === 'array')
+                pluginsBracketEnd = value.startIndex + 1 // just past the `[`
+        }
+        for (const child of node.children)
+            child && visit(child)
+    }
+    visit(tree.rootNode)
+
+    if (pluginsBracketEnd === -1 || lastImportEnd === -1 || lastImportEnd > pluginsBracketEnd)
+        return fail(cfg)
+
+    // Match the array's own indentation: copy the whitespace run that follows the `[`.
+    let indent = ''
+    for (let i = pluginsBracketEnd; src[i] === '\n' || src[i] === ' ' || src[i] === '\t'; i++)
+        indent = src[i] === '\n' ? '' : indent + src[i]
+
+    // Splice high offset first so the low one stays valid.
+    const withPlugin = `${src.slice(0, pluginsBracketEnd)}\n${indent}aihand(),${src.slice(pluginsBracketEnd)}`
+    const importLine = `\nimport { aihand } from 'aihand/vite'`
+    const wired = `${withPlugin.slice(0, lastImportEnd)}${importLine}${withPlugin.slice(lastImportEnd)}`
+    writeFileSync(cfg, wired)
+    console.log(`  ${pc.green('✓')} Wired vite plugin into ${cfg}`)
+}
+
+function fmtTokens(n: number): string {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`
+    if (n >= 1000)
+        return `${(n / 1000).toFixed(1)}K`
+    return String(n)
+}
+
+interface Row { file: string, info?: string, meta?: string }
+
+function printTable(rows: Row[]) {
+    const colFile = Math.max(...rows.map(r => r.file.length)) + 2
+    for (const r of rows) {
+        const file = pad(r.file, colFile)
+        const extra = r.info ? pc.dim(r.info) : r.meta ? pc.dim(r.meta) : ''
+        console.log(`  ${pc.green('✓')} ${file}${extra}`)
+    }
+}
+
+function readAll(paths: string[]): Map<string, string> {
+    const contents = new Map<string, string>()
+    for (const p of paths) {
+        try {
+            contents.set(p, readFileSync(p, 'utf-8'))
+        }
+        catch { /* skip unreadable files */ }
+    }
+    return contents
+}
+
+async function run(config: Config, opts: { quiet?: boolean } = {}): Promise<{ paths: string[], totalTokens: number, injected: number }> {
+    // --stdout: print the assembled codemap to stdout, never touch files (no markers, no inject,
+    // no decoration lines). After the map collapses to a pointer in CLAUDE.md, the full map is
+    // fetched on demand via this command — this is exactly what that pointer points at.
+    const toStdout = args.includes('--stdout')
+    const { quiet = toStdout } = opts
+    const perf = !quiet && args.includes('--perf')
+    const t0 = performance.now()
+    const mark = (label: string) => {
+        if (perf) {
+            const elapsed = (performance.now() - t0).toFixed(0)
+            console.log(pc.dim(`  [${elapsed}ms] ${label}`))
+        }
+    }
+    // D0: Ensure markers exist in inject targets
+    if (!toStdout) {
+        for (const target of config.read.injectTargetFiles)
+            ensureMarkers(target)
+    }
+    mark('ensureMarkers')
+
+    // D1: Scan
+    const paths = scan(config)
+    mark(`scan (${paths.length} files)`)
+    if (!quiet)
+        console.log(`${BANNER} ${pc.dim(`${paths.length} files`)}`)
+
+    // Read all files once
+    const contents = readAll(paths)
+    mark('readAll')
+
+    // D2+D3: Classify + Compress
+    // Extraction level: always compact by default (overview needs content even when
+    // display level is 'tree'). fileDetailLevel overrides per-glob.
+    const classifyExtract = buildClassifier(config.read.fileDetailLevel, 'compact')
+    // Display level: drives what shows up in signatures / full sections.
+    // Defaults to injectDetailLevel; fileDetailLevel overrides per-glob.
+    const classifyDisplay = buildClassifier(config.read.fileDetailLevel, config.read.injectDetailLevel)
+    const blocks = await buildBlocks(paths, config, undefined, classifyExtract, contents)
+    mark('buildBlocks (compress)')
+
+    // Split into root (overview) and src (signatures) blocks
+    const rootBlocks = blocks.filter(b => !b.path.includes('/'))
+    const srcBlocks = blocks.filter(b => b.path.includes('/'))
+
+    // D4: Format — tree (needed for budget calc before allocation)
+    // When a Signatures/Full section will list file paths, the tree drops filenames (skeleton
+    // mode) to avoid duplicating the same path set in two sections.
+    const hasSignatures = srcBlocks.some(b => classifyDisplay(b.path) !== 'tree')
+
+    // Control panel — 从代码涌现的控制论模型（旋钮 + 状态），复用已读 contents 不回盘。
+    // 先于 tree 算出来：它言及的文件 = 关键文件，倒灌进 tree 标 ★，从控制面投影自动涌现重要度。
+    const knobs = await buildPanel(paths, contents)
+    const panel = knobs.length ? formatPanel(knobs) : undefined
+    const panelTokens = panel ? estimateTokens(panel) : 0
+    mark(`panel (${knobs.length} knobs)`)
+
+    // 状态显示（输出端）：扫 store(返回类型带响应式 marker 的工厂)抽状态量全集——洗衣机面板的另一半。
+    const storeStates = await buildState(paths, config.runtime.storeMarker)
+    const stateFieldCount = storeStates.reduce((n, s) => n + s.fields.length, 0)
+    const state = storeStates.length ? formatState(storeStates) : undefined
+    const stateTokens = state ? estimateTokens(state) : 0
+    mark(`state (${stateFieldCount} fields)`)
+
+    // 关键文件 = 控制面言及的文件（旋钮 filePath ∪ store filePath）。
+    const starred = new Set<string>([...knobs.map(k => k.filePath), ...storeStates.map(s => s.filePath)])
+    const treeOpts = { skeletonOnly: hasSignatures, starred }
+    const activePaths = paths
+    // 有控制面 → tree 坍缩成「关键文件版图」：只显 ★ 文件 + 目录骨架，非★叶子折成 `… N more`。
+    // 全量物理布局是 AI 几乎不消费的噪音（找文件用 glob/grep），★ 才是入口。无控制面回落全量树。
+    const starredMode = starred.size > 0
+    let tree = starredMode
+        ? formatStarredTree(activePaths, starred)
+        : formatTree(activePaths, config.read.treeFoldThreshold, treeOpts)
+    let treeTokens = estimateTokens(tree)
+    mark('formatTree')
+
+    // Allocation result — used by formatXml to filter by level
+    let allocLevels: Map<string, import('./types.js').FileDetailLevel> | undefined
+
+    // Overview tokens — computed once, used in budget + display
+    const overviewTokens = computeOverviewTokens(rootBlocks)
+
+    // D3.5: Smart allocation (only when maxTokens is set)
+    if (config.read.maxTokens) {
+        const rootFileCount = paths.filter(p => !p.includes('/')).length
+        const sigBudget = computeSignaturesBudget(config.read.maxTokens, overviewTokens, rootFileCount)
+
+        const filePaths = srcBlocks.map(b => b.path)
+        const recency = computeRecency(filePaths)
+        const importGraph = buildImportGraph(srcBlocks)
+        const centrality = computeCentrality(filePaths, importGraph)
+        const pinned = computePinnedSet(filePaths, config.read.fileDetailLevel)
+        const result = allocate(srcBlocks, recency, centrality, sigBudget, pinned, p => classifyDisplay(p) === 'tree')
+        allocLevels = result.levels
+        mark('allocate')
+
+        // Still over budget after compact→tree? Collapse low-signal subtrees top-down: expand
+        // hot paths until the budget runs out, fold the rest to `dir/ (N files, M dirs)`.
+        // Gate on the REAL rendered tree size, not allocate()'s per-file estimate: formatTree
+        // already folds (`.ext ×N`, single-child chains), so the actual tree is far smaller than
+        // fileCount×treeEntryTokens. Folding off a phantom deficit shrinks a tree that already fit.
+        let collapsedCount = 0
+        const sigTokens = estimateTokens(formatXml(selectSignatureBlocks(srcBlocks, classifyDisplay), result.levels))
+        // starred 树已是最小关键版图，不参与预算折叠（它本就远低于预算）。
+        if (!starredMode && treeTokens + sigTokens > sigBudget) {
+            const srcPaths = srcBlocks.map(b => b.path)
+            const { kept, collapsedDirs } = expandByBudget(srcPaths, result.scores, result.contentTokens, sigBudget, result.treeEntryTokens)
+            collapsedCount = collapsedDirs.size
+            tree = formatTree(activePaths, config.read.treeFoldThreshold, { ...treeOpts, kept, collapsedDirs })
+            treeTokens = estimateTokens(tree)
+            mark('expandByBudget')
+        }
+
+        if (result.downgraded > 0 || collapsedCount > 0) {
+            const parts: string[] = []
+            if (result.downgraded > 0)
+                parts.push(`${result.downgraded} downgraded`)
+            if (collapsedCount > 0)
+                parts.push(`${collapsedCount} dirs collapsed`)
+            if (!quiet)
+                console.log(`  ${pc.cyan('Smart allocation')}  ${pc.dim(`${fmtTokens(result.totalBefore)} → ${fmtTokens(result.totalAfter)} tokens  (${parts.join(', ')})`)}`)
+        }
+    }
+
+    // D4: Format sections
+    const overview = formatOverview(rootBlocks)
+    const signatureBlocks = selectSignatureBlocks(srcBlocks, classifyDisplay)
+    const signatures = formatXml(signatureBlocks, allocLevels)
+    const sigTokens = estimateTokens(signatures)
+    mark('formatXml (signatures)')
+
+    // Full blocks for the full section (and reused for security scan below).
+    const fullOnlyBlocks = selectFullBlocks(paths, contents, classifyDisplay)
+    const full = fullOnlyBlocks.length ? formatXml(fullOnlyBlocks) : undefined
+    // Security scan: all non-tree files regardless of display level (defense in depth).
+    const fullBlocks = paths
+        .filter(p => classifyDisplay(p) !== 'tree' && contents.get(p)?.trim())
+        .map(p => ({ path: p, level: 'full' as const, content: contents.get(p)! }))
+    mark('full blocks')
+
+    // Raw token count from file contents (no XML wrapper overhead)
+    let fullTokens = 0
+    for (const [, v] of contents) fullTokens += estimateTokens(v)
+
+    const data: RepodexData = {
+        overview,
+        ...(panel ? { panel } : {}),
+        ...(state ? { state } : {}),
+        tree,
+        signatures,
+        ...(full ? { full } : {}),
+    }
+
+    mark('done')
+
+    // Print section breakdown — match what actually gets injected
+    const rows: Row[] = [
+        { file: 'overview', info: `${fmtTokens(overviewTokens)} tokens` },
+    ]
+    let totalTokens = overviewTokens + treeTokens
+    if (panel) {
+        rows.push({ file: 'panel', info: `${knobs.length} knobs · ${fmtTokens(panelTokens)} tokens` })
+        totalTokens += panelTokens
+    }
+    if (state) {
+        rows.push({ file: 'state', info: `${stateFieldCount} fields · ${fmtTokens(stateTokens)} tokens` })
+        totalTokens += stateTokens
+    }
+    rows.push({ file: 'tree', info: `${fmtTokens(treeTokens)} tokens` })
+    if (signatures) {
+        rows.push({ file: 'signatures', info: `${fmtTokens(sigTokens)} tokens` })
+        totalTokens += sigTokens
+    }
+    if (full) {
+        const fullXmlTokens = estimateTokens(full)
+        rows.push({ file: 'full', info: `${fmtTokens(fullXmlTokens)} tokens` })
+        totalTokens += fullXmlTokens
+    }
+    if (!quiet) {
+        console.log(pc.bold('  Sections'))
+        printTable(rows)
+    }
+
+    // D5: Inject — or print to stdout. stdout forces injectCodemap:true (this command exists
+    // precisely to show the full map), going through the same renderSections as inject so
+    // "what you see == what was once injected".
+    let injected: string[] = []
+    if (toStdout) {
+        process.stdout.write(`${renderSections({ ...config, read: { ...config.read, injectCodemap: true } }, data)}\n`)
+    }
+    else {
+        injected = injectAll(config, data, config.read.injectTargetFiles)
+        if (injected.length && !quiet) {
+            console.log(pc.bold('\n  Injected'))
+            printTable(injected.map(f => ({ file: f, meta: `injectDetailLevel=${config.read.injectDetailLevel}` })))
+        }
+    }
+    mark('inject')
+
+    // Security check
+    const secrets = scanSecrets(fullBlocks)
+    if (secrets.length && !quiet) {
+        console.log(`\n  ${pc.bold(pc.red(`⚠ ${secrets.length} potential secret(s) in full output:`))}`)
+        for (const s of secrets)
+            console.log(`    ${pc.yellow(`${s.path}:${s.line}`)} ${pc.dim(s.pattern)}`)
+    }
+
+    // Token distribution by directory (verbose only)
+    if (perf) {
+        const allBlocks = [...rootBlocks, ...srcBlocks]
+        if (allBlocks.length > 3) {
+            const dirTokens = new Map<string, number>()
+            for (const b of allBlocks) {
+                const parts = b.path.split('/')
+                const dir = parts.length > 2 ? `${parts[0]}/${parts[1]}/` : parts.length > 1 ? `${parts[0]}/` : '(root)'
+                dirTokens.set(dir, (dirTokens.get(dir) ?? 0) + estimateTokens(b.content))
+            }
+            const topDirs = [...dirTokens.entries()].sort((a, b) => b[1] - a[1]).slice(0, 6)
+            console.log(pc.bold('\n  Token distribution'))
+            const colDir = Math.max(...topDirs.map(([d]) => d.length)) + 2
+            for (const [dir, tokens] of topDirs) {
+                const pct = totalTokens > 0 ? ((tokens / totalTokens) * 100).toFixed(0) : '0'
+                console.log(`    ${pad(dir, colDir)}${fmtTokens(tokens).padStart(6)}  ${pc.dim(`${pct}%`)}`)
+            }
+        }
+    }
+
+    // Summary
+    if (!quiet) {
+        const savedPct = fullTokens > 0 ? ((1 - totalTokens / fullTokens) * 100).toFixed(1) : '0.0'
+        console.log(`\n  ${pc.green(`${fmtTokens(totalTokens)} tokens injected`)} ${pc.dim(`— saved ${savedPct}% (${fmtTokens(fullTokens)} raw → ${fmtTokens(totalTokens)})`)}\n`)
+    }
+
+    return { paths, totalTokens, injected: injected.length }
+}
+
+async function main() {
+    // A directory with its own package.json but no aihand.config.ts is a fresh subproject:
+    // init here instead of climbing to an ancestor's config (which would index the wrong tree).
+    const initHere = existsSync('package.json') && !existsSync(CONFIG_PATH)
+    if (!initHere)
+        cdToRoot()
+
+    const useJson = args.includes('--json')
+
+    // Refactor: move-file <src> <dest> [--dry] — AST-level, rewrites all importers
+    if (args[0] === 'move-file') {
+        if (!args[1] || !args[2]) {
+            console.error('Usage: aihand refactor move-file <src> <dest> [--dry]')
+            process.exit(1)
+        }
+        const { moveFile } = await import('./refactor.js')
+        await moveFile(args[1], args[2], args.includes('--dry'))
+        return
+    }
+
+    // Refactor: rename <file> <oldName> <newName> [--dry] — type-checker-driven, all refs + alias imports
+    if (args[0] === 'rename') {
+        if (!args[1] || !args[2] || !args[3]) {
+            console.error('Usage: aihand refactor rename <file> <oldName> <newName> [--dry]')
+            process.exit(1)
+        }
+        const { renameSymbol } = await import('./refactor.js')
+        await renameSymbol(args[1], args[2], args[3], args.includes('--dry'))
+        return
+    }
+
+    // Refactor: move-symbol <fromFile> <name> <toFile> [--dry] — carries decl + deps, rewrites importers
+    if (args[0] === 'move-symbol') {
+        if (!args[1] || !args[2] || !args[3]) {
+            console.error('Usage: aihand refactor move-symbol <fromFile> <name> <toFile> [--dry]')
+            process.exit(1)
+        }
+        const { moveSymbol } = await import('./refactor.js')
+        await moveSymbol(args[1], args[2], args[3], args.includes('--dry'))
+        return
+    }
+
+    // source <file:line> — 一体化反向态射:运行时坐标(file:line,或直接喂 /dom 的
+    // data-insp-path) → 静态符号上下文。symbolAtLine 取精确 uid,callers/callees 按 uid。
+    if (args[0] === 'source') {
+        const config = await loadConfig()
+        const paths = scan(config)
+        const tsFiles = paths.filter(isTsFile)
+        const graph = await buildCallGraph(tsFiles)
+        if (!args[1]) {
+            console.error('Usage: aihand read source <file:line>   (file:line 可直接是 /dom 的 data-insp-path)')
+            process.exit(1)
+        }
+        const { file, line } = parseInspPath(args[1])
+        if (!file || !Number.isFinite(line)) {
+            console.error(`Bad location: ${args[1]} — expected file:line (or data-insp-path)`)
+            process.exit(1)
+        }
+        const result = locate(graph, file, line)
+        if (!result) {
+            console.error(`No symbol covers ${file}:${line} (是否 scan 范围内的文件?行号是否在某符号区间内?)`)
+            process.exit(1)
+        }
+        console.log(renderLocate(result, useJson))
+        return
+    }
+
+    // tree — file-tree navigation map: "where files live / the layout". Pulled standalone instead
+    // of via --stdout's full map, so you don't drag 288 lines of panel+state just to glance at the
+    // file layout (kills the multi-layer routing).
+    if (args[0] === 'tree') {
+        const config = await loadConfig()
+        console.log(formatTree(scan(config), config.read.treeFoldThreshold))
+        return
+    }
+
+    // panel — 控制面：从代码涌现整个 App 的旋钮（系统控制论模型第一层）。
+    // --live[=port] 合缝：⋈ 运行时已渲染旋钮（label+file），每个旋钮标 ● live / ○ 未渲染。
+    if (args[0] === 'panel') {
+        const config = await loadConfig()
+        const staticKnobs = await buildPanel(scan(config))
+
+        const liveFlag = args.find(a => a === '--live' || a.startsWith('--live='))
+        let knobs: Array<typeof staticKnobs[number] & { live?: boolean }> = staticKnobs
+        let liveCount = 0
+        if (liveFlag) {
+            const port = Number(liveFlag.includes('=') ? liveFlag.split('=')[1] : 5173)
+            const runtime = await fetchRuntimeKnobs(port)
+            const joined = joinPanel(staticKnobs, runtime)
+            knobs = joined
+            liveCount = joined.filter(k => k.live).length
+        }
+
+        if (useJson) {
+            console.log(JSON.stringify(knobs, null, 2))
+            return
+        }
+        // 按文件分组打印，每个文件一段控制面。
+        const byFile = new Map<string, typeof knobs>()
+        for (const k of knobs) {
+            const arr = byFile.get(k.filePath) ?? []
+            arr.push(k)
+            byFile.set(k.filePath, arr)
+        }
+        const head = liveFlag
+            ? `控制面 — ${knobs.length} 个旋钮，${liveCount} 个此刻已渲染（● live），${byFile.size} 个文件\n`
+            : `控制面 — ${knobs.length} 个旋钮，${byFile.size} 个文件\n`
+        console.log(pc.bold(head))
+        for (const [file, ks] of byFile) {
+            console.log(pc.cyan(file))
+            for (const k of ks) {
+                const dot = !liveFlag ? '' : k.live ? `${pc.green('●')} ` : `${pc.dim('○')} `
+                const name = k.label ? `「${k.label}」` : pc.dim(`<${k.tag}>`)
+                console.log(`  ${dot}${name}  ${pc.dim(`${k.event} →`)} ${k.store}.{ ${fmtTransitions(k.transitions)} }  ${pc.dim(`@${k.line}`)}`)
+            }
+        }
+        return
+    }
+
+    const watchMode = args.includes('--watch') || args.includes('-w')
+
+    if (!existsSync(CONFIG_PATH)) {
+        await initConfig()
+    }
+
+    const config = await loadConfig()
+    const { paths: files, totalTokens: initialTokens } = await run(config)
+    let lastTokens = initialTokens
+
+    if (!watchMode)
+        return
+
+    // Parent guard: if the spawning dev server dies uncatchably (SIGKILL/crash),
+    // its cleanup never runs and we'd be orphaned. An orphan gets reparented (to
+    // launchd/init), so ppid changes from its launch value — detect that and self-exit.
+    const parentAtLaunch = process.ppid
+    setInterval(() => {
+        if (process.ppid !== parentAtLaunch)
+            process.exit(0) // reparented → original parent gone, nothing to serve
+    }, 2000).unref()
+
+    // Watch source dirs + root files (e.g. package.json, aihand.config.ts)
+    const watchRoots = new Set<string>()
+    for (const f of files) {
+        const seg = f.split('/')[0]
+        watchRoots.add(seg)
+    }
+    watchRoots.add(CONFIG_PATH)
+
+    // Ignore self-output: injecting into target files would otherwise retrigger watch → infinite loop.
+    const ignored = new Set(config.read.injectTargetFiles.map(f => f.split('/').pop()))
+
+    const timeFmt = new Intl.DateTimeFormat(undefined, { hour: 'numeric', minute: 'numeric', second: 'numeric' })
+    let timer: ReturnType<typeof setTimeout> | null = null
+    const changed = new Set<string>()
+    const onChange = (filename: string | Buffer | null, root: string, rootIsFile: boolean) => {
+        const fname = filename?.toString() ?? ''
+        const path = rootIsFile ? root : fname ? `${root}/${fname}` : root
+        if (ignored.has(path.split('/').pop()))
+            return
+        changed.add(path)
+        if (timer)
+            clearTimeout(timer)
+        timer = setTimeout(async () => {
+            const fresh = await loadConfig()
+            const t0 = performance.now()
+            const { totalTokens, injected } = await run(fresh, { quiet: true })
+            const list = [...changed]
+            changed.clear()
+            if (!injected)
+                return // nothing changed in the injected output — stay silent
+            const ms = (performance.now() - t0).toFixed(0)
+            const time = timeFmt.format(new Date())
+            const summary = list.join(', ')
+            const diff = totalTokens - lastTokens
+            lastTokens = totalTokens
+            const diffStr = diff === 0
+                ? pc.dim('±0')
+                : (diff > 0 ? pc.yellow : pc.cyan)(`${diff > 0 ? '+' : '-'}${fmtTokens(Math.abs(diff))}`)
+            console.log(`${pc.dim(time)} ${pc.dim(`[aihand ${VERSION}]`)} ${pc.green('update')} ${pc.dim(summary)} ${pc.dim(`${ms}ms`)} ${pc.dim('·')} ${pc.green(fmtTokens(totalTokens))} ${diffStr}`)
+        }, 300)
+    }
+
+    for (const root of watchRoots) {
+        if (!existsSync(root))
+            continue
+        const isFile = looksLikeFile(root)
+        watch(root, isFile ? {} : { recursive: true }, (_e, f) => onChange(f, root, isFile))
+    }
+
+    console.log(pc.dim(`  watching ${[...watchRoots].join(', ')}...\n`))
+}
+
+// Exported entry for the unified router (src/cli.ts). Named distinctly from the
+// internal injection-pipeline run() above.
+export async function runCli(argv: string[]) {
+    args = argv
+    await main()
+}