@lijian-ui/dsh-term 0.1.0

package/src/client/term/xterm-styles.ts

@@ -0,0 +1,182 @@
+/**
+ * Inlined xterm.js 5.3.0 core styles (MIT) — injected as a <style> tag at
+ * runtime because the client build compiles only *.module.css and the
+ * shell's css-modules pipeline rejects a raw :global block with xterm's
+ * class names.
+ * @module dsh-term/client/term/xterm-styles
+ */
+
+export const XTERM_CSS: string = `
+.xterm {
+    cursor: text;
+    position: relative;
+    user-select: none;
+    -ms-user-select: none;
+    -webkit-user-select: none;
+}
+
+.xterm.focus,
+.xterm:focus {
+    outline: none;
+}
+
+.xterm .xterm-helpers {
+    position: absolute;
+    top: 0;
+    /**
+     * The z-index of the helpers must be higher than the canvases in order for
+     * IMEs to appear on top.
+     */
+    z-index: 5;
+}
+
+.xterm .xterm-helper-textarea {
+    padding: 0;
+    border: 0;
+    margin: 0;
+    /* Move textarea out of the screen to the far left, so that the cursor is not visible */
+    position: absolute;
+    opacity: 0;
+    left: -9999em;
+    top: 0;
+    width: 0;
+    height: 0;
+    z-index: -5;
+    /** Prevent wrapping so the IME appears against the textarea at the correct position */
+    white-space: nowrap;
+    overflow: hidden;
+    resize: none;
+}
+
+.xterm .composition-view {
+    /* TODO: Composition position got messed up somewhere */
+    background: #000;
+    color: #FFF;
+    display: none;
+    position: absolute;
+    white-space: nowrap;
+    z-index: 1;
+}
+
+.xterm .composition-view.active {
+    display: block;
+}
+
+.xterm .xterm-viewport {
+    /* On OS X this is required in order for the scroll bar to appear fully opaque */
+    background-color: #000;
+    overflow-y: scroll;
+    cursor: default;
+    position: absolute;
+    right: 0;
+    left: 0;
+    top: 0;
+    bottom: 0;
+}
+
+.xterm .xterm-screen {
+    position: relative;
+}
+
+.xterm .xterm-screen canvas {
+    position: absolute;
+    left: 0;
+    top: 0;
+}
+
+.xterm .xterm-scroll-area {
+    visibility: hidden;
+}
+
+.xterm-char-measure-element {
+    display: inline-block;
+    visibility: hidden;
+    position: absolute;
+    top: 0;
+    left: -9999em;
+    line-height: normal;
+}
+
+.xterm.enable-mouse-events {
+    /* When mouse events are enabled (eg. tmux), revert to the standard pointer cursor */
+    cursor: default;
+}
+
+.xterm.xterm-cursor-pointer,
+.xterm .xterm-cursor-pointer {
+    cursor: pointer;
+}
+
+.xterm.column-select.focus {
+    /* Column selection mode */
+    cursor: crosshair;
+}
+
+.xterm .xterm-accessibility,
+.xterm .xterm-message {
+    position: absolute;
+    left: 0;
+    top: 0;
+    bottom: 0;
+    right: 0;
+    z-index: 10;
+    color: transparent;
+    pointer-events: none;
+}
+
+.xterm .live-region {
+    position: absolute;
+    left: -9999px;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+}
+
+.xterm-dim {
+    /* Dim should not apply to background, so the opacity of the foreground color is applied
+     * explicitly in the generated class and reset to 1 here */
+    opacity: 1 !important;
+}
+
+.xterm-underline-1 { text-decoration: underline; }
+.xterm-underline-2 { text-decoration: double underline; }
+.xterm-underline-3 { text-decoration: wavy underline; }
+.xterm-underline-4 { text-decoration: dotted underline; }
+.xterm-underline-5 { text-decoration: dashed underline; }
+
+.xterm-overline {
+    text-decoration: overline;
+}
+
+.xterm-overline.xterm-underline-1 { text-decoration: overline underline; }
+.xterm-overline.xterm-underline-2 { text-decoration: overline double underline; }
+.xterm-overline.xterm-underline-3 { text-decoration: overline wavy underline; }
+.xterm-overline.xterm-underline-4 { text-decoration: overline dotted underline; }
+.xterm-overline.xterm-underline-5 { text-decoration: overline dashed underline; }
+
+.xterm-strikethrough {
+    text-decoration: line-through;
+}
+
+.xterm-screen .xterm-decoration-container .xterm-decoration {
+	z-index: 6;
+	position: absolute;
+}
+
+.xterm-screen .xterm-decoration-container .xterm-decoration.xterm-decoration-top-layer {
+	z-index: 7;
+}
+
+.xterm-decoration-overview-ruler {
+    z-index: 8;
+    position: absolute;
+    top: 0;
+    right: 0;
+    pointer-events: none;
+}
+
+.xterm-decoration-top {
+    z-index: 2;
+    position: relative;
+}
+`

package/src/core/types.ts

@@ -0,0 +1,73 @@
+/**
+ * Wire types shared between the host half and the browser half of dsh-term.
+ * Pure data — no runtime imports (keeps the client bundle purity gate happy).
+ * @module dsh-term/core/types
+ */
+
+/** One live PTY session as the browser knows it. */
+export interface TermSessionInfo {
+  /** Stable session id (the wire handle). */
+  readonly id: string
+  /** User-facing tab title (defaults to the shell name). */
+  readonly title: string
+  /** Session cwd (absolute). */
+  readonly cwd: string
+  /** PTY size at last resize. */
+  cols: number
+  rows: number
+  /** Whether the shell process is still alive. */
+  readonly alive: boolean
+  /** POSIX exit code when the session ended (null while alive). */
+  readonly exitCode: number | null
+}
+
+/** Request: open a new PTY session. */
+export interface TermSpawnRequest {
+  /** Optional session display name. */
+  name?: string
+  /** Working directory (defaults to the session's workspace cwd). */
+  cwd?: string
+  /** Shell executable (defaults to the platform shell). */
+  shell?: string
+  /** Shell arguments (defaults to an interactive login-less profile). */
+  args?: string[]
+  /** Initial terminal size. */
+  cols?: number
+  rows?: number
+}
+
+/** Request: deliver terminal input. */
+export interface TermWriteRequest {
+  readonly id: string
+  /** Raw bytes to write into the PTY (UTF-8 string; xterm emits UTF-8). */
+  readonly data: string
+}
+
+/** Request: resize one session. */
+export interface TermResizeRequest {
+  readonly id: string
+  readonly cols: number
+  readonly rows: number
+}
+
+/** Request: signal one session. */
+export interface TermSignalRequest {
+  readonly id: string
+  /** PTY signal name (e.g. `SIGHUP`, `SIGINT`, `SIGTERM`, `SIGKILL`). */
+  readonly signal: 'SIGHUP' | 'SIGINT' | 'SIGTERM' | 'SIGKILL'
+}
+
+/** The full session listing snapshot. */
+export interface TermListResponse {
+  readonly sessions: readonly TermSessionInfo[]
+}
+
+/** One output chunk pushed over the SSE change stream. */
+export type TermEvent =
+  | { readonly kind: 'output'; readonly id: string; readonly data: string }
+  | { readonly kind: 'exit'; readonly id: string; readonly exitCode: number }
+  | { readonly kind: 'start'; readonly session: TermSessionInfo }
+  | { readonly kind: 'closed'; readonly id: string }
+
+/** The workspace-gated session id (host-minted; the wire carries only this). */
+export type TermSessionId = string

package/src/host/loopback.ts

@@ -0,0 +1,63 @@
+// Generated by scripts/sync-shared.mjs from shared/host/loopback.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Loopback trust fence shared by the host route families: socket address,
+ * Host header, and browser same-origin markers. Packages receive this file as
+ * a generated copy via scripts/sync-shared.mjs; edit the shared source and
+ * re-run the sync instead of editing a copy.
+ *
+ * Semantics: RFC 5735 IPv4 127/8, ::1, IPv4-mapped ::ffff:127/8 (matching the
+ * remote-web-ui gate), localhost hostnames, plus the browser same-origin
+ * markers (sec-fetch-site and Origin) for the request-level fence.
+ * @module dsh-web-ui-shared/host/loopback
+ */
+
+import type { IncomingMessage } from 'node:http'
+
+/** IPv4 127/8 predicate (four decimal octets, first == 127). */
+export function isIPv4Loopback(v4: string): boolean {
+  const parts = v4.split('.')
+  return parts.length === 4
+    && parts[0] === '127'
+    && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+}
+
+/** Whether a socket remote address names the loopback range (127/8, ::1, IPv4-mapped). */
+export function isLoopbackAddress(address: string | undefined): boolean {
+  if (address === undefined) return false
+  const normalized = address.toLowerCase()
+  if (normalized === '::1') return true
+  if (normalized.startsWith('::ffff:')) return isIPv4Loopback(normalized.slice('::ffff:'.length))
+  return isIPv4Loopback(normalized)
+}
+
+/** Whether a normalized URL hostname names the loopback authority (localhost, [::1], 127/8). */
+export function isLoopbackHostname(hostname: string): boolean {
+  if (hostname === 'localhost' || hostname === '[::1]') return true
+  return isIPv4Loopback(hostname)
+}
+
+/**
+ * Request-level trust fence: a loopback socket address AND a loopback Host
+ * header, plus browser same-origin markers. The socket address is
+ * authoritative; X-Forwarded-For is never trusted.
+ */
+export function isLoopbackRequest(request: IncomingMessage): boolean {
+  if (!isLoopbackAddress(request.socket.remoteAddress)) return false
+  const host = request.headers.host
+  if (typeof host !== 'string') return false
+  let hostUrl: URL
+  try {
+    hostUrl = new URL('http://' + host)
+  } catch {
+    return false
+  }
+  if (!isLoopbackHostname(hostUrl.hostname)) return false
+  if (request.headers['sec-fetch-site'] === 'cross-site') return false
+  const origin = request.headers.origin
+  if (origin === undefined) return true
+  try {
+    return new URL(origin).host === hostUrl.host
+  } catch {
+    return false
+  }
+}

package/src/host/pty-service.ts

@@ -0,0 +1,131 @@
+/**
+ * PTY session service for dsh-term: a framework-free registry over node-pty.
+ *
+ * A "pure user terminal" (A-version) needs no dsh agent ownership — every
+ * session is a plain node-pty child process keyed by a host-minted id, with
+ * byte streams bridged to the browser over the /dsh-term/* HTTP layer. This
+ * deliberately does NOT use the official @deepseek-ai/dsh-terminal service:
+ * that registry requires an exact `Agent` owner (model-facing semantics) and
+ * its resolution path from a user-initiated web route is unverified; node-pty
+ * is already present in the desktop tree (ABI-matched, verified loadable) and
+ * gives full control over multi-tab local shells.
+ * @module dsh-term/host/pty-service
+ */
+
+import { randomUUID } from 'node:crypto'
+import * as nodePty from 'node-pty'
+import type { TermSessionInfo, TermSpawnRequest } from '../core/types.ts'
+
+/** Live session plus its pty handle (service-private). */
+interface LiveSession {
+  readonly info: TermSessionInfo
+  readonly pty: nodePty.IPty
+}
+
+/** Default interactive shell for the platform. */
+export function defaultShell(): string {
+  if (process.platform === 'win32') return 'powershell.exe'
+  return process.env.SHELL ?? '/bin/bash'
+}
+
+/** Default args for an interactive login-less shell. */
+export function defaultArgs(shell: string): string[] {
+  if (process.platform === 'win32') return []
+  const base = shell.endsWith('bash') ? ['--noprofile', '--norc', '-i'] : ['-i']
+  return base
+}
+
+/**
+ * The PTY registry. Every mutation goes through this class so the route
+ * layer stays a thin HTTP shape (the file-manager pattern). Output/exit
+ * callbacks are assignable so the SSE layer can bind them after construction.
+ */
+export class PtyService {
+  private readonly sessions = new Map<string, LiveSession>()
+
+  /** Fired with raw PTY output chunks (UTF-8). Bound by the route layer. */
+  onOutput: (sessionId: string, data: string) => void = () => {}
+  /** Fired once when a session exits. Bound by the route layer. */
+  onExit: (sessionId: string, exitCode: number) => void = () => {}
+
+  /** Open one session; returns the wire info immediately (output streams async). */
+  spawn(req: TermSpawnRequest): TermSessionInfo {
+    const id = randomUUID()
+    const shell = req.shell ?? defaultShell()
+    const args = req.args ?? defaultArgs(shell)
+    const cols = req.cols ?? 80
+    const rows = req.rows ?? 24
+    const cwd = req.cwd ?? process.cwd()
+    const pty = nodePty.spawn(shell, args, {
+      name: 'xterm-256color',
+      cols,
+      rows,
+      cwd,
+    })
+    const info: TermSessionInfo = {
+      id,
+      title: req.name ?? shell,
+      cwd,
+      cols,
+      rows,
+      alive: true,
+      exitCode: null,
+    }
+    this.sessions.set(id, { info, pty })
+    pty.onData((data) => { this.onOutput(id, data) })
+    pty.onExit(({ exitCode }) => {
+      this.sessions.delete(id)
+      this.onExit(id, exitCode)
+    })
+    return info
+  }
+
+  /** Write raw bytes (UTF-8) into a session. Returns false when unknown. */
+  write(id: string, data: string): boolean {
+    const live = this.sessions.get(id)
+    if (live === undefined) return false
+    try { live.pty.write(data) } catch { return false }
+    return true
+  }
+
+  /** Resize a session. Returns false when unknown. */
+  resize(id: string, cols: number, rows: number): boolean {
+    const live = this.sessions.get(id)
+    if (live === undefined) return false
+    try {
+      live.pty.resize(Math.max(2, cols), Math.max(2, rows))
+      live.info.cols = cols
+      live.info.rows = rows
+    } catch { return false }
+    return true
+  }
+
+  /** Deliver a signal (SIGINT/SIGHUP/SIGTERM/SIGKILL). Returns false when unknown. */
+  signal(id: string, signal: string): boolean {
+    const live = this.sessions.get(id)
+    if (live === undefined) return false
+    try { live.pty.kill(signal as Parameters<typeof live.pty.kill>[0]) } catch { return false }
+    return true
+  }
+
+  /** Close a session forcefully (SIGHUP semantics via kill). Returns false when unknown. */
+  close(id: string): boolean {
+    const live = this.sessions.get(id)
+    if (live === undefined) return false
+    try { live.pty.kill() } catch { /* already dead */ }
+    return true
+  }
+
+  /** The full session listing snapshot. */
+  list(): readonly TermSessionInfo[] {
+    return [...this.sessions.values()].map(({ info }) => ({ ...info }))
+  }
+
+  /** Close every session (route teardown). */
+  dispose(): void {
+    for (const live of this.sessions.values()) {
+      try { live.pty.kill() } catch { /* ignore */ }
+    }
+    this.sessions.clear()
+  }
+}

package/src/host/routes.ts

@@ -0,0 +1,198 @@
+/**
+ * /dsh-term/* route layer: JSON envelope (ok/error) for the PTY operations
+ * and one SSE stream (output/exit/start events) per client. Loopback-fenced
+ * like every other host route family — a terminal is arbitrary command
+ * execution, so only same-origin browser clients may reach it.
+ * @module dsh-term/host/routes
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type { TermEvent, TermSpawnRequest } from '../core/types.ts'
+import type { PtyService } from './pty-service.ts'
+import { isLoopbackRequest } from './loopback.ts'
+
+/** JSON envelope mirrors the file-manager panel shape. */
+type Envelope<T> = { ok: true; value: T } | { ok: false; error: { code: string; message: string } }
+
+const OK = (value: unknown): Envelope<unknown> => ({ ok: true, value })
+const FAIL = (message: string, code = 'internal'): Envelope<never> => ({ ok: false, error: { code, message } })
+const MALFORMED = FAIL('malformed request')
+
+/** One SSE subscriber. */
+interface Subscriber {
+  readonly res: ServerResponse
+}
+
+/** Read a small JSON request body (bounded to 64 KiB). */
+function readBody(req: IncomingMessage): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    let size = 0
+    req.on('data', (chunk: Buffer) => {
+      size += chunk.length
+      if (size > 64 * 1024) {
+        reject(new Error('request body too large'))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      try {
+        resolve(chunks.length === 0 ? {} : JSON.parse(Buffer.concat(chunks).toString('utf-8')))
+      } catch {
+        reject(new Error('invalid JSON'))
+      }
+    })
+    req.on('error', reject)
+  })
+}
+
+function json(res: ServerResponse, envelope: Envelope<unknown>, status = 200): void {
+  const body = JSON.stringify(envelope)
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  })
+  res.end(body)
+}
+
+/**
+ * Register the /dsh-term routes.
+ * @param ctx - context carrying the webServer service.
+ * @param pty - the session registry.
+ * @returns route disposers.
+ */
+export function registerTermRoutes(ctx: Context, pty: PtyService): () => void {
+  const subscribers = new Set<Subscriber>()
+  const push = (event: TermEvent): void => {
+    for (const subscriber of subscribers) {
+      subscriber.res.write(`event: term\ndata: ${JSON.stringify(event)}\n\n`)
+    }
+  }
+
+  pty.onOutput = (id, data) => push({ kind: 'output', id, data })
+  pty.onExit = (id, exitCode) => push({ kind: 'exit', id, exitCode })
+
+  const handler = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    if (!isLoopbackRequest(req)) {
+      json(res, FAIL('loopback-only', 'forbidden'), 403)
+      return
+    }
+    const url = new URL(req.url ?? '/', 'http://dsh-term.local')
+    try {
+      if (req.method === 'GET' && url.pathname === '/dsh-term/list') {
+        json(res, OK({ sessions: pty.list() }))
+        return
+      }
+      if (req.method !== 'POST') {
+        json(res, MALFORMED, 405)
+        return
+      }
+      let payload: unknown
+      try {
+        payload = await readBody(req)
+      } catch {
+        json(res, MALFORMED, 400)
+        return
+      }
+      switch (url.pathname) {
+        case '/dsh-term/spawn': {
+          const request = payload as Partial<TermSpawnRequest>
+          if (typeof request !== 'object' || request === null) {
+            json(res, MALFORMED, 400)
+            return
+          }
+          const session = pty.spawn({
+            name: typeof request.name === 'string' ? request.name : undefined,
+            cwd: typeof request.cwd === 'string' ? request.cwd : undefined,
+            shell: typeof request.shell === 'string' ? request.shell : undefined,
+            args: Array.isArray(request.args) ? request.args.filter((a): a is string => typeof a === 'string') : undefined,
+            cols: typeof request.cols === 'number' ? request.cols : undefined,
+            rows: typeof request.rows === 'number' ? request.rows : undefined,
+          })
+          push({ kind: 'start', session })
+          json(res, OK(session))
+          return
+        }
+        case '/dsh-term/write': {
+          const body = payload as { id?: unknown; data?: unknown }
+          if (typeof body?.id !== 'string' || typeof body?.data !== 'string') {
+            json(res, MALFORMED, 400)
+            return
+          }
+          json(res, OK({ ok: pty.write(body.id, body.data) }))
+          return
+        }
+        case '/dsh-term/resize': {
+          const body = payload as { id?: unknown; cols?: unknown; rows?: unknown }
+          if (typeof body?.id !== 'string' || typeof body?.cols !== 'number' || typeof body?.rows !== 'number') {
+            json(res, MALFORMED, 400)
+            return
+          }
+          json(res, OK({ ok: pty.resize(body.id, body.cols, body.rows) }))
+          return
+        }
+        case '/dsh-term/signal': {
+          const body = payload as { id?: unknown; signal?: unknown }
+          if (typeof body?.id !== 'string' || typeof body?.signal !== 'string') {
+            json(res, MALFORMED, 400)
+            return
+          }
+          json(res, OK({ ok: pty.signal(body.id, body.signal) }))
+          return
+        }
+        case '/dsh-term/close': {
+          const body = payload as { id?: unknown }
+          if (typeof body?.id !== 'string') {
+            json(res, MALFORMED, 400)
+            return
+          }
+          json(res, OK({ ok: pty.close(body.id) }))
+          return
+        }
+        default:
+          json(res, MALFORMED, 404)
+      }
+    } catch (error: unknown) {
+      ctx.logger.warn(`dsh-term: route failed: ${String(error)}`)
+      json(res, FAIL('internal error'))
+    }
+  }
+
+  const sse = (req: IncomingMessage, res: ServerResponse): void => {
+    if (!isLoopbackRequest(req)) {
+      res.writeHead(403).end('loopback-only')
+      return
+    }
+    res.writeHead(200, {
+      'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'no-store',
+      'connection': 'keep-alive',
+      'x-accel-buffering': 'no',
+    })
+    res.write(': connected\n\n')
+    const subscriber: Subscriber = { res }
+    subscribers.add(subscriber)
+    const heartbeat = setInterval(() => {
+      if (subscriber.res.writableEnded) return
+      subscriber.res.write(': ping\n\n')
+    }, 15_000)
+    req.on('close', () => {
+      clearInterval(heartbeat)
+      subscribers.delete(subscriber)
+    })
+  }
+
+  const disposers = [
+    ctx.webServer.register({ kind: 'prefix', path: '/dsh-term', handler }),
+    ctx.webServer.register({ kind: 'exact', path: '/dsh-term/events', handler: sse }),
+  ]
+  return () => {
+    for (const dispose of disposers) dispose()
+    for (const subscriber of subscribers) subscriber.res.end()
+    subscribers.clear()
+  }
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * dsh-term host half: mounts the PTY session service and the /dsh-term/*
+ * routes on the shared webserver. The browser half (src/client) renders the
+ * panel UI against these routes — no dsh source changes.
+ * @module dsh-term
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import { mountOnce } from './mount-once.ts'
+import { PtyService } from './host/pty-service.ts'
+import { registerTermRoutes } from './host/routes.ts'
+
+/** Required services: the route registry. */
+export const inject = ['webServer']
+
+/** Model-facing announcement: plugin presence. */
+export const DSH_TERM_GUIDANCE = '本机已安装 dsh-term 插件（DSH Web GUI 的面板式终端）：用户可在聊天区打开本地终端（真实 PTY，默认 powershell/bash），多标签并存、会话持久；用户提到「终端 / 打开终端 / 执行命令」时即指本插件，请据此协作。'
+
+/**
+ * Mount the PTY service and its routes.
+ * @param ctx - context carrying the webServer service.
+ */
+export const apply = mountOnce('@lijian-ui/dsh-term', applyImpl)
+
+function applyImpl(ctx: Context): void {
+  const pty = new PtyService()
+  // Route registration + pty teardown both ride the effect fiber: the effect
+  // callback runs immediately and its return value is the fiber disposer.
+  ctx.effect(() => {
+    const disposeRoutes = registerTermRoutes(ctx, pty)
+    return () => {
+      disposeRoutes()
+      pty.dispose()
+    }
+  }, 'dsh-term: routes + pty lifecycle')
+}