dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,552 @@
+/**
+ * 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-over-ssh/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/over-ssh` 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 **sessions** (conversation ids) that added this root  -  the strict identity behind
+     * {@link workspaces}, and the field ADR-0013 decides by.
+     *
+     * `workspaces` cannot separate two conversations opened on the same directory; this can. Written by the
+     * 「添加目录」 card (it knows its `sessionId`) and unioned on re-add, exactly like `workspaces`. **Absent
+     * means "written before ADR-0013"**: such an entry keeps the workspace-level rule, so an upgrade does not
+     * silently take a directory away from the session that added it.
+     */
+    readonly sessions?: 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[];
+    /**
+     * Whether `state` is a **fallback**, not what the file says.
+     *
+     * `true` means this read could not understand the document (unparsable JSON, a foreign `version`, an I/O
+     * error) and substituted {@link emptyUserRootsState}. Writing that fallback back is data loss — every root
+     * and connection the file held disappears — so every write path refuses while this is set
+     * ({@link assertUserRootsWritable}). A **missing** file is not degraded: that is the pristine state, and
+     * creating it is the intended first write.
+     */
+    readonly degraded: boolean;
+}
+/**
+ * The part of a read the write guards look at.
+ *
+ * Structural on purpose: the HTTP layer's `loadUserState` seam hands back `{ state, warnings }` from any
+ * wiring (including a test double that predates this field), so the guards must not require a full
+ * {@link UserRootsLoad}. An **absent** `degraded` means "this wiring never degrades" — true for an in-memory
+ * double, and the safe reading for one that does not implement the check.
+ */
+export interface UserRootsDegradedRead {
+    readonly warnings: readonly string[];
+    readonly degraded?: boolean;
+}
+/**
+ * The refusal a write gets while the file cannot be read (see {@link UserRootsLoad.degraded}).
+ *
+ * Deliberately **not** an `SshDevError`: none of the plugin's codes describes "the plugin's own state file is
+ * unreadable", and inventing one would put a value in the code table that `doc/07-reference/error-codes.md`
+ * (the single owner of that table) does not list. The HTTP layer maps a non-plugin error to 500 and passes
+ * `details.reason` through as its own field, so a client can branch on `reason: 'user-roots-unreadable'`
+ * without matching prose.
+ */
+export declare class UserRootsUnreadableError extends Error {
+    readonly details: {
+        readonly reason: 'user-roots-unreadable';
+        readonly warnings: readonly string[];
+    };
+    constructor(load: UserRootsDegradedRead);
+}
+/**
+ * Refuse a write whose base state is a fallback rather than the file's content.
+ *
+ * Called by every write path (`mutate`, `save`, and the HTTP layer's `reconcile`) so the rule has one
+ * implementation and a new caller cannot forget it.
+ *
+ * @param loaded - the read the write is about to be based on.
+ * @throws UserRootsUnreadableError when `loaded.degraded` is set.
+ */
+export declare function assertUserRootsWritable(loaded: UserRootsDegradedRead): void;
+/** 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;
+/**
+ * Union `sessions` into the entry at `key`, keeping the file's own order and de-duplicating.
+ *
+ * The same union as {@link withWorkspaces} and for the same reason: one directory added by two conversations
+ * is one root that both list, and the second add must not un-list the first. Called only for entries that
+ * already exist; a new entry carries its `sessions` from the request.
+ *
+ * @param state - the persisted state to update.
+ * @param key - key of the entry to update.
+ * @param sessions - the sessions to add.
+ * @returns a new state, or the same state when nothing changed.
+ */
+export declare function withSessions(state: UserRootsState, key: string, sessions: 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;
+/**
+ * Remove one root from **one session**, keeping it for the others.
+ *
+ * The scoped-removal twin of {@link removeRootFromWorkspace}, for the identity ADR-0013 made decisive. A card
+ * that lists a root because *this conversation* added it must be able to drop it without touching the
+ * conversation next door  -  which is exactly what the workspace-scoped removal cannot express when both
+ * conversations sit in the same workspace.
+ *
+ * The entry disappears when its `sessions` list empties: a root that no session lists is a root no session can
+ * see, so keeping it would be a silently unusable entry. `workspaces` is left untouched on the surviving path
+ *  -  it is inert while `sessions` is non-empty (the session rule wins), and rewriting it would erase the record
+ * the legacy path still uses.
+ *
+ * @param state - current state.
+ * @param key - key from {@link userRootKey} (or from a `GET` response).
+ * @param sessionId - the session to remove it from.
+ * @returns the next state.
+ * @throws SshDevError `ROOT_INVALID` when no root matches or the root was not added by that session.
+ */
+export declare function removeRootFromSession(state: UserRootsState, key: string, sessionId: 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/host/app/roots-api-connections.d.ts

@@ -0,0 +1,49 @@
+/**
+ * roots-api-connections
+ *
+ * 连接的 6 个 action：ssh-config 发现/导入、增删改连接、连接自检。
+ *
+ * 从 `roots-api-roots.ts` 拆出（审计 0077）：根与连接是两套独立的状态机，
+ * 原先共处一个 switch，各自的辅助函数也互不相干。
+ *
+ * @module dsh-remote-workspace/app/roots-api-connections
+ */
+import type { RootsApiRequest, RootsApiResponse, RootsApiDeps } from './roots-api-contract.ts';
+export declare function handleConnectionActions(action: string, body: Record<string, unknown>, req: RootsApiRequest, res: RootsApiResponse, deps: RootsApiDeps): Promise<boolean>;
+/**
+ * Importable `~/.ssh/config` aliases, and what the flow refuses.
+ *
+ * The refusal list is the point, not a nicety: a wildcard `Host *` or an alias already imported is skipped
+ * **with its reason and line number**, so the dialog can say why a host the user can see in the file is not on
+ * the list. Silently importing a subset is how a user concludes the feature is broken.
+ */
+export interface SshConfigCandidates {
+    /** Aliases the user may import, already filtered. */
+    readonly candidates: readonly SshConfigCandidate[];
+    /** Patterns that were refused, each with its reason. */
+    readonly skipped: readonly {
+        readonly pattern: string;
+        readonly reason: string;
+        readonly line: number;
+    }[];
+    /** Absolute path the text was read from, when the wiring knows it. */
+    readonly path?: string;
+}
+/** One importable alias, projected to what the dialog renders. */
+export interface SshConfigCandidate {
+    /** The literal alias; also the `ssh` target. */
+    readonly alias: string;
+    /** Resolved host name (falls back to the alias). */
+    readonly host: string;
+    /** Login user when the block named one. */
+    readonly user?: string;
+    /** Port when the block named a numeric one. */
+    readonly port?: number;
+    /** Whether the block named an identity file (the path itself is not sent: see the route's invariant 1). */
+    readonly hasIdentityFile: boolean;
+    /** Whether the block named a ProxyJump. */
+    readonly hasProxyJump: boolean;
+    /** The id this import would create, so the dialog can show and edit it before committing. */
+    readonly suggestedId: string;
+}
+//# sourceMappingURL=roots-api-connections.d.ts.map