dsh-over-ssh 0.1.0 → 0.2.0

package/lib/types/src/host/integration/transfer-tracker.d.ts

@@ -1,106 +0,0 @@
-/**
- * A bounded registry of in-flight and recently finished transfers (FR-2.6.4).
- *
- * Why a registry and not a callback straight into the client: the UI asks "what is happening" whenever it
- * renders, which is a *pull*. Pushing would need a channel this plugin does not have (its client half talks
- * over one HTTP route), so the honest shape is a small table the UI polls.
- *
- * Three rules, each of which is a way a progress UI usually lies:
- *
- *  1. **A finished transfer is kept, not deleted.** A row that vanishes the instant it completes leaves the
- *     user unable to tell "done" from "failed and cleared"; the failure list FR-2.6.4 asks for is exactly
- *     the recent history.
- *  2. **The table is bounded** (`maxEntries`, oldest finished first). An unbounded map keyed by transfer id is
- *     a leak that only shows up after a long session.
- *  3. **`percent` is computed from the bytes that landed, never extrapolated.** A progress bar that jumps to
- *     the end because a chunk was *planned* is worse than no bar.
- *
- * The module imports no cordis and no `node:fs`: it is a table plus transitions, so it is testable offline.
- *
- * @module dsh-remote-workspace/integration/transfer-tracker
- */
-import { type TransferProgress } from '../domain/transfer.ts';
-/** Lifecycle of one tracked transfer. */
-export type TrackedTransferStatus = 'running' | 'done' | 'failed' | 'cancelled';
-/** One tracked transfer, as the UI sees it. */
-export interface TrackedTransfer {
-    readonly id: string;
-    readonly direction: 'upload' | 'download';
-    readonly connectionId: string;
-    /** Remote path (root-absolute). */
-    readonly remotePath: string;
-    /** Local path; for a download this is the destination, for an upload the source. */
-    readonly localPath: string;
-    readonly status: TrackedTransferStatus;
-    readonly progress: TransferProgress;
-    /** Message of the failure, when `status === 'failed'`. */
-    readonly error?: string;
-    /** Machine-readable code of the failure, when the host named one. */
-    readonly errorCode?: string;
-    readonly startedAt: number;
-    /** When it stopped running; absent while it is still running. */
-    readonly finishedAt?: number;
-}
-/** What a caller supplies to open a transfer. */
-export interface TransferStart {
-    readonly direction: 'upload' | 'download';
-    readonly connectionId: string;
-    readonly remotePath: string;
-    readonly localPath: string;
-    readonly totalBytes: number;
-}
-/** The tracker's injected facts. */
-export interface TransferTrackerOptions {
-    /** How many entries to retain, finished ones evicted oldest-first. At least 1. */
-    readonly maxEntries: number;
-    /** Injectable clock. */
-    readonly now?: () => number;
-}
-/** The table. */
-export interface TransferTracker {
-    /** Open a transfer and return its id. */
-    start(input: TransferStart): string;
-    /**
-     * Record progress; unknown ids are ignored (a late callback after eviction must not throw).
-     *
-     * `totalBytes` is carried on every report because the tracker does **not** know the size up front: the plan is
-     * computed inside the transfer service, so the first honest total arrives with the first progress callback.
-     * Guessing a total at `start` would show 100% for a transfer that has barely begun.
-     */
-    progress(id: string, transferredBytes: number, totalBytes?: number): void;
-    /** Mark it finished. */
-    done(id: string, transferredBytes?: number): void;
-    /** Mark it failed, with whatever code the host produced. */
-    fail(id: string, error: string, errorCode?: string): void;
-    /** Mark it cancelled (the user's own action, which is not a failure). */
-    cancel(id: string): void;
-    /**
-     * Close a transfer from the error it threw, choosing between `cancelled` and `failed`.
-     *
-     * The policy lives here rather than at the call site because it is a **domain** rule, not plumbing: a
-     * cancelled transfer is the user's own action, so listing it among failures would bury the real ones — and
-     * the requirement's failure list is the thing that has to stay readable. It sat in the composition root
-     * first, where no test could reach it (audit 0046).
-     *
-     * @param id - the transfer.
-     * @param failure - the thrown value and the code the host produced, if any.
-     */
-    settle(id: string, failure: {
-        readonly code?: string | undefined;
-        readonly message: string;
-    }): void;
-    /** Everything retained, newest first. */
-    list(): readonly TrackedTransfer[];
-    /** One entry, if it is still retained. */
-    get(id: string): TrackedTransfer | undefined;
-    /** Drop every finished entry (the UI's "clear" button). */
-    clearFinished(): number;
-}
-/**
- * Build a tracker.
- *
- * @param options - bounds and clock.
- * @returns the tracker.
- */
-export declare function createTransferTracker(options: TransferTrackerOptions): TransferTracker;
-//# sourceMappingURL=transfer-tracker.d.ts.map

package/lib/types/src/host/integration/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