@tiphareth/dsh-hardssh 0.1.2

package/src/client/migrate.ts

@@ -0,0 +1,109 @@
+/**
+ * One-time migration from the legacy GLOBAL local⇄remote mode. The previous
+ * hardssh client persisted each session's mode in localStorage under
+ * `ssh-session-state:<sessionId>`; a remembered REMOTE target meant the whole
+ * host switched to that SSH server. With the workspace-bound redesign, the
+ * correct home for that binding is an SSH workspace record. This module
+ * scans the legacy keys, converts each DISTINCT remote target (alias +
+ * remoteRoot) into a ledger record (reusing it for every session that shared
+ * it), and clears the legacy keys so the migration runs exactly once.
+ *
+ * Best-effort: any failure is logged by the caller and never blocks boot.
+ * @module dsh-hardssh/client/migrate
+ */
+
+import type { WorkspaceApi } from './api.ts'
+
+const LEGACY_KEY_PREFIX = 'ssh-session-state:'
+
+/** The distinct remote targets remembered by the legacy build. */
+interface LegacyTarget {
+  alias: string
+  remoteRoot?: string
+  // A human label when the legacy build kept one ('~' or an explicit path).
+  label?: string
+}
+
+/** Read one legacy key (guarded, lenient). */
+function readLegacy(key: string): LegacyTarget | null {
+  try {
+    const raw = localStorage.getItem(key)
+    if (raw === null) return null
+    const parsed = JSON.parse(raw) as Record<string, unknown>
+    if (parsed.mode !== 'remote' || typeof parsed.alias !== 'string' || parsed.alias === '') return null
+    return {
+      alias: parsed.alias,
+      remoteRoot: typeof parsed.remoteRoot === 'string' && parsed.remoteRoot !== '' ? parsed.remoteRoot : undefined,
+      label: typeof parsed.remoteRootLabel === 'string' ? parsed.remoteRootLabel : undefined,
+    }
+  } catch {
+    return null
+  }
+}
+
+/** All legacy session-memory keys present. */
+function legacyKeys(): string[] {
+  const keys: string[] = []
+  for (let index = 0; index < localStorage.length; index += 1) {
+    const key = localStorage.key(index)
+    if (key !== null && key.startsWith(LEGACY_KEY_PREFIX)) keys.push(key)
+  }
+  return keys
+}
+
+/**
+ * Migrate legacy remote memories into SSH workspace records. Returns the
+ * number of workspaces created (0 when nothing to do).
+ */
+export async function migrateLegacySessionMemory(api: WorkspaceApi): Promise<number> {
+  const keys = legacyKeys()
+  if (keys.length === 0) return 0
+
+  // Collect the distinct remote targets (dedupe by alias + remoteRoot).
+  const targets: LegacyTarget[] = []
+  const seen = new Set<string>()
+  for (const key of keys) {
+    const target = readLegacy(key)
+    if (target === null) continue
+    const id = `${target.alias}|${target.remoteRoot ?? ''}`
+    if (seen.has(id)) continue
+    seen.add(id)
+    targets.push(target)
+  }
+  if (targets.length === 0) {
+    // Nothing remote in the legacy memory: just clear the stale keys.
+    for (const key of keys) localStorage.removeItem(key)
+    return 0
+  }
+
+  // Existing workspace records (so a re-run never duplicates).
+  const existing = await api.listWorkspaces()
+  const existingKey = new Set(existing.map((record) => `${record.alias}|${record.remoteRoot}`))
+  let created = 0
+
+  for (const target of targets) {
+    const id = `${target.alias}|${target.remoteRoot ?? ''}`
+    if (existingKey.has(id)) continue
+    // The legacy build stored '~' as the label but the RESOLVED root in
+    // remoteRoot — use the root as the workspace root verbatim.
+    if (target.remoteRoot === undefined || target.remoteRoot === '') {
+      // No resolved root: the legacy host resolved it on connect; guard by
+      // skipping a target we cannot address (can't create without a root).
+      continue
+    }
+    const title = target.label === '~' || target.label === undefined
+      ? `${target.alias}:home`
+      : target.label.split('/').filter(Boolean).pop() ?? target.alias
+    try {
+      await api.createWorkspace({ title, alias: target.alias, remoteRoot: target.remoteRoot })
+      created += 1
+    } catch (error) {
+      // One failed target must not block the rest.
+      console.warn(`[dsh-hardssh] migration of ${target.alias}@${target.remoteRoot} failed:`, error)
+    }
+  }
+
+  // Clear the legacy keys: the migration is done exactly once.
+  for (const key of keys) localStorage.removeItem(key)
+  return created
+}

package/src/client/ssh/api.ts

@@ -0,0 +1,411 @@
+/**
+ * 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 {
+  SSH_API,
+  type ClusterResult,
+  type ExecResult,
+  type HostPayload,
+  type ImportResult,
+  type KnownHostAction,
+  type KnownHostView,
+  type RemoteDirEntry,
+  type SshHostSummary,
+  type TerminalClientFrame,
+  type TerminalServerFrame,
+  type TestResult,
+  type TransferProgress,
+  type TransferStreamLine,
+  type TunnelInfo,
+} from '../../ssh/protocol.ts'
+
+/** Minimal File System Access API surface (not in all lib.dom versions). */
+interface WindowWithFileSystemAccess {
+  showSaveFilePicker?: (options: { suggestedName?: string }) => Promise<{
+    createWritable: () => Promise<{ write: (data: Uint8Array) => Promise<void>; close: () => Promise<void> }>
+  }>
+}
+
+/** Error carrying the route's JSON error message. */
+export class SshApiError extends Error {
+  /** Stable machine code from the route error body (HOST_KEY_*, HOST_IN_USE, …). */
+  readonly code: string | undefined
+  readonly hostKeyFingerprint: string | undefined
+  constructor(message: string, code?: string, hostKeyFingerprint?: string) {
+    super(message)
+    this.name = 'SshApiError'
+    this.code = code
+    this.hostKeyFingerprint = hostKeyFingerprint
+  }
+}
+
+/** Parse a JSON response or throw an SshApiError. */
+async function readJson<T>(response: Response): Promise<T> {
+  let body: unknown
+  try {
+    body = await response.json()
+  } catch {
+    throw new SshApiError(`HTTP ${response.status}: invalid JSON response`)
+  }
+  if (!response.ok) {
+    const record = typeof body === 'object' && body !== null ? body as Record<string, unknown> : {}
+    const message = typeof record.error === 'string' ? record.error : `HTTP ${response.status}`
+    const code = typeof record.code === 'string' ? record.code : undefined
+    const hostKeyFingerprint = typeof record.hostKeyFingerprint === 'string' ? record.hostKeyFingerprint : undefined
+    throw new SshApiError(message, code, hostKeyFingerprint)
+  }
+  return body as T
+}
+
+/** Query-string helper. */
+function query(params: Record<string, string | number | undefined>): string {
+  const search = new URLSearchParams()
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== '') search.set(key, String(value))
+  }
+  const text = search.toString()
+  return text === '' ? '' : '?' + text
+}
+
+/** 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 class SshApi {
+  // -------------------------------------------------------------- hosts
+  async listHosts(queryText?: string): Promise<SshHostSummary[]> {
+    const response = await fetch(SSH_API.hosts + query({ query: queryText }))
+    const body = await readJson<{ hosts: SshHostSummary[] }>(response)
+    return body.hosts
+  }
+
+  async createHost(payload: HostPayload): Promise<SshHostSummary> {
+    const response = await fetch(SSH_API.hosts, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    const body = await readJson<{ host: SshHostSummary }>(response)
+    return body.host
+  }
+
+  async updateHost(alias: string, patch: HostPayload): Promise<SshHostSummary> {
+    const response = await fetch(SSH_API.hosts + query({ alias }), {
+      method: 'PATCH',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(patch),
+    })
+    const body = await readJson<{ host: SshHostSummary }>(response)
+    return body.host
+  }
+
+  async deleteHost(alias: string): Promise<void> {
+    const response = await fetch(SSH_API.hosts + query({ alias }), { method: 'DELETE' })
+    await readJson<{ ok: boolean }>(response)
+  }
+
+  async importSshConfig(): Promise<ImportResult> {
+    const response = await fetch(SSH_API.importSshConfig, { method: 'POST' })
+    const body = await readJson<{ result: ImportResult }>(response)
+    return body.result
+  }
+
+  // ---------------------------------------------------------------- ops
+  async testHost(alias: string): Promise<TestResult> {
+    const response = await fetch(SSH_API.test, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ alias }),
+    })
+    const body = await readJson<{ result: TestResult }>(response)
+    return body.result
+  }
+
+  async exec(alias: string, command: string, timeoutMs?: number): Promise<ExecResult> {
+    const response = await fetch(SSH_API.exec, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ alias, command, timeoutMs }),
+    })
+    const body = await readJson<{ result: ExecResult }>(response)
+    return body.result
+  }
+
+  async cluster(options: {
+    command: string
+    aliases?: string[]
+    environment?: string
+    tags?: string[]
+    timeoutMs?: number
+    maxWorkers?: number
+  }): Promise<ClusterResult[]> {
+    const response = await fetch(SSH_API.cluster, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(options),
+    })
+    const body = await readJson<{ results: ClusterResult[] }>(response)
+    return body.results
+  }
+
+  // ----------------------------------------------------------------- ls
+  async ls(alias: string, path: string): Promise<RemoteDirEntry[]> {
+    const response = await fetch(SSH_API.ls + query({ alias, path }))
+    const body = await readJson<{ entries: RemoteDirEntry[] }>(response)
+    return body.entries
+  }
+
+  // ------------------------------------------------------------- tunnel
+  async listTunnels(): Promise<TunnelInfo[]> {
+    const response = await fetch(SSH_API.tunnel, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ action: 'list' }),
+    })
+    const body = await readJson<{ tunnels: TunnelInfo[] }>(response)
+    return body.tunnels
+  }
+
+  async startTunnel(options: { alias: string; remotePort: number; remoteHost?: string; localPort?: number }): Promise<TunnelInfo> {
+    const response = await fetch(SSH_API.tunnel, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ action: 'start', ...options }),
+    })
+    const body = await readJson<{ tunnel: TunnelInfo }>(response)
+    return body.tunnel
+  }
+
+  async stopTunnel(tunnelId: string): Promise<boolean> {
+    const response = await fetch(SSH_API.tunnel, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ action: 'stop', tunnelId }),
+    })
+    const body = await readJson<{ ok: boolean }>(response)
+    return body.ok
+  }
+
+  async stopAllTunnels(alias?: string): Promise<number> {
+    const response = await fetch(SSH_API.tunnel, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ action: 'stop-all', alias }),
+    })
+    const body = await readJson<{ stopped: number }>(response)
+    return body.stopped
+  }
+
+  // ------------------------------------------------------------ transfer
+  /**
+   * Upload one file (raw bytes) to a remote path. Progress arrives through
+   * the NDJSON response stream; resolves when the result frame lands.
+   */
+  async uploadFile(
+    file: File,
+    alias: string,
+    remotePath: string,
+    onProgress?: (progress: TransferProgress) => void,
+  ): Promise<{ transferredBytes: number }> {
+    const response = await fetch(SSH_API.upload + query({ alias, remotePath }), {
+      method: 'POST',
+      body: file,
+    })
+    if (!response.ok || response.body === null) {
+      throw new SshApiError(`upload failed: HTTP ${response.status}`)
+    }
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+    let finalError: string | undefined
+    let sawResult = false
+    let transferredBytes = 0
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      buffer += decoder.decode(value, { stream: true })
+      const lines = buffer.split('\n')
+      buffer = lines.pop() ?? ''
+      for (const line of lines) {
+        if (line.trim() === '') continue
+        let parsed: TransferStreamLine
+        try {
+          parsed = JSON.parse(line) as TransferStreamLine
+        } catch {
+          continue
+        }
+        if (parsed.type === 'progress') {
+          onProgress?.(parsed.progress)
+        } else if (parsed.type === 'result') {
+          sawResult = true
+          if (parsed.ok) transferredBytes = parsed.transferredBytes ?? 0
+          finalError = parsed.ok ? undefined : parsed.error ?? 'upload failed'
+        }
+      }
+    }
+    if (finalError !== undefined) throw new SshApiError(finalError)
+    if (!sawResult) throw new SshApiError('upload ended without a result frame — the transfer did not complete')
+    return { transferredBytes }
+  }
+
+  /**
+   * 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.
+   */
+  async downloadFile(
+    alias: string,
+    remotePath: string,
+    onProgress?: (progress: TransferProgress) => void,
+  ): Promise<{ blob?: Blob; filename: string; streamed: boolean; bytes: number }> {
+    const response = await fetch(SSH_API.download + query({ alias, remotePath }))
+    if (!response.ok || response.body === null) {
+      const text = await response.text().catch(() => '')
+      throw new SshApiError(text !== '' && text.startsWith('{') ? text : `download failed: HTTP ${response.status}`)
+    }
+    const total = Number(response.headers.get('content-length') ?? '0')
+    const disposition = response.headers.get('content-disposition') ?? ''
+    const match = /filename="([^"]+)"/.exec(disposition)
+    const filename = match?.[1] ?? remotePath.split('/').pop() ?? 'download'
+    const reader = response.body.getReader()
+    const picker = typeof window !== 'undefined'
+      ? (window as WindowWithFileSystemAccess).showSaveFilePicker
+      : undefined
+    let streamed = false
+    let writable: { write: (data: Uint8Array) => Promise<void>; close: () => Promise<void> } | undefined
+    const chunks: Uint8Array<ArrayBuffer>[] = []
+    let received = 0
+    const progress = (): void => {
+      onProgress?.({
+        phase: 'transferring',
+        file: remotePath,
+        transferred: received,
+        total,
+        percent: total > 0 ? Math.round((received / total) * 1000) / 10 : 0,
+      })
+    }
+    try {
+      if (picker !== undefined) {
+        const handle = await picker.call(window, { suggestedName: filename })
+        writable = await handle.createWritable()
+        streamed = true
+      }
+    } catch {
+      // User cancelled the save dialog or the API is unavailable: fall back.
+    }
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      if (writable !== undefined) {
+        await writable.write(value as Uint8Array)
+      } else {
+        chunks.push(value as Uint8Array<ArrayBuffer>)
+      }
+      received += value.length
+      progress()
+    }
+    if (writable !== undefined) await writable.close()
+    onProgress?.({ phase: 'done', file: remotePath, transferred: received, total: received > 0 ? received : total, percent: 100 })
+    return {
+      blob: streamed ? undefined : new Blob(chunks),
+      filename,
+      streamed,
+      bytes: received,
+    }
+  }
+
+  // ------------------------------------------------------------ terminal
+  /** Open a WebSocket terminal session. */
+  openTerminal(alias: string, cols: number, rows: number): TerminalConnection {
+    const scheme = window.location.protocol === 'https:' ? 'wss' : 'ws'
+    const url = scheme + '://' + window.location.host + SSH_API.terminal + query({ alias, cols, rows })
+    const socket = new WebSocket(url)
+    const connection: TerminalConnection = {
+      onReady: undefined,
+      onOutput: undefined,
+      onExit: undefined,
+      send: (data) => {
+        if (socket.readyState === WebSocket.OPEN) {
+          socket.send(JSON.stringify({ type: 'input', data } satisfies TerminalClientFrame))
+        }
+      },
+      resize: (cols, rows) => {
+        if (socket.readyState === WebSocket.OPEN) {
+          socket.send(JSON.stringify({ type: 'resize', cols, rows } satisfies TerminalClientFrame))
+        }
+      },
+      close: () => {
+        try { socket.close() } catch { /* already closed */ }
+      },
+    }
+    socket.onmessage = (event: MessageEvent<string>) => {
+      let frame: TerminalServerFrame
+      try {
+        frame = JSON.parse(event.data) as TerminalServerFrame
+      } catch {
+        return
+      }
+      if (frame.type === 'ready') connection.onReady?.()
+      else if (frame.type === 'output') connection.onOutput?.(frame.data)
+      else if (frame.type === 'exit') connection.onExit?.(frame.code, frame.error)
+    }
+    socket.onclose = () => { connection.onExit?.(null, 'connection closed') }
+    socket.onerror = () => { connection.onExit?.(null, 'connection error') }
+    return connection
+  }
+
+  // --------------------------------------------------------- known-hosts
+  /** Read the host-key trust records (optionally one alias's). */
+  async listKnownHosts(alias?: string): Promise<KnownHostView[]> {
+    const response = await fetch(SSH_API.knownHosts + query({ alias }))
+    const body = await readJson<{ records: KnownHostView[] }>(response)
+    return body.records
+  }
+
+  /** Confirm (trust) or reset (forget) one alias's host key. */
+  async hostKeyAction(alias: string, action: KnownHostAction): Promise<void> {
+    const response = await fetch(SSH_API.knownHosts, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ alias, action }),
+    })
+    await readJson<{ ok: true }>(response)
+  }
+
+  // -------------------------------------------------------- connections
+  /** Aliases currently holding a live pooled SSH connection (badge coloring). */
+  async connectedAliases(): Promise<string[]> {
+    const response = await fetch(SSH_API.connections)
+    const body = await readJson<{ connected: string[] }>(response)
+    return body.connected
+  }
+
+  // ------------------------------------------------------ session secrets
+
+  /** Provide a password/passphrase for `alias` THIS SESSION ONLY (never
+   *  persisted). Called when a connection replied NEEDS_PASSWORD; after
+   *  injection the caller retries the operation. */
+  async setSessionSecret(alias: string, secret: { password?: string; passphrase?: string }): Promise<void> {
+    const response = await fetch(SSH_API.sessionSecret, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ alias, ...secret }),
+    })
+    await readJson<{ ok: true }>(response)
+  }
+}

package/src/client/ssh/apply.ts

@@ -0,0 +1,50 @@
+/**
+ * SSH operations browser surfaces, hosted inside dsh-hardssh's client bundle
+ * (migrated from the legacy dsh-ssh package): the 'dsh-ssh'
+ * locale dictionaries, the sidebar entry row, and the SSH operations panel
+ * in the center column. Mounted from src/client/index.ts alongside the
+ * workspace surfaces; a DOM failure here degrades the SSH panel only, never
+ * the GUI.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+// Type-only: pulls the locale plugin's Context merge (ctx.locale).
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+// Type-only: pulls the LocaleNamespaceMap merge table.
+import type {} from '@deepseek-ai/dsh-client-ui-slots'
+import { SshApi } from './api.ts'
+import { en, zh } from './locales.ts'
+import { mountPanel } from './mount.tsx'
+import { PanelController } from './panel/controller.ts'
+import { mountSidebarEntry } from './sidebar-entry.ts'
+
+/** Locale namespace this capability owns (kept as 'dsh-ssh'). */
+export const NS = 'dsh-ssh'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    /** dsh-ssh surface copy (now inside dsh-hardssh). */
+    'dsh-ssh': import('./locales.ts').SshKey
+  }
+}
+
+/**
+ * Mount the SSH operations surfaces (sidebar entry + operations panel).
+ * @param ctx - client root context (locale service).
+ */
+export function mountSshOperations(ctx: ClientContext): void {
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'dsh-ssh: dictionaries')
+
+  const controller = new PanelController()
+  const api = new SshApi()
+  const disposers: Array<() => void> = []
+  try {
+    disposers.push(mountSidebarEntry(controller))
+    disposers.push(mountPanel(controller, api))
+  } catch (error) {
+    // DOM failures degrade the panel, never the GUI.
+    console.warn('[dsh-ssh] mount failed:', error)
+  }
+  ctx.effect(() => () => {
+    for (const dispose of disposers.splice(0)) dispose()
+  }, 'dsh-ssh: ui mounts')
+}