dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,461 @@
+/**
+ * User-owned roots and connections, as the **panel** may edit them.
+ *
+ * Two files in the plugin state directory must never be confused:
+ *
+ *  - `roots.json` — the terminal wrapper's manifest ({@link ./terminal-manifest.ts}). It is *derived*: the
+ *    host rewrites it from the live registry after every mutation, and it contains already-resolved ssh
+ *    argv. Nothing here touches it.
+ *  - `user-roots.json` — **this module**. It is the *input*: what the user asked for in the UI, kept across
+ *    restarts so a panel can list and edit roots without the host having to re-derive them from Config.
+ *
+ * Shape (version 1):
+ *
+ * ```json
+ * {
+ *   "version": 1,
+ *   "roots": [{ "location": "remote", "connectionId": "gpu01", "path": "/srv/work", "writable": true }],
+ *   "connections": [{ "id": "gpu01", "host": "gpu01.example.net", "user": "root", "port": 22,
+ *                     "authKind": "key", "keyPath": "~/.ssh/id_ed25519" }]
+ * }
+ * ```
+ *
+ * Non-negotiables this module owns:
+ *
+ *  1. **Atomic writes** — temp file + `rename`, so a reader never sees a half-written document. The temp name
+ *     is unique per write: a shared `${file}.tmp` let two overlapping writers truncate each other's scratch
+ *     file and race on the `rename`.
+ *  2. **Bad JSON never throws at the caller** — {@link parseUserRoots} returns the empty state plus a
+ *     human-readable warning; a single corrupt entry is dropped, not fatal.
+ *  3. **No secret value, ever** — a `password` or `passphrase` **field** is refused with an error that says so
+ *     (密码不入 UI 存储). Passwords belong in `ctx.credentials`. **`authKind: 'password'` itself is accepted**:
+ *     what is stored for it is only `credentialKey`, the *name* of the stored value, and the reference is
+ *     derived from the id when the caller supplies none. (This paragraph used to claim `authKind: 'password'`
+ *     was refused while the same file's {@link normalizeConnectionEntry} accepted it — audit 0043.)
+ *  4. **Every mutation returns a new state** and persists it; nothing mutates a shared object in place.
+ *  5. **A connection rename takes its roots with it** ({@link updateConnectionInState}): a remote root names
+ *     its connection in its key, so an id change that left the roots behind would break them silently.
+ *  6. **Mutations are serialised within this process** ({@link createUserRootsStore}): each one is a
+ *     read-modify-write of one document, so overlapping requests would otherwise lose updates silently.
+ *
+ * This module deliberately imports **no** `@deepseek-ai/*` package: it is pure I/O plus validation, and the
+ * file system is injected so tests never touch the developer's home directory.
+ *
+ * @module dsh-remote-workspace/integration/user-roots
+ */
+/** The only format version this module reads or writes. */
+export declare const USER_ROOTS_VERSION = 1;
+/** File name inside the plugin state directory (`~/.dsh/ssh-dev` by default in the entry). */
+export declare const USER_ROOTS_FILE_NAME = "user-roots.json";
+/** Where a user root lives. */
+export type UserRootLocation = 'local' | 'remote';
+/**
+ * Which authentication a panel-added connection may use.
+ *
+ * The **secret** is what may never appear here: the validator refuses a `password` or `passphrase` field
+ * even when it arrives as raw JSON. `password` authentication is supported, but only as a
+ * {@link UserConnectionRecord.credentialKey} **reference** into `ctx.credentials`.
+ */
+export type UserConnectionAuthKind = 'agent' | 'key' | 'password';
+/**
+ * Which transport a panel-added connection asks for.
+ *
+ * **Not the same thing as {@link UserConnectionAuthKind}'s `agent`**, and the two must never be conflated:
+ * `authKind: 'agent'` names the **local** ssh-agent as a credential source, while `transport: 'agent'` names
+ * the **remote** Tier 2 Go program this plugin uploads on first connect (ADR-0005/0007). The values mirror the
+ * host's own `TransportKind` (`domain/connection.ts`); this module keeps its own copy because it validates the
+ * file, and `transport` is what `toProfileInput` reads to build the profile.
+ */
+export type UserConnectionTransport = 'alias' | 'ssh2' | 'agent';
+/** One root the user added. */
+export interface UserRootEntry {
+    /** Local directory or remote directory. */
+    readonly location: UserRootLocation;
+    /** Non-empty local path, or a POSIX absolute path for a remote root. */
+    readonly path: string;
+    /** Connection id; required exactly for remote roots. */
+    readonly connectionId?: string;
+    /** Display label shown by the panel. */
+    readonly label?: string;
+    /** Whether writes under this root are allowed; the panel's default is `true`. */
+    readonly writable?: boolean;
+    /**
+     * The workspaces this root was added **to** (canonical local paths).
+     *
+     * **Absent means "not added to any session yet"**  -  it does **not** mean "applies to every session". A
+     * session lists only the roots whose `workspaces` names its own workspace path (`session-directory.ts`,
+     * `loadRoots`), so an unscoped root is registered with the host but is listed by no session until one opts
+     * in with 「添加目录」.
+     *
+     * Why it exists: the composer's 「添加目录」 reads as "add this directory to *this* conversation", and the
+     * first version wrote every such root into one flat list  -  so a directory added in one workspace showed up
+     * in the next one, which the user rightly called out. The requirement document already separates the two
+     * (FR-1.7: extra roots live in the plugin's own storage, grouped per project), so the grouping is recorded
+     * here.
+     *
+     * The settings panel adds **unscoped** roots because its form has no scope field at all
+     * (`RootsPanelDrafts` carries no `workspaces` member): it registers a root with the host, and a session opts
+     * in explicitly. An earlier revision of this comment justified listing unscoped roots in *every* session by
+     * claiming that the panel's "own copy says those apply to every session"  -  **no such copy existed**; every
+     * `roots*` string in both dictionaries is about paths, connections, testing and validation (audit 0056).
+     * The silent global visibility that followed  -  a remote directory appearing in a session that had never
+     * added it  -  is why the rule is now the other way round.
+     *
+     * Plural because identity is the **path** ({@link userRootKey}) and the same path can be added to more than
+     * one workspace. The live registry and the router are plugin-wide (a path resolves by scheme/anchor, not by
+     * workspace), so a remote root stays addressable from another workspace. Filtering is a view fact, not a
+     * sandbox.
+     */
+    readonly workspaces?: readonly string[];
+    /**
+     * The local anchor directory this remote root stands on, when it has one.
+     *
+     * It is persisted because it is **identity at the platform level**: the platform creates a workspace on
+     * this host path, so a root whose anchor is re-derived differently (a connection rename changes both the
+     * `connectionId` segment and the digest) silently orphans the workspace that was created on the old one.
+     * The first version derived it on every read and never stored it; a rename then moved every anchor and left
+     * the user's remote workspaces pointing at paths no root covered (`ROOT_OUTSIDE`).
+     *
+     * Absent means "derive it from the connection id and path" (`index.ts`'s `toRoot`), which is what entries
+     * written before this field existed do. Only remote roots may carry it; a local root is its own anchor.
+     */
+    readonly anchorPath?: string;
+}
+/** One connection the user added. Carries **no** credential. */
+export interface UserConnectionRecord {
+    /** Slug, unique in the file. */
+    readonly id: string;
+    /** Host name or IP. */
+    readonly host: string;
+    /** Login user. */
+    readonly user: string;
+    /** TCP port; absent means the ssh default. */
+    readonly port?: number;
+    /** `agent` (ssh-agent / ssh config), `key` (identity file) or `password` (stored secret). */
+    readonly authKind: UserConnectionAuthKind;
+    /**
+     * Transport the user chose in the panel; absent means the default the reader applies (`agent`, see
+     * `toProfileInput` in the entry). Optional rather than defaulted here so an older file keeps loading: a
+     * record written before the selector existed has no opinion, and inventing one on read would be a silent
+     * migration. A **present** value is validated ({@link normalizeConnectionEntry}) and is always one of the
+     * three, so a reader never has to guess whether a spelling is meaningful.
+     */
+    readonly transport?: UserConnectionTransport;
+    /** Identity file path; only meaningful for `authKind: 'key'`. */
+    readonly keyPath?: string;
+    /**
+     * Name of the stored secret, never the secret; only meaningful for `authKind: 'password'`.
+     *
+     * Derived from the id when a caller does not supply one (see `credentialRefFor`), because the platform's
+     * reference grammar is a POSIX identifier and a user-chosen Chinese name is not one.
+     */
+    readonly credentialKey?: string;
+}
+/** The whole persisted document. */
+export interface UserRootsState {
+    readonly version: typeof USER_ROOTS_VERSION;
+    readonly roots: readonly UserRootEntry[];
+    readonly connections: readonly UserConnectionRecord[];
+}
+/** One read of the file: the state plus everything that was wrong with it. */
+export interface UserRootsLoad {
+    readonly state: UserRootsState;
+    /** Non-fatal problems (missing file is **not** one: that is the pristine state). */
+    readonly warnings: readonly string[];
+}
+/** File-system surface, injected so tests never touch the developer's home directory. */
+export interface UserRootsIo {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, data: string): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+}
+/** Real file-system binding: UTF-8, owner-only, atomic. */
+export declare const nodeUserRootsIo: UserRootsIo;
+/** The pristine state: no roots, no connections. */
+export declare function emptyUserRootsState(): UserRootsState;
+/**
+ * Stable identity of a user root, and the key `remove-root` accepts.
+ *
+ * Local paths are normalised for separators and trailing slashes but **keep the caller's case**; remote keys
+ * are POSIX and therefore case-sensitive. `RootRegistry.rootKey` folds case on Windows, so
+ * {@link removeRootFromState} retries once case-insensitively for `local:` keys — otherwise a root listed by
+ * the UI as `D:/Work` could not be removed with the key `local:d:/work`.
+ *
+ * @param entry - a validated (or at least well-formed) root entry.
+ * @returns `local:<path>` or `remote:<connectionId>:<path>`.
+ */
+export declare function userRootKey(entry: UserRootEntry): string;
+/**
+ * The persisted state as JSON text: UTF-8 without BOM, two-space indent, trailing newline.
+ *
+ * The BOM-free part is deliberate — a `\uFEFF` prefix makes `JSON.parse` fail in some readers and is exactly
+ * what `Set-Content -Encoding UTF8` used to add to files in this repository.
+ *
+ * @param state - state to serialise.
+ * @returns the file contents.
+ */
+export declare function serializeUserRoots(state: UserRootsState): string;
+/**
+ * Read the persisted state from text.
+ *
+ * **Never throws.** Every failure mode degrades to the empty state plus a warning that names the reason:
+ * unreadable text is not distinguishable here (the caller catches the I/O error), but malformed JSON, a
+ * foreign `version`, and individual corrupt entries all are.
+ *
+ * @param text - file contents, or `undefined` when the file does not exist.
+ * @returns the usable state and the warnings collected on the way.
+ */
+export declare function parseUserRoots(text: string | undefined): UserRootsLoad;
+/**
+ * Normalise and validate one root entry.
+ *
+ * Rules: `location` must be `local` or `remote`; a local path must be non-empty; a remote path must be a
+ * POSIX **absolute** path and must not be `/` (the whole remote filesystem is not a workspace root); a
+ * remote root must name a valid connection id. Unknown keys are ignored by construction — only the fields
+ * below are read.
+ *
+ * @param input - untrusted value (a JSON body or one entry of the file).
+ * @returns a clean entry.
+ * @throws SshDevError `ROOT_INVALID` when the entry is not usable.
+ */
+export declare function normalizeRootEntry(input: unknown): UserRootEntry;
+/**
+ * Normalise and validate one connection entry.
+ *
+ * **A secret is refused here**, with a message that says why: 密码不入 UI 存储 — a password in this file
+ * would be readable by anything that can read the state directory, and the plugin's credential path is
+ * `ctx.credentials`. A `password` or `passphrase` field is rejected outright. `authKind: 'password'` **is**
+ * accepted, but the record then carries only `credentialKey` — the *name* of the stored value — which is
+ * derived from the id when the caller does not supply one. `keyPath` is kept for `authKind: 'key'` and
+ * dropped for the other two.
+ *
+ * `transport` is optional (absent means "the reader's default", see {@link UserConnectionRecord.transport}),
+ * but a value that **is** present must be one of the three the union allows: an unknown spelling is refused as
+ * `CONNECTION_INVALID` rather than stored, because a record the transport selector cannot read would silently
+ * fall back to a transport the user did not choose.
+ *
+ * @param input - untrusted value.
+ * @returns a clean record, never containing a credential.
+ * @throws SshDevError `CONNECTION_INVALID` when the entry is not usable.
+ */
+export declare function normalizeConnectionEntry(input: unknown): UserConnectionRecord;
+/** Find one persisted entry by key (case-folded like the registry), or `undefined`. */
+export declare function findRootInState(state: UserRootsState, key: string): UserRootEntry | undefined;
+/**
+ * Union `workspaces` into the entry at `key`, keeping the file's own order and de-duplicating.
+ *
+ * The **union** is the point, not a replace: two workspaces that both added the same directory must not
+ * un-list each other. Identity here is the path ({@link userRootKey}), and the live registry refuses the same
+ * path twice  -  so one directory added in two workspaces is one root that two workspaces list.
+ *
+ * @param state - the persisted state to update.
+ * @param key - key of the entry to update.
+ * @param workspaces - the workspaces to add.
+ * @returns a new state, or the same state when nothing changed.
+ */
+export declare function withWorkspaces(state: UserRootsState, key: string, workspaces: readonly string[]): UserRootsState;
+/**
+ * Append a root, returning a new state.
+ *
+ * @param state - current state.
+ * @param input - untrusted entry.
+ * @returns the next state (the input state is untouched).
+ * @throws SshDevError `ROOT_INVALID` on an invalid entry or a duplicate key.
+ */
+export declare function addRootToState(state: UserRootsState, input: unknown): UserRootsState;
+/**
+ * Remove a root by key, returning a new state.
+ *
+ * @param state - current state.
+ * @param key - key from {@link userRootKey} (or from a `GET` response).
+ * @returns the next state.
+ * @throws SshDevError `ROOT_INVALID` when no root matches — a silent no-op would make the panel report
+ * success for a removal that never happened.
+ */
+export declare function removeRootFromState(state: UserRootsState, key: string): UserRootsState;
+/**
+ * Remove one root from **one** workspace, keeping it for the others.
+ *
+ * The add side is a union ({@link withWorkspaces}): one directory added to two workspaces is one root that
+ * both list. The first removal implementation only had the global delete, so removing it in the workspace the
+ * operator was looking at removed it from the other one too - the inverse of the union promise, and the reason
+ * the scoped action exists.
+ *
+ * The root itself disappears only when the last workspace drops it; a root that no workspace lists is a root
+ * no session can see, so keeping it would be a silently unusable entry.
+ *
+ * @param state - current state.
+ * @param key - key from {@link userRootKey} (or from a `GET` response).
+ * @param workspacePath - the workspace to remove it from (canonical local path, compared as stored).
+ * @returns the next state.
+ * @throws SshDevError `ROOT_INVALID` when no root matches, so a no-op cannot be reported as success.
+ */
+export declare function removeRootFromWorkspace(state: UserRootsState, key: string, workspacePath: string): UserRootsState;
+/**
+ * Stamp the given anchor paths onto the entries they name, returning a new state.
+ *
+ * Used by the connection-rename path: the anchor is read from the live registry **before** the roots are
+ * re-keyed, so the new entries keep pointing at the directory the user's workspaces were created on.
+ *
+ * @param state - current state.
+ * @param anchors - root key → anchor path for the entries to stamp.
+ * @returns the next state, or the same object when nothing changed.
+ */
+export declare function withAnchorPaths(state: UserRootsState, anchors: ReadonlyMap<string, string>): UserRootsState;
+/**
+ * Append a connection, returning a new state.
+ *
+ * @param state - current state.
+ * @param input - untrusted entry (must not carry a password).
+ * @returns the next state.
+ * @throws SshDevError `CONNECTION_INVALID` on an invalid entry, a duplicate id, or a password field.
+ */
+export declare function addConnectionToState(state: UserRootsState, input: unknown): UserRootsState;
+/**
+ * Remove a connection **and every remote root that pointed at it**, returning a new state.
+ *
+ * Dropping the roots is not optional: a remote root whose connection is gone makes
+ * `RootRegistry.createRemoteBackend` throw `CONNECTION_NOT_FOUND` on the next use, so leaving it behind
+ * would turn a deletion into a later crash.
+ *
+ * @param state - current state.
+ * @param id - connection id.
+ * @returns the next state.
+ * @throws SshDevError `CONNECTION_INVALID` when no connection has that id.
+ */
+export declare function removeConnectionFromState(state: UserRootsState, id: string): UserRootsState;
+/**
+ * The fields `update-connection` may change. Absent means **keep what is there**.
+ *
+ * `password` is deliberately not here (it is not part of a record, exactly as in
+ * {@link addConnectionToState}); `credentialKey` **is**, because a rename that keeps a password must be
+ * able to keep - or deliberately re-point - the stored reference name.
+ */
+export interface ConnectionPatch {
+    /** New id (a rename). The value must pass {@link normalizeConnectionEntry}'s id rule. */
+    readonly id?: string;
+    readonly host?: string;
+    readonly user?: string;
+    /** A number, or `null`/`''` to drop the field (back to the ssh default). */
+    readonly port?: number | null | '';
+    readonly authKind?: UserConnectionAuthKind;
+    readonly keyPath?: string;
+    readonly transport?: UserConnectionTransport;
+    readonly credentialKey?: string;
+}
+/**
+ * Update one connection **in place**, returning a new state.
+ *
+ * Semantics, all of them deliberate:
+ *
+ *  1. **Absent means unchanged.** The patch is merged over the existing record, so a caller that only wants to
+ *     change the host does not have to restate the authentication - and cannot accidentally drop it.
+ *  2. **A rename migrates the roots.** A remote root names its connection in its own key
+ *     (`remote:<connectionId>:<path>`), so leaving the old id behind would turn every root of that
+ *     connection into a dangling reference that throws `CONNECTION_NOT_FOUND` on next use. The rewrite
+ *     happens here, in the same pure transition, so the file can never hold the two halves out of step.
+ *  3. **The stored secret's reference name survives a rename** unless the patch says otherwise. The reference
+ *     is a name in `ctx.credentials`, derived from the id only when nothing better is known; re-deriving it
+ *     from the new id would **orphan** the stored password (still in the store, no longer reachable) and could
+ *     silently hand it to a later connection whose derived name collides.
+ *  4. **The position in the list is kept**, so the panel's rows do not jump when one is edited.
+ *
+ * @param state - current state.
+ * @param id - id of the connection to update (the **current** id, before any rename).
+ * @param patch - the fields to change; anything absent keeps its value.
+ * @returns the next state.
+ * @throws SshDevError `CONNECTION_INVALID` when the id is unknown, the merged record is invalid, or the new
+ *   id collides with another connection.
+ */
+export declare function updateConnectionInState(state: UserRootsState, id: string, patch: ConnectionPatch): UserRootsState;
+/** What one store instance offers. Every mutation returns the new state **and** writes it. */
+export interface UserRootsStore {
+    /** Absolute path of the state file. */
+    readonly filePath: string;
+    /** Read the file; never throws for content reasons (see {@link parseUserRoots}). */
+    load(): Promise<UserRootsLoad>;
+    /** Validate and persist a whole state. */
+    save(next: UserRootsState): Promise<UserRootsState>;
+    /** Resolves once every write queued so far has settled (both success and failure). */
+    settled(): Promise<unknown>;
+    /** Persist `state + entry` and return the new state. */
+    addRoot(entry: unknown): Promise<UserRootsState>;
+    /** Persist `state - key` and return the new state. */
+    removeRoot(key: string): Promise<UserRootsState>;
+    /** Persist `state + connection` and return the new state. */
+    addConnection(entry: unknown): Promise<UserRootsState>;
+    /** Persist `state - connection` (and its remote roots) and return the new state. */
+    removeConnection(id: string): Promise<UserRootsState>;
+    /**
+     * Persist the patched connection (renaming its roots too when the id changes) and return the new state.
+     *
+     * @param id - the connection's current id.
+     * @param patch - fields to change; anything absent keeps its value.
+     */
+    updateConnection(id: string, patch: ConnectionPatch): Promise<UserRootsState>;
+}
+/** Options for {@link createUserRootsStore}. */
+export interface UserRootsStoreOptions {
+    /** Plugin state directory; the file is {@link USER_ROOTS_FILE_NAME} inside it. */
+    readonly dir: string;
+    /** File-system binding; defaults to the real one. */
+    readonly io?: UserRootsIo;
+}
+/**
+ * Build the store over one state directory.
+ *
+ * Deliberately **not** a class: every method is "read the current file, compute the next state purely, write
+ * it", which is exactly the shape the HTTP handlers need and the shape a test can drive with an in-memory
+ * `io`. There is no in-process cache, so two writers cannot disagree about what is on disk — the cost is
+ * that concurrent writers can still lose an update (read-modify-write is not locked; see the audit's
+ * unverified list).
+ *
+ * @param options - state directory plus an optional injected file system.
+ * @returns the store.
+ */
+export declare function createUserRootsStore(options: UserRootsStoreOptions): UserRootsStore;
+/**
+ * Whether the state already contains the root `key` names.
+ *
+ * The HTTP layer needs this to make its write **idempotent**: it asks the live seam to register a root and
+ * only then reconciles the file, so "already present" must not be treated as a duplicate error.
+ *
+ * @param state - current state.
+ * @param key - key from {@link userRootKey}.
+ * @returns whether a root with that key exists.
+ */
+export declare function stateHasRoot(state: UserRootsState, key: string): boolean;
+/**
+ * Whether the state already contains a connection with that id.
+ *
+ * @param state - current state.
+ * @param id - connection id.
+ * @returns whether the connection exists.
+ */
+export declare function stateHasConnection(state: UserRootsState, id: string): boolean;
+/**
+ * Validate a whole state that is about to be written.
+ *
+ * `save` runs this so a caller cannot persist an entry that {@link normalizeRootEntry} would have rejected —
+ * otherwise the file would become a source of invalid state for every later reader.
+ *
+ * @param next - candidate state.
+ * @returns the normalised state.
+ * @throws SshDevError when any entry is invalid or duplicated.
+ */
+export declare function validateState(next: UserRootsState): UserRootsState;
+/**
+ * Public spelling of {@link sameRootKey} for the route layer.
+ *
+ * The route has to compare keys from three sources that fold differently: the live registry (Windows local
+ * paths already lower-cased), the persisted file (case preserved), and the client (built from the `path` the
+ * answer carried). Without one comparison rule, a Windows local root is listed with a key the host cannot
+ * remove.
+ *
+ * @param left - one key.
+ * @param right - the other key.
+ * @returns whether they name the same root.
+ */
+export declare function sameUserRootKey(left: string, right: string): boolean;
+//# sourceMappingURL=user-roots.d.ts.map

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

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

@@ -0,0 +1,78 @@
+/**
+ * Remote capability probing.
+ *
+ * The plugin installs nothing on the remote host, so it must discover what the host already
+ * offers and degrade accordingly: `git ls-files` when git exists, a bounded `find` otherwise;
+ * `rg` when available, bounded `grep` otherwise.
+ *
+ * @module dsh-over-ssh/domain/capability
+ */
+/** What one probe learned about the remote host. */
+export interface RemoteCapabilities {
+    /** `uname -s` output, or `unknown`. */
+    readonly uname: string;
+    /** Whether the host is a POSIX shell host this plugin supports. */
+    readonly posix: boolean;
+    readonly git: boolean;
+    readonly ripgrep: boolean;
+    readonly grep: boolean;
+    readonly base64: boolean;
+    readonly findMaxDepth: boolean;
+    readonly sha256: 'sha256sum' | 'shasum' | null;
+    readonly statFlavor: 'gnu' | 'bsd' | 'unknown';
+    /**
+     * Language servers found on the remote `PATH`.
+     *
+     * `undefined` means **nobody looked** (Tier 1 shell transport, or an agent older than the probe);
+     * an empty array means the probe ran and found none. The difference matters: the first case must not be
+     * reported to a caller as "not installed", because we have no evidence either way.
+     */
+    readonly lspServers?: readonly LspServerInfo[];
+}
+/** One language server found on the remote `PATH`. */
+export interface LspServerInfo {
+    readonly command: string;
+    readonly language: string;
+    readonly path: string;
+}
+/**
+ * The one-shot probe script.
+ *
+ * Every line is `key=value`; values never contain newlines. The script is written for `sh`
+ * and tolerates missing commands, because discovering a missing command is the point.
+ *
+ * @returns a POSIX shell script.
+ */
+export declare function probeScript(): string;
+/** The capabilities assumed when probing failed: POSIX basics only. */
+export declare function conservativeCapabilities(): RemoteCapabilities;
+/**
+ * Parse probe output into capabilities.
+ *
+ * Unknown keys are ignored so the script can grow without breaking older parsers.
+ *
+ * @param stdout - the probe's standard output.
+ * @returns parsed capabilities.
+ */
+export declare function parseProbeOutput(stdout: string): RemoteCapabilities;
+/** How the plugin will search file contents on a host. */
+export type SearchStrategy = {
+    readonly kind: 'git-grep';
+} | {
+    readonly kind: 'ripgrep';
+} | {
+    readonly kind: 'grep-bounded';
+};
+/** How the plugin will enumerate files for `@` completion on a host. */
+export type IndexStrategy = {
+    readonly kind: 'git-ls-files';
+} | {
+    readonly kind: 'find-bounded';
+};
+/** Pick the content-search strategy for a host. */
+export declare function searchStrategyFor(capabilities: RemoteCapabilities): SearchStrategy;
+/** Pick the file-enumeration strategy for a host. */
+export declare function indexStrategyFor(capabilities: RemoteCapabilities): IndexStrategy;
+/** Whether the host can run the plugin's file-transfer path. */
+export declare function canTransferBytes(capabilities: RemoteCapabilities): boolean;
+//# sourceMappingURL=capability.d.ts.map