@thaut/claude-ide 0.0.0-stage → 1.0.0

package/server/config/agents.ts

@@ -0,0 +1,186 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { AgentFile, AgentInput } from "../../shared/config.ts";
+import { initInfo, invalidate } from "../cli-control.ts";
+import { ConfigError, configDir, writeFileAtomic } from "./paths.ts";
+
+/**
+ * Custom subagents (/agents): `~/.claude/agents/*.md` and `<project>/.claude/agents/*.md`,
+ * YAML frontmatter (name, description, tools, model, …) + the system prompt as body.
+ * Unknown frontmatter keys are kept verbatim.
+ */
+
+const KNOWN = ["name", "description", "tools", "model"] as const;
+
+export function agentsDir(scope: "user" | "project", root: string | null): string {
+  if (scope === "user") return path.join(configDir, "agents");
+  if (!root) throw new ConfigError(400, "项目级 agent 需要先选择项目");
+  return path.join(root, ".claude", "agents");
+}
+
+type Entry = { key: string; lines: string[] };
+
+/** Split frontmatter into top-level entries; an entry owns its indented continuation lines. */
+export function splitFrontmatter(text: string): { entries: Entry[] | null; body: string } {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(text);
+  if (!m) return { entries: null, body: text };
+  const entries: Entry[] = [];
+  for (const line of m[1].split(/\r?\n/)) {
+    const km = /^([A-Za-z0-9_-]+)\s*:/.exec(line);
+    if (km && !/^\s/.test(line)) entries.push({ key: km[1], lines: [line] });
+    else if (entries.length) entries[entries.length - 1].lines.push(line);
+    else entries.push({ key: "", lines: [line] });
+  }
+  return { entries, body: text.slice(m[0].length) };
+}
+
+function unquote(v: string): string {
+  const t = v.trim();
+  if (t.startsWith('"') && t.endsWith('"') && t.length >= 2) {
+    try {
+      return JSON.parse(t) as string;
+    } catch {
+      return t.slice(1, -1);
+    }
+  }
+  if (t.startsWith("'") && t.endsWith("'") && t.length >= 2) return t.slice(1, -1).replace(/''/g, "'");
+  return t;
+}
+
+/** Scalar value of an entry; handles `key: value`, block scalars (`|`, `>`) and `- item` lists. */
+function entryValue(e: Entry): string {
+  const first = e.lines[0].slice(e.lines[0].indexOf(":") + 1).trim();
+  const rest = e.lines.slice(1);
+  if (/^[|>][-+]?$/.test(first)) {
+    const lines = rest.map((l) => l.replace(/^\s{1,2}/, ""));
+    return (first.startsWith(">") ? lines.join(" ") : lines.join("\n")).trim();
+  }
+  const items = rest.map((l) => /^\s*-\s+(.*)$/.exec(l)?.[1]).filter((x): x is string => x !== undefined);
+  if (!first && items.length) return items.map(unquote).join(", ");
+  if (first.startsWith("[") && first.endsWith("]")) return first.slice(1, -1).split(",").map(unquote).filter(Boolean).join(", ");
+  return [first, ...rest.map((l) => l.trim())].filter(Boolean).map(unquote).join(" ");
+}
+
+/** YAML-safe scalar: plain when harmless, else a JSON (= YAML double-quoted) string. */
+function yamlScalar(v: string): string {
+  if (/^[\w./@()* ,+-]+$/.test(v) && !/^[-?:,[\]{}#&*!|>'"%@`]/.test(v) && !/:\s|\s#/.test(v) && v.trim() === v) return v;
+  return JSON.stringify(v);
+}
+
+export function parseAgent(text: string): Omit<AgentFile, "scope" | "file" | "path" | "mtime"> {
+  const { entries, body } = splitFrontmatter(text);
+  const get = (k: string) => {
+    const e = entries?.find((x) => x.key === k);
+    return e ? entryValue(e) : "";
+  };
+  const extra = (entries ?? [])
+    .filter((e) => !(KNOWN as readonly string[]).includes(e.key))
+    .flatMap((e) => e.lines)
+    .join("\n");
+  return { name: get("name"), description: get("description"), tools: get("tools"), model: get("model"), extra, prompt: body.replace(/^\r?\n/, "") };
+}
+
+export function serializeAgent(a: { name: string; description: string; tools: string; model: string; prompt: string }, original?: string): string {
+  const known: Record<string, string> = {
+    name: a.name.trim(),
+    description: a.description.trim(),
+    tools: a.tools
+      .split(",")
+      .map((t) => t.trim())
+      .filter(Boolean)
+      .join(", "),
+    model: a.model.trim(),
+  };
+  const prev = original ? splitFrontmatter(original).entries : null;
+  const out: string[] = [];
+  const written = new Set<string>();
+  // Keep the original key order and unknown keys; update or drop the known ones.
+  for (const e of prev ?? []) {
+    if ((KNOWN as readonly string[]).includes(e.key)) {
+      if (known[e.key]) out.push(`${e.key}: ${yamlScalar(known[e.key])}`);
+      written.add(e.key);
+    } else out.push(...e.lines);
+  }
+  for (const k of KNOWN) if (!written.has(k) && known[k]) out.push(`${k}: ${yamlScalar(known[k])}`);
+  const prompt = a.prompt.replace(/\s+$/, "");
+  return `---\n${out.join("\n")}\n---\n\n${prompt}\n`;
+}
+
+async function exists(p: string) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readAgentFile(scope: "user" | "project", file: string): Promise<AgentFile | null> {
+  try {
+    const st = await fs.stat(file);
+    if (!st.isFile()) return null;
+    return { scope, file: path.basename(file, ".md"), path: file, mtime: st.mtimeMs, ...parseAgent(await fs.readFile(file, "utf8")) };
+  } catch {
+    return null;
+  }
+}
+
+export async function listAgents(root: string | null) {
+  const agents: AgentFile[] = [];
+  for (const scope of root ? (["user", "project"] as const) : (["user"] as const)) {
+    const dir = agentsDir(scope, root);
+    let names: string[] = [];
+    try {
+      names = (await fs.readdir(dir)).filter((n) => n.endsWith(".md")).sort();
+    } catch {
+      // no agents dir
+    }
+    for (const n of names) {
+      const a = await readAgentFile(scope, path.join(dir, n));
+      if (a) agents.push(a);
+    }
+  }
+  // Agents the CLI actually loads (built-ins, plugins, files), for reference.
+  const init = await initInfo(root ?? os.homedir()).catch(() => null);
+  return { agents, effective: (init?.agents ?? []).map((a) => ({ name: a.name, description: a.description, model: a.model })) };
+}
+
+const FILE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$/;
+
+function agentPath(scope: "user" | "project", root: string | null, file: string): string {
+  if (!FILE_RE.test(file) || file.includes("..")) throw new ConfigError(400, "文件名不合法");
+  return path.join(agentsDir(scope, root), `${file}.md`);
+}
+
+export async function saveAgent(root: string | null, input: AgentInput & { baseMtime?: number }) {
+  const scope = input.scope === "project" ? "project" : "user";
+  const name = String(input.name ?? "").trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(name)) throw new ConfigError(400, "名称只能包含字母、数字、- 和 _");
+  if (!String(input.description ?? "").trim()) throw new ConfigError(400, "请填写说明（Claude 据此决定何时使用它）");
+  const file = input.file ?? name;
+  const p = agentPath(scope, root, file);
+  let original: string | undefined;
+  if (input.file) {
+    try {
+      const st = await fs.stat(p);
+      if (input.baseMtime !== undefined && Math.abs(st.mtimeMs - input.baseMtime) > 1) throw new ConfigError(409, "文件在你编辑期间被修改了，请重新打开后再保存");
+      original = await fs.readFile(p, "utf8");
+    } catch (err) {
+      if (err instanceof ConfigError) throw err;
+      throw new ConfigError(404, "agent 文件不存在");
+    }
+  } else if (await exists(p)) {
+    throw new ConfigError(409, "同名 agent 已存在");
+  }
+  await writeFileAtomic(p, serializeAgent({ name, description: input.description, tools: input.tools ?? "", model: input.model ?? "", prompt: input.prompt ?? "" }, original));
+  invalidate("init:");
+  return (await readAgentFile(scope, p))!;
+}
+
+export async function deleteAgent(root: string | null, scope: string, file: string) {
+  const p = agentPath(scope === "project" ? "project" : "user", root, file);
+  if (!(await exists(p))) throw new ConfigError(404, "agent 文件不存在");
+  await fs.rm(p);
+  invalidate("init:");
+}

package/server/config/mcp.ts

@@ -0,0 +1,86 @@
+import os from "node:os";
+import type { McpAddInput, McpServer, SettingsScope } from "../../shared/config.ts";
+import { clearMcpAuth, mcpStatus, toggleMcp } from "../cli-control.ts";
+import { ConfigError, runClaude } from "./paths.ts";
+
+/**
+ * MCP servers (/mcp). Status comes from the CLI (mcpServerStatus in a probe query);
+ * add/remove go through `claude mcp add-json/remove -s <scope>` so the CLI writes its
+ * own files (~/.claude.json for local/user, .mcp.json for project).
+ */
+
+const EDITABLE = new Set(["local", "project", "user"]);
+
+export async function listMcp(root: string | null): Promise<McpServer[]> {
+  const list = await mcpStatus(root ?? os.homedir());
+  return list.map((s) => {
+    const scope = s.scope ?? s.source ?? "unknown";
+    return {
+      name: s.name,
+      scope,
+      status: s.status,
+      ...(s.error ? { error: s.error.length > 500 ? s.error.slice(0, 500) + "…" : s.error } : {}),
+      config: s.config ?? {},
+      editable: EDITABLE.has(scope) && (scope === "user" || !!root),
+    };
+  });
+}
+
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+
+function cliError(r: { stdout: string; stderr: string }, fallback: string) {
+  const text = (r.stderr || r.stdout).trim();
+  return new ConfigError(400, text ? text.split("\n").slice(0, 6).join("\n") : fallback);
+}
+
+export async function addMcp(root: string | null, input: McpAddInput) {
+  const name = String(input.name ?? "").trim();
+  if (!NAME_RE.test(name)) throw new ConfigError(400, "名称只能包含字母、数字、-、_ 和 .");
+  const scope = input.scope as SettingsScope;
+  if (!["local", "project", "user"].includes(scope)) throw new ConfigError(400, "未知的作用域");
+  if (scope !== "user" && !root) throw new ConfigError(400, "local / project 作用域需要先选择项目");
+  let json: Record<string, unknown>;
+  if (input.transport === "stdio") {
+    const command = String(input.command ?? "").trim();
+    if (!command) throw new ConfigError(400, "请填写命令");
+    json = { type: "stdio", command, args: (input.args ?? []).map(String), env: cleanMap(input.env) };
+  } else if (input.transport === "http" || input.transport === "sse") {
+    const url = String(input.url ?? "").trim();
+    if (!/^https?:\/\//.test(url)) throw new ConfigError(400, "请填写 http(s) 地址");
+    json = { type: input.transport, url, ...(Object.keys(cleanMap(input.headers)).length ? { headers: cleanMap(input.headers) } : {}) };
+  } else throw new ConfigError(400, "未知的传输方式");
+  const r = await runClaude(["mcp", "add-json", "-s", scope, name, JSON.stringify(json)], root ?? os.homedir());
+  if (r.code !== 0) throw cliError(r, "添加失败");
+  return { ok: true, message: r.stdout.trim() };
+}
+
+function cleanMap(m: Record<string, string> | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(m ?? {})) if (k.trim()) out[k.trim()] = String(v);
+  return out;
+}
+
+export async function removeMcp(root: string | null, name: string, scope: string) {
+  if (!NAME_RE.test(name)) throw new ConfigError(400, "名称不合法");
+  if (!EDITABLE.has(scope)) throw new ConfigError(400, "这个服务器不在可编辑的作用域里");
+  const r = await runClaude(["mcp", "remove", "-s", scope, name], root ?? os.homedir());
+  if (r.code !== 0) throw cliError(r, "移除失败");
+  return { ok: true, message: r.stdout.trim() };
+}
+
+export async function setMcpEnabled(root: string | null, name: string, enabled: boolean) {
+  const r = await toggleMcp(root ?? os.homedir(), name, enabled);
+  return { ok: true, ...r };
+}
+
+export async function logoutMcp(root: string | null, name: string) {
+  await clearMcpAuth(root ?? os.homedir(), name);
+  return { ok: true };
+}
+
+/** `claude mcp get <name>`: the CLI's own view of one server (used by tests and the detail view). */
+export async function getMcpText(root: string | null, name: string) {
+  if (!NAME_RE.test(name)) throw new ConfigError(400, "名称不合法");
+  const r = await runClaude(["mcp", "get", name], root ?? os.homedir());
+  return { found: r.code === 0, text: (r.stdout || r.stderr).trim() };
+}

package/server/config/memory.ts

@@ -0,0 +1,193 @@
+import fs from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import path from "node:path";
+import type { MemoryFile, MemoryKind, MemoryListing, SettingsScope, TextFile } from "../../shared/config.ts";
+import { invalidate, memoryDialog } from "../cli-control.ts";
+import { ConfigError, configDir, isInside, readJsonFile, settingsFile, tildify, updateJsonFile, writeFileAtomic } from "./paths.ts";
+
+/**
+ * CLAUDE.md files, rules and auto memory (/memory). The CLI's memory dialog tells us
+ * which files it loads and where the auto-memory folder is (it canonicalizes worktrees
+ * to the main repo); the fixed locations are added so missing files can be created.
+ */
+
+const MAX_EDIT_BYTES = 1024 * 1024;
+
+/** Directory name the CLI uses under ~/.claude/projects for a project root. */
+export function encodeProjectDir(root: string): string {
+  return root.replace(/[^a-zA-Z0-9]/g, "-");
+}
+
+type Targets = {
+  fixed: { kind: MemoryKind; path: string; label: string }[];
+  dirs: { kind: MemoryKind; path: string; label: string }[];
+  other: { path: string; label: string }[];
+  auto: { enabled: boolean; dir: string | null };
+};
+
+async function targets(root: string | null): Promise<Targets> {
+  const fixed: Targets["fixed"] = [{ kind: "user", path: path.join(configDir, "CLAUDE.md"), label: tildify(path.join(configDir, "CLAUDE.md")) }];
+  const dirs: Targets["dirs"] = [{ kind: "user-rule", path: path.join(configDir, "rules"), label: tildify(path.join(configDir, "rules")) }];
+  const other: Targets["other"] = [];
+  let auto: Targets["auto"] = { enabled: true, dir: null };
+  if (root) {
+    fixed.push(
+      { kind: "project", path: path.join(root, "CLAUDE.md"), label: "CLAUDE.md" },
+      { kind: "project", path: path.join(root, ".claude", "CLAUDE.md"), label: ".claude/CLAUDE.md" },
+      { kind: "local", path: path.join(root, "CLAUDE.local.md"), label: "CLAUDE.local.md" },
+    );
+    dirs.push({ kind: "project-rule", path: path.join(root, ".claude", "rules"), label: ".claude/rules" });
+    let autoDir = path.join(configDir, "projects", encodeProjectDir(root), "memory");
+    try {
+      const d = await memoryDialog(root);
+      const folder = d.folders.find((f) => f.kind === "auto");
+      if (folder) autoDir = path.resolve(folder.path);
+      auto = { enabled: d.auto_memory.enabled, dir: autoDir };
+      const known = new Set([...fixed.map((f) => f.path)]);
+      for (const f of d.files) {
+        const p = path.resolve(f.path);
+        if (known.has(p) || dirs.some((dd) => isInside(dd.path, p))) continue;
+        other.push({ path: p, label: tildify(p) });
+      }
+    } catch {
+      auto = { enabled: await autoMemoryFromFiles(root), dir: autoDir };
+    }
+    dirs.push({ kind: "auto", path: auto.dir!, label: "自动记忆" });
+  }
+  return { fixed, dirs, other, auto };
+}
+
+async function autoMemoryFromFiles(root: string | null): Promise<boolean> {
+  for (const scope of ["local", "project", "user"] as const) {
+    const f = settingsFile(scope, root);
+    if (!f) continue;
+    const v = (await readJsonFile(f)).data.autoMemoryEnabled;
+    if (typeof v === "boolean") return v;
+  }
+  return true;
+}
+
+async function statFile(p: string): Promise<{ exists: boolean; size?: number; mtime?: number }> {
+  try {
+    const st = await fs.stat(p);
+    return st.isFile() ? { exists: true, size: st.size, mtime: st.mtimeMs } : { exists: false };
+  } catch {
+    return { exists: false };
+  }
+}
+
+async function listMarkdown(dir: string, depth = 0): Promise<string[]> {
+  if (depth > 4) return [];
+  let entries: Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out: string[] = [];
+  for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...await listMarkdown(p, depth + 1));
+    else if (e.isFile() && e.name.endsWith(".md")) out.push(p);
+  }
+  return out;
+}
+
+export async function listMemory(root: string | null): Promise<MemoryListing> {
+  const t = await targets(root);
+  const files: MemoryFile[] = [];
+  for (const f of t.fixed) {
+    const st = await statFile(f.path);
+    // .claude/CLAUDE.md is an alternative location; only list it when it exists.
+    if (!st.exists && f.label === ".claude/CLAUDE.md") continue;
+    files.push({ kind: f.kind, path: f.path, label: f.label, ...st });
+  }
+  for (const d of t.dirs) {
+    const list = await listMarkdown(d.path);
+    // MEMORY.md (the index) first.
+    if (d.kind === "auto") list.sort((a, b) => Number(path.basename(b) === "MEMORY.md") - Number(path.basename(a) === "MEMORY.md"));
+    for (const p of list) files.push({ kind: d.kind, path: p, label: d.kind === "auto" ? path.relative(d.path, p) : `${d.label}/${path.relative(d.path, p)}`, ...await statFile(p) });
+  }
+  for (const o of t.other) files.push({ kind: "other", path: o.path, label: o.label, ...await statFile(o.path) });
+  return {
+    files,
+    dirs: t.dirs.map((d) => ({ kind: d.kind, path: d.path, label: d.kind === "auto" ? tildify(d.path) : d.label })),
+    autoMemory: { enabled: t.auto.enabled, dir: t.auto.dir, scope: await autoMemoryScope(root) },
+  };
+}
+
+/** Only known memory files, or Markdown files inside the rules / auto-memory dirs, may be touched. */
+async function checkPath(root: string | null, raw: string): Promise<string> {
+  if (!raw || raw.includes("\0") || !path.isAbsolute(raw)) throw new ConfigError(400, "非法路径");
+  const p = path.resolve(raw);
+  const t = await targets(root);
+  if (t.fixed.some((f) => f.path === p) || t.other.some((o) => o.path === p)) return p;
+  const dir = t.dirs.find((d) => isInside(d.path, p) && p !== d.path);
+  if (p.endsWith(".md") && dir) {
+    // Symlinks inside the directory must not lead outside it.
+    let probe = p;
+    for (;;) {
+      try {
+        await fs.access(probe);
+        break;
+      } catch {
+        const parent = path.dirname(probe);
+        if (parent === probe) break;
+        probe = parent;
+      }
+    }
+    if (!isInside(dir.path, probe)) return p; // nothing under the directory exists yet
+    if (isInside(await fs.realpath(dir.path), await fs.realpath(probe))) return p;
+  }
+  throw new ConfigError(403, "不是记忆文件");
+}
+
+export async function readMemoryFile(root: string | null, raw: string): Promise<TextFile> {
+  const p = await checkPath(root, raw);
+  const st = await statFile(p);
+  if (!st.exists) throw new ConfigError(404, "文件不存在");
+  if ((st.size ?? 0) > MAX_EDIT_BYTES) throw new ConfigError(400, "文件太大");
+  return { path: p, content: await fs.readFile(p, "utf8"), mtime: st.mtime! };
+}
+
+export async function writeMemoryFile(root: string | null, body: { path?: string; content?: string; create?: boolean; baseMtime?: number }): Promise<TextFile> {
+  const p = await checkPath(root, String(body.path ?? ""));
+  const content = String(body.content ?? "");
+  if (Buffer.byteLength(content) > MAX_EDIT_BYTES) throw new ConfigError(400, "内容太大");
+  const st = await statFile(p);
+  if (body.create && st.exists) throw new ConfigError(409, "文件已存在");
+  if (!body.create && !st.exists) throw new ConfigError(404, "文件不存在");
+  // Someone (Claude, the CLI) changed it since it was opened: don't overwrite blindly.
+  if (body.baseMtime !== undefined && st.exists && Math.abs((st.mtime ?? 0) - body.baseMtime) > 1) {
+    throw new ConfigError(409, "文件在你编辑期间被修改了，请重新打开后再保存");
+  }
+  await writeFileAtomic(p, content);
+  if (root) invalidate(`memory:${root}`);
+  return { path: p, content, mtime: (await statFile(p)).mtime! };
+}
+
+export async function deleteMemoryFile(root: string | null, raw: string) {
+  const p = await checkPath(root, raw);
+  if (!(await statFile(p)).exists) throw new ConfigError(404, "文件不存在");
+  await fs.rm(p);
+  if (root) invalidate(`memory:${root}`);
+}
+
+/** The highest-priority settings file that sets autoMemoryEnabled (null: default). */
+async function autoMemoryScope(root: string | null): Promise<SettingsScope | null> {
+  for (const scope of ["local", "project", "user"] as const) {
+    const f = settingsFile(scope, root);
+    if (f && typeof (await readJsonFile(f)).data.autoMemoryEnabled === "boolean") return scope;
+  }
+  return null;
+}
+
+/** Toggle auto memory where it is decided: the layer that sets it, else user settings. */
+export async function setAutoMemory(root: string | null, enabled: boolean) {
+  const scope = (await autoMemoryScope(root)) ?? "user";
+  await updateJsonFile(settingsFile(scope, root)!, (d) => {
+    d.autoMemoryEnabled = enabled;
+  });
+  if (root) invalidate(`memory:${root}`);
+  return { scope };
+}

package/server/config/paths.ts

@@ -0,0 +1,156 @@
+import { childEnv } from "../child-env.ts";
+import fs from "node:fs/promises";
+import { withFileLock } from "../fs-queue.ts";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { execFile } from "node:child_process";
+import type { SettingsScope } from "../../shared/config.ts";
+
+/**
+ * Where the CLI keeps its user-level config. Normally ~/.claude (+ ~/.claude.json).
+ * `CLAUDE_IDE_CLAUDE_CONFIG_DIR` points only the settings pages (and the `claude`
+ * subcommands / probe queries they run) at another directory — e2e tests use it so
+ * they never touch the real config while live sessions keep the real login.
+ * An inherited `CLAUDE_CONFIG_DIR` is honoured the same way the CLI honours it.
+ */
+const override = process.env.CLAUDE_IDE_CLAUDE_CONFIG_DIR ? path.resolve(process.env.CLAUDE_IDE_CLAUDE_CONFIG_DIR) : undefined;
+const inherited = process.env.CLAUDE_CONFIG_DIR ? path.resolve(process.env.CLAUDE_CONFIG_DIR) : undefined;
+
+export const configDir = override ?? inherited ?? path.join(os.homedir(), ".claude");
+if (override) await fs.mkdir(override, { recursive: true });
+
+/** The CLI's state file: `$CLAUDE_CONFIG_DIR/.claude.json` when set, else `~/.claude.json`. */
+export const globalStateFile = override || inherited ? path.join(configDir, ".claude.json") : path.join(os.homedir(), ".claude.json");
+
+/** Environment for `claude` subcommands and probe queries started by the settings pages. */
+export function claudeEnv(): Record<string, string | undefined> {
+  const env = childEnv();
+  if (override) env.CLAUDE_CONFIG_DIR = override;
+  return env;
+}
+
+/** "~/…" for display, relative to the real home. */
+export function tildify(p: string): string {
+  const home = os.homedir();
+  return p === home || p.startsWith(home + path.sep) ? "~" + p.slice(home.length) : p;
+}
+
+export function settingsFile(scope: SettingsScope, projectRoot: string | null): string | null {
+  if (scope === "user") return path.join(configDir, "settings.json");
+  if (!projectRoot) return null;
+  return path.join(projectRoot, ".claude", scope === "project" ? "settings.json" : "settings.local.json");
+}
+
+export const isInside = (root: string, p: string) => {
+  const rel = path.relative(root, p);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+};
+
+// ---------- atomic writes ----------
+
+/** Write a file atomically (temp file in the same directory, then rename), keeping its mode. */
+export async function writeFileAtomic(file: string, content: string) {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  let mode: number | undefined;
+  try {
+    mode = (await fs.stat(file)).mode & 0o777;
+  } catch {
+    // new file
+  }
+  const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`);
+  await fs.writeFile(tmp, content, mode !== undefined ? { mode } : {});
+  try {
+    await fs.rename(tmp, file);
+  } catch (err) {
+    await fs.rm(tmp, { force: true });
+    throw err;
+  }
+}
+
+type JsonObject = Record<string, unknown>;
+
+export class ConfigError extends Error {
+  constructor(
+    public status: 400 | 403 | 404 | 409 | 500 | 502,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export async function readJsonFile(file: string): Promise<{ data: JsonObject; exists: boolean; indent: string | number; newline: boolean }> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(file, "utf8");
+  } catch {
+    return { data: {}, exists: false, indent: 2, newline: true };
+  }
+  if (!raw.trim()) return { data: {}, exists: true, indent: 2, newline: true };
+  let data: unknown;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    throw new ConfigError(409, `${tildify(file)} 不是合法的 JSON，请先手动修复`);
+  }
+  if (!data || typeof data !== "object" || Array.isArray(data)) throw new ConfigError(409, `${tildify(file)} 的顶层不是对象`);
+  // Keep the file's indentation style: the first indented line decides.
+  const m = /\n([ \t]+)\S/.exec(raw);
+  const indent = m ? (m[1].includes("\t") ? "\t" : m[1].length) : 2;
+  return { data: data as JsonObject, exists: true, indent, newline: raw.endsWith("\n") };
+}
+
+/**
+ * Read-modify-write a JSON config file. Unknown keys are kept as they are, the
+ * indentation style is preserved, and the write is atomic.
+ */
+export function updateJsonFile(file: string, fn: (data: JsonObject) => void): Promise<JsonObject> {
+  return withFileLock(file, async () => {
+    const { data, indent, newline } = await readJsonFile(file);
+    fn(data);
+    await writeFileAtomic(file, JSON.stringify(data, null, indent) + (newline ? "\n" : ""));
+    return data;
+  });
+}
+
+// ---------- running `claude` ----------
+
+export const claudeBin = process.env.CLAUDE_IDE_CLAUDE_BIN || "claude";
+
+export type CliResult = { code: number; stdout: string; stderr: string };
+
+/** Run a `claude` subcommand (never a model call) against the configured config dir. */
+export function runClaude(args: string[], cwd: string, opts: { timeoutMs?: number } = {}): Promise<CliResult> {
+  return new Promise((resolve, reject) => {
+    execFile(
+      claudeBin,
+      args,
+      { cwd, env: claudeEnv(), timeout: opts.timeoutMs ?? 60_000, maxBuffer: 16 * 1024 * 1024, encoding: "utf8" },
+      (err, stdout, stderr) => {
+        if (err && typeof (err as NodeJS.ErrnoException).code === "string") return reject(new ConfigError(500, `无法运行 claude：${err.message}`));
+        if (err && (err as { killed?: boolean }).killed) return resolve({ code: -1, stdout, stderr: stderr || "超时" });
+        const code = err ? ((err as { code?: number }).code ?? 1) : 0;
+        resolve({ code: typeof code === "number" ? code : 1, stdout, stderr });
+      },
+    ).stdin?.end();
+  });
+}
+
+/** Parse the last JSON value printed on stdout (`--json` prints one line, sometimes after other text). */
+export function parseJsonOutput<T>(stdout: string): T | undefined {
+  const t = stdout.trim();
+  if (!t) return undefined;
+  try {
+    return JSON.parse(t) as T;
+  } catch {
+    const lines = t.split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+      try {
+        return JSON.parse(lines.slice(i).join("\n")) as T;
+      } catch {
+        // keep looking
+      }
+    }
+  }
+  return undefined;
+}