@tiphareth/dsh-hardssh 0.1.2-alpha

package/lib/switch-fs-CAJpFY9C.js

@@ -0,0 +1,193 @@
+import { FileSystem } from "@deepseek-ai/dsh-fs";
+//#region src/switch/switch-fs.ts
+/**
+* The `ctx.fs` switching facade: routes every filesystem call to the backend
+* of the SESSION's workspace — a local session operates on the local sandbox,
+* an SSH-bound workspace on the remote host the workspace is bound to.
+*
+* Routing anchor: the cwd the tool call was made under (`resolve`'s
+* `opts.cwd`, the write/edit `sandboxPolicy.workspaceRoot`). The resolver
+* ("which SSH workspace owns this cwd?") lives in the deps; a hit routes to
+* that workspace's remote backend, a miss to the local backend. Later
+* operations (stat/read/write) receive only the resolved `FsTarget`, so the
+* backend identity is encoded into the target key — `ssh:<recordId>:<remoteKey>`
+* for remote targets, bare local keys for local ones — and decoded on every
+* dispatch. This keeps two SSH workspaces on DIFFERENT hosts (or different
+* directories on the SAME host) from colliding, and never misroutes a local
+* target.
+*
+* @module dsh-hardssh/switch-fs
+*/
+/** Key namespace: 'ssh:<recordId>:' for remote workspaces. */
+const REMOTE_PREFIX = "ssh:";
+/** The routing filesystem facade. */
+var SwitchFileSystem = class extends FileSystem {
+	deps;
+	local;
+	constructor(ctx, deps) {
+		super(ctx);
+		this.deps = deps;
+		this.local = deps.local;
+	}
+	/** Sandbox default from the local backend (remote worlds are unconfined —
+	*  the docs/doc of the tool layer reads this once at mount). */
+	get sandboxMode() {
+		return this.local.sandboxMode;
+	}
+	/** Encode a raw key into the world's namespace. */
+	encode(rawKey, namespace) {
+		return namespace === "" ? rawKey : `${namespace}${rawKey}`;
+	}
+	/** Decode a namespaced key back to (rawKey, world). */
+	decode(key) {
+		if (key.startsWith("ssh:")) {
+			const end = key.indexOf(":", 4);
+			if (end > 0) {
+				const namespace = key.slice(0, end + 1);
+				const world = this.deps.worldForNamespace(namespace);
+				if (world !== void 0) return {
+					rawKey: key.slice(namespace.length),
+					world
+				};
+			}
+			return;
+		}
+		return {
+			rawKey: key,
+			world: {
+				backend: this.local,
+				namespace: ""
+			}
+		};
+	}
+	async resolve(path, opts) {
+		const world = this.deps.worldFor(opts?.cwd);
+		const effectivePath = world.anchorPath !== void 0 && world.remoteRoot !== void 0 ? this.translateAnchorPath(world.anchorPath, world.remoteRoot, path) : path;
+		const raw = await world.backend.resolve(effectivePath, opts);
+		return {
+			targetKey: this.encode(String(raw.targetKey), world.namespace),
+			displayPath: raw.displayPath
+		};
+	}
+	/** Rewrite `<anchor>/<rest>` to `<remoteRoot>/<rest>` when `path` is the
+	*  anchor or under it; otherwise return `path` unchanged (remote absolute
+	*  paths, relative paths, and foreign local paths all pass through). */
+	translateAnchorPath(anchor, remoteRoot, path) {
+		const norm = (value) => value.replace(/[\\/]+$/, "");
+		const a = norm(anchor);
+		const isWin = a.includes("\\");
+		const normPath = (value) => {
+			let out = norm(value);
+			if (isWin) out = out.replace(/\//g, "\\");
+			return out;
+		};
+		const p = normPath(path);
+		const aa = isWin ? a.toLowerCase() : a;
+		const pp = isWin ? p.toLowerCase() : p;
+		if (pp === aa) return remoteRoot;
+		if (pp.startsWith(`${aa}\\`) || pp.startsWith(`${aa}/`)) {
+			const tail = p.slice(a.length).replace(/^[\\/]+/, "").replace(/\\/g, "/");
+			return tail === "" ? remoteRoot : `${remoteRoot.replace(/\/+$/, "")}/${tail}`;
+		}
+		return path;
+	}
+	processPath(target) {
+		const key = String(target.targetKey);
+		const decoded = this.decode(key);
+		return decoded?.world.backend.processPath({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		}) ?? key;
+	}
+	fileUrl(target) {
+		const decoded = this.decode(String(target.targetKey));
+		if (decoded === void 0) return this.local.fileUrl(target);
+		return decoded.world.backend.fileUrl({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		});
+	}
+	contains(parent, child) {
+		const p = this.decode(String(parent.targetKey));
+		const c = this.decode(String(child.targetKey));
+		if (p === void 0 || c === void 0 || p.world.backend !== c.world.backend) return false;
+		return p.world.backend.contains({
+			targetKey: p.rawKey,
+			displayPath: parent.displayPath
+		}, {
+			targetKey: c.rawKey,
+			displayPath: child.displayPath
+		});
+	}
+	async stat(target, signal) {
+		const decoded = this.decode(String(target.targetKey));
+		if (decoded === void 0) return void 0;
+		return decoded.world.backend.stat({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		}, signal);
+	}
+	async lstat(path, opts, signal) {
+		const world = this.deps.worldFor(opts?.cwd);
+		const effectivePath = world.anchorPath !== void 0 && world.remoteRoot !== void 0 ? this.translateAnchorPath(world.anchorPath, world.remoteRoot, path) : path;
+		return world.backend.lstat(effectivePath, opts, signal);
+	}
+	async readText(target, signal) {
+		const decoded = this.decode(String(target.targetKey));
+		if (decoded === void 0) throw new Error("fs-ssh: cannot route target");
+		return decoded.world.backend.readText({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		}, signal);
+	}
+	async streamText(target, signal) {
+		const decoded = this.decode(String(target.targetKey));
+		if (decoded === void 0) throw new Error("fs-ssh: cannot route target");
+		return decoded.world.backend.streamText({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		}, signal);
+	}
+	async readBytes(target, signal, maxBytes) {
+		const decoded = this.decode(String(target.targetKey));
+		if (decoded === void 0) throw new Error("fs-ssh: cannot route target");
+		return decoded.world.backend.readBytes({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		}, signal, maxBytes);
+	}
+	async listDir(target, signal) {
+		const decoded = this.decode(String(target.targetKey));
+		if (decoded === void 0) throw new Error("fs-ssh: cannot route target");
+		const entries = await decoded.world.backend.listDir({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		}, signal);
+		if (decoded.world.namespace === "") return entries;
+		return entries.map((entry) => ({
+			...entry,
+			target: {
+				targetKey: this.encode(String(entry.target.targetKey), decoded.world.namespace),
+				displayPath: entry.target.displayPath
+			}
+		}));
+	}
+	async writeText(target, content, expected, signal, sandboxPolicy) {
+		const decoded = this.decode(String(target.targetKey));
+		if (decoded === void 0) throw new Error("fs-ssh: cannot route target");
+		return decoded.world.backend.writeText({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		}, content, expected, signal, sandboxPolicy);
+	}
+	async editText(target, edit, expected, signal, sandboxPolicy) {
+		const decoded = this.decode(String(target.targetKey));
+		if (decoded === void 0) throw new Error("fs-ssh: cannot route target");
+		return decoded.world.backend.editText({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		}, edit, expected, signal, sandboxPolicy);
+	}
+};
+//#endregion
+export { SwitchFileSystem as n, REMOTE_PREFIX as t };

package/lib/switch-fs-RrZtG2gv.js

@@ -0,0 +1,210 @@
+import { FileSystem } from "@deepseek-ai/dsh-fs";
+//#region src/switch/switch-fs.ts
+/**
+* The `ctx.fs` switching facade: routes every filesystem call to the backend
+* of the SESSION's workspace — a local session operates on the local sandbox,
+* an SSH-bound workspace on the remote host the workspace is bound to.
+*
+* Routing anchor: the cwd the tool call was made under (`resolve`'s
+* `opts.cwd`, the write/edit `sandboxPolicy.workspaceRoot`). The resolver
+* ("which SSH workspace owns this cwd?") lives in the deps; a hit routes to
+* that workspace's remote backend, a miss to the local backend. Later
+* operations (stat/read/write) receive only the resolved `FsTarget`, so the
+* backend identity is encoded into the target key — `ssh:<recordId>:<remoteKey>`
+* for remote targets, bare local keys for local ones — and decoded on every
+* dispatch. This keeps two SSH workspaces on DIFFERENT hosts (or different
+* directories on the SAME host) from colliding, and never misroutes a local
+* target.
+*
+* @module dsh-hardssh/switch-fs
+*/
+/** Key namespace: 'ssh:<recordId>:' (legacy) or 'wfs://<id>/' (current)
+*  for remote/workspace-bound targets. Both decode; new keys emit wfs://. */
+const REMOTE_PREFIX = "ssh:";
+/** Strict WFS key prefix (includes the double slash + separator). */
+const WFS_NAMESPACE_MARKER = `wfs://`;
+/** The routing filesystem facade. */
+var SwitchFileSystem = class extends FileSystem {
+	deps;
+	local;
+	constructor(ctx, deps) {
+		super(ctx);
+		this.deps = deps;
+		this.local = deps.local;
+	}
+	/** Sandbox default from the local backend (remote worlds are unconfined —
+	*  the docs/doc of the tool layer reads this once at mount). */
+	get sandboxMode() {
+		return this.local.sandboxMode;
+	}
+	/** Encode a raw key into the world's namespace. */
+	encode(rawKey, namespace) {
+		return namespace === "" ? rawKey : `${namespace}${rawKey}`;
+	}
+	/** Decode a namespaced key back to (rawKey, world). Supports both the
+	*  current `wfs://<id>/…` form and the legacy `ssh:<recordId>:…` form. */
+	decode(key) {
+		if (key.startsWith(WFS_NAMESPACE_MARKER)) {
+			const rest = key.slice(WFS_NAMESPACE_MARKER.length);
+			const end = rest.indexOf("/");
+			if (end > 0) {
+				const namespace = `wfs://${rest.slice(0, end + 1)}`;
+				const world = this.deps.worldForNamespace(namespace);
+				if (world !== void 0) return {
+					rawKey: rest.slice(end + 1),
+					world
+				};
+			}
+			return;
+		}
+		if (key.startsWith("ssh:")) {
+			const end = key.indexOf(":", 4);
+			if (end > 0) {
+				const namespace = key.slice(0, end + 1);
+				const world = this.deps.worldForNamespace(namespace);
+				if (world !== void 0) return {
+					rawKey: key.slice(namespace.length),
+					world
+				};
+			}
+			return;
+		}
+		return {
+			rawKey: key,
+			world: {
+				backend: this.local,
+				namespace: ""
+			}
+		};
+	}
+	async resolve(path, opts) {
+		const world = this.deps.worldFor(opts?.cwd);
+		const effectivePath = world.anchorPath !== void 0 && world.remoteRoot !== void 0 ? this.translateAnchorPath(world.anchorPath, world.remoteRoot, path) : path;
+		const raw = await world.backend.resolve(effectivePath, opts);
+		return {
+			targetKey: this.encode(String(raw.targetKey), world.namespace),
+			displayPath: raw.displayPath
+		};
+	}
+	/** Rewrite `<anchor>/<rest>` to `<remoteRoot>/<rest>` when `path` is the
+	*  anchor or under it; otherwise return `path` unchanged (remote absolute
+	*  paths, relative paths, and foreign local paths all pass through). */
+	translateAnchorPath(anchor, remoteRoot, path) {
+		const norm = (value) => value.replace(/[\\/]+$/, "");
+		const a = norm(anchor);
+		const isWin = a.includes("\\");
+		const normPath = (value) => {
+			let out = norm(value);
+			if (isWin) out = out.replace(/\//g, "\\");
+			return out;
+		};
+		const p = normPath(path);
+		const aa = isWin ? a.toLowerCase() : a;
+		const pp = isWin ? p.toLowerCase() : p;
+		if (pp === aa) return remoteRoot;
+		if (pp.startsWith(`${aa}\\`) || pp.startsWith(`${aa}/`)) {
+			const tail = p.slice(a.length).replace(/^[\\/]+/, "").replace(/\\/g, "/");
+			return tail === "" ? remoteRoot : `${remoteRoot.replace(/\/+$/, "")}/${tail}`;
+		}
+		return path;
+	}
+	processPath(target) {
+		const key = String(target.targetKey);
+		const decoded = this.decode(key);
+		return decoded?.world.backend.processPath({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		}) ?? key;
+	}
+	fileUrl(target) {
+		const decoded = this.decode(String(target.targetKey));
+		if (decoded === void 0) return this.local.fileUrl(target);
+		return decoded.world.backend.fileUrl({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		});
+	}
+	contains(parent, child) {
+		const p = this.decode(String(parent.targetKey));
+		const c = this.decode(String(child.targetKey));
+		if (p === void 0 || c === void 0 || p.world.backend !== c.world.backend) return false;
+		return p.world.backend.contains({
+			targetKey: p.rawKey,
+			displayPath: parent.displayPath
+		}, {
+			targetKey: c.rawKey,
+			displayPath: child.displayPath
+		});
+	}
+	async stat(target, signal) {
+		const decoded = this.decode(String(target.targetKey));
+		if (decoded === void 0) return void 0;
+		return decoded.world.backend.stat({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		}, signal);
+	}
+	async lstat(path, opts, signal) {
+		const world = this.deps.worldFor(opts?.cwd);
+		const effectivePath = world.anchorPath !== void 0 && world.remoteRoot !== void 0 ? this.translateAnchorPath(world.anchorPath, world.remoteRoot, path) : path;
+		return world.backend.lstat(effectivePath, opts, signal);
+	}
+	async readText(target, signal) {
+		const decoded = this.decode(String(target.targetKey));
+		if (decoded === void 0) throw new Error("fs-ssh: cannot route target");
+		return decoded.world.backend.readText({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		}, signal);
+	}
+	async streamText(target, signal) {
+		const decoded = this.decode(String(target.targetKey));
+		if (decoded === void 0) throw new Error("fs-ssh: cannot route target");
+		return decoded.world.backend.streamText({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		}, signal);
+	}
+	async readBytes(target, signal, maxBytes) {
+		const decoded = this.decode(String(target.targetKey));
+		if (decoded === void 0) throw new Error("fs-ssh: cannot route target");
+		return decoded.world.backend.readBytes({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		}, signal, maxBytes);
+	}
+	async listDir(target, signal) {
+		const decoded = this.decode(String(target.targetKey));
+		if (decoded === void 0) throw new Error("fs-ssh: cannot route target");
+		const entries = await decoded.world.backend.listDir({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		}, signal);
+		if (decoded.world.namespace === "") return entries;
+		return entries.map((entry) => ({
+			...entry,
+			target: {
+				targetKey: this.encode(String(entry.target.targetKey), decoded.world.namespace),
+				displayPath: entry.target.displayPath
+			}
+		}));
+	}
+	async writeText(target, content, expected, signal, sandboxPolicy) {
+		const decoded = this.decode(String(target.targetKey));
+		if (decoded === void 0) throw new Error("fs-ssh: cannot route target");
+		return decoded.world.backend.writeText({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		}, content, expected, signal, sandboxPolicy);
+	}
+	async editText(target, edit, expected, signal, sandboxPolicy) {
+		const decoded = this.decode(String(target.targetKey));
+		if (decoded === void 0) throw new Error("fs-ssh: cannot route target");
+		return decoded.world.backend.editText({
+			targetKey: decoded.rawKey,
+			displayPath: target.displayPath
+		}, edit, expected, signal, sandboxPolicy);
+	}
+};
+//#endregion
+export { SwitchFileSystem as n, WFS_NAMESPACE_MARKER as r, REMOTE_PREFIX as t };

package/lib/types/backend.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Gated filesystem backends and the production workspace file service.
+ *
+ * UI workspace routes resolve an exact ledger anchor and then create a
+ * request-scoped RemoteBackend. There is no implicit local fallback and no
+ * dependency on the legacy global SSH mode state.
+ */
+import type { SshEngine } from './ssh/engine.ts';
+import { shellQuote } from './shell.ts';
+import { RemoteSearchService } from './remote-search.ts';
+import type { SshWorkspaceLedger } from './ledger.ts';
+import type { DirListing, FileRead, FileWriteResult, SearchView, SshWorkspaceRecord, WorkspaceEntry } from './protocol.ts';
+export declare const SEARCH_HIT_CAP = 200;
+export declare const SEARCH_SCAN_CAP = 20000;
+export declare const SEARCH_MAX_DEPTH = 4;
+export declare const REMOTE_SEARCH_TIMEOUT_MS = 20000;
+export type BackendErrorCode = 'binary' | 'too-large' | 'conflict' | 'outside-root' | 'not-remote' | 'root-mismatch' | 'not-found' | 'forbidden' | 'invalid' | 'io';
+export declare class BackendError extends Error {
+    readonly code: BackendErrorCode;
+    constructor(code: BackendErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface WorkspaceFileContext {
+    workspaceId: string;
+    requestedRoot: string;
+    anchorPath: string;
+    alias: string;
+    remoteRoot: string;
+}
+export interface WorkspaceFileService {
+    resolveContext(root: string): Promise<WorkspaceFileContext>;
+    list(root: string, rel: string): Promise<DirListing>;
+    read(root: string, rel: string): Promise<FileRead>;
+    write(root: string, rel: string, content: string, expectedMtime?: number): Promise<FileWriteResult>;
+    search(root: string, query: string): Promise<SearchView>;
+}
+export interface WorkspaceBackend {
+    assertRoot(root: string): void;
+    list(root: string, rel: string): Promise<DirListing>;
+    read(root: string, rel: string): Promise<FileRead>;
+    write(root: string, rel: string, content: string, expectedMtime?: number): Promise<FileWriteResult>;
+    search(root: string, query: string): Promise<SearchView>;
+}
+/**
+ * Normalize a workspace-relative path.
+ *
+ * Backslashes are rejected instead of treated as separators: the same input
+ * would mean a separator on Windows and a filename character on POSIX.
+ * Absolute paths, drive-qualified paths, NUL and ".." are rejected.
+ */
+export declare function normalizeRel(raw: string): string;
+/** POSIX prefix gate. Handles "/" without producing an empty root. */
+export declare function isInside(root: string, abs: string): boolean;
+/** Resolve a normalized relative path below a POSIX root. */
+export declare function relToAbs(root: string, rel: string): string;
+export { shellQuote };
+/** Stable dir-first, case-insensitive ordering shared by every backend. */
+export declare function sortWorkspaceEntries(entries: WorkspaceEntry[]): WorkspaceEntry[];
+export type WorkspacePathFlavor = 'local' | 'remote';
+/** Return abs relative to root, rejecting prefix-collision/parent traversal. */
+export declare function relativeWorkspacePath(root: string, abs: string, flavor: WorkspacePathFlavor): string;
+/** Normalize filesystem/SFTP errors to stable route-visible codes. */
+export declare function toBackendIoError(error: unknown, path: string): BackendError;
+/** Map a BackendError to its stable HTTP status (routes use this). */
+export declare function backendErrorStatus(error: BackendError, ioStatus: 500 | 502): number;
+/**
+ * Local implementation retained for explicit local-only consumers. It is
+ * deliberately NOT selected by LedgerWorkspaceFileService.
+ */
+export declare class LocalBackend implements WorkspaceBackend {
+    assertRoot(root: string): void;
+    list(root: string, rel: string): Promise<DirListing>;
+    read(root: string, rel: string): Promise<FileRead>;
+    write(root: string, rel: string, content: string, expectedMtime?: number): Promise<FileWriteResult>;
+    search(root: string, query: string): Promise<SearchView>;
+    private resolvePath;
+    /** Resolve the nearest existing ancestor; root and every existing target
+     *  ancestor must resolve below the real workspace root. */
+    private assertRealpathWalk;
+}
+/** A request-scoped remote backend bound to one immutable ledger record. */
+export declare class RemoteBackend implements WorkspaceBackend {
+    private readonly engine;
+    private readonly record;
+    private readonly searchService;
+    private readonly remoteRoot;
+    constructor(engine: SshEngine, record: SshWorkspaceRecord, searchService: RemoteSearchService);
+    assertRoot(root: string): void;
+    list(root: string, rel: string): Promise<DirListing>;
+    read(root: string, rel: string): Promise<FileRead>;
+    write(root: string, rel: string, content: string, expectedMtime?: number): Promise<FileWriteResult>;
+    search(root: string, query: string): Promise<SearchView>;
+}
+/** Production UI service: exact ledger anchor -> request-scoped backend. */
+export declare class LedgerWorkspaceFileService implements WorkspaceFileService {
+    private readonly ledger;
+    private readonly engine;
+    private readonly searchService;
+    constructor(ledger: SshWorkspaceLedger, engine: SshEngine, searchService: RemoteSearchService);
+    resolveContext(root: string): Promise<WorkspaceFileContext>;
+    list(root: string, rel: string): Promise<DirListing>;
+    read(root: string, rel: string): Promise<FileRead>;
+    write(root: string, rel: string, content: string, expectedMtime?: number): Promise<FileWriteResult>;
+    search(root: string, query: string): Promise<SearchView>;
+    private resolveBackend;
+}
+//# sourceMappingURL=backend.d.ts.map

package/lib/types/base/capability.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Provider capability interfaces — the resource-access contracts a workspace
+ * provider may offer. Providers implement only what they support; consumers
+ * look up capabilities through `WorkspaceConnection.get(...)` and degrade
+ * gracefully when undefined.
+ *
+ * All paths in these interfaces are workspace-relative POSIX-like paths
+ * resolved against the record's `location.root` by the provider. The provider
+ * is responsible for root confinement (and any extra semantics, e.g. SFTP
+ * mode bits), so a consumer can treat every workspace uniformly.
+ *
+ * @module @tiphareth/dsh-hardssh/base/capability
+ */
+/** Uniform stat shape (both backends normalize to this). */
+export interface WorkspaceStat {
+    type: 'dir' | 'file' | 'other';
+    size: number;
+    mtimeMs: number;
+    mode?: number;
+}
+/** One directory entry. */
+export interface WorkspaceDirEntry {
+    name: string;
+    type: 'dir' | 'file' | 'other';
+    size: number;
+    mtimeMs: number;
+}
+/** File-system capability. */
+export interface WorkspaceFileSystem {
+    stat(path: string, signal?: AbortSignal): Promise<WorkspaceStat | undefined>;
+    list(path: string, signal?: AbortSignal): Promise<WorkspaceDirEntry[]>;
+    readFile(path: string, signal?: AbortSignal): Promise<Uint8Array>;
+    writeFile(path: string, data: Uint8Array, signal?: AbortSignal): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    rename(from: string, to: string, signal?: AbortSignal): Promise<void>;
+}
+/** One process result. */
+export interface WorkspaceProcessResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    timedOut?: boolean;
+    durationMs?: number;
+}
+/** Subprocess capability. */
+export interface WorkspaceProcessRuntime {
+    exec(command: string, options?: {
+        timeoutMs?: number;
+        cwd?: string;
+        signal?: AbortSignal;
+    }): Promise<WorkspaceProcessResult>;
+}
+/** Interactive terminal capability. */
+export interface WorkspaceTerminalService {
+    openTerminal(cols: number, rows: number): Promise<WorkspaceTerminalHandle>;
+}
+/** Minimal PTY handle (mirrors the ssh provider's duck-typed handle). */
+export interface WorkspaceTerminalHandle {
+    shell: string;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(): void;
+    onData(handler: (data: string) => void): {
+        dispose(): void;
+    };
+    onExit(handler: (event: {
+        exitCode: number;
+    }) => void): {
+        dispose(): void;
+    };
+}
+/** One filename-search hit. */
+export interface WorkspaceSearchHit {
+    /** Absolute path on the provider. */
+    path: string;
+    /** Path relative to the search root. */
+    rel: string;
+    isDir: boolean;
+}
+/** Filename / content search capability. */
+export interface WorkspaceSearchService {
+    /** glob-style filename search. */
+    glob(pattern: string, options?: {
+        root?: string;
+        maxDepth?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        hits: WorkspaceSearchHit[];
+        truncated: boolean;
+    }>;
+    /** fixed-string content search (skips .git / node_modules). */
+    grep(fixedPhrase: string, options?: {
+        root?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        hits: WorkspaceSearchHit[];
+        truncated: boolean;
+    }>;
+}
+//# sourceMappingURL=capability.d.ts.map

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

@@ -0,0 +1,18 @@
+/**
+ * @tiphareth/dsh-hardssh/base — the generic workspace base.
+ *
+ * Provider-agnostic core: workspace model, provider/connection/capability
+ * contracts, registry, ledger, namespace codec, router, and the plugin
+ * registration API. No SSH, no Cordis, no React.
+ *
+ * @module @tiphareth/dsh-hardssh/base
+ */
+export * from './model.ts';
+export * from './capability.ts';
+export * from './registry.ts';
+export * from './ledger.ts';
+export * from './namespace.ts';
+export * from './router.ts';
+export * from './ledger-router.ts';
+export * from './plugin.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/base/ledger-router.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Ledger-backed workspace router — the concrete `WorkspaceRouter` that ties
+ * the ledger's anchor index, the namespace codec, and the provider registry
+ * together. Any provider can be routed through this router with zero SSH
+ * knowledge: a session cwd inside a workspace's anchor resolves to that
+ * workspace's provider connection; an explicit `wfs://…` (or legacy `ssh:…`)
+ * target key resolves to the owning connection.
+ *
+ * The router opens connections lazily and caches them per workspace id;
+ * removed workspaces drop their connections so stale keys fail closed.
+ *
+ * @module @tiphareth/dsh-hardssh/base/ledger-router
+ */
+import type { WorkspaceConnection, WorkspaceRecord } from './model.ts';
+import { type WorkspaceNamespaceCodec, type WorkspaceRoute } from './namespace.ts';
+import type { WorkspaceRegistry } from './registry.ts';
+import { type WorkspaceLedger } from './ledger.ts';
+import type { WorkspaceResolution, WorkspaceRouter } from './router.ts';
+/** Open-or-reuse strategy for workspace connections. */
+export interface LedgerRouterOptions {
+    codec?: WorkspaceNamespaceCodec;
+    /** Called with the record; resolves to a connection (undefined = cannot open). */
+    open(record: WorkspaceRecord, signal?: AbortSignal): Promise<WorkspaceConnection | undefined>;
+    /** Called when a workspace is removed (drop cache / pool leases). */
+    onRemoved?(workspaceId: string): void;
+}
+/** Ledger + registry based router. */
+export declare class LedgerWorkspaceRouter implements WorkspaceRouter {
+    private readonly ledger;
+    private readonly registry;
+    private readonly options;
+    readonly codec: WorkspaceNamespaceCodec;
+    private readonly connections;
+    private readonly anchors;
+    constructor(ledger: WorkspaceLedger, registry: WorkspaceRegistry, options: LedgerRouterOptions);
+    private reindex;
+    private openFor;
+    fromNamespace(key: string): WorkspaceResolution | undefined;
+    fromAnchor(cwd: string | undefined): WorkspaceConnection | undefined;
+    resolveRoute(route: WorkspaceRoute): WorkspaceResolution | undefined;
+    /** Async open used by the adapter at mount time (pre-warm active records). */
+    ensureOpen(record: WorkspaceRecord, signal?: AbortSignal): Promise<WorkspaceConnection | undefined>;
+    /** All currently cached connections (for lifecycle/teardown). */
+    connectionsSnapshot(): WorkspaceConnection[];
+    /** Close every cached connection (plugin teardown). */
+    closeAll(): Promise<void>;
+}
+//# sourceMappingURL=ledger-router.d.ts.map