Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

26.7 KB
Raw Blame
/**
 * Workdir File Browser — single-layer directory scanner + file reader.
 *
 * Why single-layer (not recursive):
 *   Real Unity workdir benchmark: full recursive scan with builtin ignore
 *   = 4 seconds / 698k entries (unacceptable IPC payload + render cost).
 *   Per-folder readdir = 0.1-12 ms (the worst folder under test was
 *   `EntityScriptDatas/` with 17k entries → still 12 ms). So lazy expansion
 *   is the only viable strategy at this scale.
 *
 * All paths in the public API are workdir-relative POSIX strings; absolute
 * paths never leave this module. Path traversal is blocked via
 * `assertInsideWorkdir` — renderer cannot ask for `../../etc/passwd`.
 */

import { randomBytes } from 'node:crypto';
import { promises as fs, type Stats, type Dirent } from 'node:fs';
import path from 'node:path';

import { scopedLogger } from './logging.js';
import { loadIgnoreMatcher, type Matcher } from './ignore.js';

const log = scopedLogger('file-browser/scanner');

// Reuse the locale-aware comparator across lazy directory expansions.
const entryNameCollator = new Intl.Collator(undefined, { numeric: true });

/** Hard cap on file size we'll send to the renderer. Anything larger gets
 *  truncated; renderer shows a "file truncated, open in OS to see more"
 *  banner. 2 MiB is enough for any realistic markdown/code file. */
const MAX_FILE_BYTES = 2 * 1024 * 1024;

/** PDF 文件头。规范允许其前面有少量垃圾字节,pdf.js 也只在前 1 KiB 内找它,这里同口径。 */
const PDF_SIGNATURE = Buffer.from('%PDF-', 'latin1');
const PDF_SIGNATURE_WINDOW = 1024;

/**
 * 文本读取 / 覆写前的二进制判定,readFile 与 writeFile 共用:
 *   - 前 4 KiB 含 NUL → PNG/FBX/DLL 等常见二进制;
 *   - `.pdf` 文件前 1 KiB 内出现 `%PDF-` → PDF。合法 PDF 不一定含 NUL(对象流未压缩、
 *     纯 ASCII 时整份文件都可能没有 NUL),只靠 NUL 探测会把它当 UTF-8 文本交给渲染层,
 *     显示成 `%PDF-1.4 ... obj ... stream` 原始语法(issue #4158)。判成二进制后渲染层按
 *     扩展名走既有 PdfPreview 分支。
 *     文件头判定只对 `.pdf` 扩展名生效:渲染层的 PDF 预览本来就以扩展名为准,其他扩展名
 *     判成二进制只会得到不可渲染占位、还会让编辑器拒绝保存;而 markdown / 日志 / 源码
 *     在开头引用 `%PDF-` 很常见,不能误伤。
 */
function isBinaryProbe(probe: Buffer, relPath: string): boolean {
  if (probe.includes(0)) return true;
  if (!hasPdfExtension(relPath)) return false;
  return probe.subarray(0, PDF_SIGNATURE_WINDOW).includes(PDF_SIGNATURE);
}

function hasPdfExtension(relPath: string): boolean {
  const name = relPath.slice(relPath.lastIndexOf('/') + 1);
  const dot = name.lastIndexOf('.');
  return dot > 0 && name.slice(dot).toLowerCase() === '.pdf';
}

/**
 * 原子写中间产物的后缀。writeFile 把内容先落到 `${target}.<随机>.xdt-tmp`,fsync 后
 * rename 成正式名。这个临时文件理论上只活一两毫秒,但在边栏 listDir 路径上仍
 * 可能被瞥见 → 一闪而过的 ghost row,视觉上像"刷一下"。
 *
 * 因此 listDir 输出和 watcher 事件都要把它过滤掉,让它对前端完全不可见。
 * 见 watcher.ts 里同步定义。
 */
export const XDT_TMP_SUFFIX = '.xdt-tmp';

export interface DirEntry {
  /** filename only, no path */
  name: string;
  /** workdir-relative POSIX path */
  relPath: string;
  type: 'file' | 'directory';
  /** file size in bytes (only for files; directories report 0) */
  size: number;
  /** ms since epoch */
  mtimeMs: number;
}

export interface FileReadResult {
  relPath: string;
  /** UTF-8 contents (truncated to MAX_FILE_BYTES) */
  content: string;
  /** Total file size in bytes (may be larger than content.length for truncated reads) */
  size: number;
  mtimeMs: number;
  truncated: boolean;
}

export interface FileStat {
  relPath: string;
  type: 'file' | 'directory';
  size: number;
  mtimeMs: number;
}

/**
 * Workdir-relative POSIX path normalization. Accepts either '' / '.' / 'a/b'
 * for a path inside the workdir; throws on absolute or traversal attempts.
 */
function assertInsideWorkdir(workdir: string, relPath: string): string {
  // Normalize and reject anything that escapes the workdir. We resolve to
  // absolute and verify the resolved path starts with workdir + sep.
  // Reject anything absolute on ANY host OS, checked on the raw input so the
  // guard is host-independent (this browser runs on macOS/Windows/Linux):
  //  - path.posix.isAbsolute → POSIX absolute "/etc/passwd";
  //  - path.win32.isAbsolute → "\x", UNC "\\srv\share", drive-absolute "C:\x"/"C:/x";
  //  - /^[a-zA-Z]:/          → drive-*relative* "C:foo"/"C:", which win32.isAbsolute
  //    misses yet path.resolve on Windows reinterprets against drive C:'s current
  //    directory (NOT as a workdir entry literally named "C:foo"). A ":"-carrying
  //    drive token is Windows path syntax and cannot be a workdir-relative POSIX
  //    name cross-platform, so reject it rather than silently mis-resolving it.
  if (
    path.posix.isAbsolute(relPath) ||
    path.win32.isAbsolute(relPath) ||
    /^[a-zA-Z]:/.test(relPath)
  ) {
    throw new Error(`absolute path not allowed: ${relPath}`);
  }
  // What remains is a workdir-relative path: normalize separators and strip a
  // leading "./". Traversal ("../…") is caught by the containment check below.
  const cleaned = relPath.replace(/\\/g, '/').replace(/^\.\/+/, '');
  if (cleaned === '' || cleaned === '.') return '';
  const abs = path.resolve(workdir, cleaned);
  const wdAbs = path.resolve(workdir);
  if (abs !== wdAbs && !abs.startsWith(wdAbs + path.sep)) {
    throw new Error(`path escapes workdir: ${relPath}`);
  }
  return cleaned;
}

async function assertRealPathInsideWorkdir(
  workdir: string,
  absPath: string,
): Promise<string> {
  const [wdReal, targetReal] = await Promise.all([
    fs.realpath(workdir),
    fs.realpath(absPath),
  ]);
  if (targetReal !== wdReal && !targetReal.startsWith(wdReal + path.sep)) {
    throw new Error(`path escapes workdir via symlink: ${path.relative(workdir, absPath)}`);
  }
  return targetReal;
}

async function assertRealParentInsideWorkdir(
  workdir: string,
  absPath: string,
): Promise<void> {
  const [wdReal, parentReal] = await Promise.all([
    fs.realpath(workdir),
    fs.realpath(path.dirname(absPath)),
  ]);
  if (parentReal !== wdReal && !parentReal.startsWith(wdReal + path.sep)) {
    throw new Error(`path escapes workdir via symlink: ${path.relative(workdir, absPath)}`);
  }
}

export interface ListDirOptions {
  /** Optional transfer budget; exceeding it fails instead of returning a partial list. */
  maxEntries?: number;
  /**
   * "Doc mode": only show doc/config text files (see DOC_MODE_EXTS); only
   * show directories that have at least one such file as a descendant.
   * The recursive descendant check applies the same ignore matcher and
   * short-circuits on first hit.
   */
  docMode?: boolean;
}

/**
 * Allowed file extensions in doc mode. Intentionally excludes code (.ts /
 * .py / .css / ...) and `.env` (secret-prone). Add new entries here when a
 * user calls out a missing file type — keeping the list small avoids the
 * "everything is a doc" drift that defeats the point of doc mode.
 */
const DOC_MODE_EXTS = new Set([
  'md',
  'txt',
  'json',
  'yaml',
  'yml',
  'toml',
  'ini',
  'xml',
  'csv',
]);

function isDocModeFile(name: string): boolean {
  const dot = name.lastIndexOf('.');
  if (dot < 0 || dot === name.length - 1) return false;
  return DOC_MODE_EXTS.has(name.slice(dot + 1).toLowerCase());
}

/**
 * Cheap recursive probe: does this directory contain at least one
 * doc-mode-visible file as a descendant (under the same matcher)?
 * Short-circuits on first hit. Used by listDir's docMode to decide
 * whether to surface a subdir.
 *
 * Implementation:
 *   - Sibling subdirs are walked in parallel (Promise.all over the level)
 *     so a top-level dir like apps/desktop/ doesn't serialize 50 subwalks.
 *   - Overlapping probes share only the in-flight `readdir` for each absolute
 *     directory. Traversals keep their own `Found` cell, preserving sibling
 *     short-circuiting without allowing one probe's result to contaminate
 *     another; completed directory reads are never cached.
 *
 * Worst case (deep subtree with no matching file): walks the whole subtree
 * once, but in parallel. BUILTIN_IGNORE prunes node_modules / Library /
 * etc., which are the only realistic huge subtrees.
 */
type Found = { v: boolean };

/** In-flight-only sharing for overlapping doc-mode directory reads. */
const docDirentsInFlight = new Map<string, Promise<Dirent[]>>();

function readDocDirents(abs: string): Promise<Dirent[]> {
  const key = path.resolve(abs);
  const current = docDirentsInFlight.get(key);
  if (current) return current;

  const read = fs.readdir(abs, { withFileTypes: true });
  docDirentsInFlight.set(key, read);
  void read.then(
    () => {
      if (docDirentsInFlight.get(key) === read) docDirentsInFlight.delete(key);
    },
    () => {
      if (docDirentsInFlight.get(key) === read) docDirentsInFlight.delete(key);
    },
  );
  return read;
}

async function hasDocDescendantInner(
  abs: string,
  relPath: string,
  matcher: Matcher,
  found: Found,
): Promise<boolean> {
  if (found.v) return true;
  let dirents: Dirent[];
  try {
    dirents = await readDocDirents(abs);
  } catch {
    return false;
  }
  if (found.v) return true;
  // Pass 1: own files (cheaper than recursing).
  const subdirs: { name: string; childRel: string }[] = [];
  for (const d of dirents) {
    const childRel = relPath === '' ? d.name : `${relPath}/${d.name}`;
    const isDir = d.isDirectory();
    if (matcher.ignores(childRel, isDir)) continue;
    if (d.isSymbolicLink()) continue;
    if (isDir) {
      subdirs.push({ name: d.name, childRel });
    } else if (isDocModeFile(d.name)) {
      found.v = true;
      return true;
    }
  }
  if (subdirs.length === 0 || found.v) return found.v;
  // Pass 2: recurse all subdirs in parallel. Each traversal keeps the same
  // `Found` cell, so a fast hit stops deeper work in sibling branches.
  const results = await Promise.all(
    subdirs.map((s) =>
      hasDocDescendantInner(path.join(abs, s.name), s.childRel, matcher, found),
    ),
  );
  return results.some(Boolean);
}

async function hasDocDescendant(
  abs: string,
  relPath: string,
  matcher: Matcher,
): Promise<boolean> {
  return hasDocDescendantInner(abs, relPath, matcher, { v: false });
}

/**
 * List entries of one directory (single-layer, no recursion). Filtered
 * through an optional presentation matcher. Without a matcher all ordinary
 * files are listed, including hidden files and build outputs. Sort: directories before files,
 * each group case-insensitive natural order (chapter2 before chapter10).
 */
export async function listDir(
  workdir: string,
  relPath: string,
  matcher: Matcher | null = null,
  opts: ListDirOptions = {},
): Promise<DirEntry[]> {
  if (opts.maxEntries !== undefined && (!Number.isSafeInteger(opts.maxEntries) || opts.maxEntries < 1)) {
    throw new Error('Invalid directory entry limit');
  }
  const sub = assertInsideWorkdir(workdir, relPath);
  const abs = sub === '' ? workdir : path.join(workdir, sub);
  await assertRealPathInsideWorkdir(workdir, abs);
  // In doc mode this top-level read participates in the same in-flight map as
  // recursive descendant probes. An overlapping `listDir('src')` can thus
  // reuse the read already started while listing the root, without retaining
  // a completed snapshot.
  const dirents = opts.docMode
    ? await readDocDirents(abs)
    : await fs.readdir(abs, { withFileTypes: true });
  if (opts.maxEntries !== undefined && dirents.length > opts.maxEntries) {
    throw new Error('DIRECTORY_TOO_LARGE');
  }

  // Process all entries in parallel. With docMode on, each surviving subdir
  // triggers a recursive hasDocDescendant probe — running siblings in
  // parallel turns a (#subdirs × per-subdir-walk) wall-clock cost into one
  // bounded by the slowest subtree. lstat + readdir all overlap.
  const candidates = await Promise.all(
    dirents.map(async (d): Promise<DirEntry | null> => {
      const childRel = sub === '' ? d.name : `${sub}/${d.name}`;
      const isDir = d.isDirectory();
      if (matcher?.ignores(childRel, isDir)) return null;
      // 原子写中间产物 — 隐藏不让前端看到一闪而过的临时行。
      if (matcher && !isDir && d.name.endsWith(XDT_TMP_SUFFIX)) return null;
      // We need stats for size + mtime; use lstat to avoid following symlinks
      // into Library/ et al. (some Unity setups symlink huge caches in).
      let st: Stats;
      try {
        st = await fs.lstat(path.join(abs, d.name));
      } catch (error) {
        // Complete enumeration must not silently return a partial snapshot.
        if (!matcher) throw error;
        // Presentation mode tolerates files removed mid-scan or inaccessible entries.
        return null;
      }
      // Skip symlinks unless they point inside the workdir; cheaper to just
      // skip than to chase them. User can open via OS if needed.
      if (st.isSymbolicLink()) return null;
      if (!st.isDirectory() && !st.isFile()) return null;
      if (opts.docMode) {
        if (isDir) {
          if (!(await hasDocDescendant(path.join(abs, d.name), childRel, matcher ?? { ignores: () => false }))) {
            return null;
          }
        } else if (!isDocModeFile(d.name)) {
          return null;
        }
      }
      return {
        name: d.name,
        relPath: childRel,
        type: isDir ? 'directory' : 'file',
        size: isDir ? 0 : st.size,
        mtimeMs: st.mtimeMs,
      };
    }),
  );
  const out: DirEntry[] = candidates.filter((e): e is DirEntry => e !== null);

  // Directories first, then natural name order within each group.
  out.sort((a, b) => {
    if (a.type !== b.type) return a.type === 'directory' ? -1 : 1;
    const aName = a.name.toLocaleLowerCase();
    const bName = b.name.toLocaleLowerCase();
    // Keep the legacy text order for numeric ties such as 001, 01 and 1.
    return entryNameCollator.compare(aName, bName) || aName.localeCompare(bName);
  });

  return out;
}

/**
 * Read one file, capped at MAX_FILE_BYTES. Returns UTF-8 string + truncation
 * flag. Binary files (NULL byte in first 4KB, or a `.pdf` with a PDF header)
 * raise an error so the renderer can render the placeholder / PDF preview instead.
 */
export async function readFile(
  workdir: string,
  relPath: string,
): Promise<FileReadResult> {
  const sub = assertInsideWorkdir(workdir, relPath);
  if (sub === '') throw new Error('cannot read workdir root as file');
  const abs = path.join(workdir, sub);
  const realAbs = await assertRealPathInsideWorkdir(workdir, abs);
  const st = await fs.stat(realAbs);
  if (st.isDirectory()) throw new Error(`is a directory: ${relPath}`);

  const truncated = st.size > MAX_FILE_BYTES;
  const handle = await fs.open(realAbs, 'r');
  try {
    const buf = Buffer.alloc(Math.min(st.size, MAX_FILE_BYTES));
    if (buf.length > 0) {
      await handle.read(buf, 0, buf.length, 0);
    }
    // Quick binary detection: NULL byte in first 4 KiB (PNG/FBX/DLL etc.) or a
    // PDF header in a `.pdf` file (see isBinaryProbe). UTF-16 text files contain
    // NULL bytes too but are rare in dev workflows; renderer can still fall back
    // to "open in OS" if needed.
    const probe = buf.subarray(0, Math.min(buf.length, 4096));
    if (isBinaryProbe(probe, sub)) {
      const err = new Error(`binary file: ${relPath}`);
      (err as Error & { code?: string }).code = 'BINARY_FILE';
      throw err;
    }
    return {
      relPath: sub,
      content: buf.toString('utf8'),
      size: st.size,
      mtimeMs: st.mtimeMs,
      truncated,
    };
  } finally {
    await handle.close();
  }
}

export interface FileChunkResult {
  /** 原始字节片(caller 自行编码,daemon 转 base64 进 JSON)。 */
  data: Buffer;
  /** offset + data.length ≥ 文件大小,即已是最后一片。 */
  eof: boolean;
  size: number;
  mtimeMs: number;
}

/** 单片长度上限:base64 后 ~1.37MB,远低于 NDJSON 解码缓冲,也不挤占 relay 帧。 */
export const FILE_CHUNK_MAX_LENGTH = 1024 * 1024;

/**
 * 大文件分片读:按 [offset, offset+length) 返回原始字节。与 readFile 不同,
 * 不做 2MiB 截断、不做二进制检测——它服务"任意大小文件完整拉回本地缓存"的
 * 传输管线,内容判定由消费端做。路径安全与 readFile 完全同源。
 */
export async function readFileChunk(
  workdir: string,
  relPath: string,
  offset: number,
  length: number,
): Promise<FileChunkResult> {
  const sub = assertInsideWorkdir(workdir, relPath);
  if (sub === '') throw new Error('cannot read workdir root as file');
  if (!Number.isSafeInteger(offset) || offset < 0) throw new Error(`bad offset: ${offset}`);
  const len = Math.max(0, Math.min(length, FILE_CHUNK_MAX_LENGTH));
  const abs = path.join(workdir, sub);
  const realAbs = await assertRealPathInsideWorkdir(workdir, abs);
  const st = await fs.stat(realAbs);
  if (st.isDirectory()) throw new Error(`is a directory: ${relPath}`);

  const readLen = Math.max(0, Math.min(len, st.size - offset));
  const handle = await fs.open(realAbs, 'r');
  try {
    // fs.read 可能短读(bytesRead < 请求长度),必须循环读满;否则未填充的
    // 尾部以 0x00 混进结果,消费端(SSH 大文件取回)会把补零字节写进缓存
    // 副本并把 offset 推进过真实数据 —— 内容静默损坏。
    const buf = Buffer.alloc(readLen);
    let filled = 0;
    while (filled < readLen) {
      const { bytesRead } = await handle.read(buf, filled, readLen - filled, offset + filled);
      if (bytesRead === 0) break; // 真 EOF(文件被并发截断):按实际读到的返回
      filled += bytesRead;
    }
    return {
      data: filled === readLen ? buf : buf.subarray(0, filled),
      eof: offset + filled >= st.size,
      size: st.size,
      mtimeMs: st.mtimeMs,
    };
  } finally {
    await handle.close();
  }
}

/**
 * Atomically write text content to a file inside workdir. Pattern: write to
 * `${target}.<random>.xdt-tmp`, fsync handle, rename → target. Crash-safe (consumer
 * either sees old content or new, never partial).
 *
 * Constraints:
 *   - Path traversal blocked via assertInsideWorkdir.
 *   - File must already exist — this API is for editing previewed files,
 *     not creating new ones (no "save as" semantics in the file-browser).
 *   - Refuses files >MAX_FILE_BYTES on disk (the read path truncates large
 *     files; saving back would silently lose data).
 *   - Refuses content >MAX_FILE_BYTES (defense against giant paste).
 *   - Refuses binary files (NULL byte in first 4KB, or a `.pdf` with a PDF
 *     header) — same probe as readFile, so the editor never opens binaries.
 */
export async function writeFile(
  workdir: string,
  relPath: string,
  content: string,
): Promise<{ size: number; mtimeMs: number }> {
  const sub = assertInsideWorkdir(workdir, relPath);
  if (sub === '') throw new Error('cannot write workdir root');
  const abs = path.join(workdir, sub);
  const realAbs = await assertRealPathInsideWorkdir(workdir, abs);

  // File must exist. Editing-a-file-that-was-just-deleted is a corner case
  // we surface as an error instead of silently re-creating.
  const st = await fs.stat(realAbs);
  if (st.isDirectory()) throw new Error(`is a directory: ${relPath}`);
  if (st.size > MAX_FILE_BYTES) {
    throw new Error(`file too large to edit (>${MAX_FILE_BYTES} bytes): ${relPath}`);
  }

  const buf = Buffer.from(content, 'utf8');
  if (buf.length > MAX_FILE_BYTES) {
    throw new Error(`content too large (>${MAX_FILE_BYTES} bytes)`);
  }

  // Defense in depth: re-probe binary signature on the on-disk version.
  // (User shouldn't be able to open & edit a binary anyway, but if some
  // upstream check is bypassed, we don't want to overwrite a .png with
  // textual JSON.)
  const probeHandle = await fs.open(realAbs, 'r');
  try {
    const probe = Buffer.alloc(Math.min(st.size, 4096));
    if (probe.length > 0) await probeHandle.read(probe, 0, probe.length, 0);
    if (isBinaryProbe(probe, sub)) {
      throw new Error(`binary file: ${relPath}`);
    }
  } finally {
    await probeHandle.close();
  }

  // 临时名带随机段并以 'wx' 独占创建:固定名可被工作目录里预置的符号链接
  // 占位,'w' 会跟随链接写到工作目录外,rename 还会把链接本身搬成目标文件。
  // 仍以 XDT_TMP_SUFFIX 结尾,listDir / watcher 的过滤照旧生效。
  const tmp = `${realAbs}.${randomBytes(6).toString('hex')}${XDT_TMP_SUFFIX}`;
  const handle = await fs.open(tmp, 'wx');
  try {
    try {
      await handle.writeFile(buf);
      await handle.sync();
    } finally {
      await handle.close();
    }
    // rename is atomic on same filesystem (which .xdt-tmp guarantees since
    // we wrote it in the same directory).
    await fs.rename(tmp, realAbs);
  } catch (err) {
    await fs.rm(tmp, { force: true }).catch(() => {});
    throw err;
  }

  const after = await fs.stat(realAbs);
  return { size: after.size, mtimeMs: after.mtimeMs };
}

/**
 * Create an empty file inside workdir. Refuses if anything already exists at
 * the target path (file/dir/symlink). Parent dir must already exist — caller
 * is the file-tree, parent is always a known visible folder. Returns the
 * stat of the created file.
 */
export async function createFile(
  workdir: string,
  relPath: string,
): Promise<FileStat> {
  const sub = assertInsideWorkdir(workdir, relPath);
  if (sub === '') throw new Error('cannot create at workdir root');
  const abs = path.join(workdir, sub);
  await assertRealParentInsideWorkdir(workdir, abs);
  // 'wx' = create, fail if exists. Doesn't create parent dirs.
  const handle = await fs.open(abs, 'wx');
  await handle.close();
  const st = await fs.stat(abs);
  return { relPath: sub, type: 'file', size: st.size, mtimeMs: st.mtimeMs };
}

/**
 * Create a folder inside workdir. Errors if anything already exists at the
 * target path. Parent dir must already exist (same rationale as createFile).
 */
export async function createFolder(
  workdir: string,
  relPath: string,
): Promise<FileStat> {
  const sub = assertInsideWorkdir(workdir, relPath);
  if (sub === '') throw new Error('cannot create at workdir root');
  const abs = path.join(workdir, sub);
  await assertRealParentInsideWorkdir(workdir, abs);
  // recursive:false — fail if parent missing or target exists.
  await fs.mkdir(abs, { recursive: false });
  const st = await fs.stat(abs);
  return { relPath: sub, type: 'directory', size: 0, mtimeMs: st.mtimeMs };
}

/**
 * Rename / move a file or directory inside workdir. 同一 workdir 内,from 与
 * to 都走 assertInsideWorkdir 防越界。
 *
 * 冲突策略:
 *   - 目标已存在 → 抛错(留给上层 toast)。大小写仅改写时比较文件身份:
 *     NTFS / HFS+ 默认是 case-insensitive,'Foo.md' → 'foo.md' 指向同一文件,
 *     可以放行;case-sensitive FS 上两个名字也可能是不同文件,不能静默覆盖。
 *   - source 不存在 → fs.rename 自然抛 ENOENT,上层 toast。
 *   - 跨卷不会发生,因为 from/to 都在同一 workdir 下。
 */
export async function renameEntry(
  workdir: string,
  fromRel: string,
  toRel: string,
): Promise<FileStat> {
  const fromSub = assertInsideWorkdir(workdir, fromRel);
  const toSub = assertInsideWorkdir(workdir, toRel);
  if (fromSub === '') throw new Error('cannot rename workdir root');
  if (toSub === '') throw new Error('cannot rename to workdir root');
  if (fromSub === toSub) {
    // no-op,直接返回当前 stat 让上层走刷新逻辑(也可能是大小写在 case-sensitive
    // FS 上重名,但走到这里说明 normalize 后完全相同 → 当 no-op)
    const realFrom = await assertRealPathInsideWorkdir(workdir, path.join(workdir, fromSub));
    const st = await fs.lstat(realFrom);
    return {
      relPath: fromSub,
      type: st.isDirectory() ? 'directory' : 'file',
      size: st.isDirectory() ? 0 : st.size,
      mtimeMs: st.mtimeMs,
    };
  }
  const absFrom = path.join(workdir, fromSub);
  const absTo = path.join(workdir, toSub);
  const realFrom = await assertRealPathInsideWorkdir(workdir, absFrom);
  await assertRealParentInsideWorkdir(workdir, absTo);
  const caseOnly = fromSub.toLowerCase() === toSub.toLowerCase();
  if (caseOnly) {
    try {
      const [fromStat, toStat] = await Promise.all([fs.stat(realFrom), fs.stat(absTo)]);
      if (fromStat.dev !== toStat.dev || fromStat.ino !== toStat.ino) {
        throw new Error(`目标已存在: ${toSub}`);
      }
    } catch (err) {
      const code = (err as NodeJS.ErrnoException).code;
      if (code !== 'ENOENT') throw err;
    }
  } else {
    try {
      await fs.access(absTo);
      throw new Error(`目标已存在: ${toSub}`);
    } catch (err) {
      const code = (err as NodeJS.ErrnoException).code;
      if (code !== 'ENOENT') throw err;
    }
  }
  await fs.rename(realFrom, absTo);
  const st = await fs.lstat(absTo);
  return {
    relPath: toSub,
    type: st.isDirectory() ? 'directory' : 'file',
    size: st.isDirectory() ? 0 : st.size,
    mtimeMs: st.mtimeMs,
  };
}

/**
 * Delete a file or directory inside workdir. Directories are removed
 * recursively. No trash / undo — the caller is expected to have shown a
 * confirm prompt.
 */
export async function deleteEntry(workdir: string, relPath: string): Promise<void> {
  const sub = assertInsideWorkdir(workdir, relPath);
  if (sub === '') throw new Error('cannot delete workdir root');
  const abs = path.join(workdir, sub);
  const realAbs = await assertRealPathInsideWorkdir(workdir, abs);
  // rm with recursive+force handles both file and directory; force only
  // suppresses "not found" which is fine for a delete operation.
  await fs.rm(realAbs, { recursive: true, force: true });
}

/** Cheap stat for the unrenderable placeholder (size + mtime). */
export async function statEntry(
  workdir: string,
  relPath: string,
): Promise<FileStat> {
  const sub = assertInsideWorkdir(workdir, relPath);
  if (sub === '') throw new Error('cannot stat workdir root');
  const realAbs = await assertRealPathInsideWorkdir(workdir, path.join(workdir, sub));
  const st = await fs.stat(realAbs);
  return {
    relPath: sub,
    type: st.isDirectory() ? 'directory' : 'file',
    size: st.isDirectory() ? 0 : st.size,
    mtimeMs: st.mtimeMs,
  };
}

/**
 * Convenience wrapper: load matcher + list root in one call. Used by the
 * IPC handler when the renderer enters MD/file-browse mode for the first
 * time on a workdir.
 */
export async function listRoot(
  workdir: string,
  opts: { hideMetaFiles?: boolean; docMode?: boolean } = {},
): Promise<{ entries: DirEntry[]; matcher: Matcher }> {
  const matcher = await loadIgnoreMatcher(workdir, opts);
  const entries = await listDir(workdir, '', matcher, { docMode: opts.docMode });
  log.debug(`listRoot ${workdir} → ${entries.length} entries`);
  return { entries, matcher };
}