dsh-over-ssh 0.0.0-stage → 0.1.0

package/lib/types/src/host/integration/root-registry.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The root registry: which directories a workspace has, and which backend serves each one.
+ *
+ * It owns exactly one {@link RoutedFileSystem} and mutates it in place, so the object handed to the
+ * core `ctx.fs` provider keeps its identity across root changes (a rebuilt router would silently
+ * invalidate every target key a caller is holding).
+ *
+ * Backend construction is injected: the local and remote backends need `node:fs` and a transport
+ * respectively, and keeping those out of this module is what makes the registry testable without a
+ * filesystem or a network.
+ *
+ * @module dsh-remote-workspace/integration/root-registry
+ */
+import type { Backend } from '../app/backend.ts';
+import { RoutedFileSystem, type RoutedTarget } from '../app/routed-fs.ts';
+import { type RootOptions, type RootRef } from '../domain/root.ts';
+/** One registered root together with its backend. */
+export interface RootRecord {
+    readonly key: string;
+    readonly root: RootRef;
+    readonly backend: Backend;
+}
+/** Options for {@link RootRegistry}. */
+export interface RootRegistryOptions {
+    /** Builds the backend for a local root. */
+    readonly createLocalBackend: (root: RootRef) => Backend;
+    /** Builds the backend for a remote root (one per connection in this design). */
+    readonly createRemoteBackend: (root: RootRef) => Backend;
+    readonly caseInsensitive?: boolean;
+    readonly maxReadBytes?: number;
+    /** Called after every mutation, so a client half or a status view can refresh. */
+    readonly onChanged?: (records: readonly RootRecord[]) => void;
+}
+/** Remote-root options. */
+export interface RemoteRootOptions extends RootOptions {
+    /** Local empty anchor directory; DSH requires a workspace path that exists on the host. */
+    readonly anchorPath?: string;
+}
+/** The set of roots of one workspace. */
+export declare class RootRegistry {
+    #private;
+    constructor(options: RootRegistryOptions);
+    /** The router every consumer reads through (`ctx.fs` wraps this). */
+    get routed(): RoutedFileSystem;
+    /** Registered roots in registration order. **Hidden roots are not here** (see {@link addHidden}). */
+    get records(): readonly RootRecord[];
+    /**
+     * Register a root that only the router knows about.
+     *
+     * Used for the file-level recycle bin, which has to live outside the caller's repository and therefore
+     * outside every visible root (ADR-0011). The backend is built exactly as for a visible root, so routing,
+     * `stat`, `list`, `move` and `remove` all behave normally — what changes is only that nothing lists it.
+     *
+     * Idempotent: registering the same key twice returns the existing record instead of throwing, because the
+     * caller (a bin resolver) may be asked for the same root repeatedly and a duplicate is not an error there.
+     *
+     * @param root - the hidden root to register.
+     * @returns the record, newly created or already present.
+     */
+    addHidden(root: RootRef): RootRecord;
+    /** Hidden roots registered so far (for tests and diagnostics — never for a user-facing list). */
+    get hiddenRecords(): readonly RootRecord[];
+    /** Look up one hidden root by key. */
+    getHidden(key: string): RootRecord | undefined;
+    /** Remove one hidden root by key (used when a connection's bin can no longer be resolved). */
+    removeHidden(key: string): boolean;
+    /** Register a local directory root. */
+    addLocal(path: string, options?: RootOptions): RootRecord;
+    /** Register a remote directory root on one connection. */
+    addRemote(connectionId: string, path: string, options?: RemoteRootOptions): RootRecord;
+    /** Register an already-built root reference. */
+    add(root: RootRef): RootRecord;
+    /** Remove one root by key. */
+    remove(key: string): boolean;
+    /**
+     * Remove one root by a key that may differ in case from the registered one.
+     *
+     * Windows local keys are folded by {@link rootKey}, while the file and the client keep the caller's case, so
+     * a removal that only matched verbatim removed the file entry and left the root live. The exact match is
+     * tried first; the fallback folds **only local keys**, where case is not significant on Windows and where
+     * the mismatch can only come from that spelling difference.
+     *
+     * @param key - the key the caller holds.
+     * @returns the key the root was registered under, so related caches can forget the same spelling; `undefined`
+     *   when nothing matched.
+     */
+    removeByLooseKey(key: string): string | undefined;
+    /** Replace every root (workspace switch, profile reload). Hidden roots go too: they are derived from these. */
+    reset(roots: readonly RootRef[]): void;
+    /** Roots belonging to one connection, for connection teardown and status. */
+    forConnection(connectionId: string): readonly RootRecord[];
+    /** Look one root up by key. */
+    get(key: string): RootRecord | undefined;
+    /**
+     * Remove every root of one connection (the connection was deleted or its transport is gone).
+     *
+     * @param connectionId - connection whose roots should disappear.
+     * @returns the removed records, so a caller can report what was dropped.
+     */
+    removeConnection(connectionId: string): readonly RootRecord[];
+}
+/** Declaration merging so the provider can read the registry from `ctx` with a typed property. */
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Root registry provided by this plugin. */
+        sshDevRoots: RootRegistry;
+    }
+}
+/** Narrow view used by the `ctx.fs` provider: it only needs the router. */
+export interface RoutedTargetOwner {
+    readonly routed: RoutedFileSystem;
+}
+/** Re-exported for consumers that only need the target type. */
+export type { RoutedTarget };
+//# sourceMappingURL=root-registry.d.ts.map

package/lib/types/src/host/integration/roots/anchor-directory.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The local anchor directory of a remote root.
+ *
+ * A remote root needs a **local** path to stand in for it, because a workspace path must exist on this machine
+ * (`root.ts` keeps that anchor on the `RootRef`). The platform then resolves that path with `realpath` when it
+ * opens a workspace on it, so the directory has to be **created**, not just computed:
+ *
+ *     workspace create failed: workspace/invalid-path: cannot create a Workspace at
+ *     "C:\\Users\\…\\.dsh\\over-ssh\\roots\\腾讯云\\39d1e90c": ENOENT …
+ *
+ * That failure is what this module exists to prevent. It lives in its own file so the rule ("a remote root's
+ * anchor must exist") is in one place and testable without a real home directory (红线 3: 外部依赖走注入).
+ *
+ * @module dsh-over-ssh/integration/anchor-directory
+ */
+import type { RootRef } from '../../domain/roots/root.ts';
+/** The one filesystem call this module needs. */
+export interface AnchorDirectoryIo {
+    /**
+     * Create a directory and its parents; a no-op when it already exists.
+     *
+     * The return value is ignored on purpose (`node:fs` answers with the first created path): this module only
+     * cares that the directory exists afterwards, so the seam stays as narrow as that fact.
+     */
+    mkdir(path: string, options: {
+        readonly recursive: true;
+    }): Promise<unknown> | unknown;
+}
+/**
+ * Make one root's local anchor exist.
+ *
+ * Local roots are their own anchor (the directory is the user's own path, which the platform checks itself), and
+ * a remote root without an anchor simply has nothing to create  - both cases return without touching the disk.
+ *
+ * @param root - the root that is about to become live.
+ * @param io - the injected filesystem.
+ * @returns nothing; a failure propagates so the caller decides whether it is fatal.
+ */
+export declare function ensureAnchorDirectory(root: Pick<RootRef, 'location' | 'anchorPath'>, io: AnchorDirectoryIo): Promise<void>;
+/**
+ * The last path segment of a remote root's anchor: **the remote folder's own name**.
+ *
+ * Why it matters: the platform titles a new workspace with `defaultWorkspaceTitle(path)` =
+ * `basename(path)` (`dsh-workspace/lib/types/paths.js:26-29`), and the directory-flow contract only carries a
+ * `path`  - there is no title parameter to pass (`DirectoryFlowOwnerProps`). So the segment this function
+ * returns **is** the name the user sees in the sidebar. A digest-only anchor made every remote workspace show
+ * up as `daf8c293`; this is what turns it into `stress_10`.
+ *
+ * Identity is *not* this function's job: the caller keeps a digest directory above it, so two remote paths with
+ * the same folder name still get two anchors (one canonical path per workspace).
+ *
+ * @param remotePath - absolute POSIX path on the remote host.
+ * @returns a segment that is safe to create on this machine and readable as a workspace name.
+ */
+export declare function anchorLeafName(remotePath: string): string;
+//# sourceMappingURL=anchor-directory.d.ts.map

package/lib/types/src/host/integration/roots/bin-root-resolver.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Decide, per root, where its file-level recycle bin lives — and make that place resolvable.
+ *
+ * The bin must sit **outside** the caller's repository (a "safe delete" that pollutes `git status` is not safe),
+ * yet it must be reachable by the router, which only resolves paths inside a registered root (ADR-0011). So the
+ * bin directory is registered as a **hidden root**: routable, but absent from `RootRegistry.records` and
+ * therefore from every user-facing list.
+ *
+ * This module owns the one decision that cannot be pure — *is the chosen directory usable?* — and it answers by
+ * measuring rather than assuming: the bin's parent must exist and must be on the **same device** as the root,
+ * because a cross-device `rename` is refused outright and the file-level bin has no copy fallback
+ * (`fs-commands.ts`, `recycle-bin-service.ts`). If a measurement fails, the bin stays inside the root — the old
+ * behaviour — and the reason is recorded, so a fallback is **visible** rather than silent.
+ *
+ * @module dsh-over-ssh/integration/bin-root-resolver
+ */
+import { type RootRef } from '../../domain/roots/root.ts';
+import type { RootRecord } from './root-registry.ts';
+/** Where one root's bin ended up, and why. */
+export interface BinRootChoice {
+    /** Absolute bin directory. */
+    readonly binRoot: string;
+    /** `beside` = outside the repository (the goal); `inside` = the documented fallback. */
+    readonly placement: 'beside' | 'inside';
+    /** Whether a hidden root was registered for it (only for `beside`). */
+    readonly hidden: boolean;
+    /** Human-readable reason for a fallback, or for an inconclusive measurement. */
+    note?: string;
+}
+/** What the resolver needs from its owner. */
+export interface BinRootResolverDeps {
+    /** Register a hidden root; returns the record. */
+    readonly addHiddenRoot: (root: RootRef) => RootRecord;
+    /** Drop a hidden root by key; used when a migration fails and the new location is abandoned. */
+    readonly removeHiddenRoot?: (key: string) => void;
+    /** The configured bin directory name (`limits.binDir`). */
+    readonly binDir: string;
+    /**
+     * Whether two paths are on the same device.
+     *
+     * `undefined` means **unknown**, and unknown is treated as *usable*: refusing to move a file into the bin is
+     * worse than putting the bin in an untidy place, and a transport without a working `stat` cannot answer.
+     */
+    readonly sameDevice: (root: RootRef, left: string, right: string) => Promise<boolean | undefined>;
+    /** Whether a directory exists. */
+    readonly exists: (root: RootRef, path: string) => Promise<boolean>;
+    /**
+     * Move a directory, creating the destination's parents.
+     *
+     * Only ever called for the **old bin → new bin** migration, where the two are on one device (already
+     * measured), so a plain `rename` is the whole implementation.
+     */
+    readonly moveDirectory: (root: RootRef, from: string, to: string) => Promise<void>;
+}
+/** The resolver handed to the recycle-bin wiring. */
+export interface BinRootResolver {
+    /**
+     * The bin directory for one root, registering a hidden root on first use.
+     *
+     * Synchronous by contract: the bin service asks repeatedly and cannot await (`binRootFor`). The measurement
+     * therefore happens in {@link BinRootResolver.prepare}, which the composition calls when a root is registered.
+     *
+     * @param root - the root being served.
+     * @returns its bin directory.
+     */
+    binRootFor: (root: RootRef) => string;
+    /** Measure and register a root's bin placement; call this when the root is added. */
+    prepare: (root: RootRef) => Promise<BinRootChoice>;
+    /** The choice made for one root, if any (for diagnostics). */
+    choiceFor: (root: RootRef) => BinRootChoice | undefined;
+    /** Drop one root's cached choice (its root was removed, or its connection changed). */
+    forget: (key: string) => void;
+}
+/**
+ * Build the resolver.
+ *
+ * @param deps - injected registration, configuration and measurement seams.
+ * @returns the resolver.
+ */
+export declare function createBinRootResolver(deps: BinRootResolverDeps): BinRootResolver;
+//# sourceMappingURL=bin-root-resolver.d.ts.map

package/lib/types/src/host/integration/roots/remote-home.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Resolve a connection's **home directory** on the remote host.
+ *
+ * Why this exists: the directory browser used to start remote listings at `/` (the filesystem root), which is
+ * almost never what someone adding a remote folder wants — and on a shared server it shows every other
+ * account's home. The obvious "fix" of spelling `home/<user>` is **wrong**, and this host proves it: the login
+ * user's home is `/home1/yezhiyuan` while `/home/yezhiyuan` does not exist, because the site spreads accounts
+ * across `/home`, `/home1`, `/home2`, … (an NFS/automount convention). Only the host can answer the question,
+ * so the answer is **probed, never guessed**.
+ *
+ * Precedence, highest first:
+ *
+ *  1. `remoteDefaultRoot` from the connection's own configuration — an explicit choice always wins.
+ *  2. A probe of the login user's home (`printf %s "$HOME"`), run over the connection's transport.
+ *  3. `/`, the old behaviour, when the probe cannot answer (a transport without command execution, a shell
+ *     that prints nothing, a path that is not absolute). Degrading to the previous behaviour keeps a browse
+ *     surface usable instead of empty.
+ *
+ * Results are cached per connection: the answer is a property of the account, not of the moment, and browsing
+ * re-asks on every level change. {@link RemoteHomeResolver.forget} drops one entry when a connection changes.
+ *
+ * @module dsh-over-ssh/integration/remote-home
+ */
+/** The fallback every path of last resort uses. */
+export declare const REMOTE_ROOT_FALLBACK = "/";
+/** Options for {@link createRemoteHomeResolver}. */
+export interface RemoteHomeResolverOptions {
+    /**
+     * Probe the login user's home over the connection's transport.
+     *
+     * @returns the absolute path, or `undefined` when the host could not answer.
+     */
+    readonly probe: (connectionId: string) => Promise<string | undefined>;
+    /** The connection's configured `remoteDefaultRoot`, when it has one. */
+    readonly configuredRoot?: (connectionId: string) => string | undefined;
+}
+/** The resolver the route calls. */
+export interface RemoteHomeResolver {
+    /**
+     * The directory a remote browse should start at.
+     *
+     * @param connectionId - the connection to resolve for.
+     * @returns an absolute path; never empty, and never throws (failures degrade to `/`).
+     */
+    resolve(connectionId: string): Promise<string>;
+    /** Drop one connection's cached answer (its profile changed, or it was removed). */
+    forget(connectionId: string): void;
+    /** Drop every cached answer. */
+    disposeAll(): void;
+}
+/**
+ * Whether a string is usable as a remote directory to list.
+ *
+ * The same fence the route applies to client-supplied paths: absolute, and no `..` segment. A probe that
+ * answers something else (a shell banner, a relative path, a trailing newline artefact) must not become the
+ * listing target.
+ *
+ * @param value - candidate path.
+ * @returns the normalised path, or `undefined` when it is unusable.
+ */
+export declare function normalizeRemoteDir(value: string | undefined): string | undefined;
+/**
+ * Build the resolver.
+ *
+ * @param options - injected probe and configuration reader.
+ * @returns the resolver.
+ */
+export declare function createRemoteHomeResolver(options: RemoteHomeResolverOptions): RemoteHomeResolver;
+//# sourceMappingURL=remote-home.d.ts.map

package/lib/types/src/host/integration/roots/root-registry.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The root registry: which directories a workspace has, and which backend serves each one.
+ *
+ * It owns exactly one {@link RoutedFileSystem} and mutates it in place, so the object handed to the
+ * core `ctx.fs` provider keeps its identity across root changes (a rebuilt router would silently
+ * invalidate every target key a caller is holding).
+ *
+ * Backend construction is injected: the local and remote backends need `node:fs` and a transport
+ * respectively, and keeping those out of this module is what makes the registry testable without a
+ * filesystem or a network.
+ *
+ * The registry also owns the **session workspace roots** ({@link RootRegistry.syncSessionWorkspaces}): one
+ * hidden, session-scoped local root per live session cwd, so a session's own working directory is always
+ * resolvable — including by absolute path without a cwd, which is how the platform reads the workspace while a
+ * turn starts.
+ *
+ * @module dsh-over-ssh/integration/root-registry
+ */
+import type { Backend } from '../../app/backend.ts';
+import { RoutedFileSystem, type RoutedTarget } from '../../app/routed-fs.ts';
+import { type RootOptions, type RootRef } from '../../domain/roots/root.ts';
+/** One registered root together with its backend. */
+export interface RootRecord {
+    readonly key: string;
+    readonly root: RootRef;
+    readonly backend: Backend;
+}
+/** Options for {@link RootRegistry}. */
+export interface RootRegistryOptions {
+    /** Builds the backend for a local root. */
+    readonly createLocalBackend: (root: RootRef) => Backend;
+    /** Builds the backend for a remote root (one per connection in this design). */
+    readonly createRemoteBackend: (root: RootRef) => Backend;
+    readonly caseInsensitive?: boolean;
+    readonly maxReadBytes?: number;
+    /** Called after every mutation, so a client half or a status view can refresh. */
+    readonly onChanged?: (records: readonly RootRecord[]) => void;
+}
+/** Remote-root options. */
+export interface RemoteRootOptions extends RootOptions {
+    /** Local empty anchor directory; DSH requires a workspace path that exists on the host. */
+    readonly anchorPath?: string;
+}
+/** The set of roots of one workspace. */
+export declare class RootRegistry {
+    #private;
+    constructor(options: RootRegistryOptions);
+    /** The router every consumer reads through (`ctx.fs` wraps this). */
+    get routed(): RoutedFileSystem;
+    /** Registered roots in registration order. **Hidden roots are not here** (see {@link addHidden}). */
+    get records(): readonly RootRecord[];
+    /**
+     * Register a root that only the router knows about.
+     *
+     * Used for the file-level recycle bin, which has to live outside the caller's repository and therefore
+     * outside every visible root (ADR-0011). The backend is built exactly as for a visible root, so routing,
+     * `stat`, `list`, `move` and `remove` all behave normally — what changes is only that nothing lists it.
+     *
+     * Idempotent: registering the same key twice returns the existing record instead of throwing, because the
+     * caller (a bin resolver) may be asked for the same root repeatedly and a duplicate is not an error there.
+     *
+     * @param root - the hidden root to register.
+     * @returns the record, newly created or already present.
+     */
+    addHidden(root: RootRef): RootRecord;
+    /** Hidden roots registered so far (for tests and diagnostics — never for a user-facing list). */
+    get hiddenRecords(): readonly RootRecord[];
+    /** Look up one hidden root by key. */
+    getHidden(key: string): RootRecord | undefined;
+    /** Remove one hidden root by key (used when a connection's bin can no longer be resolved). */
+    removeHidden(key: string): boolean;
+    /** Session-workspace roots added by {@link syncSessionWorkspaces} — diagnostics and tests, never a list. */
+    get sessionWorkspaceRecords(): readonly RootRecord[];
+    /**
+     * Register the **live sessions' working directories** as session-scoped local roots.
+     *
+     * The failure this fixes is turn-level, not tool-level: DSH reads the workspace (`AGENTS.md` and friends)
+     * through `ctx.fs` while a turn is starting, and `@deepseek-ai/dsh-agent-instructions` resolves that file by
+     * **absolute path without a cwd** (`fileSystem.resolve(join(current, marker), { signal })`). A cwd no
+     * registered root covers therefore failed the whole turn before the model was called — and a fallback keyed on
+     * `cwd` cannot help, because that call carries none. So every live session's working directory becomes a real
+     * local root: **in memory only** (never written to `user-roots.json`), scoped to its session
+     * (`workspaces: [cwd]`, which {@link rootVisibleToSession} already reads), and hidden
+     * ({@link addHidden}) so no surface built from `records` shows a directory the user never added.
+     *
+     * Idempotent and cheap: a cwd already covered by a local root is skipped, so a registered root keeps its
+     * priority and its backend; a cwd that already has its session root is reused. Roots whose session is gone are
+     * pruned — an access grant must not outlive the session it was created for — but only when the caller reports
+     * sessions at all: an empty list means "the session service was not readable", not "no session is live", and
+     * dropping every grant on a transient read failure would break live turns.
+     *
+     * @param cwds - working directories of the live sessions.
+     * @returns the session roots this call added (empty when every cwd was already covered).
+     */
+    syncSessionWorkspaces(cwds: readonly string[]): readonly RootRecord[];
+    /** Register a local directory root. */
+    addLocal(path: string, options?: RootOptions): RootRecord;
+    /** Register a remote directory root on one connection. */
+    addRemote(connectionId: string, path: string, options?: RemoteRootOptions): RootRecord;
+    /** Register an already-built root reference. */
+    add(root: RootRef): RootRecord;
+    /** Remove one root by key. */
+    remove(key: string): boolean;
+    /**
+     * Remove one root by a key that may differ in case from the registered one.
+     *
+     * Windows local keys are folded by {@link rootKey}, while the file and the client keep the caller's case, so
+     * a removal that only matched verbatim removed the file entry and left the root live. The exact match is
+     * tried first; the fallback folds **only local keys**, where case is not significant on Windows and where
+     * the mismatch can only come from that spelling difference.
+     *
+     * @param key - the key the caller holds.
+     * @returns the key the root was registered under, so related caches can forget the same spelling; `undefined`
+     *   when nothing matched.
+     */
+    removeByLooseKey(key: string): string | undefined;
+    /** Replace every root (workspace switch, profile reload). Hidden roots go too: they are derived from these. */
+    reset(roots: readonly RootRef[]): void;
+    /** Roots belonging to one connection, for connection teardown and status. */
+    forConnection(connectionId: string): readonly RootRecord[];
+    /** Look one root up by key. */
+    get(key: string): RootRecord | undefined;
+    /**
+     * Remove every root of one connection (the connection was deleted or its transport is gone).
+     *
+     * @param connectionId - connection whose roots should disappear.
+     * @returns the removed records, so a caller can report what was dropped.
+     */
+    removeConnection(connectionId: string): readonly RootRecord[];
+}
+/** Declaration merging so the provider can read the registry from `ctx` with a typed property. */
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Root registry provided by this plugin. */
+        sshDevRoots: RootRegistry;
+    }
+}
+/** Narrow view used by the `ctx.fs` provider: it only needs the router. */
+export interface RoutedTargetOwner {
+    readonly routed: RoutedFileSystem;
+}
+/** Re-exported for consumers that only need the target type. */
+export type { RoutedTarget };
+//# sourceMappingURL=root-registry.d.ts.map