dsh-over-ssh 0.1.0 → 0.1.1

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

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

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