dsh-over-ssh 0.0.0-stage → 0.1.0

package/lib/types/src/client/roots-panel.d.ts

@@ -0,0 +1,347 @@
+/**
+ * The roots panel's whole decision surface: wire parsing, the HTTP calls to the host route, input validation
+ * and the view model. **No React, no DOM, no `@deepseek-ai/*`** — the component renders what this module
+ * returns and nothing else, which is what makes the panel testable without a browser (红线 2).
+ *
+ * Two rules this module owns:
+ *
+ *  1. **No credentials, ever.** {@link parseRootsSnapshot} copies field by field and drops anything else, so a
+ *     host answer that leaked `keyPath` / `password` still cannot reach the DOM. The host route filters its
+ *     side; this is the client's half of the same rule.
+ *  2. **Password authentication is not editable here.** A password must never round-trip through a browser
+ *     form and a same-origin POST, so {@link validateConnectionDraft} refuses it outright rather than
+ *     growing a field that leaks secrets into web storage.
+ *
+ * @module dsh-remote-workspace/client/roots-panel
+ */
+/**
+ * Where the host route lives, as the browser must request it.
+ *
+ * **Relative on purpose, and this is the platform's own convention.** The GUI is served from two different
+ * origins depending on the carrier, and only a relative path is correct in both:
+ *
+ *  - `dsh web` (browser): the page origin *is* the host, so `/api/…` reaches
+ *    `ctx.webServer` directly;
+ *  - the Desktop shell: the page is `dsh-app://app/` and `/api/…` resolves to
+ *    `dsh-app://app/api/…`, which Electron's `protocol.handle('dsh-app')` forwards to the owned host with
+ *    the browser-session cookie the shell keeps out of the page
+ *    (`resources/app.asar/lib/main.js`, `forwardWebRequest`: non-asset paths are proxied with
+ *    `headers.set('cookie', cookie)`; `serveWebDocument` never sees `/api/…`).
+ *
+ * The absolute host origin (`globalThis.__DSH_TRANSPORT__.streamBaseUrl`) is deliberately **not** used here:
+ * the shell strips `set-cookie` from proxied responses and the session cookie is host-only + `HttpOnly`, so
+ * a direct fetch to the host origin cannot authenticate — it would turn a working request into a 401. The
+ * platform uses that origin for the WebSocket only (`dsh-api-gateway`, `REMOTE_STREAM_MUX_PATH`), and its
+ * own HTTP callers resolve against `document.baseURI` (`dsh-client-file-upload`, `new URL(request.path,
+ * document.baseURI)`).
+ */
+export declare const ROOTS_API_PATH = "/api/remote-workspace/roots";
+/** A root either lives on this machine or behind a connection. */
+export type RootLocation = 'local' | 'remote';
+/** One root as the panel shows it. */
+export interface RootRow {
+    /** Stable identity: `<location>:<connectionId or '-'>:<path>`. */
+    readonly key: string;
+    readonly location: RootLocation;
+    readonly path: string;
+    readonly connectionId?: string;
+    readonly label?: string;
+    readonly writable: boolean;
+    /** `config` rows come from the profile patch; `user` rows were added in this panel. */
+    readonly source: 'config' | 'user';
+    /** Whether this root also appears in the panel's own file — only those may be deleted. */
+    readonly inUserFile: boolean;
+    /**
+     * The workspaces that list this root; absent means plugin-wide.
+     *
+     * The composer's card filters on it (one workspace must not inherit another's directories); the settings
+     * panel ignores it, because that panel manages the plugin-wide list.
+     */
+    readonly workspaces?: readonly string[];
+}
+/** A connection, narrowed to what the panel may display. **No credential fields exist on this type.** */
+export interface ConnectionSummary {
+    readonly id: string;
+    readonly host: string;
+    readonly user?: string;
+    readonly port?: number;
+    readonly authKind: 'agent' | 'key' | 'password';
+    /**
+     * The transport the record asks for, when it names one.
+     *
+     * The edit form prefills from this: a form that always showed the default would silently rewrite a
+     * connection the user had deliberately set to zero-install. Absent means "the reader's default" (the
+     * record carries no choice), which is a different fact from "the user chose the default".
+     */
+    readonly transport?: ConnectionTransportChoice;
+}
+/** Everything one GET answers. */
+export interface RootsSnapshot {
+    readonly roots: readonly RootRow[];
+    readonly connections: readonly ConnectionSummary[];
+    readonly warnings: readonly string[];
+}
+/** The outcome of one call: the panel never throws on a host failure, it shows it. */
+export type ApiResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** What this module needs from `fetch`; injected so tests run without a server (红线 3). */
+export type FetchLike = (input: string, init?: {
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: string;
+    readonly signal?: AbortSignal;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    json: () => Promise<unknown>;
+}>;
+/** A message is a key plus its parameters; the component resolves it against the locale dictionaries. */
+export interface MessageKey {
+    readonly key: string;
+    readonly params?: Readonly<Record<string, string | number>>;
+}
+/** A validated draft, or the reason it was refused. */
+export type Validation<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly message: MessageKey;
+};
+/** The payload the panel sends to add a root. */
+export interface RootDraft {
+    readonly location: RootLocation;
+    readonly path: string;
+    readonly connectionId?: string;
+    readonly label?: string;
+    readonly writable?: boolean;
+}
+/**
+ * Which transport a connection should use, as the form offers it.
+ *
+ * Spelled out here rather than imported from the host's `TransportKind` (`host/domain/connection.ts`): this
+ * module is the pure client half and imports nothing from the host (红线 2). The two unions must stay equal,
+ * and the host re-validates whatever arrives (`normalizeConnectionEntry`), so a drift cannot reach the file.
+ *
+ * **Not to be confused with `authKind: 'agent'`**, which names the *local* ssh-agent as a credential source.
+ * `transport: 'agent'` names the *remote* Tier 2 Go program this plugin uploads (ADR-0005/0007).
+ */
+export type ConnectionTransportChoice = 'alias' | 'ssh2' | 'agent';
+/** Every transport the form may offer, in the order the selector lists them (the default first). */
+export declare const CONNECTION_TRANSPORTS: readonly ConnectionTransportChoice[];
+/** The transport a draft uses when it names none: the Tier 2 agent, matching the host's own default. */
+export declare const DEFAULT_CONNECTION_TRANSPORT: ConnectionTransportChoice;
+/**
+ * Narrow an untrusted value to a transport this build knows.
+ *
+ * Anything unrecognised degrades to the default rather than reaching the wire: the field is a closed union, and
+ * a value the host would reject as `CONNECTION_INVALID` is worse than the documented default.
+ *
+ * @param value - the raw field.
+ * @returns the transport, or {@link DEFAULT_CONNECTION_TRANSPORT}.
+ */
+export declare function toConnectionTransport(value: unknown): ConnectionTransportChoice;
+/**
+ * The payload the panel sends to add a connection.
+ *
+ * `password` is the **only** secret this client ever holds, and only long enough to post it: the host writes
+ * it into `ctx.credentials` and answers with a projection that never contains it (FR-2.1.2).
+ */
+export interface ConnectionDraft {
+    readonly id: string;
+    readonly host: string;
+    readonly user: string;
+    readonly authKind: 'agent' | 'key' | 'password';
+    /**
+     * The transport to use. Optional on the way in (an omitted value means {@link DEFAULT_CONNECTION_TRANSPORT})
+     * and **always present on the way out**: the host persists the user's explicit choice, so "the default" is a
+     * decision the record carries rather than one every reader has to re-derive.
+     */
+    readonly transport?: ConnectionTransportChoice;
+    readonly keyPath?: string;
+    readonly password?: string;
+    readonly port?: number;
+}
+/** The identity the host also uses, so removals address the same row the list shows. */
+export declare function rootKey(location: RootLocation, path: string, connectionId?: string): string;
+/**
+ * Narrow one GET answer to the panel's model, field by field.
+ *
+ * Unknown fields are dropped rather than copied: an answer carrying `keyPath` reaches the DOM only as a
+ * missing field, never as a value. A malformed answer becomes an empty snapshot with a warning instead of a
+ * throw — a broken channel must degrade the panel, not break the whole settings page.
+ *
+ * @param value - the parsed JSON the route answered with.
+ * @returns a snapshot that is safe to render.
+ */
+export declare function parseRootsSnapshot(value: unknown): RootsSnapshot;
+/** True when a string is an absolute path this machine can open (drive letter, POSIX root, or UNC). */
+export declare function isAbsoluteLocalPath(path: string): boolean;
+/**
+ * Refuse a draft before it becomes a request.
+ *
+ * @param draft - what the form holds.
+ * @param existing - roots already shown, to reject a duplicate.
+ * @returns the wire payload, or the message key to show next to the field.
+ */
+export declare function validateRootDraft(draft: RootDraft, existing?: readonly RootRow[]): Validation<RootDraft>;
+/**
+ * Refuse a connection draft before it becomes a request.
+ *
+ * The id rule is the **host's** rule (a user-chosen name, Chinese included), so the panel refuses exactly
+ * what `path-grammar.ts` would refuse instead of sending a request that comes back 400.
+ *
+ * Password auth is supported: the draft carries the password once, the host stores it in `ctx.credentials`,
+ * and nothing in any answer ever carries it back (FR-2.1.2).
+ *
+ * The transport is **always** in the returned value, even when the draft omits it: the form has a selector,
+ * and the host must receive the user's choice explicitly rather than re-deriving the default per reader.
+ *
+ * @param draft - what the form holds.
+ * @param existing - connections already shown, to reject a duplicate id.
+ * @returns the wire payload, or the message key to show next to the field.
+ */
+export declare function validateConnectionDraft(draft: ConnectionDraft, existing?: readonly ConnectionSummary[]): Validation<ConnectionDraft>;
+/**
+ * Refuse an **edit** draft before it becomes a request.
+ *
+ * The same rules as {@link validateConnectionDraft} for every field, with the three differences an edit
+ * needs, and each one exists for a reason:
+ *
+ *  1. **A rename is allowed but must not collide with a *different* connection.** Uniqueness is checked
+ *     against the rows except the one being edited  -  `validateConnectionDraft` cannot express that, and using
+ *     it here would refuse every save that kept the id.
+ *  2. **An empty password means "do not touch the stored secret", not "refuse".** No answer ever carries a
+ *     secret back, so the form's password box is always empty on render; requiring it would make it
+ *     impossible to change a host without retyping the password, and treating empty as "clear" would delete
+ *     the password on every unrelated edit. The field is therefore **omitted** from the payload unless the
+ *     user typed one, which is exactly how the host reads it.
+ *  3. **`keyPath` follows the same rule as the password: blank means "keep the stored one".** The panel
+ *     cannot prefill it, because the host's answer deliberately never carries a `keyPath` (it names a real
+ *     file). Refusing a blank one would therefore make it impossible to edit a key connection's host without
+ *     retyping its private-key path, and *filling* it with a guess would silently repoint the connection.
+ *     So it is omitted unless the user typed one  -  the host's merge keeps what is stored.
+ *
+ * @param draft - what the form holds.
+ * @param originalId - the id of the connection being edited (the lookup key the host needs).
+ * @param existing - connections already shown, to reject a colliding rename.
+ * @returns the wire payload, or the message key to show next to the field.
+ */
+export declare function validateConnectionEdit(draft: ConnectionDraft, originalId: string, existing?: readonly ConnectionSummary[]): Validation<Record<string, unknown>>;
+/** One row as the component renders it. */
+export interface RootRowView {
+    readonly key: string;
+    readonly location: RootLocation;
+    readonly title: string;
+    readonly subtitle: string;
+    readonly badgeKey: string;
+    readonly removable: boolean;
+}
+/** The panel's complete render input. */
+export interface RootsView {
+    readonly rows: readonly RootRowView[];
+    readonly connections: readonly ConnectionSummary[];
+    /** Set when the host did not answer, so the panel can say why instead of looking empty. */
+    readonly notice?: MessageKey;
+    /** False while a request is in flight, so the form cannot double-submit. */
+    readonly canEdit: boolean;
+}
+/**
+ * Turn a snapshot (or the failure to get one) into render input.
+ *
+ * @param input - the last answer, or the last error, plus whether a request is running.
+ * @returns rows, connections, notice and the edit gate.
+ */
+export declare function buildRootsView(input: {
+    readonly snapshot?: RootsSnapshot;
+    readonly error?: string;
+    readonly pending?: boolean;
+}): RootsView;
+/** The calls the panel makes. */
+export interface RootsApi {
+    load(signal?: AbortSignal): Promise<ApiResult<RootsSnapshot>>;
+    send(body: Record<string, unknown>): Promise<ApiResult<RootsSnapshot>>;
+    /**
+     * A POST whose answer is **not** a snapshot.
+     *
+     * The import actions answer a candidate list and an import report, neither of which is a roots snapshot. It
+     * is a separate method rather than a looser return type on {@link RootsApi.send} so that every existing call
+     * keeps the snapshot it already depends on: widening `send` would make `state` optional for all of them.
+     */
+    sendRaw(body: Record<string, unknown>): Promise<ApiResult<Record<string, unknown>>>;
+}
+/** One importable `~/.ssh/config` alias, as the import dialog renders it. */
+export interface SshConfigCandidate {
+    /** The literal alias; also the `ssh` target. Shown verbatim so the user recognises their own config. */
+    readonly alias: string;
+    /** Resolved host name. */
+    readonly host: string;
+    readonly user?: string;
+    readonly port?: number;
+    /** Whether the block named an identity file. The path itself never reaches the client. */
+    readonly hasIdentityFile: boolean;
+    readonly hasProxyJump: boolean;
+    /** The id the import would create. Editable in spirit: the user sees it before committing. */
+    readonly suggestedId: string;
+}
+/** One alias the host refused, with the machine-readable reason. */
+export interface SshConfigSkipped {
+    readonly pattern: string;
+    readonly reason: string;
+    readonly line: number;
+}
+/** What `list-ssh-config` answers. */
+export interface SshConfigListing {
+    readonly candidates: readonly SshConfigCandidate[];
+    readonly skipped: readonly SshConfigSkipped[];
+}
+/**
+ * Narrow the host's `list-ssh-config` answer.
+ *
+ * Defensive in the same way {@link parseRootsSnapshot} is: the client never trusts the wire's shape, and a row
+ * without a usable alias or id is **dropped** rather than rendered as a checkbox that would import nothing.
+ *
+ * @param value - the parsed JSON body.
+ * @returns the listing, with unusable rows removed.
+ */
+export declare function parseSshConfigListing(value: unknown): SshConfigListing;
+/**
+ * The human-readable reason one alias was refused.
+ *
+ * The mapping lives here rather than in the view so the reasons are testable without rendering, and an unknown
+ * reason from a newer host still produces a sentence instead of an empty cell.
+ *
+ * @param reason - the machine-readable reason.
+ * @returns a message key.
+ */
+export declare function sshConfigSkipKey(reason: string): string;
+/** A candidate's one-line summary: `user@host:port`, with the flags that matter for the import. */
+export declare function sshConfigCandidateSummary(candidate: SshConfigCandidate): string;
+/**
+ * The reason a failed response reports, when the host did not name one.
+ *
+ * The path is part of the text on purpose: `http-404` alone cannot distinguish "this route is not
+ * registered" (the host half never claimed it — that was a real defect) from "the request never reached the
+ * host" (the shell's proxy or the composition is at fault). Both are shown verbatim in the panel's notice.
+ *
+ * @param status - the HTTP status.
+ * @param path - the exact URL that was requested.
+ * @returns the machine-readable reason.
+ */
+export declare function transportFailureReason(status: number, path: string): string;
+/**
+ * Bind the route to the panel's two operations.
+ *
+ * @param fetchImpl - `window.fetch` in the app, a stub in tests.
+ * @param path - override for tests; defaults to {@link ROOTS_API_PATH}.
+ * @returns the calls the component uses.
+ */
+export declare function createRootsApi(fetchImpl: FetchLike, path?: string): RootsApi;
+/** The field names the panel must never send, asserted by tests rather than trusted to reviewers. */
+export declare function isForbiddenField(name: string): boolean;
+//# sourceMappingURL=roots-panel.d.ts.map