dsh-single-terminal 0.1.0

package/src/client/xterm-css.ts

@@ -0,0 +1,224 @@
+/**
+ * xterm.css（@xterm/xterm 5.x 自带样式）· 生成期内嵌。
+ * 来源：node_modules/@xterm/xterm/css/xterm.css（MIT，xterm.js authors）。
+ * 升级 @xterm/xterm 后重跑 scripts/gen-xterm-css.mjs 再生成本文件。
+ */
+export const XTERM_CSS = `/**
+ * Copyright (c) 2014 The xterm.js authors. All rights reserved.
+ * Copyright (c) 2012-2013, Christopher Jeffrey (MIT License)
+ * https://github.com/chjj/term.js
+ * @license MIT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * Originally forked from (with the author's permission):
+ *   Fabrice Bellard's javascript vt100 for jslinux:
+ *   http://bellard.org/jslinux/
+ *   Copyright (c) 2011 Fabrice Bellard
+ *   The original design remains. The terminal itself
+ *   has been extended to include xterm CSI codes, among
+ *   other features.
+ */
+
+/**
+ *  Default styles for xterm.js
+ */
+
+.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:not(.debug),
+.xterm .xterm-message {
+    position: absolute;
+    left: 0;
+    top: 0;
+    bottom: 0;
+    right: 0;
+    z-index: 10;
+    color: transparent;
+    pointer-events: none;
+}
+
+.xterm .xterm-accessibility-tree:not(.debug) *::selection {
+  color: transparent;
+}
+
+.xterm .xterm-accessibility-tree {
+  user-select: text;
+  white-space: pre;
+}
+
+.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/host/cordis-augment.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 宿主 Context 的服务类型增强（声明合并）。
+ *
+ * 说明：本插件只用 `ctx.get` 读取宿主服务（配合 src/host/types.ts 里的最小
+ * 服务视图），不引入对 @deepseek-ai/* 实现包的值依赖。@deepseek-ai/cordis
+ * 自带的 Context 增强经 `export *` 间接导出后在 TS 5.9 下不生效（同
+ * dsh-jenkins 的实测），这里在插件侧显式增强。
+ */
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** 反射层提供的服务读取（context proxy 运行时委托给 reflect）。 */
+    get<T = unknown>(name: string): T | undefined
+    /**
+     * 注册随插件卸载/热重载自动清理的副作用（回调返回 disposer）。
+     * 运行时 Context 代理委托给 fiber.effect；npm cordis 4.x 仅在 Fiber
+     * 类型上声明，这里补充 Context 视图（同 vendored cordis 的形态）。
+     */
+    effect(execute: () => () => unknown, label?: string): () => unknown
+  }
+}
+
+export {}

package/src/host/hub.ts

@@ -0,0 +1,302 @@
+/**
+ * dsh-single-terminal —— 终端 Hub：PTY 会话管理 + WebSocket 帧协议。
+ *
+ * - PTY 经插件自身依赖 node-pty（原生模块，external）直连 ConPTY/POSIX pty，
+ *   获得完整 resize/kill/数据流控制（宿主 ctx.subprocess 的 TerminalHandle
+ *   接口不暴露 resize，无法满足抽屉尺寸跟随）；
+ * - 会话与 WebSocket 连接解耦：页面刷新/抽屉关闭后会话保活，重连后 attach
+ *   回放环形缓冲（容量 scrollbackLimit）；
+ * - 多浏览器标签页可同时 attach 同一会话：输出广播、输入合并。
+ */
+
+import { spawn } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { statSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { homedir } from 'node:os'
+import { isAbsolute } from 'node:path'
+import type { IncomingMessage } from 'node:http'
+import type { Duplex } from 'node:stream'
+import { WebSocket, WebSocketServer } from 'ws'
+import type { IPty } from 'node-pty'
+import type { ShellRegistry, ResolvedShell } from './shells.ts'
+import type { ClientFrame, HostFrame, SessionInfo, TerminalPluginConfig } from './types.ts'
+
+const require = createRequire(import.meta.url)
+const nodePty = require('node-pty') as typeof import('node-pty')
+
+interface Session {
+  id: string
+  shell: ResolvedShell
+  cwd: string
+  pty: IPty
+  buffer: string
+  alive: boolean
+  closing: boolean
+  exitCode: number | null
+  signal: number | null
+}
+
+const MAX_SESSIONS = 20
+const INPUT_LIMIT = 1 << 16
+const COLS_MIN = 2
+const COLS_MAX = 500
+const ROWS_MIN = 2
+const ROWS_MAX = 300
+
+const clamp = (value: number, min: number, max: number): number =>
+  Number.isFinite(value) ? Math.min(max, Math.max(min, Math.round(value))) : min
+
+export class TerminalHub {
+  private readonly wss = new WebSocketServer({ noServer: true })
+  private readonly sockets = new Set<WebSocket>()
+  private readonly sessions = new Map<string, Session>()
+  private nextSocketId = 0
+
+  constructor(
+    private readonly config: TerminalPluginConfig,
+    private readonly registry: ShellRegistry,
+  ) {
+    this.wss.on('connection', (socket: WebSocket) => { this.handleConnection(socket) })
+  }
+
+  /** webServer.registerUpgrade 的 handler 入口（鉴权由插件入口完成后调用）。 */
+  handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void {
+    this.wss.handleUpgrade(req, socket, head, (ws) => {
+      this.wss.emit('connection', ws, req)
+    })
+  }
+
+  /** 插件卸载：终止全部会话并断开所有连接。 */
+  dispose(): void {
+    console.log(`[dsh-single-terminal] hub dispose (${this.sessions.size} sessions, ${this.sockets.size} sockets)`)
+    for (const session of this.sessions.values()) {
+      this.killSession(session)
+    }
+    this.sessions.clear()
+    for (const socket of this.sockets) {
+      try { socket.terminate() } catch { /* already gone */ }
+    }
+    this.sockets.clear()
+  }
+
+  /* ── 连接生命周期 ─────────────────────────────────────────────── */
+
+  private handleConnection(socket: WebSocket): void {
+    const sid = ++this.nextSocketId
+    this.sockets.add(socket)
+    console.log(`[dsh-single-terminal] ws#${sid} connected (total ${this.sockets.size})`)
+    socket.on('message', (raw: unknown) => { this.dispatch(socket, raw, sid) })
+    socket.on('close', () => { this.sockets.delete(socket); console.log(`[dsh-single-terminal] ws#${sid} closed (total ${this.sockets.size})`) })
+    socket.on('error', () => { this.sockets.delete(socket) })
+    this.send(socket, {
+      type: 'hello',
+      platform: process.platform,
+      defaultShell: this.registry.defaultShellId(this.config.defaultShell),
+      fontSize: this.config.fontSize,
+      fontFamily: this.config.fontFamily,
+    })
+  }
+
+  private dispatch(socket: WebSocket, raw: unknown, sid: number): void {
+    let frame: ClientFrame
+    try {
+      frame = JSON.parse(String(raw)) as ClientFrame
+    } catch {
+      return
+    }
+    if (frame.type !== 'input' && frame.type !== 'resize') {
+      const detail = 'id' in frame ? ` id=${String(frame.id).slice(0, 8)}` : ''
+      console.log(`[dsh-single-terminal] ws#${sid} <- ${frame.type}${detail}`)
+    }
+    switch (frame.type) {
+      case 'ping':
+        this.send(socket, { type: 'pong' })
+        break
+      case 'list':
+        this.send(socket, this.snapshotFrame())
+        break
+      case 'open':
+        this.open(frame.shellId, frame.cols, frame.rows, frame.cwd)
+        break
+      case 'input': {
+        const session = this.sessions.get(frame.id)
+        if (session === undefined || !session.alive) break
+        try {
+          session.pty.write(frame.data.length > INPUT_LIMIT ? frame.data.slice(0, INPUT_LIMIT) : frame.data)
+        } catch { /* dead pty: exit event follows */ }
+        break
+      }
+      case 'resize': {
+        const session = this.sessions.get(frame.id)
+        if (session === undefined || !session.alive) break
+        try {
+          session.pty.resize(clamp(frame.cols, COLS_MIN, COLS_MAX), clamp(frame.rows, ROWS_MIN, ROWS_MAX))
+        } catch { /* transient during teardown */ }
+        break
+      }
+      case 'attach': {
+        const session = this.sessions.get(frame.id)
+        if (session === undefined) break
+        this.send(socket, { type: 'replay', id: session.id, data: session.buffer })
+        if (!session.alive) {
+          this.send(socket, { type: 'exit', id: session.id, exitCode: session.exitCode, signal: session.signal })
+        }
+        break
+      }
+      case 'close':
+        this.close(frame.id)
+        break
+    }
+  }
+
+  /* ── 会话管理 ────────────────────────────────────────────────── */
+
+  private open(shellId: string, cols: number, rows: number, cwdOverride: string | undefined): void {
+    if (this.sessions.size >= MAX_SESSIONS) {
+      this.broadcast({ type: 'error', message: '终端数量已达上限 / terminal session limit reached' })
+      return
+    }
+    const shell = this.registry.resolve(shellId)
+    if (shell === null) {
+      this.broadcast({ type: 'error', message: `未知或不可用的 shell：「${shellId}」/ unknown or unavailable shell` })
+      return
+    }
+    const cwd = this.resolveCwd(cwdOverride)
+    const env: NodeJS.ProcessEnv = { ...process.env }
+    if (process.platform !== 'win32') env.TERM = 'xterm-256color'
+    let pty: IPty
+    try {
+      pty = nodePty.spawn(shell.file, shell.args, {
+        name: 'xterm-256color',
+        cols: clamp(cols, COLS_MIN, COLS_MAX),
+        rows: clamp(rows, ROWS_MIN, ROWS_MAX),
+        cwd,
+        env,
+      })
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e)
+      this.broadcast({ type: 'error', message: `无法启动 ${shell.name} / failed to spawn ${shell.name}: ${message}` })
+      return
+    }
+    const session: Session = {
+      id: randomUUID(),
+      shell,
+      cwd,
+      pty,
+      buffer: '',
+      alive: true,
+      closing: false,
+      exitCode: null,
+      signal: null,
+    }
+    this.sessions.set(session.id, session)
+    console.log(`[dsh-single-terminal] session ${session.id.slice(0, 8)} opened shell=${shell.id} pid=${pty.pid} cwd=${cwd} (${this.sessions.size} total)`)
+    pty.onData((data: string) => {
+      this.appendBuffer(session, data)
+      this.broadcast({ type: 'data', id: session.id, data })
+    })
+    pty.onExit(({ exitCode, signal }: { exitCode: number; signal?: number }) => {
+      session.alive = false
+      session.exitCode = exitCode
+      session.signal = typeof signal === 'number' ? signal : null
+      if (this.sessions.has(session.id)) {
+        this.broadcast({ type: 'exit', id: session.id, exitCode: session.exitCode, signal: session.signal })
+        // 已广播 exit，客户端本地标记「已退出」；从快照移除，避免页面刷新后
+        // 被 adopt 成死标签。之后对该 id 的 close 帧静默忽略（客户端已删标签）。
+        this.sessions.delete(session.id)
+        console.log(`[dsh-single-terminal] session ${session.id.slice(0, 8)} (pid ${session.pty.pid}) exited code=${exitCode}`)
+      }
+    })
+    this.broadcast({ type: 'opened', session: this.sessionInfo(session) })
+  }
+
+  private close(id: string): void {
+    const session = this.sessions.get(id)
+    if (session === undefined) return
+    console.log(`[dsh-single-terminal] closing session ${id.slice(0, 8)} (pid ${session.pty.pid})`)
+    this.sessions.delete(id)
+    if (!session.alive) {
+      this.broadcast({ type: 'exit', id, exitCode: session.exitCode, signal: session.signal, closed: true })
+      return
+    }
+    session.closing = true
+    this.killSession(session)
+    this.broadcast({ type: 'exit', id, exitCode: null, signal: null, closed: true })
+  }
+
+  private killSession(session: Session): void {
+    try {
+      session.pty.kill()
+    } catch { /* already dead */ }
+    if (process.platform === 'win32') {
+      // node-pty 关闭 ConPTY 在部分 shell（powershell + PSReadLine）下不会结束
+      // 整棵进程树（实测 shell 存活、控制台子进程死亡），补 taskkill /T /F 兜底；
+      // 进程已死时 taskkill 静默失败。
+      try { spawn('taskkill', ['/T', '/F', '/PID', String(session.pty.pid)], { stdio: 'ignore' }) } catch { /* best effort */ }
+    } else {
+      // forkpty 使 shell 成为会话首进程（pid == pgid），负 pid 杀整个进程组。
+      try { process.kill(-session.pty.pid, 'SIGKILL') } catch { /* group gone */ }
+    }
+  }
+
+  private resolveCwd(override: string | undefined): string {
+    const validDirectory = (path: string): boolean => {
+      try { return statSync(path).isDirectory() } catch { return false }
+    }
+    if (override !== undefined) {
+      const trimmed = override.trim()
+      if (trimmed.length > 0 && isAbsolute(trimmed) && validDirectory(trimmed)) return trimmed
+    }
+    const configured = (this.config.defaultCwd ?? 'workspace').trim()
+    if (configured.length > 0 && configured !== 'workspace' && configured !== 'home' && isAbsolute(configured) && validDirectory(configured)) {
+      return configured
+    }
+    return homedir()
+  }
+
+  private appendBuffer(session: Session, data: string): void {
+    session.buffer += data
+    const limit = this.config.scrollbackLimit
+    if (session.buffer.length > limit) {
+      session.buffer = session.buffer.slice(session.buffer.length - limit)
+    }
+  }
+
+  /* ── 帧与快照 ────────────────────────────────────────────────── */
+
+  private snapshotFrame(): HostFrame {
+    return {
+      type: 'shells',
+      defaultShell: this.registry.defaultShellId(this.config.defaultShell),
+      shells: this.registry.list(),
+      sessions: [...this.sessions.values()].map((session) => this.sessionInfo(session)),
+    }
+  }
+
+  private sessionInfo(session: Session): SessionInfo {
+    return {
+      id: session.id,
+      shellId: session.shell.id,
+      label: session.shell.name,
+      cwd: session.cwd,
+      alive: session.alive,
+      pid: session.pty.pid,
+      exitCode: session.exitCode,
+      signal: session.signal,
+    }
+  }
+
+  private send(socket: WebSocket, frame: HostFrame): void {
+    if (socket.readyState !== WebSocket.OPEN) return
+    try {
+      socket.send(JSON.stringify(frame))
+    } catch { /* connection raced closed */ }
+  }
+
+  private broadcast(frame: HostFrame): void {
+    for (const socket of this.sockets) {
+      this.send(socket, frame)
+    }
+  }
+}

package/src/host/index.ts

@@ -0,0 +1,78 @@
+/**
+ * dsh-single-terminal —— 插件宿主半边入口。
+ *
+ * - WebSocket 路由 /api/dsh-single-terminal.ws（webServer.registerUpgrade，exact path）：
+ *   鉴权复用宿主 connection.requestRejection（Host/Origin 围栏 + dsh-auth cookie），
+ *   升级后交给 TerminalHub 处理 JSON 帧协议；
+ * - Config（schemastery）由宿主 Plugins 设置页渲染，热更新经 plugin 重载生效；
+ * - 卸载清理：注销路由 + 终止全部 PTY 会话（ctx.effect disposer）。
+ */
+
+import type { IncomingMessage } from 'node:http'
+import type { Duplex } from 'node:stream'
+import type { Context } from '@deepseek-ai/cordis'
+import Schema from '@deepseek-ai/schemastery'
+import { TerminalHub } from './hub.ts'
+import { ShellRegistry } from './shells.ts'
+import type { ConnectionService, CustomShellConfig, TerminalPluginConfig, WebServerService } from './types.ts'
+
+export const name = 'dsh-single-terminal'
+export const inject = ['webServer', 'connection']
+
+/* ── 配置（docs/develop/basic/config）────────────────────────────── */
+
+const CustomShellSchema = Schema.object({
+  id: Schema.string().required().description('唯一 id，如 my-shell'),
+  name: Schema.string().required().description('菜单显示名，如 My Shell'),
+  command: Schema.string().required().description('可执行文件路径或 PATH 上的命令名，如 nu'),
+  args: Schema.array(Schema.string()).default([]).description('启动参数'),
+})
+
+export const Config: import('@deepseek-ai/schemastery').default<TerminalPluginConfig> = Schema.object({
+  defaultShell: Schema.string().default('powershell')
+    .description('默认 shell id：powershell | pwsh | cmd | gitbash | wsl（或自定义 shell 的 id）。非 Windows 下自动回退到 $SHELL/bash'),
+  defaultCwd: Schema.string().default('workspace')
+    .description('终端初始目录：workspace（当前工作区根，未知时回退用户主目录）| home | 绝对路径'),
+  scrollbackLimit: Schema.number().default(200_000)
+    .description('重连回放缓冲的字符上限（每会话）'),
+  fontSize: Schema.number().default(13).description('终端字号'),
+  fontFamily: Schema.string().default('Consolas, "Cascadia Mono", "Courier New", monospace').description('终端字体'),
+  customShells: Schema.array(CustomShellSchema).default([]).description('自定义 shell 列表'),
+}) as unknown as import('@deepseek-ai/schemastery').default<TerminalPluginConfig>
+
+/* ── apply ───────────────────────────────────────────────────────── */
+
+const WS_PATH = '/api/dsh-single-terminal.ws'
+
+export function apply(ctx: Context, config: TerminalPluginConfig): void {
+  const webServer = ctx.get<WebServerService>('webServer')
+  const connection = ctx.get<ConnectionService>('connection')
+  if (webServer === undefined || connection === undefined) return
+
+  const registry = new ShellRegistry(config.customShells ?? [])
+  const hub = new TerminalHub(config, registry)
+
+  let unregister: (() => void) | undefined
+  try {
+    unregister = webServer.registerUpgrade({
+      path: WS_PATH,
+      handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+        const rejection = connection.requestRejection(req)
+        if (rejection !== undefined) {
+          socket.destroy()
+          return
+        }
+        hub.handleUpgrade(req, socket, head)
+      },
+    })
+  } catch (e) {
+    console.warn('[dsh-single-terminal] register upgrade route failed:', e instanceof Error ? e.message : String(e))
+  }
+
+  ctx.effect(() => () => {
+    try { unregister?.() } catch { /* already unregistered */ }
+    hub.dispose()
+  })
+}
+
+export type { CustomShellConfig, TerminalPluginConfig }