@lijian-ui/dsh-file-manager 0.1.20

package/lib/types/host/fs-service.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Host filesystem service for the panel: directory listing, file read with a
+ * preview ceiling, text write with an mtime conflict check, filename search
+ * with directory pruning, and delete (untracked discard). Every operation
+ * resolves against a gated project root and refuses to escape it (path
+ * traversal guard). Text is decoded utf-8; images come back as data URLs
+ * (capped) so the browser renders them without extra round trips.
+ *
+ * Change delivery is intentionally NOT watch-based: the panel refreshes on
+ * user actions (list/read/write) and the SCM tab polls git status on its own
+ * schedule. A recursive `fs.watch` over the workspace root turned out to be
+ * a measurable CPU/IO cost on large trees (a 70k-file workspace pushed the
+ * host process to ~70% CPU during write bursts) for near-zero visible
+ * benefit — content edits never auto-reloaded the preview anyway (only a
+ * "updated" badge), so the always-on watcher was removed.
+ * @module dsh-filemgr/host/fs-service
+ */
+import type { DirListing, FileRead, PanelError, SearchView } from '../core/types.ts';
+import { type GateVerdict, type WorkspaceGate } from './gate.ts';
+/** Preview text ceiling — mirrors FileManager's single-tab 80k-char cap. */
+export declare const TEXT_CAP_CHARS = 80000;
+/** The image probe: parse PNG/JPEG/GIF/WebP header dimensions (undefined on failure). */
+export declare function probeImageSize(data: Buffer): {
+    width: number;
+    height: number;
+} | undefined;
+/**
+ * Filesystem service: gated listing/read/write/search/delete. All relative
+ * paths are resolved against the gated root.
+ * @param gate - the workspace gate (host: registered workspace membership).
+ */
+export declare class FsService {
+    private readonly gate;
+    constructor(gate: WorkspaceGate);
+    /** Verify a project root against the workspace gate (used by the SSE layer). */
+    verify(root: string): Promise<GateVerdict>;
+    /**
+     * List one directory (relative path; '' = root). Sorted dirs-first alpha.
+     * Entry metadata comes straight from `Dirent` (name + is-directory only) —
+     * no per-file stat — so listing a giant dir stays cheap. The result is
+     * capped at MAX_ENTRIES (truncated flag) to keep the tree and the '@'
+     * menu responsive on node_modules-style flat dirs.
+     */
+    list(root: string, rel: string): Promise<DirListing | PanelError>;
+    /** Read one file for preview: text decoded utf-8 (capped), images as data URLs. */
+    read(root: string, rel: string, asImage: boolean): Promise<FileRead | PanelError>;
+    /**
+     * Resolve one file for raw streaming (the markdown image / pdf preview
+     * route): gated, traversal-guarded, and .git-refusing. Returns the absolute
+     * path with the derived mime, size and mtime — the HTTP layer streams the
+     * bytes itself (createReadStream + Range), so even large files never sit in
+     * host memory. Mime magic detection reads only the first few bytes. The
+     * mtime feeds the route's ETag/Last-Modified validators.
+     */
+    readRaw(root: string, rel: string): Promise<{
+        abs: string;
+        mime: string;
+        size: number;
+        mtime: number;
+    } | PanelError>;
+    /** Write text content back, refusing when the file moved on disk (mtime conflict). */
+    write(root: string, rel: string, content: string, baseMtime?: number): Promise<{
+        mtime: number;
+    } | PanelError>;
+    /**
+     * Rename a path within the root. newName is a bare name (no separators,
+     * no '.'/'..') so the target always stays in the source's own directory;
+     * the joined target is re-checked against the canonical root anyway.
+     */
+    rename(root: string, rel: string, newName: string): Promise<{
+        ok: true;
+    } | PanelError>;
+    /** Create a directory at a relative path (its parent must already exist). */
+    mkdir(root: string, rel: string): Promise<{
+        ok: true;
+    } | PanelError>;
+    /** Create an empty file at a relative path (wx: refuses to overwrite). */
+    newFile(root: string, rel: string): Promise<{
+        ok: true;
+    } | PanelError>;
+    /**
+     * Resolve a relative path to its gated absolute path without touching it —
+     * the route layer uses it for reveal-in-file-manager / open-with-default.
+     */
+    resolveAbsolute(root: string, rel: string): Promise<{
+        ok: true;
+        abs: string;
+    } | PanelError>;
+    /** Recursive filename search (case-insensitive substring), pruned at noise dirs. */
+    search(root: string, query: string): Promise<SearchView | PanelError>;
+    /** Delete a path (discard of untracked files). Recursive for directories. */
+    delete(root: string, rel: string): Promise<{
+        ok: true;
+    } | PanelError>;
+}
+//# sourceMappingURL=fs-service.d.ts.map

package/lib/types/host/fs-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-service.d.ts","sourceRoot":"","sources":["../../../src/host/fs-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAW,UAAU,EAAa,UAAU,EAAE,MAAM,kBAAkB,CAAA;AACxG,OAAO,EAAgB,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAA;AAE9E,4EAA4E;AAC5E,eAAO,MAAM,cAAc,QAAS,CAAA;AAqEpC,yFAAyF;AACzF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAsD1F;AAuCD;;;;GAIG;AACH,qBAAa,SAAS;IAElB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,aAAa;IAGtC,gFAAgF;IAChF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAI1C;;;;;;OAMG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,UAAU,CAAC;IA8BvE,mFAAmF;IAC7E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,UAAU,CAAC;IAgEvF;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,UAAU,CAAC;IAkB1H,sFAAsF;IAChF,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,UAAU,CAAC;IAyB1C;;;;OAIG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG,UAAU,CAAC;IA0B5F,6EAA6E;IACvE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG,UAAU,CAAC;IAe1E,0EAA0E;IACpE,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG,UAAU,CAAC;IAe5E;;;OAGG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,UAAU,CAAC;IASjG,oFAAoF;IAC9E,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,UAAU,CAAC;IAuD3E,6EAA6E;IACvE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG,UAAU,CAAC;CAiB5E"}

package/lib/types/host/gate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Workspace gate for the /filemgr routes: canonicalize the requested
+ * project root and require it to be a registered workspace (or a directory
+ * inside one). This is the security boundary of the panel's fs/git routes -
+ * the browser may only read and mutate files under registered workspace
+ * roots, never arbitrary host directories.
+ * @module dsh-filemgr/host/gate
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { PanelError } from '../core/types.ts';
+/** The gate verdict for one project root. */
+export type GateVerdict = {
+    ok: true;
+    canonical: string;
+} | {
+    ok: false;
+    error: PanelError;
+};
+/** The workspace-membership check the services run on every request. */
+export type WorkspaceGate = (root: string) => Promise<GateVerdict>;
+/**
+ * Normalize a path for prefix comparison: collapse Windows separators to `/`
+ * and drop any trailing slash. On win32 the whole path is also lower-cased so
+ * a case-insensitive FS cannot trip the membership check (the drive letter and
+ * every segment are compared case-insensitively). On any other platform the
+ * path separator and case are left untouched.
+ */
+export declare function normalizeForPrefix(value: string): string;
+/**
+ * The canonical prefix check: child must live inside (or equal) the root.
+ * Separator- and case-robust on Windows: `path.join` yields backslashes while
+ * git (`rev-parse --show-toplevel`) and the browser (`./x`) yield forward
+ * slashes, so both sides are normalized to forward slashes before comparing,
+ * and the comparison is case-insensitive on win32 (the FS is case-insensitive).
+ */
+export declare function isPathInside(root: string, child: string): boolean;
+/**
+ * Production gate: canonicalize the requested root and require it to be a
+ * registered workspace path (or a subdirectory of one). The host's workspace
+ * registry owns canonicalization, so an unowned path is rejected outright.
+ * @param ctx - context carrying the workspace service.
+ * @returns the gate.
+ */
+export declare function createWorkspaceGate(ctx: Context): WorkspaceGate;
+//# sourceMappingURL=gate.d.ts.map

package/lib/types/host/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../../src/host/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,6CAA6C;AAC7C,MAAM,MAAM,WAAW,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAA;AAE5F,wEAAwE;AACxE,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAA;AAElE;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAMjE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CAmB/D"}

package/lib/types/host/git-runner.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared host git subprocess plumbing: the run result shape, the runner seam,
+ * the collected-output cap, and the production runner over the subprocess
+ * service. Packages receive this file as a generated copy via
+ * scripts/sync-shared.mjs; edit the shared source and re-run the sync instead
+ * of editing a copy.
+ *
+ * The context shape is declared structurally so this module stays
+ * self-contained (shared/ has no cordis dependency): any context whose
+ * `subprocess` satisfies SubprocessServiceLike works, which the plugin
+ * contexts do.
+ * @module dsh-web-ui-shared/host/git-runner
+ */
+/** One finished git invocation. */
+export interface GitRunResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** The spawn seam the service runs git through (subprocess service in production). */
+export interface GitRunner {
+    run(argv: readonly string[], cwd: string): Promise<GitRunResult>;
+}
+/** Collected-output cap for one git command. */
+export declare const OUTPUT_CAP_BYTES: number;
+/** The subprocess service surface this runner consumes (structural). */
+export interface SubprocessServiceLike {
+    spawn(spec: {
+        argv: readonly string[];
+        cwd: string;
+        stdio: {
+            stdin: 'ignore';
+            stdout: {
+                maxBytes: number;
+            };
+            stderr: {
+                maxBytes: number;
+            };
+        };
+        graceMs: number;
+    }): {
+        done: Promise<{
+            exitCode: number | null;
+        }>;
+        collected: {
+            stdout?: {
+                readFrom(offset: number): {
+                    text: string;
+                };
+            };
+            stderr?: {
+                readFrom(offset: number): {
+                    text: string;
+                };
+            };
+        };
+    };
+}
+/** Per-package knobs for the shared production runner. */
+export interface GitRunnerOptions {
+    /** Build the full spawn argv from the git args (default ['git', ...argv]). */
+    spawnArgv?: (argv: readonly string[]) => readonly string[];
+    /** degrade turns spawn/run failures into exitCode 127 results instead of throwing. */
+    failureMode?: 'throw' | 'degrade';
+    /** console.error tag for degrade mode. */
+    errorTag?: string;
+}
+/**
+ * Production runner over the subprocess service: one managed child per
+ * command, bounded collect on both streams. Degrade mode keeps the SCM tab
+ * showing the friendly "not a git repository" state instead of a bare 400
+ * when git is missing or the subprocess service fails.
+ * @param ctx - context carrying the subprocess service.
+ * @param options - per-package behavior knobs.
+ * @returns the runner.
+ */
+export declare function subprocessRunner(ctx: {
+    subprocess: SubprocessServiceLike;
+}, options?: GitRunnerOptions): GitRunner;
+//# sourceMappingURL=git-runner.d.ts.map

package/lib/types/host/git-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-runner.d.ts","sourceRoot":"","sources":["../../../src/host/git-runner.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;GAYG;AAEH,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED,sFAAsF;AACtF,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;CACjE;AAED,gDAAgD;AAChD,eAAO,MAAM,gBAAgB,QAAU,CAAA;AAEvC,wEAAwE;AACxE,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,IAAI,EAAE;QACV,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;QACvB,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE;YACL,KAAK,EAAE,QAAQ,CAAA;YACf,MAAM,EAAE;gBAAE,QAAQ,EAAE,MAAM,CAAA;aAAE,CAAA;YAC5B,MAAM,EAAE;gBAAE,QAAQ,EAAE,MAAM,CAAA;aAAE,CAAA;SAC7B,CAAA;QACD,OAAO,EAAE,MAAM,CAAA;KAChB,GAAG;QACF,IAAI,EAAE,OAAO,CAAC;YAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;SAAE,CAAC,CAAA;QAC1C,SAAS,EAAE;YACT,MAAM,CAAC,EAAE;gBAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG;oBAAE,IAAI,EAAE,MAAM,CAAA;iBAAE,CAAA;aAAE,CAAA;YACvD,MAAM,CAAC,EAAE;gBAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG;oBAAE,IAAI,EAAE,MAAM,CAAA;iBAAE,CAAA;aAAE,CAAA;SACxD,CAAA;KACF,CAAA;CACF;AAED,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,SAAS,MAAM,EAAE,CAAA;IAC1D,sFAAsF;IACtF,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE;IAAE,UAAU,EAAE,qBAAqB,CAAA;CAAE,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS,CA8CtH"}

package/lib/types/host/git-service.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Host git service for the SCM tab: working-tree status (porcelain v1, -z),
+ * stage/unstage/discard batches, all scoped to the gated project root and
+ * executed through the managed subprocess seam. Parsing is pure and exported
+ * for tests; the service only wraps the runner. Discard never touches the
+ * staged side (the index is only ever rewritten by stage/unstage), matching
+ * the "discard = worktree side" contract.
+ * @module dsh-filemgr/host/git-service
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type GitRunner } from './git-runner.ts';
+import type { GitBatchResult, GitChangeRow, GitFileState, GitStatusView, PanelError } from '../core/types.ts';
+import { type WorkspaceGate } from './gate.ts';
+/** One finished git invocation (shared runner plumbing). */
+export type { GitRunResult, GitRunner } from './git-runner.ts';
+/** Production runner over `ctx.subprocess`: shared plumbing, degrade mode for the SCM tab. */
+export declare function subprocessRunner(ctx: Context): GitRunner;
+/** Map one porcelain letter to the row state (unknown letters stay unknown). */
+export declare function porcelainState(letter: string): GitFileState;
+/**
+ * Parse `git status --porcelain=v1 -z` output into staged/unstaged/untracked
+ * rows. With -z every entry is NUL-terminated; rename entries carry two paths
+ * (old and new). Pure — exported for tests.
+ * @param output - raw porcelain v1 -z output.
+ * @returns the three change groups.
+ */
+export declare function parsePorcelain(output: string): {
+    staged: GitChangeRow[];
+    unstaged: GitChangeRow[];
+    untracked: GitChangeRow[];
+};
+/** Parse the porcelain row set into the status view shape. */
+export declare function parseStatusView(root: string, branch: string, output: string): GitStatusView;
+/**
+ * Workspace-scoped git operations. Gated methods pass the gate, resolve the
+ * repository root, and reject non-repositories with a stable error; the
+ * `Canonical` variants trust an already-gated canonical root (the SSE poll)
+ * and skip the gate.
+ * @param runner - the spawn seam.
+ * @param gate - workspace-membership gate.
+ * @param fsDelete - delete seam for untracked discard (host: FsService.delete).
+ */
+export declare class GitService {
+    private readonly runner;
+    private readonly gate;
+    private readonly fsDelete;
+    constructor(runner: GitRunner, gate: WorkspaceGate, fsDelete: (root: string, rel: string) => Promise<{
+        ok: true;
+    } | PanelError>);
+    /** Cached one-shot git binary probe; never re-probes after the first call. */
+    private availablePromise;
+    /**
+     * Cached repo-top-level resolution per canonical workspace, with a TTL so
+     * running `git init` (positive self-heal) or deleting `.git` (negative
+     * self-heal) is discovered by a later probe. Positive verdicts live 60s,
+     * negative (null) verdicts 30s; exitCode 127 is never cached because it
+     * means spawn/run failed rather than "not a repository".
+     */
+    private readonly repoCache;
+    /**
+     * Probe the git binary once (git --version) and cache the verdict for the
+     * service lifetime. A machine without git then degrades every operation to
+     * the stable "not a git repository" state after a single failed spawn,
+     * instead of re-spawning ENOENT on every poll tick. The cache stays false
+     * even if git is installed later; the host restart picks it up.
+     */
+    gitAvailable(): Promise<boolean>;
+    /**
+     * Resolve the repo top-level for one canonical root. Verdicts are cached
+     * with a TTL: a positive repo path for 60s, a negative null for 30s. After
+     * expiry the next call re-runs `rev-parse --show-toplevel`, so a repo
+     * created or removed while the host is running is picked up later. An
+     * exitCode 127 means the spawn/run itself failed; it returns null but is
+     * deliberately not cached so the next call retries. Any other failure is
+     * cached as a negative verdict for its TTL.
+     */
+    private repoOf;
+    /**
+     * Whether an already-gated canonical root is a git repository. Skips the
+     * workspace gate so the SSE poll does not double-gate every 2s tick; the
+     * underlying repoOf cache keeps rev-parse probes at TTL cadence.
+     */
+    isRepositoryCanonical(canonicalRoot: string): Promise<boolean>;
+    /**
+     * Whether a workspace root is a git repository. Gates the root first (POST
+     * route entry point); the SSE poll should use `isRepositoryCanonical`.
+     */
+    isRepository(root: string): Promise<boolean>;
+    /** Resolve the gated canonical root and the repository top-level. */
+    private repo;
+    /** Run one git invocation and classify failures. */
+    private run;
+    /** The repo status view; null when the root is not a repository. */
+    status(root: string): Promise<GitStatusView | null | PanelError>;
+    /**
+     * The repo status view for an already-gated canonical root; null when it is
+     * not a repository. Skips the workspace gate (SSE subscribers were gated at
+     * connect) and reuses the same repoOf cache + status parsing as `status`.
+     */
+    statusCanonical(canonicalRoot: string): Promise<GitStatusView | null>;
+    /** Run branch + porcelain status for one resolved repo and parse the view. */
+    private statusAt;
+    /** The repo root for the watch layer (null when not a repository). */
+    repoRoot(root: string): Promise<string | null>;
+    /**
+     * The unified diff of one path ('' when there is no diff to show). Staged
+     * paths diff the index against HEAD (`--cached`); unstaged paths diff the
+     * worktree against the index. Untracked paths have no index/HEAD entry, so
+     * they diff against /dev/null (the canonical new-file shape); its exit code
+     * is 1 — differences exist — which is a success here, not a failure.
+     */
+    diff(root: string, path: string, staged: boolean): Promise<{
+        content: string;
+    } | PanelError>;
+    /** Verify paths stay inside the repo root (defense in depth). */
+    private pathsInside;
+    /** Stage paths (git add). Batch result reflects the post-op status. */
+    stage(root: string, paths: string[]): Promise<GitBatchResult | PanelError>;
+    /** Unstage paths (git restore --staged). */
+    unstage(root: string, paths: string[]): Promise<GitBatchResult | PanelError>;
+    /**
+     * Discard paths (worktree side only). Tracked paths are restored from the
+     * index; untracked paths are deleted through the fs seam. The batch reports
+     * applied/failed per path.
+     */
+    discard(root: string, paths: string[]): Promise<GitBatchResult | PanelError>;
+    /** Shared batch plumbing: gate, repo resolve, path filter, run the op. */
+    private batch;
+}
+//# sourceMappingURL=git-service.d.ts.map

package/lib/types/host/git-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-service.d.ts","sourceRoot":"","sources":["../../../src/host/git-service.ts"],"names":[],"mappings":"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"}

package/lib/types/host/loopback.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Loopback trust fence shared by the host route families: socket address,
+ * Host header, and browser same-origin markers. Packages receive this file as
+ * a generated copy via scripts/sync-shared.mjs; edit the shared source and
+ * re-run the sync instead of editing a copy.
+ *
+ * Semantics: RFC 5735 IPv4 127/8, ::1, IPv4-mapped ::ffff:127/8 (matching the
+ * remote-web-ui gate), localhost hostnames, plus the browser same-origin
+ * markers (sec-fetch-site and Origin) for the request-level fence.
+ * @module dsh-web-ui-shared/host/loopback
+ */
+import type { IncomingMessage } from 'node:http';
+/** IPv4 127/8 predicate (four decimal octets, first == 127). */
+export declare function isIPv4Loopback(v4: string): boolean;
+/** Whether a socket remote address names the loopback range (127/8, ::1, IPv4-mapped). */
+export declare function isLoopbackAddress(address: string | undefined): boolean;
+/** Whether a normalized URL hostname names the loopback authority (localhost, [::1], 127/8). */
+export declare function isLoopbackHostname(hostname: string): boolean;
+/**
+ * Request-level trust fence: a loopback socket address AND a loopback Host
+ * header, plus browser same-origin markers. The socket address is
+ * authoritative; X-Forwarded-For is never trusted.
+ */
+export declare function isLoopbackRequest(request: IncomingMessage): boolean;
+//# sourceMappingURL=loopback.d.ts.map

package/lib/types/host/loopback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback.d.ts","sourceRoot":"","sources":["../../../src/host/loopback.ts"],"names":[],"mappings":"AACA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAEhD,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAKlD;AAED,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAMtE;AAED,gGAAgG;AAChG,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAmBnE"}

package/lib/types/host/poll-guard.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Poll-loop guard shared by the plugin family's Host halves (git-graph,
+ * filemgr): one bounded refresh loop that never overlaps itself,
+ * backs off on consecutive failures, and stops at a global deadline. Pure
+ * logic with injectable timers, so consumers test it without wall clocks.
+ */
+/** Timer injection seam; defaults to the global setTimeout/clearTimeout pair. */
+export interface PollTimers {
+    /** Schedule fn(ms). */
+    set: (fn: () => void, ms: number) => unknown;
+    /** Cancel a scheduled handle. */
+    clear: (handle: unknown) => void;
+}
+export interface PollGuardOptions {
+    /** Base interval between runs. */
+    intervalMs: number;
+    /** Runs stop entirely once this much wall time passed since start(). */
+    deadlineMs: number;
+    /** Cap for the failure backoff; each consecutive failure doubles the delay up to this. */
+    maxBackoffMs: number;
+    /** Optional timer seam for tests. */
+    timers?: PollTimers;
+    /** Invoked once when the deadline fires; no run starts afterwards. */
+    onDeadline?: () => void;
+    /** Invoked after a run settles with the consecutive-failure count. */
+    onSettled?: (consecutiveFailures: number) => void;
+    /** The task each tick runs; a rejection counts as a failure. */
+    onRun: () => Promise<void>;
+}
+/**
+ * Owns one bounded poll loop.
+ *
+ * Guarantees: at most one task runs at a time (a scheduled tick whose turn
+ * arrives while a run is in flight is dropped); consecutive failures double
+ * the delay up to maxBackoffMs and reset on the first success; the loop
+ * stops forever at deadlineMs and cancels its timer.
+ */
+export declare class PollGuard {
+    private readonly options;
+    private handle;
+    private running;
+    private startedAt;
+    private stopped;
+    private failures;
+    /** @param options - loop bounds; interval/deadline/backoff/onRun are required, the rest optional. */
+    constructor(options: PollGuardOptions);
+    /** Start the loop. Safe to call once; later calls are ignored. */
+    start(): void;
+    /** Stop the loop permanently and drop any pending tick. */
+    stop(): void;
+    private schedule;
+    private delay;
+    private tick;
+}
+//# sourceMappingURL=poll-guard.d.ts.map

package/lib/types/host/poll-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll-guard.d.ts","sourceRoot":"","sources":["../../../src/host/poll-guard.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,uBAAuB;IACvB,GAAG,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAA;IAC5C,iCAAiC;IACjC,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAA;CACjC;AAOD,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAA;IAClB,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAA;IAClB,0FAA0F;IAC1F,YAAY,EAAE,MAAM,CAAA;IACpB,qCAAqC;IACrC,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;IACvB,sEAAsE;IACtE,SAAS,CAAC,EAAE,CAAC,mBAAmB,EAAE,MAAM,KAAK,IAAI,CAAA;IACjD,gEAAgE;IAChE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAED;;;;;;;GAOG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,QAAQ,CAAI;IAEpB,qGAAqG;gBACzF,OAAO,EAAE,gBAAgB;IASrC,kEAAkE;IAClE,KAAK,IAAI,IAAI;IAMb,2DAA2D;IAC3D,IAAI,IAAI,IAAI;IAMZ,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAC,KAAK;YAKC,IAAI;CAoBnB"}

package/lib/types/host/routes.d.ts

@@ -0,0 +1,54 @@
+/**
+ * /filemgr/* route layer: JSON envelope (ok/error with stable codes) for
+ * the fs/git operations and one SSE stream (git status changes) per project
+ * root. The services own gating and parsing; this layer owns HTTP shape and
+ * subscriber bookkeeping.
+ *
+ * There is deliberately no fs-change push: the explorer/preview refresh on
+ * user actions and the SCM tab polls git status here, so a recursive
+ * fs.watch over the workspace (a measurable cost on large trees) is not
+ * needed. Subscribers only exist while an SCM panel is visible, so the
+ * git poll below runs only during that window.
+ * @module dsh-filemgr/host/routes
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FsService } from './fs-service.ts';
+import type { GitService } from './git-service.ts';
+/**
+ * Platform argv for "reveal in file manager" (select the entry). Windows
+ * Explorer selects via /select,; macOS Finder via open -R; Linux desktops
+ * have no select mode, so xdg-open opens the parent directory.
+ */
+export declare function revealArgv(platform: NodeJS.Platform, abs: string): string[];
+/** Platform argv for "open with the default app". */
+export declare function openArgv(platform: NodeJS.Platform, abs: string): string[];
+/**
+ * Parse a `Range: bytes=start-end` header against the file size. RFC 7233
+ * lets a server ignore any Range it does not support, so unknown units,
+ * malformed headers and multi-range requests all return null (the caller
+ * answers 200 with the full body); only a syntactically valid single range
+ * that cannot be satisfied returns 'invalid' (the caller answers 416).
+ * Suffix ranges (`bytes=-N`) select the last N bytes. Range support added
+ * after human review on #242 (pdf seeking); ignore-instead-of-416 for
+ * unsupported shapes per maintainer feedback.
+ */
+export declare function parseRangeHeader(header: string | undefined, size: number): {
+    start: number;
+    end: number;
+} | 'invalid' | null;
+/**
+ * Whether an If-None-Match header matches the current etag. Handles `*` and
+ * comma-separated entity-tag lists; GET revalidation uses weak comparison
+ * (RFC 9110), so the weak prefix is ignored on both sides.
+ */
+export declare function ifNoneMatchSaidFresh(header: string | undefined, etag: string): boolean;
+/**
+ * Register the /filemgr routes (prefix for JSON, exact for the SSE
+ * stream — longest-prefix-wins keeps them disjoint).
+ * @param ctx - context carrying the webServer service.
+ * @param fs - the gated filesystem service.
+ * @param git - the gated git service.
+ * @returns the route disposers.
+ */
+export declare function registerPanelRoutes(ctx: Context, fs: FsService, git: GitService): () => void;
+//# sourceMappingURL=routes.d.ts.map

package/lib/types/host/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/host/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAIlD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAUlD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAI3E;AAED,qDAAqD;AACrD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAIzE;AA8CD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,IAAI,EAAE,MAAM,GACX;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAAG,IAAI,CAanD;AAOD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAOtF;AA8ED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,IAAI,CAkd5F"}

package/lib/types/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @lijian-ui/dsh-file-manager — host half: the workspace-gated
+ * filesystem + git services and the /filemgr/* HTTP routes (JSON
+ * operations + SSE change stream) on the shared webserver. The browser half
+ * (exports "./client") is served by client-modules from the same package's
+ * dsh.client declaration.
+ *
+ * The host half also announces the plugin to every agent through the
+ * system-prompt section mechanism (the same band task-board uses), so agents
+ * know the right-panel system exists and how to cooperate with it.
+ *
+ * FileManager right-panel design (Apache-2.0, iOfficeAI/FileManager) — re-implemented
+ * from measured behavior and architecture, not copied code.
+ * @module @lijian-ui/dsh-file-manager
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Required services: the route registry, the managed subprocess seam, the workspace registry, and the prompt band. */
+export declare const inject: string[];
+/** Settings namespace the browser settings card edits (the Host registers it). */
+export declare const FILEMANAGER_PANEL_SETTINGS_NAMESPACE = "filemgr";
+/** Model-facing announcement: plugin presence, capabilities, and limits. */
+export declare const FILEMANAGER_PANEL_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-filemgr \u63D2\u4EF6\uFF08DSH Web GUI \u7684\u53F3\u4FA7\u9762\u677F\u7CFB\u7EDF\uFF09\uFF1A\u9879\u76EE\u4F1A\u8BDD\u6253\u5F00\u65F6\uFF0C\u804A\u5929\u533A\u53F3\u4FA7\u51FA\u73B0\u300C\u9884\u89C8\u300D\u4E0E\u300C\u6587\u4EF6/\u53D8\u66F4\u300D\u4E24\u5757\u9762\u677F\u3002\u80FD\u529B\uFF1AExplorer \u6587\u4EF6\u6811\uFF08\u70B9\u51FB\u6587\u4EF6\u5728\u9884\u89C8\u9762\u677F\u6253\u5F00\u3001\u6574\u884C\u70B9\u51FB\u5C55\u5F00\u6587\u4EF6\u5939\u3001\u6309\u6587\u4EF6\u540D\u641C\u7D22\u5B9A\u4F4D\uFF09\uFF1BPreview \u591A tab \u9884\u89C8\uFF08markdown/html/code/diff/csv/pdf/office/\u56FE\u7247/\u6587\u672C\u7B49\u683C\u5F0F\uFF0C\u652F\u6301\u6E90\u7801/\u9884\u89C8\u5207\u6362\u3001\u5206\u5C4F\u7F16\u8F91\u3001\u4FDD\u5B58\uFF1Bmarkdown \u4E0E\u804A\u5929\u6D88\u606F\u4E2D\u7684 mermaid \u4EE3\u7801\u5757\u4F1A\u6E32\u67D3\u6210\u56FE\u8868\uFF0C\u56FE\u6E90\u8BED\u6CD5\u9519\u8BEF\u65F6\u56DE\u9000\u4E3A\u4EE3\u7801\u5757\uFF09\uFF1BSCM \u53D8\u66F4\u9762\u677F\uFF08\u771F\u5B9E git stage/unstage/discard\uFF09\uFF1B\u9762\u677F\u5BBD\u5EA6\u53EF\u62D6\u62FD\u8C03\u6574\uFF08Explorer 220~500px\u3001Preview 340~1200px\uFF09\uFF0C\u53CC\u51FB\u628A\u624B\u590D\u4F4D\u9ED8\u8BA4\u5BBD\u5EA6\uFF0C\u6298\u53E0\u72B6\u6001\u4E0E\u5BBD\u5EA6\u6309\u9879\u76EE\u6301\u4E45\u5316\uFF08localStorage\uFF09\u3002\u6570\u636E\u6E90\u4E3A\u5F53\u524D\u4F1A\u8BDD\u5DE5\u4F5C\u76EE\u5F55\u7684\u771F\u5B9E\u6587\u4EF6\u7CFB\u7EDF\u4E0E\u771F\u5B9E git \u4ED3\u5E93\uFF0C\u5BBF\u4E3B\u8FDB\u7A0B\u7ECF /filemgr/* \u8DEF\u7531\u63D0\u4F9B\u3002\u7528\u6237\u63D0\u5230\u300C\u53F3\u4FA7\u9762\u677F / \u9884\u89C8\u9762\u677F / \u6587\u4EF6\u6811 / \u53D8\u66F4\u9762\u677F\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
+/** Settings section the browser card edits: a total on/off switch (issue #307). */
+export interface FileManagerPanelSettings {
+    /** Whether the right-panel system is mounted at all; default on. */
+    enabled?: boolean;
+}
+/**
+ * Mount the panel data services and their routes.
+ * @param ctx - context carrying webServer, subprocess, workspaceRegistry, systemPrompt.
+ */
+export declare const apply: typeof applyImpl;
+declare function applyImpl(ctx: Context, config?: FileManagerPanelSettings): void;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAalD,uHAAuH;AACvH,eAAO,MAAM,MAAM,UAAmE,CAAA;AAEtF,kFAAkF;AAClF,eAAO,MAAM,oCAAoC,YAAY,CAAA;AAK7D,4EAA4E;AAC5E,eAAO,MAAM,0BAA0B,oxDAAke,CAAA;AAEzgB,mFAAmF;AACnF,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK,kBAAsD,CAAA;AAExE,iBAAS,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,wBAA6B,GAAG,IAAI,CA2C5E"}

package/lib/types/mount-once.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Host single-instance guard shared by the plugin family. The family bundle
+ * (dsh-web-ui-all / dsh-skins) namespaces every child row id (web-ui-*), so
+ * the loader accepts a standalone install of the same package side by side;
+ * without this guard the second instance would still re-register the same
+ * webserver routes, tools, settings namespaces, and system-prompt sections
+ * and fail the boot. mountOnce makes the second host apply a no-op for the
+ * lifetime of the first instance (the browser half is already deduped by
+ * package name in the client module host).
+ *
+ * The registry rides a global symbol so two module instances of the same
+ * package (npm copy vs repository link) still share one verdict. cordis
+ * `ctx.effect` runs its callback immediately and treats the callback's
+ * return value as the fiber disposer, so the unmarker is returned, not run.
+ */
+/**
+ * Wrap a cordis plugin apply so the package runs at most once per process.
+ * The first mount registers normally and unmarks when its fiber disposes;
+ * any later mount of the same package name is a no-op.
+ * @param packageName - npm package identity shared by every install source.
+ * @param fn - the original plugin apply.
+ * @returns an apply of the same shape.
+ */
+export declare function mountOnce<T extends (...args: any[]) => unknown>(packageName: string, fn: T): T;
+//# sourceMappingURL=mount-once.d.ts.map

package/lib/types/mount-once.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-once.d.ts","sourceRoot":"","sources":["../../src/mount-once.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;GAcG;AAaH;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAW9F"}