dsh-over-ssh 0.1.0 → 0.2.0

package/lib/types/src/host/app/recycle-bin/recycle-bin-world.d.ts

@@ -1,38 +0,0 @@
-/**
- * 回收站服务的**世界原语**：索引读写、按根取 IO、stat、根查找。
- *
- * 从 `recycle-bin-service.ts` 的工厂里抽出（审计 0076）：只依赖 deps，不碰撤销栈与业务判断。
- *
- * @module dsh-over-ssh/app/recycle-bin-world
- */
-import type { BackendStat } from '../backend.ts';
-import { type RecycleBinEntry, type RecycleBinEntryId } from '../../domain/transfer/recycle-bin.ts';
-import { type RootRef } from '../../domain/roots/root.ts';
-import type { RecycleBinServiceDeps, RecycleBinWorldIo, RecycleBinRemovalOptions } from './recycle-bin-contract.ts';
-export type IndexState = {
-    readonly path: string;
-    readonly entries: readonly RecycleBinEntry[];
-    readonly skipped: number;
-};
-export declare function createBinWorld(deps: RecycleBinServiceDeps): {
-    describe: (error: unknown) => string;
-    abortIfRequested: (signal: AbortSignal | undefined) => void;
-    ioFor: (root: RootRef) => RecycleBinWorldIo;
-    statFor: (root: RootRef, path: string, signal: AbortSignal | undefined) => Promise<BackendStat>;
-    binRootOf: (root: RootRef) => string;
-    readIndex: (root: RootRef, signal: AbortSignal | undefined) => Promise<IndexState>;
-    writeIndex: (root: RootRef, path: string, entries: readonly RecycleBinEntry[], signal: AbortSignal | undefined) => Promise<void>;
-    withIndexLock: <T>(key: string, operation: () => Promise<T>) => Promise<T>;
-    removalOptions: (recursive: boolean, signal: AbortSignal | undefined) => RecycleBinRemovalOptions;
-    knownRoots: () => readonly RootRef[];
-    resolveRootOf: (key: string) => RootRef;
-    findEntry: (id: RecycleBinEntryId, signal: AbortSignal | undefined) => Promise<{
-        readonly root: RootRef;
-        readonly entry: RecycleBinEntry;
-    } | undefined>;
-    contains: (root: RootRef, base: string, candidate: string) => boolean;
-    entryDirOf: (entry: RecycleBinEntry) => string;
-    pruneEntryDir: (root: RootRef, dir: string, signal: AbortSignal | undefined) => Promise<boolean>;
-};
-export type BinWorld = ReturnType<typeof createBinWorld>;
-//# sourceMappingURL=recycle-bin-world.d.ts.map

package/lib/types/src/host/app/recycle-bin-contract.d.ts

@@ -1,215 +0,0 @@
-/**
- * 回收站服务的**契约**：依赖注入形状、目标/结果类型、索引状态。
- *
- * 从 `recycle-bin-service.ts` 抽出（审计 0076）。抽出的直接原因不是"文件太长"，而是
- * 世界原语模块需要这些类型：留在 service 里会形成 `world → service`（type）与
- * `service → world`（value）的环，架构测试会红。契约独立后方向单一。
- *
- * @module dsh-remote-workspace/app/recycle-bin-contract
- */
-import type { BackendEntry, BackendStat } from './backend.ts';
-import { type RecycleBinEntry, type RecycleBinEntryId } from '../domain/recycle-bin.ts';
-import { type RootRef } from '../domain/root.ts';
-export interface RecycleBinRemovalOptions {
-    /** Whether the target is a directory that must be removed with its content. */
-    readonly recursive: boolean;
-    /** Caller cancellation. */
-    readonly signal?: AbortSignal;
-}
-/** The mutating primitives of one execution world, shaped like the remote group. */
-export interface RecycleBinWorldIo {
-    /**
-     * Move (rename) a path.
-     *
-     * Contract: the implementation must create a missing destination parent directory (equivalent to
-     * `mkdir -p` + `rename`). A cross-device move that cannot be done by rename must **fail loudly**; silently
-     * degrading to copy-then-delete would break the "don't delete until it is in the bin" guarantee.
-     */
-    readonly move: (from: string, to: string, signal?: AbortSignal) => Promise<void>;
-    /** Physically delete a path. */
-    readonly remove: (path: string, options: RecycleBinRemovalOptions) => Promise<void>;
-    /** List one directory. */
-    readonly list: (dir: string, signal?: AbortSignal) => Promise<readonly BackendEntry[]>;
-    /** Read a text file (the index). */
-    readonly readText: (path: string, signal?: AbortSignal) => Promise<string>;
-    /** Write a text file as UTF-8 **without BOM** (the index). */
-    readonly writeText: (path: string, text: string, signal?: AbortSignal) => Promise<void>;
-}
-/** Everything {@link createRecycleBinService} needs; each field is injected so tests need no host. */
-export interface RecycleBinServiceDeps {
-    /** Bin root directory for one root; a deployment setting, never hardcoded here. */
-    readonly binRootFor: (root: RootRef) => string;
-    /** Find a root by its `rootKey()`; `undefined` means the root is no longer registered. */
-    readonly resolveRoot: (key: string) => RootRef | undefined;
-    /** `stat` in the local world. */
-    readonly statLocal: (path: string, signal?: AbortSignal) => Promise<BackendStat>;
-    /** `stat` in the remote world. */
-    readonly statRemote: (path: string, signal?: AbortSignal) => Promise<BackendStat>;
-    /** Move primitive of the remote world. */
-    readonly moveRemote: (from: string, to: string, signal?: AbortSignal) => Promise<void>;
-    /** Remove primitive of the remote world. */
-    readonly removeRemote: (path: string, options: RecycleBinRemovalOptions) => Promise<void>;
-    /** List primitive of the remote world. */
-    readonly listRemote: (dir: string, signal?: AbortSignal) => Promise<readonly BackendEntry[]>;
-    /** Index read primitive of the remote world. */
-    readonly readTextRemote: (path: string, signal?: AbortSignal) => Promise<string>;
-    /** Index write primitive of the remote world (UTF-8, no BOM). */
-    readonly writeTextRemote: (path: string, text: string, signal?: AbortSignal) => Promise<void>;
-    /** Clock, injected so a test can pin "now". */
-    readonly now: () => number;
-    /** Undo depth from configuration (a non-positive value keeps no history). */
-    readonly undoDepth: number;
-    /** Roots whose bins exist, so `sweep()` can walk them all. */
-    readonly knownRoots: () => readonly RootRef[];
-    /**
-     * Local-world mutators.
-     *
-     * Optional: a service built for remote work omits it, and touching a local target then fails with
-     * `REMOTE_UNSUPPORTED` instead of misapplying the remote primitives to a local path.
-     */
-    readonly localIo?: RecycleBinWorldIo;
-}
-/** One deletion target: a root plus a path inside it. */
-export interface RecycleBinTarget {
-    readonly root: RootRef;
-    /** Absolute path in the root's own spelling. */
-    readonly path: string;
-}
-/** A bin view scope: one root, optionally narrowed to targets deleted under one directory. */
-export interface RecycleBinScope {
-    readonly root: RootRef;
-    /** Optional directory prefix, matched per path segment. */
-    readonly path?: string;
-}
-/** How {@link RecycleBinService.discard} removes a target. */
-export type DiscardMode = 'permanent' | 'recycle';
-/** Options for {@link RecycleBinService.discard}. */
-export interface DiscardOptions {
-    readonly mode: DiscardMode;
-    readonly signal?: AbortSignal;
-}
-/** Result of a discard. */
-export interface DiscardResult {
-    readonly mode: DiscardMode;
-    /** The bin entry in `recycle` mode; `undefined` for `permanent`. */
-    readonly entry: RecycleBinEntry | undefined;
-    /** Whether the content can still be recovered. **Always `false` for `permanent`.** */
-    readonly recoverable: boolean;
-    /** Post-operation confirmation: the original path is gone. */
-    readonly verified: boolean;
-    /** Human-facing note, mandatory for an irreversible delete. */
-    readonly warning: string | undefined;
-}
-/** What a bin actually holds for one root. */
-export interface RecycleBinListing {
-    readonly entries: readonly RecycleBinEntry[];
-    /** Ids the index knows but the bin directory no longer contains. */
-    readonly missing: readonly RecycleBinEntryId[];
-    /** Directory names in the bin that no index record claims. */
-    readonly orphans: readonly string[];
-    /** Index records that were unusable and skipped. */
-    readonly skipped: number;
-}
-/** Result of a restore. */
-export interface RestoreResult {
-    readonly entry: RecycleBinEntry;
-    readonly restoredPath: string;
-    readonly verified: boolean;
-}
-/** Result of a physical delete from the bin. */
-export interface PurgeResult {
-    readonly id: RecycleBinEntryId;
-    readonly sizeBytes: number;
-    /** Always true when the call returns; a failed delete throws instead. */
-    readonly purged: boolean;
-    readonly warning: string;
-}
-/** Options for `list`, `restore`, `purge`, `undo` and `redo`. */
-export interface OperationOptions {
-    readonly signal?: AbortSignal;
-}
-/** Result of an undo or redo step. */
-export interface UndoResult {
-    /** The action that was executed. */
-    readonly action: 'discard' | 'restore';
-    readonly entry: RecycleBinEntry;
-    /** Human-facing description of what happened. */
-    readonly message: string;
-}
-/** Retention limits for one sweep; all optional. */
-export interface SweepOptions {
-    /** Keep at most this many entries per bin; non-positive/absent = unlimited. */
-    readonly maxEntries?: number;
-    /** Keep at most this many bytes per bin; non-positive/absent = unlimited. */
-    readonly maxBytes?: number;
-    /** Keep entries at most this old; non-positive/absent = unlimited. */
-    readonly maxAgeMs?: number;
-    readonly signal?: AbortSignal;
-}
-/** One entry physically removed by a sweep. */
-export interface SweepPurge {
-    readonly rootKey: string;
-    readonly id: RecycleBinEntryId;
-    readonly sizeBytes: number;
-    readonly dimension: 'age' | 'count' | 'bytes';
-}
-/** One entry a sweep could not delete; the sweep continues with the rest. */
-export interface SweepFailure {
-    readonly rootKey: string;
-    readonly id?: RecycleBinEntryId;
-    readonly message: string;
-}
-/** Per-root summary of a sweep. */
-export interface SweepRootReport {
-    readonly rootKey: string;
-    readonly considered: number;
-    readonly purged: readonly RecycleBinEntryId[];
-    readonly kept: readonly RecycleBinEntryId[];
-    readonly reasons: readonly {
-        readonly id: RecycleBinEntryId;
-        readonly dimension: 'age' | 'count' | 'bytes';
-    }[];
-}
-/** Outcome of a sweep. */
-export interface SweepReport {
-    readonly purged: readonly SweepPurge[];
-    readonly roots: readonly SweepRootReport[];
-    readonly failures: readonly SweepFailure[];
-    /** `false` when no dimension was limited: nothing was touched (an unconfigured 0 must not empty a bin). */
-    readonly policyApplied: boolean;
-}
-/** Read-only undo state, for a UI that needs to enable or disable the buttons. */
-export interface RecycleBinHistory {
-    readonly canUndo: boolean;
-    readonly canRedo: boolean;
-    readonly undo: readonly {
-        readonly kind: string;
-        readonly id: string;
-    }[];
-    readonly redo: readonly {
-        readonly kind: string;
-        readonly id: string;
-    }[];
-    readonly dropped: number;
-    readonly undoDepth: number;
-}
-/** The service surface. */
-export interface RecycleBinService {
-    /** Delete a target permanently or into the recycle bin. */
-    discard(target: RecycleBinTarget, options: DiscardOptions): Promise<DiscardResult>;
-    /** List one bin, reconciled against the directory that actually exists. */
-    list(scope: RecycleBinScope, options?: OperationOptions): Promise<RecycleBinListing>;
-    /** Restore one entry to its original path. */
-    restore(id: RecycleBinEntryId, options?: OperationOptions): Promise<RestoreResult>;
-    /** Physically delete one entry from the bin. */
-    purge(id: RecycleBinEntryId, options?: OperationOptions): Promise<PurgeResult>;
-    /** Apply retention limits to every known bin. */
-    sweep(options: SweepOptions): Promise<SweepReport>;
-    /** Undo the newest operation. */
-    undo(options?: OperationOptions): Promise<UndoResult>;
-    /** Re-apply the newest undone operation. */
-    redo(options?: OperationOptions): Promise<UndoResult>;
-    /** Current undo/redo state. */
-    history(): RecycleBinHistory;
-}
-//# sourceMappingURL=recycle-bin-contract.d.ts.map

package/lib/types/src/host/app/recycle-bin-move.d.ts

@@ -1,18 +0,0 @@
-/**
- * 回收站服务的**移动/恢复族**：把条目搬进 bin、搬回原处，含"移动后确认"与"索引写失败回滚"。
- *
- * 从 `recycle-bin-service.ts` 的工厂里抽出（审计 0076）。只依赖世界原语，不碰撤销栈。
- *
- * @module dsh-remote-workspace/app/recycle-bin-move
- */
-import { type RecycleBinEntry } from '../domain/recycle-bin.ts';
-import { type RootRef } from '../domain/root.ts';
-import type { BinWorld } from './recycle-bin-world.ts';
-export declare function createBinMove(world: BinWorld): {
-    tryMove: (root: RootRef, from: string, to: string, signal: AbortSignal | undefined) => Promise<boolean>;
-    moveOrReport: (root: RootRef, from: string, to: string, signal: AbortSignal | undefined, reason: string) => Promise<void>;
-    confirmInBin: (root: RootRef, entry: RecycleBinEntry, signal: AbortSignal | undefined) => Promise<void>;
-    moveIntoBin: (root: RootRef, entry: RecycleBinEntry, signal: AbortSignal | undefined) => Promise<void>;
-    restoreEntry: (root: RootRef, entry: RecycleBinEntry, signal: AbortSignal | undefined) => Promise<void>;
-};
-//# sourceMappingURL=recycle-bin-move.d.ts.map

package/lib/types/src/host/app/recycle-bin-service.d.ts

@@ -1,45 +0,0 @@
-/**
- * The recycle-bin service: the domain's pure decisions wired to injected I/O primitives.
- *
- * The seam is deliberate (AGENTS.md 红线 3): every path that touches a real filesystem or a real SSH
- * connection arrives as a function, so this module is testable offline and a test can inject a move that fails.
- *
- * Two contracts matter more than the rest:
- *
- *  1. **Move first, then confirm.** In `recycle` mode a success is reported only after `stat` shows the entry
- *     inside the bin **and** the original path gone. A move that throws is confirmed before anything is
- *     claimed: if the move actually landed (a lost response) it counts as success, otherwise the call fails
- *     and nothing is recorded — "deleted but not in the bin" must never be reported as success.
- *  2. **The index write is never swallowed.** If the index cannot be written after a successful move, the move
- *     is rolled back and the failure is reported; a physical delete has no rollback, so that case is reported
- *     with `purged: true, indexStale: true` instead of being hidden.
- *
- * Other decisions worth knowing:
- *
- *  - A `permanent` discard is irreversible by construction and says so in its result (`recoverable: false`),
- *    and its undo record is refused as `irreversible`.
- *  - Restoring onto an occupied original path is **refused** (`TRANSFER_CONFLICT`, with the informational
- *    `suggestedPath` in `details`); this module never silently restores to a different name.
- *  - `*Remote` primitives are the **remote world's** mutators. A local root additionally needs `localIo`; when it
- *    is missing the call fails with `REMOTE_UNSUPPORTED` rather than reusing remote primitives on local paths.
- *  - Every destructive call takes an `AbortSignal`, propagated to every injected primitive.
- *  - Error codes are reused from the existing table (no new code is registered): `TRASH_NOT_FOUND` (missing
- *    entry, unreadable index), `REMOTE_NOT_FOUND` (target gone), `TRANSFER_CONFLICT` (occupied restore path),
- *    `ROOT_OUTSIDE` (symlink target refused), `ROOT_AMBIGUOUS` (one id in two bins), `REMOTE_UNSUPPORTED`
- *    (local root without local primitives), `REMOTE_COMMAND_FAILED` (an operation that could not be confirmed),
- *    `ROOT_INVALID` (unusable configuration/input), `CANCELLED` (aborted signal).
- *
- * @module dsh-remote-workspace/integration/recycle-bin-service
- */
-import type { RecycleBinServiceDeps, RecycleBinService } from './recycle-bin-contract.ts';
-export * from './recycle-bin-contract.ts';
-/** Removal options for one physical delete. */
-export * from './recycle-bin-contract.ts';
-/**
- * Build the service.
- *
- * @param deps - injected I/O, clock, configuration and root lookup.
- * @returns a {@link RecycleBinService}; its undo stack is per-instance, in memory and not persisted.
- */
-export declare function createRecycleBinService(deps: RecycleBinServiceDeps): RecycleBinService;
-//# sourceMappingURL=recycle-bin-service.d.ts.map

package/lib/types/src/host/app/recycle-bin-world.d.ts

@@ -1,35 +0,0 @@
-/**
- * 回收站服务的**世界原语**：索引读写、按根取 IO、stat、根查找。
- *
- * 从 `recycle-bin-service.ts` 的工厂里抽出（审计 0076）：只依赖 deps，不碰撤销栈与业务判断。
- *
- * @module dsh-remote-workspace/app/recycle-bin-world
- */
-import type { BackendStat } from './backend.ts';
-import { type RecycleBinEntry, type RecycleBinEntryId } from '../domain/recycle-bin.ts';
-import { type RootRef } from '../domain/root.ts';
-import type { RecycleBinServiceDeps, RecycleBinWorldIo, RecycleBinRemovalOptions } from './recycle-bin-contract.ts';
-export type IndexState = {
-    readonly path: string;
-    readonly entries: readonly RecycleBinEntry[];
-    readonly skipped: number;
-};
-export declare function createBinWorld(deps: RecycleBinServiceDeps): {
-    describe: (error: unknown) => string;
-    abortIfRequested: (signal: AbortSignal | undefined) => void;
-    ioFor: (root: RootRef) => RecycleBinWorldIo;
-    statFor: (root: RootRef, path: string, signal: AbortSignal | undefined) => Promise<BackendStat>;
-    binRootOf: (root: RootRef) => string;
-    readIndex: (root: RootRef, signal: AbortSignal | undefined) => Promise<IndexState>;
-    writeIndex: (root: RootRef, path: string, entries: readonly RecycleBinEntry[], signal: AbortSignal | undefined) => Promise<void>;
-    removalOptions: (recursive: boolean, signal: AbortSignal | undefined) => RecycleBinRemovalOptions;
-    knownRoots: () => readonly RootRef[];
-    resolveRootOf: (key: string) => RootRef;
-    findEntry: (id: RecycleBinEntryId, signal: AbortSignal | undefined) => Promise<{
-        readonly root: RootRef;
-        readonly entry: RecycleBinEntry;
-    } | undefined>;
-    contains: (root: RootRef, base: string, candidate: string) => boolean;
-};
-export type BinWorld = ReturnType<typeof createBinWorld>;
-//# sourceMappingURL=recycle-bin-world.d.ts.map

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

@@ -1,49 +0,0 @@
-/**
- * roots-api-connections
- *
- * 连接的 6 个 action：ssh-config 发现/导入、增删改连接、连接自检。
- *
- * 从 `roots-api-roots.ts` 拆出（审计 0077）：根与连接是两套独立的状态机，
- * 原先共处一个 switch，各自的辅助函数也互不相干。
- *
- * @module dsh-over-ssh/app/roots-api-connections
- */
-import type { RootsApiRequest, RootsApiResponse, RootsApiDeps } from './roots-api-contract.ts';
-export declare function handleConnectionActions(action: string, body: Record<string, unknown>, req: RootsApiRequest, res: RootsApiResponse, deps: RootsApiDeps): Promise<boolean>;
-/**
- * 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;
-}
-//# sourceMappingURL=roots-api-connections.d.ts.map