dsh-over-ssh 0.1.0 → 0.1.1

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

@@ -1,79 +0,0 @@
-/**
- * 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-remote-workspace/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-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/connection.d.ts

@@ -1,95 +0,0 @@
-/**
- * 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/glob-pattern.d.ts

@@ -1,62 +0,0 @@
-/**
- * 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

@@ -1,63 +0,0 @@
-/**
- * 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

@@ -1,84 +0,0 @@
-/**
- * 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