dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,108 @@
+/**
+ * Root references: one project root is either a local directory or a remote directory on
+ * one connection. Remote roots additionally carry a local *anchor* directory, because DSH
+ * requires a workspace path that exists on the host filesystem.
+ *
+ * @module dsh-over-ssh/domain/root
+ */
+/** Where a root lives. */
+export type RootLocation = 'local' | 'remote';
+/** One project root. */
+export interface RootRef {
+    /** Local or remote. */
+    readonly location: RootLocation;
+    /** Connection id; present exactly for remote roots. */
+    readonly connectionId?: string;
+    /** Absolute local path, or absolute POSIX path for a remote root. */
+    readonly path: string;
+    /** Whether the sandbox fence admits writes under this root. */
+    readonly writable: boolean;
+    /** Local anchor directory for a remote root (empty directory, never mirrored content). */
+    readonly anchorPath?: string;
+    /** Display label; defaults to the final path segment. */
+    readonly label?: string;
+    /**
+     * The workspaces (session cwd paths) that added this root.
+     *
+     * **Absent means "no session added it"**, which under session isolation means "no session may use it"
+     * ({@link rootVisibleToSession} in `./session-roots.ts`). It is not a default-allow: the user-roots file has
+     * carried this field since the 「添加目录」 grouping landed, and the settings panel writes unscoped roots on
+     * purpose (its form has no scope field).
+     */
+    readonly workspaces?: readonly string[];
+    /**
+     * The **sessions** (conversation ids) that added this root — the strict identity behind {@link workspaces}.
+     *
+     * `workspaces` answers "which workspace added it", which cannot separate two conversations opened on the
+     * same directory; this field can. When it is present **and** the caller carries a session id, the route
+     * table decides by session and never consults the cwd (ADR-0013, `domain/roots/session-roots.ts`). Absent
+     * means "written before ADR-0013" — such a root keeps the workspace-level rule, so existing data does not
+     * lose access on upgrade.
+     */
+    readonly sessions?: readonly string[];
+    /**
+     * Whether this root is **deployment-wide** rather than a session artifact.
+     *
+     * True for roots declared in the plugin's `config.roots`: they are infrastructure the deployment declares once
+     * (the stage-2 requirement "a local root covering the current workspace" is one of them), so every session may
+     * use them. False/absent for roots the user added through the panel or 「添加目录」 — those are per-session and
+     * are gated by {@link workspaces} (see `rootVisibleToSession`).
+     */
+    readonly shared?: boolean;
+}
+/** Options shared by both root kinds. */
+export interface RootOptions {
+    /** Whether writes under this root are allowed; defaults to true. */
+    readonly writable?: boolean;
+    /** Display label override. */
+    readonly label?: string;
+    /** Workspaces that added this root; see {@link RootRef.workspaces}. */
+    readonly workspaces?: readonly string[];
+    /** Sessions that added this root; see {@link RootRef.sessions}. */
+    readonly sessions?: readonly string[];
+    /** Deployment-wide root; see {@link RootRef.shared}. */
+    readonly shared?: boolean;
+}
+/** Create a remote root, validating the connection id and remote path. */
+export declare function makeRemoteRoot(connectionId: string, remotePath: string, options?: RootOptions & {
+    readonly anchorPath?: string;
+}): RootRef;
+/**
+ * Create a local root from an absolute host path.
+ *
+ * The stored path **preserves the caller's case** (only separators, `.`/`..` and the drive letter
+ * are canonicalised). Case folding belongs to comparison and keying — `rootKey` folds, and
+ * `localPathContains` folds on request — because the root's path is also what the UI shows and what
+ * a child process receives via `processPath`.
+ */
+export declare function makeLocalRoot(path: string, options?: RootOptions): RootRef;
+/** Whether a host path is absolute in either the Windows or the POSIX spelling. */
+export declare function isAbsoluteLocalPath(path: string): boolean;
+/**
+ * Normalize a host path for comparison: separators to `/`, `.`/`..` resolved, trailing
+ * separators dropped, and (optionally) the drive letter and case folded.
+ *
+ * @param path - host path in either separator spelling.
+ * @param options - `caseInsensitive` folds case for comparison keys.
+ * @returns the normalized path.
+ */
+export declare function normalizeLocalPath(path: string, options?: {
+    readonly caseInsensitive?: boolean;
+}): string;
+/** Whether a host path is `root` itself or a descendant of it. */
+export declare function localPathContains(root: string, candidate: string, options?: {
+    readonly caseInsensitive?: boolean;
+}): boolean;
+/** Stable identity of a root, used as a cache/route key. */
+export declare function rootKey(root: RootRef): string;
+/** The model-facing and UI-facing spelling of a root's directory. */
+export declare function rootDisplay(root: RootRef): string;
+/** The display label of a root: explicit label, else the final path segment. */
+export declare function rootLabel(root: RootRef): string;
+/** Whether two roots of the same location overlap (one contains the other). */
+export declare function rootsOverlap(left: RootRef, right: RootRef): boolean;
+/** Validate a root reference produced outside this module. */
+export declare function validateRoot(root: RootRef): void;
+/** FNV-1a (32-bit) over UTF-16 code units, rendered as 8 lowercase hex characters. */
+export declare function fnv1aHex(input: string): string;
+//# sourceMappingURL=root.d.ts.map

package/lib/types/src/host/domain/roots/route-table.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The route table: turns a model-facing path into one backend plus a root-relative path.
+ *
+ * This is the heart of "one workspace, several roots". Resolution order is deliberate, and
+ * every branch is a documented rule rather than a heuristic:
+ *
+ *  1. `ssh://<connection>/abs` — the explicit remote grammar always wins.
+ *  2. Anchor match — a path (or the session cwd) under a remote root's local anchor resolves
+ *     to that remote root. The anchor is what makes a remote root a legal DSH workspace.
+ *  3. Local root containment — absolute host paths, and `cwd`-relative spellings.
+ *  4. Bare POSIX absolute path matching remote roots — needed because a prompt lists remote
+ *     roots in POSIX spelling; two equally specific remote roots on different connections
+ *     are reported as ambiguous instead of being guessed.
+ *
+ * @module dsh-over-ssh/domain/route-table
+ */
+import { SshDevError } from '../errors.ts';
+import { type RootRef } from './root.ts';
+import { type SessionIdentity } from './session-roots.ts';
+/** One resolved route. */
+export interface RouteTarget {
+    /** The root the path belongs to. */
+    readonly root: RootRef;
+    /** Root-relative spelling with `/` separators; an empty string means the root itself. */
+    readonly relativePath: string;
+    /** Stable backend key; one backend serves all paths of one root. */
+    readonly backendKey: string;
+}
+/** Per-call resolution options. */
+export interface RouteOptions {
+    /** Session working directory used for relative spellings. */
+    readonly cwd?: string;
+    /**
+     * Who is asking, when the caller knows more than its cwd (ADR-0013).
+     *
+     * The route table never invents this: the fs provider reads it from the session scope the tool dispatcher
+     * carries down (`integration/session-scope.ts`) and hands it over. `undefined` means "no session identity" —
+     * the workspace-level rule then stands, which is exactly the behaviour before ADR-0013.
+     */
+    readonly session?: SessionIdentity;
+    /**
+     * The asking session's own working directory, when the caller did not supply a `cwd`.
+     *
+     * Used **only** by the implicit session root (a session's own directory is always readable to it) — never by
+     * the gate below, which must keep seeing exactly what the platform passed. Synthesising a `cwd` for the gate
+     * would apply the workspace rule to calls that legitimately carry none, which is the failure ADR-0012 §4
+     * boundary 2 records (a whole turn lost before the model was called).
+     */
+    readonly sessionCwd?: string;
+    /** Override host-path case folding (defaults to the platform). */
+    readonly caseInsensitive?: boolean;
+}
+/** A path resolved to a root, or a diagnostic reason why it could not be. */
+export type RouteOutcome = {
+    readonly ok: true;
+    readonly target: RouteTarget;
+} | {
+    readonly ok: false;
+    readonly error: SshDevError;
+};
+/** Resolution table over an ordered set of roots. */
+export declare class RouteTable {
+    #private;
+    constructor(roots?: readonly RootRef[], options?: {
+        readonly caseInsensitive?: boolean;
+    });
+    /** Roots in registration order. */
+    get roots(): readonly RootRef[];
+    /**
+     * Register a root.
+     *
+     * @param root - root to add.
+     * @throws SshDevError `ROOT_INVALID` when the root is malformed or already registered.
+     */
+    add(root: RootRef): void;
+    /** Remove a root by its key; returns whether it was present. */
+    remove(key: string): boolean;
+    /** Replace every root; throws like {@link add} when any root is invalid. */
+    reset(roots: readonly RootRef[]): void;
+    /**
+     * Resolve a path, then apply the **session gate**.
+     *
+     * Two failures wear the same code on purpose: "no root covers this path" and "the root that covers it belongs
+     * to another session" are both `ROOT_OUTSIDE`, because from the caller's side they are the same fact — this
+     * session cannot use that path. The message and the `root` detail say which one it was.
+     *
+     * @param input - model-facing, host or remote spelling.
+     * @param options - session cwd (also the session identity, see {@link rootVisibleToSession}) and case folding.
+     * @returns the resolved route, or a failure carrying `ROOT_OUTSIDE` / `ROOT_AMBIGUOUS`.
+     */
+    tryResolve(input: string, options?: RouteOptions): RouteOutcome;
+    /**
+     * Resolve a path or throw.
+     *
+     * @param input - path to resolve.
+     * @param options - session cwd and case-folding override.
+     * @returns the resolved route.
+     * @throws SshDevError `ROOT_OUTSIDE` or `ROOT_AMBIGUOUS`.
+     */
+    resolve(input: string, options?: RouteOptions): RouteTarget;
+}
+//# sourceMappingURL=route-table.d.ts.map

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

@@ -0,0 +1,151 @@
+/**
+ * Session-scoped remote roots: which remote directories **this** conversation may target.
+ *
+ * The problem this solves. 「添加目录」 registers a directory for one session (the entry's `workspaces` list
+ * holds that session's workspace path), and until now that was a **visibility** rule only: the client card
+ * listed the directory, but every `remote_*` tool picked its root from the agent's session cwd alone
+ * (`remote-tools.ts` `targetFor`). A session opened on a local folder — `D:\project\x` — therefore could add
+ * `165服务器:/home1/me/work/android14`, see it in the card, and still get
+ * `工作目录不在任何远端根内：D:\project\x` from every remote tool. The user's own words:
+ * 「我一个本地目录的会话，我添加远程的路径，这个会话也能正常访问远程路径」.
+ *
+ * The rule implemented here is the narrow one that makes that work without turning 「添加目录」 into a
+ * process-wide switch:
+ *
+ *  1. A cwd that resolves to a remote root **wins** (the pre-existing behaviour, unchanged). A session living
+ *     on a remote workspace keeps targeting it, and nothing about `ssh://` resolution changes.
+ *  2. Otherwise, the roots **this session added** are candidates. Exactly one candidate is used; zero is the
+ *     old `ROOT_OUTSIDE` error; two or more is refused by name instead of guessed — the same stance the
+ *     route table already takes for two remote roots with the same spelling (`ROOT_AMBIGUOUS`).
+ *
+ * Why "scoped to this session" was read from the **workspace path** rather than from a session id: that is
+ * what `add-root` wrote (`session-directory.ts` passes `workspaces: [state.workspacePath]`), and it was the
+ * only field the persisted file carried. **ADR-0013 changes that**: the platform does not hand a session id to
+ * `ctx.fs`, but it does hand one to every tool execution, and `integration/session-scope.ts` carries it down.
+ * Entries now also record `sessions`, and when both the root and the caller have one, **the session decides**
+ * and the workspace path is not consulted. A fork inherits its ancestors' entries ({@link SessionIdentity}).
+ * Entries written before ADR-0013 carry no `sessions` and keep the workspace-level rule unchanged.
+ *
+ * Pure: no filesystem, no transport, no platform types — the caller injects the entries. That is what makes
+ * the rule testable offline (红线 2/3).
+ *
+ * @module dsh-over-ssh/domain/roots/session-roots
+ */
+import { type RootRef } from './root.ts';
+/** One persisted root entry, as far as this module needs to read it. */
+export interface SessionRootEntry {
+    readonly location: 'local' | 'remote';
+    readonly path: string;
+    readonly connectionId?: string;
+    /** The workspaces (session cwd paths) that added this root. Absent means "no session added it". */
+    readonly workspaces?: readonly string[];
+    /** The **sessions** (conversation ids) that added this root. Absent on entries written before ADR-0013. */
+    readonly sessions?: readonly string[];
+}
+/**
+ * Who is asking: the cwd every caller already carries, plus the session identity when one is available.
+ *
+ * `sessionId` is the strict identity — two conversations in the same workspace differ here and nowhere else.
+ * `ancestors` are that session's fork lineage, nearest first: a fork inherits the directories its parent added
+ * (the product decision recorded in ADR-0013), so a root listed for any ancestor is listed for the fork too.
+ * Both are optional because an agentless call (a CLI, a config replay) has neither.
+ */
+export interface SessionIdentity {
+    /** The asking session's id, when one is known. */
+    readonly sessionId?: string | undefined;
+    /** The asking session's fork ancestors, nearest first. */
+    readonly ancestors?: readonly string[] | undefined;
+}
+/** The target shape the tools consume; kept structural so this module imports no integration code. */
+export interface SessionRootTarget {
+    readonly connectionId: string;
+    readonly root: string;
+}
+/** Outcome of {@link resolveSessionRemoteRoot}. */
+export type SessionRootOutcome = {
+    readonly ok: true;
+    readonly target: SessionRootTarget;
+}
+/** Nothing this session added is a remote root: the caller keeps its own error. */
+ | {
+    readonly ok: false;
+    readonly reason: 'none';
+}
+/** Several added remote roots: refused by name rather than guessed. */
+ | {
+    readonly ok: false;
+    readonly reason: 'ambiguous';
+    readonly candidates: readonly SessionRootTarget[];
+};
+/**
+ * Compare two host paths the way the persisted `workspaces` field is written.
+ *
+ * Windows paths are case-insensitive, and the file stores whatever the platform reported at add time while
+ * the session header may spell the same directory with different case. Folding here is what keeps a
+ * `D:\Project\X` session from losing the directory it added as `d:\project\x`.
+ *
+ * @param left - one host path.
+ * @param right - the other host path.
+ * @returns whether they name the same directory.
+ */
+export declare function sameWorkspacePath(left: string, right: string): boolean;
+/**
+ * The remote roots one session added, in file order.
+ *
+ * @param entries - the persisted root entries.
+ * @param workspacePath - the session's workspace path (its cwd), or `undefined` when the platform gave none.
+ * @param identity - the session identity, when the platform could supply one (ADR-0013).
+ * @returns the added remote roots, each with its connection and absolute remote path.
+ */
+export declare function remoteRootsAddedBy(entries: readonly SessionRootEntry[], workspacePath: string | undefined, identity?: SessionIdentity): readonly SessionRootTarget[];
+/**
+ * Pick the remote root a session should target when its cwd names none.
+ *
+ * @param entries - the persisted root entries.
+ * @param workspacePath - the session's workspace path (its cwd).
+ * @param identity - the session identity, when the platform could supply one (ADR-0013).
+ * @returns the single added remote root, a refusal, or `none` when the session added no remote directory.
+ */
+export declare function resolveSessionRemoteRoot(entries: readonly SessionRootEntry[], workspacePath: string | undefined, identity?: SessionIdentity): SessionRootOutcome;
+/**
+ * The model-facing text for a session that added more than one remote directory.
+ *
+ * @param candidates - the added remote roots.
+ * @returns one sentence naming every candidate and the way to disambiguate.
+ */
+export declare function ambiguousSessionRootMessage(candidates: readonly SessionRootTarget[]): string;
+/**
+ * Whether one root may serve one session — the **access** rule, not the view rule.
+ *
+ * 「添加目录」 scopes a root to the workspace that added it (`workspaces`). Until now that was a visibility fact
+ * only: the panel listed the session's own roots while the router answered **any** registered root for **any**
+ * caller (`routed-fs.ts`: "Filtering is a view fact, not a sandbox"). With the routed filesystem mounted
+ * (`远程工作区-路由fs`, stage 2) that gap is an access gap — session B could read a directory only session A
+ * added, merely by spelling its path. This predicate closes it, and it is the one place the rule lives: the route
+ * table calls it for every resolution, so every file tool inherits it.
+ *
+ * **Two identities, in this order (ADR-0013).** When the root carries `sessions` **and** the caller has a
+ * session id, the session decides — the workspace path is not consulted. That is what separates two
+ * conversations opened on the same directory: they share a cwd and differ only here. Otherwise (an entry from
+ * before ADR-0013, or an agentless call) the workspace path stands in, and the root belongs to a session in
+ * exactly two ways:
+ *
+ *  1. it was **added to this workspace** — `workspaces` names the session's cwd ({@link sameWorkspacePath});
+ *  2. the session **lives on** the root — a remote root's anchor directory *is* a workspace path, so a session
+ *     opened on that anchor (or inside it) is that workspace's session. This keeps a remote workspace usable
+ *     when its root was registered before the `workspaces` grouping existed.
+ *
+ * Everything else is refused, **including a root with no `workspaces` at all**: the settings panel's unscoped
+ * roots are "added to no session" (its own copy says so), so a session has to opt in with 「添加目录」 first.
+ * That is a deliberate behaviour change — see ADR-0012 for the migration note.
+ *
+ * A caller with neither cwd nor session is not a session call — agentless config replay, a CLI — and keeps the
+ * plugin-wide view; widening a *session* silently would be the bug this function exists to stop.
+ *
+ * @param root - one registered root.
+ * @param cwd - the asking session's cwd, or `undefined` for an agentless call.
+ * @param identity - the asking session's identity, when the platform could supply one (ADR-0013).
+ * @returns whether the root may serve that caller.
+ */
+export declare function rootVisibleToSession(root: RootRef, cwd: string | undefined, identity?: SessionIdentity): boolean;
+//# sourceMappingURL=session-roots.d.ts.map

package/lib/types/src/host/domain/roots/ssh-config.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `~/.ssh/config` reader used by the "import aliases" flow.
+ *
+ * Only the keys this plugin can represent are read. OpenSSH keeps the first obtained value
+ * for a key inside one Host block, so this parser does the same; `Host` blocks accumulate
+ * their patterns and later blocks shadow earlier ones for the same literal alias.
+ *
+ * @module dsh-over-ssh/domain/ssh-config
+ */
+/** One parsed `Host` block. */
+export interface SshConfigEntry {
+    /** Patterns on the `Host` line, in order. */
+    readonly patterns: readonly string[];
+    /** `HostName` value when present. */
+    readonly hostName?: string;
+    /** `User` value when present. */
+    readonly user?: string;
+    /** `Port` value when present and numeric. */
+    readonly port?: number;
+    /** All `IdentityFile` values, in order. */
+    readonly identityFiles: readonly string[];
+    /** `ProxyJump` value when present and not `none`. */
+    readonly proxyJump?: string;
+    /** `Include` patterns (this parser does not read included files). */
+    readonly includes: readonly string[];
+    /** 1-based line number of the `Host` line. */
+    readonly line: number;
+}
+/** A connection the import flow can turn into a profile. */
+export interface SshConfigImportDraft {
+    /** The literal alias, also usable as the `ssh` target. */
+    readonly alias: string;
+    /** Resolved host name (falls back to the alias). */
+    readonly hostName: string;
+    readonly user?: string;
+    readonly port?: number;
+    readonly identityFile?: string;
+    readonly proxyJump?: string;
+}
+/** One alias the import flow refuses, with the reason shown to the user. */
+export interface SkippedAlias {
+    readonly pattern: string;
+    readonly reason: string;
+    readonly line: number;
+}
+/** Result of selecting importable aliases. */
+export interface SshConfigImportResult {
+    readonly drafts: readonly SshConfigImportDraft[];
+    readonly skipped: readonly SkippedAlias[];
+}
+/**
+ * Parse the textual content of an OpenSSH client config.
+ *
+ * @param text - file content.
+ * @returns parsed Host blocks in file order.
+ */
+export declare function parseSshConfig(text: string): SshConfigEntry[];
+/** Whether a Host pattern names one concrete host rather than a wildcard set. */
+export declare function isConcretePattern(pattern: string): boolean;
+/** Expand a leading `~` using the host home directory. */
+export declare function expandHome(path: string, home: string): string;
+/**
+ * Select the aliases the import flow will offer, and explain what it refuses.
+ *
+ * @param entries - parsed Host blocks.
+ * @param options - `home` expands `~` in identity paths; `excluded` drops known aliases.
+ * @returns importable drafts plus skipped patterns.
+ */
+export declare function importableEntries(entries: readonly SshConfigEntry[], options?: {
+    readonly home?: string;
+    readonly excluded?: readonly string[];
+}): SshConfigImportResult;
+//# sourceMappingURL=ssh-config.d.ts.map

package/lib/types/src/host/domain/route-table.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The route table: turns a model-facing path into one backend plus a root-relative path.
+ *
+ * This is the heart of "one workspace, several roots". Resolution order is deliberate, and
+ * every branch is a documented rule rather than a heuristic:
+ *
+ *  1. `ssh://<connection>/abs` — the explicit remote grammar always wins.
+ *  2. Anchor match — a path (or the session cwd) under a remote root's local anchor resolves
+ *     to that remote root. The anchor is what makes a remote root a legal DSH workspace.
+ *  3. Local root containment — absolute host paths, and `cwd`-relative spellings.
+ *  4. Bare POSIX absolute path matching remote roots — needed because a prompt lists remote
+ *     roots in POSIX spelling; two equally specific remote roots on different connections
+ *     are reported as ambiguous instead of being guessed.
+ *
+ * @module dsh-remote-workspace/domain/route-table
+ */
+import { SshDevError } from './errors.ts';
+import { type RootRef } from './root.ts';
+/** One resolved route. */
+export interface RouteTarget {
+    /** The root the path belongs to. */
+    readonly root: RootRef;
+    /** Root-relative spelling with `/` separators; an empty string means the root itself. */
+    readonly relativePath: string;
+    /** Stable backend key; one backend serves all paths of one root. */
+    readonly backendKey: string;
+}
+/** Per-call resolution options. */
+export interface RouteOptions {
+    /** Session working directory used for relative spellings. */
+    readonly cwd?: string;
+    /** Override host-path case folding (defaults to the platform). */
+    readonly caseInsensitive?: boolean;
+}
+/** A path resolved to a root, or a diagnostic reason why it could not be. */
+export type RouteOutcome = {
+    readonly ok: true;
+    readonly target: RouteTarget;
+} | {
+    readonly ok: false;
+    readonly error: SshDevError;
+};
+/** Resolution table over an ordered set of roots. */
+export declare class RouteTable {
+    #private;
+    constructor(roots?: readonly RootRef[], options?: {
+        readonly caseInsensitive?: boolean;
+    });
+    /** Roots in registration order. */
+    get roots(): readonly RootRef[];
+    /**
+     * Register a root.
+     *
+     * @param root - root to add.
+     * @throws SshDevError `ROOT_INVALID` when the root is malformed or already registered.
+     */
+    add(root: RootRef): void;
+    /** Remove a root by its key; returns whether it was present. */
+    remove(key: string): boolean;
+    /** Replace every root; throws like {@link add} when any root is invalid. */
+    reset(roots: readonly RootRef[]): void;
+    /**
+     * Resolve a path.
+     *
+     * @param input - model-facing, host or remote spelling.
+     * @param options - session cwd and case-folding override.
+     * @returns the resolved route, or a failure carrying `ROOT_OUTSIDE` / `ROOT_AMBIGUOUS`.
+     */
+    tryResolve(input: string, options?: RouteOptions): RouteOutcome;
+    /**
+     * Resolve a path or throw.
+     *
+     * @param input - path to resolve.
+     * @param options - session cwd and case-folding override.
+     * @returns the resolved route.
+     * @throws SshDevError `ROOT_OUTSIDE` or `ROOT_AMBIGUOUS`.
+     */
+    resolve(input: string, options?: RouteOptions): RouteTarget;
+}
+//# sourceMappingURL=route-table.d.ts.map