dsh-over-ssh 0.0.0-stage → 0.1.0

package/lib/types/src/host/integration/user-roots.d.ts

@@ -0,0 +1,461 @@
+/**
+ * User-owned roots and connections, as the **panel** may edit them.
+ *
+ * Two files in the plugin state directory must never be confused:
+ *
+ *  - `roots.json` — the terminal wrapper's manifest ({@link ./terminal-manifest.ts}). It is *derived*: the
+ *    host rewrites it from the live registry after every mutation, and it contains already-resolved ssh
+ *    argv. Nothing here touches it.
+ *  - `user-roots.json` — **this module**. It is the *input*: what the user asked for in the UI, kept across
+ *    restarts so a panel can list and edit roots without the host having to re-derive them from Config.
+ *
+ * Shape (version 1):
+ *
+ * ```json
+ * {
+ *   "version": 1,
+ *   "roots": [{ "location": "remote", "connectionId": "gpu01", "path": "/srv/work", "writable": true }],
+ *   "connections": [{ "id": "gpu01", "host": "gpu01.example.net", "user": "root", "port": 22,
+ *                     "authKind": "key", "keyPath": "~/.ssh/id_ed25519" }]
+ * }
+ * ```
+ *
+ * Non-negotiables this module owns:
+ *
+ *  1. **Atomic writes** — temp file + `rename`, so a reader never sees a half-written document. The temp name
+ *     is unique per write: a shared `${file}.tmp` let two overlapping writers truncate each other's scratch
+ *     file and race on the `rename`.
+ *  2. **Bad JSON never throws at the caller** — {@link parseUserRoots} returns the empty state plus a
+ *     human-readable warning; a single corrupt entry is dropped, not fatal.
+ *  3. **No secret value, ever** — a `password` or `passphrase` **field** is refused with an error that says so
+ *     (密码不入 UI 存储). Passwords belong in `ctx.credentials`. **`authKind: 'password'` itself is accepted**:
+ *     what is stored for it is only `credentialKey`, the *name* of the stored value, and the reference is
+ *     derived from the id when the caller supplies none. (This paragraph used to claim `authKind: 'password'`
+ *     was refused while the same file's {@link normalizeConnectionEntry} accepted it — audit 0043.)
+ *  4. **Every mutation returns a new state** and persists it; nothing mutates a shared object in place.
+ *  5. **A connection rename takes its roots with it** ({@link updateConnectionInState}): a remote root names
+ *     its connection in its key, so an id change that left the roots behind would break them silently.
+ *  6. **Mutations are serialised within this process** ({@link createUserRootsStore}): each one is a
+ *     read-modify-write of one document, so overlapping requests would otherwise lose updates silently.
+ *
+ * This module deliberately imports **no** `@deepseek-ai/*` package: it is pure I/O plus validation, and the
+ * file system is injected so tests never touch the developer's home directory.
+ *
+ * @module dsh-remote-workspace/integration/user-roots
+ */
+/** The only format version this module reads or writes. */
+export declare const USER_ROOTS_VERSION = 1;
+/** File name inside the plugin state directory (`~/.dsh/ssh-dev` by default in the entry). */
+export declare const USER_ROOTS_FILE_NAME = "user-roots.json";
+/** Where a user root lives. */
+export type UserRootLocation = 'local' | 'remote';
+/**
+ * Which authentication a panel-added connection may use.
+ *
+ * The **secret** is what may never appear here: the validator refuses a `password` or `passphrase` field
+ * even when it arrives as raw JSON. `password` authentication is supported, but only as a
+ * {@link UserConnectionRecord.credentialKey} **reference** into `ctx.credentials`.
+ */
+export type UserConnectionAuthKind = 'agent' | 'key' | 'password';
+/**
+ * Which transport a panel-added connection asks for.
+ *
+ * **Not the same thing as {@link UserConnectionAuthKind}'s `agent`**, and the two must never be conflated:
+ * `authKind: 'agent'` names the **local** ssh-agent as a credential source, while `transport: 'agent'` names
+ * the **remote** Tier 2 Go program this plugin uploads on first connect (ADR-0005/0007). The values mirror the
+ * host's own `TransportKind` (`domain/connection.ts`); this module keeps its own copy because it validates the
+ * file, and `transport` is what `toProfileInput` reads to build the profile.
+ */
+export type UserConnectionTransport = 'alias' | 'ssh2' | 'agent';
+/** One root the user added. */
+export interface UserRootEntry {
+    /** Local directory or remote directory. */
+    readonly location: UserRootLocation;
+    /** Non-empty local path, or a POSIX absolute path for a remote root. */
+    readonly path: string;
+    /** Connection id; required exactly for remote roots. */
+    readonly connectionId?: string;
+    /** Display label shown by the panel. */
+    readonly label?: string;
+    /** Whether writes under this root are allowed; the panel's default is `true`. */
+    readonly writable?: boolean;
+    /**
+     * The workspaces this root was added **to** (canonical local paths).
+     *
+     * **Absent means "not added to any session yet"**  -  it does **not** mean "applies to every session". A
+     * session lists only the roots whose `workspaces` names its own workspace path (`session-directory.ts`,
+     * `loadRoots`), so an unscoped root is registered with the host but is listed by no session until one opts
+     * in with 「添加目录」.
+     *
+     * Why it exists: the composer's 「添加目录」 reads as "add this directory to *this* conversation", and the
+     * first version wrote every such root into one flat list  -  so a directory added in one workspace showed up
+     * in the next one, which the user rightly called out. The requirement document already separates the two
+     * (FR-1.7: extra roots live in the plugin's own storage, grouped per project), so the grouping is recorded
+     * here.
+     *
+     * The settings panel adds **unscoped** roots because its form has no scope field at all
+     * (`RootsPanelDrafts` carries no `workspaces` member): it registers a root with the host, and a session opts
+     * in explicitly. An earlier revision of this comment justified listing unscoped roots in *every* session by
+     * claiming that the panel's "own copy says those apply to every session"  -  **no such copy existed**; every
+     * `roots*` string in both dictionaries is about paths, connections, testing and validation (audit 0056).
+     * The silent global visibility that followed  -  a remote directory appearing in a session that had never
+     * added it  -  is why the rule is now the other way round.
+     *
+     * Plural because identity is the **path** ({@link userRootKey}) and the same path can be added to more than
+     * one workspace. The live registry and the router are plugin-wide (a path resolves by scheme/anchor, not by
+     * workspace), so a remote root stays addressable from another workspace. Filtering is a view fact, not a
+     * sandbox.
+     */
+    readonly workspaces?: readonly string[];
+    /**
+     * The local anchor directory this remote root stands on, when it has one.
+     *
+     * It is persisted because it is **identity at the platform level**: the platform creates a workspace on
+     * this host path, so a root whose anchor is re-derived differently (a connection rename changes both the
+     * `connectionId` segment and the digest) silently orphans the workspace that was created on the old one.
+     * The first version derived it on every read and never stored it; a rename then moved every anchor and left
+     * the user's remote workspaces pointing at paths no root covered (`ROOT_OUTSIDE`).
+     *
+     * Absent means "derive it from the connection id and path" (`index.ts`'s `toRoot`), which is what entries
+     * written before this field existed do. Only remote roots may carry it; a local root is its own anchor.
+     */
+    readonly anchorPath?: string;
+}
+/** One connection the user added. Carries **no** credential. */
+export interface UserConnectionRecord {
+    /** Slug, unique in the file. */
+    readonly id: string;
+    /** Host name or IP. */
+    readonly host: string;
+    /** Login user. */
+    readonly user: string;
+    /** TCP port; absent means the ssh default. */
+    readonly port?: number;
+    /** `agent` (ssh-agent / ssh config), `key` (identity file) or `password` (stored secret). */
+    readonly authKind: UserConnectionAuthKind;
+    /**
+     * Transport the user chose in the panel; absent means the default the reader applies (`agent`, see
+     * `toProfileInput` in the entry). Optional rather than defaulted here so an older file keeps loading: a
+     * record written before the selector existed has no opinion, and inventing one on read would be a silent
+     * migration. A **present** value is validated ({@link normalizeConnectionEntry}) and is always one of the
+     * three, so a reader never has to guess whether a spelling is meaningful.
+     */
+    readonly transport?: UserConnectionTransport;
+    /** Identity file path; only meaningful for `authKind: 'key'`. */
+    readonly keyPath?: string;
+    /**
+     * Name of the stored secret, never the secret; only meaningful for `authKind: 'password'`.
+     *
+     * Derived from the id when a caller does not supply one (see `credentialRefFor`), because the platform's
+     * reference grammar is a POSIX identifier and a user-chosen Chinese name is not one.
+     */
+    readonly credentialKey?: string;
+}
+/** The whole persisted document. */
+export interface UserRootsState {
+    readonly version: typeof USER_ROOTS_VERSION;
+    readonly roots: readonly UserRootEntry[];
+    readonly connections: readonly UserConnectionRecord[];
+}
+/** One read of the file: the state plus everything that was wrong with it. */
+export interface UserRootsLoad {
+    readonly state: UserRootsState;
+    /** Non-fatal problems (missing file is **not** one: that is the pristine state). */
+    readonly warnings: readonly string[];
+}
+/** File-system surface, injected so tests never touch the developer's home directory. */
+export interface UserRootsIo {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, data: string): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+}
+/** Real file-system binding: UTF-8, owner-only, atomic. */
+export declare const nodeUserRootsIo: UserRootsIo;
+/** The pristine state: no roots, no connections. */
+export declare function emptyUserRootsState(): UserRootsState;
+/**
+ * Stable identity of a user root, and the key `remove-root` accepts.
+ *
+ * Local paths are normalised for separators and trailing slashes but **keep the caller's case**; remote keys
+ * are POSIX and therefore case-sensitive. `RootRegistry.rootKey` folds case on Windows, so
+ * {@link removeRootFromState} retries once case-insensitively for `local:` keys — otherwise a root listed by
+ * the UI as `D:/Work` could not be removed with the key `local:d:/work`.
+ *
+ * @param entry - a validated (or at least well-formed) root entry.
+ * @returns `local:<path>` or `remote:<connectionId>:<path>`.
+ */
+export declare function userRootKey(entry: UserRootEntry): string;
+/**
+ * The persisted state as JSON text: UTF-8 without BOM, two-space indent, trailing newline.
+ *
+ * The BOM-free part is deliberate — a `\uFEFF` prefix makes `JSON.parse` fail in some readers and is exactly
+ * what `Set-Content -Encoding UTF8` used to add to files in this repository.
+ *
+ * @param state - state to serialise.
+ * @returns the file contents.
+ */
+export declare function serializeUserRoots(state: UserRootsState): string;
+/**
+ * Read the persisted state from text.
+ *
+ * **Never throws.** Every failure mode degrades to the empty state plus a warning that names the reason:
+ * unreadable text is not distinguishable here (the caller catches the I/O error), but malformed JSON, a
+ * foreign `version`, and individual corrupt entries all are.
+ *
+ * @param text - file contents, or `undefined` when the file does not exist.
+ * @returns the usable state and the warnings collected on the way.
+ */
+export declare function parseUserRoots(text: string | undefined): UserRootsLoad;
+/**
+ * Normalise and validate one root entry.
+ *
+ * Rules: `location` must be `local` or `remote`; a local path must be non-empty; a remote path must be a
+ * POSIX **absolute** path and must not be `/` (the whole remote filesystem is not a workspace root); a
+ * remote root must name a valid connection id. Unknown keys are ignored by construction — only the fields
+ * below are read.
+ *
+ * @param input - untrusted value (a JSON body or one entry of the file).
+ * @returns a clean entry.
+ * @throws SshDevError `ROOT_INVALID` when the entry is not usable.
+ */
+export declare function normalizeRootEntry(input: unknown): UserRootEntry;
+/**
+ * Normalise and validate one connection entry.
+ *
+ * **A secret is refused here**, with a message that says why: 密码不入 UI 存储 — a password in this file
+ * would be readable by anything that can read the state directory, and the plugin's credential path is
+ * `ctx.credentials`. A `password` or `passphrase` field is rejected outright. `authKind: 'password'` **is**
+ * accepted, but the record then carries only `credentialKey` — the *name* of the stored value — which is
+ * derived from the id when the caller does not supply one. `keyPath` is kept for `authKind: 'key'` and
+ * dropped for the other two.
+ *
+ * `transport` is optional (absent means "the reader's default", see {@link UserConnectionRecord.transport}),
+ * but a value that **is** present must be one of the three the union allows: an unknown spelling is refused as
+ * `CONNECTION_INVALID` rather than stored, because a record the transport selector cannot read would silently
+ * fall back to a transport the user did not choose.
+ *
+ * @param input - untrusted value.
+ * @returns a clean record, never containing a credential.
+ * @throws SshDevError `CONNECTION_INVALID` when the entry is not usable.
+ */
+export declare function normalizeConnectionEntry(input: unknown): UserConnectionRecord;
+/** Find one persisted entry by key (case-folded like the registry), or `undefined`. */
+export declare function findRootInState(state: UserRootsState, key: string): UserRootEntry | undefined;
+/**
+ * Union `workspaces` into the entry at `key`, keeping the file's own order and de-duplicating.
+ *
+ * The **union** is the point, not a replace: two workspaces that both added the same directory must not
+ * un-list each other. Identity here is the path ({@link userRootKey}), and the live registry refuses the same
+ * path twice  -  so one directory added in two workspaces is one root that two workspaces list.
+ *
+ * @param state - the persisted state to update.
+ * @param key - key of the entry to update.
+ * @param workspaces - the workspaces to add.
+ * @returns a new state, or the same state when nothing changed.
+ */
+export declare function withWorkspaces(state: UserRootsState, key: string, workspaces: readonly string[]): UserRootsState;
+/**
+ * Append a root, returning a new state.
+ *
+ * @param state - current state.
+ * @param input - untrusted entry.
+ * @returns the next state (the input state is untouched).
+ * @throws SshDevError `ROOT_INVALID` on an invalid entry or a duplicate key.
+ */
+export declare function addRootToState(state: UserRootsState, input: unknown): UserRootsState;
+/**
+ * Remove a root by key, returning a new state.
+ *
+ * @param state - current state.
+ * @param key - key from {@link userRootKey} (or from a `GET` response).
+ * @returns the next state.
+ * @throws SshDevError `ROOT_INVALID` when no root matches — a silent no-op would make the panel report
+ * success for a removal that never happened.
+ */
+export declare function removeRootFromState(state: UserRootsState, key: string): UserRootsState;
+/**
+ * Remove one root from **one** workspace, keeping it for the others.
+ *
+ * The add side is a union ({@link withWorkspaces}): one directory added to two workspaces is one root that
+ * both list. The first removal implementation only had the global delete, so removing it in the workspace the
+ * operator was looking at removed it from the other one too - the inverse of the union promise, and the reason
+ * the scoped action exists.
+ *
+ * The root itself disappears only when the last workspace drops it; a root that no workspace lists is a root
+ * no session can see, so keeping it would be a silently unusable entry.
+ *
+ * @param state - current state.
+ * @param key - key from {@link userRootKey} (or from a `GET` response).
+ * @param workspacePath - the workspace to remove it from (canonical local path, compared as stored).
+ * @returns the next state.
+ * @throws SshDevError `ROOT_INVALID` when no root matches, so a no-op cannot be reported as success.
+ */
+export declare function removeRootFromWorkspace(state: UserRootsState, key: string, workspacePath: string): UserRootsState;
+/**
+ * Stamp the given anchor paths onto the entries they name, returning a new state.
+ *
+ * Used by the connection-rename path: the anchor is read from the live registry **before** the roots are
+ * re-keyed, so the new entries keep pointing at the directory the user's workspaces were created on.
+ *
+ * @param state - current state.
+ * @param anchors - root key → anchor path for the entries to stamp.
+ * @returns the next state, or the same object when nothing changed.
+ */
+export declare function withAnchorPaths(state: UserRootsState, anchors: ReadonlyMap<string, string>): UserRootsState;
+/**
+ * Append a connection, returning a new state.
+ *
+ * @param state - current state.
+ * @param input - untrusted entry (must not carry a password).
+ * @returns the next state.
+ * @throws SshDevError `CONNECTION_INVALID` on an invalid entry, a duplicate id, or a password field.
+ */
+export declare function addConnectionToState(state: UserRootsState, input: unknown): UserRootsState;
+/**
+ * Remove a connection **and every remote root that pointed at it**, returning a new state.
+ *
+ * Dropping the roots is not optional: a remote root whose connection is gone makes
+ * `RootRegistry.createRemoteBackend` throw `CONNECTION_NOT_FOUND` on the next use, so leaving it behind
+ * would turn a deletion into a later crash.
+ *
+ * @param state - current state.
+ * @param id - connection id.
+ * @returns the next state.
+ * @throws SshDevError `CONNECTION_INVALID` when no connection has that id.
+ */
+export declare function removeConnectionFromState(state: UserRootsState, id: string): UserRootsState;
+/**
+ * The fields `update-connection` may change. Absent means **keep what is there**.
+ *
+ * `password` is deliberately not here (it is not part of a record, exactly as in
+ * {@link addConnectionToState}); `credentialKey` **is**, because a rename that keeps a password must be
+ * able to keep - or deliberately re-point - the stored reference name.
+ */
+export interface ConnectionPatch {
+    /** New id (a rename). The value must pass {@link normalizeConnectionEntry}'s id rule. */
+    readonly id?: string;
+    readonly host?: string;
+    readonly user?: string;
+    /** A number, or `null`/`''` to drop the field (back to the ssh default). */
+    readonly port?: number | null | '';
+    readonly authKind?: UserConnectionAuthKind;
+    readonly keyPath?: string;
+    readonly transport?: UserConnectionTransport;
+    readonly credentialKey?: string;
+}
+/**
+ * Update one connection **in place**, returning a new state.
+ *
+ * Semantics, all of them deliberate:
+ *
+ *  1. **Absent means unchanged.** The patch is merged over the existing record, so a caller that only wants to
+ *     change the host does not have to restate the authentication - and cannot accidentally drop it.
+ *  2. **A rename migrates the roots.** A remote root names its connection in its own key
+ *     (`remote:<connectionId>:<path>`), so leaving the old id behind would turn every root of that
+ *     connection into a dangling reference that throws `CONNECTION_NOT_FOUND` on next use. The rewrite
+ *     happens here, in the same pure transition, so the file can never hold the two halves out of step.
+ *  3. **The stored secret's reference name survives a rename** unless the patch says otherwise. The reference
+ *     is a name in `ctx.credentials`, derived from the id only when nothing better is known; re-deriving it
+ *     from the new id would **orphan** the stored password (still in the store, no longer reachable) and could
+ *     silently hand it to a later connection whose derived name collides.
+ *  4. **The position in the list is kept**, so the panel's rows do not jump when one is edited.
+ *
+ * @param state - current state.
+ * @param id - id of the connection to update (the **current** id, before any rename).
+ * @param patch - the fields to change; anything absent keeps its value.
+ * @returns the next state.
+ * @throws SshDevError `CONNECTION_INVALID` when the id is unknown, the merged record is invalid, or the new
+ *   id collides with another connection.
+ */
+export declare function updateConnectionInState(state: UserRootsState, id: string, patch: ConnectionPatch): UserRootsState;
+/** What one store instance offers. Every mutation returns the new state **and** writes it. */
+export interface UserRootsStore {
+    /** Absolute path of the state file. */
+    readonly filePath: string;
+    /** Read the file; never throws for content reasons (see {@link parseUserRoots}). */
+    load(): Promise<UserRootsLoad>;
+    /** Validate and persist a whole state. */
+    save(next: UserRootsState): Promise<UserRootsState>;
+    /** Resolves once every write queued so far has settled (both success and failure). */
+    settled(): Promise<unknown>;
+    /** Persist `state + entry` and return the new state. */
+    addRoot(entry: unknown): Promise<UserRootsState>;
+    /** Persist `state - key` and return the new state. */
+    removeRoot(key: string): Promise<UserRootsState>;
+    /** Persist `state + connection` and return the new state. */
+    addConnection(entry: unknown): Promise<UserRootsState>;
+    /** Persist `state - connection` (and its remote roots) and return the new state. */
+    removeConnection(id: string): Promise<UserRootsState>;
+    /**
+     * Persist the patched connection (renaming its roots too when the id changes) and return the new state.
+     *
+     * @param id - the connection's current id.
+     * @param patch - fields to change; anything absent keeps its value.
+     */
+    updateConnection(id: string, patch: ConnectionPatch): Promise<UserRootsState>;
+}
+/** Options for {@link createUserRootsStore}. */
+export interface UserRootsStoreOptions {
+    /** Plugin state directory; the file is {@link USER_ROOTS_FILE_NAME} inside it. */
+    readonly dir: string;
+    /** File-system binding; defaults to the real one. */
+    readonly io?: UserRootsIo;
+}
+/**
+ * Build the store over one state directory.
+ *
+ * Deliberately **not** a class: every method is "read the current file, compute the next state purely, write
+ * it", which is exactly the shape the HTTP handlers need and the shape a test can drive with an in-memory
+ * `io`. There is no in-process cache, so two writers cannot disagree about what is on disk — the cost is
+ * that concurrent writers can still lose an update (read-modify-write is not locked; see the audit's
+ * unverified list).
+ *
+ * @param options - state directory plus an optional injected file system.
+ * @returns the store.
+ */
+export declare function createUserRootsStore(options: UserRootsStoreOptions): UserRootsStore;
+/**
+ * Whether the state already contains the root `key` names.
+ *
+ * The HTTP layer needs this to make its write **idempotent**: it asks the live seam to register a root and
+ * only then reconciles the file, so "already present" must not be treated as a duplicate error.
+ *
+ * @param state - current state.
+ * @param key - key from {@link userRootKey}.
+ * @returns whether a root with that key exists.
+ */
+export declare function stateHasRoot(state: UserRootsState, key: string): boolean;
+/**
+ * Whether the state already contains a connection with that id.
+ *
+ * @param state - current state.
+ * @param id - connection id.
+ * @returns whether the connection exists.
+ */
+export declare function stateHasConnection(state: UserRootsState, id: string): boolean;
+/**
+ * Validate a whole state that is about to be written.
+ *
+ * `save` runs this so a caller cannot persist an entry that {@link normalizeRootEntry} would have rejected —
+ * otherwise the file would become a source of invalid state for every later reader.
+ *
+ * @param next - candidate state.
+ * @returns the normalised state.
+ * @throws SshDevError when any entry is invalid or duplicated.
+ */
+export declare function validateState(next: UserRootsState): UserRootsState;
+/**
+ * Public spelling of {@link sameRootKey} for the route layer.
+ *
+ * The route has to compare keys from three sources that fold differently: the live registry (Windows local
+ * paths already lower-cased), the persisted file (case preserved), and the client (built from the `path` the
+ * answer carried). Without one comparison rule, a Windows local root is listed with a key the host cannot
+ * remove.
+ *
+ * @param left - one key.
+ * @param right - the other key.
+ * @returns whether they name the same root.
+ */
+export declare function sameUserRootKey(left: string, right: string): boolean;
+//# sourceMappingURL=user-roots.d.ts.map

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

@@ -0,0 +1,66 @@
+import { Context } from '@deepseek-ai/cordis';
+import { TransportService } from './host/app/transport/transport-service.ts';
+import { Config } from './config.ts';
+import { type TransferService } from './host/integration/transfer/transfer-service.ts';
+import { type RecycleBinService } from './host/app/recycle-bin/recycle-bin-service.ts';
+import { type SessionAdminService } from './host/app/session-admin/session-admin-service.ts';
+import type { ConnectionEntry, RootEntry, ConnectionDirectory, AgentStatus, ResolvedConfig } from './wiring/helpers.ts';
+/** Plugin name as the loader sees it. */
+export declare const name = "dsh-over-ssh";
+/** No hard dependency: the credentials service is optional and read with `ctx.get`. */
+export declare const inject: string[];
+/** Tunables; all of them are deployment-varying and therefore configuration, not constants. */
+export interface LimitsConfig {
+    readonly maxReadBytes?: number;
+    readonly connectTimeoutMs?: number;
+    readonly commandTimeoutMs?: number;
+    readonly keepAliveSeconds?: number;
+    readonly controlDir?: string;
+    /** Explicit known-hosts file for the system `ssh` transport; omitted means ssh's own default. */
+    readonly knownHostsFile?: string;
+    /** Manifest shipped with the package; defaults to `<package>/agents/agent-manifest.json`. */
+    readonly agentManifestPath?: string;
+    /** Remote directory (relative to the login user's `$HOME`) the agent is installed into. */
+    readonly agentRemoteDir?: string;
+    /** How long an enumerated remote root stays usable for `@` completion (default 30 s). */
+    readonly indexTtlMs?: number;
+    /** Maximum entries kept per enumerated root (default 20 000). */
+    readonly indexMaxEntries?: number;
+    /** Directory the terminal wrapper reads its manifest from (default ~/.dsh/over-ssh). */
+    readonly terminalStateDir?: string;
+}
+/** The plugin configuration, as a human-readable contract (the loader uses the schema above). */
+export interface PluginConfig {
+    readonly connections?: readonly ConnectionEntry[];
+    readonly roots?: readonly RootEntry[];
+    readonly limits?: LimitsConfig;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Validated connection profiles. */
+        sshDevConnections: ConnectionDirectory;
+        /**
+         * The transport service, so other plugins (and the client half's status badge) can read the
+         * decisions currently in force instead of guessing why a connection behaves the way it does.
+         */
+        sshDevTransports: TransportService;
+        /** Tier 2 install outcomes (why the agent is or is not in use). */
+        sshDevAgent: AgentStatus;
+        /** Chunked upload/download between the local machine and one remote root. */
+        sshDevTransfer: TransferService;
+        /** Recycle bin: discard, list, restore, purge, sweep, undo/redo. */
+        sshDevRecycleBin: RecycleBinService;
+        /** Session administration: inventory, delete into the session bin, restore, purge, retention. */
+        sshDevSessionAdmin: SessionAdminService;
+    }
+}
+/**
+ * Install the plugin.
+ *
+ * @param ctx - plugin context.
+ * @param config - validated configuration.
+ * @throws SshDevError when a root names an unknown connection (misconfiguration fails at load).
+ */
+export { Config };
+export declare function apply(ctx: Context, config: ResolvedConfig): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/src/local-bridge-refs.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The `./local-bridge-refs` entry: republish the private realm's stock `fileReferences` as `localFileReferences`.
+ *
+ * A **separate row** from `./local-bridge`, and that separation is load-bearing: the stock
+ * `file-reference-local` injects `workingDirectory`, which sits downstream of the routed `fs`. If one bridge
+ * gated both services it would have to wait for `fileReferences` too, and `fileReferences` cannot activate
+ * until `workingDirectory` does — which cannot happen until the router it is waiting behind exists. Two rows
+ * keep that dependency out of the way: `localFs` appears as soon as `fs` does, `localFileReferences` as soon as
+ * `fileReferences` does.
+ *
+ * @module dsh-over-ssh/local-bridge-refs
+ */
+import { Context } from '@deepseek-ai/cordis';
+import type { FileReferenceService } from '@deepseek-ai/dsh-file-reference';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** The stock `file-reference-local` instance living in this plugin's private realm. */
+        localFileReferences?: FileReferenceService;
+    }
+}
+/** Publish the realm's `fileReferences` as `localFileReferences`. */
+export default class LocalFileReferencesBridge {
+    static inject: readonly ["fileReferences"];
+    constructor(ctx: Context);
+}
+//# sourceMappingURL=local-bridge-refs.d.ts.map

package/lib/types/src/local-bridge.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The `./local-bridge` entry: republish the private realm's stock `fs` under a name the router can inject.
+ *
+ * Composition (see `cordis.patch.yml`): a `cordis:group` with `isolate: { fs: true, fileReferences: true }`
+ * instantiates the **stock** `fs-sandbox` a second time. Because that realm owns its own `fs` slot, the stock
+ * sandbox keeps running and keeps enforcing the platform's write fences for local paths — this plugin no
+ * longer re-implements them.
+ *
+ * The bridge is what carries that instance back out. It is provided under a **new name** (`localFs`), which is
+ * not in the realm's `isolate` list, so the value reaches the root scope where the router injects it.
+ *
+ * Verified against the installed Cordis: inside the realm `fs` resolves to the realm's instance, the root `fs`
+ * slot is untouched, two realms can each own one, and a root-level consumer does resolve `localFs`.
+ *
+ * @module dsh-over-ssh/local-bridge
+ */
+import { Context } from '@deepseek-ai/cordis';
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** The stock `fs-sandbox` instance living in this plugin's private realm; the router's local backend. */
+        localFs?: FileSystem;
+    }
+}
+/**
+ * Publish the realm's `fs` as `localFs`.
+ *
+ * A missing `fs` is a composition error, not something to throw about: the row only loads inside the realm
+ * group that instantiates `fs-sandbox`, and a warning plus a router without a local backend is easier to
+ * diagnose than a failed activation that takes the whole plugin down.
+ */
+export default class LocalFsBridge {
+    static inject: readonly ["fs"];
+    constructor(ctx: Context);
+}
+//# sourceMappingURL=local-bridge.d.ts.map

package/lib/types/src/shared/format.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 纯展示格式化（字节数 / 时长）。
+ *
+ * 为什么单独一层：这两个函数被 **client 与 host 两侧**同时使用，而 client 不允许依赖 host
+ * 内部模块（架构测试 tests/architecture.test.ts 会断言）。放在 `shared/` 是唯一能让
+ * 两侧共享而不产生 client → host 边的位置。
+ *
+ * @module dsh-over-ssh/shared/format
+ */
+/** Render a byte count in binary units (`1536` → `1.5 KiB`). */
+export declare function formatBytes(bytes: number): string;
+/** Render a duration (`350` → `350ms`, `1500` → `1.5s`, `90000` → `1m30s`). */
+export declare function formatDuration(ms: number): string;