dsh-over-ssh 0.1.0 → 0.2.0

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

@@ -1,407 +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?, 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-remote-workspace/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/remote-workspace/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 seams the handler needs. All of them are the Lead's wiring; none of them is imported from cordis. */
-export interface RootsApiDeps {
-    /** 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 state: UserRootsState;
-        readonly warnings: readonly string[];
-    };
-    /** 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';
-/**
- * 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;
-/**
- * Build the handler pair.
- *
- * @param deps - the injected seams (live registry, persisted store, connection writer).
- * @returns `handle` plus a no-op `dispose`.
- */
-export declare function createRootsApi(deps: RootsApiDeps): RootsApi;
-/** One root as the panel may see it: no credential can appear in a root, but the shape is still fixed. */
-export interface PublicRoot {
-    readonly key?: string;
-    readonly location: string;
-    readonly connectionId?: string;
-    readonly path: string;
-    readonly label?: string;
-    readonly writable?: boolean;
-}
-/**
- * One connection as the panel may see it. **Deliberately without `keyPath`.**
- *
- * `transport` **is** projected, and it has to be: the edit form is filled from this answer and submits what it
- * was filled with, so omitting the field silently rewrote every `alias`/`ssh2` connection to the default
- * (`agent`) on the next save - even when the operator only changed the host.
- */
-export interface PublicConnection {
-    readonly id: string;
-    readonly host: string;
-    readonly user: string;
-    readonly port?: number;
-    readonly authKind: string;
-    /** The transport this connection asks for; absent only for a record that names none. */
-    readonly transport?: string;
-}
-/**
- * The absolute chain from the filesystem root down to `absolute`, inclusive.
- *
- * The client renders "up" and "home" from this instead of composing a parent path itself: drive letters, UNC
- * shares and `/` are exactly the dialects a web client gets wrong, and one wrong guess sends `list-local` to a
- * directory the user never asked for. Every element is an ancestor of the path the answer already carries, so
- * the field discloses nothing the `path` field did not.
- *
- * @param absolute - an absolute, resolved path (what the handler answers with).
- * @returns the chain, root first; empty when the platform reports no root (impossible for a resolved path).
- */
-export declare function localPathCrumbs(absolute: string): readonly string[];
-/**
- * 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;
-}
-/**
- * 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.d.ts.map

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

@@ -1,211 +0,0 @@
-/**
- * Wire the panel's HTTP route to the live roots, the live connections and the persisted panel state.
- *
- * This module is the seam the API handler and the registry never see each other through: the handler is pure
- * request/response (see {@link createRootsApi}), the registry owns live routing, and this file is the only
- * place that knows both. It exists as its own module so the wiring is one small, reviewable call in the entry
- * rather than twenty lines inside it.
- *
- * Two behaviours worth stating:
- *
- *  - **Startup merge**: roots and connections the panel wrote survive a restart because they are read back
- *    from `user-roots.json` and applied to the live side at load. A file that cannot be applied is reported as
- *    a warning, never as a load failure: losing the panel's extra roots must not stop the plugin.
- *  - **Same-origin only**: the route is registered on the browser carrier (`ctx.webServer`). When that service
- *    is absent (a headless profile), the plugin still works and simply has no panel data channel — the reason
- *    is logged instead of thrown.
- *
- * @module dsh-remote-workspace/host/integration/roots-wiring
- */
-import { type CredentialsSeam, type RemoteFileOperations, type TransferReport, type RootsApi } from '../app/roots-api.ts';
-import { type UserConnectionRecord, type UserRootEntry, type UserRootsIo, type UserRootsStore } from '../app/user-roots.ts';
-/** The browser HTTP carrier the host exposes; only the one method this wiring needs. */
-export interface RootsRouteHost {
-    register(route: {
-        readonly kind: 'exact';
-        readonly path: string;
-        readonly handler: (req: never, res: never) => Promise<void>;
-    }): () => void;
-}
-/**
- * Deferred carrier: run `callback` once `webServer` is **available**, and again whenever it comes back.
- *
- * `ctx.inject` is the platform's documented way to depend on a service that a later composition layer
- * provides (`dsh-client-connection` does exactly this for the `/api` route). A bare `ctx.get('webServer')`
- * at activation time is **not** equivalent: measured on the packaged 0.2.0-rc.2 runtime
- * (`dsh --profile web`, `ctx.get('webServer') === undefined`, `'webServer' in ctx === false`) while
- * `ctx.get('tools')` was already an object — the carrier row is constructed after the plugin entries
- * activate. With `ctx.get` the route was never registered, the shell's `dsh-app://app/api/…` proxy fell
- * through to the SPA fallback, and the panel reported `http-404` while the plugin looked healthy.
- *
- * `scoped.get` is typed `unknown` and narrowed by {@link asRootsRouteHost} rather than declared as the
- * carrier type: this module stays clear of `@deepseek-ai/*` types (红线 2), and a cordis `Context` is
- * structurally richer than this one-method seam, so the narrower declaration would reject the real `ctx`.
- */
-export interface RootsRouteHostProvider {
-    inject(names: readonly string[], callback: (scoped: {
-        get(name: string): unknown;
-    }) => void | (() => void)): unknown;
-}
-/** Why a route could not be registered; both variants are warnings, never activation failures. */
-export type RootsRouteWarning = 
-/** No `webServer` service ever appeared (a headless composition): the panel has no data channel. */
-{
-    readonly kind: 'no-carrier';
-}
-/** The carrier refused the registration, e.g. a duplicate `(kind, path)` pair. */
- | {
-    readonly kind: 'refused';
-    readonly reason: string;
-};
-/** Everything the wiring needs from the entry. */
-export interface RootsWiringDeps {
-    /** Plugin state directory; `user-roots.json` lives inside it. */
-    readonly stateDir: string;
-    /** Live roots (the registry's records). */
-    readonly listRoots: () => readonly unknown[];
-    /** Live connections (the entry's profiles). */
-    readonly listConnections: () => readonly unknown[];
-    /** Make a root live and routable. */
-    /**
-     * Make a root live. **Awaitable**: registering a remote root also creates its local anchor directory, and the
-     * panel hands that path straight to the platform's `createWorkspace`, which resolves it with `realpath`.
-     */
-    readonly registerRoot: (entry: UserRootEntry) => Promise<void> | void;
-    /** Drop a root from the live side. */
-    readonly unregisterRoot: (key: string) => void;
-    /** Make a connection usable without a restart. */
-    readonly applyConnection: (entry: UserConnectionRecord, previousId: string) => void;
-    /**
-     * Forget a deleted connection on the live side: its profile, and everything cached per connection.
-     *
-     * Required, not optional: the `GET` answer lists connections from the live side, so a wiring that omitted this
-     * would keep answering with a connection the user deleted (see `RootsApiDeps.removeConnection`). Making it
-     * required means the compiler — not a reviewer — notices a wiring that forgot it.
-     */
-    readonly removeConnection: (id: string) => void;
-    /**
-     * Optional: list one directory on a connection (names and kinds only), for the `list-remote` action.
-     *
-     * Passed through to the handler untouched: this wiring knows nothing about transports, and a composition
-     * without it simply answers that action with an explicit failure.
-     */
-    readonly listRemoteDirectory?: ((input: {
-        readonly connectionId: string;
-        readonly path: string;
-    }) => Promise<readonly unknown[]> | readonly unknown[]) | undefined;
-    /**
-     * Optional: the directory a remote browse starts at when the client names no path.
-     *
-     * The same pass-through as {@link RootsWiringDeps.listRemoteDirectory}, and the same reason to have it: the
-     * start directory is the remote login user's home, which only the transport can answer (an account may live
-     * under `/home`, `/home1`, …). A composition without it degrades to `/`, the pre-existing behaviour.
-     */
-    readonly remoteHomeDirectory?: ((connectionId: string) => Promise<string> | string) | undefined;
-    /**
-     * Optional: list one directory **on this machine** (names and kinds only), for the `list-local` action.
-     *
-     * The same pass-through as {@link RootsWiringDeps.listRemoteDirectory}, and the same reason to have it: a
-     * profile whose platform directory picker offers only the native dialog (no `browse` capability) still gets
-     * a working browser from the host, which always has `node:fs`. A composition that does not provide it
-     * answers that action with an explicit failure rather than pretending the directory is empty.
-     */
-    readonly listLocalDirectory?: ((input: {
-        readonly path: string;
-    }) => Promise<readonly unknown[]> | readonly unknown[]) | undefined;
-    /**
-     * Optional: the text of the user's own `~/.ssh/config`, for the import flow (FR-2.1.4).
-     *
-     * The same pass-through as the directory seams, and the same reason: this wiring reads no files, and the
-     * handler wants **text** so the parsing stays a pure function under test. Absent means the import actions
-     * answer an explicit failure.
-     */
-    readonly readSshConfig?: (() => Promise<string | undefined> | string | undefined) | undefined;
-    /**
-     * Optional: the mutating remote-file operations the file tree needs (FR-2.2.2).
-     *
-     * The same pass-through as the other seams: this wiring resolves nothing itself. Absent means those actions
-     * answer an explicit refusal.
-     */
-    readonly remoteFiles?: RemoteFileOperations | undefined;
-    /**
-     * Optional: the in-flight and recent transfers (FR-2.6.4).
-     *
-     * The same pass-through as the other seams. Absent means the transfer actions answer an explicit refusal.
-     */
-    readonly transfers?: TransferReport | undefined;
-    /**
-     * Optional: the credential store, read **per request** (a getter, not a value — see `RootsApiDeps`).
-     *
-     * Absent in a composition with no credentials service: password connections are then refused with an
-     * explicit 400 instead of being written into a file that is documented to hold no secrets.
-     */
-    readonly readCredentials?: (() => CredentialsSeam | undefined) | undefined;
-    /** Optional: really connect to one saved connection (the panel's 「测试」 button). */
-    readonly testConnection?: ((id: string) => Promise<unknown> | unknown) | undefined;
-    /** Optional: the deferred `ctx.webServer` carrier. Absent in a headless profile. */
-    readonly webServerProvider?: RootsRouteHostProvider | undefined;
-    /** Optional file-system binding for the store; tests inject an in-memory one (红线 3). */
-    readonly io?: UserRootsIo | undefined;
-}
-/** What the entry holds on to. */
-export interface RootsWiring {
-    readonly api: RootsApi;
-    readonly store: UserRootsStore;
-    /** Apply everything the panel persisted, so UI edits survive a restart. */
-    mergeUserRoots(): Promise<{
-        readonly roots: number;
-        readonly connections: number;
-        readonly warnings: readonly string[];
-    }>;
-    /**
-     * Human-readable warnings collected while trying to own the route: an absent carrier, or one that
-     * refused the registration. Exposed so the entry can log them **after** activation, when `ctx.logger`
-     * itself resolves (it is undefined at activation time, the same ordering fact this file works around).
-     */
-    readonly routeWarnings: () => readonly string[];
-    /**
-     * The route's own facts, for the entry's one-line diagnostic.
-     *
-     * `injectRan` and `routeRegistered` are the two facts nothing else can answer: the first says whether the
-     * deferred carrier callback ever executed (a callback that never ran means `webServer` never appeared),
-     * the second whether the carrier actually accepted the route. Both are read **after** activation, on the
-     * next tick, because at activation time neither can be true yet on the packaged runtime.
-     */
-    readonly routeFacts: () => RootsRouteFacts;
-    readonly dispose: () => void;
-}
-/** What the wiring knows about its own route attempt; the rest of the diagnostic comes from the entry. */
-export interface RootsRouteFacts {
-    /** True once the deferred carrier callback ran at least once. */
-    readonly injectRan: boolean;
-    /** True when the route is currently registered on a carrier. */
-    readonly routeRegistered: boolean;
-    /** The warnings collected so far, in order. */
-    readonly warnings: readonly string[];
-}
-/**
- * The one-line diagnostic the entry logs when the route is still missing after the next tick.
- *
- * **Why this exists**: the panel's failure mode is `http-404`, and a 404 alone cannot tell "the carrier
- * refused the route" from "the carrier never appeared" from "the plugin never asked". Each of those has a
- * different fix, so the line carries the four facts that separate them  - whether the `ctx.inject`
- * callback ran, whether `'webServer' in ctx` is true on the entry's own context, what `ctx.get('tools')`
- * resolved to (a non-undefined service proves the context itself is live), and the warnings registered so
- * far - with the warnings inline, so a single log line is enough to act on.
- *
- * @param facts - the wiring's own facts plus the two the entry samples from its context.
- * @returns one structured line, safe for any logger.
- */
-export declare function rootsRouteDiagnostic(facts: RootsRouteFacts & {
-    readonly hasWebServerProperty: boolean;
-    readonly toolsType: string;
-}): string;
-/**
- * Build the wiring and register the route when a carrier exists.
- *
- * @param deps - live roots, live connections and the persist location.
- * @returns the wiring; call {@link RootsWiring.dispose} on unload to release the route.
- */
-export declare function createRootsWiring(deps: RootsWiringDeps): RootsWiring;
-//# sourceMappingURL=roots-wiring.d.ts.map