@linxin666/dsh-ssh 0.1.1

package/src/index.ts

@@ -0,0 +1,155 @@
+/**
+ * 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 { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
+import z from 'schemastery'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import type {} from '@deepseek-ai/dsh-tools'
+import { SshEngine } from './engine.ts'
+import { makeRoutes } from './routes.ts'
+import { HostStore } from './store.ts'
+import { sshClusterTool, sshDownloadTool, sshExecTool, sshListTool, sshTunnelTool, sshUploadTool } from './tools.ts'
+
+/** Stable cordis plugin name. */
+export const name = 'ssh'
+
+/** Services required before the SSH surfaces can mount. */
+export const inject = ['webServer', 'tools', 'systemPrompt']
+
+/**
+ * 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 const SSH_SETTINGS_NAMESPACE = settingsNamespace('dsh-ssh')
+
+/** 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 const Config: z<Config> = z.object({
+  announceToAgent: z.boolean().default(true),
+  enabled: z.boolean().default(true),
+})
+
+/** Schema default, re-read for hand-built test contexts (the loader applies them normally). */
+const DEFAULT_ANNOUNCE = true
+
+/** Order of the announcement section within the tool-guidance band. */
+const SECTION_ORDER = 150
+
+/** Model-facing announcement: plugin presence, capabilities, and limits. */
+export const SSH_GUIDANCE = '本机已安装 dsh-ssh 插件（DSH 远程 SSH 运维）：侧边栏「SSH」入口；在 dsh-web-ui 插件全家桶仓库（packages/dsh-ssh）统一维护。能力：主机配置存 ~/.dsh/dsh-ssh.json（可从 ~/.ssh/config 导入）；持久连接池复用长连接（空闲 30 分钟自动断开）；ssh_list 列出主机、ssh_exec 执行远程命令、ssh_upload/ssh_download 传输文件、ssh_tunnel 本地端口转发（访问远程数据库/内网服务）、ssh_cluster 集群并发执行；支持密钥/密码认证、passphrase 密钥与 ProxyJump 跳板机；Web 终端走 WebSocket。限制：主机操作由用户在 GUI 中配置后 agent 方可使用；密码以明文存在用户主目录私有文件（权限 0600）；命令输出原样返回、可能含敏感信息；断线重连可能重放非幂等命令；传输/执行消耗真实远程资源，先确认再操作。用户提到「SSH / 远程服务器 / 服务器操作 / 跳板机 / 隧道 / 部署 / 上传下载」时即指本插件，请据此协作。'
+
+/**
+ * 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 function apply(ctx: Context, config?: Config): void {
+  // The live source the surfaces read: the settings section once the web
+  // settings surface is served, the composition entry otherwise.
+  let current: () => Config = () => config ?? {}
+  const resolve = (): Config => {
+    const value = current()
+    return {
+      announceToAgent: value.announceToAgent ?? DEFAULT_ANNOUNCE,
+      enabled: value.enabled ?? true,
+    }
+  }
+
+  const store = new HostStore()
+  const engine = new SshEngine(store)
+  ctx.effect(() => () => { engine.dispose() }, 'dsh-ssh: engine')
+
+  // The /api/dsh-ssh route family + terminal upgrade.
+  const { routes, upgrade } = makeRoutes({ store, engine })
+  let disposeRoutes: (() => void) | undefined
+
+  // Agent tools + their prompt sections.
+  const tools = [
+    sshListTool(engine),
+    sshExecTool(engine),
+    sshUploadTool(engine),
+    sshDownloadTool(engine),
+    sshTunnelTool(engine),
+    sshClusterTool(engine),
+  ]
+  let disposeTools: (() => void) | undefined
+
+  // System-prompt announcement.
+  let disposeSection: (() => void) | undefined
+
+  // Register (or drop) every surface to match the current source. Each group
+  // is kept under one disposer: re-registering first tears the old one down
+  // so duplicate-name registrations never throw.
+  const sync = (): void => {
+    const value = resolve()
+    if (disposeSection !== undefined) {
+      disposeSection()
+      disposeSection = undefined
+    }
+    if (disposeRoutes !== undefined) {
+      disposeRoutes()
+      disposeRoutes = undefined
+    }
+    if (disposeTools !== undefined) {
+      disposeTools()
+      disposeTools = undefined
+    }
+    if (!value.enabled) return
+    if (value.announceToAgent) {
+      disposeSection = ctx.systemPrompt.section({
+        name: 'plugin:dsh-ssh',
+        order: SECTION_ORDER,
+        text: SSH_GUIDANCE,
+      })
+    }
+    disposeRoutes = ctx.effect(
+      () => {
+        const disposers = routes.map(route => ctx.webServer.register(route))
+        const upgradeDisposer = ctx.webServer.registerUpgrade(upgrade)
+        return () => {
+          for (const dispose of disposers) dispose()
+          upgradeDisposer()
+        }
+      },
+      'dsh-ssh: routes',
+    )
+    disposeTools = ctx.effect(
+      () => {
+        const disposers = tools.map(tool => ctx.tools.register(tool))
+        return () => { for (const dispose of disposers) dispose() }
+      },
+      'dsh-ssh: tools',
+    )
+  }
+
+  installSettingsSection(ctx, SSH_SETTINGS_NAMESPACE, Config, config ?? {}, {
+    setSource: (source) => {
+      current = source
+      sync()
+    },
+    onChange: sync,
+  })
+
+  // Initial registration from the composition entry (covers deployments with
+  // no settings service, whose installSettingsSection never fires its hooks).
+  sync()
+}

package/src/invariant.ts

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

package/src/protocol.ts

@@ -0,0 +1,188 @@
+/**
+ * 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 const SSH_API_BASE = '/api/dsh-ssh' as const
+
+export const SSH_API = {
+  hosts: SSH_API_BASE + '/hosts',
+  importSshConfig: SSH_API_BASE + '/hosts/import-ssh-config',
+  test: SSH_API_BASE + '/test',
+  exec: SSH_API_BASE + '/exec',
+  cluster: SSH_API_BASE + '/cluster',
+  upload: SSH_API_BASE + '/upload',
+  download: SSH_API_BASE + '/download',
+  ls: SSH_API_BASE + '/ls',
+  tunnel: SSH_API_BASE + '/tunnel',
+  terminal: SSH_API_BASE + '/terminal',
+} as const
+
+/** NDJSON transfer stream line shapes (upload). */
+export type TransferStreamLine =
+  | { type: 'progress'; progress: TransferProgress }
+  | { type: 'result'; ok: boolean; transferredBytes?: number; error?: string }