thincoder 0.8.2 → 0.8.4

package/src/tools/patch.mjs

@@ -13,11 +13,12 @@ import { existsSync } from "node:fs";
 import { join, relative, dirname } from "node:path";
 
 /**
- * 解析统一 diff（unified diff）：返回 [{ path, isNew, hunks: [{ ops: [{type:" "|"-"|"+", text}] }] }]
- * 按 @@ 头的行数计数消费 hunk 行——LLM 常把上下文空行剥成纯空行，靠计数而不是行首字符判断 hunk 边界
+ * Parse a unified diff: returns [{ path, isNew, hunks: [{ ops: [{type:" "|"-"|"+", text}] }] }]
+ * Consume hunk lines by the line counts in the @@ header — LLMs often strip context blank lines to pure empty lines,
+ * so we use counts rather than first characters to determine hunk boundaries
  */
 function parsePatch(patch) {
-  // 补丁文本常来自 CRLF 终端/模型输出，行尾 \r 会混进 hunk 内容导致上下文对不上，统一剥掉
+  // Patch text often comes from CRLF terminals/model output; trailing \r mixed into hunk content breaks context matching, strip uniformly
   const lines = patch.replace(/\r(?=\n|$)/g, "").split("\n")
   const files = []
   let cur = null
@@ -48,7 +49,7 @@ function parsePatch(patch) {
         if (i >= lines.length) throw new Error("Malformed patch: hunk truncated (line counts in @@ header not satisfied)")
         const hl = lines[i]
         if (hl.startsWith("\\")) { i++; continue } // ""
-        const tag = hl === "" ? " " : hl[0] // 纯空行按上下文行宽容处理
+        const tag = hl === "" ? " " : hl[0] // pure blank line: treat leniently as context line
         const text = hl === "" ? "" : hl.slice(1)
         if (tag === " ") { hunk.ops.push({ type: " ", text }); oldNeed--; newNeed-- }
         else if (tag === "-") { hunk.ops.push({ type: "-", text }); oldNeed-- }
@@ -59,13 +60,13 @@ function parsePatch(patch) {
       cur.hunks.push(hunk)
       continue
     }
-    i++ // diff --git / index / 空行等元信息跳过
+    i++ // skip diff --git / index / blank lines and other metadata
   }
   if (files.length === 0) throw new Error("No file changes found in patch (need --- / +++ headers)")
   return files
 }
 
-/** 在内存行数组上按序应用 hunks；任何一步失败抛错（调用方保证不落盘）。比较时忽略行尾 \r，上下文行保留原始字节 */
+/** Apply hunks sequentially onto an in-memory line array; any failure throws (caller guarantees nothing is written to disk). Ignores trailing \r when comparing; context lines retain original bytes */
 function applyHunks(fileLines, hunks, eol, path) {
   const cr = eol === "\r\n" ? "\r" : ""
   for (let h = 0; h < hunks.length; h++) {
@@ -88,7 +89,7 @@ function applyHunks(fileLines, hunks, eol, path) {
     const out = []
     let src = pos
     for (const op of hunks[h].ops) {
-      if (op.type === " ") out.push(fileLines[src++]) // 上下文保留原始行（行尾/空白原样）
+      if (op.type === " ") out.push(fileLines[src++]) // preserve original context line (trailing whitespace as-is)
       else if (op.type === "-") src++
       else out.push(op.text + cr)
     }
@@ -107,13 +108,13 @@ export const applyPatchTool = {
     required: ["patch"],
   },
   readonly: false,
-  /** 供 agent 层追踪触碰文件（多路径，替代单 path 参数） */
+  /** For the agent layer to track touched files (multi-path, replaces single path parameter) */
   touchedPaths(args) {
     try { return parsePatch(args.patch ?? "").map((f) => f.path) } catch { return [] }
   },
   async execute(args, ctx) {
     const files = parsePatch(args.patch ?? "")
-    // 先全部读入内存试算：任何一个 hunk 不上就整体抛错，不写半个补丁（原子性）
+    // Read all into memory first for trial: if any hunk fails, abort entirely — never write a partial patch (atomicity)
     const planned = []
     for (const f of files) {
       const abs = resolveInCwd(ctx, f.path)
@@ -129,7 +130,7 @@ export const applyPatchTool = {
         planned.push({ abs, path: f.path, content: lines.join("\n"), isNew: false })
       }
     }
-    // 多文件写：先全部写 .tmp，全部成功后再 rename——任一写失败清理已写的 .tmp 不影响已落盘的文件
+    // Multi-file write: write all to .tmp first, rename only after all succeed — failure cleans up written .tmp without affecting committed files
     const { rename, unlink } = await import("node:fs/promises")
     const written = []
     try {
@@ -142,17 +143,18 @@ export const applyPatchTool = {
         await rename(p.abs + ".thincoder-tmp", p.abs)
       }
     } catch (renameError) {
-      // rename 阶段失败：清理残留 .tmp 文件
+      // rename phase failed: clean up leftover .tmp files
       for (const abs of written) {
         try { await unlink(abs + ".thincoder-tmp") } catch {}
       }
       throw renameError
     }
     const summary = planned.map((p) => `  ${p.isNew ? "created " : "modified"} ${p.path}`).join("\n")
-    const syntaxResults = planned.map((p) => {
-      const r = autoSyntaxCheck(p.abs)
+    const syntaxChecks = await Promise.all(planned.map(async (p) => {
+      const r = await autoSyntaxCheck(p.abs)
       return r ? `${p.path}:${r.replace("Syntax: ", "")}` : ""
-    }).filter(Boolean).join("\n")
+    }))
+    const syntaxResults = syntaxChecks.filter(Boolean).join("\n")
     return `Applied patch to ${planned.length} file(s):\n${summary}${syntaxResults ? "\n\nSyntax checks:\n" + syntaxResults : ""}`
   },
 }
@@ -181,7 +183,7 @@ export const syntaxCheckTool = {
       })
       return `Syntax OK: ${args.path}`
     } catch (e) {
-      // node --check 把错误写到 stderr
+      // node --check writes errors to stderr
       const msg = (e.stderr || e.stdout || e.message || "").trim()
       return `Syntax error in ${args.path}:\n${msg || "(unknown)"}`
     }
@@ -207,15 +209,15 @@ export const deleteTool = {
     if (!existsSync(abs)) throw new Error(`File not found: ${args.path}`)
     const s = await stat(abs)
     if (s.isDirectory()) throw new Error(`"${args.path}" is a directory — use bash to remove directories`)
-    // git 跟踪文件拒绝直接删除（安全网）；未跟踪的放行
-    // 用解析后的相对路径（统一正斜杠），防反斜杠/非常规路径绕过 ls-files 匹配
+    // git-tracked files: refuse direct deletion (safety net); untracked: allow
+    // Use resolved relative path (normalized forward slashes) to prevent backslash/unusual paths from bypassing ls-files matching
     const rel = relative(ctx.cwd, abs).replace(/\\/g, "/")
     let tracked = false
     try {
       execFileSync("git", ["ls-files", "--error-unmatch", "--", rel], { cwd: ctx.cwd, stdio: "ignore" })
       tracked = true
     } catch {
-      // 未跟踪 / 非 git 仓库
+      // untracked / non-git repo
     }
     if (tracked && !args.force) throw new Error(`"${args.path}" is git-tracked. Set force=true to delete anyway.`)
     await unlink(abs)

package/src/tools/repomap-parse.mjs

@@ -1,14 +1,14 @@
 /**
- * repomap-parse.mjs — 仓库依赖图解析（零依赖，纯 regex）
- * 从 code_chunks 取已知文件列表，实时解析每个文件的 import/export 关系，
- * 构建正向依赖图 + 反向引用图。被 repomap.mjs 的 buildSummary / buildOutline 共用。
+ * repomap-parse.mjs — repo dependency graph parser (zero dependencies, pure regex)
+ * Gets known file list from code_chunks, parses each file's import/export relationships in real time,
+ * builds forward dependency graph + reverse reference graph. Shared by repomap.mjs's buildSummary / buildOutline.
  */
 import { readFileSync, existsSync } from "node:fs"
 import { join } from "node:path"
 
 /**
- * 扫描全量文件，构建正向依赖图 + 反向引用图。
- * 返回 { deps, importers, fileCount } 供 buildOutline / buildSummary 共用。
+ * Scan all files, build forward dependency graph + reverse reference graph.
+ * Returns { deps, importers, fileCount } shared by buildOutline / buildSummary.
  */
 export function buildDepGraph(db, cwd) {
   const allFiles = db.prepare(`SELECT DISTINCT path FROM code_chunks ORDER BY path`).all().map((r) => r.path)
@@ -34,7 +34,7 @@ export function buildDepGraph(db, cwd) {
       exports = parseExports(lines, ext)
     }
 
-    // 把 import 路径解析成相对路径（处理 ./ ../）
+    // Resolve import paths to relative paths (handle ./ ../)
     const resolved = []
     for (let imp of imports) {
       if (imp.startsWith("./")) imp = imp.slice(2)
@@ -62,17 +62,17 @@ export function buildDepGraph(db, cwd) {
   return { deps, importers, fileCount: allFiles.length }
 }
 
-// ---------------------------------------------------------- 内部实现
+// ---------------------------------------------------------- internal implementation
 
 function normalizeExt(p) {
   return p.replace(/\.(m?js|jsx|tsx?)$/i, "")
 }
 
-/** 提取 JS/TS 文件的 import 路径（去掉 .ts/.js/.mjs 后缀统一） */
+/** Extract JS/TS file import paths (normalize by stripping .ts/.js/.mjs suffixes) */
 function parseImports(lines, ext) {
   const imports = []
   const text = lines.join("\n")
-  // 普通 import
+  // standard import
   const re = /import\s+(?:{[^}]*}|\*\s+as\s+\w+|\w+\s*,?\s*(?:{[^}]*})?)\s*from\s*['"]([^'"]+)['"]|import\s+['"]([^'"]+)['"]/g
   let m
   while ((m = re.exec(text))) {
@@ -90,7 +90,7 @@ function parseImports(lines, ext) {
   return [...new Set(imports)]
 }
 
-/** 提取 JS/TS 文件的 export 符号 */
+/** Extract JS/TS file export symbols */
 function parseExports(lines, ext) {
   const exports = []
   const text = lines.join("\n")
@@ -107,17 +107,17 @@ function parseExports(lines, ext) {
     if (name) exports.push(name)
     else if (!exports.some((e) => e === "default")) exports.push("default")
   }
-  // export { a, b as c } —— 优先取 as 后的导出名
+  // export { a, b as c } — prefer the "as" alias as the exported name
   const braceRe = /export\s*\{([^}]+)\}/g
   while ((m = braceRe.exec(text))) {
     for (const name of m[1].split(",")) {
       const parts = name.trim().split(/\s+/)
-      // "a as b" → b（导出名），"a" → a
+      // "a as b" → b (exported name), "a" → a
       const exported = parts.length >= 3 ? parts[2] : parts[0]
       if (exported) exports.push(exported)
     }
   }
-  // export const { a, b } = ...（解构导出）
+  // export const { a, b } = ... (destructured export)
   const destructRe = /export\s+(?:const|let|var)\s*\{([^}]+)\}\s*=/g
   while ((m = destructRe.exec(text))) {
     for (const name of m[1].split(",")) {
@@ -129,7 +129,7 @@ function parseExports(lines, ext) {
   return [...new Set(exports)]
 }
 
-/** 提取 Python 的 import 和顶层 def/class */
+/** Extract Python imports and top-level def/class */
 function parsePyOutline(lines) {
   const imports = []
   const symbols = []
@@ -155,9 +155,9 @@ function parsePyOutline(lines) {
 }
 
 /**
- * Python 相对导入 → 相对文件路径：
- * 前导 n 个点表示上溯 n-1 层（"."=当前包），模块点号转路径分隔符。
- * 非相对导入（不以 . 开头）或纯包导入（"from . import x"）返回 null。
+ * Python relative import → relative file path:
+ * Leading n dots mean go up n-1 levels ("." = current package), module dots become path separators.
+ * Non-relative imports (not starting with .) or bare package imports ("from . import x") return null.
  */
 function pyRelPath(mod) {
   if (!mod?.startsWith(".")) return null

package/src/tools/repomap.mjs

@@ -1,16 +1,16 @@
 /**
- * repomap.mjs — 仓库依赖大纲（零依赖，纯 regex）
- * 实时解析 import/export 关系，生成紧凑文本给 LLM 理解代码结构。
- * 不存索引——每次调用读文件解析，~50ms 完成。
+ * repomap.mjs — repo dependency outline (zero dependencies, pure regex)
+ * Real-time import/export parsing, generates compact text for LLMs to understand code structure.
+ * No index stored — reads and parses files on each call, ~50ms.
  */
 import { readFileSync, existsSync } from "node:fs"
 import { join } from "node:path"
 
-/** 提取 JS/TS 文件的 import 路径（去掉 .ts/.js/.mjs 后缀统一） */
+/** Extract JS/TS file import paths (normalize by stripping .ts/.js/.mjs suffixes) */
 function parseImports(lines, ext) {
   const imports = []
   const text = lines.join("\n")
-  // 普通 import
+  // standard import
   const re = /import\s+(?:{[^}]*}|\*\s+as\s+\w+|\w+\s*,?\s*(?:{[^}]*})?)\s*from\s*['"]([^'"]+)['"]|import\s+['"]([^'"]+)['"]/g
   let m
   while ((m = re.exec(text))) {
@@ -28,7 +28,7 @@ function parseImports(lines, ext) {
   return [...new Set(imports)]
 }
 
-/** 提取 JS/TS 文件的 export 符号 */
+/** Extract JS/TS file export symbols */
 function parseExports(lines, ext) {
   const exports = []
   const text = lines.join("\n")
@@ -45,17 +45,17 @@ function parseExports(lines, ext) {
     if (name) exports.push(name)
     else if (!exports.some((e) => e === "default")) exports.push("default")
   }
-  // export { a, b as c } —— 优先取 as 后的导出名
+  // export { a, b as c } — prefer the "as" alias as the exported name
   const braceRe = /export\s*\{([^}]+)\}/g
   while ((m = braceRe.exec(text))) {
     for (const name of m[1].split(",")) {
       const parts = name.trim().split(/\s+/)
-      // "a as b" → b（导出名），"a" → a
+      // "a as b" → b (exported name), "a" → a
       const exported = parts.length >= 3 ? parts[2] : parts[0]
       if (exported) exports.push(exported)
     }
   }
-  // export const { a, b } = ...（解构导出）
+  // export const { a, b } = ... (destructured export)
   const destructRe = /export\s+(?:const|let|var)\s*\{([^}]+)\}\s*=/g
   while ((m = destructRe.exec(text))) {
     for (const name of m[1].split(",")) {
@@ -67,7 +67,7 @@ function parseExports(lines, ext) {
   return [...new Set(exports)]
 }
 
-/** 提取 Python 的 import 和顶层 def/class */
+/** Extract Python imports and top-level def/class */
 function parsePyOutline(lines) {
   const imports = []
   const symbols = []
@@ -93,9 +93,9 @@ function parsePyOutline(lines) {
 }
 
 /**
- * Python 相对导入 → 相对文件路径：
- * 前导 n 个点表示上溯 n-1 层（"."=当前包），模块点号转路径分隔符。
- * 非相对导入（不以 . 开头）或纯包导入（"from . import x"）返回 null。
+ * Python relative import → relative file path:
+ * Leading n dots mean go up n-1 levels ("." = current package), module dots become path separators.
+ * Non-relative imports (not starting with .) or bare package imports ("from . import x") return null.
  */
 function pyRelPath(mod) {
   if (!mod?.startsWith(".")) return null
@@ -110,8 +110,8 @@ function normalizeExt(p) {
 }
 
 /**
- * 内部：扫描全量文件，构建正向依赖图 + 反向引用图。
- * 返回 { deps, importers, fileCount } 供 buildOutline / buildSummary 共用。
+ * Internal: scan all files, build forward dependency graph + reverse reference graph.
+ * Returns { deps, importers, fileCount } shared by buildOutline / buildSummary.
  */
 function _buildDepGraph(db, cwd) {
   const allFiles = db.prepare(`SELECT DISTINCT path FROM code_chunks ORDER BY path`).all().map((r) => r.path)
@@ -137,7 +137,7 @@ function _buildDepGraph(db, cwd) {
       exports = parseExports(lines, ext)
     }
 
-    // 把 import 路径解析成相对路径（处理 ./ ../）
+    // Resolve import paths to relative paths (handle ./ ../)
     const resolved = []
     for (let imp of imports) {
       if (imp.startsWith("./")) imp = imp.slice(2)
@@ -166,12 +166,12 @@ function _buildDepGraph(db, cwd) {
 }
 
 /**
- * 生成紧凑架构摘要（替换旧的全量注入）。
- * 三层信息，每层信息密度递减：
- *  1. 目录级依赖（多目录项目才有意义，单目录跳过）
- *  2. 枢纽文件 Top-12（被 import 最多的文件——架构骨架）
- *  3. 入口文件（无人 import 的文件——启动/顶层入口）
- * 输出天然有界（~1000-2000 字符），不再需要 OUTLINE_INJECT_MAX 硬截断。
+ * Generate a compact architecture summary (replaces the old full-dump injection).
+ * Three layers, each with decreasing information density:
+ *  1. Directory-level dependencies (meaningful only for multi-directory projects, skipped for single-directory)
+ *  2. Hub files Top-12 (most-imported files — architecture skeleton)
+ *  3. Entry points (files with no importers — startup/top-level entry points)
+ * Output is naturally bounded (~1000-2000 chars), no more OUTLINE_INJECT_MAX hard truncation.
  */
 export function buildSummary(db, cwd) {
   const graph = _buildDepGraph(db, cwd)
@@ -181,7 +181,7 @@ export function buildSummary(db, cwd) {
   const out = []
   out.push(`${fileCount} source files indexed.`)
 
-  // 1) 目录级依赖
+  // 1) Directory-level dependencies
   const dirDeps = new Map() // dir → Set<imported-dir>
   const dirSet = new Set()
   for (const [rel, d] of deps) {
@@ -204,7 +204,7 @@ export function buildSummary(db, cwd) {
     }
   }
 
-  // 2) 枢纽文件 Top-12：按被 import 次数降序
+  // 2) Hub files Top-12: sorted by import count descending
   const HUB_LIMIT = 12
   const hubScores = []
   for (const [rel] of deps) {
@@ -227,7 +227,7 @@ export function buildSummary(db, cwd) {
     }
   }
 
-  // 3) 入口文件：无人 import 的（叶子/入口）
+  // 3) Entry points: files not imported by others (leaf/entry)
   const entries = []
   for (const [rel] of deps) {
     const key = rel.replace(/\.(m?js|jsx|tsx?)$/i, "")
@@ -247,7 +247,7 @@ export function buildSummary(db, cwd) {
   return out.join("\n")
 }
 
-/** 从 code_chunks 取已知文件列表（复用索引），按路径解析生成大纲文本 */
+/** Get known file list from code_chunks (reuse index), parse by path to generate outline text */
 export function buildOutline(db, cwd, focusPath) {
   const graph = _buildDepGraph(db, cwd)
   if (!graph) return "(no indexed source files; run codeSync or /reindex first)"
@@ -260,7 +260,7 @@ export function buildOutline(db, cwd, focusPath) {
     const d = deps.get(rel)
     if (!d) continue
     const parts = []
-    // imported by（匹配时去掉扩展名，因为 import 路径通常不含 .mjs/.js 后缀）
+    // imported by (strip extension when matching, since import paths usually don't include .mjs/.js suffix)
     const key = rel.replace(/\.(m?js|jsx|tsx?)$/i, "")
     const rev = importers.get(key)
     if (rev?.size) parts.push(`← imported by: ${[...rev].join(", ")}`)
@@ -281,8 +281,8 @@ export function buildOutline(db, cwd, focusPath) {
 }
 
 /**
- * 生成 repo_outline 工具（只读）。
- * 需要 memory.db（复用 code_chunks 文件列表）和 cwd。
+ * Build the repo_outline tool (read-only).
+ * Requires memory.db (reuses code_chunks file list) and cwd.
  */
 export function repoOutlineTool(db, cwd) {
   return {

package/src/tools/shared.mjs

@@ -1,9 +1,9 @@
 /**
- * tools/shared.mjs — 共享工具函数、常量、OpenAI schema 转换
- * 被 tools/file.mjs / system.mjs / web.mjs / git.mjs 导入
+ * tools/shared.mjs — shared tool utilities, constants, OpenAI schema conversion
+ * Imported by tools/file.mjs / system.mjs / web.mjs / git.mjs
  */
 
-import { spawn, execFileSync } from "node:child_process"
+import { spawn, execFileSync, execFile } from "node:child_process"
 import { readFileSync, existsSync, realpathSync } from "node:fs"
 import { dirname, join, resolve, relative, isAbsolute, sep } from "node:path"
 import { fileURLToPath } from "node:url"
@@ -13,11 +13,14 @@ export const DESC = (name) => readFileSync(join(__dirname, "..", "tools", `${nam
 
 export const MAX_READ_LINES = 2000
 export const MAX_OUTPUT_CHARS = 200_000
+
+const ENCODING_DETECT_MAX_TRIM = 3
+const SYNTAX_CHECK_TIMEOUT = 10000
 export const BASH_TIMEOUT_MS = 120_000
 export const MAX_RESPONSE_BODY_BYTES = 5_000_000
 export const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "build", ".turbo", "coverage"])
 
-/** 转成 OpenAI tools 参数格式 */
+/** Convert to OpenAI tools parameter format */
 export function toOpenAISchema(tool) {
   return {
     type: "function",
@@ -29,7 +32,7 @@ export function toOpenAISchema(tool) {
   }
 }
 
-/** 剥离 ANSI 转义序列 */
+/** Strip ANSI escape sequences */
 export function sanitizeOutput(s) {
   return s
     .replace(/\x1b\[[0-9;?]*[\x40-\x7E]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[()][0-9A-B]|\x1b[=>#][0-9]?/g, "")
@@ -37,12 +40,13 @@ export function sanitizeOutput(s) {
     .replace(/\r/g, "\n")
 }
 
+/** Truncate text to max chars, appending a truncation notice */
 export function truncate(text, max = MAX_OUTPUT_CHARS) {
   if (text.length <= max) return text
   return text.slice(0, max) + `\n[... truncated: ${text.length - max} chars omitted — redirect to a file if you need the full output]`
 }
 
-/** 限量读取响应体 */
+/** Read response body with a byte limit */
 export async function readBodyText(response, limit = MAX_RESPONSE_BODY_BYTES) {
   if (!response.body) return ""
   const reader = response.body.getReader()
@@ -59,7 +63,8 @@ export async function readBodyText(response, limit = MAX_RESPONSE_BODY_BYTES) {
   return new TextDecoder("utf-8").decode(Buffer.concat(chunks))
 }
 
-/** 流解码器：编码嗅探 ASCII→UTF-8→GBK */
+/** Streaming decoder: encoding sniffing ASCII→UTF-8→GBK.
+ *  Each call creates an independent decoder instance — must not be shared across parallel streams (internal decoder state accumulates). */
 export function makeDecoder() {
   let decoder = null
   let pending = Buffer.alloc(0)
@@ -68,7 +73,7 @@ export function makeDecoder() {
     if (!decoder) {
       const hasHighByte = pending.some((b) => b >= 0x80)
       if (!hasHighByte) { const s = pending.toString("ascii"); pending = Buffer.alloc(0); return s }
-      for (let trim = 0; trim <= 3 && !decoder; trim++) {
+      for (let trim = 0; trim <= ENCODING_DETECT_MAX_TRIM && !decoder; trim++) {
         try { new TextDecoder("utf-8", { fatal: true }).decode(pending.subarray(0, pending.length - trim)); decoder = new TextDecoder("utf-8") }
         catch { /* continue */ }
       }
@@ -80,7 +85,7 @@ export function makeDecoder() {
   }
 }
 
-/** 单文件 git diff，失败静默返回空。大 diff 超 maxBuffer 时截断而非吞掉 */
+/** Single-file git diff. Silently returns empty on failure. Large diffs that exceed maxBuffer are truncated rather than swallowed. */
 export function gitDiffOne(cwd, abs) {
   try {
     const diff = execFileSync("git", ["--no-pager", "diff", "--no-color", "--", abs], {
@@ -91,7 +96,7 @@ export function gitDiffOne(cwd, abs) {
     if (lines.length <= 200) return diff
     return lines.slice(0, 200).join("\n") + `\n... (${lines.length - 200} more diff lines)`
   } catch (e) {
-    // maxBuffer 溢出时 e.stdout 含已收集的部分；其他错误（非 git 仓库等）返回空
+    // maxBuffer overflow: e.stdout contains partial collected output; other errors (non-git repo etc.) return empty
     if (e.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" && e.stdout) {
       const lines = e.stdout.toString().split("\n")
       return lines.slice(0, 200).join("\n") + `\n... (diff too large, showing first 200 of more lines)`
@@ -100,19 +105,32 @@ export function gitDiffOne(cwd, abs) {
   }
 }
 
-/** 文件变更后自动语法检查 */
-export function autoSyntaxCheck(abs) {
+/** Auto syntax check after file modification */
+export async function autoSyntaxCheck(abs) {
   if (!/\.(m?js)$/i.test(abs)) return ""
   try {
-    execFileSync("node", ["--check", abs], { stdio: ["ignore", "pipe", "pipe"], timeout: 10000 })
+    await new Promise((resolve, reject) => {
+      const child = execFile("node", ["--check", abs], { timeout: SYNTAX_CHECK_TIMEOUT, stdio: ["ignore", "pipe", "pipe"] })
+      let stderr = ""
+      child.stderr.on("data", (d) => { stderr += d.toString() })
+      child.on("error", reject)
+      child.on("close", (code) => {
+        if (code === 0) resolve()
+        else {
+          const err = new Error(stderr.trim() || `node --check exited with code ${code}`)
+          err.stderr = stderr
+          reject(err)
+        }
+      })
+    })
     return "\nSyntax: OK"
   } catch (e) {
     const err = (e.stderr || e.stdout || e.message || "").toString().split("\n").slice(0, 3).join("\n")
-    return `\nSyntax: FAILED — ${err}`
+    return `\nSyntax: FAILED — ${err}\n(If this file was corrupted by a bad edit, recover it from a checkpoint: checkpoint action=list then action=rewind with the latest id.)`
   }
 }
 
-/** 逐级向上找真实路径 */
+/** Resolve realpath by walking up the directory tree */
 export function realpathNearest(abs) {
   let cur = abs
   const tail = []
@@ -127,11 +145,13 @@ export function realpathNearest(abs) {
 }
 
 const realCwdCache = new Map()
+/** Resolve cwd to realpath, cached */
 export function realCwd(cwd) {
   if (!realCwdCache.has(cwd)) realCwdCache.set(cwd, realpathNearest(resolve(cwd)))
   return realCwdCache.get(cwd)
 }
 
+/** Assert that a resolved path is inside cwd; throws on escape */
 export function assertInside(cwd, resolved, p) {
   const rel = relative(cwd, resolved)
   if (isAbsolute(rel) || rel === ".." || rel.startsWith(".." + sep)) {
@@ -139,6 +159,7 @@ export function assertInside(cwd, resolved, p) {
   }
 }
 
+/** Resolve a user-supplied path relative to cwd, asserting it stays within cwd */
 export function resolveInCwd(ctx, p) {
   const cwd = realCwd(ctx.cwd)
   const resolved = resolve(cwd, p)
@@ -148,25 +169,31 @@ export function resolveInCwd(ctx, p) {
   return resolved
 }
 
-/** 破坏性预检用的粗切分（也切 > >> <，使段内破坏性检测在重定向时仍生效） */
+/** Resolve a path relative to cwd without boundary check — use only when the user explicitly provides an external path */
+export function resolveExternal(ctx, p) {
+  const cwd = realCwd(ctx.cwd)
+  return resolve(cwd, p)
+}
+
+/** Coarse segmentation for destructive pre-check (also splits on > >> < so destructive detection still works through redirection) */
 export function shellSegments(command) {
   return command.split(/&&|\|\||>>|\$\(|[;|\n<>]|`|[(]/)
 }
 
-/** 检测 shell 输出/输入重定向（> >> < 后跟文件名）——引号内未排除，保守拦截 */
+/** Detect shell output/input redirection (> >> < followed by filename) — not excluded inside quotes, conservative block */
 export function hasFileRedirection(command) {
   return /(^|[\s;&|])>{1,2}\s*\S/.test(command) || /(^|[\s;&|])<\s*\S/.test(command)
 }
 
-/** 单命令段是否为破坏性非 git 命令（保守：宁可误拦） */
+/** Whether a single command segment is a destructive non-git command (conservative: prefer false positives) */
 export function isDestructiveCommand(seg) {
   const s = seg
-  // rm 同时带递归(-r/-R)与强制(-f)标志：-rf / -fr / -r -f / -Rf 等
+  // rm with both recursive (-r/-R) and force (-f) flags: -rf / -fr / -r -f / -Rf etc.
   if (/\brm\b/.test(s) && /\s-\S*r/i.test(s) && /\s-\S*f/i.test(s)) return true
   if (/\brmdir\b/i.test(s)) return true
   if (/\bdel\b/i.test(s) && /\/f\b/i.test(s)) return true
   if (/\brd\b/i.test(s) && /\/s\b/i.test(s)) return true
-  // format 作为命令调用（排除 --format= 之类的选项误报）
+  // format called as a command (exclude --format= option false positives)
   if (/\bformat\b\s+\S/i.test(s) && !/--format\b/i.test(s)) return true
   if (/\bshred\b/i.test(s)) return true
   if (/\bdd\b/.test(s) && /\bof=/i.test(s)) return true
@@ -176,7 +203,7 @@ export function isDestructiveCommand(seg) {
   return false
 }
 
-/** 单命令段是否销毁未提交改动 */
+/** Whether a single command segment destroys uncommitted changes */
 export function isDestructiveGitSegment(seg) {
   if (!/^\s*git\s/.test(seg)) return false
   if (/\scheckout\s+(?:--|\.(?:\s|$))/.test(seg)) return true
@@ -186,7 +213,7 @@ export function isDestructiveGitSegment(seg) {
   return false
 }
 
-/** cwd 是否在 git 仓库内 */
+/** Whether cwd is inside a git repository */
 export function insideGitRepo(cwd) {
   try {
     execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
@@ -196,7 +223,7 @@ export function insideGitRepo(cwd) {
   } catch { return false }
 }
 
-/** glob 转正则 */
+/** Convert glob pattern to regex */
 export function globToRegex(pattern) {
   const DS = "\u0001", DP = "\u0002"
   const escaped = pattern
@@ -208,7 +235,7 @@ export function globToRegex(pattern) {
   return new RegExp(`^${escaped}$`)
 }
 
-/** 剥 HTML 标签 */
+/** Strip HTML tags */
 export function stripTags(html) {
   return html
     .replace(/<[^>]+>/g, "")
@@ -223,7 +250,7 @@ export function stripTags(html) {
     .trim()
 }
 
-/** HTML → 粗文本：去脚本样式、块级标签换行、剥标签、解码实体、压缩空行 */
+/** HTML → plain text: strip scripts/styles, newline block tags, strip tags, decode entities, compress blank lines */
 export function htmlToText(html) {
   return html
     .replace(/<script[\s\S]*?<\/script>/gi, "")
@@ -239,18 +266,18 @@ export function htmlToText(html) {
     .replace(/&lt;/g, "<")
     .replace(/&gt;/g, ">")
     .replace(/&quot;/g, '"')
-    .replace(/&amp;/g, "&") // &amp; 必须最后解码，否则 &amp;lt; 会被二次解码成 <
+    .replace(/&amp;/g, "&") // &amp; must be decoded last, otherwise &amp;lt; gets double-decoded to <
     .replace(/[ \t]+/g, " ")
     .replace(/\n\s*\n\s*\n+/g, "\n\n")
     .trim()
 }
 
-/** 执行 git 命令。maxBuffer 10MB 防大 diff/log 溢出；溢出时返回截断的部分输出而非空。 */
+/** Execute a git command. maxBuffer 10MB prevents large diff/log overflow; on overflow, returns truncated partial output rather than empty. */
 export function runGit(cwd, cmdArgs) {
   try {
     return execFileSync("git", cmdArgs, { cwd, encoding: "utf8", maxBuffer: 10 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"] }).trim().replace(/\r/g, "")
   } catch (e) {
-    // ERR_CHILD_PROCESS_STDIO_MAXBUFFER 时 e.stdout 含部分输出，截取前 200 行返回
+    // ERR_CHILD_PROCESS_STDIO_MAXBUFFER: e.stdout contains partial output, return first 200 lines
     if (e.stdout) return String(e.stdout).trim().replace(/\r/g, "").split("\n").slice(0, 200).join("\n")
     return ""
   }