jishushell 0.4.30 → 0.5.15

package/dist/services/files-manager.js

@@ -0,0 +1,1075 @@
+/**
+ * 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/\` — Panel-private AI metadata
+
+This directory is **maintained by the JishuShell panel**, 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 panel.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);
+        db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS docs USING fts5(
+        sha256 UNINDEXED,
+        path,
+        content,
+        tags
+      )
+    `);
+        this._indexDb = db;
+        // 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);
+        let hits;
+        if (opts?.pathPrefix) {
+            // Escape LIKE special chars in prefix
+            const escaped = opts.pathPrefix.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_");
+            const likePattern = `${escaped}%`;
+            const rows = db.prepare(`SELECT path, sha256,
+                snippet(docs, 2, '<b>', '</b>', '…', 16) AS snippet,
+                bm25(docs) AS score
+         FROM docs
+         WHERE docs MATCH ?
+           AND path LIKE ? ESCAPE '\\'
+         ORDER BY score
+         LIMIT ?`).all(q, likePattern, limit);
+            hits = rows;
+        }
+        else {
+            const rows = db.prepare(`SELECT path, sha256,
+                snippet(docs, 2, '<b>', '</b>', '…', 16) AS snippet,
+                bm25(docs) AS score
+         FROM docs
+         WHERE docs MATCH ?
+         ORDER BY score
+         LIMIT ?`).all(q, limit);
+            hits = rows;
+        }
+        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);
+}
+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