jishushell 0.6.5 → 0.6.18

package/dist/services/files/files-manager.d.ts

@@ -0,0 +1,265 @@
+import { Readable } from "node:stream";
+import { isHidden } from "../../utils/path-safety.js";
+import { type ExternalMount } from "./external-mounts.js";
+export interface DirEntry {
+    name: string;
+    is_dir: boolean;
+    size: number;
+    mtime: number;
+    etag: string;
+    mime?: string;
+    child_count?: number;
+}
+export interface DirListing {
+    path: string;
+    entries: DirEntry[];
+    quota_mb: number;
+    used_mb: number;
+    available_mb: number;
+}
+export interface FileStat {
+    is_dir: boolean;
+    size: number;
+    mtime: number;
+    etag: string;
+    mime?: string;
+}
+export interface ReadStreamResult {
+    /** Lazy: opens the file only when called. Avoids leaking fds in 304 paths. */
+    openStream: () => Readable;
+    etag: string;
+    mime: string;
+    size: number;
+    mtime: number;
+}
+export interface ReadSmallResult {
+    buf: Buffer;
+    etag: string;
+    mime: string;
+    truncated: boolean;
+    size: number;
+}
+export interface WriteOptions {
+    ifMatch?: string;
+    overwrite?: boolean;
+    expectedSize?: number;
+}
+export interface WriteResult {
+    etag: string;
+    size: number;
+    mime: string;
+}
+export interface QuotaInfo {
+    quota_mb: number;
+    used_mb: number;
+    available_mb: number;
+    trash_mb: number;
+}
+export interface FilesManagerConfig {
+    filesRoot?: string;
+    trashRoot?: string;
+    auditLog?: string;
+    quotaMb?: number;
+    maxUploadMb?: number;
+    textPreviewMaxKb?: number;
+    blockedExtensions?: Set<string>;
+    /**
+     * External mount points — virtual subtrees of files/ that resolve
+     * to host paths outside FILES_ROOT. Validated by the caller (typically
+     * loaded from core.json:external_mounts).
+     */
+    externalMounts?: ExternalMount[];
+}
+export declare class FilesError extends Error {
+    code: string;
+    httpStatus: number;
+    constructor(message: string, code: string, httpStatus: number);
+}
+export interface SidecarMeta {
+    schema_version: 1;
+    sha256: string;
+    size: number;
+    mtime: number;
+    indexed_at: number;
+    tags?: string[];
+    summary?: string;
+    links?: Array<{
+        path: string;
+        rel: string;
+    }>;
+    agent_notes?: string;
+    [key: string]: any;
+}
+export interface SearchHit {
+    path: string;
+    sha256: string;
+    snippet: string;
+    score: number;
+}
+export interface ReindexResult {
+    indexed: number;
+    skipped: number;
+    errors: number;
+}
+export declare class FilesManager {
+    private filesRoot;
+    private trashRoot;
+    private auditLog;
+    private quotaMb;
+    private maxUploadMb;
+    private textPreviewMaxKb;
+    private blockedExtensions;
+    private externalMounts;
+    private _indexDb;
+    private _indexDbRegistered;
+    constructor(cfg?: FilesManagerConfig);
+    /**
+     * 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: ExternalMount[]): void;
+    list(relPath: string, opts?: {
+        showHidden?: boolean;
+    }): Promise<DirListing>;
+    stat(relPath: string): Promise<FileStat>;
+    readStream(relPath: string): Promise<ReadStreamResult>;
+    readSmall(relPath: string, maxBytes: number): Promise<ReadSmallResult>;
+    writeStream(relPath: string, source: Readable, opts?: WriteOptions): Promise<WriteResult>;
+    /**
+     * Copy one file through the same path, mount, quota, extension, symlink,
+     * atomic-write, and audit boundary used by ordinary file writes.
+     */
+    copy(fromRel: string, toRel: string, overwrite?: boolean): Promise<WriteResult>;
+    mkdir(relPath: string): Promise<void>;
+    move(fromRel: string, toRel: string, overwrite?: boolean): Promise<void>;
+    remove(relPath: string): Promise<void>;
+    private removeInternal;
+    /**
+     * 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/integrations/openclaw/integration.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.
+     */
+    resolveLocalPath(relPath: string): Promise<{
+        abs_path: string;
+        exists: boolean;
+        external_mount?: string;
+        external_mount_mode?: "ro" | "rw";
+        is_dir?: boolean;
+        size?: number;
+        mtime?: number;
+    }>;
+    quota(): Promise<QuotaInfo>;
+    private assertQuotaAvailable;
+    audit(op: string, relPath: string, meta?: Record<string, any>): void;
+    /**
+     * 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.
+     */
+    private resolve;
+    private resolveOp;
+    /**
+     * Refuse mutations that target a read-only external mount. Called by
+     * write / move / delete / mkdir before any fs work.
+     */
+    private assertWritable;
+    /**
+     * 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.
+     */
+    private statOrThrow;
+    /**
+     * 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.
+     */
+    private assertNoSymlinkInAncestors;
+    /**
+     * Find the trust root for an absolute path: either an external mount's
+     * host_path (if abs is inside one) or FILES_ROOT.
+     */
+    private trustRootFor;
+    private checkExtension;
+    /**
+     * Returns the knowledge directory path (does NOT create it).
+     */
+    private get knowledgeDir();
+    /**
+     * Returns the SQLite DB path.
+     */
+    private get indexDbPath();
+    /**
+     * Returns the sidecar path for a given sha256.
+     */
+    private sidecarPath;
+    /**
+     * 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.
+     */
+    private ensureKnowledgeDir;
+    /**
+     * Lazy-initialize the SQLite FTS5 handle. Creates the .knowledge dir
+     * and the schema on first call.
+     */
+    private getIndexDb;
+    /**
+     * Search the FTS5 index.
+     */
+    searchIndex(query: string, opts?: {
+        limit?: number;
+        pathPrefix?: string;
+    }): Promise<SearchHit[]>;
+    /**
+     * Read a sidecar JSON for a file identified by sha256 or path.
+     */
+    getMeta(args: {
+        sha256?: string;
+        path?: string;
+    }): Promise<SidecarMeta | null>;
+    /**
+     * Write (merge or replace) a sidecar for a given sha256.
+     */
+    setMeta(sha256: string, payload: Partial<SidecarMeta>, opts?: {
+        merge?: boolean;
+    }): Promise<SidecarMeta>;
+    /**
+     * Walk the file tree and upsert text-indexable files into the FTS5 index.
+     */
+    reindex(opts?: {
+        pathPrefix?: string;
+    }): Promise<ReindexResult>;
+}
+export { isHidden };