@linxin666/dsh-ssh 0.1.1

package/lib/invariant.js

@@ -0,0 +1,6 @@
+//#region src/invariant.ts
+/** Invariant companion plugin (no assertions — nothing to check at runtime). */
+/** Provides no assertions: the ssh plugin owns no cross-package runtime invariants. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/types/client/api.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Browser-side API client for the /api/dsh-ssh route family. The only data
+ * access path the panel components use — plain fetch/WebSocket, same origin.
+ */
+import { type ClusterResult, type ExecResult, type HostPayload, type ImportResult, type RemoteDirEntry, type SshHostSummary, type TestResult, type TransferProgress, type TunnelInfo } from '../protocol.ts';
+/** Error carrying the route's JSON error message. */
+export declare class SshApiError extends Error {
+    constructor(message: string);
+}
+/** One open terminal connection (WebSocket JSON frames). */
+export interface TerminalConnection {
+    /** Fired on the ready frame (shell is up). */
+    onReady: (() => void) | undefined;
+    /** Fired on every output frame. */
+    onOutput: ((data: string) => void) | undefined;
+    /** Fired on the exit frame (or transport error). */
+    onExit: ((code: number | null, error?: string) => void) | undefined;
+    /** Send raw input to the remote shell. */
+    send(data: string): void;
+    /** Resize the remote PTY. */
+    resize(cols: number, rows: number): void;
+    /** Close the socket and the remote session. */
+    close(): void;
+}
+/** The browser half's only data entry point. */
+export declare class SshApi {
+    listHosts(queryText?: string): Promise<SshHostSummary[]>;
+    createHost(payload: HostPayload): Promise<SshHostSummary>;
+    updateHost(alias: string, patch: HostPayload): Promise<SshHostSummary>;
+    deleteHost(alias: string): Promise<void>;
+    importSshConfig(): Promise<ImportResult>;
+    testHost(alias: string): Promise<TestResult>;
+    exec(alias: string, command: string, timeoutMs?: number): Promise<ExecResult>;
+    cluster(options: {
+        command: string;
+        aliases?: string[];
+        environment?: string;
+        tags?: string[];
+        timeoutMs?: number;
+        maxWorkers?: number;
+    }): Promise<ClusterResult[]>;
+    ls(alias: string, path: string): Promise<RemoteDirEntry[]>;
+    listTunnels(): Promise<TunnelInfo[]>;
+    startTunnel(options: {
+        alias: string;
+        remotePort: number;
+        remoteHost?: string;
+        localPort?: number;
+    }): Promise<TunnelInfo>;
+    stopTunnel(tunnelId: string): Promise<boolean>;
+    stopAllTunnels(alias?: string): Promise<number>;
+    /**
+     * Upload one file (raw bytes) to a remote path. Progress arrives through
+     * the NDJSON response stream; resolves when the result frame lands.
+     */
+    uploadFile(file: File, alias: string, remotePath: string, onProgress?: (progress: TransferProgress) => void): Promise<{
+        transferredBytes: number;
+    }>;
+    /**
+     * Download a remote file with client-side progress. Streams straight to
+     * disk when the File System Access API is available (no full-file RAM
+     * copy); otherwise falls back to an in-memory Blob.
+     */
+    downloadFile(alias: string, remotePath: string, onProgress?: (progress: TransferProgress) => void): Promise<{
+        blob?: Blob;
+        filename: string;
+        streamed: boolean;
+        bytes: number;
+    }>;
+    /** Open a WebSocket terminal session. */
+    openTerminal(alias: string, cols: number, rows: number): TerminalConnection;
+}

package/lib/types/client/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Browser-half entry for the dsh-ssh plugin — runs inside the dsh web GUI.
+ *
+ * Registers the dsh-ssh locale dictionaries and mounts the two DOM surfaces:
+ * the sidebar entry row (toggles the panel) and the SSH operations panel in
+ * the center column. Failure policy: DOM mounting problems are logged, never
+ * thrown — the web shell fails the whole boot when a plugin apply throws, and
+ * an external plugin must not take the GUI down.
+ *
+ * Export discipline (packages/client rule): the /client surface carries what
+ * cordis loading needs plus types only — all value exports stay internal.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import { type SshKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** dsh-ssh surface copy. */
+        'dsh-ssh': SshKey;
+    }
+}
+/** Required services (fiber inject waiting — the runtime must be up first). */
+export declare const inject: string[];
+/** Type-only surface (export discipline: no value exports beyond the plugin contract). */
+export type { PanelControllerSnapshot } from './panel/controller.ts';
+export type { SshPanelProps } from './panel/SshPanel.tsx';
+export type { HostsTabProps } from './panel/HostsTab.tsx';
+export type { HostFormDialogProps } from './panel/HostFormDialog.tsx';
+export type { TerminalTabProps } from './panel/TerminalTab.tsx';
+export type { TransferTabProps } from './panel/TransferTab.tsx';
+export type { TunnelsTabProps } from './panel/TunnelsTab.tsx';
+export type { ClusterTabProps } from './panel/ClusterTab.tsx';
+export type { SshKey } from './locales.ts';
+/**
+ * Mount the SSH panel.
+ * @param ctx - client root context (locale service).
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/locales.d.ts

@@ -0,0 +1,137 @@
+/**
+ * dsh-ssh surface copy: zh is the key source, en mirrors every key.
+ */
+export declare const zh: {
+    readonly 'entry.label': "SSH";
+    readonly 'entry.tooltip': "远程 SSH 运维面板";
+    readonly 'panel.title': "远程 SSH";
+    readonly 'tab.hosts': "主机";
+    readonly 'tab.terminal': "终端";
+    readonly 'tab.transfer': "传输";
+    readonly 'tab.tunnels': "隧道";
+    readonly 'tab.cluster': "集群";
+    readonly 'hosts.empty': "尚未配置主机。点击「新增主机」添加，或从 ~/.ssh/config 导入。";
+    readonly 'hosts.add': "新增主机";
+    readonly 'hosts.import': "导入 ~/.ssh/config";
+    readonly 'hosts.search': "搜索别名 / 描述 / 标签…";
+    readonly 'hosts.col.alias': "别名";
+    readonly 'hosts.col.host': "主机";
+    readonly 'hosts.col.user': "用户";
+    readonly 'hosts.col.auth': "认证";
+    readonly 'hosts.col.environment': "环境";
+    readonly 'hosts.col.tags': "标签";
+    readonly 'hosts.col.description': "备注";
+    readonly 'hosts.col.actions': "操作";
+    readonly 'hosts.test': "测试";
+    readonly 'hosts.edit': "编辑";
+    readonly 'hosts.delete': "删除";
+    readonly 'hosts.deleteConfirm': "确定删除主机「{alias}」？将同时停止其隧道。";
+    readonly 'hosts.imported': "解析 {parsed} 个配置块，新增 {added} 台主机，跳过 {skipped} 个。";
+    readonly 'hosts.testing': "连接测试中…";
+    readonly 'hosts.testOk': "连接成功（{latency} ms）";
+    readonly 'hosts.testFail': "连接失败：{error}";
+    readonly 'hosts.connected': "连接";
+    readonly 'hosts.notConnected': "未连接";
+    readonly 'form.title.create': "新增主机";
+    readonly 'form.title.edit': "编辑主机 {alias}";
+    readonly 'form.alias': "别名";
+    readonly 'form.aliasHint': "小写字母、数字与单连字符，操作时使用";
+    readonly 'form.host': "主机地址";
+    readonly 'form.port': "端口";
+    readonly 'form.user': "用户名";
+    readonly 'form.auth': "认证方式";
+    readonly 'form.auth.key': "密钥";
+    readonly 'form.auth.password': "密码";
+    readonly 'form.authKeepHint': "编辑时密钥/密码留空将保留原认证方式与已存凭据；如需更换认证方式请填写新凭据。";
+    readonly 'form.keyPath': "私钥路径";
+    readonly 'form.keyPathHint': "如 ~/.ssh/id_ed25519";
+    readonly 'form.passphrase': "密钥口令";
+    readonly 'form.password': "密码";
+    readonly 'form.passwordHint': "明文保存在 ~/.dsh/dsh-ssh.json（本机私有文件）";
+    readonly 'form.proxyJump': "跳板机别名";
+    readonly 'form.proxyJumpHint': "逗号分隔的本地主机别名，按顺序连接";
+    readonly 'form.description': "备注";
+    readonly 'form.environment': "环境";
+    readonly 'form.environmentHint': "如 development / production";
+    readonly 'form.tags': "标签";
+    readonly 'form.tagsHint': "逗号分隔";
+    readonly 'form.location': "位置";
+    readonly 'form.save': "保存";
+    readonly 'form.cancel': "取消";
+    readonly 'form.required': "请填写必填字段：别名、主机地址、用户名。";
+    readonly 'form.portInvalid': "端口必须是 1-65535 之间的整数。";
+    readonly 'terminal.selectHost': "选择主机";
+    readonly 'terminal.connect': "连接";
+    readonly 'terminal.disconnect': "断开";
+    readonly 'terminal.placeholder': "选择主机后点击「连接」打开远程终端。";
+    readonly 'terminal.connecting': "正在连接…";
+    readonly 'terminal.ready': "终端已连接（{alias}）";
+    readonly 'terminal.exited': "终端已退出（{alias}）";
+    readonly 'terminal.error': "终端错误：{error}";
+    readonly 'transfer.selectHost': "选择主机";
+    readonly 'transfer.remotePath': "远程路径";
+    readonly 'transfer.remotePathHint': "如 /tmp/ 或 /home/user/app.tar.gz";
+    readonly 'transfer.upload': "上传";
+    readonly 'transfer.uploading': "正在上传 {file}…";
+    readonly 'transfer.download': "下载";
+    readonly 'transfer.downloading': "正在下载…";
+    readonly 'transfer.done': "完成：{bytes} 字节";
+    readonly 'transfer.failed': "传输失败：{error}";
+    readonly 'transfer.browseRemote': "浏览远程目录";
+    readonly 'transfer.refresh': "刷新";
+    readonly 'transfer.name': "名称";
+    readonly 'transfer.upLevel': "上级目录";
+    readonly 'transfer.size': "大小";
+    readonly 'transfer.modified': "修改时间";
+    readonly 'transfer.bytes': "{value} B";
+    readonly 'transfer.kib': "{value} KB";
+    readonly 'transfer.mib': "{value} MB";
+    readonly 'transfer.gib': "{value} GB";
+    readonly 'transfer.percent': "{value}%";
+    readonly 'transfer.speed': "{value}/s";
+    readonly 'transfer.dir': "目录";
+    readonly 'transfer.file': "文件";
+    readonly 'tunnel.empty': "没有活跃的隧道。";
+    readonly 'tunnel.start': "新建隧道";
+    readonly 'tunnel.alias': "主机别名";
+    readonly 'tunnel.remotePort': "远程端口";
+    readonly 'tunnel.remoteHost': "远程主机";
+    readonly 'tunnel.remoteHostHint': "默认 127.0.0.1（服务器自身）";
+    readonly 'tunnel.localPort': "本地端口";
+    readonly 'tunnel.localPortHint': "留空自动分配";
+    readonly 'tunnel.stop': "停止";
+    readonly 'tunnel.stopAll': "全部停止";
+    readonly 'tunnel.stopAllConfirm': "确定停止全部隧道吗？";
+    readonly 'tunnel.row': "{alias}: 127.0.0.1:{localPort} -> {remoteHost}:{remotePort}";
+    readonly 'tunnel.started': "隧道已建立：127.0.0.1:{localPort}";
+    readonly 'tunnel.failed': "隧道启动失败：{error}";
+    readonly 'cluster.command': "命令";
+    readonly 'cluster.run': "执行";
+    readonly 'cluster.confirm': "确定在匹配的主机上执行该命令吗？该操作会真实运行在远程服务器上。";
+    readonly 'cluster.aliases': "主机别名（逗号分隔，留空为全部）";
+    readonly 'cluster.environment': "环境过滤";
+    readonly 'cluster.tags': "标签过滤（逗号分隔）";
+    readonly 'cluster.results': "执行结果";
+    readonly 'cluster.empty': "输入命令后点击「执行」。";
+    readonly 'cluster.noMatch': "没有匹配的主机。";
+    readonly 'cluster.ok': "成功";
+    readonly 'cluster.fail': "失败";
+    readonly 'cluster.timeout': "超时";
+    readonly 'cluster.col.alias': "主机";
+    readonly 'cluster.col.status': "状态";
+    readonly 'cluster.col.exit': "退出码";
+    readonly 'cluster.col.stdout': "标准输出";
+    readonly 'cluster.col.stderr': "标准错误";
+    readonly 'cluster.col.error': "错误";
+    readonly 'cluster.col.duration': "耗时";
+    readonly 'common.loading': "加载中…";
+    readonly 'common.error': "出错：{error}";
+    readonly 'common.refresh': "刷新";
+    readonly 'common.close': "关闭";
+    readonly 'common.confirm': "确定";
+};
+export declare const en: Record<keyof typeof zh, string>;
+/** Locale key union. */
+export type SshKey = keyof typeof zh;
+/** Tiny interpolation: {name} -> value. */
+export declare function t(dictionary: Record<string, string>, key: string, values?: Record<string, string | number>): string;

package/lib/types/client/mount.d.ts

@@ -0,0 +1,12 @@
+import type { SshApi } from './api.ts';
+import type { PanelController } from './panel/controller.ts';
+/** The injected panel container (kept in the DOM, hidden when inactive). */
+export declare const PANEL_VIEW_SELECTOR = "[data-dsh-ssh-view]";
+/**
+ * Mount the panel React tree into the center column and bind its visibility
+ * to the controller's panelOpen state.
+ * @param controller - the panel controller driving the view.
+ * @param api - the SSH API client the tabs operate through.
+ * @returns disposer unmounting the tree and restoring the column.
+ */
+export declare function mountPanel(controller: PanelController, api: SshApi): () => void;

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

@@ -0,0 +1,7 @@
+import type { SshApi } from '../api.ts';
+/** Cluster tab props. */
+export interface ClusterTabProps {
+    api: SshApi;
+}
+/** The cluster execution tab. */
+export declare function ClusterTab({ api }: ClusterTabProps): import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+import type { SshApi } from '../api.ts';
+import type { SshHostSummary } from '../../protocol.ts';
+/** Host form dialog props. */
+export interface HostFormDialogProps {
+    api: SshApi;
+    /** The host being edited; null/undefined means create. */
+    editing?: SshHostSummary | null;
+    onClose: () => void;
+    onSaved: (host: SshHostSummary) => void;
+}
+/** The create/edit host modal. */
+export declare function HostFormDialog({ api, editing, onClose, onSaved }: HostFormDialogProps): import("react").JSX.Element;

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

@@ -0,0 +1,9 @@
+import type { SshApi } from '../api.ts';
+/** Hosts tab props. */
+export interface HostsTabProps {
+    api: SshApi;
+    /** Connect the given alias in the terminal tab. */
+    onConnect: (alias: string) => void;
+}
+/** The hosts table plus its toolbar and dialogs. */
+export declare function HostsTab({ api, onConnect }: HostsTabProps): import("react").JSX.Element;

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

@@ -0,0 +1,13 @@
+import type { SshApi } from '../api.ts';
+import type { PanelController } from './controller.ts';
+/** The panel's tab identifiers. */
+export type SshTab = 'hosts' | 'terminal' | 'transfer' | 'tunnels' | 'cluster';
+/** Panel shell props. */
+export interface SshPanelProps {
+    /** The panel state owner (open/close/toggle). */
+    controller: PanelController;
+    /** The SSH API client every tab operates through. */
+    api: SshApi;
+}
+/** The tabbed SSH panel. */
+export declare function SshPanel({ controller, api }: SshPanelProps): import("react").JSX.Element;

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

@@ -0,0 +1,11 @@
+import type { SshApi } from '../api.ts';
+/** Terminal tab props. */
+export interface TerminalTabProps {
+    api: SshApi;
+    /** Alias preselected by a "connect" action from the hosts tab. */
+    presetAlias?: string;
+    /** Monotonic id of the connect request (re-applies presetAlias). */
+    requestId?: number;
+}
+/** The xterm terminal view. */
+export declare function TerminalTab({ api, presetAlias, requestId }: TerminalTabProps): import("react").JSX.Element;

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

@@ -0,0 +1,7 @@
+import type { SshApi } from '../api.ts';
+/** Transfer tab props. */
+export interface TransferTabProps {
+    api: SshApi;
+}
+/** The upload/download tab. */
+export declare function TransferTab({ api }: TransferTabProps): import("react").JSX.Element;

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

@@ -0,0 +1,7 @@
+import type { SshApi } from '../api.ts';
+/** Tunnels tab props. */
+export interface TunnelsTabProps {
+    api: SshApi;
+}
+/** The tunnels tab. */
+export declare function TunnelsTab({ api }: TunnelsTabProps): import("react").JSX.Element;

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

@@ -0,0 +1,22 @@
+/**
+ * SSH panel controller: the single owner of the panel's open/closed state.
+ *
+ * Framework-free (structural runtime faces, task-board core/controller.ts
+ * style) so the DOM mounts and the React panel share one tiny subscription
+ * surface. The state lives only for the browser session (no persistence).
+ */
+/** Immutable controller snapshot for UI subscriptions. */
+export interface PanelControllerSnapshot {
+    panelOpen: boolean;
+}
+/** The panel state owner the sidebar entry toggles and the view renders from. */
+export declare class PanelController {
+    private panelOpen;
+    private listeners;
+    getSnapshot(): PanelControllerSnapshot;
+    subscribe(fn: () => void): () => void;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    private notify;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Shared panel helpers: the active-dictionary pick (document-language based,
+ * task-board precedent) bound to the dsh-ssh interpolator in locales.ts, plus
+ * a small error-message extractor. All copy stays in the locale dictionaries.
+ */
+import { type SshKey } from '../locales.ts';
+/** Template values accepted by the interpolator. */
+export type TranslateValues = Record<string, string | number>;
+/** Active dictionary, picked by the document language at call time. */
+export declare function dictionary(): Record<string, string>;
+/** Translate a key with optional {name} template params (current language). */
+export declare function tt(key: SshKey, values?: TranslateValues): string;
+/** Human-readable error text from an unknown thrown value. */
+export declare function errorMessage(error: unknown): string;

package/lib/types/client/panel/xterm.css.d.ts

@@ -0,0 +1,2 @@
+/** xterm.css text embedded at build-authoring time (the ?raw suffix is not resolvable by the tsdown/rolldown pipeline). Generated file — see the package docs. */
+export declare const XTERM_CSS: string;

package/lib/types/client/sidebar-entry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Sidebar entry injection.
+ *
+ * dsh's sidebar shell exposes no slot an external plugin can register into,
+ * so — following the task-board precedent of DOM-level extension — the entry
+ * row is injected between the shell's New Session button and the workspace
+ * browser. The injection self-heals: a MutationObserver watches the sidebar
+ * root and re-inserts the row whenever a React re-render displaces it
+ * (re-insertion happens in the same frame, before paint, so no flicker).
+ *
+ * The row is plain DOM (no React tree) so it can never disturb the shell's
+ * reconciliation; the panel view it toggles is a separate React root mounted
+ * in the center column (see mount.tsx).
+ */
+import type { PanelController } from './panel/controller.ts';
+/** Stable data attribute identifying the injected entry row. */
+export declare const ENTRY_SELECTOR = "[data-dsh-ssh-entry]";
+/**
+ * Mount the sidebar entry, waiting for the shell to render and self-healing
+ * on later React re-renders.
+ * @param controller - the panel controller the entry toggles.
+ * @returns disposer removing the entry and its observers.
+ */
+export declare function mountSidebarEntry(controller: PanelController): () => void;

package/lib/types/engine.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The SSH engine: a per-alias persistent connection pool (ssh2) with
+ * multi-hop jump support, command execution, PTY shells, SFTP transfers,
+ * local port-forward tunnels and cluster execution — the DSH counterpart of
+ * ssh-skill's daemon + scripts, living entirely in the host process.
+ */
+import type { ClusterResult, ExecResult, SshHostSummary, TestResult, TransferProgress, TunnelInfo } from './protocol.ts';
+import { type HostStore } from './store.ts';
+/** Default engine knobs. */
+export interface EngineOptions {
+    /** Connections idle longer than this are closed (ms). */
+    idleTimeoutMs?: number;
+    /** SSH handshake timeout (ms). */
+    connectTimeoutMs?: number;
+    /** Keepalive ping interval (ms). */
+    keepaliveIntervalMs?: number;
+    /** Cap on captured stdout/stderr bytes per exec (ms). */
+    maxOutputBytes?: number;
+    /** Default exec timeout (ms). */
+    defaultExecTimeoutMs?: number;
+    /** Default cluster concurrency. */
+    defaultMaxWorkers?: number;
+    /** SFTP concurrent channel count for transfers. */
+    sftpConcurrency?: number;
+}
+/** A live PTY shell session. */
+export interface ShellSession {
+    /** Assign to receive remote output. */
+    onData?: (data: Buffer) => void;
+    /** Assign to be notified when the channel closes. */
+    onExit?: (code: number | null, error?: string) => void;
+    /** Write raw input to the shell. */
+    send(data: string): void;
+    /** Resize the remote PTY. */
+    resize(cols: number, rows: number): void;
+    /** Close the session and its channel. */
+    close(): void;
+    /** Pause remote output delivery (transport backpressure). */
+    pause(): void;
+    /** Resume remote output delivery. */
+    resume(): void;
+}
+/**
+ * The engine. Owns the pool, tunnels, and all operations. One instance per
+ * plugin apply; dispose() closes every connection.
+ */
+export declare class SshEngine {
+    private readonly store;
+    private readonly opts;
+    private readonly pool;
+    private readonly tunnels;
+    private sweepTimer;
+    private nextTunnelId;
+    /**
+     * @param store - the host config store.
+     * @param options - engine knobs (defaults applied).
+     */
+    constructor(store: HostStore, options?: EngineOptions);
+    /** Secret-free host list (filtered by the optional query). */
+    list(query?: string): SshHostSummary[];
+    /** One host summary by alias. */
+    find(alias: string): SshHostSummary | undefined;
+    /**
+     * Run `fn` with a live client for `alias`, reconnecting (up to the
+     * attempt budget) when the connection broke mid-flight.
+     */
+    private withClient;
+    /**
+     * Build one full jump chain for an entry: hop clients connected through in
+     * order, each forwarding a stream to the next destination, ending with the
+     * target client. Shared by the pool and standalone shell sessions.
+     */
+    private connectChain;
+    /** In-flight acquire promises, deduped per alias (concurrent first use). */
+    private readonly acquireQueue;
+    /** Connect (or reuse) the pooled chain for one alias; pins nothing. */
+    private acquire;
+    private doAcquire;
+    /**
+     * Tear down one alias's record. When `record` is given and no longer the
+     * pooled record for the alias (a concurrent acquire replaced it), nothing
+     * is torn down — the connection belongs to someone else now.
+     */
+    private disposeRecord;
+    /** Close connections idle beyond the threshold (skips pinned and in-flight). */
+    private sweep;
+    /** Run one command on `alias` (reusing the pooled connection). */
+    exec(alias: string, command: string, timeoutMs?: number): Promise<ExecResult>;
+    /** Run one command against many hosts concurrently. */
+    cluster(options: {
+        command: string;
+        aliases?: string[];
+        environment?: string;
+        tags?: string[];
+        timeoutMs?: number;
+        maxWorkers?: number;
+    }): Promise<ClusterResult[]>;
+    /** Open a PTY shell session for the web terminal (standalone connection). */
+    openShell(alias: string, size: {
+        cols: number;
+        rows: number;
+    }): Promise<ShellSession>;
+    /** Upload one local file (or directory tree) to a remote path. */
+    upload(alias: string, localPath: string, remotePath: string, recursive: boolean, onProgress?: (progress: TransferProgress) => void): Promise<{
+        bytes: number;
+        files: number;
+    }>;
+    /** Download one remote file to a local path. */
+    download(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void): Promise<{
+        bytes: number;
+    }>;
+    /** List a remote directory (file browser). */
+    ls(alias: string, path: string): Promise<import('./protocol.ts').RemoteDirEntry[]>;
+    private sftp;
+    /** Create a remote directory chain (stat-then-mkdir per segment). */
+    private ensureRemoteDir;
+    private fastPut;
+    private fastGet;
+    /** Start a local port-forward tunnel (listens on 127.0.0.1 only). */
+    startTunnel(alias: string, options: {
+        remotePort: number;
+        remoteHost?: string;
+        localPort?: number;
+    }): Promise<TunnelInfo>;
+    /** All active tunnels. */
+    listTunnels(): TunnelInfo[];
+    /** Stop one tunnel (closes the listener, live sockets, and the pinned connection). */
+    stopTunnel(id: string): boolean;
+    /** Stop all tunnels (optionally for one alias). */
+    stopAllTunnels(alias?: string): number;
+    /** Probe connectivity: connect, run `true`, close. */
+    test(alias: string): Promise<TestResult>;
+    /** Close every pooled connection and tunnel. */
+    dispose(): void;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * dsh-ssh — host half. Mounts the SSH engine (persistent ssh2 connection
+ * pool, exec / PTY shell / SFTP / tunnels / cluster), the /api/dsh-ssh route
+ * family plus the terminal WebSocket upgrade, the agent tools (ssh_list,
+ * ssh_exec, ssh_upload, ssh_download, ssh_tunnel, ssh_cluster), and a
+ * system-prompt announcement. The browser half (./client) renders the host
+ * manager and web terminal. Everything rides official NPM SDK packages —
+ * no dsh source changes.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from 'schemastery';
+/** Stable cordis plugin name. */
+export declare const name = "ssh";
+/** Services required before the SSH surfaces can mount. */
+export declare const inject: string[];
+/**
+ * Settings namespace of the SSH capability — the section the web settings
+ * surface edits. Spelled here rather than imported: the browser half spells
+ * the same value and must not depend on a Host package.
+ */
+export declare const SSH_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+/** Plugin config, validated by the same-named schemastery schema. */
+export interface Config {
+    /**
+     * When true (default), a system-prompt section announces the SSH plugin to
+     * every agent (tools + host store). Set false to keep it silent.
+     */
+    announceToAgent?: boolean;
+    /** Master switch for the plugin (routes, tools, prompt section). */
+    enabled?: boolean;
+}
+export declare const Config: z<Config>;
+/** Model-facing announcement: plugin presence, capabilities, and limits. */
+export declare const SSH_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-ssh \u63D2\u4EF6\uFF08DSH \u8FDC\u7A0B SSH \u8FD0\u7EF4\uFF09\uFF1A\u4FA7\u8FB9\u680F\u300CSSH\u300D\u5165\u53E3\uFF1B\u5728 dsh-web-ui \u63D2\u4EF6\u5168\u5BB6\u6876\u4ED3\u5E93\uFF08packages/dsh-ssh\uFF09\u7EDF\u4E00\u7EF4\u62A4\u3002\u80FD\u529B\uFF1A\u4E3B\u673A\u914D\u7F6E\u5B58 ~/.dsh/dsh-ssh.json\uFF08\u53EF\u4ECE ~/.ssh/config \u5BFC\u5165\uFF09\uFF1B\u6301\u4E45\u8FDE\u63A5\u6C60\u590D\u7528\u957F\u8FDE\u63A5\uFF08\u7A7A\u95F2 30 \u5206\u949F\u81EA\u52A8\u65AD\u5F00\uFF09\uFF1Bssh_list \u5217\u51FA\u4E3B\u673A\u3001ssh_exec \u6267\u884C\u8FDC\u7A0B\u547D\u4EE4\u3001ssh_upload/ssh_download \u4F20\u8F93\u6587\u4EF6\u3001ssh_tunnel \u672C\u5730\u7AEF\u53E3\u8F6C\u53D1\uFF08\u8BBF\u95EE\u8FDC\u7A0B\u6570\u636E\u5E93/\u5185\u7F51\u670D\u52A1\uFF09\u3001ssh_cluster \u96C6\u7FA4\u5E76\u53D1\u6267\u884C\uFF1B\u652F\u6301\u5BC6\u94A5/\u5BC6\u7801\u8BA4\u8BC1\u3001passphrase \u5BC6\u94A5\u4E0E ProxyJump \u8DF3\u677F\u673A\uFF1BWeb \u7EC8\u7AEF\u8D70 WebSocket\u3002\u9650\u5236\uFF1A\u4E3B\u673A\u64CD\u4F5C\u7531\u7528\u6237\u5728 GUI \u4E2D\u914D\u7F6E\u540E agent \u65B9\u53EF\u4F7F\u7528\uFF1B\u5BC6\u7801\u4EE5\u660E\u6587\u5B58\u5728\u7528\u6237\u4E3B\u76EE\u5F55\u79C1\u6709\u6587\u4EF6\uFF08\u6743\u9650 0600\uFF09\uFF1B\u547D\u4EE4\u8F93\u51FA\u539F\u6837\u8FD4\u56DE\u3001\u53EF\u80FD\u542B\u654F\u611F\u4FE1\u606F\uFF1B\u65AD\u7EBF\u91CD\u8FDE\u53EF\u80FD\u91CD\u653E\u975E\u5E42\u7B49\u547D\u4EE4\uFF1B\u4F20\u8F93/\u6267\u884C\u6D88\u8017\u771F\u5B9E\u8FDC\u7A0B\u8D44\u6E90\uFF0C\u5148\u786E\u8BA4\u518D\u64CD\u4F5C\u3002\u7528\u6237\u63D0\u5230\u300CSSH / \u8FDC\u7A0B\u670D\u52A1\u5668 / \u670D\u52A1\u5668\u64CD\u4F5C / \u8DF3\u677F\u673A / \u96A7\u9053 / \u90E8\u7F72 / \u4E0A\u4F20\u4E0B\u8F7D\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
+/**
+ * Mount the SSH engine, routes, tools, and announcement.
+ * @param ctx - host plugin context carrying webServer/tools/systemPrompt.
+ * @param config - resolved plugin config (schema defaults applied by the loader).
+ */
+export declare function apply(ctx: Context, config?: Config): void;

package/lib/types/invariant.d.ts

@@ -0,0 +1,3 @@
+/** Invariant companion plugin (no assertions — nothing to check at runtime). */
+/** Provides no assertions: the ssh plugin owns no cross-package runtime invariants. */
+export declare function apply(): void;