npm - @tiphareth/dsh-hardssh - Versions diffs - 0.1.2 - Mend

@tiphareth/dsh-hardssh 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (165) hide show

package/README.md +50 -0
package/cordis.patch.yml +26 -0
package/lib/client.js +17780 -0
package/lib/environment-BL1jddfB.js +449 -0
package/lib/fs.js +478 -0
package/lib/index.js +6758 -0
package/lib/subprocess.js +600 -0
package/lib/switch-fs-CAJpFY9C.js +193 -0
package/lib/switch-fs-RrZtG2gv.js +210 -0
package/lib/types/backend.d.ts +108 -0
package/lib/types/base/capability.d.ts +107 -0
package/lib/types/base/index.d.ts +18 -0
package/lib/types/base/ledger-router.d.ts +48 -0
package/lib/types/base/ledger.d.ts +82 -0
package/lib/types/base/model.d.ts +108 -0
package/lib/types/base/namespace.d.ts +57 -0
package/lib/types/base/plugin.d.ts +102 -0
package/lib/types/base/registry.d.ts +60 -0
package/lib/types/base/router.d.ts +40 -0
package/lib/types/client/api.d.ts +85 -0
package/lib/types/client/directory-flow.d.ts +82 -0
package/lib/types/client/icons.d.ts +19 -0
package/lib/types/client/index.d.ts +34 -0
package/lib/types/client/locales.d.ts +104 -0
package/lib/types/client/manager-button.d.ts +32 -0
package/lib/types/client/migrate.d.ts +20 -0
package/lib/types/client/ssh/api.d.ts +89 -0
package/lib/types/client/ssh/apply.d.ts +23 -0
package/lib/types/client/ssh/locales.d.ts +156 -0
package/lib/types/client/ssh/mount.d.ts +13 -0
package/lib/types/client/ssh/panel/ClusterTab.d.ts +8 -0
package/lib/types/client/ssh/panel/HostFingerprintDialog.d.ts +16 -0
package/lib/types/client/ssh/panel/HostFormDialog.d.ts +13 -0
package/lib/types/client/ssh/panel/HostsTab.d.ts +10 -0
package/lib/types/client/ssh/panel/SessionSecretDialog.d.ts +16 -0
package/lib/types/client/ssh/panel/SshPanel.d.ts +14 -0
package/lib/types/client/ssh/panel/TerminalTab.d.ts +12 -0
package/lib/types/client/ssh/panel/TransferTab.d.ts +8 -0
package/lib/types/client/ssh/panel/TunnelsTab.d.ts +8 -0
package/lib/types/client/ssh/panel/controller.d.ts +23 -0
package/lib/types/client/ssh/panel/helpers.d.ts +15 -0
package/lib/types/client/ssh/panel/xterm.css.d.ts +3 -0
package/lib/types/client/ssh/sidebar-entry.d.ts +25 -0
package/lib/types/client/state.d.ts +32 -0
package/lib/types/client/text.d.ts +11 -0
package/lib/types/client/workspace-badges.d.ts +38 -0
package/lib/types/client/workspace-gate.d.ts +15 -0
package/lib/types/client-http.d.ts +15 -0
package/lib/types/core.d.ts +43 -0
package/lib/types/fs.d.ts +36 -0
package/lib/types/host-http.d.ts +25 -0
package/lib/types/index.d.ts +53 -0
package/lib/types/ledger.d.ts +132 -0
package/lib/types/protocol.d.ts +101 -0
package/lib/types/providers/index.d.ts +19 -0
package/lib/types/providers/local/provider.d.ts +58 -0
package/lib/types/providers/ssh/provider.d.ts +112 -0
package/lib/types/remote/environment.d.ts +29 -0
package/lib/types/remote/output.d.ts +38 -0
package/lib/types/remote/remote-fs.d.ts +69 -0
package/lib/types/remote/remote-process.d.ts +41 -0
package/lib/types/remote/remote-subprocess.d.ts +31 -0
package/lib/types/remote/remote-terminal.d.ts +41 -0
package/lib/types/remote-runner.d.ts +83 -0
package/lib/types/remote-search.d.ts +50 -0
package/lib/types/routes.d.ts +24 -0
package/lib/types/runtime/workspace-core.d.ts +59 -0
package/lib/types/seam-state.d.ts +69 -0
package/lib/types/shell.d.ts +8 -0
package/lib/types/ssh/connection/lease.d.ts +16 -0
package/lib/types/ssh/connection/pool.d.ts +57 -0
package/lib/types/ssh/engine.d.ts +434 -0
package/lib/types/ssh/exec/output.d.ts +31 -0
package/lib/types/ssh/known-hosts.d.ts +89 -0
package/lib/types/ssh/plugin.d.ts +57 -0
package/lib/types/ssh/protocol.d.ts +236 -0
package/lib/types/ssh/routes.d.ts +44 -0
package/lib/types/ssh/store.d.ts +107 -0
package/lib/types/ssh/tools.d.ts +35 -0
package/lib/types/ssh/transfer/progress.d.ts +14 -0
package/lib/types/ssh/vault.d.ts +110 -0
package/lib/types/subprocess.d.ts +32 -0
package/lib/types/switch/switch-fs.d.ts +88 -0
package/lib/types/switch/switch-subprocess.d.ts +34 -0
package/lib/types/tools.d.ts +12 -0
package/package.json +134 -0
package/src/backend.ts +624 -0
package/src/base/capability.ts +86 -0
package/src/base/index.ts +18 -0
package/src/base/ledger-router.ts +128 -0
package/src/base/ledger.ts +299 -0
package/src/base/model.ts +118 -0
package/src/base/namespace.ts +102 -0
package/src/base/plugin.ts +170 -0
package/src/base/registry.ts +109 -0
package/src/base/router.ts +43 -0
package/src/client/api.ts +196 -0
package/src/client/css-modules.d.ts +5 -0
package/src/client/directory-flow.tsx +482 -0
package/src/client/icons.tsx +50 -0
package/src/client/index.ts +210 -0
package/src/client/locales.ts +105 -0
package/src/client/manager-button.tsx +269 -0
package/src/client/migrate.ts +109 -0
package/src/client/ssh/api.ts +411 -0
package/src/client/ssh/apply.ts +50 -0
package/src/client/ssh/locales.ts +322 -0
package/src/client/ssh/mount.tsx +83 -0
package/src/client/ssh/panel/ClusterTab.tsx +123 -0
package/src/client/ssh/panel/HostFingerprintDialog.tsx +82 -0
package/src/client/ssh/panel/HostFormDialog.tsx +228 -0
package/src/client/ssh/panel/HostsTab.tsx +236 -0
package/src/client/ssh/panel/SessionSecretDialog.tsx +80 -0
package/src/client/ssh/panel/SshPanel.tsx +77 -0
package/src/client/ssh/panel/TerminalTab.tsx +176 -0
package/src/client/ssh/panel/TransferTab.tsx +232 -0
package/src/client/ssh/panel/TunnelsTab.tsx +177 -0
package/src/client/ssh/panel/controller.ts +48 -0
package/src/client/ssh/panel/helpers.ts +26 -0
package/src/client/ssh/panel/panel.module.css +1006 -0
package/src/client/ssh/panel/xterm.css.ts +2 -0
package/src/client/ssh/sidebar-entry.ts +123 -0
package/src/client/state.ts +99 -0
package/src/client/text.ts +22 -0
package/src/client/workspace-badges.ts +96 -0
package/src/client/workspace-gate.ts +225 -0
package/src/client/workspace.module.css +283 -0
package/src/client-http.ts +45 -0
package/src/core.ts +47 -0
package/src/fs.ts +85 -0
package/src/host-http.ts +74 -0
package/src/index.ts +244 -0
package/src/ledger.ts +416 -0
package/src/protocol.ts +114 -0
package/src/providers/index.ts +34 -0
package/src/providers/local/provider.ts +179 -0
package/src/providers/ssh/provider.ts +274 -0
package/src/remote/environment.ts +123 -0
package/src/remote/output.ts +142 -0
package/src/remote/remote-fs.ts +532 -0
package/src/remote/remote-process.ts +203 -0
package/src/remote/remote-subprocess.ts +159 -0
package/src/remote/remote-terminal.ts +141 -0
package/src/remote-runner.ts +201 -0
package/src/remote-search.ts +163 -0
package/src/routes.ts +395 -0
package/src/runtime/workspace-core.ts +154 -0
package/src/seam-state.ts +185 -0
package/src/shell.ts +10 -0
package/src/ssh/connection/lease.ts +17 -0
package/src/ssh/connection/pool.ts +275 -0
package/src/ssh/engine.ts +1761 -0
package/src/ssh/exec/output.ts +70 -0
package/src/ssh/known-hosts.ts +214 -0
package/src/ssh/plugin.ts +184 -0
package/src/ssh/protocol.ts +227 -0
package/src/ssh/routes.ts +892 -0
package/src/ssh/store.ts +544 -0
package/src/ssh/tools.ts +402 -0
package/src/ssh/transfer/progress.ts +75 -0
package/src/ssh/vault.ts +477 -0
package/src/subprocess.ts +71 -0
package/src/switch/switch-fs.ts +253 -0
package/src/switch/switch-subprocess.ts +59 -0
package/src/tools.ts +221 -0

package/lib/types/client/ssh/sidebar-entry.d.ts ADDED Viewed

@@ -0,0 +1,25 @@
+/**
+ * Sidebar entry injection.
+ *
+ * dsh's sidebar shell exposes no slot an external plugin can register into,
+ * so — following the task-board precedent of DOM-level extension — the entry
+ * row is injected between the shell's New Session button and the workspace
+ * browser. The injection self-heals: a MutationObserver watches the sidebar
+ * root and re-inserts the row whenever a React re-render displaces it
+ * (re-insertion happens in the same frame, before paint, so no flicker).
+ *
+ * The row is plain DOM (no React tree) so it can never disturb the shell's
+ * reconciliation; the panel view it toggles is a separate React root mounted
+ * in the center column (see mount.tsx).
+ */
+import type { PanelController } from './panel/controller.ts';
+/** Stable data attribute identifying the injected entry row. */
+export declare const ENTRY_SELECTOR = "[data-dsh-ssh-entry]";
+/**
+ * Mount the sidebar entry, waiting for the shell to render and self-healing
+ * on later React re-renders.
+ * @param controller - the panel controller the entry toggles.
+ * @returns disposer removing the entry and its observers.
+ */
+export declare function mountSidebarEntry(controller: PanelController): () => void;
+//# sourceMappingURL=sidebar-entry.d.ts.map

package/lib/types/client/state.d.ts ADDED Viewed

@@ -0,0 +1,32 @@
+/**
+ * Client-side SSH workspace state: the list of SSH-bound workspaces plus a
+ * light poll (3s) keeping it fresh. The snapshot is replaced only on
+ * successful fetches, so React's useSyncExternalStore sees stable references
+ * between polls. There is NO global local/remote mode anymore — a session's
+ * execution world is decided host-side by its cwd (an anchor path of an SSH
+ * workspace routes remote); this client state only drives the management UI
+ * (list / create / delete) and the sidebar title annotations.
+ */
+import type { SshWorkspaceRecord } from '../protocol.ts';
+import type { WorkspaceApi } from './api.ts';
+export interface WorkspaceManagerState {
+    /** SSH-bound workspaces, in creation order. */
+    workspaces: SshWorkspaceRecord[];
+    /** Whether the last load failed (keeps the previous list). */
+    error: string | null;
+}
+export declare class WorkspaceManager {
+    private readonly api;
+    private state;
+    private readonly listeners;
+    private timer;
+    constructor(api: WorkspaceApi);
+    getSnapshot(): WorkspaceManagerState;
+    subscribe(listener: () => void): () => void;
+    private emit;
+    refresh(): Promise<void>;
+    start(): void;
+    stop(): void;
+    remove(id: string): Promise<void>;
+}
+//# sourceMappingURL=state.d.ts.map

package/lib/types/client/text.d.ts ADDED Viewed

@@ -0,0 +1,11 @@
+/**
+ * Tiny localization helper: resolves the active dictionary (zh when the
+ * document language starts with zh, else en). The dictionary is swapped by
+ * the plugin's apply() on <html lang> changes.
+ */
+import { type WorkspaceKey } from './locales.ts';
+/** Switch the active dictionary (called by the client entry on lang change). */
+export declare function setLanguage(zhMode: boolean): void;
+/** Resolve one copy key (supports %s / %d substitution). */
+export declare function tt(key: WorkspaceKey, ...args: Array<string | number>): string;
+//# sourceMappingURL=text.d.ts.map

package/lib/types/client/workspace-badges.d.ts ADDED Viewed

@@ -0,0 +1,38 @@
+/**
+ * Sidebar workspace-row augmentation: labels every host workspace row whose
+ * title matches an SSH-bound workspace with a compact remote badge
+ * (`alias @ remoteRoot`), so a glance tells a local workspace from a remote
+ * one. Pure DOM-level extension (the sidebar shell exposes no slot for row
+ * decoration), following the dsh-ssh sidebar-entry precedent: a
+ * MutationObserver self-heals when React re-renders displace the injected
+ * badge.
+ *
+ * The row title alone matches: SSH-bound workspace titles are unique enough
+ * in practice (the ledger title is what the row shows). A title match against
+ * `~/.dsh/ssh-workspaces/<id>` anchors also works when the host picks that
+ * default title.
+ *
+ * @module dsh-hardssh/client/workspace-badges
+ */
+/** Render a small remote badge element. The cloud icon marks "remote";
+ *  connected servers render in DeepSeek blue, disconnected stay gray. The
+ *  tooltip shows the REMOTE directory plus the server, e.g.
+ *  `/data/app (prod-01)`. */
+export declare function makeBadge(alias: string, remoteRoot: string, connected: boolean): HTMLElement;
+/**
+ * Mount the row-decoration pass. Queries the sidebar for project rows and
+ * appends a remote badge when the row's title belongs to an SSH workspace.
+ * Badges of aliases in `connected` render blue, others gray. Self-heals via
+ * MutationObserver on the sidebar container (rows re-render on
+ * session/workspace changes).
+ * @param workspaces - the SSH workspace records (id/title/alias/remoteRoot).
+ * @param connected - aliases with a live pooled connection (badge coloring).
+ * @returns disposer.
+ */
+export declare function mountWorkspaceBadges(workspaces: Array<{
+    id: string;
+    title: string;
+    alias: string;
+    remoteRoot: string;
+}>, connected?: ReadonlySet<string>): () => void;
+//# sourceMappingURL=workspace-badges.d.ts.map

package/lib/types/client/workspace-gate.d.ts ADDED Viewed

@@ -0,0 +1,15 @@
+import type { SshApi } from './ssh/api.ts';
+/** Silent prompt-only connection gate (no row / banner) for flows that
+ *  surface their own errors (e.g. the directory browser). */
+export declare function connectHost(api: SshApi, alias: string): Promise<boolean>;
+/**
+ * Mount the click gate over every sidebar workspace row whose title belongs
+ * to an SSH-bound workspace. Self-heals via MutationObserver. Returns a
+ * disposer that removes listeners and injected state.
+ */
+export declare function mountWorkspaceGates(workspaces: Array<{
+    id: string;
+    title: string;
+    alias: string;
+}>, api: SshApi): () => void;
+//# sourceMappingURL=workspace-gate.d.ts.map

package/lib/types/client-http.d.ts ADDED Viewed

@@ -0,0 +1,15 @@
+/**
+ * Browser-side HTTP helpers for the dsh-hardssh route clients.
+ * Plain fetch / same-origin — bundled inline into the client bundle.
+ */
+/** Error carrying the route's JSON error message and stable code/status. */
+export declare class HttpApiError extends Error {
+    readonly code?: string | undefined;
+    readonly status?: number | undefined;
+    constructor(message: string, code?: string | undefined, status?: number | undefined);
+}
+/** Query-string helper (skips undefined and empty values). */
+export declare function buildQuery(params: Record<string, string | number | undefined>): string;
+/** Parse a JSON response or throw an HttpApiError (code/status preserved). */
+export declare function readJson<T>(response: Response): Promise<T>;
+//# sourceMappingURL=client-http.d.ts.map

package/lib/types/core.d.ts ADDED Viewed

@@ -0,0 +1,43 @@
+/**
+ * The shared workspace core: the host store, the SSH engine, and the
+ * workspace ledger, provided as `ctx.hardsshCore` by the main plugin row so
+ * the two switch rows (fs / subprocess) resolve one instance each.
+ */
+import type { SshEngine } from './ssh/engine.ts';
+import type { SshHostEntry, SshHostSummary } from './ssh/protocol.ts';
+import type { SshWorkspaceLedger } from './ledger.ts';
+import type { RemoteWorkspaceRunner } from './remote-runner.ts';
+import type { WorkspaceSeamState } from './seam-state.ts';
+/** Read-only host-store surface exposed on the core (the write paths live in
+ *  the SSH routes, which get the full store). Avoids coupling the core type
+ *  to either the plaintext HostStore or the vault-backed SecureHostStore. */
+export interface HostStoreView {
+    readonly path: string;
+    list(): SshHostEntry[];
+    find(alias: string): SshHostEntry | undefined;
+    summarize(entry: SshHostEntry): SshHostSummary;
+}
+/** One process-wide core shared by every dsh-hardssh row. */
+export interface HardsshCore {
+    hosts: HostStoreView;
+    engine: SshEngine;
+    /** The SSH-bound workspace ledger (anchor dir -> remote dir). */
+    ledger: SshWorkspaceLedger;
+    /** The shared seam state: ledger-derived routing snapshot + per-record
+     *  fs/subprocess instances, consumed by the fs/subprocess switch rows. */
+    seams: WorkspaceSeamState;
+    /** Remote-workspace runner: resolve local anchor paths to remote channels
+     *  (git / files / commands) so other plugins (dsh-workbench-tiphareth) can
+     *  operate SSH-bound workspaces transparently. Optional in older builds. */
+    resolveRemote?: RemoteWorkspaceRunner['resolveRemote'];
+}
+/**
+ * @deprecated Use HardsshCore. Kept as a source-compatible migration alias.
+ */
+export type EasysshCore = HardsshCore;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        hardsshCore: HardsshCore;
+    }
+}
+//# sourceMappingURL=core.d.ts.map

package/lib/types/fs.d.ts ADDED Viewed

@@ -0,0 +1,36 @@
+/**
+ * The `ctx.fs` switch row: provides the workspace-routing filesystem facade in
+ * the host scope. The local backend (the deployment's sandboxed filesystem) is
+ * mounted in an isolated child scope so its own `ctx.fs` provide never
+ * collides. Routing and per-record remote backends are owned by the SHARED
+ * seam state (hardsshCore.seams): the row only binds its per-record backend
+ * factory and reads the state on every call. Every SSH-bound workspace record
+ * gets its OWN remote backend instance bound to that record's alias + remote
+ * root; the facade routes each call by the session cwd — an anchor path of an
+ * SSH workspace routes remote, everything else stays local. The facade
+ * auto-provides `fs` here because the `fs-sandbox` row is disabled by the
+ * profile patch.
+ *
+ * The seam state re-applies the ledger snapshot synchronously on every
+ * commit, so creating or removing an SSH workspace takes effect without a
+ * plugin restart and the fs/subprocess seams can never disagree. Before the
+ * initial ledger load finishes, routing degrades to local with a one-time
+ * warning for anchor-root paths.
+ *
+ * @module dsh-hardssh/fs
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { HardsshCore } from './core.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        hardsshCore: HardsshCore;
+    }
+}
+/** Stable cordis plugin name. */
+export declare const name = "hardssh-fs";
+/** Services required: the shared workspace core (mode store + engine) and the
+ *  sandbox policy the local backend (`SandboxedFileSystem`) consumes. */
+export declare const inject: string[];
+/** Mount the switching filesystem facade. */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=fs.d.ts.map

package/lib/types/host-http.d.ts ADDED Viewed

@@ -0,0 +1,25 @@
+/**
+ * Host-side HTTP route helpers for the dsh-hardssh route family.
+ * HOST-ONLY: these import node:http types and must never end up in the
+ * client bundle (the client half never imports this module).
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** One JSON response. */
+export declare function writeJson(res: ServerResponse, status: number, body: unknown): void;
+/** URL query helper (first value, decoded). */
+export declare function queryParam(url: URL, name: string): string | undefined;
+/** Loopback literal check plus browser same-origin markers (mirrors dsh-ssh). */
+export declare function isLoopbackRequest(request: IncomingMessage): boolean;
+export type ReadJsonBodyResult = {
+    ok: true;
+    body: Record<string, unknown>;
+} | {
+    ok: false;
+    reason: 'too-large' | 'malformed' | 'not-object';
+};
+/**
+ * Read a JSON request body with a hard byte cap. Discriminative result so
+ * the caller keeps its own error mapping (silent undefined vs 400/413).
+ */
+export declare function readJsonBody(req: IncomingMessage, maxBytes: number): Promise<ReadJsonBodyResult>;
+//# sourceMappingURL=host-http.d.ts.map

package/lib/types/index.d.ts ADDED Viewed

@@ -0,0 +1,53 @@
+/**
+ * dsh-hardssh — host half. Owns the local⇄remote mode store, the
+ * /api/dsh-hardssh route family (loopback-only), the remote_* agent
+ * tools, a model-facing announcement section, the shared workspace core
+ * (`ctx.hardsshCore`, including the shared seam state the fs/subprocess
+ * switch rows consume), and — since the legacy dsh-ssh package was merged
+ * in — the SSH operations capability (host manager, ssh_* tools, /api/dsh-ssh,
+ * web terminal). In SSH mode the model's ordinary read/write/edit/bash tools
+ * run transparently on the remote host through those switch rows. File
+ * operations and SSH operations ride ONE shared SshEngine/HostStore over
+ * ~/.dsh/dsh-ssh.json (a single connection pool; SSH ops and workspaces
+ * invalidate together on config change). The browser half (./client) renders
+ * the header buttons, the SSH config dialog, the left workspace panel, and
+ * the SSH host-manager surfaces.
+ *
+ * The announcement section is rendered PER SESSION from the ledger facts
+ * (which workspace this session's cwd binds to), never from path-string
+ * heuristics; and a global tool guard blocks glob/grep/pwsh calls in
+ * SSH-bound sessions with a clear error instead of letting them fail with
+ * "No such file or directory" on the remote host.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Stable cordis plugin name. */
+export declare const name = "hardssh";
+/**
+ * Services required before the workspace surfaces can mount. `webServer` is
+ * deliberately NOT here: headless profiles lack it, and a hard inject would
+ * block the whole load tree — routes register through the dynamic
+ * ctx.inject(['webServer'], …) below (DSH 插件规范 §4.2).
+ */
+export declare const inject: string[];
+/** Plugin config (schemastery; optional fields use .default, never .optional). */
+export interface Config {
+    /** Master switch (default on). Disabling requires reverting the profile seam patch. */
+    enabled: boolean;
+    /** Whether the model-facing announcement section is mounted. */
+    announceToAgent: boolean;
+    /**
+     * Secret storage mode: 'none' (default, VSCode Remote-SSH style: passwords
+     * never persisted, prompted once per session) or 'vault' (encrypted at
+     * rest, for unattended agents). Mirrors the dsh-ssh settings namespace.
+     */
+    secretStorage: 'none' | 'vault';
+}
+export declare const Config: z<Config>;
+/**
+ * Mount the mode store, routes, tools, announcement, guard, and the shared core.
+ * @param ctx - host plugin context carrying tools/systemPrompt (webServer optional).
+ * @param config - resolved plugin config (schema defaults applied by the loader).
+ */
+export declare function apply(ctx: Context, config?: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/ledger.d.ts ADDED Viewed

@@ -0,0 +1,132 @@
+/**
+ * SSH-bound workspace ledger: the mapping from a LOCAL ANCHOR directory (the
+ * host-visible workspace path, which sessions use as their cwd) to a REMOTE
+ * directory on an SSH host. Persisted as JSON next to dsh-ssh.json so the
+ * fs/subprocess seams can route a session whose cwd is an anchor to the
+ * remote execution world, and everything else stays local.
+ *
+ * A ledger record is created through the GUI (pick a host, browse a remote
+ * dir, give it a title). The host-side anchor directory is auto-created
+ * under ~/.dsh/ssh-workspaces/<id>/; the host workspace registry owns it as
+ * a normal local workspace, so session creation/listing/persistence keep
+ * working untouched.
+ *
+ * Mutations are serialized through a per-instance queue and committed as:
+ * write temp file → atomic rename → swap memory/index → bump revision →
+ * notify subscribers. A persistence failure leaves observable state
+ * unchanged and never publishes an event.
+ *
+ * @module dsh-hardssh/ledger
+ */
+import type { SshWorkspaceRecord } from './protocol.ts';
+/** One committed snapshot of the ledger. */
+export interface LedgerSnapshot {
+    revision: number;
+    records: readonly SshWorkspaceRecord[];
+}
+/** One committed mutation, delivered to subscribers. */
+export type LedgerChange = {
+    type: 'created';
+    revision: number;
+    record: SshWorkspaceRecord;
+} | {
+    type: 'renamed';
+    revision: number;
+    before: SshWorkspaceRecord;
+    record: SshWorkspaceRecord;
+} | {
+    type: 'removed';
+    revision: number;
+    record: SshWorkspaceRecord;
+};
+export type LedgerListener = (change: LedgerChange) => void;
+/** Ledger file location: ~/.dsh/dsh-hardssh-workspaces.json. */
+export declare function ledgerPath(): string;
+/**
+ * Normalize a remote POSIX root: keep '/' as '/', collapse repeated
+ * separators and dot segments, reject relative paths and NUL.
+ */
+export declare function normalizeRemoteRoot(raw: string): string;
+/** Anchor roots: ~/.dsh/ssh-workspaces/<id>/ — visible in the sidebar as
+ *  ordinary host workspaces (and thus selectable for sessions). */
+export declare function anchorRoot(): string;
+/** The anchor directory for one id. */
+export declare function anchorPathFor(id: string): string;
+/** Default record title when the user gives none. */
+export declare function defaultTitle(remoteRoot: string, alias: string): string;
+/**
+ * Normalize a local anchor path for comparison: Windows anchors are
+ * case-insensitive with mixed separators; POSIX anchors stay case-sensitive.
+ */
+export declare function normalizeAnchorPath(path: string): string;
+/** True when candidate equals anchor or is one of its descendants. Lexical
+ *  comparison over already-resolved paths; deliberately no fs access. */
+export declare function isPathUnderAnchor(anchor: string, candidate: string): boolean;
+/**
+ * The in-memory ledger. Loaded lazily on first access; every mutation writes
+ * through durably (atomic rename) and is serialized through a per-instance
+ * queue. A synchronous anchor index is maintained from the latest committed
+ * records so host seams can resolve a cwd/root without awaiting I/O.
+ */
+export declare class SshWorkspaceLedger {
+    private readonly fileOverride?;
+    private readonly anchorOverride?;
+    private records;
+    private loadPromise;
+    private anchorIndex;
+    private mutationTail;
+    private currentRevision;
+    private readonly listeners;
+    /** Overridable file location (tests isolate per instance). */
+    constructor(fileOverride?: string | undefined, anchorOverride?: string | undefined);
+    private file;
+    private anchors;
+    private anchorFor;
+    /** Load the ledger once (missing/unreadable/malformed file -> empty ledger). */
+    private ensureLoaded;
+    private readRecords;
+    /** Rebuild the synchronous anchor index from the current records. */
+    private reindex;
+    /** Persist a proposed record array without touching observable state. */
+    private save;
+    /** Serialize one mutation; a rejected earlier mutation never poisons later ones. */
+    private enqueueMutation;
+    /** Commit a computed next state: swap memory, bump revision, notify. */
+    private commit;
+    private emit;
+    /** Load the ledger (compat; returns detached copies). */
+    load(): Promise<SshWorkspaceRecord[]>;
+    /** All records, in creation order (detached copies). */
+    list(): Promise<SshWorkspaceRecord[]>;
+    /** Current detached snapshot. */
+    snapshot(): Promise<LedgerSnapshot>;
+    /** Current in-process snapshot, synchronously (empty before first load).
+     *  The returned records are the live immutable objects — callers must not
+     *  mutate them (commits always replace the array wholesale). */
+    snapshotSync(): LedgerSnapshot;
+    /** Current in-process revision (restarts at 0 on process restart). */
+    revision(): number;
+    /** Subscribe to committed mutations (no initial event). Returns a disposer. */
+    subscribe(listener: LedgerListener): () => void;
+    /** Look up by id. */
+    get(id: string): Promise<SshWorkspaceRecord | undefined>;
+    /** Look up by LOCAL anchor path (resolved). Returns the record whose
+     *  anchor owns the path (the anchor itself or any descendant). */
+    findByAnchor(path: string): Promise<SshWorkspaceRecord | undefined>;
+    /** Synchronous anchor lookup (uses the in-memory index). */
+    findByAnchorSync(path: string): SshWorkspaceRecord | undefined;
+    /** Create a record: materialize the anchor, then persist+commit. */
+    create(input: {
+        title: string;
+        alias: string;
+        remoteRoot: string;
+    }): Promise<SshWorkspaceRecord>;
+    /** Rename a record (display title only). */
+    rename(id: string, title: string): Promise<SshWorkspaceRecord | undefined>;
+    /** Remove a record. The anchor directory is left in place (a host
+     *  workspace may still reference it; the caller decides on deletion). */
+    remove(id: string): Promise<boolean>;
+    /** The anchor root shared by every record (for UI hints). */
+    anchorsRoot(): string;
+}
+//# sourceMappingURL=ledger.d.ts.map

package/lib/types/protocol.d.ts ADDED Viewed

@@ -0,0 +1,101 @@
+/**
+ * Wire contract between the host half (routes.ts) and the browser half
+ * (client/api.ts). Pure types only — imported by both halves, bundled into
+ * each, no runtime identity to share.
+ */
+/** The two workspace modes of the plugin. */
+export type WorkspaceMode = 'local' | 'remote';
+/** The plugin's mode state (host-owned singleton). */
+export interface WorkspaceState {
+    /** Current mode: local = this machine, remote = an SSH host. */
+    mode: WorkspaceMode;
+    /** Active SSH host alias (kept while in local mode so the toggle can return). */
+    alias?: string;
+    /** Resolved absolute remote root (the workspace gate prefix). */
+    remoteRoot?: string;
+    /** Human label of the remote root ('~' when the default home was resolved). */
+    remoteRootLabel?: string;
+}
+/** One directory entry (both backends normalize to this shape). */
+export interface WorkspaceEntry {
+    name: string;
+    type: 'dir' | 'file' | 'other';
+    size: number;
+    mtimeMs: number;
+}
+/** Directory listing response. */
+export interface DirListing {
+    /** The listed absolute path. */
+    path: string;
+    entries: WorkspaceEntry[];
+}
+/** File read response (text only; binary/oversize is rejected with an error). */
+export interface FileRead {
+    path: string;
+    content: string;
+    size: number;
+    mtime: number;
+}
+/** File write response (new mtime for the UI's conflict tracking). */
+export interface FileWriteResult {
+    mtime: number;
+}
+/** One filename-search hit. */
+export interface SearchHit {
+    /** Absolute path. */
+    path: string;
+    /** Path relative to the search root. */
+    rel: string;
+    isDir: boolean;
+}
+/** Filename-search response. */
+export interface SearchView {
+    query: string;
+    hits: SearchHit[];
+    truncated: boolean;
+}
+/** JSON error body used by every route. */
+export interface ApiErrorBody {
+    error: string;
+}
+/** Route paths the client calls (shared literals). */
+export declare const WORKSPACE_API_BASE: "/api/dsh-hardssh";
+export declare const WORKSPACE_API: {
+    readonly state: string;
+    readonly tree: string;
+    readonly file: string;
+    readonly search: string;
+    readonly sshWorkspaces: string;
+    readonly sshWorkspaceDir: string;
+};
+/**
+ * One SSH-bound workspace: a local anchor directory (the host-visible
+ * workspace path, which sessions use as their cwd) bound to a directory on
+ * an SSH host. The fs/subprocess seams route by the anchor path: a session
+ * whose cwd is this anchor operates on the REMOTE directory; everything else
+ * stays local.
+ */
+export interface SshWorkspaceRecord {
+    /** Stable id (uuid). */
+    id: string;
+    /** Display title (sidebar). */
+    title: string;
+    /** SSH host alias (dsh-ssh host store). */
+    alias: string;
+    /** Resolved absolute remote root (the remote directory to operate in). */
+    remoteRoot: string;
+    /** Local anchor directory (host workspace path / session cwd). */
+    anchorPath: string;
+    /** When the record was created. */
+    createdAt: string;
+}
+/** The ledger of SSH-bound workspaces (persisted by the host). */
+export type SshWorkspaceLedger = SshWorkspaceRecord[];
+/** One remote directory entry for the picker tree. */
+export interface RemoteDirEntry {
+    name: string;
+    type: 'dir' | 'file' | 'other';
+    size: number;
+    mtimeMs: number;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/lib/types/providers/index.d.ts ADDED Viewed

@@ -0,0 +1,19 @@
+/**
+ * Registry of every built-in provider. The DSH runtime (and any consumer)
+ * uses this to mount local + ssh providers; third-party providers register
+ * the same way through the base plugin API.
+ *
+ * @module @tiphareth/dsh-hardssh/providers
+ */
+import type { WorkspaceProviderRegistry } from '../base/registry.ts';
+import type { SshEngine } from '../ssh/engine.ts';
+import type { HostStoreView } from '../core.ts';
+/** Register both built-in providers. Returns per-provider disposers. */
+export declare function registerBuiltinProviders(registry: WorkspaceProviderRegistry, deps?: {
+    engine?: SshEngine;
+    hosts?: HostStoreView;
+}): Array<() => void>;
+/** The canonical provider ids. */
+export declare const BUILTIN_PROVIDER_IDS: readonly ["local", "ssh"];
+export type BuiltinProviderId = (typeof BUILTIN_PROVIDER_IDS)[number];
+//# sourceMappingURL=index.d.ts.map

package/lib/types/providers/local/provider.d.ts ADDED Viewed

@@ -0,0 +1,58 @@
+/**
+ * Local provider — the workspace provider for local-disk workspaces. Direct
+ * Node fs implementation of `WorkspaceFileSystem`, so the local provider is
+ * usable OUTSIDE the dsh harness too (a consumer only needs `base`).
+ *
+ * The DSH runtime later re-wraps this over `dsh-fs-sandbox` / `dsh-fs-local`
+ * for sandbox semantics when running inside the harness; the base contract
+ * stays identical.
+ *
+ * @module @tiphareth/dsh-hardssh/providers/local
+ */
+import type { WorkspaceCapabilityMap, WorkspaceConnection, WorkspaceProvider, WorkspaceProviderManifest } from '../../base/model.ts';
+import type { WorkspaceDirEntry, WorkspaceFileSystem, WorkspaceStat } from '../../base/capability.ts';
+/** The local provider manifest. */
+export declare const localProviderManifest: WorkspaceProviderManifest;
+/** One open local workspace connection. */
+export declare class LocalWorkspaceConnection implements WorkspaceConnection {
+    readonly workspaceId: string;
+    private readonly root;
+    readonly providerId = "local";
+    constructor(workspaceId: string, root: string);
+    get<K extends keyof WorkspaceCapabilityMap>(capability: K): WorkspaceCapabilityMap[K] | undefined;
+    status(): 'connecting' | 'ready' | 'degraded' | 'closed';
+    close(): Promise<void>;
+}
+/**
+ * Node-fs implementation of `WorkspaceFileSystem` confined to a root.
+ * Workspace-relative paths (`/src/index.ts`, `src/index.ts`) are resolved
+ * against the root; `..` escapes are rejected; symlinks are not followed
+ * out of the root by the stat path (defense in depth — the contract says
+ * the provider enforces confinement).
+ */
+export declare class LocalWorkspaceFileSystem implements WorkspaceFileSystem {
+    private readonly root;
+    constructor(root: string);
+    /** Resolve a workspace-relative path into an absolute path inside root. */
+    private abs;
+    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>;
+    /** Convenience: check the root exists and is readable (for open()). */
+    accessible(): Promise<boolean>;
+}
+/** The local provider factory. */
+export declare function createLocalWorkspaceProvider(): WorkspaceProvider;
+/** Helper: title mostly used by record factories. */
+export declare function localDefaultTitle(root: string): string;
+//# sourceMappingURL=provider.d.ts.map