@evandu/super-pi 0.0.0-stage → 0.1.1

package/dist/server/files.js

@@ -0,0 +1,629 @@
+/**
+ * Workspace file browsing and editing.
+ *
+ * ONE RULE GOVERNS THIS FILE, and it is the reason the module exists rather than four functions inside
+ * `index.ts`: a path that arrives from a browser is UNTRUSTED, and the question "does this resolve to
+ * somewhere inside the workspace" has to be answered in exactly one place. Every read, every write,
+ * every directory listing and every search walks through `resolveInsideRoot`. A check that is written
+ * twice is a check that is correct once.
+ *
+ * WHAT THE WORKSPACE ROOT IS, because the requirement says to find this out rather than assume it: it is
+ * `Workspace.path`, the directory the user picked when they created the workspace (`store.ts`
+ * `createWorkspace` stores `path` verbatim; the left rail's directory picker reads `/api/fs/dirs`, which
+ * is why that endpoint exists and why it is deliberately NOT reused here - see the note on it below).
+ * It is the same directory Pi runs in (`index.ts` `turnContext` hands `workspace.path` to every turn as
+ * `cwd`), which is the property that makes "the Files tab shows me what the agent is working on" true
+ * rather than aspirational.
+ *
+ * `/api/fs/dirs` IS NOT A PREDECESSOR OF ANYTHING IN HERE. It resolves whatever absolute path it is
+ * handed, because picking a workspace directory requires naming a directory that does not exist yet -
+ * it is a file picker, not a file reader, and reusing it would import its deliberate absence of
+ * containment straight into the one surface that must have it.
+ *
+ * THE ROOT IS ALSO A SUBJECT OF THIS FILE. `Workspace.path` is a stored string, and a stored string can
+ * name a directory that is no longer there - deleted, renamed, on a drive that is no longer mounted. The
+ * picker cannot create that state (`/api/fs/dirs` only ever lists directories it has just `stat`ed), but
+ * time can. So "does the workspace root exist" is answered here, once, in `realpathOfRoot`, and it is
+ * answered before any question is asked about the path INSIDE it. That ordering is what makes a missing
+ * directory a 404 that names itself instead of a containment failure about a symlink that does not exist.
+ */
+import { createHash } from "node:crypto";
+import { readFile, readdir, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+/**
+ * Above this a read is refused rather than served. 5MB is roughly a large source file or a long document,
+ * and it is deliberately far below the point where an editor tab stops being useful: this panel is for
+ * reading and editing code and markdown, and a file too big for that has not become more editable by
+ * being loaded whole. The size is checked from `stat` BEFORE the read, so an oversized file costs one
+ * `stat` rather than a full buffer.
+ */
+export const MAX_FILE_BYTES = 5 * 1024 * 1024;
+/** Cap on one directory listing, so a `node_modules` or a generated assets folder cannot produce a
+ *  multi-megabyte response. The count is reported as `truncated` rather than applied silently. */
+export const MAX_DIR_ENTRIES = 2000;
+/** Cap on a recursive filename search, for the same reason: a scan of a large repository has to end
+ *  somewhere. The UI says the list was cut rather than pretending it is complete. */
+export const MAX_SEARCH_RESULTS = 500;
+/** How deep the recursive search walks. Twelve levels is past any real source tree; the cap is what
+ *  turns a pathologically deep dependency tree from a hang into a result. */
+export const MAX_SEARCH_DEPTH = 12;
+/** Directories the recursive search skips. The TREE does not skip them - a directory the user cannot
+ *  browse is a directory they cannot inspect a file in, and the binary handling below is only reachable
+ *  if `node_modules` is reachable. A recursive filename search, by contrast, returns thousands of matches
+ *  from these and nothing a person searched for, so they are excluded from the scan and the exclusion is
+ *  reported in the response rather than being invisible. */
+const SEARCH_SKIP_DIRS = new Set([".git", "node_modules", "dist", "build", ".super-pi", ".next", ".cache", "coverage", ".venv"]);
+/**
+ * Extensions that are binary by definition, checked BEFORE any bytes are read.
+ *
+ * This is a fast path, not the real test: a `.ts` file containing PNG bytes still has to be caught, and
+ * it is caught by `looksBinary` below. What this set buys is refusing the obvious cases without opening
+ * them - and, more importantly, refusing them with a MESSAGE that names the reason rather than "invalid
+ * UTF-8", because the person clicking the file wants to know it is an image.
+ */
+const BINARY_EXTENSIONS = new Set([
+    ".png", ".jpg", ".jpeg", ".gif", ".bmp", ".ico", ".webp", ".avif", ".tif", ".tiff", ".heic",
+    ".psd", ".ai", ".eps",
+    ".zip", ".tar", ".gz", ".tgz", ".bz2", ".xz", ".7z", ".rar", ".iso", ".dmg", ".jar", ".war", ".whl",
+    ".exe", ".dll", ".so", ".dylib", ".bin", ".o", ".obj", ".a", ".lib", ".class", ".wasm", ".node",
+    ".pyd", ".msi", ".apk", ".deb", ".rpm",
+    ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx", ".odt", ".ods", ".odp",
+    ".woff", ".woff2", ".ttf", ".otf", ".eot",
+    ".mp3", ".wav", ".flac", ".ogg", ".mp4", ".mov", ".avi", ".mkv", ".webm",
+    ".sqlite", ".sqlite3", ".db", ".pyc", ".pyo", ".pack", ".idx",
+]);
+/**
+ * Extensions this panel OPENS without needing a sniff. It is a hint used only to label a file in the tree
+ * before it is read, and never as a permission: a `.png` is refused by name even if a sniffing pass would
+ * have liked it, and a `.txt` holding PNG bytes is still refused by the sniff.
+ */
+export const TEXT_EXTENSIONS = new Set([
+    ".md", ".markdown", ".mdx", ".txt", ".text", ".log",
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts",
+    ".json", ".jsonc", ".json5", ".yaml", ".yml", ".toml", ".ini", ".cfg", ".conf",
+    ".css", ".scss", ".less", ".html", ".htm", ".xml", ".svg", ".vue", ".svelte", ".astro",
+    ".py", ".rb", ".go", ".rs", ".java", ".kt", ".kts", ".c", ".h", ".cc", ".cpp", ".hpp", ".cs", ".swift",
+    ".sh", ".bash", ".zsh", ".fish", ".ps1", ".bat", ".cmd",
+    ".sql", ".graphql", ".gql", ".proto", ".tf", ".tfvars", ".lua", ".r", ".jl", ".ex", ".exs", ".erl",
+    ".diff", ".patch", ".csv", ".tsv", ".lock",
+]);
+/** The HTTP failure, carried as a status so the route can render it without a second switch. `details` is
+ *  for the cases where the CLIENT can act on more than the sentence - today that is a conflict, where the
+ *  current etag is what lets the UI offer a deliberate "overwrite anyway" instead of a blind one. */
+export class FilesError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, message, code, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.name = "FilesError";
+    }
+}
+/**
+ * Whether `candidate` is `root` itself or something under it.
+ *
+ * THE COMPARISON IS NOT `startsWith(root)`, because that is the traversal bug this whole file exists to
+ * avoid: with root `/home/u/proj`, the string `/home/u/proj-secrets` also starts with `/home/u/proj`.
+ * `relative()` asks the question in the form that can be answered exactly - it returns a path RELATIVE to
+ * the root, so "escaped" becomes "the relative path begins by going up", which is true for
+ * `/home/u/proj/../etc` and false for `/home/u/proj/etc`. `isAbsolute(relative)` catches the case
+ * `relative` cannot express: two different Windows drives, where there is no relative path between them
+ * and it hands back an absolute one.
+ */
+export function contains(root, candidate) {
+    const rel = relative(root, candidate);
+    if (rel === "")
+        return true;
+    // Two drives on Windows, or a relative path that came back absolute. Either way there is no in-bounds
+    // answer, so it is a refusal rather than a comparison.
+    if (isAbsolute(rel))
+        return false;
+    return rel !== ".." && !rel.startsWith(`..${sep}`) && !rel.startsWith("../");
+}
+/**
+ * The syntactic half of the containment check: reject the SHAPES of a path that could escape, before
+ * anything is resolved.
+ *
+ * Every branch here is platform-independent on purpose. A server deployed on Linux must refuse `C:\...`
+ * and `\\server\share`, because a client is free to send them and a Linux build that only knows about `/`
+ * would happily `resolve` `C:\Windows` into a harmless-looking relative path under the root and answer
+ * 200 to a request that should be 403. The tests run on Windows and would not catch that.
+ *
+ * The backslash rewrite is the same decision, and it is a real trade rather than a free win: `\` is a
+ * legal CHARACTER in a POSIX filename, so a file literally named `a\b` is unreachable through this API.
+ * The alternative - honouring `\` only on Windows - buys that filename at the price of the same request
+ * meaning different things on two hosts, which is the more expensive of the two mistakes for a
+ * security check. Every escape form in the requirement is spelled with a backslash, and the check is
+ * worth more than the filename.
+ */
+function rejectUnsafeShape(requested) {
+    // A NUL truncates the path inside every syscall it reaches - `readFile("a\0../../etc")` is `readFile("a")`
+    // as far as libuv is concerned, and the string this function validated is not the string the OS acts on.
+    // Refused before anything is normalised.
+    if (requested.includes("\0"))
+        throw new FilesError(400, "路径包含非法的空字符", "bad_path");
+    // UNC: `\\server\share\...` and its POSIX-spelled twin `//server/share`. Named explicitly because
+    // `isAbsolute` is true for the first on Windows and false for the second on Linux.
+    if (/^[\\/]{2}/.test(requested))
+        throw new FilesError(403, "拒绝 UNC 路径：路径必须在 workspace 内", "outside_workspace");
+    // A drive letter in EITHER position: `C:\x` is absolute, `C:x` is drive-relative and resolves against
+    // that drive's current directory, which is not a location the caller gets to choose. The colon is also
+    // how NTFS alternate data streams are addressed (`notes.md:hidden`), which is a second file hiding
+    // behind one path - handled by the segment check below.
+    if (/^[A-Za-z]:/.test(requested))
+        throw new FilesError(403, "拒绝 Windows 盘符路径：路径必须在 workspace 内", "outside_workspace");
+    // Rooted, POSIX or Windows: `/etc/passwd` and `\Windows`. Both are absolute, and the leading-slash
+    // forms are spelled out so the refusal does not depend on the host's own path parser agreeing.
+    if (requested.startsWith("/") || requested.startsWith("\\"))
+        throw new FilesError(403, "拒绝绝对路径：路径必须在 workspace 内", "outside_workspace");
+    return requested.replace(/\\/g, "/");
+}
+/**
+ * `realpath` of a workspace ROOT, where "does not exist" is a FINDING rather than a fallback.
+ *
+ * This function exists because of a measured failure, not a hypothetical one. With a workspace whose
+ * `path` does not exist, `nearestExistingAncestor` climbs to the nearest directory that DOES exist, gets
+ * handed back something above the root, and the containment test concludes - correctly, for what it was
+ * asked - that the target escaped. The route therefore answered:
+ *
+ *     403 {"error":"路径经符号链接后超出 workspace 范围，已拒绝：","code":"outside_workspace"}
+ *
+ * A security error, about a symlink that does not exist, naming NO PATH, for a workspace whose directory
+ * is simply not there. The user cannot act on that sentence, and the trailing colon shows the other half
+ * of the bug: the root is requested as `""`, so the message interpolates an empty string. A missing
+ * directory is a 404 that says which directory, and it is decided HERE - once, before the symlink half -
+ * so every read, write, listing and search says the same true thing about the same root.
+ *
+ * `realpath` rather than `stat` because the canonical form is needed anyway one line later, and a second
+ * syscall to learn something the first one already told us would be a race. `EACCES`/`EPERM` are named
+ * separately: a directory that exists but cannot be entered is a different mistake from one that was
+ * deleted, and the user needs to be able to tell them apart.
+ */
+async function realpathOfRoot(base) {
+    try {
+        return await realpath(base);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            throw new FilesError(404, `工作区路径不存在：${base}`, "workspace_missing", { path: base });
+        if (code === "EACCES" || code === "EPERM")
+            throw new FilesError(403, `工作区路径无法访问（权限不足）：${base}`, "denied", { path: base });
+        throw error;
+    }
+}
+/**
+ * The nearest ANCESTOR of `target` that exists on disk, canonically.
+ *
+ * Needed because a WRITE targets a file that may legitimately not exist yet, and the symlink half of the
+ * check still has to run on it. Climbing is safe to stop at: by the time the walk has climbed, every
+ * segment below the one it stopped on has been shown not to exist, and a segment that does not exist
+ * cannot itself be a symlink out of the tree.
+ */
+async function nearestExistingAncestor(target) {
+    let current = target;
+    for (;;) {
+        try {
+            return await realpath(current);
+        }
+        catch (error) {
+            const code = error.code;
+            // ENOENT and ENOTDIR are the only two that mean "climb". EACCES and ELOOP are real problems and are
+            // allowed to surface as themselves rather than being turned into a climb that hides them.
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                throw error;
+            const parent = dirname(current);
+            if (parent === current)
+                throw error;
+            current = parent;
+        }
+    }
+}
+/** A guard bound to one workspace root. `resolveInsideRoot` is the one-shot form and is what callers are
+ *  meant to use; the factory exists for the two places that check many paths against the SAME root in one
+ *  request, so the canonical form of the root is resolved once instead of once per entry. */
+export function createRootGuard(root) {
+    const base = resolve(root);
+    let realBase;
+    return async (requested) => {
+        const raw = (requested ?? "").trim();
+        // Empty means "the workspace itself", which is what the tree's root row and a listing of the top
+        // level both send. It is not an error and it is not a wildcard.
+        const target = raw === "" ? base : resolve(base, rejectUnsafeShape(raw));
+        // (1) LEXICAL, on the literal string. Catches `../`, `..\`, `/etc/passwd`, `C:\Windows`,
+        // `\\host\share` and anything else the caller SHAPED to escape, before any syscall touches the disk.
+        if (!contains(base, target))
+            throw new FilesError(403, `路径超出 workspace 范围，已拒绝：${raw}`, "outside_workspace");
+        // NTFS alternate data streams address a SECOND file behind one path. Windows only, because that is
+        // the only platform where the syntax means anything - a POSIX filename may legally contain a colon,
+        // and this check would refuse files that exist and are perfectly safe to read.
+        if (process.platform === "win32") {
+            const inside = target.slice(base.length);
+            if (inside.split(/[\\/]/).some((segment) => segment.includes(":"))) {
+                throw new FilesError(403, `拒绝 NTFS 数据流路径：${raw}`, "outside_workspace");
+            }
+        }
+        // (2) SYMLINK, on the resolved path. Catches a link INSIDE the workspace that points OUT of it - the
+        // one escape that is invisible to the string, because `workspace/link/etc/passwd` is a perfectly
+        // in-bounds spelling of a file somewhere else entirely. Both sides are canonicalised with `realpath`
+        // before comparison, because the root itself is very often reached through a link (on macOS
+        // `/var` -> `/private/var`, and a Windows worktree or junction is routine), so comparing a canonical
+        // target against an uncanonical root would reject every legitimate path.
+        // THE ROOT IS DECIDED FIRST, BEFORE ANY WORK ON THE TARGET, and both halves of that are deliberate.
+        //
+        // `realpathOfRoot` throws 404 `workspace_missing` for a workspace whose directory is gone, so the
+        // climb below can only ever be asked about a directory that exists - which is what makes the
+        // comparison after it mean "this path left the workspace" instead of "the workspace is not there".
+        //
+        // AWAITING IT BEFORE `nearestExistingAncestor` IS ALSO LOAD-BEARING. The first version asked for the
+        // target's canonical form first, and a workspace on a drive letter that does not exist (`Z:\nope`)
+        // then died inside the climb - it reaches the drive root, finds `dirname` unchanged, and rethrows the
+        // raw Node error. That surfaced as `500 {"error":"ENOENT: no such file or directory, realpath 'Z:\\'"}`:
+        // a missing workspace reported as an internal fault, leaking a libuv message. Resolving the root
+        // first means the 404 is always the answer, because the root is always known before the climb starts.
+        //
+        // THE `.catch(() => {})` IS LOAD-BEARING TOO, and it is there because that same first version CRASHED
+        // THE PROCESS on the ordinary missing-directory case. `realBase` is a PROMISE, and creating it and
+        // then awaiting anything else hands the event loop a turn with a rejected promise that has no handler
+        // yet; Node's default for an unhandled rejection is to terminate, so the server died with an uncaught
+        // `FilesError` instead of answering the 404. This attaches a handler at creation time and discards
+        // nothing - the original promise still rejects, and `await` below still receives it.
+        if (realBase === undefined) {
+            const pending = realpathOfRoot(base);
+            pending.catch(() => { });
+            realBase = pending;
+        }
+        const canonicalRoot = await realBase;
+        const realTarget = await nearestExistingAncestor(target);
+        if (!contains(canonicalRoot, realTarget))
+            throw new FilesError(403, `路径经符号链接后超出 workspace 范围，已拒绝：${raw}`, "outside_workspace");
+        return target;
+    };
+}
+/**
+ * THE CONTAINMENT CHECK. Every read, write, listing and search in this file goes through it, and the
+ * route layer is not allowed to do its own path arithmetic.
+ *
+ * `requested` arrives already percent-decoded, because `URLSearchParams` decodes once when the query is
+ * parsed. That is the right number of decodes: `%2e%2e%2f` is `../` by the time it gets here and is
+ * refused by the lexical test, while decoding a SECOND time would turn the harmless literal `%2e%2e%2f`
+ * into a live traversal - inventing an attack the URL parser does not actually have. The route decodes
+ * nothing further and never passes the raw query string down.
+ */
+export function resolveInsideRoot(root, requested) {
+    return createRootGuard(root)(requested);
+}
+/**
+ * The identity of a file's CURRENT bytes, as far as a filesystem can cheaply say.
+ *
+ * Built from size and the nanosecond modification time rather than a content hash: hashing every file on
+ * every read would make opening a tab cost a full pass over the file, and the two fields together already
+ * change on any edit a human would call an edit. `bigint: true` is what makes this exact - the
+ * millisecond float `stat` reports by default rounds two edits inside the same millisecond into one
+ * value, and an external-change check that misses a change is worse than no check at all, because the
+ * user has been told it is safe to save.
+ */
+export async function fileEtag(path) {
+    const info = await stat(path, { bigint: true });
+    return createHash("sha1").update(`${info.size}:${info.mtimeNs}:${info.ino}`).digest("hex").slice(0, 20);
+}
+export async function fileMeta(path) {
+    const [info, etag] = await Promise.all([stat(path), fileEtag(path)]);
+    return { etag, size: Number(info.size), modifiedAt: info.mtime.toISOString() };
+}
+/**
+ * Whether these bytes are text.
+ *
+ * The NUL test is the one that matters and it is the same one git uses for its "binary file" heuristic: a
+ * NUL byte cannot appear in valid UTF-8 text, while every common binary container has one within the
+ * first block. The sample is bounded so classifying a large file does not turn into reading all of it.
+ */
+const BINARY_SNIFF_BYTES = 4096;
+export function looksBinary(sample) {
+    const limit = Math.min(sample.length, BINARY_SNIFF_BYTES);
+    for (let i = 0; i < limit; i++)
+        if (sample[i] === 0)
+            return true;
+    return false;
+}
+/**
+ * Whether the NAME alone says this is binary.
+ *
+ * `endsWith` is the whole test, and the dot is what makes it a suffix test rather than a substring one:
+ * `"tool.bin".endsWith(".bin")` is true and `"foobin".endsWith(".bin")` is false, because the dot has to be
+ * one of the characters being matched. An earlier version added a "the character before the suffix must be
+ * a dot" guard on top of this, which was wrong - it compared the index of the dot AGAINST ITSELF minus
+ * one, so `"photo.png"` was checked at the `o` and came back false. Every binary file was therefore
+ * reaching the byte sniff instead of being refused by name, and the tests only ever passed because the
+ * fixture binaries also contained NUL bytes. A check that is dead code while a second check quietly does
+ * its job is exactly the kind of thing that survives review, which is why `files-api.test.mjs` asserts
+ * the extension path with a fixture whose CONTENT is text.
+ */
+export function hasBinaryExtension(name) {
+    const lower = basename(name).toLowerCase();
+    for (const binary of BINARY_EXTENSIONS) {
+        if (lower.endsWith(binary))
+            return true;
+    }
+    return false;
+}
+/** Whether a file is worth putting in an editor tab at all, decided from its NAME alone, for the tree's
+ *  own labelling. The authoritative answer comes from `readWorkspaceFile`, which reads bytes. */
+export function isTextName(name) {
+    if (hasBinaryExtension(name))
+        return false;
+    const lower = basename(name).toLowerCase();
+    if (lower === "dockerfile" || lower === "makefile" || lower === "license" || lower === "readme")
+        return true;
+    const dot = lower.lastIndexOf(".");
+    if (dot <= 0)
+        return true; // extensionless files are usually source or config; the sniff decides
+    return TEXT_EXTENSIONS.has(lower.slice(dot));
+}
+/** The `/`-separated relative form used on the wire and in every comparison. */
+export function toRelative(root, absolute) {
+    return relative(root, absolute).split(sep).join("/");
+}
+/** One directory's contents. Directories sort before files, then case-insensitively by name with numeric
+ *  ordering, so `src2` lands between `src` and `src10` rather than after every `srcN`. */
+export async function listDirectory(root, requested) {
+    const guard = createRootGuard(root);
+    const target = await guard(requested);
+    const info = await stat(target).catch((error) => {
+        const code = error?.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            throw new FilesError(404, `目录不存在：${toRelative(root, target) || "/"}`, "not_found");
+        if (code === "EACCES" || code === "EPERM")
+            throw new FilesError(403, `权限不足：${toRelative(root, target) || "/"}`, "denied");
+        throw error;
+    });
+    if (!info.isDirectory())
+        throw new FilesError(400, `不是目录：${toRelative(root, target)}`, "not_a_directory");
+    const dirents = await readdir(target, { withFileTypes: true });
+    const entries = [];
+    for (const dirent of dirents) {
+        const absolute = resolve(target, dirent.name);
+        const isLink = dirent.isSymbolicLink();
+        // ONLY a link can leave the workspace. A regular file or directory reached through a path whose
+        // ancestors have all already been resolved cannot be anywhere else - there is no other way to get out
+        // - so running the symlink half of the guard on every entry of a 2000-file directory would be a few
+        // thousand `realpath` calls to re-derive what `isDirectory()` just said. A link is the exception, and
+        // it is the one worth a syscall.
+        let outside = false;
+        if (isLink) {
+            try {
+                await guard(absolute);
+            }
+            catch {
+                outside = true;
+            }
+        }
+        const isDir = dirent.isDirectory();
+        entries.push({
+            path: toRelative(root, absolute),
+            name: dirent.name,
+            kind: outside ? "symlink" : isDir ? "directory" : "file",
+            text: isDir ? null : !outside && isTextName(dirent.name),
+            ...(isLink ? { symlink: true } : {}),
+            ...(outside ? { outside: true } : {}),
+        });
+    }
+    entries.sort((a, b) => {
+        const aFile = a.kind === "file" ? 1 : 0;
+        const bFile = b.kind === "file" ? 1 : 0;
+        if (aFile !== bFile)
+            return aFile - bFile;
+        return a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: "base" });
+    });
+    const relativePath = toRelative(root, target);
+    const truncated = entries.length > MAX_DIR_ENTRIES;
+    return {
+        path: relativePath,
+        parent: relativePath === "" ? null : relativePath.split("/").slice(0, -1).join("/"),
+        entries: truncated ? entries.slice(0, MAX_DIR_ENTRIES) : entries,
+        truncated,
+    };
+}
+/**
+ * A recursive FILENAME search. Filename only, on purpose: content search is a different feature with
+ * different costs - it reads every candidate file, honours the size cap on each one, and it is the thing
+ * that turns a panel into a hang - and the requirement is explicit that this round does not need it.
+ *
+ * Every directory it descends into goes through the SAME guard as every other path here, so the search
+ * cannot be walked out of the workspace by a link, and it stops at `MAX_SEARCH_DEPTH` and
+ * `MAX_SEARCH_RESULTS` so a repository with a vendored dependency tree returns a truncated answer rather
+ * than never returning.
+ */
+export async function searchByName(root, query) {
+    const needle = query.trim().toLowerCase();
+    if (!needle)
+        return { hits: [], truncated: false, skipped: [] };
+    const guard = createRootGuard(root);
+    const hits = [];
+    const skipped = [];
+    let truncated = false;
+    const walk = async (directory, depth) => {
+        if (truncated)
+            return;
+        if (depth > MAX_SEARCH_DEPTH) {
+            truncated = true;
+            return;
+        }
+        let listing;
+        try {
+            listing = await listDirectory(root, directory);
+        }
+        catch (error) {
+            // THE ROOT IS NOT ONE OF THE SKIPPABLE DIRECTORIES. Skipping a subdirectory that cannot be read is
+            // honest - the response says `skipped: [...]` - but skipping the workspace itself produced
+            // `200 {"mode":"search","hits":[],"skipped":["/"]}`, which is byte-for-byte the response for
+            // "I searched and nothing matched". Measured, on a workspace whose path did not exist. A workspace
+            // that is not there is therefore rethrown as the 404 it is: the whole point of reporting `skipped`
+            // is that the client can tell "no matches" from "I could not see everything", and a missing root
+            // is the case where neither is true.
+            if (!directory && error instanceof FilesError)
+                throw error;
+            // An unreadable directory is skipped and REPORTED, not swallowed: a search that silently skips half
+            // a repository and reports "no matches" is worse than one that says where it could not look.
+            if (error instanceof FilesError && (error.status === 403 || error.status === 404)) {
+                skipped.push(directory || "/");
+                return;
+            }
+            throw error;
+        }
+        for (const entry of listing.entries) {
+            if (truncated)
+                return;
+            if (entry.kind === "file") {
+                if (entry.name.toLowerCase().includes(needle)) {
+                    hits.push({ path: entry.path, name: entry.name, directory: entry.path.split("/").slice(0, -1).join("/") });
+                    if (hits.length >= MAX_SEARCH_RESULTS) {
+                        truncated = true;
+                        return;
+                    }
+                }
+                continue;
+            }
+            // A link is never descended: following one is how a search becomes an infinite walk, and the tree
+            // already refuses to expand it.
+            if (entry.kind === "symlink")
+                continue;
+            if (SEARCH_SKIP_DIRS.has(entry.name)) {
+                skipped.push(entry.path);
+                continue;
+            }
+            await walk(entry.path, depth + 1);
+        }
+    };
+    await walk("", 0);
+    hits.sort((a, b) => a.path.localeCompare(b.path, undefined, { numeric: true, sensitivity: "base" }));
+    return { hits, truncated, skipped };
+}
+/**
+ * Read one file, or refuse it with a reason a person can act on.
+ *
+ * ORDER MATTERS and is the whole reason the refusals are trustworthy: extension, then SIZE from `stat`,
+ * then a sniff, then a fatal decode. The size check precedes the read so an oversized file costs a `stat`
+ * rather than a buffer, and the sniff precedes the decode so binary bytes are never handed to
+ * `TextDecoder` as if they were text - a decode that "succeeds" on binary produces U+FFFD throughout,
+ * which is mojibake, and mojibake that then gets SAVED is how a text editor destroys a binary file.
+ */
+export async function readWorkspaceFile(root, requested) {
+    const target = await resolveInsideRoot(root, requested);
+    const info = await stat(target).catch((error) => {
+        const code = error?.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            throw new FilesError(404, `文件不存在：${requested}`, "not_found");
+        if (code === "EACCES" || code === "EPERM")
+            throw new FilesError(403, `权限不足：${requested}`, "denied");
+        throw error;
+    });
+    if (info.isDirectory())
+        throw new FilesError(400, `这是一个目录，不是文件：${requested}`, "not_a_file");
+    if (hasBinaryExtension(target))
+        throw new FilesError(415, `不支持的文件类型（二进制）：${requested}`, "binary");
+    const meta = await fileMeta(target);
+    if (meta.size > MAX_FILE_BYTES) {
+        throw new FilesError(413, `文件过大（${(meta.size / 1024 / 1024).toFixed(1)}MB），上限 ${MAX_FILE_BYTES / 1024 / 1024}MB：${requested}`, "too_large");
+    }
+    const raw = await readFile(target);
+    if (looksBinary(raw))
+        throw new FilesError(415, `不支持的文件类型（二进制内容）：${requested}`, "binary");
+    // `fatal: true` so a truncated multi-byte sequence - a file written by something that cut a UTF-8
+    // character in half - throws here instead of decoding to U+FFFD and being written back on save.
+    let content;
+    try {
+        content = new TextDecoder("utf-8", { fatal: true }).decode(raw);
+    }
+    catch {
+        throw new FilesError(415, `不是有效的 UTF-8 文本，不支持编辑：${requested}`, "binary");
+    }
+    return { path: toRelative(root, target), content, meta, eol: content.includes("\r\n") ? "\r\n" : "\n" };
+}
+/**
+ * Write one EXISTING text file. No creation, no deletion, no rename, no directories.
+ *
+ * THE SCOPE CALL, with its reasoning, because it is a decision and not an omission:
+ *
+ * This panel's stated job is to BROWSE and EDIT what is in the workspace. Creation is refused even though
+ * the brief leaves it open, because creation is the operation where a mistake has no undo: a bad `path`
+ * parameter or a bug that loses one character writes a file the user never asked for and never has to
+ * clean up, whereas a refused write leaves nothing behind. Deletion is deferred by the brief and is
+ * deferred here for the same reason plus the one that matters more - it is irreversible.
+ *
+ * The symmetry is deliberate: create and delete are the two ends of the same axis, and shipping one
+ * without the other is how a "conservative, no surprises" surface becomes a half-built file manager.
+ *
+ * What IS refused regardless: a write to a file that does not exist (428), a write with no `baseEtag` at
+ * all (428 - without one the server cannot tell a save from a blind overwrite, and "may I overwrite" is
+ * not a question this endpoint is allowed to skip), a write whose `baseEtag` no longer matches the file
+ * on disk (409 `stale`), and a write that would push the file past the size cap.
+ *
+ * The write itself is a whole-file replace through a temporary file in the SAME directory and a rename,
+ * so an interrupted save cannot leave a half-written file where a whole one used to be. The temporary name
+ * is derived from the target's OWN name rather than living in the system temp directory, because a rename
+ * across filesystems is not atomic and would silently become a copy.
+ */
+export async function writeWorkspaceFile(root, requested, content, baseEtag) {
+    const target = await resolveInsideRoot(root, requested);
+    const info = await stat(target).catch((error) => {
+        const code = error?.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            throw new FilesError(428, `文件不存在，本面板只允许写入已存在的文件：${requested}`, "missing_target");
+        if (code === "EACCES" || code === "EPERM")
+            throw new FilesError(403, `权限不足：${requested}`, "denied");
+        throw error;
+    });
+    if (info.isDirectory())
+        throw new FilesError(400, `这是一个目录，不能写入：${requested}`, "not_a_file");
+    if (hasBinaryExtension(target))
+        throw new FilesError(415, `拒绝写入二进制文件：${requested}`, "binary");
+    const current = await fileMeta(target);
+    if (!baseEtag)
+        throw new FilesError(428, "缺少 baseEtag：保存必须带上打开时读到的版本标识，否则无法判断文件是否被改动过", "etag_required");
+    if (baseEtag !== current.etag) {
+        // The CURRENT etag travels with the refusal, and that is what makes an informed overwrite possible:
+        // the UI can offer "仍然覆盖" which re-sends THIS etag, rather than a blind write that would succeed
+        // only because the check was skipped once. The refusal is not a dead end - it is a question.
+        throw new FilesError(409, `文件在磁盘上已被其他程序修改，未保存：${requested}`, "stale", {
+            path: toRelative(root, target),
+            current,
+            yourEtag: baseEtag,
+        });
+    }
+    const bytes = Buffer.byteLength(content, "utf8");
+    if (bytes > MAX_FILE_BYTES)
+        throw new FilesError(413, `写入内容过大（${(bytes / 1024 / 1024).toFixed(1)}MB），上限 ${MAX_FILE_BYTES / 1024 / 1024}MB`, "too_large");
+    // A save must not turn a text file into a binary one, so the sniff that guards the read guards the
+    // write: a NUL arriving through a paste would otherwise be written to disk and make the file unreadable
+    // to this panel ever after.
+    if (looksBinary(Buffer.from(content, "utf8")))
+        throw new FilesError(415, "拒绝写入：内容包含二进制字节（\\0）", "binary");
+    const temporary = `${target}.super-pi-${process.pid}-${Date.now().toString(36)}.tmp`;
+    try {
+        await writeFile(temporary, content, "utf8");
+        await rename(temporary, target);
+    }
+    catch (error) {
+        // The temporary file is the ONLY thing this function can leave behind, and it is the one thing that
+        // must never survive a failed save.
+        await unlink(temporary).catch(() => { });
+        throw error;
+    }
+    return { path: toRelative(root, target), meta: await fileMeta(target), created: false };
+}
+/** Every `FilesError` carries the status it should be rendered with; anything else is a real fault and
+ *  becomes a 500 rather than being dressed up as a refusal the user is asked to understand. */
+export function describe(error) {
+    if (error instanceof FilesError)
+        return { status: error.status, body: { error: error.message, code: error.code, ...(error.details ? { details: error.details } : {}) } };
+    const code = error?.code;
+    if (code === "EACCES" || code === "EPERM")
+        return { status: 403, body: { error: "权限不足，无法访问该路径", code: "denied" } };
+    if (code === "ELOOP")
+        return { status: 403, body: { error: "符号链接循环，已拒绝", code: "outside_workspace" } };
+    return { status: 500, body: { error: error instanceof Error ? error.message : "文件操作失败", code: "internal" } };
+}

package/dist/server/http-server.d.ts

@@ -0,0 +1,20 @@
+import { type Server as NodeHttpServer } from "node:http";
+import type { ServerContext } from "./server-context.js";
+/**
+ * Checks if the remote address is a local loopback interface.
+ */
+export declare function isLoopbackAddress(remoteAddress: string | undefined): boolean;
+/**
+ * Checks whether an incoming HTTP request satisfies access token authorization.
+ */
+export declare function isAuthorized(request: {
+    headers: Record<string, string | string[] | undefined>;
+}, accessToken?: string): boolean;
+export interface HttpServerOptions {
+    context: ServerContext;
+    onShutdown: (reason: string) => void;
+}
+/**
+ * Creates the HTTP server providing static client assets and all `/api/*` endpoints.
+ */
+export declare function createHttpServer(options: HttpServerOptions): NodeHttpServer;