jishushell 0.6.5 → 0.7.3

package/dist/services/files-manager.js

@@ -1,1156 +0,0 @@
-/**
- * FilesManager — POSIX file CRUD for `~/.jishushell/files/` (M1 W1 PR-3).
- *
- * Source-of-truth: real filesystem (POSIX). sqlite indexing comes in W5
- * (NAS module) but does not change the truth model.
- *
- * Streaming-first:
- *   - readStream()  → fs.createReadStream
- *   - writeStream() → atomicWriteStream (tmp + sha256 transform + fsync + rename)
- *
- * ETag policy (W1):
- *   - Weak ETag W/"<size>-<mtime_ms>" — no sha256 scan on GET
- *   - If-Match uses weak comparison
- *   - Strong ETag (sha256 from index) added in W5
- *
- * Soft delete:
- *   - DELETE moves to ~/.jishushell/files/.trash/{YYYY-MM-DD}/{name}.{epoch}
- *   - 30-day retention cleaner is W7+; W1 just creates the directory
- */
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { createHash } from "node:crypto";
-import { DatabaseSync } from "node:sqlite";
-import { resolveSafe, isHidden, PathSafetyError, } from "../utils/path-safety.js";
-import { atomicWriteStream } from "../utils/safe-write.js";
-import { withPathLock } from "../utils/path-locks.js";
-import { safeWriteJson, safeReadJson } from "../utils/safe-json.js";
-import { FILES_ROOT, FILES_TRASH_DIR, FILES_AUDIT_LOG, } from "../config.js";
-import { resolveAcrossMounts, } from "./external-mounts.js";
-import { homedir } from "node:os";
-export class FilesError extends Error {
-    code;
-    httpStatus;
-    constructor(message, code, httpStatus) {
-        super(message);
-        this.code = code;
-        this.httpStatus = httpStatus;
-        this.name = "FilesError";
-    }
-}
-// ── Defaults ─────────────────────────────────────────
-const DEFAULT_BLOCKED_EXTENSIONS = new Set([
-    ".exe",
-    ".bat",
-    ".cmd",
-    ".ps1",
-    ".sh",
-    ".bash",
-    ".zsh",
-    ".com",
-    ".scr",
-    ".msi",
-    ".app",
-]);
-const DEFAULT_QUOTA_MB = 10240; // 10 GB
-const DEFAULT_MAX_UPLOAD_MB = 50;
-const DEFAULT_TEXT_PREVIEW_KB = 256;
-// Extensions treated as indexable text even when MIME is not text/*
-const INDEXABLE_EXTS = new Set([
-    ".md", ".txt", ".log", ".csv", ".tsv", ".json", ".yaml", ".yml",
-    ".toml", ".ini", ".cfg", ".js", ".ts", ".tsx", ".jsx", ".mjs", ".cjs",
-    ".py", ".rb", ".go", ".rs", ".java", ".c", ".cpp", ".h", ".hpp",
-    ".sh", ".html", ".css", ".xml", ".sql",
-]);
-// Minimal MIME map covering the formats Files Tab actually previews +
-// common archive/binary types. Avoid pulling a 100KB dep for W1.
-const MIME_MAP = {
-    ".txt": "text/plain; charset=utf-8",
-    ".md": "text/markdown; charset=utf-8",
-    ".json": "application/json",
-    ".yaml": "application/yaml",
-    ".yml": "application/yaml",
-    ".csv": "text/csv; charset=utf-8",
-    ".log": "text/plain; charset=utf-8",
-    ".html": "text/html; charset=utf-8",
-    ".css": "text/css; charset=utf-8",
-    ".js": "application/javascript",
-    ".ts": "application/typescript",
-    ".xml": "application/xml",
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".png": "image/png",
-    ".webp": "image/webp",
-    ".gif": "image/gif",
-    ".svg": "image/svg+xml",
-    ".bmp": "image/bmp",
-    ".pdf": "application/pdf",
-    ".mp3": "audio/mpeg",
-    ".wav": "audio/wav",
-    ".ogg": "audio/ogg",
-    ".mp4": "video/mp4",
-    ".webm": "video/webm",
-    ".mov": "video/quicktime",
-    ".zip": "application/zip",
-    ".tar": "application/x-tar",
-    ".gz": "application/gzip",
-};
-function lookupMime(p) {
-    const ext = path.extname(p).toLowerCase();
-    return MIME_MAP[ext] ?? "application/octet-stream";
-}
-// ── AI-FS W4: Knowledge-dir README ───────────────────
-const KNOWLEDGE_README_TEMPLATE = `# \`.knowledge/\` — Core-managed AI metadata
-
-This directory is **maintained by JishuShell core**, not by you.
-
-It stores two kinds of artifacts that let the AI agent answer questions about
-your files without re-reading them from scratch each time:
-
-- **\`index.sqlite\`** — FTS5 full-text search index over text / markdown / code /
-  json / yaml content under \`~/.jishushell/files/\`. Rebuilt on demand when the
-  agent calls \`drive_reindex\`. Never auto-rebuilt on file changes.
-- **\`<sha256>.json\`** — Per-file metadata sidecars. Each file is keyed by its
-  content hash, not its path, so renaming a file does not lose its tags or
-  notes. Schema: \`{ schema_version, sha256, size, mtime, indexed_at, tags?,
-  summary?, links?, agent_notes?, ... }\`.
-
-## Why it's here, not somewhere hidden
-
-You own this filesystem. We surface \`.knowledge/\` instead of stashing state
-inside a database the panel keeps to itself, so backups, snapshots, and
-disaster recovery work without coordinating with the panel. If you copy
-\`~/.jishushell/files/\` to another machine, the AI knowledge moves with it.
-
-## Safe to do
-
-- **Browse it** — to satisfy curiosity.
-- **Back it up** — it's part of your data, treat it like the rest of the tree.
-- **Delete the whole directory** — the panel will recreate it next time the
-  agent uses \`drive_*\` tools; you just lose the cached index and any
-  agent-authored notes/tags.
-
-## Don't do
-
-- **Don't hand-edit** \`<sha256>.json\` files. Use the agent (or a future panel
-  UI) to write metadata. Hand-edits work but are not validated — easy to
-  corrupt schemas.
-- **Don't rename or move this directory** — the panel hard-codes the path.
-
-## Want to ignore it?
-
-Filebrowser shows hidden dotfiles by default. If \`.knowledge/\` clutter bothers
-you, toggle "Hide dotfiles" in your Filebrowser user settings; the panel doesn't
-care whether you see it or not.
-
-— jishushell @ AI-FS v1
-`;
-// ── Class ────────────────────────────────────────────
-export class FilesManager {
-    filesRoot;
-    trashRoot;
-    auditLog;
-    quotaMb;
-    maxUploadMb;
-    textPreviewMaxKb;
-    blockedExtensions;
-    externalMounts;
-    _indexDb = null;
-    _indexDbRegistered = false;
-    constructor(cfg = {}) {
-        this.filesRoot = cfg.filesRoot ?? FILES_ROOT;
-        this.trashRoot = cfg.trashRoot ?? FILES_TRASH_DIR;
-        this.auditLog = cfg.auditLog ?? FILES_AUDIT_LOG;
-        this.quotaMb = cfg.quotaMb ?? DEFAULT_QUOTA_MB;
-        this.maxUploadMb = cfg.maxUploadMb ?? DEFAULT_MAX_UPLOAD_MB;
-        this.textPreviewMaxKb = cfg.textPreviewMaxKb ?? DEFAULT_TEXT_PREVIEW_KB;
-        this.blockedExtensions =
-            cfg.blockedExtensions ?? DEFAULT_BLOCKED_EXTENSIONS;
-        this.externalMounts = cfg.externalMounts ?? [];
-        fs.mkdirSync(this.filesRoot, { recursive: true });
-    }
-    /**
-     * Replace the current external-mount set; used when core.json is
-     * mutated through routes/external-mounts.ts so a new mount becomes
-     * visible without restarting the server.
-     */
-    setExternalMounts(mounts) {
-        this.externalMounts = [...mounts];
-    }
-    // ── Listing ─────────────────────────────────────
-    async list(relPath, opts = {}) {
-        const abs = this.resolve(relPath);
-        const stat = this.statOrThrow(abs);
-        if (!stat.isDirectory()) {
-            throw new FilesError("not a directory", "not-dir", 400);
-        }
-        const showHidden = opts.showHidden === true;
-        const names = fs.readdirSync(abs);
-        const entries = [];
-        for (const name of names) {
-            if (!showHidden && name.startsWith("."))
-                continue;
-            const childAbs = path.join(abs, name);
-            let childStat;
-            try {
-                // lstat: do NOT follow symlinks during listing (defense layer 3)
-                childStat = fs.lstatSync(childAbs);
-            }
-            catch {
-                continue;
-            }
-            // Skip symlinks entirely from listings — present as a separate concept
-            // if/when we want them. W1 hides them.
-            if (childStat.isSymbolicLink())
-                continue;
-            const entry = {
-                name,
-                is_dir: childStat.isDirectory(),
-                size: childStat.isDirectory() ? 0 : childStat.size,
-                mtime: Math.floor(childStat.mtimeMs / 1000),
-                etag: makeWeakETag(childStat),
-            };
-            if (entry.is_dir) {
-                try {
-                    entry.child_count = fs.readdirSync(childAbs).length;
-                }
-                catch {
-                    /* ignore */
-                }
-            }
-            else {
-                entry.mime = lookupMime(name);
-            }
-            entries.push(entry);
-        }
-        // Merge external mount aliases as virtual entries when listing the
-        // root. Mounts inside subdirectories are not (intentionally) — keep
-        // mount surface flat at the top of files/.
-        if (relPath === "" && this.externalMounts.length > 0) {
-            const seen = new Set(entries.map((e) => e.name));
-            for (const m of this.externalMounts) {
-                if (seen.has(m.alias))
-                    continue; // real entry shadows the mount
-                const mountRoot = m.host_path.startsWith("~")
-                    ? path.join(homedir(), m.host_path.slice(1))
-                    : path.resolve(m.host_path);
-                let mtime = 0;
-                let childCount;
-                try {
-                    const s = fs.statSync(mountRoot);
-                    mtime = Math.floor(s.mtimeMs / 1000);
-                    if (s.isDirectory()) {
-                        try {
-                            childCount = fs.readdirSync(mountRoot).filter((n) => !n.startsWith(".")).length;
-                        }
-                        catch {
-                            /* permission denied — fine, leave undefined */
-                        }
-                    }
-                }
-                catch {
-                    /* host path missing — still surface the alias so user sees the
-                       configuration even if the underlying directory is unavailable */
-                }
-                entries.push({
-                    name: m.alias,
-                    is_dir: true,
-                    size: 0,
-                    mtime,
-                    etag: `W/"mount-${m.alias}-${mtime}"`,
-                    child_count: childCount,
-                });
-            }
-        }
-        entries.sort(sortDirsFirst);
-        const quota = await this.quota();
-        return {
-            path: relPath,
-            entries,
-            quota_mb: quota.quota_mb,
-            used_mb: quota.used_mb,
-            available_mb: quota.available_mb,
-        };
-    }
-    // ── Reading ─────────────────────────────────────
-    async readStream(relPath) {
-        const abs = this.resolve(relPath);
-        const stat = this.statOrThrow(abs);
-        if (stat.isDirectory()) {
-            throw new FilesError("path is a directory", "is-dir", 400);
-        }
-        return {
-            openStream: () => fs.createReadStream(abs),
-            etag: makeWeakETag(stat),
-            mime: lookupMime(relPath),
-            size: stat.size,
-            mtime: Math.floor(stat.mtimeMs / 1000),
-        };
-    }
-    async readSmall(relPath, maxBytes) {
-        const abs = this.resolve(relPath);
-        const stat = this.statOrThrow(abs);
-        if (stat.isDirectory()) {
-            throw new FilesError("path is a directory", "is-dir", 400);
-        }
-        const target = Math.min(stat.size, maxBytes);
-        const fd = fs.openSync(abs, "r");
-        let buf = Buffer.alloc(target);
-        try {
-            let offset = 0;
-            while (offset < target) {
-                const got = fs.readSync(fd, buf, offset, target - offset, offset);
-                if (got === 0)
-                    break;
-                offset += got;
-            }
-            buf = buf.subarray(0, offset);
-        }
-        finally {
-            fs.closeSync(fd);
-        }
-        return {
-            buf,
-            etag: makeWeakETag(stat),
-            mime: lookupMime(relPath),
-            truncated: stat.size > maxBytes,
-            size: stat.size,
-        };
-    }
-    // ── Writing ─────────────────────────────────────
-    async writeStream(relPath, source, opts = {}) {
-        if (relPath === "") {
-            throw new FilesError("cannot write to root", "invalid-path", 400);
-        }
-        this.checkExtension(relPath);
-        this.assertWritable(relPath);
-        const abs = this.resolve(relPath);
-        return withPathLock(abs, async () => {
-            // Defense layer 3 — ancestor symlinks are always rejected;
-            // a symlink AT the target is also rejected (we never write through
-            // a symlink, even with overwrite=true).
-            this.assertNoSymlinkInAncestors(abs);
-            let existedBefore = false;
-            let beforeSize = 0;
-            try {
-                const ls = fs.lstatSync(abs);
-                if (ls.isSymbolicLink()) {
-                    throw new FilesError("target is a symlink", "symlink", 400);
-                }
-                if (ls.isDirectory()) {
-                    throw new FilesError("target is a directory", "is-dir", 400);
-                }
-                existedBefore = true;
-                beforeSize = ls.size;
-            }
-            catch (e) {
-                if (e instanceof FilesError)
-                    throw e;
-                if (e.code !== "ENOENT")
-                    throw e;
-            }
-            if (existedBefore && opts.overwrite !== true) {
-                throw new FilesError("target exists (use overwrite=true)", "exists", 409);
-            }
-            if (existedBefore && opts.ifMatch !== undefined) {
-                const currentETag = makeWeakETag(fs.lstatSync(abs));
-                if (!weakETagMatch(opts.ifMatch, currentETag)) {
-                    throw new FilesError("If-Match did not match current ETag", "etag-mismatch", 412);
-                }
-            }
-            // Pre-check quota using expectedSize when available
-            if (opts.expectedSize !== undefined) {
-                const delta = opts.expectedSize - beforeSize;
-                if (delta > 0)
-                    await this.assertQuotaAvailable(delta);
-                if (opts.expectedSize >
-                    this.maxUploadMb * 1024 * 1024) {
-                    throw new FilesError(`file size exceeds max_upload_mb=${this.maxUploadMb}`, "too-large", 413);
-                }
-            }
-            fs.mkdirSync(path.dirname(abs), { recursive: true });
-            const result = await atomicWriteStream(abs, source, {
-                expectedSize: opts.expectedSize,
-            });
-            // Defensive: re-check size against max_upload_mb in case expectedSize
-            // was not provided (e.g. chunked client). If exceeded, soft-delete.
-            const finalStat = fs.lstatSync(abs);
-            if (finalStat.size > this.maxUploadMb * 1024 * 1024) {
-                // Move to trash so we don't lose user data, then throw
-                try {
-                    await this.removeInternal(abs, relPath);
-                }
-                catch {
-                    /* best-effort */
-                }
-                throw new FilesError(`file size exceeds max_upload_mb=${this.maxUploadMb}`, "too-large", 413);
-            }
-            const etag = makeWeakETag(finalStat);
-            this.audit("write", relPath, { size: result.size });
-            return { etag, size: result.size, mime: lookupMime(relPath) };
-        });
-    }
-    // ── mkdir / move / remove ───────────────────────
-    async mkdir(relPath) {
-        if (relPath === "") {
-            throw new FilesError("cannot mkdir root", "invalid-path", 400);
-        }
-        this.assertWritable(relPath);
-        const abs = this.resolve(relPath);
-        this.assertNoSymlinkInAncestors(abs);
-        try {
-            const ls = fs.lstatSync(abs);
-            if (ls.isSymbolicLink()) {
-                throw new FilesError("path is a symlink", "symlink", 400);
-            }
-            throw new FilesError("path already exists", "exists", 409);
-        }
-        catch (e) {
-            if (e instanceof FilesError)
-                throw e;
-            if (e.code !== "ENOENT")
-                throw e;
-        }
-        fs.mkdirSync(abs, { recursive: true });
-        this.audit("mkdir", relPath);
-    }
-    async move(fromRel, toRel, overwrite = false) {
-        if (fromRel === "" || toRel === "") {
-            throw new FilesError("cannot move root", "invalid-path", 400);
-        }
-        this.assertWritable(fromRel); // moving FROM a ro mount = removing
-        this.assertWritable(toRel); // moving TO   a ro mount = creating
-        const fromAbs = this.resolve(fromRel);
-        const toAbs = this.resolve(toRel);
-        this.checkExtension(toRel);
-        // Defense layer 3 on both endpoints
-        this.assertNoSymlinkInAncestors(fromAbs);
-        this.assertNoSymlinkInAncestors(toAbs);
-        let fromLstat;
-        try {
-            fromLstat = fs.lstatSync(fromAbs);
-        }
-        catch (e) {
-            if (e.code === "ENOENT") {
-                throw new FilesError("source not found", "not-found", 404);
-            }
-            throw e;
-        }
-        if (fromLstat.isSymbolicLink()) {
-            throw new FilesError("source is a symlink", "symlink", 400);
-        }
-        // Lock both paths in deterministic order to avoid deadlock
-        const sorted = [fromAbs, toAbs].sort();
-        const [first, second] = [sorted[0], sorted[1]];
-        return withPathLock(first, () => withPathLock(second, async () => {
-            try {
-                const toLstat = fs.lstatSync(toAbs);
-                if (toLstat.isSymbolicLink()) {
-                    throw new FilesError("target is a symlink", "symlink", 400);
-                }
-                if (!overwrite) {
-                    throw new FilesError("target exists", "exists", 409);
-                }
-            }
-            catch (e) {
-                if (e instanceof FilesError)
-                    throw e;
-                if (e.code !== "ENOENT")
-                    throw e;
-            }
-            fs.mkdirSync(path.dirname(toAbs), { recursive: true });
-            fs.renameSync(fromAbs, toAbs);
-            this.audit("move", fromRel, { to: toRel });
-        }));
-    }
-    async remove(relPath) {
-        if (relPath === "") {
-            throw new FilesError("cannot remove root", "invalid-path", 400);
-        }
-        this.assertWritable(relPath);
-        const abs = this.resolve(relPath);
-        this.assertNoSymlinkInAncestors(abs);
-        let ls;
-        try {
-            ls = fs.lstatSync(abs);
-        }
-        catch (e) {
-            if (e.code === "ENOENT") {
-                throw new FilesError("path not found", "not-found", 404);
-            }
-            throw e;
-        }
-        if (ls.isSymbolicLink()) {
-            throw new FilesError("cannot remove symlink", "symlink", 400);
-        }
-        return withPathLock(abs, () => this.removeInternal(abs, relPath));
-    }
-    async removeInternal(abs, relPath) {
-        const trashDay = path.join(this.trashRoot, ymd());
-        fs.mkdirSync(trashDay, { recursive: true });
-        const baseName = path.basename(abs);
-        const ts = Date.now();
-        const trashTarget = path.join(trashDay, `${baseName}.${ts}`);
-        fs.renameSync(abs, trashTarget);
-        this.audit("remove", relPath, { trash: trashTarget });
-    }
-    // ── Path resolution ─────────────────────────────
-    /**
-     * Resolve a files/-relative path to its absolute host filesystem path.
-     *
-     * Why a public API: the drive-shim (and the agents that call it via MCP)
-     * needs to hand the resulting absolute path to IM channel plugins
-     * (Feishu / WeChat / Telegram / ...) that send files. Those plugins read
-     * from the local filesystem, not via HTTP. The OpenClaw container runs
-     * with host==container bind mounts (see buildVolumes in
-     * src/services/runtime/adapters/openclaw.ts), so the same absolute
-     * string is valid on both sides; raw_exec / process service managers
-     * run the agent natively on the host, where the path is also directly
-     * usable.
-     *
-     * External mounts: a path whose first segment is an external mount
-     * alias resolves into the mount's host_path. The returned abs_path
-     * points at the real host location; external_mount is set so the
-     * caller can warn the user that this is outside files/. mode is
-     * propagated so writers know if it's read-only.
-     *
-     * Symlink policy: if the path resolves to a symlink we still surface
-     * the abs_path (callers may legitimately want to know where it points
-     * conceptually), but exists is reported as false to discourage handing
-     * symlinks to channel plugins.
-     */
-    async resolveLocalPath(relPath) {
-        const r = this.resolveOp(relPath);
-        const out = {
-            abs_path: r.abs,
-            exists: false,
-        };
-        if (r.ext) {
-            out.external_mount = r.ext.alias;
-            out.external_mount_mode = r.ext.mode;
-        }
-        try {
-            const ls = fs.lstatSync(r.abs);
-            if (ls.isSymbolicLink()) {
-                return out; // exists stays false; symlinks are not handed out
-            }
-            out.exists = true;
-            out.is_dir = ls.isDirectory();
-            out.size = ls.size;
-            out.mtime = Math.floor(ls.mtimeMs / 1000);
-        }
-        catch (e) {
-            if (e?.code !== "ENOENT" && e?.code !== "ENOTDIR") {
-                throw new FilesError(`stat failed: ${e.message}`, "stat", 500);
-            }
-        }
-        return out;
-    }
-    // ── Quota ───────────────────────────────────────
-    async quota() {
-        const used = dirSize(this.filesRoot, this.trashRoot);
-        const trash = fs.existsSync(this.trashRoot) ? dirSize(this.trashRoot) : 0;
-        const usedMb = used / (1024 * 1024);
-        const trashMb = trash / (1024 * 1024);
-        return {
-            quota_mb: this.quotaMb,
-            used_mb: round(usedMb),
-            available_mb: round(Math.max(0, this.quotaMb - usedMb)),
-            trash_mb: round(trashMb),
-        };
-    }
-    async assertQuotaAvailable(deltaBytes) {
-        if (deltaBytes <= 0)
-            return;
-        const q = await this.quota();
-        const availBytes = q.available_mb * 1024 * 1024;
-        if (deltaBytes > availBytes) {
-            throw new FilesError("quota exceeded", "quota", 507);
-        }
-    }
-    // ── Audit ───────────────────────────────────────
-    audit(op, relPath, meta = {}) {
-        try {
-            const line = JSON.stringify({
-                ts: Math.floor(Date.now() / 1000),
-                op,
-                path: relPath,
-                ...meta,
-            }) + "\n";
-            fs.mkdirSync(path.dirname(this.auditLog), { recursive: true });
-            fs.appendFileSync(this.auditLog, line);
-        }
-        catch (e) {
-            console.warn(`[files-audit] failed: ${e.message}`);
-        }
-    }
-    // ── Internals ───────────────────────────────────
-    /**
-     * Resolve a files/-relative path. If the first segment matches a
-     * registered external mount alias the path is virtualized into the
-     * mount's host_path; otherwise the path resolves under FILES_ROOT.
-     *
-     * Symlink defense (assertNoSymlinkInAncestors) and lstat checks in
-     * the calling op still run on the absolute path returned here, so
-     * symlinks INSIDE an external mount are still rejected.
-     */
-    resolve(relPath) {
-        return this.resolveOp(relPath).abs;
-    }
-    resolveOp(relPath) {
-        if (this.externalMounts.length > 0) {
-            const m = resolveAcrossMounts(relPath, this.externalMounts);
-            if (m) {
-                const mountRoot = m.mount.host_path.startsWith("~")
-                    ? path.join(homedir(), m.mount.host_path.slice(1))
-                    : path.resolve(m.mount.host_path);
-                try {
-                    const abs = resolveSafe(mountRoot, m.remainder);
-                    return { abs, ext: m.mount };
-                }
-                catch (e) {
-                    if (e instanceof PathSafetyError) {
-                        throw new FilesError(`invalid path: ${e.message}`, "invalid-path", 400);
-                    }
-                    throw e;
-                }
-            }
-        }
-        try {
-            return { abs: resolveSafe(this.filesRoot, relPath), ext: null };
-        }
-        catch (e) {
-            if (e instanceof PathSafetyError) {
-                throw new FilesError(`invalid path: ${e.message}`, "invalid-path", 400);
-            }
-            throw e;
-        }
-    }
-    /**
-     * Refuse mutations that target a read-only external mount. Called by
-     * write / move / delete / mkdir before any fs work.
-     */
-    assertWritable(rel) {
-        const r = this.resolveOp(rel);
-        if (r.ext && r.ext.mode === "ro") {
-            throw new FilesError(`mount "${r.ext.alias}" is read-only`, "read-only", 403);
-        }
-    }
-    /**
-     * Defense layer 3 (per path-safety.ts header): refuse symlinks at the
-     * target path AND refuse paths that traverse a symlink in their parent
-     * chain inside the trust root.
-     *
-     * For external mounts the trust root is the mount's host_path (the
-     * user explicitly chose that directory; symlinks inside it are their
-     * own filesystem and not an attack we need to defend against). For
-     * regular files/ paths the trust root is FILES_ROOT.
-     */
-    statOrThrow(abs) {
-        try {
-            const ls = fs.lstatSync(abs);
-            if (ls.isSymbolicLink()) {
-                throw new FilesError("symlink target is not allowed", "symlink", 400);
-            }
-            this.assertNoSymlinkInAncestors(abs);
-            return fs.statSync(abs);
-        }
-        catch (e) {
-            if (e instanceof FilesError)
-                throw e;
-            if (e.code === "ENOENT") {
-                throw new FilesError("path not found", "not-found", 404);
-            }
-            throw e;
-        }
-    }
-    /**
-     * Walk up from `abs` toward the relevant trust root and refuse if any
-     * intermediate component is a symlink. Trust root is FILES_ROOT for
-     * regular paths and the matching external-mount host_path for paths
-     * that fall inside an external mount.
-     */
-    assertNoSymlinkInAncestors(abs) {
-        const trustRoot = this.trustRootFor(abs);
-        let cur = path.dirname(abs);
-        while (cur.length >= trustRoot.length && cur !== path.dirname(cur)) {
-            if (cur === trustRoot)
-                return;
-            try {
-                const s = fs.lstatSync(cur);
-                if (s.isSymbolicLink()) {
-                    throw new FilesError("path traverses a symlink ancestor", "symlink", 400);
-                }
-            }
-            catch (e) {
-                if (e instanceof FilesError)
-                    throw e;
-                if (e.code !== "ENOENT")
-                    throw e;
-                // missing intermediate is OK — write side may create it
-            }
-            cur = path.dirname(cur);
-        }
-    }
-    /**
-     * Find the trust root for an absolute path: either an external mount's
-     * host_path (if abs is inside one) or FILES_ROOT.
-     */
-    trustRootFor(abs) {
-        for (const m of this.externalMounts) {
-            const root = m.host_path.startsWith("~")
-                ? path.join(homedir(), m.host_path.slice(1))
-                : path.resolve(m.host_path);
-            if (abs === root || abs.startsWith(root + path.sep))
-                return root;
-        }
-        return this.filesRoot;
-    }
-    checkExtension(relPath) {
-        const ext = path.extname(relPath).toLowerCase();
-        if (this.blockedExtensions.has(ext)) {
-            throw new FilesError(`extension ${ext} is blocked`, "blocked-ext", 400);
-        }
-    }
-    // ── Knowledge index (AI-FS W3) ───────────────────
-    /**
-     * Returns the knowledge directory path (does NOT create it).
-     */
-    get knowledgeDir() {
-        return path.join(this.filesRoot, ".knowledge");
-    }
-    /**
-     * Returns the SQLite DB path.
-     */
-    get indexDbPath() {
-        return path.join(this.knowledgeDir, "index.sqlite");
-    }
-    /**
-     * Returns the sidecar path for a given sha256.
-     */
-    sidecarPath(sha256) {
-        return path.join(this.knowledgeDir, `${sha256}.json`);
-    }
-    /**
-     * Creates ~/.jishushell/files/.knowledge/ (mode 0700) and, on first
-     * creation only, writes a README.md explaining the directory is
-     * panel-private metadata. README is idempotent: only written when the
-     * file doesn't already exist, never overwritten.
-     */
-    ensureKnowledgeDir() {
-        fs.mkdirSync(this.knowledgeDir, { recursive: true, mode: 0o700 });
-        const readmePath = path.join(this.knowledgeDir, "README.md");
-        if (!fs.existsSync(readmePath)) {
-            try {
-                fs.writeFileSync(readmePath, KNOWLEDGE_README_TEMPLATE, { encoding: "utf8", mode: 0o644 });
-            }
-            catch (e) {
-                try {
-                    this.audit("knowledge-readme-warn", readmePath, { err: e.message });
-                }
-                catch { /* ignore */ }
-            }
-        }
-    }
-    /**
-     * Lazy-initialize the SQLite FTS5 handle. Creates the .knowledge dir
-     * and the schema on first call.
-     */
-    getIndexDb() {
-        if (this._indexDb !== null)
-            return this._indexDb;
-        this.ensureKnowledgeDir();
-        const db = new DatabaseSync(this.indexDbPath);
-        // Migrate a legacy unicode61 index to the trigram tokenizer. unicode61
-        // does not segment CJK (a whole Chinese run becomes one token), so
-        // substring queries like "发票" never match. trigram indexes 3-char
-        // windows, which lets LIKE substring probes hit the index for Chinese.
-        // The index is a derived cache (POSIX is source of truth), so dropping
-        // and rebuilding it is safe.
-        const existing = db
-            .prepare("SELECT sql FROM sqlite_master WHERE type='table' AND name='docs'")
-            .get();
-        const needsMigration = !!existing?.sql && !/\btrigram\b/i.test(existing.sql);
-        if (needsMigration) {
-            db.exec("DROP TABLE docs");
-        }
-        db.exec(`
-      CREATE VIRTUAL TABLE IF NOT EXISTS docs USING fts5(
-        sha256 UNINDEXED,
-        path,
-        content,
-        tags,
-        tokenize='trigram'
-      )
-    `);
-        this._indexDb = db;
-        // After a tokenizer migration the table is empty; repopulate from the
-        // POSIX tree so search isn't blank in the meantime. Fire-and-forget —
-        // getIndexDb() now returns the cached handle, so no re-migration.
-        if (needsMigration) {
-            this.reindex().catch((e) => {
-                this.audit("reindex-error", "", {
-                    err: e?.message,
-                    stack: e?.stack,
-                    reason: "trigram-migration",
-                });
-            });
-        }
-        // Register process.exit close handler once per instance
-        if (!this._indexDbRegistered) {
-            this._indexDbRegistered = true;
-            process.once("beforeExit", () => {
-                try {
-                    this._indexDb?.close();
-                }
-                catch { /* ignore */ }
-            });
-        }
-        return db;
-    }
-    /**
-     * Search the FTS5 index.
-     */
-    async searchIndex(query, opts) {
-        const q = query.trim();
-        if (!q) {
-            throw new FilesError("query must not be empty", "invalid-query", 400);
-        }
-        // Return empty if DB doesn't exist yet (no reindex run)
-        if (!fs.existsSync(this.indexDbPath)) {
-            this.audit("search_index", "", { query: q, hits: 0 });
-            return [];
-        }
-        const db = this.getIndexDb();
-        const limit = Math.min(opts?.limit ?? 20, 100);
-        // High-recall substring matching. Split the query into whitespace-separated
-        // terms; a doc matching ANY term is a candidate, ranked by how many terms it
-        // matches. The trigram tokenizer lets these LIKE substring probes hit the
-        // index (CJK included). Semantic understanding and precise re-ranking are
-        // the agent's job, not the panel's — this is a dumb, high-recall surface.
-        const terms = q.split(/\s+/).filter(Boolean).slice(0, 16);
-        if (terms.length === 0) {
-            this.audit("search_index", "", { query: q, hits: 0 });
-            return [];
-        }
-        const escapeLike = (s) => s.replace(/([\\%_])/g, "\\$1");
-        const perTerm = "(content LIKE ? ESCAPE '\\' OR path LIKE ? ESCAPE '\\' OR tags LIKE ? ESCAPE '\\')";
-        const matchCountExpr = terms
-            .map(() => `(CASE WHEN ${perTerm} THEN 1 ELSE 0 END)`)
-            .join(" + ");
-        const whereExpr = terms.map(() => perTerm).join(" OR ");
-        // Positional params follow SQL text order: the match-count CASEs (SELECT
-        // clause) first, then the WHERE clause, then optional prefix, then limit.
-        const likeParams = [];
-        for (const t of terms) {
-            const pat = `%${escapeLike(t)}%`;
-            likeParams.push(pat, pat, pat);
-        }
-        let rows;
-        if (opts?.pathPrefix) {
-            const prefix = `${escapeLike(opts.pathPrefix)}%`;
-            rows = db.prepare(`SELECT path, sha256, content, (${matchCountExpr}) AS match_count
-         FROM docs
-         WHERE (${whereExpr}) AND path LIKE ? ESCAPE '\\'
-         ORDER BY match_count DESC
-         LIMIT ?`).all(...likeParams, ...likeParams, prefix, limit);
-        }
-        else {
-            rows = db.prepare(`SELECT path, sha256, content, (${matchCountExpr}) AS match_count
-         FROM docs
-         WHERE (${whereExpr})
-         ORDER BY match_count DESC
-         LIMIT ?`).all(...likeParams, ...likeParams, limit);
-        }
-        const hits = rows.map((r) => ({
-            path: r.path,
-            sha256: r.sha256,
-            snippet: buildSnippet(r.content, terms),
-            score: -r.match_count,
-        }));
-        this.audit("search_index", "", { query: q, hits: hits.length });
-        return hits;
-    }
-    /**
-     * Read a sidecar JSON for a file identified by sha256 or path.
-     */
-    async getMeta(args) {
-        let sha256;
-        if (args.sha256) {
-            sha256 = args.sha256.toLowerCase();
-            if (!SHA256_RE.test(sha256)) {
-                throw new FilesError("invalid sha256 format", "invalid-sha256", 400);
-            }
-        }
-        else if (args.path) {
-            // Resolve path and stream-hash the file
-            const abs = this.resolve(args.path);
-            if (!fs.existsSync(abs)) {
-                throw new FilesError("path not found", "not-found", 404);
-            }
-            sha256 = await streamSha256(abs, 64 * 1024 * 1024);
-        }
-        else {
-            throw new FilesError("sha256 or path required", "invalid-args", 400);
-        }
-        this.audit("get_meta", sha256);
-        const sp = this.sidecarPath(sha256);
-        if (!fs.existsSync(sp))
-            return null;
-        const raw = safeReadJson(sp, "get_meta");
-        if (raw === null) {
-            this.audit("get_meta_warn", sha256, { warn: "sidecar malformed, treating as null" });
-            return null;
-        }
-        return raw;
-    }
-    /**
-     * Write (merge or replace) a sidecar for a given sha256.
-     */
-    async setMeta(sha256, payload, opts) {
-        const normalizedSha = sha256.toLowerCase();
-        if (!SHA256_RE.test(normalizedSha)) {
-            throw new FilesError("invalid sha256 format", "invalid-sha256", 400);
-        }
-        // Validate payload is JSON-serializable and within size limit
-        let serialized;
-        try {
-            serialized = JSON.stringify(payload);
-        }
-        catch {
-            throw new FilesError("payload is not JSON-serializable", "invalid-payload", 400);
-        }
-        if (Buffer.byteLength(serialized, "utf8") > 64 * 1024) {
-            throw new FilesError("payload exceeds 64KB limit", "payload-too-large", 413);
-        }
-        const merge = opts?.merge !== false; // default true
-        this.ensureKnowledgeDir();
-        let base = {};
-        if (merge) {
-            const existing = safeReadJson(this.sidecarPath(normalizedSha), "set_meta");
-            if (existing !== null)
-                base = existing;
-        }
-        const now = Math.floor(Date.now() / 1000);
-        const merged = {
-            ...base,
-            ...payload,
-            schema_version: 1,
-            sha256: normalizedSha,
-            indexed_at: now,
-            size: base.size ?? 0,
-            mtime: base.mtime ?? 0,
-        };
-        safeWriteJson(this.sidecarPath(normalizedSha), merged);
-        this.audit("set_meta", normalizedSha, { merge });
-        return merged;
-    }
-    /**
-     * Walk the file tree and upsert text-indexable files into the FTS5 index.
-     */
-    async reindex(opts) {
-        const walkRoot = opts?.pathPrefix
-            ? path.join(this.filesRoot, opts.pathPrefix)
-            : this.filesRoot;
-        const result = { indexed: 0, skipped: 0, errors: 0 };
-        if (!fs.existsSync(walkRoot)) {
-            this.audit("reindex", opts?.pathPrefix ?? "/", result);
-            return result;
-        }
-        const db = this.getIndexDb();
-        const upsertDelete = db.prepare("DELETE FROM docs WHERE sha256 = ?");
-        const upsertInsert = db.prepare("INSERT INTO docs(sha256, path, content, tags) VALUES (?, ?, ?, ?)");
-        const stack = [walkRoot];
-        while (stack.length > 0) {
-            const cur = stack.pop();
-            let entries;
-            try {
-                entries = fs.readdirSync(cur, { withFileTypes: true });
-            }
-            catch (e) {
-                result.errors++;
-                this.audit("reindex-error", cur, { err: e?.message });
-                continue;
-            }
-            for (const entry of entries) {
-                const absEntry = path.join(cur, entry.name);
-                // Compute rel path relative to filesRoot
-                const relEntry = path.relative(this.filesRoot, absEntry);
-                if (entry.isDirectory()) {
-                    // Skip panel-private dirs
-                    if (relEntry === ".knowledge" || relEntry.startsWith(".knowledge" + path.sep))
-                        continue;
-                    if (relEntry === ".trash" || relEntry.startsWith(".trash" + path.sep))
-                        continue;
-                    stack.push(absEntry);
-                    continue;
-                }
-                if (!entry.isFile())
-                    continue;
-                // Skip non-indexable files
-                const mime = lookupMime(entry.name);
-                const ext = path.extname(entry.name).toLowerCase();
-                if (!mime.startsWith("text/") && !INDEXABLE_EXTS.has(ext)) {
-                    result.skipped++;
-                    continue;
-                }
-                try {
-                    // Compute sha256 via streaming (full file) and read up to 512KB for content
-                    const sha = await streamSha256(absEntry);
-                    const stat = fs.statSync(absEntry);
-                    const readBytes = Math.min(stat.size, 512 * 1024);
-                    let content = "";
-                    if (readBytes > 0) {
-                        const fd = fs.openSync(absEntry, "r");
-                        try {
-                            const buf = Buffer.alloc(readBytes);
-                            let off = 0;
-                            while (off < readBytes) {
-                                const got = fs.readSync(fd, buf, off, readBytes - off, off);
-                                if (got === 0)
-                                    break;
-                                off += got;
-                            }
-                            content = buf.subarray(0, off).toString("utf8");
-                        }
-                        finally {
-                            fs.closeSync(fd);
-                        }
-                    }
-                    // Load tags from existing sidecar if present
-                    const sp = this.sidecarPath(sha);
-                    let tags = "";
-                    if (fs.existsSync(sp)) {
-                        const sc = safeReadJson(sp, "reindex");
-                        if (sc?.tags && Array.isArray(sc.tags)) {
-                            tags = sc.tags.join(" ");
-                        }
-                    }
-                    upsertDelete.run(sha);
-                    upsertInsert.run(sha, relEntry, content, tags);
-                    result.indexed++;
-                }
-                catch (e) {
-                    result.errors++;
-                    this.audit("reindex-error", relEntry, { err: e?.message });
-                }
-            }
-        }
-        this.audit("reindex", opts?.pathPrefix ?? "/", result);
-        return result;
-    }
-}
-// ── Helpers ───────────────────────────────────────
-function makeWeakETag(stat) {
-    return `W/"${stat.size}-${Math.floor(stat.mtimeMs)}"`;
-}
-function weakETagMatch(provided, current) {
-    // RFC 7232 weak comparison: strip W/ from both, compare values
-    const strip = (s) => s.replace(/^W\//, "");
-    return strip(provided) === strip(current);
-}
-// Build a `<b>`-highlighted snippet around the first matched term. Replaces
-// FTS5 snippet() (which needs MATCH); we do substring search via LIKE instead.
-const SNIPPET_WINDOW = 30;
-function buildSnippet(content, terms) {
-    if (!content)
-        return "";
-    const lc = content.toLowerCase();
-    let best = -1;
-    let bestLen = 0;
-    for (const t of terms) {
-        const idx = lc.indexOf(t.toLowerCase());
-        if (idx !== -1 && (best === -1 || idx < best)) {
-            best = idx;
-            bestLen = t.length;
-        }
-    }
-    const clean = (s) => s.replace(/\s+/g, " ").trim();
-    if (best === -1) {
-        // Shouldn't happen for a LIKE hit, but degrade gracefully.
-        const head = clean(content.slice(0, SNIPPET_WINDOW * 2));
-        return content.length > SNIPPET_WINDOW * 2 ? `${head}…` : head;
-    }
-    let start = Math.max(0, best - SNIPPET_WINDOW);
-    let end = Math.min(content.length, best + bestLen + SNIPPET_WINDOW);
-    // Don't split a surrogate pair (e.g. CJK Ext-B chars) at the window edges.
-    const cc = (i) => content.charCodeAt(i);
-    if (start > 0 && cc(start) >= 0xdc00 && cc(start) <= 0xdfff)
-        start--;
-    if (end < content.length && cc(end - 1) >= 0xd800 && cc(end - 1) <= 0xdbff)
-        end++;
-    const before = clean(content.slice(start, best));
-    const match = clean(content.slice(best, best + bestLen));
-    const after = clean(content.slice(best + bestLen, end));
-    return `${start > 0 ? "…" : ""}${before}<b>${match}</b>${after}${end < content.length ? "…" : ""}`;
-}
-function ymd() {
-    const d = new Date();
-    const yyyy = d.getFullYear();
-    const mm = String(d.getMonth() + 1).padStart(2, "0");
-    const dd = String(d.getDate()).padStart(2, "0");
-    return `${yyyy}-${mm}-${dd}`;
-}
-function round(n) {
-    return Math.round(n * 10) / 10;
-}
-function sortDirsFirst(a, b) {
-    if (a.is_dir !== b.is_dir)
-        return a.is_dir ? -1 : 1;
-    return a.name.localeCompare(b.name, "zh-CN", { sensitivity: "base" });
-}
-function dirSize(rootAbs, exclude) {
-    if (!fs.existsSync(rootAbs))
-        return 0;
-    let total = 0;
-    const stack = [rootAbs];
-    while (stack.length > 0) {
-        const cur = stack.pop();
-        if (exclude && (cur === exclude || cur.startsWith(exclude + path.sep))) {
-            continue;
-        }
-        let entries;
-        try {
-            entries = fs.readdirSync(cur, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        for (const e of entries) {
-            const full = path.join(cur, e.name);
-            if (e.isSymbolicLink())
-                continue;
-            if (e.isDirectory()) {
-                stack.push(full);
-            }
-            else if (e.isFile()) {
-                try {
-                    total += fs.statSync(full).size;
-                }
-                catch {
-                    /* ignore */
-                }
-            }
-        }
-    }
-    return total;
-}
-// Re-export isHidden so callers don't need a second import for this common check
-export { isHidden };
-// ── Knowledge-index helpers ───────────────────────
-const SHA256_RE = /^[a-f0-9]{64}$/i;
-/**
- * Stream-hash a file with SHA-256 and return the hex digest.
- * Reads the entire file (or up to `maxBytes` for large files) without
- * loading it fully into memory.
- */
-async function streamSha256(absPath, maxBytes) {
-    return new Promise((resolve, reject) => {
-        const hasher = createHash("sha256");
-        const stream = fs.createReadStream(absPath, maxBytes !== undefined ? { end: maxBytes - 1 } : undefined);
-        stream.on("data", (chunk) => hasher.update(chunk));
-        stream.on("end", () => resolve(hasher.digest("hex")));
-        stream.on("error", reject);
-    });
-}
-//# sourceMappingURL=files-manager.js.map