dsh-over-ssh 0.1.0 → 0.1.1

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

@@ -1,369 +0,0 @@
-/**
- * The same-origin HTTP route a client panel uses to **edit** roots and connections.
- *
- * Why a plain HTTP route instead of a Typert `@Remote` service (the shape audit 0021 used for reads):
- *
- *  - every action here carries **parameters**, and a Client Remote descriptor with parameters requires a
- *    generated strict codec that this repository cannot produce (`doc/02-platform/client-plugin.md` §4);
- *  - the panel is served from the GUI's own origin, so a relative `fetch` is same-origin: no CORS
- *    concession, no code generation, no `@Remote` registration — exactly the shape the third-party
- *    `dsh-plugin-stock-market` uses (`ctx.webServer.register({ kind: 'exact', path, handler })`).
- *
- * This module is a **handler factory decoupled from cordis**: everything it needs arrives through
- * {@link RootsApiDeps}, so it can be unit-tested with fake dependencies and fake request/response objects.
- * The Lead performs the actual registration:
- *
- * ```ts
- * const api = createRootsApi({ ... })
- * disposers.push(webServer.register({ kind: 'exact', path: ROOTS_API_PATH, handler: api.handle }))
- * ```
- *
- * Contract:
- *
- * | Request | Answer |
- * |---|---|
- * | `GET` | `200 { ok: true, roots, connections, userRoots, warnings }` |
- * | `POST` `{ action: 'add-root' \| 'remove-root' \| 'add-connection' \| 'update-connection' \| 'remove-connection', ... }` | `200 { ok: true, action, state }` |
- * | `POST` `{ action: 'add-root', location, path, connectionId?, workspaces?, sessions?, reuseExisting? }` | `200 { ok: true, action, state, anchorPath? }` — `reuseExisting: true` makes an already-persisted root idempotent and answers its anchor instead of `400 该根已存在` |
- * | `POST` `{ action: 'remove-root', key, workspace? }` | `200 { ok: true, action, state }` — `workspace` removes the root from that workspace only; the root disappears when the last one drops it |
- * | `POST` `{ action: 'update-connection', id, newId?, host?, user?, port?, authKind?, keyPath?, credentialKey?, transport?, password? }` | `200 { ok: true, action, state }` — absent fields keep their value; `newId` renames and migrates the connection's roots (keeping their anchors) |
- * | `POST` `{ action: 'list-remote', connectionId, path }` | `200 { ok: true, action, connectionId, path, entries: [{ name, kind }], truncated }` |
- * | `POST` `{ action: 'list-local', path? }` | `200 { ok: true, action, path, entries: [{ name, kind }], crumbs, truncated }` |
- * | `POST` `{ action: 'list-ssh-config' }` | `200 { ok: true, action, candidates: [{ alias, host, user?, port?, hasIdentityFile, hasProxyJump, suggestedId }], skipped: [{ pattern, reason, line }] }` (FR-2.1.4) |
- * | `POST` `{ action: 'import-ssh-config', aliases: [alias, …] }` | `200 { ok: true, action, imported: [id, …], refused: [{ alias, reason }], state }` — the body names **aliases**, never ids/hosts/paths: every field is re-derived from the config |
- * | any validation / trust / body failure | `400`/`403` `{ ok: false, error, reason? }` |
- * | any other method | `405` `{ ok: false, error }` + `Allow: GET, HEAD, POST` |
- *
- * Two invariants this layer owns:
- *
- *  1. **Credentials never come back out.** `connections` (live and persisted), the `state` echoed by
- *     `POST` and every directory row (`list-remote` and `list-local`) are whitelist projections:
- *     `{ id, host, user, port, authKind, transport? }` and `{ name, kind }` respectively. `keyPath`, `password`,
- *     `passphrase`, `credentialKey`, `alias`, `proxyJump`, sizes, times, modes and symlink targets are
- *     never serialised, and no file content is readable through this route at all.
- *  2. **Parameters are taken from a whitelist, one field at a time** — the body is never spread into a
- *     call. A field the UI does not own cannot reach the seam, however the body is shaped.
- *
- * @module dsh-over-ssh/integration/roots-api
- */
-import { type UserConnectionRecord, type UserRootEntry, type UserRootsState } from './user-roots.ts';
-/** The one path this plugin claims on the host HTTP carrier. */
-export declare const ROOTS_API_PATH = "/api/over-ssh/roots";
-/** Largest accepted request body. A root/connection edit is a few hundred bytes; 64 KiB is a ceiling, not a budget. */
-export declare const ROOTS_API_MAX_BODY_BYTES: number;
-/** Entries one `list-remote` answer carries at most; the tail is dropped and `truncated` says so. */
-export declare const REMOTE_LIST_MAX_ENTRIES = 2000;
-/** Entries one `list-local` answer carries at most (the same budget as `list-remote`). */
-export declare const LOCAL_LIST_MAX_ENTRIES = 2000;
-/**
- * One remote directory row as the wire may carry it.
- *
- * **Names and kinds only.** A browsing client needs to render a list and decide what is enterable, and
- * nothing else: no sizes, no times, no symlink targets, no file contents, no credentials. The projection
- * below is what enforces that, field by field, exactly like `publicConnection` does for connections.
- */
-export interface RemoteDirectoryEntry {
-    /** Base name of the entry. */
-    readonly name: string;
-    /** What the row is; anything the listing cannot classify is reported as `file`. */
-    readonly kind: 'directory' | 'file' | 'symlink';
-}
-/** Where one `list-remote` request points. */
-export interface RemoteListRequest {
-    /** Connection the directory lives behind. */
-    readonly connectionId: string;
-    /** Absolute POSIX path on that host. */
-    readonly path: string;
-}
-/**
- * One **local** directory row as the wire may carry it.
- *
- * The same discipline as {@link RemoteDirectoryEntry} with a narrower vocabulary: a local `readdir` can
- * report sizes, modes, owners and times without a second syscall, and it can only tell a link from a
- * directory by following it — which this route never does. So anything that is neither a plain file nor a
- * plain directory is answered as `other`, and no field but the name and the kind ever leaves the host.
- */
-export interface LocalDirectoryEntry {
-    /** Base name of the entry. */
-    readonly name: string;
-    /** What the row is: a plain file, a plain directory, or something else (a symlink, a socket, a device). */
-    readonly kind: 'file' | 'directory' | 'other';
-}
-/** Where one `list-local` request points. */
-export interface LocalListRequest {
-    /** Absolute, `..`-free path on **this** machine, already defaulted and canonicalised by the handler. */
-    readonly path: string;
-}
-/** One action `POST` accepts; anything else is refused with the list. */
-export declare const ROOTS_API_ACTIONS: readonly ["add-root", "remove-root", "add-connection", "update-connection", "test-connection", "remove-connection", "list-remote", "list-local", "list-ssh-config", "import-ssh-config", "mkdir-remote", "rename-remote", "remove-remote", "list-transfers", "clear-transfers"];
-/** One accepted action. */
-export type RootsApiAction = (typeof ROOTS_API_ACTIONS)[number];
-/**
- * The request surface this handler consumes: a structural subset of `node:http`'s `IncomingMessage`, so a
- * test can pass a `Readable` with `method`/`url`/`headers` and no cast, while a real `IncomingMessage`
- * still satisfies it (asserted at compile time in `tests/roots-api.test.ts`).
- */
-export interface RootsApiRequest {
-    readonly method?: string | undefined;
-    readonly url?: string | undefined;
-    readonly headers: Readonly<Record<string, string | readonly string[] | undefined>>;
-    [Symbol.asyncIterator](): AsyncIterator<unknown>;
-}
-/** The response surface this handler consumes: a structural subset of `ServerResponse`. */
-export interface RootsApiResponse {
-    statusCode: number;
-    setHeader(name: string, value: string): void;
-    end(chunk?: string): void;
-    /**
-     * The response's lifecycle, when the endpoint has one.
-     *
-     * A long-poll handler watches it to notice that the client disconnected before the answer was written; a test
-     * double without this member simply cannot be observed as closed, which is what the immediate-answer cases need.
-     */
-    readonly on?: ((event: 'close', listener: () => void) => unknown) | undefined;
-    /** Counterpart of {@link RootsApiResponse.on}. */
-    readonly off?: ((event: 'close', listener: () => void) => unknown) | undefined;
-    /** Set once the answer has been written. */
-    readonly writableEnded?: boolean | undefined;
-}
-/** The seams the handler needs. All of them are the Lead's wiring; none of them is imported from cordis. */
-export interface RootsApiDeps {
-    /**
-     * Optional: the directory every remote root's local **anchor** is created under
-     * (`<home>/.dsh/over-ssh/roots` in the entry's wiring).
-     *
-     * Published in the `GET` snapshot as `anchorRoot` for one reason: a client cannot tell a remote workspace
-     * from a local one otherwise. A remote workspace's cwd *is* the anchor path, and the per-root anchor paths
-     * this route deliberately never publishes (`publicRoot`) would be a per-row answer to a per-plugin
-     * question. Absent means the snapshot says nothing about anchors and a client falls back to "unknown",
-     * never to a guess.
-     */
-    readonly anchorRootDir?: string | undefined;
-    /** Live roots (the registry snapshot), as roots — credentials are stripped here anyway. */
-    listRoots(): Promise<readonly unknown[]> | readonly unknown[];
-    /** Live connections (profiles), which **do** carry credentials; only the whitelist is answered. */
-    listConnections(): Promise<readonly unknown[]> | readonly unknown[];
-    /** The persisted panel-owned state plus its warnings (see `createUserRootsStore().load`). */
-    loadUserState(): Promise<{
-        readonly state: UserRootsState;
-        readonly warnings: readonly string[];
-        readonly degraded?: boolean;
-    }> | {
-        readonly state: UserRootsState;
-        readonly warnings: readonly string[];
-        readonly degraded?: boolean;
-    };
-    /** Persist a whole state; returns what was written (normalised). */
-    saveUserState(next: UserRootsState): Promise<UserRootsState> | UserRootsState;
-    /** Make a root live **and** remember it. The handler reconciles the file afterwards, so persisting here is expected but not required (a second write is skipped when the content already matches). */
-    registerRoot(entry: UserRootEntry): Promise<unknown> | unknown;
-    /** Drop a root from the live side (and, if the wiring persists there, from the file). */
-    unregisterRoot(key: string): Promise<unknown> | unknown;
-    /** Remember a connection. Applying it to a live profile is a reload concern, not this handler's. */
-    addConnection(entry: UserConnectionRecord): Promise<unknown> | unknown;
-    /**
-     * Optional: apply a patched connection to the **live** profile map (and, if the wiring chooses, forget what
-     * was cached for it: the agent installation state and the probed remote home are properties of the account,
-     * so a changed host must not keep the previous host's answers).
-     *
-     * The handler already made the rename coherent for the *roots* (see {@link updateConnectionInState}); this
-     * seam is what makes it coherent for the live transports. Absent means the change is persisted only, and
-     * takes effect after a restart — which is why the wiring provides it.
-     */
-    applyConnection?: ((entry: UserConnectionRecord, previousId: string) => Promise<unknown> | unknown) | undefined;
-    /**
-     * Optional: forget a connection on the **live** side after it was removed.
-     *
-     * The mirror image of {@link RootsApiDeps.applyConnection}, and it exists for a reason that is easy to miss:
-     * the `GET` answer lists connections from the **live** profile map, not from the file. Dropping the record
-     * from `user-roots.json` alone therefore leaves the connection on screen — the panel would show a row that
-     * no longer exists in any file and whose 「删除」 button reports success forever. Everything the plugin caches
-     * **per connection** belongs to this call too: the live transport (a real SSH master or agent child process),
-     * the remote index, the installed-agent bookkeeping, the stored askpass secret and its temp directory, the
-     * probed remote home. A connection the user deleted must stop costing memory and processes.
-     *
-     * Absent means the removal is persisted only and the connection stays visible until a restart, which is why
-     * the wiring provides it.
-     */
-    removeConnection?: ((id: string) => Promise<unknown> | unknown) | undefined;
-    /**
-     * Optional: hands back the credential store for **this** request; it writes and drops, never reads.
-     *
-     * A getter rather than a value on purpose: a service read while the entry activates can still be absent —
-     * `ctx.get('webServer')` behaved exactly that way on the packaged runtime — and capturing `undefined` once
-     * would disable password connections for the whole process. A composition that never provides one refuses
-     * `authKind: 'password'` with an explicit message instead of storing a password in a file the user was told
-     * holds no secrets.
-     */
-    credentials?: (() => CredentialsSeam | undefined) | undefined;
-    /**
-     * Optional: really connect to one saved connection and run one command, for the panel's 「测试」 button.
-     *
-     * Optional for the same reason as every other capability here: a composition without a transport service
-     * answers the action with an explicit failure instead of pretending the connection is fine. The result is
-     * projected field by field, so a wiring that returns extra facts cannot leak them.
-     */
-    testConnection?: ((id: string) => Promise<unknown> | unknown) | undefined;
-    /**
-     * Optional: list one directory on a connection, for the browsing action (`list-remote`).
-     *
-     * The wiring implements it with the transport's own directory primitive; a composition that does not
-     * provide it answers `list-remote` with an explicit failure instead of failing to activate. Whatever it
-     * returns is projected to `{ name, kind }` before it reaches the wire.
-     */
-    listRemoteDirectory?: ((input: RemoteListRequest) => Promise<readonly unknown[]> | readonly unknown[]) | undefined;
-    /**
-     * Optional: the directory a remote browse starts at when the client names none.
-     *
-     * A getter rather than a value for the same reason as {@link credentials}: resolving it may need a live
-     * transport, which can appear after this entry activates. When absent, an empty `path` degrades to `/`.
-     */
-    remoteHomeDirectory?: ((connectionId: string) => Promise<string> | string) | undefined;
-    /**
-     * Optional: list one directory **on this machine**, for the browsing action (`list-local`).
-     *
-     * Same contract as {@link RootsApiDeps.listRemoteDirectory} — rows in, `{ name, kind }` out — and injected
-     * for the same two reasons: the domain layer imports no `@deepseek-ai/*` (and no `node:fs`), and a test can
-     * assert what the seam was asked for without touching the disk. The wiring implements it with `node:fs`,
-     * so a machine whose platform directory picker has no `browse` capability still has a working browser.
-     *
-     * Whatever it throws must carry the filesystem's own `errno` code (`ENOENT`, `ENOTDIR`, `EACCES`, …): that
-     * is how the handler turns "there is no such directory" into a machine-readable `400 reason` instead of an
-     * empty listing. A row without a usable name is dropped before it reaches the wire.
-     */
-    listLocalDirectory?: ((input: LocalListRequest) => Promise<readonly unknown[]> | readonly unknown[]) | undefined;
-    /**
-     * Optional: read the user's own `~/.ssh/config` for the import action (FR-2.1.4).
-     *
-     * Injected for the same two reasons as the directory seams: the domain layer reads no files, and a test can
-     * answer with a fixture instead of depending on the developer's home directory. It returns the **text**, not
-     * parsed entries, so the parsing (`domain/ssh-config.ts`) stays a pure function under test.
-     *
-     * Absent means the action answers an explicit "this composition cannot read the file" failure rather than
-     * silently importing nothing.
-     */
-    readSshConfig?: (() => Promise<string | undefined> | string | undefined) | undefined;
-    /**
-     * Optional: the remote-file operations the file tree needs (FR-2.2.2).
-     *
-     * One seam rather than three, because all three are the same capability from this route's point of view
-     * ("change the remote filesystem") and a composition either has it or does not. `rename` must refuse to
-     * clobber and `remove` must refuse a directory without `recursive` — the contract is in `app/backend.ts`.
-     */
-    remoteFiles?: RemoteFileOperations | undefined;
-    /**
-     * Optional: the in-flight and recent transfers (FR-2.6.4).
-     *
-     * A **pull** seam, not a push one: the client half has exactly one HTTP route, so "what is happening" is a
-     * question it asks, not a stream it subscribes to. Absent means the two transfer actions answer an explicit
-     * refusal instead of an empty list — "nothing is running" and "this composition cannot tell you" are
-     * different answers, and only one of them is honest.
-     */
-    transfers?: TransferReport | undefined;
-}
-/** What the route needs from the tracker, without importing it (the handler stays decoupled). */
-export interface TransferReport {
-    list(): readonly unknown[];
-    clearFinished(): number;
-}
-/** The three mutating remote-file operations (FR-2.2.2). */
-export interface RemoteFileOperations {
-    mkdir(input: {
-        readonly connectionId: string;
-        readonly path: string;
-        readonly recursive: boolean;
-    }): Promise<void> | void;
-    rename(input: {
-        readonly connectionId: string;
-        readonly from: string;
-        readonly to: string;
-        readonly createParents: boolean;
-    }): Promise<void> | void;
-    remove(input: {
-        readonly connectionId: string;
-        readonly path: string;
-        readonly recursive: boolean;
-    }): Promise<void> | void;
-}
-/**
- * The credential store as this route needs it: **write, drop, and nothing else**.
- *
- * There is deliberately no read here. The route must not be able to answer with a stored secret, so the only
- * operations it can ask for are the two that leave the value in the store.
- */
-export interface CredentialsSeam {
-    /** Store one value under a reference name (the platform rejects an empty one). */
-    set(ref: string, value: string): Promise<void> | void;
-    /** Drop one stored value; a no-op when the name is not present. */
-    unset(ref: string): Promise<void> | void;
-}
-/** The handler pair the Lead registers. */
-export interface RootsApi {
-    /**
-     * Serve one request. Never throws: a handler that rejects would leave the socket without a status.
-     *
-     * Bound as an arrow property so `handler: api.handle` can be passed directly.
-     */
-    readonly handle: (req: RootsApiRequest, res: RootsApiResponse) => Promise<void>;
-    /** No resources are held; the route registration belongs to the caller. */
-    dispose(): void;
-}
-/** Reasons a request is refused before any action runs. */
-export type TrustVerdict = 'ok' | 'no-host' | 'bad-host' | 'cross-site' | 'bad-origin';
-/** Fields a root action may carry. Everything else in the body is ignored. */
-/**
- * Fields a root action may carry.
- *
- * `sessions` joined the list with ADR-0013: 「添加目录」 writes the conversation that added the directory,
- * and that is the identity the route gate decides by when both sides have one.
- */
-export declare const ROOT_FIELDS: readonly ["location", "path", "connectionId", "label", "writable", "workspaces", "sessions"];
-/**
- * Fields a connection action may carry.
- *
- * `password` is deliberately **not** here: it is not part of a connection record. `add-connection` takes it out
- * of the body separately, writes it to the credential store, and persists only the reference name.
- * `passphrase` is not here either — nothing in this feature has a representation for it.
- *
- * `transport` **is** here, and it has to be: the panel's form sends the user's explicit choice, and this
- * whitelist is what decides which fields survive to `normalizeConnectionEntry`. Leaving it out would drop the
- * field silently — the connection would be persisted with no transport and every reader would fall back to
- * the default, which is exactly the "no escape hatch from the agent" bug this field exists to fix.
- */
-export declare const CONNECTION_FIELDS: readonly ["id", "host", "user", "port", "authKind", "keyPath", "credentialKey", "transport"];
-/**
- * Fields `update-connection` may patch.
- *
- * `id` is deliberately **not** here. In `add-connection` it names the connection being created; in an edit it
- * is the *lookup* key ("which connection am I changing"), so reusing it for the new name would make the two
- * meanings collide and a rename impossible to express. The new id therefore travels in its own field,
- * **`newId`** (optional; absent means "keep the id").
- */
-export declare const UPDATE_CONNECTION_FIELDS: readonly ["host", "user", "port", "authKind", "keyPath", "credentialKey", "transport"];
-/**
- * Decide whether a request is same-origin enough to serve.
- *
- * The rule, and why it is not stricter:
- *
- *  - **A missing `Origin` is allowed.** Non-browser clients do not send it: `curl`, a Node-side `fetch`, and
- *    the DSH desktop shell's own calls. Browsers always send `Origin` on a `POST` (including a cross-site
- *    `no-cors` form post), which is the case this fence exists for, so "absent" cannot be produced by a
- *    cross-site page.
- *  - **`Origin: null` is refused** (sandboxed iframe, `file:` document).
- *  - **`Origin` must match `Host`.** A different port or hostname is a different origin.
- *  - **A port-less loopback spelling is accepted** when the `Origin` carried no port at all: some Chromium
- *    builds serialise a loopback page as `http://127.0.0.1` even when the page is on a non-default port
- *    (observed in this workspace by the `dsh-remote-ssh` plugin, which fences the same way). A *different*
- *    explicit port still fails, because that path compares full `host`.
- *  - **`Sec-Fetch-Site: cross-site` is refused** even if the two headers were somehow consistent.
- *
- * The host allowlist itself (loopback / trusted hosts) is **not** re-implemented here: the carrier already
- * decides what it serves. See the audit's unverified list.
- *
- * @param req - incoming request.
- * @returns `'ok'`, or the reason to refuse.
- */
-export declare function trustVerdict(req: RootsApiRequest): TrustVerdict;
-/** User-facing text for one {@link TrustVerdict}. */
-export declare function trustMessage(verdict: TrustVerdict): string;
-//# sourceMappingURL=roots-api-contract.d.ts.map

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

@@ -1,13 +0,0 @@
-/**
- * roots-api-directories
- *
- * 目录与文件操作的 5 个 action：mkdir/rename/remove、远端列举、本机列举。
- *
- * 从 `roots-api.ts` 的 `serveAction`（543 行 / 15 个 case）拆出（审计 0076）：
- * case 体逐字搬移，只把 `return;` 改成 `return true;`，未命中时返回 `false` 由分发器报 400。
- *
- * @module dsh-over-ssh/app/roots-api-directories
- */
-import type { RootsApiRequest, RootsApiResponse, RootsApiDeps } from './roots-api-contract.ts';
-export declare function handleDirectoryActions(action: string, body: Record<string, unknown>, req: RootsApiRequest, res: RootsApiResponse, deps: RootsApiDeps): Promise<boolean>;
-//# sourceMappingURL=roots-api-directories.d.ts.map

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

@@ -1,77 +0,0 @@
-/**
- * 根路由的**请求/响应原语**：读 body、发 JSON、字段校验、凭据字段拦截。
- *
- * 从 `roots-api-support.ts` 拆出（审计 0079）：这一层只认 HTTP 与 body 形状，
- * 不知道任何 DTO，也不读用户状态。
- *
- * @module dsh-over-ssh/app/roots-api-http
- */
-import { type UserRootEntry } from './user-roots.ts';
-import type { RootsApiRequest, RootsApiResponse, RootsApiDeps } from './roots-api-contract.ts';
-export declare function readBody(req: RootsApiRequest): Promise<string>;
-export declare function toBytes(chunk: unknown): Uint8Array;
-export declare function send(req: RootsApiRequest, res: RootsApiResponse, status: number, value: unknown): void;
-export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
-export declare function messageOf(error: unknown): string;
-/** The machine-readable reason a refusal carries in its details, when it has one. */
-export declare function reasonOf(error: unknown): string | undefined;
-export declare function isValidationFailure(error: unknown): boolean;
-/** One required non-empty string field of a body. */
-export declare function requiredString(value: unknown, field: string): string;
-export declare function requiredKey(value: unknown): string;
-/**
- * The optional `path` field of a `list-local` body.
- *
- * Absent and empty (or blank) both mean "the host default", which is the user's home directory. Anything else
- * that is not a string — `null` included — is the caller's fault and is refused before a directory is chosen:
- * silently browsing the home directory because a client sent `null` would look like the request succeeded.
- */
-export declare function optionalPath(value: unknown): string | undefined;
-/** Take only the named fields from a body; the body itself is never handed to a seam. */
-export declare function pick(source: Record<string, unknown>, fields: readonly string[]): Record<string, unknown>;
-/**
- * The one body field this route refuses outright, whatever the action.
- *
- * `passphrase` has no representation anywhere in this feature, so accepting it would be a lie — and silently
- * dropping it would tell the user their passphrase was stored.
- *
- * `password` is **not** refused any more: `add-connection` and `update-connection` take it, write it into the
- * credential store and keep only the reference (FR-2.1.2). `credentialKey` is a *name*, not a secret, and
- * travels normally.
- */
-export declare function firstCredentialField(body: Record<string, unknown>, action: string): string | undefined;
-/**
- * The live registry's own key for one persisted entry, or `undefined` when it is not live.
- *
- * The comparison goes through `sameUserRootKey` rather than `===`: the registry lower-cases Windows local
- * paths (`domain/root.ts`'s `rootKey`), the persisted file keeps the caller's case, and the client rebuilds
- * the key from the `path` the answer carried. Comparing them verbatim made a Windows local root impossible to
- * remove - the file entry went, the live root stayed, and the row then had no delete button because it was no
- * longer in the file.
- *
- * @param deps - the injected seams (only `listRoots` is read).
- * @param entry - the entry to look for.
- * @returns the key the registry holds it under, or `undefined`.
- */
-export declare function matchedLiveKey(deps: RootsApiDeps, entry: UserRootEntry): Promise<string | undefined>;
-/**
- * Read one live record as a root key, matching it against `entry`.
- *
- * @param raw - a `RootRecord` (key + root) or a bare `RootRef`.
- * @param entry - the entry to match.
- * @returns the record's own key when it names `entry`, else `undefined`.
- */
-export declare function liveKeyOfRecord(raw: unknown, entry: UserRootEntry): string | undefined;
-/**
- * Turn an alias into a connection id that passes {@link isValidConnectionId}.
- *
- * `~/.ssh/config` aliases routinely contain characters this plugin's ids reject (`@`, `:`, `/`, spaces) —
- * `deploy@bastion` is a perfectly normal alias. Importing one verbatim would be refused by
- * {@link normalizeConnectionEntry} with a message about id grammar, which reads as "the import is broken".
- * The alias is therefore **kept as the ssh target** (`alias`), and only the *id* is sanitised.
- *
- * @param alias - the literal alias from the config.
- * @returns a valid id, or `undefined` when sanitising leaves nothing usable.
- */
-export declare function connectionIdFromAlias(alias: string): string | undefined;
-//# sourceMappingURL=roots-api-http.d.ts.map

package/lib/types/src/host/app/roots/roots-api-long-poll.d.ts

@@ -1,130 +0,0 @@
-/**
- * Long-poll support for the transfer snapshot (`list-transfers` with `waitMs`).
- *
- * ## Why long-polling at all
- *
- * The panel used to re-ask on a 1 s / 5 s timer. A progress bar fed by a timer advances in steps of
- * `interval × rate`, which on a large upload is exactly the "进度一顿一顿" the user reported: the bytes are
- * continuous, the bar is sampled. A long poll flips the direction — the client asks once and the host answers
- * **when something changed or when the budget runs out** — so the bar advances with the transfer.
- *
- * ## Why the change is observed by sampling
- *
- * The tray of transfers (`integration/transfer/transfer-tracker.ts`) has no change notification, and that module is
- * outside this task's write scope. This module therefore compares a **fingerprint** of the projected table on a
- * short internal step ({@link TRANSFER_WAIT_STEP_MS}) and answers as soon as it differs. The cost is an in-memory
- * `JSON.stringify` of at most a handful of rows per step and no I/O, no lock and no extra HTTP round trip; the
- * trade-off is up to one step of latency. When the tracker grows a notification hook, only {@link awaitChange}'s
- * `read` seam needs to change — the route does not.
- *
- * ## The concurrency rule the parked request must obey
- *
- * A parked request holds nothing the rest of the plugin needs. The platform's HTTP carrier
- * (`dsh-host-webserver`) keeps a route table and one handler per request; it has **no per-route in-flight quota** for
- * a handler to occupy, so a waiting request cannot make another tool call queue. What could accumulate is sockets,
- * so {@link MAX_TRANSFER_WAITERS} caps simultaneous waits and every request beyond the cap is answered
- * **immediately** (with `degraded: true` on the wire) instead of queuing.
- *
- * @module dsh-over-ssh/app/roots-api-long-poll
- */
-/** Longest a parked snapshot request may wait (the client asks for this). */
-export declare const TRANSFER_WAIT_MAX_MS = 25000;
-/** How often the waiter re-reads the in-memory table while parked. */
-export declare const TRANSFER_WAIT_STEP_MS = 100;
-/** How many parked snapshot requests may exist at once across the process. */
-export declare const MAX_TRANSFER_WAITERS = 16;
-/** @returns how many snapshot requests are parked right now (diagnostics and tests). */
-export declare function transferWaiterCount(): number;
-/**
- * Reserve one waiter slot.
- *
- * @returns true when the caller may park; false means "answer immediately" — the degraded path exists so a leaked
- *   or misbehaving client can never grow the number of parked handles without bound.
- */
-export declare function tryAcquireTransferWaiter(): boolean;
-/** Release one waiter slot. Safe to call once per successful acquire. */
-export declare function releaseTransferWaiter(): void;
-/**
- * Reset the waiter count.
- *
- * Exported for tests only: the counter is process-wide (the route is one handler), and a test that left a slot held
- * would make the next test's "degraded" assertion depend on ordering.
- */
-export declare function resetTransferWaitersForTests(): void;
-/**
- * Read the requested `waitMs` off a request body.
- *
- * Anything that is not a finite number becomes `0` (answer now): the client is the only caller, and a malformed
- * value must degrade to the old behaviour instead of parking a request for an unbounded time.
- *
- * @param value - the raw `waitMs` field.
- * @returns the clamped budget in milliseconds.
- */
-export declare function readWaitMs(value: unknown): number;
-/** The two event sources a `node:http` request/response pair exposes for "the client went away". */
-export interface ClosableEndpoint {
-    readonly on?: ((event: 'close', listener: () => void) => unknown) | undefined;
-    /** The counterpart of {@link ClosableEndpoint.on}; present on every real emitter and on `Readable` doubles. */
-    readonly off?: ((event: 'close', listener: () => void) => unknown) | undefined;
-    readonly writableEnded?: boolean | undefined;
-    readonly destroyed?: boolean | undefined;
-}
-/** One close watcher over a request/response pair. */
-export interface CloseWatcher {
-    /** True once the client disconnected (or the response was already finished). */
-    readonly closed: boolean;
-    /** Remove the listeners; safe to call more than once. */
-    dispose(): void;
-}
-/**
- * Watch the **response** for the client going away.
- *
- * Why the response and not the request: on a real Node HTTP server the *request's* `close` fires the moment its body
- * has been read — measured on Node 24, `req.on('close')` at `end` with `req.destroyed === true`, while
- * `res.on('close')` fires only when the connection actually goes away (client abort) or after `res.end`. Watching
- * the request would therefore mark every long poll closed immediately and answer nothing. The response is the only
- * endpoint whose `close` means "the peer is gone".
- *
- * A parked answer must stop waiting when the page aborts its fetch — otherwise the handler keeps a timer alive for up
- * to 25 s after the panel is gone (and lengthens plugin unload).
- *
- * @param response - the outgoing response.
- * @returns the watcher.
- */
-export declare function watchClose(response: ClosableEndpoint): CloseWatcher;
-/** What one wait produced. */
-export interface ChangeWaitOutcome {
-    /** Whether the fingerprint differed before the budget ran out. */
-    readonly changed: boolean;
-    /** How long the request actually waited. */
-    readonly waitedMs: number;
-    /** True when the client disconnected while waiting: the caller must not send anything. */
-    readonly aborted: boolean;
-}
-/** The seams {@link awaitChange} runs on; the route passes none of them and tests pass fakes. */
-export interface ChangeWaitOptions {
-    /** The fingerprint taken when the request arrived. */
-    readonly before: string;
-    /** Read the current fingerprint (cheap: an in-memory projection). */
-    readonly read: () => string;
-    /** Total budget. */
-    readonly waitMs: number;
-    /** Step between reads; defaults to {@link TRANSFER_WAIT_STEP_MS}. */
-    readonly stepMs?: number;
-    /** Stop early when the client disconnected. */
-    readonly isClosed?: () => boolean;
-    /** Injected timer; defaults to `setTimeout`. */
-    readonly sleep?: (ms: number) => Promise<void>;
-    /** Injected clock; defaults to `Date.now`. */
-    readonly now?: () => number;
-}
-/**
- * Wait until the fingerprint changes, the budget runs out, or the client disconnects.
- *
- * A timeout is **not** an error: it is the normal "nothing happened" answer, and the client immediately asks again.
- *
- * @param options - the fingerprint seam, the budget and the lifecycle hooks.
- * @returns whether anything changed, how long it waited, and whether the client left.
- */
-export declare function awaitChange(options: ChangeWaitOptions): Promise<ChangeWaitOutcome>;
-//# sourceMappingURL=roots-api-long-poll.d.ts.map