dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,219 @@
+/**
+ * Wire the panel's HTTP route to the live roots, the live connections and the persisted panel state.
+ *
+ * This module is the seam the API handler and the registry never see each other through: the handler is pure
+ * request/response (see {@link createRootsApi}), the registry owns live routing, and this file is the only
+ * place that knows both. It exists as its own module so the wiring is one small, reviewable call in the entry
+ * rather than twenty lines inside it.
+ *
+ * Two behaviours worth stating:
+ *
+ *  - **Startup merge**: roots and connections the panel wrote survive a restart because they are read back
+ *    from `user-roots.json` and applied to the live side at load. A file that cannot be applied is reported as
+ *    a warning, never as a load failure: losing the panel's extra roots must not stop the plugin.
+ *  - **Same-origin only**: the route is registered on the browser carrier (`ctx.webServer`). When that service
+ *    is absent (a headless profile), the plugin still works and simply has no panel data channel — the reason
+ *    is logged instead of thrown.
+ *
+ * @module dsh-over-ssh/host/integration/roots-wiring
+ */
+import { type CredentialsSeam, type RemoteFileOperations, type TransferReport, type RootsApi } from '../../app/roots/roots-api.ts';
+import { type UserConnectionRecord, type UserRootEntry, type UserRootsIo, type UserRootsStore } from '../../app/roots/user-roots.ts';
+/** The browser HTTP carrier the host exposes; only the one method this wiring needs. */
+export interface RootsRouteHost {
+    register(route: {
+        readonly kind: 'exact';
+        readonly path: string;
+        readonly handler: (req: never, res: never) => Promise<void>;
+    }): () => void;
+}
+/**
+ * Deferred carrier: run `callback` once `webServer` is **available**, and again whenever it comes back.
+ *
+ * `ctx.inject` is the platform's documented way to depend on a service that a later composition layer
+ * provides (`dsh-client-connection` does exactly this for the `/api` route). A bare `ctx.get('webServer')`
+ * at activation time is **not** equivalent: measured on the packaged 0.2.0-rc.2 runtime
+ * (`dsh --profile web`, `ctx.get('webServer') === undefined`, `'webServer' in ctx === false`) while
+ * `ctx.get('tools')` was already an object — the carrier row is constructed after the plugin entries
+ * activate. With `ctx.get` the route was never registered, the shell's `dsh-app://app/api/…` proxy fell
+ * through to the SPA fallback, and the panel reported `http-404` while the plugin looked healthy.
+ *
+ * `scoped.get` is typed `unknown` and narrowed by {@link asRootsRouteHost} rather than declared as the
+ * carrier type: this module stays clear of `@deepseek-ai/*` types (红线 2), and a cordis `Context` is
+ * structurally richer than this one-method seam, so the narrower declaration would reject the real `ctx`.
+ */
+export interface RootsRouteHostProvider {
+    inject(names: readonly string[], callback: (scoped: {
+        get(name: string): unknown;
+    }) => void | (() => void)): unknown;
+}
+/** Why a route could not be registered; both variants are warnings, never activation failures. */
+export type RootsRouteWarning = 
+/** No `webServer` service ever appeared (a headless composition): the panel has no data channel. */
+{
+    readonly kind: 'no-carrier';
+}
+/** The carrier refused the registration, e.g. a duplicate `(kind, path)` pair. */
+ | {
+    readonly kind: 'refused';
+    readonly reason: string;
+};
+/** Everything the wiring needs from the entry. */
+export interface RootsWiringDeps {
+    /** Plugin state directory; `user-roots.json` lives inside it. */
+    readonly stateDir: string;
+    /**
+     * Optional: the directory remote roots' local anchors live under.
+     *
+     * Passed through to the `GET` snapshot as `anchorRoot`: a client uses it to recognise a session whose cwd
+     * is a remote workspace, which is otherwise indistinguishable from a local folder (the shell has no
+     * per-workspace icon and no workspace-row slot). Absent means the snapshot simply omits it.
+     */
+    readonly anchorRootDir?: string | undefined;
+    /** Live roots (the registry's records). */
+    readonly listRoots: () => readonly unknown[];
+    /** Live connections (the entry's profiles). */
+    readonly listConnections: () => readonly unknown[];
+    /** Make a root live and routable. */
+    /**
+     * Make a root live. **Awaitable**: registering a remote root also creates its local anchor directory, and the
+     * panel hands that path straight to the platform's `createWorkspace`, which resolves it with `realpath`.
+     */
+    readonly registerRoot: (entry: UserRootEntry) => Promise<void> | void;
+    /** Drop a root from the live side. */
+    readonly unregisterRoot: (key: string) => void;
+    /** Make a connection usable without a restart. */
+    readonly applyConnection: (entry: UserConnectionRecord, previousId: string) => void;
+    /**
+     * Forget a deleted connection on the live side: its profile, and everything cached per connection.
+     *
+     * Required, not optional: the `GET` answer lists connections from the live side, so a wiring that omitted this
+     * would keep answering with a connection the user deleted (see `RootsApiDeps.removeConnection`). Making it
+     * required means the compiler — not a reviewer — notices a wiring that forgot it.
+     */
+    readonly removeConnection: (id: string) => void;
+    /**
+     * Optional: list one directory on a connection (names and kinds only), for the `list-remote` action.
+     *
+     * Passed through to the handler untouched: this wiring knows nothing about transports, and a composition
+     * without it simply answers that action with an explicit failure.
+     */
+    readonly listRemoteDirectory?: ((input: {
+        readonly connectionId: string;
+        readonly path: string;
+    }) => Promise<readonly unknown[]> | readonly unknown[]) | undefined;
+    /**
+     * Optional: the directory a remote browse starts at when the client names no path.
+     *
+     * The same pass-through as {@link RootsWiringDeps.listRemoteDirectory}, and the same reason to have it: the
+     * start directory is the remote login user's home, which only the transport can answer (an account may live
+     * under `/home`, `/home1`, …). A composition without it degrades to `/`, the pre-existing behaviour.
+     */
+    readonly remoteHomeDirectory?: ((connectionId: string) => Promise<string> | string) | undefined;
+    /**
+     * Optional: list one directory **on this machine** (names and kinds only), for the `list-local` action.
+     *
+     * The same pass-through as {@link RootsWiringDeps.listRemoteDirectory}, and the same reason to have it: a
+     * profile whose platform directory picker offers only the native dialog (no `browse` capability) still gets
+     * a working browser from the host, which always has `node:fs`. A composition that does not provide it
+     * answers that action with an explicit failure rather than pretending the directory is empty.
+     */
+    readonly listLocalDirectory?: ((input: {
+        readonly path: string;
+    }) => Promise<readonly unknown[]> | readonly unknown[]) | undefined;
+    /**
+     * Optional: the text of the user's own `~/.ssh/config`, for the import flow (FR-2.1.4).
+     *
+     * The same pass-through as the directory seams, and the same reason: this wiring reads no files, and the
+     * handler wants **text** so the parsing stays a pure function under test. Absent means the import actions
+     * answer an explicit failure.
+     */
+    readonly readSshConfig?: (() => Promise<string | undefined> | string | undefined) | undefined;
+    /**
+     * Optional: the mutating remote-file operations the file tree needs (FR-2.2.2).
+     *
+     * The same pass-through as the other seams: this wiring resolves nothing itself. Absent means those actions
+     * answer an explicit refusal.
+     */
+    readonly remoteFiles?: RemoteFileOperations | undefined;
+    /**
+     * Optional: the in-flight and recent transfers (FR-2.6.4).
+     *
+     * The same pass-through as the other seams. Absent means the transfer actions answer an explicit refusal.
+     */
+    readonly transfers?: TransferReport | undefined;
+    /**
+     * Optional: the credential store, read **per request** (a getter, not a value — see `RootsApiDeps`).
+     *
+     * Absent in a composition with no credentials service: password connections are then refused with an
+     * explicit 400 instead of being written into a file that is documented to hold no secrets.
+     */
+    readonly readCredentials?: (() => CredentialsSeam | undefined) | undefined;
+    /** Optional: really connect to one saved connection (the panel's 「测试」 button). */
+    readonly testConnection?: ((id: string) => Promise<unknown> | unknown) | undefined;
+    /** Optional: the deferred `ctx.webServer` carrier. Absent in a headless profile. */
+    readonly webServerProvider?: RootsRouteHostProvider | undefined;
+    /** Optional file-system binding for the store; tests inject an in-memory one (红线 3). */
+    readonly io?: UserRootsIo | undefined;
+}
+/** What the entry holds on to. */
+export interface RootsWiring {
+    readonly api: RootsApi;
+    readonly store: UserRootsStore;
+    /** Apply everything the panel persisted, so UI edits survive a restart. */
+    mergeUserRoots(): Promise<{
+        readonly roots: number;
+        readonly connections: number;
+        readonly warnings: readonly string[];
+    }>;
+    /**
+     * Human-readable warnings collected while trying to own the route: an absent carrier, or one that
+     * refused the registration. Exposed so the entry can log them **after** activation, when `ctx.logger`
+     * itself resolves (it is undefined at activation time, the same ordering fact this file works around).
+     */
+    readonly routeWarnings: () => readonly string[];
+    /**
+     * The route's own facts, for the entry's one-line diagnostic.
+     *
+     * `injectRan` and `routeRegistered` are the two facts nothing else can answer: the first says whether the
+     * deferred carrier callback ever executed (a callback that never ran means `webServer` never appeared),
+     * the second whether the carrier actually accepted the route. Both are read **after** activation, on the
+     * next tick, because at activation time neither can be true yet on the packaged runtime.
+     */
+    readonly routeFacts: () => RootsRouteFacts;
+    readonly dispose: () => void;
+}
+/** What the wiring knows about its own route attempt; the rest of the diagnostic comes from the entry. */
+export interface RootsRouteFacts {
+    /** True once the deferred carrier callback ran at least once. */
+    readonly injectRan: boolean;
+    /** True when the route is currently registered on a carrier. */
+    readonly routeRegistered: boolean;
+    /** The warnings collected so far, in order. */
+    readonly warnings: readonly string[];
+}
+/**
+ * The one-line diagnostic the entry logs when the route is still missing after the next tick.
+ *
+ * **Why this exists**: the panel's failure mode is `http-404`, and a 404 alone cannot tell "the carrier
+ * refused the route" from "the carrier never appeared" from "the plugin never asked". Each of those has a
+ * different fix, so the line carries the four facts that separate them  - whether the `ctx.inject`
+ * callback ran, whether `'webServer' in ctx` is true on the entry's own context, what `ctx.get('tools')`
+ * resolved to (a non-undefined service proves the context itself is live), and the warnings registered so
+ * far - with the warnings inline, so a single log line is enough to act on.
+ *
+ * @param facts - the wiring's own facts plus the two the entry samples from its context.
+ * @returns one structured line, safe for any logger.
+ */
+export declare function rootsRouteDiagnostic(facts: RootsRouteFacts & {
+    readonly hasWebServerProperty: boolean;
+    readonly toolsType: string;
+}): string;
+/**
+ * Build the wiring and register the route when a carrier exists.
+ *
+ * @param deps - live roots, live connections and the persist location.
+ * @returns the wiring; call {@link RootsWiring.dispose} on unload to release the route.
+ */
+export declare function createRootsWiring(deps: RootsWiringDeps): RootsWiring;
+//# sourceMappingURL=roots-wiring.d.ts.map

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

@@ -0,0 +1,52 @@
+/**
+ * A cached read of `user-roots.json`, answering "which remote directories did this session add?".
+ *
+ * `resolveSessionRoot` runs on **every** remote tool call, so it must not touch the disk each time: a tool call
+ * is latency the user feels, and the file only changes when the user acts on the panel. The cache is
+ * therefore bounded by time, not by events — there is no change hook on the persisted file, and inventing one
+ * would couple the tool surface to the panel's writer.
+ *
+ * Two properties worth naming:
+ *
+ *  - **A read failure never breaks a tool call.** A missing file (a fresh profile) answers "no session roots";
+ *    a malformed one does too. The user's fallback is the old `ROOT_OUTSIDE` message, which is exactly what
+ *    they got before this feature existed — strictly better than a tool that throws because a JSON file is
+ *    being rewritten at that instant.
+ *  - **The rule itself is not here.** Selection lives in `domain/roots/session-roots.ts` (pure, offline
+ *    tested); this module only decides *when* to re-read and hands the parsed entries over.
+ *
+ * @module dsh-over-ssh/integration/roots/session-root-index
+ */
+import { type SessionIdentity, type SessionRootOutcome } from '../../domain/roots/session-roots.ts';
+/** What the index needs. */
+export interface SessionRootIndexDeps {
+    /** Absolute path of `user-roots.json`. */
+    readonly filePath: string;
+    /** Read one file as UTF-8; injected so tests need no disk. */
+    readonly readFile: (path: string, encoding: 'utf8') => Promise<string>;
+    /** How long a parsed answer stays usable (milliseconds). */
+    readonly ttlMs: number;
+    /** Clock, injected so a test can advance it without sleeping. */
+    readonly now?: (() => number) | undefined;
+}
+/** The seam the tool backend consumes. */
+export interface SessionRootIndex {
+    /**
+     * Which remote root this session may target when its cwd names none.
+     *
+     * @param workspacePath - the session's cwd.
+     * @param identity - the session identity, when the platform could supply one (ADR-0013).
+     * @returns the rule's outcome; `none` also covers "the file could not be read".
+     */
+    outcomeFor(workspacePath: string, identity?: SessionIdentity): SessionRootOutcome;
+    /** Drop the cache (a panel write, or a test asserting a fresh read). */
+    invalidate(): void;
+}
+/**
+ * Build the cached index.
+ *
+ * @param deps - file path, reader, TTL, clock.
+ * @returns the index.
+ */
+export declare function createSessionRootIndex(deps: SessionRootIndexDeps): SessionRootIndex;
+//# sourceMappingURL=session-root-index.d.ts.map