@zhangzhian/dsh-devtools-terminal 0.0.0-stage → 0.3.0

package/lib/routes.js

@@ -0,0 +1,115 @@
+/**
+ * 宿主侧唯一的一条路由：把 xterm 懒加载块发出去。
+ *
+ * ## 为什么需要宿主路由
+ *
+ * 浏览器里 xterm 是几百 KB，不该进启动路径。DSH 的客户端加载器没有代码分割能力
+ * （factory 里的 `require` 只认种子模块和已加载的插件行，网络上的块拿不到），
+ * 所以懒加载只能自己搭：客户端插一个
+ * `<script src="/devtools-terminal/bundle/chunk-terminal.js">`，这个 URL 由宿主发。
+ *
+ * ## 两个必须守住的点
+ *
+ * 1. **白名单**：`<name>` 直接拼进文件路径，不校验就是任意文件读取。
+ * 2. **Host 围栏**：这个路由不需要会话、不需要工作区，所以任何能访问到端口的
+ *    东西都能拿到。绑定在回环上时要求 Host 也是回环名 —— 否则一个恶意网页
+ *    可以用 DNS rebinding 把请求打进来读本地文件。绑定 `0.0.0.0` 时用户
+ *    已经明确选择对外，放行。
+ *
+ * （与 `dsh-devtools-workbench` 的同名函数刻意各自实现：这是安全边界，
+ * 让它跟着各自的路由表走，比共享一份更不容易被改坏。）
+ */
+import { once } from 'node:events';
+import { createReadStream } from 'node:fs';
+/** 路由前缀（客户端 `chunk-loader.ts` 里的 URL 必须与它一致）。 */
+export const PREFIX = '/devtools-terminal';
+/** 允许发出去的产物名（白名单，**不要**改成读目录）。 */
+const BUNDLE_NAMES = new Set(['chunk-terminal.js']);
+/** 认定为回环的 Host 名。 */
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1', '[::1]', '0.0.0.0']);
+/** 客户端产物目录。 */
+const clientDir = new URL('../client/', import.meta.url);
+/**
+ * 注册路由。
+ *
+ * @param ctx - host 上下文（需要 `ctx.webServer`）。
+ * @returns 卸载函数。
+ */
+export function registerRoutes(ctx) {
+    return ctx.webServer.register({
+        kind: 'prefix',
+        path: `${PREFIX}/bundle`,
+        handler: (request, response) => {
+            serveBundle(ctx, request, response);
+        },
+    });
+}
+/**
+ * 发一个懒加载块。
+ *
+ * @param ctx - host 上下文。
+ * @param request - 请求。
+ * @param response - 响应。
+ */
+async function serveBundle(ctx, request, response) {
+    if (!trusted(request, ctx)) {
+        send(response, 403, 'forbidden');
+        return;
+    }
+    if (request.method !== 'GET' && request.method !== 'HEAD') {
+        send(response, 405, 'method not allowed');
+        return;
+    }
+    const name = decodeURIComponent((request.url ?? '').split('?')[0] ?? '').slice(`${PREFIX}/bundle/`.length);
+    if (!BUNDLE_NAMES.has(name)) {
+        // 白名单之外一律 404（**不要**回显 name：那是反射）。
+        send(response, 404, 'not found');
+        return;
+    }
+    const stream = createReadStream(new URL(name, clientDir));
+    try {
+        await once(stream, 'open');
+    }
+    catch {
+        send(response, 404, 'not found');
+        return;
+    }
+    response.writeHead(200, {
+        'content-type': 'text/javascript; charset=utf-8',
+        'cache-control': 'no-store',
+        'x-content-type-options': 'nosniff',
+    });
+    stream.pipe(response);
+}
+/**
+ * 请求来自可信来源吗。
+ *
+ * @param request - 请求。
+ * @param ctx - host 上下文。
+ * @returns 可信时为 `true`。
+ */
+function trusted(request, ctx) {
+    if (ctx.webServer.host === '0.0.0.0')
+        return true;
+    const host = request.headers.host ?? '';
+    // Host 可能带端口：`127.0.0.1:3080`。
+    const name = host.startsWith('[') ? host.slice(0, host.indexOf(']') + 1) : (host.split(':')[0] ?? '');
+    return LOOPBACK.has(name);
+}
+/**
+ * 回一个短文本响应。
+ *
+ * @param response - 响应。
+ * @param status - 状态码。
+ * @param body - 响应体。
+ */
+function send(response, status, body) {
+    if (response.headersSent || response.writableEnded)
+        return;
+    response.writeHead(status, {
+        'content-type': 'text/plain; charset=utf-8',
+        'cache-control': 'no-store',
+        'x-content-type-options': 'nosniff',
+    });
+    response.end(body);
+}

package/lib/types/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `dsh-devtools-terminal` — 右侧栏终端（接管平台内置 `terminal` 页签，带链接能力）。
+ *
+ * ## 这一行为什么存在
+ *
+ * 平台的右侧栏终端只做了「PTY → xterm」，**没有 link provider**：输出里的 URL
+ * 只是普通文字，点不了。平台把那个终端做成了**私有**懒加载块，第三方插件既拿
+ * 不到 xterm 实例、也换不掉它的 UI —— 唯一干净的扩展点是页签类型注册表：
+ * 一个 `priority: 'extension'` 的注册可以**顶替**同 kind 的内置类型
+ * （`sidebar-right` 的 `tab-registry` 文档原话；仓库里的 `dsh-devtools-files`
+ * 已经用同一手法接管了内置 `files`）。
+ *
+ * 所以我们接管 `terminal` 这个 kind：自己渲染终端（xterm 走懒加载块），
+ * 顺手在 xterm 上注册 link provider。PTY 仍然用**平台的** `ctx.webTerminals`，
+ * 不自己起进程 —— 否则会和宿主的并发上限、空闲回收、崩溃恢复三套机制打架。
+ *
+ * ## host 半
+ *
+ * 只有一条路由：把 `chunk-terminal.js`（xterm + FitAddon）发给浏览器。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** 依赖门：只有 `webServer`（懒加载块路由）。 */
+export declare const inject: string[];
+/**
+ * 挂载 host 半。
+ *
+ * @param ctx - host 根上下文。
+ */
+export declare function apply(ctx: Context): void;

package/lib/types/link-target.d.ts

@@ -0,0 +1,50 @@
+/** 链接最终落到哪儿。 */
+export type LinkDestination = 'panel' | 'external';
+/**
+ * 决定一次打开该落到哪儿。
+ *
+ * 面板可用就优先面板 —— 这是本插件要的产品行为（用户要的是"在 DSH 插件浏览器
+ * 里打开"，而不是跳出去）。不可用（profile 关掉了那一行 / 平台版本没有这个页签
+ * 类型）才回退系统浏览器。
+ *
+ * @param panelAvailable - 右栏浏览器页签当前是否可用。
+ * @returns 落点。
+ */
+export declare function linkDestination(panelAvailable: boolean): LinkDestination;
+/** 打开链接需要的外部动作（由客户端注入；host 侧测试喂假的）。 */
+export interface LinkOpenPorts {
+    /**
+     * 右栏浏览器页签现在可用吗。
+     *
+     * 每次**点击时**都问一次（不是启动时问一次）：`browser` 页签类型由平台插件
+     * 注册/卸载，和本插件同批加载、顺序不保证；而且 profile 的 patch 可能随时改。
+     *
+     * @returns 页签类型在注册表里存在时为 true。
+     */
+    panelAvailable(): boolean;
+    /**
+     * 在右栏浏览器里打开一个地址。
+     *
+     * 地址已经过 {@link isHttpUrl} 校验；实现方不必再验。**允许抛错**（页签刚被
+     * 关掉、面板没有会话作用域等），抛了就回退 {@link LinkOpenPorts.openExternal}。
+     *
+     * @param url - http(s) 地址。
+     */
+    openInPanel(url: string): void;
+    /**
+     * 回退：交给系统 / 默认浏览器。
+     *
+     * @param url - http(s) 地址。
+     */
+    openExternal(url: string): void;
+}
+/**
+ * 造一个「打开终端链接」的动作。
+ *
+ * 语义（与 VSCode 终端一致）：只认 http(s)；面板优先；面板这次没开成功就回退
+ * 系统浏览器 —— **不能因为面板抛错就什么都不做**，那等于点击没反应。
+ *
+ * @param ports - 外部动作。
+ * @returns 打开动作（非 http(s) 静默忽略）。
+ */
+export declare function createLinkOpener(ports: LinkOpenPorts): (url: string) => void;

package/lib/types/links.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 终端链接的**纯逻辑**：URL 识别、折行拼接、字符→单元格映射。
+ *
+ * ## 为什么单独放这里（不塞进客户端半）
+ *
+ * 客户端半进浏览器、只能靠 E2E 验；而这几个函数是纯字符串/坐标运算，
+ * 放在 host 可编译进 `lib/`，用 `node --test` 就能把边界钉死
+ * （折行、宽字符、中文标点、成对括号……）。客户端分块再 import 同一份代码
+ * （tsdown 会内联进去）。
+ *
+ * ## 只依赖「行」的最小结构
+ *
+ * xterm 的 `IBufferLine` 在这里只以结构类型出现（`isWrapped` / `length` /
+ * `getCell`），不 import xterm —— 于是测试可以喂假行，客户端也照常编译。
+ */
+/** 一条逻辑行最多往回/往前拼多少行（防病态 scrollback 把主线程卡住）。 */
+export declare const MAX_LOGICAL_ROWS = 256;
+/** 一行里的一个字符落在哪个单元格（`row`/`col` 为 0 基，`width` 为 1 或 2）。 */
+export interface CellRef {
+    readonly row: number;
+    readonly col: number;
+    readonly width: number;
+}
+/** 一条逻辑行：拼好的文本 + 每个字符的单元格映射。 */
+export interface LogicalLine {
+    readonly text: string;
+    readonly cells: readonly CellRef[];
+}
+/** 文本里命中的一条 URL（下标是**文本下标**，不是列号）。 */
+export interface UrlMatch {
+    readonly url: string;
+    readonly start: number;
+    readonly end: number;
+}
+/** 按行切开的一段链接范围（`startCol`/`endCol` 0 基，`endCol` 是最后一个被占单元格）。 */
+export interface LinkSegment {
+    readonly row: number;
+    readonly startCol: number;
+    readonly endCol: number;
+}
+/** xterm `IBufferCell` 里我们用到的两个方法。 */
+export interface LineCellLike {
+    getWidth(): number;
+    getChars(): string;
+}
+/** xterm `IBufferLine` 里我们用到的三个成员。 */
+export interface LineLike {
+    readonly isWrapped: boolean;
+    readonly length: number;
+    getCell(col: number): LineCellLike | undefined;
+}
+/**
+ * 判断字符串是不是可打开的 http(s) 地址。
+ *
+ * @param text - 候选文本。
+ * @returns http/https 且能被 URL 解析时为 true。
+ */
+export declare function isHttpUrl(text: string): boolean;
+/**
+ * 剥掉 URL 末尾不属于它的标点。
+ *
+ * 两种规则：常见中英文句读一律剥；收尾的 `)`/`]`/`}` 只有在**没有配对的开括号**
+ * 时才剥（`https://en.wikipedia.org/wiki/Foo_(bar)` 保持完整）。
+ *
+ * @param url - 正则刚匹配出来的候选。
+ * @returns 剥过尾巴的候选（可能为空串）。
+ */
+export declare function trimTrailing(url: string): string;
+/**
+ * 找出一段文本里的所有 http(s) URL。
+ *
+ * @param text - 一条逻辑行的纯文本。
+ * @returns 命中列表（`end` 开区间）。
+ */
+export declare function findUrls(text: string): UrlMatch[];
+/**
+ * 从请求行往回走到逻辑行开头，再把续行拼起来。
+ *
+ * 终端里的「一行」在 buffer 里可能是多行：**只有续行**的 `isWrapped` 为 true。
+ * URL 被折成两行是常见情况，所以识别必须以逻辑行为单位。
+ *
+ * @param getLine - `(row0) => 行 | undefined`，row0 为 0 基行号。
+ * @param row - 请求行（0 基）。
+ * @returns 逻辑行；拿不到行时返回 null。
+ */
+export declare function readLogicalLine(getLine: (row: number) => LineLike | undefined, row: number): LogicalLine | null;
+/**
+ * 把「文本下标区间」切成按行分段的单元格区间。
+ *
+ * xterm 的 ILink 可以跨行，但渲染器按行画下划线；按行切段最省事，每段都带完整
+ * URL 文本（点任何一段打开的都是整个 URL）。
+ *
+ * @param cells - {@link readLogicalLine} 的 cells。
+ * @param start - 起始文本下标（含）。
+ * @param end - 结束文本下标（不含）。
+ * @returns 按行的分段。
+ */
+export declare function segmentsOf(cells: readonly CellRef[], start: number, end: number): LinkSegment[];
+/**
+ * 生成请求行上的链接范围（1 基、含首尾，xterm ILink 的坐标约定）。
+ *
+ * @param getLine - `(row0) => 行 | undefined`。
+ * @param row - 请求行（0 基）。
+ * @param makeLink - `(url, range) => T`，由调用方决定 ILink 的 activate 实现。
+ * @returns 请求行上的链接。
+ */
+export declare function linksForRow<T>(getLine: (row: number) => LineLike | undefined, row: number, makeLink: (url: string, range: {
+    start: {
+        x: number;
+        y: number;
+    };
+    end: {
+        x: number;
+        y: number;
+    };
+}) => T): T[];

package/lib/types/routes.d.ts

@@ -0,0 +1,10 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** 路由前缀（客户端 `chunk-loader.ts` 里的 URL 必须与它一致）。 */
+export declare const PREFIX = "/devtools-terminal";
+/**
+ * 注册路由。
+ *
+ * @param ctx - host 上下文（需要 `ctx.webServer`）。
+ * @returns 卸载函数。
+ */
+export declare function registerRoutes(ctx: Context): () => void;

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Terminal",
+    "description": "Right-sidebar terminal with Cmd/Ctrl+clickable links."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "终端",
+    "description": "右侧栏终端：输出里的 URL 支持 Cmd/Ctrl+点击打开。"
+  }
+}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@zhangzhian/dsh-devtools-terminal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "type": "module",
+  "description": "DSH 开发工具：右侧栏终端（Ctrl/Cmd+点击打开输出里的 URL）",
+  "license": "MIT",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "terminal"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://codeup.aliyun.com/67617ae720a07de19c7c1633/dsh-plugins.git",
+    "directory": "packages/dsh-devtools-terminal"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "lib",
+    "client",
+    "locale"
+  ],
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": "./client/client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@xterm/addon-fit": "^0.10.0",
+    "@xterm/xterm": "^5.5.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.2"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsdown": "^0.23.0",
+    "typescript": "^5.9.0"
+  },
+  "dsh": {
+    "client": {
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('client',{recursive:true,force:true})\" && tsc -p tsconfig.json && tsc -p tsconfig.client.json && tsdown",
+    "watch": "tsdown --watch",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.client.json",
+    "test": "pnpm build && tsc -p tsconfig.json && node --test test/*.test.mjs"
+  }
 }