@linxin666/dsh-ssh 0.1.1

package/lib/types/protocol.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Wire contract between the host half (routes.ts) and the browser half
+ * (client/api.ts). Pure types only — imported by both halves, bundled into
+ * each, no runtime identity to share.
+ */
+/** Authentication flavors a host entry may carry. */
+export type SshAuthKind = 'key' | 'password';
+/** One stored host entry (the ~/.dsh/dsh-ssh.json store shape). */
+export interface SshHostEntry {
+    /** Stable, user-chosen identifier used by every operation. */
+    alias: string;
+    /** Hostname or IP of the target. */
+    host: string;
+    /** SSH port (default 22). */
+    port: number;
+    /** Login user. */
+    user: string;
+    /** Authentication. */
+    auth: {
+        kind: SshAuthKind;
+        /** Absolute path to the private key for 'key' auth. */
+        keyPath?: string;
+        /** Passphrase for an encrypted key. */
+        passphrase?: string;
+        /** Password for 'password' auth. */
+        password?: string;
+    };
+    /** Jump chain: local aliases connected through in order (ProxyJump). */
+    proxyJump: string[];
+    /** Free-form note. */
+    description?: string;
+    /** Deployment environment label (development / production / ...). */
+    environment?: string;
+    /** Free-form tags. */
+    tags: string[];
+    /** Physical location note. */
+    location?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Public (secret-free) projection of an entry, safe for the browser/agent. */
+export interface SshHostSummary {
+    alias: string;
+    host: string;
+    port: number;
+    user: string;
+    auth: SshAuthKind;
+    /** Whether the key path exists on the host machine (key auth only). */
+    keyReady: boolean;
+    proxyJump: string[];
+    description?: string;
+    environment?: string;
+    tags: string[];
+    location?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Result of one non-interactive command execution. */
+export interface ExecResult {
+    success: boolean;
+    /** Remote exit code, or null when the channel died without one. */
+    exitCode: number | null;
+    timedOut: boolean;
+    stdout: string;
+    stderr: string;
+    /** Wall-clock duration of the round trip in ms. */
+    durationMs: number;
+    /** Connection error message when the command never ran. */
+    error?: string;
+}
+/** One server entry in a cluster run. */
+export interface ClusterResult {
+    alias: string;
+    ok: boolean;
+    exitCode?: number | null;
+    timedOut?: boolean;
+    stdout?: string;
+    stderr?: string;
+    durationMs?: number;
+    error?: string;
+}
+/** SFTP transfer progress frame (upload stream). */
+export interface TransferProgress {
+    phase: 'connecting' | 'transferring' | 'done' | 'error';
+    file: string;
+    transferred: number;
+    total: number;
+    percent: number;
+    speedBps?: number;
+    error?: string;
+}
+/** One active local port-forward tunnel. */
+export interface TunnelInfo {
+    id: string;
+    alias: string;
+    localPort: number;
+    remoteHost: string;
+    remotePort: number;
+    state: 'forwarding' | 'connecting' | 'failed';
+    error?: string;
+    startedAt: number;
+}
+/** One directory listing entry (remote file browser). */
+export interface RemoteDirEntry {
+    name: string;
+    type: 'dir' | 'file' | 'other';
+    size: number;
+    mtimeMs: number;
+    mode?: number;
+}
+/** Test-connection outcome. */
+export interface TestResult {
+    ok: boolean;
+    latencyMs?: number;
+    error?: string;
+}
+/** Host edit payload (create/update); 'alias' comes from the URL for updates. */
+export interface HostPayload {
+    alias?: string;
+    host: string;
+    port?: number;
+    user: string;
+    /**
+     * Authentication. Required on create; on update an omitted auth keeps the
+     * stored secrets (the browser never receives them back).
+     */
+    auth?: SshHostEntry['auth'];
+    proxyJump?: string[];
+    description?: string;
+    environment?: string;
+    tags?: string[];
+    location?: string;
+}
+/** Import outcome from ~/.ssh/config. */
+export interface ImportResult {
+    parsed: number;
+    added: number;
+    skipped: number;
+    /** Aliases that failed to map (wildcard patterns, missing HostName, ...). */
+    skippedNames: string[];
+}
+/** JSON error body used by every route. */
+export interface ApiErrorBody {
+    error: string;
+}
+/** WebSocket terminal protocol frames (host -> client and client -> host). */
+export type TerminalServerFrame = {
+    type: 'ready';
+    alias: string;
+} | {
+    type: 'output';
+    data: string;
+} | {
+    type: 'exit';
+    code: number | null;
+    error?: string;
+};
+export type TerminalClientFrame = {
+    type: 'input';
+    data: string;
+} | {
+    type: 'resize';
+    cols: number;
+    rows: number;
+};
+/** Route paths the client calls (shared literals). */
+export declare const SSH_API_BASE: "/api/dsh-ssh";
+export declare const SSH_API: {
+    readonly hosts: string;
+    readonly importSshConfig: string;
+    readonly test: string;
+    readonly exec: string;
+    readonly cluster: string;
+    readonly upload: string;
+    readonly download: string;
+    readonly ls: string;
+    readonly tunnel: string;
+    readonly terminal: string;
+};
+/** NDJSON transfer stream line shapes (upload). */
+export type TransferStreamLine = {
+    type: 'progress';
+    progress: TransferProgress;
+} | {
+    type: 'result';
+    ok: boolean;
+    transferredBytes?: number;
+    error?: string;
+};

package/lib/types/routes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The /api/dsh-ssh route family: host CRUD, exec, cluster, SFTP transfer
+ * (NDJSON progress stream for uploads, binary stream for downloads), remote
+ * listing, tunnels, and the WebSocket PTY terminal upgrade. Every route
+ * carries a loopback-only trust fence (plus browser same-origin markers) —
+ * these endpoints execute commands on remote servers, so LAN-exposed dsh web
+ * deployments must not serve them.
+ */
+import type { WebRoute, WebUpgradeRoute } from '@deepseek-ai/dsh-host-webserver';
+import type { SshEngine } from './engine.ts';
+import type { HostStore } from './store.ts';
+/** Route family dependencies. */
+export interface SshRoutesDeps {
+    /** The host store (CRUD). */
+    store: HostStore;
+    /** The engine (ops). */
+    engine: SshEngine;
+    /** Temp dir for upload/download staging (tests inject a sandbox). */
+    stagingDir?: string;
+}
+/**
+ * Build every /api/dsh-ssh route (exact paths) plus the terminal upgrade.
+ * @param deps - store, engine, staging dir.
+ * @returns routes and the upgrade route.
+ */
+export declare function makeRoutes(deps: SshRoutesDeps): {
+    routes: WebRoute[];
+    upgrade: WebUpgradeRoute;
+};

package/lib/types/store.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Host config store: one JSON file (`~/.dsh/dsh-ssh.json`) holding every
+ * SSH host entry, written atomically (tmp + rename). Also parses the user's
+ * standard `~/.ssh/config` for one-shot import. Secrets (passwords,
+ * passphrases) live in this user-owned file in plaintext — same trust model
+ * as ssh-skill's annotated ssh-config comments; document it, never log it.
+ */
+import type { HostPayload, ImportResult, SshHostEntry, SshHostSummary } from './protocol.ts';
+/** Store file location: <home>/.dsh/dsh-ssh.json. */
+export declare function storePath(): string;
+/** The user's standard OpenSSH config path. */
+export declare function sshConfigPath(): string;
+/** Validate the wire shape of a host payload; returns a message or undefined. */
+export declare function validateHostPayload(payload: unknown): string | undefined;
+/** Validate an alias for creation. */
+export declare function validateAlias(alias: string): string | undefined;
+/**
+ * The host store. Pure file I/O — no cordis dependency, unit-testable.
+ */
+export declare class HostStore {
+    /** The JSON file path. */
+    readonly path: string;
+    /** Optional override of the ~/.ssh/config path (tests). */
+    private readonly sshConfigOverride;
+    /**
+     * @param path - store file path (defaults to the standard location).
+     * @param sshConfigOverride - ssh config path override (tests only).
+     */
+    constructor(path?: string, sshConfigOverride?: string);
+    /** Load all entries (empty store when the file is absent). */
+    list(): SshHostEntry[];
+    /** Find one entry by alias. */
+    find(alias: string): SshHostEntry | undefined;
+    /** Secret-free projection for the browser and agent surfaces. */
+    summarize(entry: SshHostEntry): SshHostSummary;
+    /** Create one entry. Throws on alias collision or invalid payload. */
+    create(payload: HostPayload): SshHostEntry;
+    /** Update the fields present in `patch`; unknown aliases throw. */
+    update(alias: string, patch: Partial<HostPayload>): SshHostEntry;
+    /** Remove one entry. */
+    delete(alias: string): void;
+    /**
+     * Import hosts from `~/.ssh/config`: Host blocks with a single non-wildcard
+     * pattern and a HostName become entries (key auth via IdentityFile, jump
+     * hosts via ProxyJump). Existing aliases are skipped.
+     * @returns import statistics.
+     */
+    importFromSshConfig(): ImportResult;
+    private skippedNames;
+    private load;
+    private save;
+}
+/** Expand a leading `~` in a filesystem path. */
+export declare function expandHome(path: string): string;

package/lib/types/tools.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Agent tools: the DSH-native counterpart of ssh-skill's CLI. Every tool
+ * talks to the same engine the web UI uses, so a host configured in the GUI
+ * is immediately operable by any agent, and vice versa.
+ */
+import type { SshEngine } from './engine.ts';
+/** The host-list tool. */
+export declare function sshListTool(engine: SshEngine): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** The command-execution tool. */
+export declare function sshExecTool(engine: SshEngine): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** The upload tool. */
+export declare function sshUploadTool(engine: SshEngine): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** The download tool. */
+export declare function sshDownloadTool(engine: SshEngine): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** The tunnel tool. */
+export declare function sshTunnelTool(engine: SshEngine): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** The cluster tool. */
+export declare function sshClusterTool(engine: SshEngine): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@linxin666/dsh-ssh",
+  "description": "Remote SSH operations for the dsh web GUI: host config store (~/.dsh/dsh-ssh.json, import from ~/.ssh/config), a persistent ssh2 connection pool with jump-host support, exec / PTY web terminal / SFTP transfer / local port-forward tunnels / cluster execution, plus agent tools (ssh_list, ssh_exec, ssh_upload, ssh_download, ssh_tunnel, ssh_cluster). Hot-pluggable — mounted via ~/.dsh/cordis.patch.yml + a profile node_modules symlink, no dsh source changes.",
+  "version": "0.1.1",
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ],
+      "platform": "web"
+    }
+  },
+  "dependencies": {
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^6.0.0",
+    "ssh2": "^1.17.0",
+    "ws": "^8.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-connection": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@types/node": "^22.20.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "^18.3.5",
+    "@types/ssh2": "^1.15.5",
+    "@types/ws": "^8.5.13",
+    "jsdom": "^25.0.0",
+    "lightningcss": "1.32.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "schemastery": "^3.18.0",
+    "tsdown": "0.22.2",
+    "typescript": "~5.7.2",
+    "vitest": "^3.0.0"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "license": "BSD-3-Clause",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsdown",
+    "bundle": "tsdown",
+    "watch": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}