dsh-over-ssh 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,77 @@
+/**
+ * The settings panel: a pure template over {@link PanelModel}.
+ *
+ * Written with `createElement` instead of JSX on purpose. The repository's test runner is plain Node with
+ * native TypeScript stripping, which does **not** transform JSX  - a `.tsx` component could not be imported
+ * by any test, and every source file must have a test (AGENTS.md 红线 1). `createElement` keeps the
+ * component in a `.ts` module that Node can load, and the bundle step treats it exactly the same.
+ *
+ * It receives everything through props (the platform's five-share contract puts the business face on props
+ * via `inject`, and components never see `ctx`), so there is no lookup, no subscription and no async state
+ * here  - which is what keeps the panel renderable in isolation.
+ *
+ * The visual layer is `./styles.ts` (theme tokens) and `./controls.ts` (hover/focus state). The token names
+ * this file used to hard-code (`--dsw-alias-text-primary`, `--dsw-alias-border-subtle`,
+ * `--dsw-alias-surface-subtle`, `--dsw-alias-surface-warning`) **are not in the shipped theme**, so every one
+ * of them silently fell back  - which is part of why this page looked unstyled.
+ *
+ * @module dsh-over-ssh/client/panel
+ */
+import { type ReactNode } from 'react';
+import type { PanelModel } from './core/panel-model.ts';
+import { type RootsPanelController, type RootsPanelCopy } from './roots/roots-panel-view.ts';
+/** The editable section's injection: the dictionary plus the controller that owns its state. */
+export interface SshDevPanelRootsProps {
+    /** The active locale's dictionary; the section resolves its own dynamic keys through it. */
+    readonly copy: RootsPanelCopy;
+    /** Live state and the two host calls; created once per plugin load by the entry (`index.ts`). */
+    readonly controller: RootsPanelController;
+}
+/** Props composed by the slot framework: the injected business face plus the owner's `close`. */
+export interface SshDevPanelProps {
+    /** Model built by the registration's inject factory. */
+    readonly model: PanelModel;
+    /** Close the settings panel (the shell owns the open state). */
+    readonly close: () => void;
+    /**
+     * The remote-workspaces editor. Omitted by a caller that has no controller (a probe, or a test), in which
+     * case the panel is exactly the read-only page it was before.
+     */
+    readonly roots?: SshDevPanelRootsProps;
+    /**
+     * Start a connectivity probe for one connection (the 「测试」 button on its row).
+     *
+     * Omitted by a caller with no tester, in which case rows render without the button  - the same rule as
+     * {@link SshDevPanelProps.roots}.
+     */
+    readonly onTestConnection?: (id: string) => void;
+    /**
+     * The row actions that come from the **live** panel state: which connection is being edited, which removal
+     * is awaiting confirmation, and whether a request is in flight.
+     *
+     * A separate prop from {@link SshDevPanelProps.onTestConnection} because the tester is a different store
+     * (it belongs to the transport probe, not to the editor). Omitted by a caller with no editor.
+     */
+    readonly rowState?: {
+        readonly editingId?: string;
+        readonly confirmingId?: string;
+        readonly remoteRootsOf: (connectionId: string) => number;
+        readonly disabled: boolean;
+        readonly onEdit: (id: string) => void;
+        readonly onRemove: (id: string) => void;
+        readonly onCancelRemove: () => void;
+        readonly onConfirmRemove: (id: string) => void;
+    };
+}
+/** The row actions a caller with an editor hands in. All of them are omitted by a read-only caller. */
+export interface ConnectionRowActions {
+    readonly onTest?: (id: string) => void;
+    /** Open the edit form for this connection. */
+    readonly onEdit?: (id: string) => void;
+    /** Ask for confirmation before removing this connection. */
+    readonly onRemove?: (id: string) => void;
+    /** True while a request is in flight, so every action is disabled at once. */
+    readonly disabled?: boolean;
+}
+/** Render the panel. */
+export declare function SshDevPanel({ model, close, roots, onTestConnection, rowState }: SshDevPanelProps): ReactNode;

package/lib/types/src/client/roots/connection-test.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The 「测试」 button's state: one connection at a time, answer or failure, and nothing else.
+ *
+ * Kept out of the component (which is a pure template) and out of the roots editor (which owns the *file*):
+ * this is transient UI state whose only job is to hold "what did the last probe say" long enough to render it.
+ *
+ * The probe itself runs on the host (a real connect plus one command); this module only carries the request and
+ * narrows the answer, so the four fields it reads are the four the host whitelists  - an answer that grew a
+ * field cannot reach the panel.
+ *
+ * @module dsh-over-ssh/client/connection-test
+ */
+import type { MessageKey } from '../core/message.ts';
+import type { FetchLike } from './roots-panel.ts';
+/** Where one connection's probe stands. */
+/**
+ * Where one connection's probe stands.
+ *
+ * `idle` is the state a row is in **before** anyone clicked  - the button must already be there (it is what the
+ * user clicks), so "no answer yet" is a status, not a missing field.
+ */
+export type ConnectionTestStatus = 'idle' | 'running' | 'ok' | 'failed';
+/** The last answer for one connection. */
+export interface ConnectionTestState {
+    readonly status: ConnectionTestStatus;
+    /** Transport the host actually used (`alias` / `ssh2` / `agent`), once it answered. */
+    readonly transport?: string;
+    /** Whether that transport was a degraded substitute. */
+    readonly degraded?: boolean;
+    /** Machine-readable failure code (`AUTH_FAILED`, `TIMEOUT`, …). */
+    readonly code?: string;
+    /** The host's own sentence about the failure (or the carrier's, e.g. `Failed to fetch`). */
+    readonly message?: string;
+    /**
+     * Our own sentence, when the failure was ours.
+     *
+     * A key rather than text: this module has no dictionary, and the three sentences it used to spell were Chinese
+     * in both locales (`roots-panel-view` renders them through `resolveMessage` with the active dictionary).
+     */
+    readonly messageKey?: MessageKey;
+    /** Round trip in milliseconds, either way. */
+    readonly ms?: number;
+}
+/** The tester the panel drives. */
+export interface ConnectionTester {
+    /** Current answers by connection id; a new map after every change (safe for a snapshot comparison). */
+    readonly getState: () => ReadonlyMap<string, ConnectionTestState>;
+    /** Probe one connection; resolves when the answer (or the failure) has been recorded. */
+    readonly test: (id: string) => Promise<void>;
+    /** Watch for changes; returns the disposer. */
+    readonly subscribe: (listener: () => void) => () => void;
+    /** Drop listeners; an in-flight answer is discarded rather than delivered. */
+    readonly dispose: () => void;
+}
+/**
+ * How long a probe may stay 「测试中…」 before the client gives up on it.
+ *
+ * A real connect plus one command can take seconds, but it can also hang forever: the host's own connect has no
+ * deadline the client can see, and a `fetch` with no signal keeps its promise (and the row's button) in limbo.
+ * Without this the 「测试」 button stayed disabled and read 「测试中…」 **forever**, with no cancel and no way to try
+ * again short of reloading the page (audit 2026-11-01b ui P2-11).
+ */
+export declare const CONNECTION_TEST_TIMEOUT_MS = 15000;
+export declare function createConnectionTester(options: {
+    readonly fetchImpl: FetchLike;
+    readonly path?: string;
+    /** Override for {@link CONNECTION_TEST_TIMEOUT_MS}; a test drives the timeout instead of waiting 15 s. */
+    readonly timeoutMs?: number;
+}): ConnectionTester;

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

@@ -0,0 +1,307 @@
+/**
+ * 根面板的**状态层**：草稿、状态机、reducer、选择器与文案解析。
+ *
+ * 从 `roots-panel-view.ts` 抽出（审计 0076）：这一层是纯函数，不碰 React，
+ * 也是测试最密集的部分；拆开后 view 只负责渲染与接线。
+ *
+ * @module dsh-over-ssh/client/roots-panel-state
+ */
+import type { OverSshKey } from '../core/locale.ts';
+import { type MessageKey, type RootsSnapshot, type RootsView, type SshConfigListing } from './roots-panel.ts';
+export type RootsPanelCopy = Record<OverSshKey, string>;
+/** The three forms' contents. Kept flat so a patch is one spread and a test can name a single field. */
+export interface RootsPanelDrafts {
+    /** Local root path (form 1). */
+    readonly localPath: string;
+    /** Remote root path (form 2). */
+    readonly remotePath: string;
+    /** Connection chosen for the remote root (form 2). */
+    readonly remoteConnectionId: string;
+    /** Optional label for the remote root (form 2). */
+    readonly remoteLabel: string;
+    /** New connection: id. */
+    readonly newId: string;
+    /** New connection: host. */
+    readonly newHost: string;
+    /** New connection: user. */
+    readonly newUser: string;
+    /** New connection: authentication mode. */
+    readonly newAuthKind: 'agent' | 'key' | 'password';
+    /** New connection: key path, only meaningful for `newAuthKind === 'key'`. */
+    readonly newKeyPath: string;
+    /**
+     * New connection: password, only meaningful for `newAuthKind === 'password'`.
+     *
+     * Held only between typing and the POST that follows it — the drafts are reset once the request settles, and
+     * no answer ever carries it back (the host stores it in `ctx.credentials`).
+     */
+    readonly newPassword: string;
+    /** New connection: port as typed; parsed by the controller so a bad value can be refused, not coerced. */
+    readonly newPort: string;
+}
+/** A change to the drafts; every field is optional so one handler can serve every input. */
+export type RootsPanelDraftPatch = Partial<RootsPanelDrafts>;
+/**
+ * The **edit dialog's** own fields, kept apart from {@link RootsPanelDrafts}.
+ *
+ * The two forms used to share one flat draft set, and that is exactly what went wrong (audit 2026-11-01b ui
+ * P1-4 — three symptoms, one cause):
+ *
+ *  - `edit-started` overwrote the add form's drafts with the row being edited, so opening 「编辑」 to look at a
+ *    record threw away whatever the operator had already typed into 「新增连接」;
+ *  - `edit-ended` reset **all** drafts, so even cancelling the dialog wiped the add form;
+ *  - both forms read the same fields, so submitting the add form (reachable while the dialog is up, in a
+ *    composition where the card has no backdrop) posted the edit dialog's values as a *new* connection.
+ *
+ * The password box belongs here, not in {@link RootsPanelDrafts}: it is always empty on render, and empty means
+ * 「keep the stored password」 — a rule about the edit path only (「新增连接」 has its own required-password rule).
+ */
+export interface RootsPanelEditDrafts {
+    /** The connection's id. Editable: a change is a rename that re-keys its remote roots. */
+    readonly id: string;
+    readonly host: string;
+    readonly user: string;
+    readonly authKind: 'agent' | 'key' | 'password';
+    readonly keyPath: string;
+    /** Always empty on render; empty means 「keep the stored password」. */
+    readonly password: string;
+    /** Port as typed; parsed by the controller so a bad value can be refused, not coerced. */
+    readonly port: string;
+}
+/** A change to the edit dialog's fields. */
+export type RootsPanelEditDraftPatch = Partial<RootsPanelEditDrafts>;
+/** @returns the edit dialog's fields in their fresh state. */
+export declare function emptyRootsPanelEditDrafts(): RootsPanelEditDrafts;
+/** Where an inline form message belongs. */
+export type RootsPanelFormScope = 'roots' | 'connection' | 'edit';
+/** A refusal or a failed submit, shown next to the form it belongs to. */
+export interface RootsPanelFormNotice {
+    readonly scope: RootsPanelFormScope;
+    readonly message: MessageKey;
+}
+/** Everything the section renders from. */
+export interface RootsPanelState {
+    /** True once an initial `load()` has been asked for, so a remount does not re-fetch. */
+    readonly started: boolean;
+    /** True while a request is in flight; the edit gate is `buildRootsView`'s `canEdit`. */
+    readonly pending: boolean;
+    /** True once a `load()` answered (ok or not). */
+    readonly loaded: boolean;
+    /** The last host answer, if any. */
+    readonly snapshot?: RootsSnapshot;
+    /** The last transport-level failure, if any. */
+    readonly error?: string;
+    /** The forms' contents. */
+    readonly drafts: RootsPanelDrafts;
+    /**
+     * The **edit dialog's** fields (see {@link RootsPanelEditDrafts}).
+     *
+     * Always present, empty while no dialog is open: an optional field would make "the dialog is closed" and "the
+     * value was dropped" the same state, which is how the two forms ended up sharing one draft set.
+     */
+    readonly editDrafts: RootsPanelEditDrafts;
+    /**
+     * The connection currently open in the edit form, if any.
+     *
+     * Only the **id** is remembered: every other value lives in the drafts, so the form cannot show a stale copy
+     * of a record the host has since changed. `undefined` means the add form is the one on screen.
+     */
+    readonly editingId?: string;
+    /**
+     * The connection whose removal is awaiting confirmation.
+     *
+     * Deleting a connection also deletes its roots (the host does that), which is not obvious from a row that
+     * shows only `id · host`  -  hence the confirmation, the same shape the session panel uses for its
+     * irreversible actions.
+     */
+    readonly confirmingRemove?: string;
+    /** The last validation refusal or submit failure, with the form it belongs to. */
+    readonly formNotice?: RootsPanelFormNotice;
+    /**
+     * The last **successful** submit, with the form it belongs to.
+     *
+     * Adding a root, adding a connection or saving an edit used to end silently: the form emptied itself and the
+     * only evidence was the list changing somewhere else on the page. The success line reuses the same
+     * per-form slot mechanism as {@link RootsPanelState.formNotice}, with the opposite tone
+     * (audit 2026-11-01b ui P3-5).
+     */
+    readonly formSuccess?: RootsPanelFormNotice;
+    /**
+     * True while the `~/.ssh/config` import dialog is open (FR-2.1.4).
+     *
+     * The dialog is state in this controller rather than local `useState` in the view for the same reason the
+     * forms are: the controller owns every request, and an import is a request. Keeping the listing here also
+     * means reopening the dialog does not re-read the file unless the user asks.
+     */
+    readonly importOpen?: boolean;
+    /** The aliases the host offered, once `list-ssh-config` answered. */
+    readonly importListing?: SshConfigListing;
+    /** Aliases ticked in the dialog, in the order they were ticked. */
+    readonly importSelected?: readonly string[];
+    /** True while `list-ssh-config` or `import-ssh-config` is in flight. */
+    readonly importBusy?: boolean;
+    /** The last import's report, shown inside the dialog (ids imported, aliases refused). */
+    readonly importReport?: {
+        readonly imported: readonly string[];
+        readonly refused: readonly {
+            readonly alias: string;
+            readonly reason: string;
+        }[];
+    };
+    /** Why the last import attempt failed, shown inside the dialog. */
+    readonly importError?: string;
+}
+/** What the reducer accepts. */
+export type RootsPanelAction = 
+/** A request is being sent; also marks the panel as started. */
+{
+    readonly type: 'load';
+} | {
+    readonly type: 'loaded';
+    readonly snapshot: RootsSnapshot;
+}
+/**
+ * A request failed. With a `scope` it is a submit failure and is shown next to that form; without one it
+ * is the initial load failing, which the view's own `notice` already reports  - showing both would say the
+ * same thing twice.
+ */
+ | {
+    readonly type: 'failed';
+    readonly error: string;
+    readonly scope?: RootsPanelFormScope;
+}
+/** One form field changed: clears the inline message, because the user is fixing it. */
+ | {
+    readonly type: 'draft-changed';
+    readonly patch: RootsPanelDraftPatch;
+}
+/** One field of the **edit** dialog changed; the add form's drafts are untouched. */
+ | {
+    readonly type: 'edit-draft-changed';
+    readonly patch: RootsPanelEditDraftPatch;
+}
+/** A submit is in flight. */
+ | {
+    readonly type: 'submitted';
+}
+/** A draft was refused before any request; nothing was sent. */
+ | {
+    readonly type: 'refused';
+    readonly scope: RootsPanelFormScope;
+    readonly message: MessageKey;
+}
+/**
+ * A request succeeded. `resetDrafts` clears the forms (an add did); a removal keeps them.
+ *
+ * `scope` decides which form gets the "saved" line — a removal passes none, because its evidence is the row
+ * leaving the list, not a sentence.
+ */
+ | {
+    readonly type: 'succeeded';
+    readonly resetDrafts?: boolean;
+    readonly scope?: RootsPanelFormScope;
+}
+/** A removal is in flight; the reducer itself refuses a row that is not removable. */
+ | {
+    readonly type: 'remove';
+    readonly key: string;
+}
+/** Open the edit form for one connection, prefilled from the last answer. */
+ | {
+    readonly type: 'edit-started';
+    readonly id: string;
+}
+/** Close the edit form (cancelled, or the edit settled). */
+ | {
+    readonly type: 'edit-ended';
+}
+/** Ask for confirmation before removing a connection (it takes its roots with it). */
+ | {
+    readonly type: 'remove-connection-asked';
+    readonly id: string;
+}
+/** Dismiss the confirmation without removing anything. */
+ | {
+    readonly type: 'remove-connection-dismissed';
+}
+/** Open the ssh-config import dialog (FR-2.1.4). */
+ | {
+    readonly type: 'import-opened';
+}
+/** Close it, keeping nothing but the panel's own state. */
+ | {
+    readonly type: 'import-closed';
+}
+/** A read or an import is in flight. */
+ | {
+    readonly type: 'import-busy';
+}
+/** The host's candidate list arrived. */
+ | {
+    readonly type: 'import-loaded';
+    readonly listing: SshConfigListing;
+}
+/** One alias was ticked or unticked. */
+ | {
+    readonly type: 'import-toggled';
+    readonly alias: string;
+}
+/** Tick every candidate. */
+ | {
+    readonly type: 'import-all';
+}
+/** Untick everything. */
+ | {
+    readonly type: 'import-none';
+}
+/** The import settled: what went in, and what was refused with its reason. */
+ | {
+    readonly type: 'import-settled';
+    readonly imported: readonly string[];
+    readonly refused: readonly {
+        readonly alias: string;
+        readonly reason: string;
+    }[];
+}
+/** The read or the import failed. */
+ | {
+    readonly type: 'import-failed';
+    readonly error: string;
+} | {
+    readonly type: 'import-failed';
+    readonly error: string;
+};
+/** The starting state: nothing loaded, no drafts, no queue. */
+export declare function emptyRootsPanelDrafts(): RootsPanelDrafts;
+/** @returns the state a freshly created controller holds. */
+export declare function initialRootsPanelState(): RootsPanelState;
+/**
+ * The panel's state machine. Pure: same state + same action => same result, and an action that changes
+ * nothing returns the **same object**, so a subscriber is never woken for a no-op.
+ *
+ * @param state - the current state.
+ * @param action - what happened.
+ * @returns the next state.
+ */
+export declare function rootsPanelReducer(state: RootsPanelState, action: RootsPanelAction): RootsPanelState;
+/**
+ * The view model for a state.
+ *
+ * @param state - the panel state.
+ * @returns exactly what `buildRootsView` says: rows with `removable`, connections, notice and the edit gate.
+ */
+export declare function selectRootsView(state: RootsPanelState): RootsView;
+/** True when the panel may accept input right now: an answer arrived and no request is in flight. */
+export declare function canEdit(state: RootsPanelState): boolean;
+/**
+ * Turn one `MessageKey` into text, with its parameters substituted.
+ *
+ * The implementation is `core/message.ts`'s (the session panel and the transfer panel need the same two lines and
+ * must not import this React-bearing module); what stays here is the roots panel's own convenience: no message
+ * renders as `''`, because every caller in this file is a template slot that simply renders nothing.
+ *
+ * @param copy - the dictionary of the active locale.
+ * @param message - the key plus optional `{name}` parameters.
+ * @returns the rendered text, or `''` when there is no message.
+ */
+export declare function resolveMessage(copy: RootsPanelCopy, message: MessageKey | undefined): string;