dsh-over-ssh 0.1.0 → 0.2.0

package/lib/types/src/host/infra/transport/ssh2-transport.d.ts

@@ -1,302 +0,0 @@
-/**
- * The `ssh2` transport: a pure-JS SSH client.
- *
- * Why a second implementation:
- *
- *  - **Password authentication** cannot be done by a non-interactive system `ssh` (it hardcodes
- *    `BatchMode`-style behaviour and would block on a prompt).
- *  - **Dynamic ProxyJump** chains (per-connection host/port/credentials) cannot be expressed
- *    through the system client's argv without writing a temporary ssh config.
- *  - **Connection reuse on Windows**: the host platform's OpenSSH does not support ControlMaster
- *    (measured: `getsockname failed: Not a socket`), so the only way to reuse one connection for
- *    many commands there is a client we own. See `doc/03-decisions/0006-windows-host-no-controlmaster.md`.
- *
- * Everything the plugin needs from the remote host is expressed with the *same* helpers as the
- * alias transport — the same probe script, the same shell quoting, the same `size:mtimeSeconds`
- * version token, the same failure classification — so behaviour does not change when a connection
- * switches transports. File bytes travel over the SFTP subsystem (part of OpenSSH, still zero
- * install) instead of base64 over the exec channel.
- *
- * The client itself is injected (`Ssh2Connector`), so this module never imports the `ssh2`
- * package: unit tests run without it and without a network.
- *
- * @module dsh-remote-workspace/infra/transport/ssh2-transport
- */
-import { type RemoteCapabilities } from '../../domain/capability.ts';
-import type { HostKeyPolicy } from '../../domain/connection.ts';
-import { SshDevError } from '../../domain/errors.ts';
-import { type ExecRequest, type ExecResult, type ReadFileRangeRequest, type ReadFileRequest, type RemoteFileChunk, type RemoteWriteOutcome, type RemoveRequest, type RenameRequest, type Transport, type WriteFileRangeRequest, type WriteFileRequest } from './transport.ts';
-import { TransportBase } from './transport-base.ts';
-/** Authentication material for one hop. */
-export interface Ssh2Auth {
-    readonly password?: string;
-    readonly privateKey?: string | Uint8Array;
-    readonly passphrase?: string;
-    /** ssh-agent socket path, or `pageant` on Windows. */
-    readonly agent?: string;
-}
-/** One host to connect to. */
-export interface Ssh2Target {
-    readonly host: string;
-    readonly port?: number;
-    readonly username: string;
-    readonly auth: Ssh2Auth;
-}
-/** Everything needed to open a session. */
-export interface Ssh2ConnectConfig {
-    /** Final target. */
-    readonly target: Ssh2Target;
-    /** Ordered jump hosts: hop 0 is reached directly, each next hop through the previous one. */
-    readonly jump?: readonly Ssh2Target[];
-    readonly hostKeyPolicy?: HostKeyPolicy;
-    /** Accepted host key fingerprints (`SHA256:…`), required when the policy is `strict`. */
-    readonly trustedHostKeys?: readonly string[];
-    readonly connectTimeoutMs?: number;
-    readonly keepAliveMs?: number;
-    /** Cancellation for the connect attempt. */
-    readonly signal?: AbortSignal;
-}
-/**
- * An SFTP file handle.
- *
- * Opaque on purpose: `ssh2` hands back a raw `Buffer` handle that is only meaningful to
- * `sftp.read` / `sftp.close` (verified against the real library — there is **no**
- * `handle.read` method, which is exactly the mistake this shape prevents).
- */
-export type Ssh2FileHandle = unknown;
-/** SFTP statistics as far as this transport needs them. */
-export interface Ssh2Stats {
-    /** Base name of a `readdir` entry; absent on objects returned by `stat`. */
-    readonly filename?: string;
-    readonly size: number;
-    /**
-     * Modification time in **seconds** since the epoch.
-     *
-     * SFTP v3 attributes carry seconds, and `ssh2` passes them through unchanged (verified on a
-     * real host: `mtime = 1789217901`). The alias transport's `stat -c %Y` also reports seconds, so
-     * keeping the same unit is what makes version tokens comparable across transports.
-     */
-    readonly mtime: number;
-    /**
-     * SFTP file mode bits (`stats.mode & 0o170000`).
-     *
-     * Optional because a caller may hand over a `Stats`-shaped object without it, but the real
-     * library always sets it. It is the only reliable way to detect a **symbolic link** during a
-     * recursive removal: SFTP v3 `readdir` reports the link itself and never follows it.
-     */
-    readonly mode?: number;
-    /** `readdir` long name; starts with `l` for a symbolic link (`-` file, `d` directory). */
-    readonly longname?: string;
-    isDirectory?(): boolean;
-    isFile?(): boolean;
-    isSymbolicLink?(): boolean;
-}
-/**
- * The narrow SFTP surface this transport uses, mirroring the real `ssh2` API:
- * `open` yields a handle, and reads go through `read(handle, …)`, not through the handle.
- *
- * `readdir` / `rmdir` are optional for the same reason `ext_openssh_rename` is: a fake or a
- * non-OpenSSH server may not provide them, and {@link Ssh2Transport.remove} must then report
- * `REMOTE_UNSUPPORTED` instead of pretending a tree went away.
- */
-export interface Ssh2Sftp {
-    stat(path: string, callback: (error?: Error, stats?: Ssh2Stats) => void): void;
-    open(path: string, flags: string, callback: (error?: Error, handle?: Ssh2FileHandle) => void): void;
-    /** Read into a real `Buffer` (the library rejects plain `Uint8Array` views). */
-    read(handle: Ssh2FileHandle, buffer: Buffer, offset: number, length: number, position: number, callback: (error?: Error, bytesRead?: number) => void): void;
-    /**
-     * Positioned write into an open handle. `position` is the **file** offset; `offset` is the
-     * offset inside `buffer` (the same parameter order as the real library).
-     */
-    write(handle: Ssh2FileHandle, buffer: Buffer, offset: number, length: number, position: number, callback: (error?: Error) => void): void;
-    close(handle: Ssh2FileHandle, callback: (error?: Error) => void): void;
-    /** Statistics for an **open handle**, used to size a positioned write before truncating. */
-    fstat?(handle: Ssh2FileHandle, callback: (error?: Error, stats?: Ssh2Stats) => void): void;
-    /** Truncate an open handle to `length` bytes. */
-    ftruncate?(handle: Ssh2FileHandle, length: number, callback: (error?: Error) => void): void;
-    writeFile(path: string, data: Uint8Array, callback: (error?: Error) => void): void;
-    mkdir(path: string, attributes: {
-        readonly mode: number;
-    }, callback: (error?: Error) => void): void;
-    /** List a directory. The v3 protocol returns `.` and `..` too, so callers must skip them. */
-    readdir?(path: string, callback: (error?: Error, entries?: readonly Ssh2Stats[]) => void): void;
-    /** Remove an **empty** directory. */
-    rmdir?(path: string, callback: (error?: Error) => void): void;
-    /**
-     * Plain SFTP rename.
-     *
-     * Measured on a real OpenSSH server: this **fails with SSH_FX_FAILURE when the destination
-     * already exists**, so it cannot be the only path for an overwriting write.
-     */
-    rename(from: string, to: string, callback: (error?: Error) => void): void;
-    /**
-     * `posix-rename@openssh.com`: atomic overwrite. Present on OpenSSH servers/clients, absent
-     * elsewhere — which is why {@link writeFile} keeps a fallback ladder.
-     */
-    ext_openssh_rename?: ((from: string, to: string, callback: (error?: Error) => void) => void) | undefined;
-    unlink(path: string, callback: (error?: Error) => void): void;
-    end(): void;
-}
-/** A command channel as far as this transport needs it. */
-export interface Ssh2Channel {
-    on(event: 'data', listener: (chunk: Buffer) => void): this;
-    on(event: 'close', listener: (code: number | null, signal: string | null) => void): this;
-    on(event: string, listener: (...args: never[]) => void): this;
-    stderr: {
-        on(event: 'data', listener: (chunk: Buffer) => void): unknown;
-    };
-    write(data: string | Uint8Array): boolean;
-    end(data?: string | Uint8Array): void;
-    close(): void;
-}
-/** An open SSH session: many channels, one connection. */
-export interface Ssh2Session {
-    exec(command: string, options: {
-        readonly pty?: boolean;
-    }, callback: (error?: Error, channel?: Ssh2Channel) => void): void;
-    sftp(callback: (error?: Error, sftp?: Ssh2Sftp) => void): void;
-    /** Open a TCP channel through this session, used to chain jump hosts. */
-    forwardOut(sourceAddress: string, sourcePort: number, destinationAddress: string, destinationPort: number, callback: (error?: Error, stream?: unknown) => void): void;
-    end(): void;
-    destroy(): void;
-    /**
-     * Intermediate jump-host sessions this session rides on, so `dispose()` can close them too.
-     *
-     * **Deliberately per-session, not a module-level slot.** The first version of this fix kept them in
-     * a module-level `lastHops`, which is wrong as soon as one process has two connections
-     * (`TransportService` caches by `profile.id`, so multiple profiles are normal):
-     *  - the second `connect` cleared the array, so the first connection's hops were **leaked**;
-     *  - the first `dispose()` then took the *second* connection's hops and **ended a live connection
-     *    another transport was still using**.
-     * Hanging them on the session they belong to makes ownership structural instead of positional.
-     * `ssh2`'s real `Client` has no such property, so it is optional and set only by
-     * {@link defaultConnector}.
-     */
-    readonly hops?: readonly Ssh2Session[];
-}
-/** Opens a session; injected so tests never load the real client. */
-export type Ssh2Connector = (config: Ssh2ConnectConfig) => Promise<Ssh2Session>;
-/** Construction options. */
-export interface Ssh2TransportOptions {
-    readonly connectionId: string;
-    /** Session factory. Defaults to the real `ssh2` client (loaded lazily). */
-    readonly connector?: Ssh2Connector;
-    readonly connect?: Ssh2ConnectConfig;
-    readonly commandTimeoutMs?: number;
-    readonly now?: () => number;
-}
-/**
- * Bytes of a command's **stderr** that are retained.
- *
- * `maxBytes` bounds stdout only, and stderr used to be accumulated without any bound at all: a command
- * that writes diagnostics in a loop (`ssh -v`, a verbose build, a remote program that logs errors) grew
- * this process's heap until the channel closed. Measured before the fix: a peer emitting 64 MiB of
- * stderr retained **all 64 MiB** while stdout was correctly capped at 1 KiB (审计 0050).
- *
- * The **tail** is kept, not the head: every consumer of this string wants the last thing the command
- * said. `domain/errors.ts` reduces it with `tail(stderr, 2000)` for classification, and a failing
- * command's useful diagnostic (the final error, the `DSH_ERROR=` refusal) is at the end.
- */
-export declare const SSH2_STDERR_MAX_BYTES: number;
-/**
- * First line prepended to a truncated stderr capture.
- *
- * The truncation is announced **in the string itself** because `ExecResult.truncated` is stdout's flag
- * (see its JSDoc) and must keep that meaning: `remote-backend` treats a truncated batch read as "these
- * paths were not read", so setting it for a chatty command's stderr would report readable files as
- * missing. Announcing it here keeps the diagnostic honest without overloading the flag.
- */
-export declare const STDERR_TRUNCATION_NOTICE = "\uFF08stderr \u8FC7\u957F\uFF0C\u4EC5\u4FDD\u7559\u672B\u5C3E\u7247\u6BB5\uFF09";
-/**
- * The pure-JS transport.
- *
- * One session serves every command and every file transfer, which is what gives Windows hosts
- * the connection reuse their OpenSSH client cannot provide.
- */
-export declare class Ssh2Transport extends TransportBase implements Transport {
-    #private;
-    readonly id: string;
-    constructor(options: Ssh2TransportOptions);
-    get sessionCount(): number;
-    /** Open the session; concurrent calls share one attempt. */
-    connect(signal?: AbortSignal): Promise<void>;
-    /** Close the session. Idempotent. */
-    dispose(): Promise<void>;
-    /** Run one remote command over a channel of the shared session. */
-    exec(request: ExecRequest, signal?: AbortSignal): Promise<ExecResult>;
-    /**
-     * Read a remote file over SFTP.
-     *
-     * The version token is `size:mtimeSeconds` — the same shape the alias transport produces, so
-     * caches keyed on version tokens keep working when a connection changes transport.
-     */
-    readFile(request: ReadFileRequest, signal?: AbortSignal): Promise<RemoteFileChunk>;
-    /**
-     * Read `maxBytes` from `offset` over SFTP, seeking with a real `position`.
-     *
-     * Why the seek matters: `readFile` always starts at 0, so paging through a large file by
-     * reading `[0, offset+len)` and slicing transfers every earlier byte on every page. Here the
-     * server only sends the requested window, and only `maxBytes` is ever allocated locally.
-     */
-    readFileRange(request: ReadFileRangeRequest, signal?: AbortSignal): Promise<RemoteFileChunk>;
-    /**
-     * Write at `offset` over SFTP, leaving the bytes before it untouched.
-     *
-     * Flags are chosen by offset, and the semantics are deliberately narrow:
-     *
-     *  - `offset === 0` uses `'w'`: the file is **created or truncated**, so a chunked upload that
-     *    restarts from 0 overwrites a longer previous file instead of leaving a stale tail.
-     *  - `offset > 0` uses `'r+'`: the file **must already exist** (there is no other way to preserve
-     *    the earlier bytes), otherwise `REMOTE_NOT_FOUND`. After the positioned write the file is
-     *    truncated to `offset + bytes.byteLength` — a shorter final chunk must shorten the file, or
-     *    the tail of a previous, longer upload would survive and corrupt the result.
-     */
-    writeFileRange(request: WriteFileRangeRequest, signal?: AbortSignal): Promise<RemoteWriteOutcome>;
-    /**
-     * Move a remote path with a plain SFTP `rename`.
-     *
-     * A cross-device move makes the server fail (`SSH_FX_FAILURE` / `EXDEV`) and that failure is
-     * **propagated as-is**: copying would silently turn a move into a copy, which breaks the
-     * "move, then delete the source only after confirmation" semantics callers rely on.
-     */
-    rename(request: RenameRequest, signal?: AbortSignal): Promise<void>;
-    /**
-     * Remove a file, or a directory tree when `recursive` is set.
-     *
-     * A directory without `recursive` is an explicit error, never a silent success: a caller that
-     * hears "removed" must be able to trust that the path is gone.
-     *
-     * Symbolic links are never followed. SFTP v3 `readdir` reports a link as an entry with
-     * `mode & 0o170000 === 0o120000`; treating it as a directory would either recurse forever on a
-     * self-referential link or descend into a tree that was never requested for deletion.
-     */
-    remove(request: RemoveRequest, signal?: AbortSignal): Promise<void>;
-    /**
-     * Write a remote file over SFTP: temp file in the target directory, then a rename.
-     *
-     * The optional `expectedSha256` guard runs the same remote digest tool the alias transport
-     * uses, so a guarded write means the same thing on both transports.
-     */
-    writeFile(request: WriteFileRequest, signal?: AbortSignal): Promise<RemoteWriteOutcome>;
-    /**
-     * Probe the remote host once and remember the result.
-     *
-     * @param signal - cancellation.
-     * @param maxAgeMs - reuse a previous probe inside this window (default 5 minutes).
-     * @returns the discovered capabilities.
-     */
-    probeCapabilities(signal?: AbortSignal, maxAgeMs?: number): Promise<RemoteCapabilities>;
-}
-/** Version token shared by every transport: `size:mtimeSeconds`. */
-export declare function versionToken(size: number, mtimeSeconds: number): string;
-/** Map an SFTP failure onto a plugin error code. */
-export declare function sftpError(operation: string, path: string, error?: Error): SshDevError;
-/**
- * The real connector: wraps the `ssh2` package.
- *
- * Loaded lazily so this module (and its unit tests) never require the dependency, and required
- * for dynamic jump chains: each hop is reached by forwarding a TCP channel through the previous
- * session.
- */
-export declare const defaultConnector: Ssh2Connector;
-//# sourceMappingURL=ssh2-transport.d.ts.map

package/lib/types/src/host/integration/agent/agent-install-io.d.ts

@@ -1,33 +0,0 @@
-/**
- * The install ladder's I/O, built on the connection's **Tier 1 transport**.
- *
- * The agent cannot install itself, so every step of the ladder runs through the transport that already
- * works: `exec` for the probe, `writeFile` for the upload (the Tier 1 transports already implement bounded,
- * atomic remote writes), and one more `exec` for the digest. Nothing here opens a second authentication
- * path, which is what keeps "upload" as trustworthy as "run a command".
- *
- * @module dsh-over-ssh/integration/agent-install-io
- */
-import type { AgentInstallIo } from '../../infra/transport/agent/agent-installer.ts';
-import type { Transport } from '../../infra/transport/transport.ts';
-/** Options for {@link createAgentInstallIo}. */
-export interface AgentInstallIoOptions {
-    /** The Tier 1 transport of the connection being installed onto. */
-    readonly transport: Transport;
-    /** Refuse to upload anything larger than this (a corrupt manifest must not fill the host's disk). */
-    readonly maxUploadBytes?: number;
-    /** Local file reader, injected so tests never touch a real file. */
-    readonly readLocalFile?: (path: string) => Promise<Uint8Array>;
-    /** Local size lookup, so an oversized artifact is rejected before it is read into memory. */
-    readonly localSize?: (path: string) => Promise<number>;
-    /** Cap for exec output while probing; the ladder only needs tiny answers. */
-    readonly probeMaxBytes?: number;
-}
-/**
- * Build the ladder's I/O from an existing transport.
- *
- * @param options - transport plus optional readers and caps.
- * @returns an {@link AgentInstallIo} that never opens a second connection.
- */
-export declare function createAgentInstallIo(options: AgentInstallIoOptions): AgentInstallIo;
-//# sourceMappingURL=agent-install-io.d.ts.map

package/lib/types/src/host/integration/agent/askpass-registry.d.ts

@@ -1,66 +0,0 @@
-/**
- * Per-connection store of `SSH_ASKPASS` helpers.
- *
- * Why this exists as a module: preparing a helper is **async** (it reads the secret from the credential
- * service and writes two files), but transport factories are **synchronous** and are also reached from
- * `createAlias` during the install ladder. The two are joined here: something async calls
- * {@link AskpassRegistry.prepare} first, and the factory then reads {@link AskpassRegistry.envFor}
- * without awaiting.
- *
- * Three rules:
- *
- *  1. **One helper per connection.** Preparing twice returns the same handle, so a reconnect does not
- *     accumulate temp directories (and the secret is read once).
- *  2. **Only password connections get one.** Key and agent connections never prompt; handing them
- *     `BatchMode=no` would let a misconfigured host block on an interactive prompt forever.
- *  3. **A failure is a degradation, not a throw.** If the secret cannot be resolved the connection still
- *     works through the transports that do not need it; {@link AskpassRegistry.prepare} reports `undefined`
- *     and the caller keeps its previous behaviour.
- *
- * @module dsh-over-ssh/integration/askpass-registry
- */
-import { type AskpassHandle } from '../../infra/transport/ssh/askpass.ts';
-import type { ConnectionProfile } from '../../domain/roots/connection.ts';
-/** Options for {@link createAskpassRegistry}. */
-export interface AskpassRegistryOptions {
-    /** Resolve the connection's password. Throws when it is missing or the credential service is absent. */
-    readonly readSecret: (profile: ConnectionProfile) => Promise<string>;
-    /** Materialise one helper for a secret. */
-    readonly create: (secret: string) => Promise<AskpassHandle>;
-    /** Optional sink for "we could not prepare one" so the reason is not swallowed. */
-    readonly onUnavailable?: (connectionId: string, reason: string) => void;
-}
-/** The registry surface the composition root needs. */
-export interface AskpassRegistry {
-    /**
-     * Ensure a helper exists for this connection.
-     *
-     * @param profile - the connection.
-     * @returns the environment to hand `ssh`, or `undefined` when this connection needs none or preparation
-     *          failed (in which case the caller must keep its non-prompting behaviour).
-     */
-    prepare(profile: ConnectionProfile): Promise<Record<string, string> | undefined>;
-    /** The environment prepared for this connection, if any. Synchronous, for transport factories. */
-    envFor(profile: ConnectionProfile): Record<string, string> | undefined;
-    /** Whether a connection is currently using a password helper. */
-    has(connectionId: string): boolean;
-    /** Drop one connection's helper (its transport was released, or the connection changed). */
-    forget(connectionId: string): Promise<void>;
-    /**
-     * Allow a retired connection id to prepare a helper again.
-     *
-     * Call this only when the connection is deliberately re-established. Without it, a re-saved connection
-     * could never get a password helper, because `forget` leaves a tombstone that `prepare` honours.
-     */
-    revive(connectionId: string): void;
-    /** Drop every helper (plugin unload). */
-    disposeAll(): Promise<void>;
-}
-/**
- * Build the registry.
- *
- * @param options - injected secret reader, helper factory and optional sink.
- * @returns the registry.
- */
-export declare function createAskpassRegistry(options: AskpassRegistryOptions): AskpassRegistry;
-//# sourceMappingURL=askpass-registry.d.ts.map

package/lib/types/src/host/integration/agent-install-io.d.ts

@@ -1,33 +0,0 @@
-/**
- * The install ladder's I/O, built on the connection's **Tier 1 transport**.
- *
- * The agent cannot install itself, so every step of the ladder runs through the transport that already
- * works: `exec` for the probe, `writeFile` for the upload (the Tier 1 transports already implement bounded,
- * atomic remote writes), and one more `exec` for the digest. Nothing here opens a second authentication
- * path, which is what keeps "upload" as trustworthy as "run a command".
- *
- * @module dsh-remote-workspace/integration/agent-install-io
- */
-import type { AgentInstallIo } from '../infra/transport/agent-installer.ts';
-import type { Transport } from '../infra/transport/transport.ts';
-/** Options for {@link createAgentInstallIo}. */
-export interface AgentInstallIoOptions {
-    /** The Tier 1 transport of the connection being installed onto. */
-    readonly transport: Transport;
-    /** Refuse to upload anything larger than this (a corrupt manifest must not fill the host's disk). */
-    readonly maxUploadBytes?: number;
-    /** Local file reader, injected so tests never touch a real file. */
-    readonly readLocalFile?: (path: string) => Promise<Uint8Array>;
-    /** Local size lookup, so an oversized artifact is rejected before it is read into memory. */
-    readonly localSize?: (path: string) => Promise<number>;
-    /** Cap for exec output while probing; the ladder only needs tiny answers. */
-    readonly probeMaxBytes?: number;
-}
-/**
- * Build the ladder's I/O from an existing transport.
- *
- * @param options - transport plus optional readers and caps.
- * @returns an {@link AgentInstallIo} that never opens a second connection.
- */
-export declare function createAgentInstallIo(options: AgentInstallIoOptions): AgentInstallIo;
-//# sourceMappingURL=agent-install-io.d.ts.map

package/lib/types/src/host/integration/agent-preflight.d.ts

@@ -1,56 +0,0 @@
-/**
- * The bridge between the install ladder and transport selection.
- *
- * Selection is synchronous (it may only consult cached facts) while the ladder must talk to the host, so
- * the two are joined by an **async preflight**: the selector's first answer is revised before any transport
- * is built. That is what makes "agent unavailable ⇒ Tier 1" true without making the selector depend on I/O.
- *
- * Two rules this module exists to enforce:
- *
- *  1. **No host traffic unless the connection asked for the agent.** A non-agent decision returns
- *     immediately, so an ordinary alias connection never probes or uploads anything.
- *  2. **A failed ladder is a degradation, never an exception.** `ensureAgent` already turns every remote
- *     problem into a `tier1` outcome; this module forwards that as a revised decision plus a hint.
- *
- * @module dsh-remote-workspace/integration/agent-preflight
- */
-import type { TransportPreflight } from '../app/transport-service.ts';
-import type { ConnectionProfile } from '../domain/connection.ts';
-import type { AgentInstallation } from '../infra/transport/agent-installer.ts';
-/** What the preflight learned about one connection. */
-export type AgentPreflightOutcome = {
-    readonly kind: 'agent';
-    readonly remotePath: string;
-    readonly platform: string;
-    readonly reused: boolean;
-} | {
-    readonly kind: 'tier1';
-    readonly reason: string;
-    readonly hint: string;
-};
-/** Options for {@link createAgentPreflight}. */
-export interface AgentPreflightOptions {
-    /** Run (or reuse a memoized) ladder for one connection. Injected so this module stays offline-testable. */
-    readonly ensure: (profile: ConnectionProfile, signal?: AbortSignal) => Promise<AgentInstallation>;
-    /** Optional sink so the connection UI can show what happened. */
-    readonly onOutcome?: (connectionId: string, outcome: AgentPreflightOutcome) => void;
-    /** Optional logger for the "we are not even trying" path; defaults to silence. */
-    readonly onSkipped?: (profile: ConnectionProfile) => void;
-}
-/** The preflight plus the installation facts the agent factory needs. */
-export interface AgentPreflight {
-    /** Pass this to {@link TransportServiceOptions.preflight}. */
-    readonly preflight: TransportPreflight;
-    /** The installation for a connection, once the ladder approved one. */
-    installationFor(connectionId: string): AgentPreflightOutcome | undefined;
-    /** Forget one connection (its transport was released, or the user changed the connection). */
-    forget(connectionId: string): void;
-}
-/**
- * Build the preflight.
- *
- * @param options - ladder plus optional sinks.
- * @returns the preflight, an installation lookup, and a way to forget a connection.
- */
-export declare function createAgentPreflight(options: AgentPreflightOptions): AgentPreflight;
-//# sourceMappingURL=agent-preflight.d.ts.map

package/lib/types/src/host/integration/anchor-directory.d.ts

@@ -1,56 +0,0 @@
-/**
- * The local anchor directory of a remote root.
- *
- * A remote root needs a **local** path to stand in for it, because a workspace path must exist on this machine
- * (`root.ts` keeps that anchor on the `RootRef`). The platform then resolves that path with `realpath` when it
- * opens a workspace on it, so the directory has to be **created**, not just computed:
- *
- *     workspace create failed: workspace/invalid-path: cannot create a Workspace at
- *     "C:\\Users\\…\\.dsh\\ssh-dev\\roots\\腾讯云\\39d1e90c": ENOENT …
- *
- * That failure is what this module exists to prevent. It lives in its own file so the rule ("a remote root's
- * anchor must exist") is in one place and testable without a real home directory (红线 3: 外部依赖走注入).
- *
- * @module dsh-remote-workspace/integration/anchor-directory
- */
-import type { RootRef } from '../domain/root.ts';
-/** The one filesystem call this module needs. */
-export interface AnchorDirectoryIo {
-    /**
-     * Create a directory and its parents; a no-op when it already exists.
-     *
-     * The return value is ignored on purpose (`node:fs` answers with the first created path): this module only
-     * cares that the directory exists afterwards, so the seam stays as narrow as that fact.
-     */
-    mkdir(path: string, options: {
-        readonly recursive: true;
-    }): Promise<unknown> | unknown;
-}
-/**
- * Make one root's local anchor exist.
- *
- * Local roots are their own anchor (the directory is the user's own path, which the platform checks itself), and
- * a remote root without an anchor simply has nothing to create  - both cases return without touching the disk.
- *
- * @param root - the root that is about to become live.
- * @param io - the injected filesystem.
- * @returns nothing; a failure propagates so the caller decides whether it is fatal.
- */
-export declare function ensureAnchorDirectory(root: Pick<RootRef, 'location' | 'anchorPath'>, io: AnchorDirectoryIo): Promise<void>;
-/**
- * The last path segment of a remote root's anchor: **the remote folder's own name**.
- *
- * Why it matters: the platform titles a new workspace with `defaultWorkspaceTitle(path)` =
- * `basename(path)` (`dsh-workspace/lib/types/paths.js:26-29`), and the directory-flow contract only carries a
- * `path`  - there is no title parameter to pass (`DirectoryFlowOwnerProps`). So the segment this function
- * returns **is** the name the user sees in the sidebar. A digest-only anchor made every remote workspace show
- * up as `daf8c293`; this is what turns it into `stress_10`.
- *
- * Identity is *not* this function's job: the caller keeps a digest directory above it, so two remote paths with
- * the same folder name still get two anchors (one canonical path per workspace).
- *
- * @param remotePath - absolute POSIX path on the remote host.
- * @returns a segment that is safe to create on this machine and readable as a workspace name.
- */
-export declare function anchorLeafName(remotePath: string): string;
-//# sourceMappingURL=anchor-directory.d.ts.map

package/lib/types/src/host/integration/askpass-registry.d.ts

@@ -1,59 +0,0 @@
-/**
- * Per-connection store of `SSH_ASKPASS` helpers.
- *
- * Why this exists as a module: preparing a helper is **async** (it reads the secret from the credential
- * service and writes two files), but transport factories are **synchronous** and are also reached from
- * `createAlias` during the install ladder. The two are joined here: something async calls
- * {@link AskpassRegistry.prepare} first, and the factory then reads {@link AskpassRegistry.envFor}
- * without awaiting.
- *
- * Three rules:
- *
- *  1. **One helper per connection.** Preparing twice returns the same handle, so a reconnect does not
- *     accumulate temp directories (and the secret is read once).
- *  2. **Only password connections get one.** Key and agent connections never prompt; handing them
- *     `BatchMode=no` would let a misconfigured host block on an interactive prompt forever.
- *  3. **A failure is a degradation, not a throw.** If the secret cannot be resolved the connection still
- *     works through the transports that do not need it; {@link AskpassRegistry.prepare} reports `undefined`
- *     and the caller keeps its previous behaviour.
- *
- * @module dsh-remote-workspace/integration/askpass-registry
- */
-import { type AskpassHandle } from '../infra/transport/askpass.ts';
-import type { ConnectionProfile } from '../domain/connection.ts';
-/** Options for {@link createAskpassRegistry}. */
-export interface AskpassRegistryOptions {
-    /** Resolve the connection's password. Throws when it is missing or the credential service is absent. */
-    readonly readSecret: (profile: ConnectionProfile) => Promise<string>;
-    /** Materialise one helper for a secret. */
-    readonly create: (secret: string) => Promise<AskpassHandle>;
-    /** Optional sink for "we could not prepare one" so the reason is not swallowed. */
-    readonly onUnavailable?: (connectionId: string, reason: string) => void;
-}
-/** The registry surface the composition root needs. */
-export interface AskpassRegistry {
-    /**
-     * Ensure a helper exists for this connection.
-     *
-     * @param profile - the connection.
-     * @returns the environment to hand `ssh`, or `undefined` when this connection needs none or preparation
-     *          failed (in which case the caller must keep its non-prompting behaviour).
-     */
-    prepare(profile: ConnectionProfile): Promise<Record<string, string> | undefined>;
-    /** The environment prepared for this connection, if any. Synchronous, for transport factories. */
-    envFor(profile: ConnectionProfile): Record<string, string> | undefined;
-    /** Whether a connection is currently using a password helper. */
-    has(connectionId: string): boolean;
-    /** Drop one connection's helper (its transport was released, or the connection changed). */
-    forget(connectionId: string): Promise<void>;
-    /** Drop every helper (plugin unload). */
-    disposeAll(): Promise<void>;
-}
-/**
- * Build the registry.
- *
- * @param options - injected secret reader, helper factory and optional sink.
- * @returns the registry.
- */
-export declare function createAskpassRegistry(options: AskpassRegistryOptions): AskpassRegistry;
-//# sourceMappingURL=askpass-registry.d.ts.map