dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,337 @@
+/**
+ * Recycle bin: entry model, on-disk layout, retention policy and the undo stack — pure logic only.
+ *
+ * Why the domain layer (AGENTS.md 红线 2): entry ids, the bin path layout, the retention decision and the
+ * undo state machine are all decisions that can be verified offline in milliseconds. Every real filesystem
+ * or SSH interaction stays behind the injected seam of
+ * [`integration/recycle-bin-service.ts`](../integration/recycle-bin-service.ts).
+ *
+ * Contract notes:
+ *
+ *  - **Deterministic ids.** The same inputs (root key, original path, deletion instant, delete ordinal for
+ *    that path) always yield the same id. Two deletes of the same path at the same millisecond are told
+ *    apart by `sequence`, and {@link allocateRecycleBinId} breaks genuine hash collisions deterministically.
+ *  - **Layout.** `<binRoot>/<id>/<original basename>`. The id is unique, so same-named files never collide;
+ *    keeping the original basename in the bin means a restore does not rename anything. Everything else a
+ *    restore needs (root key, original absolute path) lives on the entry, which the service persists in an
+ *    index file next to the bins.
+ *  - **Restore conflicts.** When the original path is occupied, {@link planRestore} reports `blocked` plus an
+ *    informational suffix candidate; the caller must **refuse**, never silently write to a different name.
+ *  - **Retention.** `maxEntries` / `maxBytes` / `maxAgeMs` are applied per dimension: a **non-positive value
+ *    means "no limit"** for that dimension (0 and negatives never wipe anything — deliberate, because a
+ *    misconfigured 0 must not empty the bin). Oversized bins shed **oldest first**, with the id as a stable
+ *    tie-break, so the same input always produces the same decision.
+ *  - **Undo.** A stack. The inverse of `discard` is `restore` (and vice versa, which is what makes the undo
+ *    redoable); `purge` is a physical delete and is therefore **explicitly irreversible**.
+ *
+ * @module dsh-remote-workspace/domain/recycle-bin
+ */
+/**
+ * Opaque identity of one recycle-bin entry.
+ *
+ * Branded on purpose: an id is the directory name inside the bin and a handle the UI holds across calls, so
+ * it must not be confused with a path or a session id.
+ */
+export type RecycleBinEntryId = string & {
+    readonly __recycleBinEntryId: 'RecycleBinEntryId';
+};
+/** Which world a target lives in; same vocabulary as `RootRef.location`. */
+export type RecycleBinLocation = 'local' | 'remote';
+/** Name of the index file inside a bin root. */
+export declare const RECYCLE_BIN_INDEX_FILE = "index.json";
+/** Version stamped into the index file; a different version is a hard parse failure. */
+export declare const RECYCLE_BIN_INDEX_VERSION = 1;
+/** Inputs that determine an entry id. */
+export interface RecycleBinIdInput {
+    /** Stable root key (`rootKey()`); scopes ids to one root. */
+    readonly rootKey: string;
+    /** Absolute path of the deleted target, in this repository's normalized spelling. */
+    readonly originalPath: string;
+    /** Deletion instant in milliseconds since the epoch. */
+    readonly deletedAtMs: number;
+    /** Which delete of that same path this is, 1-based. */
+    readonly sequence: number;
+}
+/** One recycle-bin entry: everything a restore needs, plus the facts the bin view shows. */
+export interface RecycleBinEntry {
+    readonly id: RecycleBinEntryId;
+    /** Root key (`rootKey()`) the target was deleted from. */
+    readonly rootKey: string;
+    readonly location: RecycleBinLocation;
+    /** Original absolute path, normalized (local: `/` separators; remote: POSIX). */
+    readonly originalPath: string;
+    /** Final segment of {@link originalPath}; the bin keeps this name. */
+    readonly originalName: string;
+    /** Bin root directory (`binRootFor(root)`). */
+    readonly binRoot: string;
+    /** Actual location inside the bin: `<binRoot>/<id>/<originalName>`. */
+    readonly binPath: string;
+    readonly deletedAtMs: number;
+    /** Bytes reported by the pre-delete `stat`; for directories this is the directory entry, not a sum. */
+    readonly sizeBytes: number;
+    readonly isDirectory: boolean;
+    /** 1-based ordinal of this delete among deletes of the same path. */
+    readonly sequence: number;
+}
+/** Input for {@link makeRecycleBinEntry}; {@link RecycleBinIdInput} plus the id and the observed facts. */
+export interface MakeRecycleBinEntryInput extends RecycleBinIdInput {
+    readonly id: RecycleBinEntryId;
+    readonly location: RecycleBinLocation;
+    readonly binRoot: string;
+    readonly sizeBytes: number;
+    readonly isDirectory: boolean;
+}
+/**
+ * Normalize a deletion target into the spelling the rest of the repository uses.
+ *
+ * Local targets go through `normalizeLocalPath` (separators to `/`, case preserved), remote targets through
+ * `normalizeRemotePath` (POSIX, absolute). A filesystem root is rejected because it can never be a target.
+ *
+ * @param path - target path in either separator spelling.
+ * @param location - which world the path belongs to.
+ * @returns the normalized absolute path.
+ * @throws SshDevError `ROOT_INVALID` when the path is empty, relative, or a filesystem root.
+ */
+export declare function normalizeRecycleTarget(path: string, location: RecycleBinLocation): string;
+/**
+ * The deterministic id for one {@link RecycleBinIdInput}.
+ *
+ * Same input → same id (a test can therefore pin ids). Different inputs collide only if FNV-1a collides,
+ * which {@link allocateRecycleBinId} handles.
+ *
+ * @param input - root key, original path, deletion instant and delete ordinal.
+ * @returns a filesystem-safe id of the form `rb-<8 hex>`.
+ */
+export declare function makeRecycleBinEntryId(input: RecycleBinIdInput): RecycleBinEntryId;
+/**
+ * Allocate an id that is not already taken by `existing`.
+ *
+ * The first candidate is {@link makeRecycleBinEntryId}; on collision the suffix `-2`, `-3`, … is appended.
+ * The loop is bounded by the number of live entries, because every candidate it rejects is one of them.
+ *
+ * @param existing - ids already present in the bin index.
+ * @param input - id material.
+ * @returns an id not present in `existing`.
+ */
+export declare function allocateRecycleBinId(existing: Iterable<string>, input: RecycleBinIdInput): RecycleBinEntryId;
+/**
+ * Build one entry, validating its inputs and computing the bin layout.
+ *
+ * @param input - id, root, worlds, observed `stat` facts.
+ * @returns the entry, with `binPath` = `<binRoot>/<id>/<originalName>`.
+ * @throws SshDevError `ROOT_INVALID` when a path, the bin root, or a numeric field is unusable.
+ */
+export declare function makeRecycleBinEntry(input: MakeRecycleBinEntryInput): RecycleBinEntry;
+/**
+ * Join segments under an absolute base with `/`.
+ *
+ * Both worlds use this spelling (`local` roots are stored normalized by `normalizeLocalPath`, remote ones are
+ * POSIX), so the bin layout is spelled the same way everywhere. A drive-rooted base (`D:`) keeps its slash.
+ *
+ * @param base - absolute base directory.
+ * @param segments - segments to append.
+ * @returns the joined path.
+ */
+export declare function joinUnderPath(base: string, ...segments: readonly string[]): string;
+/** A restore decision: either the move is ready, or the original path is occupied and must not be reused. */
+export type RestorePlan = {
+    readonly kind: 'ready';
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly kind: 'blocked';
+    readonly to: string;
+    readonly reason: 'occupied';
+    readonly suggestedPath: string;
+};
+/**
+ * Decide how to restore one entry.
+ *
+ * Policy: **an occupied original path is refused, never renamed silently.** `suggestedPath` is returned so a
+ * UI can *offer* an alternative, but no code path in this module moves a target to it.
+ *
+ * @param entry - entry to restore.
+ * @param options - `occupied` is the caller's `stat` of `entry.originalPath`.
+ * @returns the plan.
+ */
+export declare function planRestore(entry: RecycleBinEntry, options: {
+    readonly occupied: boolean;
+}): RestorePlan;
+/** Retention policy. A non-positive value means "no limit" for that dimension. */
+export interface RecycleBinPolicy {
+    /** Keep at most this many entries; non-positive = unlimited. */
+    readonly maxEntries: number;
+    /** Keep at most this many bytes (sum of entry sizes); non-positive = unlimited. */
+    readonly maxBytes: number;
+    /** Keep entries at most this old, in milliseconds; non-positive = unlimited. */
+    readonly maxAgeMs: number;
+}
+/** Neutral element: no dimension is limited, therefore nothing is ever swept with it. */
+export declare const NO_RECYCLE_BIN_LIMITS: RecycleBinPolicy;
+/** Which dimension caused one entry to be swept. */
+export type SweepDimension = 'age' | 'count' | 'bytes';
+/** Why one entry is scheduled for physical deletion. */
+export interface SweepReason {
+    readonly id: RecycleBinEntryId;
+    readonly dimension: SweepDimension;
+    readonly detail: string;
+}
+/** The pure retention decision for one bin. */
+export interface SweepDecision {
+    /** Ids to delete physically, oldest first. */
+    readonly purge: readonly RecycleBinEntryId[];
+    /** Ids to keep, oldest first. */
+    readonly keep: readonly RecycleBinEntryId[];
+    /** One reason per purged id, in the same order. */
+    readonly reasons: readonly SweepReason[];
+    /** Entries and bytes left after applying the decision. */
+    readonly remainingEntries: number;
+    readonly remainingBytes: number;
+}
+/**
+ * Apply a retention policy to one bin.
+ *
+ * Rules, in this order (all of them deterministic: entries are ordered oldest first with the id as tie-break):
+ *
+ *  1. `maxAgeMs > 0`: purge everything older than the limit. An entry exactly **at** the limit is kept, and a
+ *     negative age (clock skew, future timestamp) is never purged.
+ *  2. `maxBytes > 0`: walk the survivors oldest first and purge until the remaining sum is within the limit.
+ *     A single entry larger than the whole budget is purged too — otherwise the budget would be meaningless.
+ *  3. `maxEntries > 0`: purge the oldest survivors until the count is within the limit.
+ *
+ * @param entries - entries of one bin.
+ * @param policy - limits; non-positive values are ignored.
+ * @param nowMs - current instant in milliseconds since the epoch.
+ * @returns the decision.
+ */
+export declare function decideSweep(entries: readonly RecycleBinEntry[], policy: RecycleBinPolicy, nowMs: number): SweepDecision;
+/** What one committed operation did; the unit of the undo stack. */
+export type OperationKind = 'discard' | 'restore' | 'purge';
+/** One committed operation. */
+export interface RecycleBinOperation {
+    readonly kind: OperationKind;
+    /** Entry the operation acted on; `undefined` for a permanent delete, which has no bin entry. */
+    readonly entry: RecycleBinEntry | undefined;
+    /** Entry id, or a synthesized id for a permanent delete. */
+    readonly id: RecycleBinEntryId;
+    readonly atMs: number;
+}
+/** Stack-shaped undo state: `undo` is the history, `redo` what was undone and can be re-applied. */
+export interface UndoStack {
+    readonly undo: readonly RecycleBinOperation[];
+    readonly redo: readonly RecycleBinOperation[];
+    /** Operations dropped for exceeding the depth limit; explains "too old to undo". */
+    readonly dropped: number;
+}
+/** Fresh state with no history. */
+export declare const EMPTY_UNDO_STACK: UndoStack;
+/** Why an undo/redo step was refused. */
+export type UndoRejectionReason = 'nothing-to-undo' | 'nothing-to-redo' | 'entry-missing' | 'irreversible';
+/** The world state an undo decision is validated against. */
+export interface UndoContext {
+    /**
+     * Ids **currently present in the recycle bin**.
+     *
+     * One rule covers both directions: a `restore` action needs the bin copy (the id must be listed), and a
+     * `discard` action needs the file to be back at its original path (the id must not be listed).
+     */
+    readonly liveIds: readonly RecycleBinEntryId[];
+}
+/** A step to execute: move the entry out of the bin, or back into it. */
+export interface UndoAction {
+    readonly kind: 'restore' | 'discard';
+    readonly operation: RecycleBinOperation;
+    readonly entry: RecycleBinEntry;
+}
+/** Why a step is not executable. */
+export interface UndoRejection {
+    readonly reason: UndoRejectionReason;
+    readonly message: string;
+    readonly operation: RecycleBinOperation | undefined;
+}
+/** Outcome of one undo/redo step: either an action to run, or a rejection. */
+export interface UndoOutcome {
+    /** State after the step; a rejected record is dropped from the stack (it can never succeed). */
+    readonly stack: UndoStack;
+    readonly action: UndoAction | undefined;
+    readonly rejection: UndoRejection | undefined;
+}
+/**
+ * Record one committed operation.
+ *
+ * The redo half is cleared (a new operation starts a new branch of history), the record goes on top of the
+ * undo half, and anything beyond `undoDepth` is dropped. A non-positive `undoDepth` keeps no history at all.
+ *
+ * @param stack - current state.
+ * @param operation - the operation that just succeeded.
+ * @param options - `undoDepth` from configuration.
+ * @returns the new state.
+ */
+export declare function recordOperation(stack: UndoStack, operation: RecycleBinOperation, options: {
+    readonly undoDepth: number;
+}): UndoStack;
+/** The operation {@link takeUndo} would consume, or `undefined` for an empty history. */
+export declare function nextUndo(stack: UndoStack): RecycleBinOperation | undefined;
+/** The operation that can be re-applied, or `undefined` when nothing was undone. */
+export declare function nextRedo(stack: UndoStack): RecycleBinOperation | undefined;
+/**
+ * Consume the newest operation as an **inverse** step.
+ *
+ * `discard` reverses to `restore`; `restore` reverses to `discard`; `purge` is refused as `irreversible`
+ * (a physical delete cannot be undone, and the record is dropped instead of being offered again).
+ *
+ * @param stack - current state.
+ * @param context - which ids are actually in the bin right now.
+ * @returns the action to run plus the new state, or a rejection plus the state with the dead record dropped.
+ */
+export declare function takeUndo(stack: UndoStack, context: UndoContext): UndoOutcome;
+/**
+ * Re-apply the newest undone operation.
+ *
+ * This is the exact inverse of {@link takeUndo}: it consumes the redo half and pushes the same operation back
+ * onto the undo half.
+ *
+ * @param stack - current state.
+ * @param context - which ids are actually in the bin right now.
+ * @returns the action to run plus the new state, or a rejection.
+ */
+export declare function takeRedo(stack: UndoStack, context: UndoContext): UndoOutcome;
+/** The persisted index document. */
+export interface RecycleBinIndex {
+    readonly version: number;
+    readonly entries: readonly RecycleBinEntry[];
+}
+/** One record the parser refused, with the reason (a corrupt index must never silently lose data). */
+export interface SkippedIndexRecord {
+    readonly index: number;
+    readonly reason: string;
+}
+/** Result of {@link parseRecycleBinIndex}. */
+export interface ParsedRecycleBinIndex {
+    readonly entries: readonly RecycleBinEntry[];
+    readonly skipped: readonly SkippedIndexRecord[];
+}
+/**
+ * Serialize the index.
+ *
+ * Entries are sorted by id so the same set always produces byte-identical text (easy to diff, easy to test).
+ * The result is a plain JavaScript string: written as UTF-8 it carries **no BOM**, and {@link parseRecycleBinIndex}
+ * tolerates one anyway because remote tooling and editors add them.
+ *
+ * @param entries - entries to persist.
+ * @returns JSON text.
+ */
+export declare function serializeRecycleBinIndex(entries: readonly RecycleBinEntry[]): string;
+/**
+ * Parse the index.
+ *
+ * A malformed document or an unknown version is a hard failure (the bin contents cannot be trusted); a single
+ * unusable record is skipped and reported. Stored `binPath` values are taken as authoritative and not recomputed,
+ * so changing the `binRootFor` configuration later does not invalidate existing entries.
+ *
+ * @param text - index file content.
+ * @returns the usable entries plus the skipped records.
+ * @throws SshDevError `TRASH_NOT_FOUND` when the document cannot be read as an index.
+ */
+export declare function parseRecycleBinIndex(text: string): ParsedRecycleBinIndex;
+//# sourceMappingURL=recycle-bin.d.ts.map

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

@@ -0,0 +1,74 @@
+/**
+ * Root references: one project root is either a local directory or a remote directory on
+ * one connection. Remote roots additionally carry a local *anchor* directory, because DSH
+ * requires a workspace path that exists on the host filesystem.
+ *
+ * @module dsh-remote-workspace/domain/root
+ */
+/** Where a root lives. */
+export type RootLocation = 'local' | 'remote';
+/** One project root. */
+export interface RootRef {
+    /** Local or remote. */
+    readonly location: RootLocation;
+    /** Connection id; present exactly for remote roots. */
+    readonly connectionId?: string;
+    /** Absolute local path, or absolute POSIX path for a remote root. */
+    readonly path: string;
+    /** Whether the sandbox fence admits writes under this root. */
+    readonly writable: boolean;
+    /** Local anchor directory for a remote root (empty directory, never mirrored content). */
+    readonly anchorPath?: string;
+    /** Display label; defaults to the final path segment. */
+    readonly label?: string;
+}
+/** Options shared by both root kinds. */
+export interface RootOptions {
+    /** Whether writes under this root are allowed; defaults to true. */
+    readonly writable?: boolean;
+    /** Display label override. */
+    readonly label?: string;
+}
+/** Create a remote root, validating the connection id and remote path. */
+export declare function makeRemoteRoot(connectionId: string, remotePath: string, options?: RootOptions & {
+    readonly anchorPath?: string;
+}): RootRef;
+/**
+ * Create a local root from an absolute host path.
+ *
+ * The stored path **preserves the caller's case** (only separators, `.`/`..` and the drive letter
+ * are canonicalised). Case folding belongs to comparison and keying — `rootKey` folds, and
+ * `localPathContains` folds on request — because the root's path is also what the UI shows and what
+ * a child process receives via `processPath`.
+ */
+export declare function makeLocalRoot(path: string, options?: RootOptions): RootRef;
+/** Whether a host path is absolute in either the Windows or the POSIX spelling. */
+export declare function isAbsoluteLocalPath(path: string): boolean;
+/**
+ * Normalize a host path for comparison: separators to `/`, `.`/`..` resolved, trailing
+ * separators dropped, and (optionally) the drive letter and case folded.
+ *
+ * @param path - host path in either separator spelling.
+ * @param options - `caseInsensitive` folds case for comparison keys.
+ * @returns the normalized path.
+ */
+export declare function normalizeLocalPath(path: string, options?: {
+    readonly caseInsensitive?: boolean;
+}): string;
+/** Whether a host path is `root` itself or a descendant of it. */
+export declare function localPathContains(root: string, candidate: string, options?: {
+    readonly caseInsensitive?: boolean;
+}): boolean;
+/** Stable identity of a root, used as a cache/route key. */
+export declare function rootKey(root: RootRef): string;
+/** The model-facing and UI-facing spelling of a root's directory. */
+export declare function rootDisplay(root: RootRef): string;
+/** The display label of a root: explicit label, else the final path segment. */
+export declare function rootLabel(root: RootRef): string;
+/** Whether two roots of the same location overlap (one contains the other). */
+export declare function rootsOverlap(left: RootRef, right: RootRef): boolean;
+/** Validate a root reference produced outside this module. */
+export declare function validateRoot(root: RootRef): void;
+/** FNV-1a (32-bit) over UTF-16 code units, rendered as 8 lowercase hex characters. */
+export declare function fnv1aHex(input: string): string;
+//# sourceMappingURL=root.d.ts.map

package/lib/types/src/host/domain/roots/bin-location.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Where a root's **file-level recycle bin** lives, and how to tell whether that place is usable.
+ *
+ * The bin used to sit at `<root>/.dsh-remote-workspace/trash` — inside the caller's own repository, so every
+ * `git status` and `git add .` saw the bytes someone had just "safely deleted". Moving it out is not a matter
+ * of changing a default (audit 0064 §3): the router refuses any path that is not inside a registered root, so
+ * the new location has to be *registered* as a root of its own — one that is deliberately **not** listed
+ * anywhere the user looks. The placement rules live here, as pure functions, because they are the part that
+ * must be identical for every root and every world.
+ *
+ * Two constraints decide the location, and both are hard:
+ *
+ *  1. **Same device as the root.** The bin's whole guarantee is "move first, then confirm", and a cross-device
+ *     `rename` is refused outright rather than degraded to a copy (`fs-commands.ts`), because a copy can fail
+ *     half way and leave the bytes neither here nor there. The file-level bin has no copy fallback. So the bin
+ *     must be on the root's own filesystem.
+ *  2. **Outside the repository, but not somewhere unguessable.** `$HOME` looks tidy and is the wrong answer:
+ *     on the site this plugin was built against the login home is `/home1/<user>` while projects live under
+ *     `/srv` or `/mnt`, which are usually separate mounts (NFS/automount) — so a home-based bin would make
+ *     **every** delete fail with `cross-device`. The root's own **parent** is the closest directory that is
+ *     almost always on the same filesystem.
+ *
+ * @module dsh-over-ssh/domain/bin-location
+ */
+import { type RootRef } from './root.ts';
+/** The bin directory name used when the caller configures none (`binDir`). */
+export declare const DEFAULT_BIN_DIR = ".dsh-over-ssh/trash";
+/**
+ * Bin directory names this plugin used before it was renamed to `dsh-over-ssh`.
+ *
+ * Kept as **read sources**, never as write targets: the bin index is the only record of what is recoverable
+ * and each entry names its bytes by absolute path, so a rename without a migration would leave every already
+ * deleted file on disk but unreachable. The resolver moves an old bin into {@link DEFAULT_BIN_DIR} the first
+ * time it sees one (see `bin-root-resolver.ts`).
+ *
+ * Both spellings are listed because the bin lived in two places over its lifetime: inside the root, and
+ * beside it under the root's parent.
+ */
+export declare const LEGACY_BIN_DIRS: readonly [".dsh-remote-workspace/trash"];
+/**
+ * The root's own directory, in the spelling that world uses.
+ *
+ * Remote paths are always POSIX and are normalised as such; a local path is normalised by the host's rules
+ * (which is what makes `D:\work\a` and `D:/work/a` the same directory on Windows).
+ *
+ * @param root - the root whose directory is wanted.
+ * @returns a `/`-separated path.
+ */
+export declare function rootDirectory(root: RootRef): string;
+/**
+ * The bin directory **inside** the root — the historical location, kept as the documented fallback.
+ *
+ * @param root - the root being served.
+ * @param binDir - configured directory name, relative to the root.
+ * @returns the absolute bin directory.
+ */
+export declare function binRootInsideRoot(root: RootRef, binDir?: string): string;
+/**
+ * A stable, filesystem-safe directory name for one root's bin.
+ *
+ * Two roots can share a parent (and even a basename, across connections), so the name carries a hash of the
+ * root's identity rather than only its last segment. Stable across runs: the bin directory must be findable
+ * again after a restart, and an unstable name would silently orphan every deleted byte.
+ *
+ * @param root - the root being served.
+ * @returns a name such as `work-1f3a9c02`.
+ */
+export declare function binRootSlug(root: RootRef): string;
+/**
+ * The bin directory **beside** the root, under its parent.
+ *
+ * The parent is used rather than `$HOME` because it is almost always the root's own filesystem, which is the
+ * one property the bin cannot do without. `binDir` keeps its configured name so the plugin's footprint reads
+ * the same as before; the per-root slug keeps two roots in one parent apart.
+ *
+ * @param root - the root being served.
+ * @param binDir - configured directory name, relative to the parent.
+ * @returns the absolute bin directory, or `undefined` when the root has no usable parent (it *is* `/`).
+ */
+export declare function binRootBesideRoot(root: RootRef, binDir?: string): string | undefined;
+/**
+ * The directory a same-device check must compare the bin directory against.
+ *
+ * The bin is created by the plugin, so on the first delete it may not exist yet; the parent is what has to be
+ * on the same filesystem, and it always exists (it contains the root).
+ *
+ * @param root - the root being served.
+ * @returns the absolute parent directory, or `undefined` for a root with no parent.
+ */
+export declare function binParentDirectory(root: RootRef): string | undefined;
+//# sourceMappingURL=bin-location.d.ts.map

package/lib/types/src/host/domain/roots/connection.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Connection profiles and their validation.
+ *
+ * A profile never carries secret material: a password is referenced by credential key and
+ * resolved from `ctx.credentials` per operation.
+ *
+ * @module dsh-over-ssh/domain/connection
+ */
+import type { SshConfigImportDraft } from './ssh-config.ts';
+/** How the transport reaches the host. `agent` is the opt-in Tier 2 proxy (launched over the system ssh). */
+export type TransportKind = 'alias' | 'ssh2' | 'agent';
+/** Host key verification policy. */
+export type HostKeyPolicy = 'strict' | 'accept-new';
+/** Authentication method. */
+export type AuthSpec = {
+    readonly kind: 'agent';
+} | {
+    readonly kind: 'key';
+    readonly keyPath: string;
+    readonly hasPassphrase: boolean;
+} | {
+    readonly kind: 'password';
+    readonly credentialKey: string;
+};
+/** One saved connection. */
+export interface ConnectionProfile {
+    /** Stable slug used inside `ssh://` paths and as the pool key. */
+    readonly id: string;
+    /** Human-facing name. */
+    readonly name: string;
+    /** Transport implementation. */
+    readonly transport: TransportKind;
+    /** Host name used by the ssh2 transport, and by alias transport only for diagnostics. */
+    readonly host: string;
+    readonly port: number;
+    readonly user: string;
+    /** OpenSSH alias; required by the alias transport. */
+    readonly alias?: string;
+    readonly auth: AuthSpec;
+    /** ProxyJump chain, applied through `-J` (ssh2) or the alias (config). */
+    readonly proxyJump: readonly string[];
+    readonly hostKeyPolicy: HostKeyPolicy;
+    /** Remote directory used as the default root when creating a remote workspace. */
+    readonly remoteDefaultRoot?: string;
+    readonly connectTimeoutMs: number;
+    readonly commandTimeoutMs: number;
+    readonly keepAliveSeconds: number;
+}
+/** Defaults for a new connection. */
+export declare const CONNECTION_DEFAULTS: {
+    readonly port: 22;
+    readonly connectTimeoutMs: 15000;
+    readonly commandTimeoutMs: 30000;
+    readonly keepAliveSeconds: 60;
+};
+/** Whether a string can name a value in the credential store. */
+export declare function isValidCredentialRef(value: string): boolean;
+/**
+ * 一个凭据引用名**可能落在哪几个名字上**，按优先顺序。
+ *
+ * `credentialKey` 会落盘进 `user-roots.json`，所以老连接的引用名仍是 `DSH_SSH_…`，直接用就行。回退是
+ * 为了那些**没落盘**的早期记录：它们的引用名是运行时按 id 现推的，改名后会推出新前缀，不回退就取不到
+ * 已存的密码。反过来，新名字在前，所以迁移过的连接不会去读旧位置。
+ *
+ * @param key - 当前的引用名。
+ * @returns 一个或两个候选名字；不是本插件派生的名字时只有一个（原样）。
+ */
+export declare function credentialRefCandidates(key: string): readonly string[];
+/**
+ * Derive the credential-reference name that holds one connection's password.
+ *
+ * The platform names stored values with a POSIX identifier, so a user-chosen name — `腾讯云` included —
+ * cannot be used verbatim. The derivation keeps whatever ASCII is readable and then appends a 64-bit digest
+ * of the **exact** id: readable enough to find in the credentials file, and collision-free between two names
+ * that sanitise to the same slug (`a b` and `a_b`). It is a pure function of the id, so re-adding the same
+ * name reuses one stored secret instead of accumulating orphans.
+ *
+ * @param connectionId - the user's connection name.
+ * @returns a name satisfying {@link isValidCredentialRef}.
+ */
+export declare function credentialRefFor(connectionId: string): string;
+/**
+ * Validate untrusted input into a connection profile.
+ *
+ * Misconfiguration fails loudly at this boundary, so the rest of the plugin can treat a
+ * `ConnectionProfile` as trustworthy.
+ *
+ * @param input - candidate value (settings JSON, import draft or test fixture).
+ * @returns the validated profile.
+ * @throws SshDevError with code `CONNECTION_INVALID`.
+ */
+export declare function validateConnectionProfile(input: unknown): ConnectionProfile;
+/**
+ * Turn one importable `~/.ssh/config` alias into a profile.
+ *
+ * The alias transport inherits user/port/identity/proxy settings from the alias itself, so
+ * the draft's explicit values are kept only for display and for the ssh2 fallback.
+ *
+ * @param id - connection id assigned by the caller (keeps this function deterministic).
+ * @param draft - one draft from {@link importableEntries}.
+ * @returns the validated profile.
+ */
+export declare function profileFromImportDraft(id: string, draft: SshConfigImportDraft): ConnectionProfile;
+/** One-line summary used by diagnostics and the settings list. */
+export declare function connectionSummary(profile: ConnectionProfile): string;
+//# sourceMappingURL=connection.d.ts.map