dsh-over-ssh 0.1.0 → 0.2.0

package/lib/types/src/host/app/transport-selector.d.ts

@@ -1,98 +0,0 @@
-/**
- * Transport selection: which implementation serves a connection, and why.
- *
- * The decision is **probe-driven**, never platform-guessed (ADR-0006): a mux failure measured on
- * this machine is remembered, and a later decision for the same connection changes accordingly.
- * Everything observable about the decision is returned as a structured record so the connection
- * UI can show *why* a connection is slower instead of hiding it.
- *
- * @module dsh-remote-workspace/app/transport-selector
- */
-import type { ConnectionProfile, TransportKind } from '../domain/connection.ts';
-import type { MultiplexingCache } from '../infra/transport/transport.ts';
-/** Stable reasons a transport was chosen. */
-export type TransportReason = 'explicit-ssh2' | 'explicit-alias' | 'explicit-agent' | 'agent-unavailable' | 'password-requires-ssh2' | 'no-multiplexing' | 'ssh2-unavailable' | 'alias-required' | 'default-alias';
-/** A non-fatal loss of quality the user should know about. */
-export interface TransportDegradation {
-    /** Stable code for the UI to branch on. */
-    readonly code: 'no-connection-reuse' | 'ssh2-unavailable' | 'alias-unavailable' | 'password-needs-key' | 'agent-unavailable';
-    /** Actionable, user-facing sentence. */
-    readonly hint: string;
-}
-/** The outcome of one selection. */
-export interface TransportDecision {
-    readonly connectionId: string;
-    readonly kind: TransportKind;
-    readonly reason: TransportReason;
-    /** One sentence for the UI/status badge. */
-    readonly hint: string;
-    readonly degradations: readonly TransportDegradation[];
-    /** Whether commands can share one connection (`false` on Windows without ssh2, for example). */
-    readonly reusesConnection: boolean;
-}
-/** Whether the optional Tier 2 agent can serve this connection right now. */
-export interface AgentAvailability {
-    /**
-     * `false` only when a previous ladder run already failed (the reason is then required).
-     *
-     * `true` and `undefined` both mean "the selector cannot know yet": an explicit agent choice is honoured
-     * optimistically and the async preflight downgrades it after running the ladder.
-     */
-    readonly available: boolean;
-    /** Why it is unavailable (the ladder's reason), for the UI. */
-    readonly reason?: string;
-    /** One sentence for the status badge. */
-    readonly hint?: string;
-}
-/** Facts the selector needs. All of them are injected so this module stays testable offline. */
-export interface TransportSelectionInput {
-    readonly profile: ConnectionProfile;
-    /** Whether the `ssh2` dependency is loadable in this build. */
-    readonly ssh2Available: boolean;
-    /** Remembers hosts whose `ssh` client cannot multiplex. */
-    readonly multiplexing: Pick<MultiplexingCache, 'isUnsupported' | 'reasonFor'>;
-    /** `ssh` executable name, for the multiplexing cache key. */
-    readonly sshBinary?: string;
-    /** Tier 2 availability. Absent means "not considered", which keeps the agent strictly opt-in. */
-    readonly agent?: AgentAvailability;
-}
-/**
- * Choose a transport for one connection.
- *
- * Order of concerns: an explicit user choice wins unless it cannot work at all (password auth on
- * the system client, a missing dependency); only then is another implementation substituted, and
- * the substitution is always reported as a degradation.
- *
- * @param input - profile plus injected environment facts.
- * @returns the decision, including every degradation.
- */
-export declare function selectTransport(input: TransportSelectionInput): TransportDecision;
-/** Records observed facts so later decisions reflect reality. */
-export declare class TransportSelector {
-    #private;
-    constructor(options: {
-        readonly multiplexing: Pick<MultiplexingCache, 'isUnsupported' | 'reasonFor'> & Partial<Pick<MultiplexingCache, 'markUnsupported'>>;
-        readonly ssh2Available: boolean;
-        readonly sshBinary?: string;
-    });
-    /** Whether the `ssh2` dependency is currently loadable. */
-    get ssh2Available(): boolean;
-    /** Late-bound availability (the dependency is loaded lazily). */
-    setSsh2Available(available: boolean): void;
-    /**
-     * Decide for one profile.
-     *
-     * @param profile - the saved connection.
-     * @returns the decision.
-     * @throws SshDevError `CONNECTION_INVALID` when no implementation can serve the connection.
-     */
-    decide(profile: ConnectionProfile): TransportDecision;
-    /**
-     * Record that this connection's `ssh` client could not multiplex.
-     *
-     * Called by the integration layer right after an {@link AliasTransport} connect attempt, so the
-     * next decision (and every other connection sharing the same client+alias) picks ssh2.
-     */
-    noteMultiplexingFailure(profile: ConnectionProfile, reason: string): void;
-}
-//# sourceMappingURL=transport-selector.d.ts.map

package/lib/types/src/host/app/transport-service.d.ts

@@ -1,75 +0,0 @@
-/**
- * Transport lifecycle: acquire, reuse, replace and release one transport per connection.
- *
- * The service owns three behaviours the rest of the plugin relies on:
- *
- *  1. **One transport per connection**, created lazily and shared by every caller (single flight).
- *  2. **Replacement on a changed decision**: when the selector's answer changes (for example after
- *     a mux failure is recorded), the old transport is disposed and a new one built, so a stale
- *     decision can never keep serving traffic.
- *  3. **Explicit release**, so shutting a connection down closes its process/connection rather
- *     than leaving it to the garbage collector.
- *
- * The transport contract lives in `infra/transport/transport.ts` and is imported as a type only,
- * which keeps this module free of implementation and of the core packages.
- *
- * @module dsh-remote-workspace/app/transport-service
- */
-import type { ConnectionProfile } from '../domain/connection.ts';
-import type { Transport } from '../infra/transport/transport.ts';
-import type { TransportDecision } from './transport-selector.ts';
-import type { TransportSelector } from './transport-selector.ts';
-/** Creates the implementation chosen by the selector. */
-export interface TransportFactories {
-    readonly createAlias: (profile: ConnectionProfile, decision: TransportDecision) => Transport;
-    readonly createSsh2: (profile: ConnectionProfile, decision: TransportDecision) => Transport;
-    /**
-     * Creates the Tier 2 agent transport. Optional: a build without the agent (or without a shipped binary)
-     * simply omits it, and the selector never chooses `agent` in that case.
-     */
-    readonly createAgent?: (profile: ConnectionProfile, decision: TransportDecision) => Transport;
-}
-/**
- * Optional asynchronous step between deciding and connecting.
- *
- * The synchronous selector cannot know whether the agent's install ladder succeeded — that requires
- * talking to the host. A preflight therefore gets the first decision and may revise it (for example
- * `agent` → `alias` once the ladder reported a reason), which is how "agent unavailable ⇒ fall back to
- * Tier 1" is enforced *before* a transport is built.
- */
-export type TransportPreflight = (profile: ConnectionProfile, decision: TransportDecision) => Promise<TransportDecision>;
-/** One acquired transport plus the decision that produced it. */
-export interface AcquiredTransport {
-    readonly transport: Transport;
-    readonly decision: TransportDecision;
-}
-/** Facts injected for testability. */
-export interface TransportServiceOptions {
-    readonly selector: TransportSelector;
-    readonly factories: TransportFactories;
-    /** See {@link TransportPreflight}. Omitted means "no revision". */
-    readonly preflight?: TransportPreflight;
-}
-/** Owns one transport instance per connection. */
-export declare class TransportService {
-    #private;
-    constructor(options: TransportServiceOptions);
-    /**
-     * Get a connected transport for a profile, creating it if needed.
-     *
-     * @param profile - the connection to serve.
-     * @param signal - cancellation for the connect attempt.
-     * @returns the transport and the decision behind it (after any preflight revision).
-     * @throws SshDevError from the selector or from the transport's own connect.
-     */
-    acquire(profile: ConnectionProfile, signal?: AbortSignal): Promise<AcquiredTransport>;
-    /** The cached transport for a connection, if any. */
-    current(connectionId: string): AcquiredTransport | undefined;
-    /** Decisions currently in force, for the connection status UI. */
-    decisions(): readonly TransportDecision[];
-    /** Dispose and forget one connection. */
-    release(connectionId: string): Promise<void>;
-    /** Dispose every connection (plugin unload, connection-service shutdown). */
-    disposeAll(): Promise<void>;
-}
-//# sourceMappingURL=transport-service.d.ts.map

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

@@ -1,461 +0,0 @@
-/**
- * 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