dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,95 @@
+/**
+ * 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-remote-workspace/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;
+/**
+ * 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

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

@@ -0,0 +1,55 @@
+/**
+ * Domain errors and SSH failure diagnostics.
+ *
+ * Failure classification satisfies the requirement that a failed connection must name
+ * an actionable cause (missing key vs rejected key vs unreachable host vs changed host key)
+ * instead of a generic "connection failed".
+ *
+ * @module dsh-over-ssh/domain/errors
+ */
+/** Stable error codes crossing the plugin's internal and remote boundaries. */
+export declare const SSH_DEV_ERROR_CODES: readonly ["CONNECTION_INVALID", "CONNECTION_NOT_FOUND", "CONNECTION_LOST", "CONNECTION_UNREACHABLE", "AUTH_FAILED", "HOST_KEY_CHANGED", "ROOT_INVALID", "ROOT_AMBIGUOUS", "ROOT_OUTSIDE", "REMOTE_NOT_FOUND", "REMOTE_UNSUPPORTED", "REMOTE_COMMAND_FAILED", "SANDBOX_DENIED", "TRANSFER_CONFLICT", "TRASH_NOT_FOUND", "SESSION_ACTIVE", "CANCELLED"];
+/** One stable plugin error code. */
+export type SshDevErrorCode = (typeof SSH_DEV_ERROR_CODES)[number];
+/** A plugin-owned failure that carries a stable code and structured details. */
+export declare class SshDevError extends Error {
+    readonly code: SshDevErrorCode;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: SshDevErrorCode, message: string, details?: Readonly<Record<string, unknown>>);
+}
+/** Test whether a value is a plugin-owned failure. */
+export declare function isSshDevError(value: unknown): value is SshDevError;
+/** Actionable classification of one local `ssh` failure. */
+export type SshFailureKind = 'auth-failed' | 'key-missing' | 'key-permissions' | 'agent-unavailable' | 'host-unreachable' | 'dns-failed' | 'host-key-changed' | 'host-key-unknown' | 'timeout' | 'remote-command-missing' | 'connection-lost' | 'unknown';
+/** A classified failure plus the next action a user can take. */
+export interface SshDiagnostic {
+    readonly kind: SshFailureKind;
+    readonly hint: string;
+}
+/** Classify one local `ssh` attempt from its exit status, stderr and signal. */
+export declare function classifySshFailure(input: {
+    readonly exitCode?: number | undefined;
+    readonly stderr?: string | undefined;
+    readonly signal?: string | null | undefined;
+}): SshDiagnostic;
+/**
+ * Build the plugin failure for one unclassified-or-classified ssh failure.
+ *
+ * The classification is what decides the **code**, and the two host-key kinds have codes of their own. Mapping
+ * them onto `CONNECTION_LOST` (the old fallback) told the user "the connection dropped, reconnect" for a
+ * condition where reconnecting is exactly what must not happen silently — a changed host key is the one
+ * failure whose whole point is to stop and be looked at. `HOST_KEY_CHANGED` was declared in
+ * {@link SSH_DEV_ERROR_CODES} and never thrown anywhere until this mapping existed (audit 0043).
+ *
+ * @param connectionId - the connection the attempt belonged to.
+ * @param input - exit status, stderr and signal of the failed attempt.
+ * @returns the error to surface.
+ */
+export declare function sshFailureToError(connectionId: string, input: {
+    readonly exitCode?: number | undefined;
+    readonly stderr?: string | undefined;
+    readonly signal?: string | null | undefined;
+}): SshDevError;
+/** Keep only the tail of a long diagnostic string so details stay bounded. */
+export declare function tail(text: string, maxChars: number): string;
+//# sourceMappingURL=errors.d.ts.map

package/lib/types/src/host/domain/glob-pattern.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Glob patterns, matched the way the Tier 2 agent matches them.
+ *
+ * Why this module exists: `remote_glob` used to mean two different things depending on which transport answered.
+ * The Tier 2 agent delegates to Go's `doublestar`, while the Tier 1 fallback ran a literal substring test
+ * (`path.includes(pattern)`), so `*.cpp` matched nothing on one tier and every `.cpp` on the other, and the
+ * tool description described only the substring half. The two behaviours were introduced by different audits
+ * (0052 P3 chose substring, 0030 added the Go fast path) and nothing compared them afterwards.
+ *
+ * The rules below are a port of `dsh-over-ssh-agent/internal/agent/glob_semantics_test.go`, and that same table is
+ * mirrored in this module's test. A divergence between the two implementations is therefore a test failure on
+ * one side or the other, instead of a surprise for whoever happens to run on the other tier.
+ *
+ * The language:
+ *
+ *  - A pattern **without** `/` matches the basename at any depth (`*.h` finds `app/include/header.h`).
+ *  - A pattern **with** `/` is anchored at the enumerated root, and `*` never crosses a `/`.
+ *  - `**` as a whole segment crosses zero or more segments: `**\/a` matches `a`, `x/a`, `x/y/a`; `a/**`
+ *    matches `a` itself as well as everything below it. `**` inside a segment (`a**b`) behaves like `*`.
+ *  - `?` is one character other than `/`.
+ *  - `[...]` is a character class; a leading `!` or `^` negates it.
+ *  - `{a,b}` alternates (and `{a}` is just `a`).
+ *  - `\x` is a literal `x`.
+ *  - An unclosed `[` or `{` **throws**: a caller who wrote a broken pattern must be told, because an empty
+ *    result would otherwise read as "no such file".
+ *
+ * Matching is case-sensitive, like `doublestar`. Paths are `/`-separated and **relative to the enumerated
+ * root** — the caller normalizes them, so this module needs no filesystem knowledge and stays offline-testable.
+ *
+ * @module dsh-over-ssh/domain/glob-pattern
+ */
+/** A pattern that cannot be compiled; the message names the offending construct. */
+export declare class GlobPatternError extends Error {
+    constructor(message: string);
+}
+/** One compiled pattern. */
+export interface CompiledGlob {
+    /** The pattern as the caller wrote it. */
+    readonly pattern: string;
+    /**
+     * True when the pattern has no `/`, so it is matched against the basename at any depth.
+     *
+     * The test is on the **raw** pattern, matching the agent (`!strings.Contains(pattern, "/")`): a `/` inside
+     * braces still anchors the pattern.
+     */
+    readonly basenameOnly: boolean;
+    /**
+     * Whether one root-relative path matches.
+     *
+     * @param relativePath - `/`-separated path relative to the enumerated root.
+     */
+    matches(relativePath: string): boolean;
+}
+/**
+ * Compile one glob pattern.
+ *
+ * @param pattern - the pattern as the caller wrote it.
+ * @returns the compiled pattern.
+ * @throws GlobPatternError when the pattern is not a valid glob.
+ */
+export declare function compileGlob(pattern: string): CompiledGlob;
+//# sourceMappingURL=glob-pattern.d.ts.map

package/lib/types/src/host/domain/literal-text.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Literal string helpers shared by the two write paths.
+ *
+ * The plugin has **three** literal edit call sites — `app/routed-fs.ts` (the path-based `FileSystem`
+ * surface), `integration/fs/fs-provider.ts` (the core `ctx.fs` provider) and
+ * `integration/fs/remote-file-tools.ts` (`remote_edit`) — because the seams were written separately. They
+ * must agree on what "the requested text appears N times" means and on what "replace it" produces, or the
+ * same edit is ambiguous through one seam and corrupting through another.
+ *
+ * They already diverged twice. First on counting: each carried its **own** private `countOccurrences`,
+ * and only one of the two guarded the empty needle — without that guard `indexOf('')` returns `0` forever,
+ * so the unguarded copy was an **infinite loop** (audit 0057 §11 #4, latent because a caller happened to
+ * reject the empty needle first). Then on replacing: two of the three used
+ * `source.replace(needle, replacement)`, whose **string** replacement expands `$&`, `` $` ``, `$'` and
+ * `$$` — so a replacement containing `$$` (a shell PID in a Makefile, say) was written back as `$`, and on
+ * the Tier 1 fallback path that corrupted the remote file (audit 2026-10-31 P1). One implementation each,
+ * in the domain layer, removes the possibility of a further divergence.
+ *
+ * @module dsh-over-ssh/domain/literal-text
+ */
+/**
+ * Count non-overlapping occurrences of a literal needle.
+ *
+ * **An empty needle returns 0, never "matches everywhere".** That is not a style choice: the loop below
+ * advances by `needle.length`, so a zero-length needle would never advance and the loop would never end.
+ * Returning 0 keeps the "0 occurrences ⇒ the text was not found" branch in the callers correct, which is
+ * the answer an empty search deserves.
+ *
+ * Occurrences are non-overlapping: `countOccurrences('aaaa', 'aa') === 2`, matching what
+ * `String.prototype.split(needle).length - 1` (the replacement the callers use) would produce.
+ *
+ * @param haystack - the text to search.
+ * @param needle - the literal text to count; treated verbatim, never as a pattern.
+ * @returns how many times `needle` occurs, or 0 when `needle` is empty.
+ */
+export declare function countOccurrences(haystack: string, needle: string): number;
+/** What one literal replacement produced. */
+export interface LiteralReplacement {
+    /** The text after the replacement. */
+    readonly text: string;
+    /** How many occurrences were replaced (`all ? occurrences : 1`), or `0` when the needle is absent. */
+    readonly replacements: number;
+}
+/**
+ * Replace occurrences of a literal needle, **verbatim on both sides**.
+ *
+ * The replacement text is spliced in by index (single) or joined from `split` (all), never passed to
+ * `String.prototype.replace` as a string replacement: that overload expands `$&`, `` $` ``, `$'` and `$$`,
+ * so `new: '$$'` would be written as `$`. Splicing is the only way to make "the replacement is inserted
+ * verbatim" true for a caller that has no idea what a `$` means to JavaScript.
+ *
+ * Total by construction: an empty or absent needle replaces nothing and returns the source unchanged, so a
+ * caller cannot turn a policy question ("should this have matched?") into a corrupted file. Every caller
+ * validates the occurrence count *before* calling this.
+ *
+ * @param source - the text to edit.
+ * @param needle - literal text to find; treated verbatim, never as a pattern.
+ * @param replacement - text to insert; no `$` expansion of any kind.
+ * @param all - replace every occurrence, or only the first.
+ * @returns the new text plus how many occurrences were replaced.
+ */
+export declare function replaceLiteral(source: string, needle: string, replacement: string, all: boolean): LiteralReplacement;
+//# sourceMappingURL=literal-text.d.ts.map

package/lib/types/src/host/domain/path-grammar.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The model-facing path grammar for remote roots.
+ *
+ * Remote files are addressed as `ssh://<connectionId>/<absolute remote path>` so that a
+ * POSIX remote path can never be confused with a local POSIX path. Local anchor directories
+ * are an implementation detail of the workspace requirement (a workspace path must exist
+ * locally); they are not part of the model-facing grammar.
+ *
+ * @module dsh-over-ssh/domain/path-grammar
+ */
+/** The scheme that marks a remote path. */
+export declare const SSH_SCHEME = "ssh://";
+/** A parsed `ssh://` reference. */
+export interface RemotePathRef {
+    /** Connection id (slug). */
+    readonly connectionId: string;
+    /** Absolute POSIX path on that host. */
+    readonly path: string;
+}
+/** Whether a string is written in the remote grammar. */
+export declare function isSshPath(input: string): boolean;
+/** Validate a connection id slug. */
+export declare function isValidConnectionId(id: string): boolean;
+/**
+ * Parse `ssh://<connectionId>/<absolute path>`.
+ *
+ * @param input - candidate reference.
+ * @returns the parsed reference, or `undefined` when the input is not in the grammar.
+ * @throws SshDevError when the input uses the scheme but is malformed.
+ */
+export declare function parseSshPath(input: string): RemotePathRef | undefined;
+/** Format a remote reference into the model-facing grammar. */
+export declare function formatSshPath(connectionId: string, remotePath: string): string;
+/**
+ * Normalize an absolute POSIX path: collapse repeated separators, resolve `.` and `..`,
+ * and reject relative spellings. Trailing separators are dropped except for the root.
+ *
+ * @param path - absolute POSIX path.
+ * @returns the normalized absolute path.
+ * @throws SshDevError when the path is not absolute.
+ */
+export declare function normalizeRemotePath(path: string): string;
+/**
+ * Join a relative spelling onto an absolute remote base, then normalize.
+ *
+ * @param base - absolute POSIX base directory.
+ * @param relative - relative spelling, optionally containing `.`/`..`.
+ * @returns the normalized absolute path.
+ */
+export declare function joinRemotePath(base: string, relative: string): string;
+/**
+ * Whether `candidate` is `root` itself or a descendant of it, compared per path segment
+ * (so `/srv/appdata` is not contained by `/srv/app`).
+ *
+ * @param root - absolute POSIX directory.
+ * @param candidate - absolute POSIX path.
+ * @returns whether the candidate is inside the root.
+ */
+export declare function remotePathContains(root: string, candidate: string): boolean;
+/**
+ * The parent directory of an absolute remote path; the root's parent is the root.
+ *
+ * @param path - absolute POSIX path.
+ * @returns the normalized parent directory.
+ */
+export declare function remoteDirname(path: string): string;
+/**
+ * The final segment of an absolute remote path; the root yields an empty string.
+ *
+ * @param path - absolute POSIX path.
+ * @returns the final segment.
+ */
+export declare function remoteBasename(path: string): string;
+/**
+ * Whether `candidate` is a descendant of one of the roots, returning the longest match.
+ *
+ * Longest-prefix matching is what keeps nested roots (`/srv` and `/srv/app`) unambiguous.
+ *
+ * @param roots - absolute POSIX roots to test.
+ * @param candidate - absolute POSIX path.
+ * @returns the matched root, or `undefined` when nothing contains the candidate.
+ */
+export declare function longestContainingRoot(roots: readonly string[], candidate: string): string | undefined;
+//# sourceMappingURL=path-grammar.d.ts.map