dsh-single-terminal 0.1.0

package/README.md

@@ -0,0 +1,144 @@
+# dsh-single-terminal
+
+**dsh-single-terminal** is a real-terminal drawer plugin for the DeepSeek
+Harness (DSH) host. It docks an interactive PTY terminal (xterm.js) to the
+bottom of the web app — type into it, Ctrl-C it, resize it, open as many tabs
+as you need.
+
+- **Real PTY, not an emulator** — each tab is a true pseudo-terminal
+  (ConPTY on Windows, forkpty on POSIX) driven by `node-pty`; interactive REPLs,
+  full-screen programs and Ctrl-C all behave like a native terminal
+- **Shell picker** — Windows: PowerShell (default) / pwsh 7 / CMD / Git Bash /
+  WSL (shells that are not installed are hidden automatically) + custom shells
+  from config; POSIX: `$SHELL` / bash / zsh / fish
+- **Two drawer modes** — *Docked* pushes the page content up (no occlusion),
+  *Overlay* floats above it; drag the top edge to resize, the drawer remembers
+  mode and height
+- **Keep-alive sessions** — terminals survive page refreshes and drawer
+  close/reopen; on reconnect the recent output is replayed from a ring buffer.
+  Opening the drawer with no terminal yet auto-creates one with the default
+  shell.
+- **Bilingual UI** — follows the host interface language (中文 / English);
+  `Alt+C` toggles the drawer
+
+[中文文档](README.zh.md)
+
+## Features
+
+- **Header entry** (`conversation.session.header.utilities`): a panel-bottom
+  icon button in the session header's utilities row toggles
+  the drawer. Hovering shows a bubble tooltip (the host `Tooltip` component)
+  with the shortcut; `Alt+C` toggles from anywhere except while typing inside
+  the terminal (there `Alt+C` is passed to the shell as `ESC c`).
+- **Drawer** (`shell.overlay`): a frame-level bottom drawer with
+  - a tab strip — one PTY session per tab, independent shells, close button
+    per tab (terminates the whole process tree; the pid is verified gone),
+  - a `＋` button (new tab with the default shell) and a `▸` menu
+    (all shells found on this machine; unavailable ones are not listed),
+  - a mode switch (*Docked* / *Overlay*), a connection status dot and a
+    collapse button,
+  - a drag handle on the top edge (pointer-capture drag, min 140px).
+- **Docked mode** pushes the app frame up with `padding-bottom` on the frame
+  root element (no host hook exists for bottom docks); when the anchor cannot
+  be found it silently falls back to overlay.
+- **Model tools**: none — this plugin is UI-only by design.
+
+## Configuration
+
+Schemastery `Config` (renders on the host Plugins settings page), and / or the
+profile `cordis.patch.yml`:
+
+```yaml
+- insert:
+    - id: dsh-single-terminal
+      name: dsh-single-terminal
+      config:
+        defaultShell: powershell   # powershell | pwsh | cmd | gitbash | wsl | <custom id>
+        defaultCwd: home           # home | workspace | absolute path
+        scrollbackLimit: 200000    # replay ring buffer, bytes per session
+        fontSize: 13
+        fontFamily: Consolas, "Cascadia Mono", "Courier New", monospace
+        customShells:
+          - id: nu
+            name: Nushell
+            command: nu            # resolved through PATH
+            args: []
+```
+
+- `defaultShell` — shell used by the `＋` button; when unavailable it falls
+  back (`powershell` on Windows, `$SHELL`/`bash` on POSIX).
+- `defaultCwd` — `home` (default) starts in the user home; `workspace` is
+  reserved (currently resolves to home); an absolute path must exist.
+- `customShells` — extra launchers; `command` may be an absolute path or a
+  name resolved through `PATH` (with `PATHEXT` on Windows).
+
+## Installation
+
+```sh
+# Local development
+dsh plugin --profile web add ./dsh-single-terminal
+
+# Published: npm / tarball / GitHub
+dsh plugin --profile web add dsh-single-terminal
+dsh plugin --profile web add ./dsh-single-terminal-0.1.0.tgz
+dsh plugin --profile web add github:you/dsh-single-terminal#<sha>
+
+dsh --profile web                 # start (restart required for the host half to load)
+```
+
+> **node-pty** is a native dependency of the *host half* (`dependencies`, kept
+> external and loaded via `createRequire`). It ships prebuilds for common
+> platforms; on unusual platforms a C/C++ toolchain is needed for
+> `pnpm install` to compile it. The browser half inlines xterm.js entirely —
+> no runtime dependency there.
+
+## Development
+
+Requirements: **Node ≥ 22.19 (or ≥ 24) + pnpm 10** (the `packageManager` field
+pins the pnpm version).
+
+```sh
+pnpm install           # includes node-pty + ws (runtime) and @xterm/* (bundled into the client)
+pnpm run check         # whole-tree TypeScript type check (tsc -b)
+pnpm run build         # clean lib → tsc -b (declarations) → tsdown (both halves)
+pnpm run watch         # tsdown watch mode
+pnpm run verify        # simulate the host seed table to check lib/client.js loads
+```
+
+```
+├── src/host/           # Host half: index.ts (entry, ws route + config), hub.ts (session hub + frame protocol), shells.ts (registry + probing), types.ts
+├── src/client/         # Browser half: plugin.tsx (slots), drawer.tsx, term.tsx, controller.ts, ws.ts, styles.ts, i18n.ts ...
+├── lib/index.js        # Host half build artifact (tsdown, ESM)
+├── lib/client.js       # Browser half build artifact (tsdown → __ModuleLoader__ factory, xterm inlined)
+├── scripts/verify-client.mjs    # host-seed simulation check
+├── scripts/gen-xterm-css.mjs    # regenerates src/client/xterm-css.ts from the @xterm/xterm package
+├── cordis.patch.yml    # Bundle patch: plugin row referenced by package name (no paths)
+└── package.json        # dsh.bundle + dsh.client(web) manifests + peerDependencies
+```
+
+## Implementation notes
+
+- **Why the plugin ships its own node-pty**: the host `subprocess` terminal
+  primitive (`SubprocessTerminalHandle`) intentionally exposes no `resize`,
+  which a resize-following terminal needs; a plugin-owned `node-pty` gets the
+  full `write / resize / kill` control surface with the same ConPTY/forkpty
+  substrate the host uses.
+- **Transport**: a dedicated WebSocket route (`/api/dsh-single-terminal.ws`)
+  registered through `ctx.webServer.registerUpgrade`, gated by
+  `ctx.connection.requestRejection` (same trusted-host fence as the host API
+  gateway). The client connects same-origin and rides the `dsh-auth` cookie.
+- **Session model**: sessions live in a hub `Map` independent of sockets —
+  page refresh / reconnect re-`list`s, adopts live sessions and `attach`es
+  with a `replay` of the ring buffer. Exited sessions are pruned so dead tabs
+  never resurrect. Multiple browser tabs may attach to one session (output is
+  broadcast, input is merged).
+- **Frame protocol**: JSON text frames; client → host `open / input / resize /
+  close / list / attach / ping`, host → client `hello / shells / opened / data
+  / replay / exit / error / pong`. `input`/`resize` are size-capped and
+  clamped server-side.
+- **Windows process tree**: closing a tab runs `pty.kill()` and additionally
+  `taskkill /T /F` on the session pid — ConPTY closure alone can leave
+  PowerShell (+PSReadLine) alive; POSIX kills the foreground process group
+  (`kill(-pid)`).
+- **The official `deepseek-harness` project is not modified**; all UI sits in
+  existing slots (`shell.overlay`, `conversation.session.header.utilities`).

package/README.zh.md

@@ -0,0 +1,129 @@
+# dsh-single-terminal
+
+**dsh-single-terminal** 是 DeepSeek Harness（DSH）宿主的真实终端抽屉插件。它在
+Web 应用底部挂一条交互式 PTY 终端（xterm.js）——可以正常敲命令、Ctrl-C、拖拽
+改大小、开任意多个标签。
+
+- **真 PTY，非模拟** —— 每个标签是一条真实伪终端（Windows 为 ConPTY，POSIX 为
+  forkpty），由 `node-pty` 驱动；交互式 REPL、全屏程序、Ctrl-C 与原生终端一致
+- **Shell 选择** —— Windows：PowerShell（默认）/ pwsh 7 / CMD / Git Bash / WSL
+  （未安装的自动隐藏）+ config 自定义 shell；POSIX：`$SHELL` / bash / zsh / fish
+- **两种抽屉模式** —— *占高度* 把页面内容顶起（无遮挡），*浮层* 悬浮于内容之上；
+  顶边可拖拽调高度，模式与高度自动记忆
+- **会话保活** —— 终端在页面刷新、抽屉开合后继续存活；重连后从环形缓冲回放
+  近期输出。打开抽屉时若还没有任何终端，会自动用默认 shell 新建一个。
+- **双语 UI** —— 跟随宿主界面语言（中文 / English）；`Alt+C` 开关抽屉
+
+[English](README.md)
+
+## 功能
+
+- **会话头部入口**（`conversation.session.header.utilities`）：会话头部
+  utilities 区的「底部面板」(panel-bottom) 图标按钮，点击开合抽屉；悬停显示
+  宿主 `Tooltip`
+  气泡（含快捷键提示）。`Alt+C` 全局开合抽屉；焦点在终端输入区内时放行
+  （`Alt+C` 作为 `ESC c` 发给 shell）。
+- **抽屉**（`shell.overlay`）：frame 级底部抽屉，包含
+  - 标签条 —— 每标签一条独立 PTY 会话，可独立选择 shell；每标签有关闭按钮
+    （终止整棵进程树，已实测 pid 消失）；
+  - `＋` 按钮（默认 shell 新建标签）与 `▸` 菜单（列出本机探测到的全部 shell，
+    不可用的不显示）；
+  - 模式切换（占高度 / 浮层）、连接状态点、收起按钮；
+  - 顶边拖拽条（pointer capture 拖拽，最小 140px）。
+- **占高度模式** 通过对框架根元素设 `padding-bottom` 把内容顶起（宿主没有底部
+  停靠钩子）；找不到锚点元素时静默降级为浮层。
+- **模型工具**：无——本插件刻意只做 UI。
+
+## 配置
+
+Schemastery `Config`（宿主 Plugins 设置页自动渲染），和 / 或 profile 的
+`cordis.patch.yml`：
+
+```yaml
+- insert:
+    - id: dsh-single-terminal
+      name: dsh-single-terminal
+      config:
+        defaultShell: powershell   # powershell | pwsh | cmd | gitbash | wsl | <自定义 id>
+        defaultCwd: home           # home | workspace | 绝对路径
+        scrollbackLimit: 200000    # 每会话回放环形缓冲字节上限
+        fontSize: 13
+        fontFamily: Consolas, "Cascadia Mono", "Courier New", monospace
+        customShells:
+          - id: nu
+            name: Nushell
+            command: nu            # 支持从 PATH 解析
+            args: []
+```
+
+- `defaultShell` —— `＋` 按钮使用的 shell；不可用时自动回退（Windows 回退
+  `powershell`，POSIX 回退 `$SHELL`/`bash`）。
+- `defaultCwd` —— `home`（默认）从用户主目录启动；`workspace` 预留（当前等同
+  home）；绝对路径必须存在。
+- `customShells` —— 额外启动器；`command` 可为绝对路径或从 `PATH` 解析的名称
+  （Windows 上叠加 `PATHEXT`）。
+
+## 安装
+
+```sh
+# 本地开发
+dsh plugin --profile web add ./dsh-single-terminal
+
+# 已发布：npm / tarball / GitHub
+dsh plugin --profile web add dsh-single-terminal
+dsh plugin --profile web add ./dsh-single-terminal-0.1.0.tgz
+dsh plugin --profile web add github:you/dsh-single-terminal#<sha>
+
+dsh --profile web                 # 启动（宿主半边需重启后生效）
+```
+
+> **node-pty** 是宿主半边的原生依赖（`dependencies`，构建时保持 external，
+> 运行时经 `createRequire` 加载）。常见平台有预编译产物；特殊平台
+> `pnpm install` 时需要 C/C++ 工具链编译。浏览器半边完整内联 xterm.js，
+> 无运行时依赖。
+
+## 开发
+
+环境要求：**Node ≥ 22.19（或 ≥ 24）+ pnpm 10**（`packageManager` 固定 pnpm 版本）。
+
+```sh
+pnpm install           # node-pty + ws（运行时）、@xterm/*（内联进 client）
+pnpm run check         # 全树 TypeScript 类型检查（tsc -b）
+pnpm run build         # 清空 lib → tsc -b（声明文件）→ tsdown（双半产物）
+pnpm run watch         # tsdown watch 模式
+pnpm run verify        # 模拟宿主 seed 表检查 lib/client.js 可加载
+```
+
+```
+├── src/host/           # 宿主半边：index.ts（入口，ws 路由 + 配置）、hub.ts（会话 Hub + 帧协议）、shells.ts（注册表 + 探测）、types.ts
+├── src/client/         # 浏览器半边：plugin.tsx（slots）、drawer.tsx、term.tsx、controller.ts、ws.ts、styles.ts、i18n.ts ...
+├── lib/index.js        # 宿主半边产物（tsdown，ESM）
+├── lib/client.js       # 浏览器半边产物（tsdown → __ModuleLoader__ 工厂，xterm 已内联）
+├── scripts/verify-client.mjs    # 宿主 seed 表模拟检查
+├── scripts/gen-xterm-css.mjs    # 从 @xterm/xterm 包重新生成 src/client/xterm-css.ts
+├── cordis.patch.yml    # Bundle patch：按包名引用的插件行（无路径）
+└── package.json        # dsh.bundle + dsh.client(web) manifests + peerDependencies
+```
+
+## 实现说明
+
+- **插件为何自带 node-pty**：宿主 `subprocess` 的终端原语
+  （`SubprocessTerminalHandle`）不暴露 `resize`，而尺寸跟随是终端抽屉的刚需；
+  插件自持 `node-pty` 即可获得与宿主同底座（ConPTY/forkpty）的完整
+  `write / resize / kill` 控制。
+- **传输**：经 `ctx.webServer.registerUpgrade` 注册独立 WebSocket 路由
+  （`/api/dsh-single-terminal.ws`），`ctx.connection.requestRejection`
+  鉴权（与宿主 API gateway 同一信任围栏）。客户端同源连接，自动携带
+  `dsh-auth` cookie。
+- **会话模型**：会话保存在 Hub 的 `Map` 中，与 socket 解耦——页面刷新 / 重连后
+  重新 `list`、adopt 存活会话并 `attach` 回放环形缓冲。已退出的会话从快照中
+  修剪，死标签不会复活。多个浏览器标签可同时 attach 同一会话（输出广播、
+  输入合并）。
+- **帧协议**：JSON 文本帧；客户端 → 宿主 `open / input / resize / close /
+  list / attach / ping`，宿主 → 客户端 `hello / shells / opened / data /
+  replay / exit / error / pong`。`input`/`resize` 在服务端限长并钳制尺寸。
+- **Windows 进程树**：关闭标签执行 `pty.kill()` 后追加 `taskkill /T /F` ——
+  仅关 ConPTY 时 PowerShell（+PSReadLine）可能存活；POSIX 杀前台进程组
+  （`kill(-pid)`）。
+- **不修改官方 `deepseek-harness` 项目**；全部 UI 落在既有插槽
+  （`shell.overlay`、`conversation.session.header.utilities`）。

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# dsh-single-terminal 静态插件 · 组合包 patch（docs/develop/basic/publish 形态）
+#
+# 作为 dsh.bundle 组合包的分发层：插件行按包名引用（Node 模块解析已安装代码），
+# 而非相对源码路径。安装方式见 README.md。
+
+- insert:
+    - id: dsh-single-terminal
+      name: dsh-single-terminal
+      config:
+        defaultShell: powershell
+        defaultCwd: workspace