dsh-over-ssh 0.1.0 → 0.2.0

package/lib/types/src/host/domain/transfer.d.ts

@@ -1,260 +0,0 @@
-/**
- * Pure transfer arithmetic: chunk plans, progress maths, root-confined remote targets and file-name
- * validation.
- *
- * Kept in the domain layer on purpose (AGENTS.md 红线 2): no `@deepseek-ai/*` import, no process, no
- * socket and no clock — every number it needs is a parameter. That is what lets the whole transfer
- * policy (offsets, percentages, resume decisions, `..` folding rules) be tested offline in
- * milliseconds, and it is why the seam in `integration/transfer-service.ts` only has to move bytes.
- *
- * Three behaviours are deliberately *deterministic* rather than "reasonable":
- *
- *  - **A zero-byte file has zero chunks** but still needs one empty write to create the target
- *    (`needsEmptyWrite`), so "upload an empty file" is a real operation rather than a no-op.
- *  - **A plan is bounded**: the chunk list is materialised, so `MAX_TRANSFER_CHUNKS` caps it and an
- *    absurd `chunkBytes` fails loudly instead of exhausting memory.
- *  - **`..` never escapes the root**: the spelling is folded the way `joinUnderRoot` folds it, and the
- *    result is re-checked against the root, so a future change to the folder cannot silently open a
- *    hole (see {@link assertInsideRoot}).
- *
- * @module dsh-remote-workspace/domain/transfer
- */
-import { formatBytes, formatDuration } from '../../shared/format.ts';
-import { SshDevError, type SshDevErrorCode } from './errors.ts';
-/**
- * Upper bound on the number of chunks one plan may contain.
- *
- * This is **not** a deployment knob — the deployment knob is `chunkBytes`. It exists because
- * {@link planTransfer} materialises the chunk list, so a tiny `chunkBytes` on a huge file would
- * otherwise allocate until the process dies.
- */
-export declare const MAX_TRANSFER_CHUNKS = 100000;
-/** One slice of a transfer: bytes `[offset, offset + length)` of the source. */
-export interface TransferChunk {
-    /** 0-based position of this chunk inside the plan it was produced by. */
-    readonly index: number;
-    /** Byte offset in the source. */
-    readonly offset: number;
-    /** Number of bytes to move; always ≥ 1. */
-    readonly length: number;
-}
-/** A complete, finite plan for moving `totalBytes`. */
-export interface TransferPlan {
-    readonly totalBytes: number;
-    readonly chunkBytes: number;
-    /** Chunks in increasing offset order; empty for a zero-byte source. */
-    readonly chunks: readonly TransferChunk[];
-    /** Whether the target still has to be created with one write of zero bytes. */
-    readonly needsEmptyWrite: boolean;
-}
-/** Why a transfer could not do something the caller asked for, or could not report a digest. */
-export interface TransferDegradation {
-    /** Stable code, so a caller can branch without reading the hint. */
-    readonly code: 'resume-unsupported' | 'resume-unusable' | 'digest-unavailable';
-    /** Actionable explanation for the user. */
-    readonly hint: string;
-}
-/** What to do about a possibly-partial target before starting. */
-export interface ResumeDecision {
-    /** Byte offset the transfer starts at. */
-    readonly startOffset: number;
-    /** Whether bytes already present on the target are being kept. */
-    readonly resumed: boolean;
-    /** Reasons the transfer is not resuming; empty when it resumes or was never asked to. */
-    readonly degradations: readonly TransferDegradation[];
-}
-/**
- * Cut `totalBytes` into contiguous chunks of at most `chunkBytes`.
- *
- * @param totalBytes - source length; 0 produces an empty plan plus `needsEmptyWrite`.
- * @param chunkBytes - per-chunk cap; must be a safe integer ≥ 1.
- * @returns the plan, with offsets starting at 0 and covering exactly `totalBytes`.
- * @throws SshDevError `ROOT_INVALID` when either argument is not a usable integer, or when the plan
- *   would exceed {@link MAX_TRANSFER_CHUNKS}.
- */
-export declare function planTransfer(totalBytes: number, chunkBytes: number): TransferPlan;
-/**
- * The chunks still to move when the target already holds `startOffset` bytes.
- *
- * The first returned chunk is trimmed to start exactly at `startOffset`, and indices are renumbered
- * from 0 because the caller reports "how many writes did *this* transfer make".
- *
- * @param plan - the full plan.
- * @param startOffset - bytes already present; ≤ 0 means "nothing", ≥ `totalBytes` means "nothing left".
- * @returns the remaining chunks; the input plan is not mutated.
- */
-export declare function remainingChunks(plan: TransferPlan, startOffset: number): readonly TransferChunk[];
-/**
- * Decide where a transfer starts, given what the target already holds.
- *
- * Precedence (each rule is a test): no resume requested → 0; zero-byte source → 0; the injected
- * implementation cannot resume → 0 with `resume-unsupported`; nothing usable on the target → 0;
- * target is at least as long as the source → 0 with `resume-unusable` (a same-size target is **never**
- * assumed complete, because nothing here can verify its content); otherwise the target's length.
- *
- * @param input - source length, target length (`undefined` when absent/unknown) and the two flags.
- * @returns the decision, including why resume did not happen.
- */
-export declare function decideStartOffset(input: {
-    readonly totalBytes: number;
-    readonly partialBytes: number | undefined;
-    readonly resumeRequested: boolean;
-    readonly resumeSupported: boolean;
-}): ResumeDecision;
-/** Progress of one transfer at one instant. */
-export interface TransferProgress {
-    readonly transferredBytes: number;
-    readonly totalBytes: number;
-    /** 0–100, rounded to one decimal; a zero-byte transfer is 100 (nothing left to do). */
-    readonly percent: number;
-    /** Average rate since the transfer started; 0 when no time has passed. */
-    readonly bytesPerSecond: number;
-    readonly elapsedMs: number;
-    /** Estimated time left; `null` when no rate is known yet, 0 when finished. */
-    readonly remainingMs: number | null;
-}
-/**
- * Compute progress from the two byte counts and elapsed time.
- *
- * Pure and monotonic: for a fixed `totalBytes` and a non-decreasing `transferredBytes`, every field
- * is non-decreasing.
- *
- * @param input - bytes moved, bytes expected and milliseconds since the start.
- * @returns the progress snapshot.
- */
-export declare function progressOf(input: {
-    readonly transferredBytes: number;
-    readonly totalBytes: number;
-    readonly elapsedMs: number;
-}): TransferProgress;
-/** Binary byte units, largest last. */
-/**
- * One-line progress text for the UI or a CLI.
- *
- * @param progress - a snapshot from {@link progressOf}.
- * @param options - `label` names the direction (`上传`/`下载`); defaults to `传输`.
- * @returns e.g. `上传 40.0%（4 B/10 B，2 B/s，剩余约 3.0s）`, or `…，耗时 350ms）` once finished.
- */
-export declare function formatProgress(progress: TransferProgress, options?: {
-    readonly label?: string;
-}): string;
-/** A remote target resolved inside one root. */
-export interface RemoteTarget {
-    /** Normalized root the target lives in. */
-    readonly root: string;
-    /** Root-absolute POSIX path of the target. */
-    readonly absolute: string;
-    /** The spelling requested, with `.`/`..` folded (may differ from `absolute`). */
-    readonly relative: string;
-    /** Final path segment. */
-    readonly name: string;
-}
-/**
- * Fold `root + requested` into a root-absolute path that cannot leave the root.
- *
- * The folding rule is exactly `joinUnderRoot`'s (imported, not re-implemented): a leading `/` is
- * treated as root-relative, `.` is dropped, and `..` pops within the *requested* part only — extra
- * `..` at the top are ignored rather than climbing out of the root. The result is re-checked with
- * {@link assertInsideRoot} so a future change to the folder cannot silently open a hole.
- *
- * @param root - absolute POSIX root directory.
- * @param requested - remote spelling relative to the root (absolute spellings are root-relative too).
- * @returns the resolved target.
- * @throws SshDevError `ROOT_INVALID` for an unusable root/request, `ROOT_OUTSIDE` when the request
- *   names the root itself, ends with `/` (a directory spelling) or somehow escapes the root.
- */
-export declare function resolveRemoteTarget(root: string, requested: string): RemoteTarget;
-/**
- * Check that a root-absolute path really is inside its root.
- *
- * @param root - absolute POSIX root directory.
- * @param absolute - root-absolute candidate.
- * @throws SshDevError `ROOT_OUTSIDE` when the candidate is not the root or below it.
- */
-export declare function assertInsideRoot(root: string, absolute: string): void;
-/**
- * Validate one remote file name (a single path segment).
- *
- * @param name - the segment to check.
- * @returns the name, unchanged.
- * @throws SshDevError `ROOT_INVALID` for an empty/blank name, one containing `/` or NUL;
- *   `ROOT_OUTSIDE` for `.`/`..`, which name a directory rather than a file.
- */
-export declare function validateRemoteFileName(name: string): string;
-/**
- * Validate one local file name for the platform the download will land on.
- *
- * The platform is a parameter rather than `process.platform` so the Windows rules stay testable on
- * any host (see [`run-tests.md`] on platform-dependent assertions).
- *
- * @param name - the segment to check (a base name, never a path).
- * @param options - `platform` selects the rule set; defaults to the running platform.
- * @returns the name, unchanged.
- * @throws SshDevError `ROOT_INVALID` for an empty/blank name, a name containing a path separator or
- *   (on win32) a forbidden character, a reserved device name or a trailing dot/space;
- *   `ROOT_OUTSIDE` for `.`/`..`.
- */
-export declare function validateLocalFileName(name: string, options?: {
-    readonly platform?: 'win32' | 'posix';
-}): string;
-/**
- * The final segment of a local path, in either separator spelling.
- *
- * @param path - host path.
- * @returns the base name; empty when the path has no segment.
- */
-export declare function localFileBasename(path: string): string;
-/**
- * What went wrong in a transfer, precisely.
- *
- * This is **not** an error code (the code table lives in `domain/errors.ts` and is unchanged by this
- * module). It is the `details.kind` of the thrown {@link SshDevError}, the same shape
- * `sshFailureToError` uses to keep "which precise cause" separate from "which stable code".
- */
-export type TransferFailureKind = 
-/** Arguments or spelling are unusable (empty root, empty name, bad chunk cap). */
-'invalid-request'
-/** The target names a directory, the root itself, or leaves the root. */
- | 'outside-root' | 'local-stat-failed' | 'local-read-failed' | 'local-write-failed' | 'remote-stat-failed' | 'remote-not-found' | 'remote-read-failed' | 'remote-short-read' | 'remote-write-failed'
-/** The source changed size while it was being read. */
- | 'source-changed' | 'verify-failed' | 'cancelled';
-/** Every {@link TransferFailureKind}, for exhaustive checks and tests. */
-export declare const TRANSFER_FAILURE_KINDS: readonly ["invalid-request", "outside-root", "local-stat-failed", "local-read-failed", "local-write-failed", "remote-stat-failed", "remote-not-found", "remote-read-failed", "remote-short-read", "remote-write-failed", "source-changed", "verify-failed", "cancelled"];
-/**
- * Map a precise transfer failure onto one of the **existing** plugin error codes.
- *
- * No code is invented here (see the audit): a local I/O failure has no dedicated code in
- * `SSH_DEV_ERROR_CODES`, so it maps to `ROOT_INVALID` ("this path is unusable") and stays
- * distinguishable through `details.kind`.
- *
- * @param kind - the precise failure.
- * @returns the stable code a caller can branch on.
- */
-export declare function failureCodeFor(kind: TransferFailureKind): SshDevErrorCode;
-/**
- * Build the plugin failure for one transfer step.
- *
- * @param kind - precise failure kind, recorded as `details.kind`.
- * @param message - actionable Chinese message (what failed and what to do).
- * @param details - structured context; must not contain secrets.
- * @returns an {@link SshDevError} carrying the mapped code.
- */
-export declare function transferFailure(kind: TransferFailureKind, message: string, details?: Readonly<Record<string, unknown>>): SshDevError;
-/**
- * Test whether a value is a transfer failure (optionally of one precise kind).
- *
- * @param error - candidate.
- * @param kind - when given, also require `details.kind` to equal it.
- * @returns whether the value is a plugin error produced by this module.
- */
-export declare function isTransferFailure(error: unknown, kind?: TransferFailureKind): boolean;
-/**
- * Compare two digests tolerantly (hex digests arrive with mixed case and stray whitespace).
- *
- * @param left - one digest, or `undefined`.
- * @param right - the other digest, or `undefined`.
- * @returns whether both are present and equal ignoring case and surrounding whitespace.
- */
-export declare function digestsMatch(left: string | undefined, right: string | undefined): boolean;
-export { formatBytes, formatDuration };
-//# sourceMappingURL=transfer.d.ts.map

package/lib/types/src/host/infra/backend/local-backend.d.ts

@@ -1,84 +0,0 @@
-/**
- * The local backend: one host directory served through `node:fs`.
- *
- * Reads are capped before allocating, writes go through a temporary file plus `rename` so a crash
- * cannot leave a half-written file, and a version token is derived from size + mtime so the router
- * can revalidate a cached body with a single `stat`.
- *
- * @module dsh-over-ssh/infra/backend/local-backend
- */
-import type { Backend, BackendEntry, BackendRead, BackendSandboxMode, BackendStat, BackendText, BackendWrite } from '../../app/backend.ts';
-/** Options for the local backend. */
-export interface LocalBackendOptions {
-    /** Backend id (the router namespaces target keys with it). */
-    readonly id: string;
-    readonly sandboxMode?: BackendSandboxMode;
-    /** Hard cap for a single read; the router passes its own, this is the floor. */
-    readonly maxReadBytes?: number;
-    /**
-     * The per-entry `stat` used by {@link LocalBackend.list}, injected so a test can observe the loop's shape
-     * (how many stats are in flight at once) without timing anything. Defaults to `node:fs/promises.stat`.
-     */
-    readonly statEntry?: (path: string) => Promise<{
-        readonly size: number;
-        readonly mtimeMs: number;
-        readonly ino?: number;
-    }>;
-}
-/** Local filesystem access for one root. */
-export declare class LocalBackend implements Backend {
-    #private;
-    readonly id: string;
-    readonly sandboxMode: BackendSandboxMode | undefined;
-    readonly watches = false;
-    constructor(options: LocalBackendOptions);
-    stat(absolute: string, signal?: AbortSignal): Promise<BackendStat>;
-    /** Stat the entry itself, so a symlink is reported as a symlink rather than its target. */
-    lstat(absolute: string, signal?: AbortSignal): Promise<BackendStat>;
-    list(absolute: string, signal?: AbortSignal): Promise<readonly BackendEntry[]>;
-    readBytes(absolute: string, maxBytes: number, signal?: AbortSignal): Promise<BackendRead>;
-    readText(absolute: string, maxBytes: number, signal?: AbortSignal): Promise<BackendText>;
-    writeText(absolute: string, text: string, expectedVersion: string | undefined, signal?: AbortSignal): Promise<BackendWrite>;
-    /** Ensure a directory exists (used when creating roots and parents). */
-    ensureDirectory(absolute: string): Promise<void>;
-    /**
-     * Create a directory (FR-2.2.2).
-     *
-     * `recursive: false` maps onto `node:fs`'s own `recursive: false`, which already fails with `EEXIST` on an
-     * existing path and `ENOENT` on a missing parent — the two refusals the contract promises.
-     */
-    mkdir(absolute: string, options: {
-        readonly recursive: boolean;
-    }, _signal?: AbortSignal): Promise<void>;
-    /**
-     * Rename/move a path (FR-2.2.2), refusing to clobber.
-     *
-     * `node:fs`'s `rename` **silently replaces** the destination, which the contract forbids, so existence is
-     * checked first. The check-then-rename window is inherent to POSIX `rename(2)`; on Windows `rename` itself
-     * fails with `EEXIST`/`EPERM`, so the guard closes it there and narrows it elsewhere.
-     */
-    rename(from: string, to: string, options: {
-        readonly createParents: boolean;
-    }, _signal?: AbortSignal): Promise<void>;
-    /**
-     * Remove a path (FR-2.2.2). `recursive: false` refuses a directory outright.
-     *
-     * The non-recursive branch checks the type first rather than relying on `unlink`, whose errno for a
-     * directory differs across platforms (Windows reports `EPERM` where POSIX reports `EISDIR`).
-     */
-    remove(absolute: string, options: {
-        readonly recursive: boolean;
-    }, _signal?: AbortSignal): Promise<void>;
-    /**
-     * Change one path's permission bits.
-     *
-     * `mode` is the same 3-4 digit octal string the tool layer validated, converted here with base 8 — passing
-     * it straight to `fs.chmod` as a number would silently reinterpret `"755"` as decimal 755.
-     */
-    chmod(absolute: string, mode: string, _signal?: AbortSignal): Promise<void>;
-    processPath(absolute: string): string;
-    fileUrl(absolute: string): string;
-}
-/** Exported for tests that need a raw full read. */
-export declare function readFileFully(path: string): Promise<Buffer>;
-//# sourceMappingURL=local-backend.d.ts.map

package/lib/types/src/host/infra/backend/local-version.d.ts

@@ -1,43 +0,0 @@
-/**
- * 本地路径的版本令牌：`size:mtimeMs:ino`。
- *
- * ## 为什么不能只用 `size:mtime`
- *
- * mtime 的精度和两次写入之间的间隔不匹配。本仓库原来有三种写法，一种比一种粗：
- *
- * | 位置 | 原写法 | 粒度 |
- * |---|---|---|
- * | `fs-provider` 列目录 | `size:秒` | **秒** |
- * | `transfer-adapters` 本地 stat | `size:秒` | **秒** |
- * | `local-backend` stat | `size:毫秒` | 毫秒 |
- *
- * 秒级意味着同一秒内的两次写入令牌完全相同——版本守卫拿「读到的」和「写之前的」比对，比对不出来
- * 就等于**放过了一次真实修改**。代理侧（Tier 2）撞上的是同一类缺陷，修法也一样（审计 0086）。
- *
- * ## 为什么加 ino
- *
- * 原子写走临时文件 + rename，必然换一个 inode。这是与 mtime 精度无关的、决定性的「换过文件」信号。
- *
- * ## 为什么保留 mtimeMs 的小数
- *
- * Node 的 `Stats.mtimeMs` 是浮点，小数部分带亚毫秒信息，`Math.floor` 会把它丢掉。当前纪元的纳秒数
- * 超出双精度能精确表示的范围，所以这里实际拿到的是微秒级精度——够用，且不必为此把整条 stat 调用
- * 改成 `bigint: true`（那会让所有数值字段变成 BigInt，波及面远大于收益）。
- *
- * @module dsh-over-ssh/infra/backend/local-version
- */
-/** The subset of `fs.Stats` this token needs; structural so tests can pass a literal. */
-export interface LocalVersionInput {
-    readonly size: number;
-    readonly mtimeMs: number;
-    /** File index. `undefined` (or 0) degrades the token to `size:mtimeMs`. */
-    readonly ino?: number | undefined;
-}
-/**
- * Build the token for a local path.
- *
- * @param info - Anything with size, mtime and (ideally) inode.
- * @returns The opaque version string.
- */
-export declare function localVersion(info: LocalVersionInput): string;
-//# sourceMappingURL=local-version.d.ts.map

package/lib/types/src/host/infra/backend/platform-local-backend.d.ts

@@ -1,89 +0,0 @@
-/**
- * 本地世界作为一个 {@link Backend}：**写入**与**监听**交给平台的原版 `fs-sandbox`（住在本插件的私有域里），
- * 其余留在 {@link LocalBackend}。
- *
- * ## 为什么只交写入与监听
- *
- * 沙箱围栏只作用于写入——读没有围栏可拿。把读也转过去只有代价：平台 seam 是「先 `resolve` 再操作」的
- * 形状，而 `resolve` 要做规范化与祖先包含检查，我们分块读大文件时每块都要多做一次，属于纯亏。
- *
- * 写入不一样：`fs-sandbox` 的 `workspace-write` / `read-only` 判断是平台自己的语义，由它执行就不必在本
- * 插件里维护第二份。这是这个适配器要换来的第一件东西。
- *
- * 监听同理：平台的 `FileSystem.watch()` **本来就是 chokidar 实现**（`SandboxedFileSystem extends
- * LocalFileSystem`），而本插件的 `LocalBackend` 没有监听能力。接管 `ctx.fs` 之后如果继续对本地根抛
- * `FS_IO_ERROR`，连本地文件的变更通知都会消失（`dsh-api-workspace-files` 会得到
- * `workspace-file/watch-unsupported`）——这是接管造成的回退。委托给平台是唯一不重复实现 chokidar 的
- * 做法，而且文件目标的"监听父目录并过滤同名条目"语义在平台实现里已经写好，照抄一遍只会漂移。
- *
- * ## 为什么其余不交
- *
- * 平台的 `ctx.fs` 比本插件的 {@link Backend} **窄**：没有 `mkdir` / `rename` / `remove` / `chmod`，
- * `FsInfo` 与 `FsDirEntry` 也不带 `mtime`。文件树的「新建目录 / 重命名 / 删除」和版本令牌都依赖这些，
- * 所以它们继续走 {@link LocalBackend}——平台从来没有这些操作，谈不上「重复实现」。
- *
- * @module dsh-over-ssh/infra/backend/platform-local-backend
- */
-import type { FileSystem } from '@deepseek-ai/dsh-fs';
-import type { Backend, BackendEntry, BackendRead, BackendSandboxMode, BackendStat, BackendText, BackendWrite } from '../../app/backend.ts';
-/** Everything {@link PlatformLocalBackend} needs; each field is injected so tests need no platform. */
-export interface PlatformLocalBackendOptions {
-    /** Stable id, also the target-key namespace. */
-    readonly id: string;
-    /** The platform's stock filesystem, captured from this plugin's private realm. */
-    readonly fs: FileSystem;
-    /** The backend that keeps the operations and metadata the platform seam does not expose. */
-    readonly fallback: Backend;
-}
-/**
- * A local root whose writes are fenced by the platform's own sandbox.
- *
- * Reads, listing, metadata and the mutation primitives stay on the fallback: see the module comment for why
- * each of those is deliberately **not** delegated.
- */
-export declare class PlatformLocalBackend implements Backend {
-    #private;
-    readonly id: string;
-    /** The platform's `FileSystem.watch` (chokidar) is the watcher this backend serves. */
-    readonly watches = true;
-    constructor(options: PlatformLocalBackendOptions);
-    /**
-     * The platform's mode wins: it is the thing actually enforcing the fence now.
-     *
-     * Falling back keeps the provider's own gate meaningful when the platform declines to report a mode.
-     */
-    get sandboxMode(): BackendSandboxMode | undefined;
-    stat(absolute: string, signal?: AbortSignal): Promise<BackendStat>;
-    lstat(absolute: string, signal?: AbortSignal): Promise<BackendStat>;
-    list(absolute: string, signal?: AbortSignal): Promise<readonly BackendEntry[]>;
-    readBytes(absolute: string, maxBytes: number, signal?: AbortSignal): Promise<BackendRead>;
-    readText(absolute: string, maxBytes: number, signal?: AbortSignal): Promise<BackendText>;
-    /**
-     * Delegate to the platform's own watcher.
-     *
-     * `watch` is part of `FileSystem` (the base class implements it with chokidar and the sandbox does not
-     * override it), so this backend does not reimplement anything — it only maps "absolute path" to the
-     * platform's target, exactly like {@link writeText} does. The platform's implementation already handles the
-     * file-vs-directory difference (a file target watches its parent with a path filter).
-     */
-    watch(absolute: string, changed: (error?: Error) => void, signal: AbortSignal): Promise<() => Promise<void>>;
-    /** Fenced by the platform. An empty `expectedVersion` means "no guard", as the backend contract says. */
-    writeText(absolute: string, text: string, expectedVersion: string | undefined, signal?: AbortSignal): Promise<BackendWrite>;
-    /** Fenced by the platform; the three-state semantics are the platform's, which is what the core expects. */
-    editText(absolute: string, oldString: string, newString: string, replaceAll: boolean, expectedVersion: string | undefined, signal?: AbortSignal): Promise<BackendWrite & {
-        readonly replaced: number;
-    }>;
-    mkdir(absolute: string, options: {
-        readonly recursive: boolean;
-    }, signal?: AbortSignal): Promise<void>;
-    rename(from: string, to: string, options: {
-        readonly createParents: boolean;
-    }, signal?: AbortSignal): Promise<void>;
-    remove(absolute: string, options: {
-        readonly recursive: boolean;
-    }, signal?: AbortSignal): Promise<void>;
-    chmod(absolute: string, mode: string, signal?: AbortSignal): Promise<void>;
-    processPath(absolute: string): string | undefined;
-    fileUrl(absolute: string): string;
-}
-//# sourceMappingURL=platform-local-backend.d.ts.map