dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,44 @@
+/**
+ * Adapters that turn the plugin's routing + transports into the injected dependencies the transfer and
+ * recycle-bin services expect.
+ *
+ * Two rules shape everything here:
+ *
+ *  - **Remote work uses the real primitives.** Chunked reads go through `Transport.readFileRange` (verified on
+ *    a real host: exact window, no whole-file read) and positioned writes through `writeFileRange` (POSIX
+ *    `pwrite` semantics, shared by all three transports). Where a transport lacks the method the fallback is
+ *    written down instead of hidden.
+ *  - **Local work never borrows the remote path.** `node:fs` is opened with `position` arguments so a local
+ *    chunk does not read the whole file either; the recycle bin's local mutators are a separate object, so a
+ *    local target can never end up being "moved" by an ssh command.
+ *
+ * @module dsh-remote-workspace/integration/transfer-adapters
+ */
+import type { RootRef } from '../domain/root.ts';
+import type { RoutedFileSystem } from '../app/routed-fs.ts';
+import type { Transport } from '../infra/transport/transport.ts';
+import type { RecycleBinServiceDeps } from '../app/recycle-bin-service.ts';
+import type { TransferDependencies } from './transfer-service.ts';
+/** What both adapters need from the plugin. */
+export interface WorldAdapterDeps {
+    /** Path routing: turns a path in any root's spelling into `{root, backend, absolute}`. */
+    readonly routed: RoutedFileSystem;
+    /** The transport of one connection (the caller already owns the profile lookup). */
+    readonly transportFor: (connectionId: string) => Promise<Transport>;
+    /** Bin directory **inside one root** (same device, so the move stays a rename). */
+    readonly binRootFor: (root: RootRef) => string;
+    /** Chunk ceiling passed to the transfer service. */
+    readonly chunkBytes: number;
+    /** Upper bound for one text read (the index file). */
+    readonly maxReadBytes: number;
+    /** Clock, injected for tests. */
+    readonly now?: () => number;
+}
+/** The transfer service's dependencies. */
+export declare function createTransferDeps(deps: WorldAdapterDeps): TransferDependencies;
+/** The recycle bin's dependencies: remote primitives plus an explicit local world. */
+export declare function createRecycleBinDeps(deps: WorldAdapterDeps & {
+    readonly knownRoots: () => readonly RootRef[];
+    readonly undoDepth: number;
+}): RecycleBinServiceDeps;
+//# sourceMappingURL=transfer-adapters.d.ts.map

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

@@ -0,0 +1,164 @@
+/**
+ * The remote-file transfer seam: move one file in one direction, in bounded chunks, with progress.
+ *
+ * This module owns the *policy* half of a transfer — offsets, resume decisions, progress callbacks,
+ * cancellation and failure classification — and none of the I/O. Every side effect arrives as an
+ * injected dependency (`readLocal`, `writeRemote`, `readRemote`, `writeLocal`, `statLocal`,
+ * `statRemote`, optional `sha256Local`, optional clock), so the whole flow can be exercised offline
+ * against substitute I/O (AGENTS.md 红线 3), and the same code runs on a real host by wiring the real
+ * implementations in [`src/index.ts`] (left to the plugin entry, which this change does not touch).
+ *
+ * Contract notes that callers and implementers both rely on:
+ *
+ *  - **Memory is bounded by `chunkBytes`**: a chunk is read, written and dropped; the file is never
+ *    assembled in memory. A test asserts this by recording every `readLocal` request, not by claiming it.
+ *  - **`offset === undefined` means "replace the target's content with exactly these bytes"**;
+ *    `offset === n` means "place these bytes at byte n, extending the target". The first write of a
+ *    fresh transfer therefore carries no offset, and every later chunk carries its absolute offset.
+ *  - **Progress fires once per completed write** and never decreases: each snapshot is computed from
+ *    a running byte counter, and the clock is injected so rates are reproducible in tests.
+ *  - **Cancellation is reported, never swallowed**: an aborted transfer fails with `CANCELLED` and
+ *    details carrying the bytes that are known to have landed, how many chunks were written, and
+ *    whether the chunk in flight may have landed partially.
+ *  - **Failure is classified**: `details.kind` is the precise {@link TransferFailureKind}; the error
+ *    code stays inside the existing `SSH_DEV_ERROR_CODES` table (see `domain/transfer.ts`).
+ *
+ * @module dsh-remote-workspace/integration/transfer-service
+ */
+import { type TransferDegradation, type TransferProgress } from '../domain/transfer.ts';
+import type { BackendStat } from '../app/backend.ts';
+import type { RemoteWriteOutcome } from '../infra/transport/transport.ts';
+/** Default cap on one read/write step; overridable per call and per service instance. */
+export declare const DEFAULT_TRANSFER_CHUNK_BYTES: number;
+/** One bounded source read. */
+export interface SourceReadOptions {
+    /** Byte offset to start at. */
+    readonly offset: number;
+    /** Maximum bytes to return; a shorter answer means the source ended early. */
+    readonly length: number;
+    readonly signal?: AbortSignal;
+}
+/** One bounded remote read. */
+export interface RemoteReadOptions {
+    /** Byte offset to start at; omitted means 0. */
+    readonly offset?: number;
+    /** Maximum bytes to return *from `offset`*. */
+    readonly maxBytes: number;
+    readonly signal?: AbortSignal;
+}
+/** One remote write. */
+export interface RemoteWriteOptions {
+    /** `undefined` replaces the file's content; `n` places the bytes at byte `n`. */
+    readonly offset?: number;
+    /** Refuse the write unless the target's current content has this digest (optimistic guard). */
+    readonly expectedSha256?: string;
+    readonly signal?: AbortSignal;
+}
+/** One local write (the download side). */
+export interface LocalWriteOptions {
+    /** `undefined` replaces the file's content; `n` places the bytes at byte `n`. */
+    readonly offset?: number;
+}
+/** Everything a transfer needs from the outside world. */
+export interface TransferDependencies {
+    /** Bounded local read. Must not return more than `length` bytes. */
+    readonly readLocal: (path: string, options: SourceReadOptions) => Promise<Uint8Array>;
+    /**
+     * Remote write. `offset === undefined` replaces the target; `offset === n` writes at `n`.
+     * Returning {@link RemoteWriteOutcome} is how a remote digest (if any) reaches the caller.
+     */
+    readonly writeRemote: (absolute: string, bytes: Uint8Array, options: RemoteWriteOptions) => Promise<RemoteWriteOutcome>;
+    /**
+     * Remote read, bounded by `maxBytes` and optionally starting at `offset`.
+     *
+     * The sketched Tier 1 transport takes only `maxBytes`; the optional `offset` is what makes a
+     * chunked download possible, so an implementation that cannot honour it must say so rather than
+     * silently returning the head of the file (a wrong answer is worse than a refused one).
+     */
+    readonly readRemote: (absolute: string, options: RemoteReadOptions) => Promise<Uint8Array>;
+    /** Local write; same offset convention as {@link TransferDependencies.writeRemote}. */
+    readonly writeLocal: (path: string, bytes: Uint8Array, options: LocalWriteOptions) => Promise<void>;
+    /** Local metadata. Must report `exists: false` for a missing path instead of throwing. */
+    readonly statLocal: (path: string) => Promise<BackendStat>;
+    /** Remote metadata. Same `exists` rule as {@link TransferDependencies.statLocal}. */
+    readonly statRemote: (absolute: string) => Promise<BackendStat>;
+    /** Optional digest of a local file; when absent the result reports `sha256: null`. */
+    readonly sha256Local?: (path: string) => Promise<string>;
+    /**
+     * Whether `writeRemote` may continue an existing partial remote file (`resume: true` requests).
+     * Defaults to `false`: a requested resume then degrades to a full rewrite **and says so**.
+     */
+    readonly supportsResume?: boolean;
+    /** Default per-chunk cap; a request may override it. */
+    readonly chunkBytes?: number;
+    /** Clock, injected so rate/remaining estimates are reproducible in tests. */
+    readonly nowMs?: () => number;
+}
+/** Common request fields. */
+export interface TransferRequestBase {
+    /** Connection the remote path belongs to; recorded in the result and in failures. */
+    readonly connectionId: string;
+    /** Absolute POSIX root the remote path must stay inside. */
+    readonly root: string;
+    /** Remote path relative to the root; `..` is folded and can never escape. */
+    readonly remotePath: string;
+    /** Per-chunk cap for this call; defaults to the service's `chunkBytes`. */
+    readonly chunkBytes?: number;
+    /** Keep bytes already present on the target when possible; defaults to `false`. */
+    readonly resume?: boolean;
+    readonly onProgress?: (progress: TransferProgress) => void;
+    readonly signal?: AbortSignal;
+}
+/** Upload one local file to the remote root. */
+export interface UploadRequest extends TransferRequestBase {
+    /** Local source file. */
+    readonly localPath: string;
+    /**
+     * Digest the remote target must currently have, forwarded to the first `writeRemote` call as its
+     * optimistic guard. A dependency that refuses the write surfaces as `TRANSFER_CONFLICT`.
+     */
+    readonly expectedSha256?: string;
+}
+/** Download one remote file into a local path. */
+export interface DownloadRequest extends TransferRequestBase {
+    /** Local destination *file* path (its base name is validated for the host platform). */
+    readonly localPath: string;
+}
+/** What one transfer did. */
+export interface TransferResult {
+    readonly direction: 'upload' | 'download';
+    readonly connectionId: string;
+    readonly root: string;
+    readonly localPath: string;
+    /** Root-absolute remote path the transfer actually used (after `..` folding). */
+    readonly remotePath: string;
+    readonly totalBytes: number;
+    /** Bytes this transfer wrote, excluding any prefix it resumed from. */
+    readonly bytesTransferred: number;
+    /** Writes performed by this transfer (0 for a resumed transfer with nothing left; 1 for an empty file). */
+    readonly chunks: number;
+    readonly resumed: boolean;
+    /** Offset the transfer started at. */
+    readonly startOffset: number;
+    readonly durationMs: number;
+    /**
+     * Digest of the transferred content, or `null` when no digest was obtainable:
+     * the remote's own digest for a single non-resumed write, else `sha256Local`'s answer.
+     */
+    readonly sha256: string | null;
+    /** Why something was not done as asked (resume refused, digest unavailable); empty when clean. */
+    readonly degradations: readonly TransferDegradation[];
+}
+/** The two operations this seam exposes. */
+export interface TransferService {
+    upload(request: UploadRequest): Promise<TransferResult>;
+    download(request: DownloadRequest): Promise<TransferResult>;
+}
+/**
+ * Build the transfer service.
+ *
+ * @param dependencies - all local/remote I/O plus the optional clock, digest and resume capability.
+ * @returns the upload/download operations; no state is kept between calls.
+ */
+export declare function createTransferService(dependencies: TransferDependencies): TransferService;
+//# sourceMappingURL=transfer-service.d.ts.map

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

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