@wingsky-1/dsh-worktree-sidebar 0.2.5

package/lib/shared/contract.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 双端共享契约：宿主与浏览器唯一必须一致的两件事——路由路径与绑定查询的响应形状。
+ *
+ * 两边各写一份的失败形态是静默的：客户端拿着对不上的键去 `__DSH_ROUTES__` 取值，
+ * 只会表现成「树没换根」；响应字段名各写一份，表现成「revision 读不到、绑定永远不刷新」。
+ * 两者都不会报错指向分歧点。所以它们在这里各定义一次。
+ *
+ * 存储形状（`bindings.json` 的版本与记录）不在这里：它只有 binding 域与它的测试读，
+ * 属域内契约，物理定义在 `server/binding/impl/model/type.ts`。
+ */
+/** 宿主路由清单。键名即 `__DSH_ROUTES__` 的键。 */
+export declare const ROUTES: {
+    readonly bindings: "/api/dsh-worktree-sidebar/bindings";
+    readonly health: "/api/dsh-worktree-sidebar/health";
+};
+/**
+ * 绑定查询端点的响应体：宿主 handler 写、客户端读取处读，两边都从这里取字段名。
+ *
+ * 字段名必须是类型而不是值常量——只有类型层才能让「某一端改回旧字面量」当场编译失败。
+ */
+export interface BindingResponse {
+    /** 绑定表修订号；客户端以它判定「宿主侧是否已经变了」。 */
+    readonly revision: number;
+    /** 该会话当前生效的 worktree 根；null 表示按会话 cwd 走。 */
+    readonly worktreePath: string | null;
+}

package/lib/shared/interface.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 双端共享契约的收口面——宿主与浏览器都必须一致的定义从这里取。
+ *
+ * 三个同名 `shared` 不同层，别互相搬：`src/shared/` 是**双端**共享；
+ * `src/server/shared/` 是宿主内部叶子；`src/client/shared/` 是客户端块间类型面。
+ */
+export { ROUTES } from "./contract.js";
+export type { BindingResponse } from "./contract.js";

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@wingsky-1/dsh-worktree-sidebar",
+  "version": "0.2.5",
+  "description": "把某个 git worktree 登记给当前会话，使该会话的官方右侧栏文件树根指向该 worktree；会话 cwd 不变。官方提供原生 worktree 会话能力即退役的过渡适配层。",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml",
+      "bannerJs": "import { createRequire as __worktreeSidebarRequire } from \"node:module\";\nconst require = __worktreeSidebarRequire(import.meta.url);"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-sidebar-right"
+      ],
+      "platform": "web"
+    }
+  },
+  "files": [
+    "lib",
+    "shared/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/dsh-agent": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-api-workspace-files": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-session": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.5-rc.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/dsh-agent": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-api-workspace-files": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.5-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.5-rc.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-agent": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-api-workspace-files": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-host-webserver": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-typert-protocol": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wingsky-1/dsh-plugin-hub.git",
+    "directory": "packages/dsh-worktree-sidebar"
+  },
+  "bugs": {
+    "url": "https://github.com/wingsky-1/dsh-plugin-hub/issues"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "worktree",
+    "git",
+    "sidebar"
+  ],
+  "author": "wingsky-1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build/clean-lib.ts && tsc -p tsconfig.json && node ../../scripts/build/bundle-host.ts .",
+    "test": "node ../../scripts/test/run-vitest.mjs --min 19",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/shared/client/ensure-style.d.ts

@@ -0,0 +1,21 @@
+/** ensureStyle 参数（issue #477 v2 契约）。 */
+export interface EnsureStyleOptions {
+  /** <style> 幂等键（package-owned 命名空间，统一 `dsh-<pkg>-style` 前缀隔离）。 */
+  id: string;
+  /** 样式文本（构建期 text-loader 内联的 style.css 内容）。 */
+  cssText: string;
+  /** 可选版本号：写入 dataset.version；变化时旧节点 remove 后重建（热更新失效）。 */
+  version?: string;
+}
+
+/**
+ * 按 id 幂等注入 <style> 节点（5 包统一样式注入入口，issue #477 收敛）。
+ *
+ * 行为契约：
+ * - head 缺失（document.head == null）静默早退 no-op 不抛；
+ * - 同 id 已存在且 version 未变（或未传）→ 不动现有节点；version 变化 → 重建；
+ * - 无 version 不写 dataset.version；
+ * - 返回 disposer（remove 该 id 节点；节点不存在时 no-op），卸载后再次调用
+ *   ensureStyle 重新注入。
+ */
+export declare function ensureStyle(options: EnsureStyleOptions): () => void;

package/shared/client/i18n.d.ts

@@ -0,0 +1,15 @@
+/** 翻译函数形态（与官方 Translate 一致：key + {name} 占位参数）。 */
+export declare type TranslateFn = (key: string, params?: Record<string, unknown>) => string;
+
+/**
+ * 当前翻译函数（apply 时由各包 index.ts 经 bindLocale 装配）。
+ * 未装配时回落 key 本体（行为零变化）。
+ */
+export declare let t: TranslateFn;
+
+/**
+ * 装配/重绑翻译函数（官方 ctx.locale.bind(ns) 产物；语言切换 subscribe 内重调）。
+ * @param locale 宿主 locale 服务（须实现 bind）。
+ * @param ns 本插件字典命名空间。
+ */
+export declare function bindLocale(locale: any, ns: string): void;

package/shared/dsh-home.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 用户 home 目录（`~` 的展开目标）：`HOME` 非空白原样采用，未设置或空白回落
+ * `os.homedir()`；Windows 以 `USERPROFILE` 优先（对齐 libuv）。显式读 env 而非
+ * 直接 `os.homedir()`，是因为后者读进程级 environ，在 worker_threads（Stryker
+ * 的 vitest-runner 强制 `pool: 'threads'`）下无法被测试的 `process.env.HOME` 隔离；
+ * 取值次序与 libuv 一致，默认形态逐字节不变。
+ */
+export declare function userHome(): string;
+
+/**
+ * DSH home 解析（单一事实源）：`DSH_HOME` 非空白原样采用；未设置或空白回落
+ * `~/.dsh`（默认形态路径逐字节不变）。语义对齐官方
+ * `@deepseek-ai/dsh-home-paths#resolveDshHome`（空白 env 视同未设置）。
+ */
+export declare function dshHome(): string;

package/shared/host-utils.d.ts

@@ -0,0 +1,65 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { LoopbackOptions } from "./loopback.d.ts";
+
+/** 写 JSON 响应（统一带 referrer-policy 头，防 referrer 泄露）。 */
+export declare function writeJson(res: ServerResponse, status: number, payload: unknown): void;
+
+/**
+ * 序列化一帧 SSE data 行（输出形如 `data: <json>\n\n`）。
+ * undefined / 含换行 payload 行为对齐三包历史实现、非承诺契约（#472）。
+ */
+export declare function sseData(payload: unknown): string;
+
+/** 请求体读不出来的具体成因：供端点在失败文案里说清是哪一种。 */
+export type JsonBodyInvalidReason = "too-large" | "unreadable" | "malformed" | "not-object";
+
+/** `readJsonBodyOutcome` 的成因可辨结果：缺席（可选 body 未给）/ 合法对象 / 非法（带具体成因）。 */
+export type JsonBodyOutcome =
+  | { kind: "absent" }
+  | { kind: "json"; value: object }
+  | { kind: "invalid"; reason: JsonBodyInvalidReason };
+
+/**
+ * 读请求 body（JSON）并保留失败成因：需要 fail-closed 的端点用它（畸形 body 不能被当成「没有 body」，
+ * 否则有副作用的端点会拿垃圾输入触发真实动作）。
+ * @param limit 字节上限（默认 2MB）。
+ */
+export declare function readJsonBodyOutcome(
+  req: IncomingMessage,
+  limit?: number,
+): Promise<JsonBodyOutcome>;
+
+/**
+ * 宽松读请求 body（JSON）：解析失败或超限返回 undefined（不抛错），由调用方决定响应。
+ * 成因不可辨——要区分「缺席」与「非法」用 `readJsonBodyOutcome`。
+ * @param limit 字节上限（默认 2MB）。
+ */
+export declare function readJsonBody(
+  req: IncomingMessage,
+  limit?: number,
+): Promise<object | undefined>;
+
+/** 把任意抛出的值转成可读错误消息。 */
+export declare function errorMessage(error: unknown): string;
+
+/**
+ * 读请求 body（JSON，限长防滥用）。
+ * 兼容 Node 事件流（data/end）与 async-iterator 桩两种形态。
+ * @param limit 字节上限（默认 256KB）。
+ */
+export declare function readBody(req: IncomingMessage, limit?: number): Promise<object>;
+
+/**
+ * Loopback + 方法白名单低阶路由守卫：非 loopback → 403，方法不在白名单 → 405，
+ * 否则放行（403 先于 405 为本守卫执行顺序，仅对套守卫端点成立）。
+ * @param methods 允许的 HTTP 方法白名单。
+ * @param loopbackOptions 透传给 isLoopbackRequest 的可选判定参数（#549：仅
+ *   serve 资源路由放行 cross-site no-cors 子资源时使用；其余路由不得传）。
+ * @returns 是否放行（true 时调用方继续处理请求）。
+ */
+export declare function guardLoopbackMethod(
+  req: IncomingMessage,
+  res: ServerResponse,
+  methods: string[],
+  loopbackOptions?: LoopbackOptions,
+): boolean;

package/shared/loopback.d.ts

@@ -0,0 +1,21 @@
+import type { IncomingMessage } from "node:http";
+
+/**
+ * Loopback 围栏判定参数。
+ * - allowCrossSiteNoCors（#549）：仅 serve 类资源伺服路由使用——放行「显式
+ *   sec-fetch-mode: no-cors」的跨站子资源请求（sandbox iframe opaque origin
+ *   的相对路径 css/js/img 加载）；cors fetch/XHR 与 navigate 仍拒绝。
+ *   普通 /api 路由必须保持默认（不传 options）拒绝一切 cross-site。
+ */
+export interface LoopbackOptions {
+  allowCrossSiteNoCors?: boolean;
+}
+
+/**
+ * Loopback 围栏：请求必须来自回环地址 + 回环 Host，且满足跨站/来源约束，
+ * 否则拒绝（DNS 重绑定 + 跨站防御）。
+ */
+export declare function isLoopbackRequest(
+  request: IncomingMessage,
+  options?: LoopbackOptions,
+): boolean;

package/shared/settings-namespace.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 宿主端「设置命名空间」注册（单一事实源）。
+ *
+ * 背景与语义见 settings-namespace.js 顶部注释。要点：DSH rc.7 起设置卡槽
+ * `settings.plugin.item` 为 keyed，只有在「宿主 serve 的命名空间 ∩ 卡片 key」
+ * 非空时渲染；为让卡片显示，宿主端需用此函数把命名空间注册进 settings 服务。
+ * 零包依赖，服务面注入，等值复刻官方 `installSettingsSection`（dsh-settings）。
+ */
+
+/** `installSettingsNamespace` 的 hooks 面。 */
+export interface SettingsNamespaceHooks {
+  /** 把插件对该命名空间的读取来源指向返回的 scope（`scope.get()`）。 */
+  setSource(source: () => unknown): void;
+  /** 来源切换或命名空间值变化时触发，插件据此刷新/落盘。 */
+  onChange(): void;
+  /** 可选自定义校验，透传给 settings.register。 */
+  validate?: unknown;
+  /**
+   * 可选；register 返回 owner scope 后立即回调（先于 setSource）。
+   * 供存量配置迁移 / 写路径装配使用；settings 服务缺失时不触发。
+   */
+  onScope?(scope: unknown, service: unknown): void;
+}
+
+/**
+ * 日志兜底：logger 可能确实没有（极端降级），全部可选调用。
+ * 单一事实源（#436）：notifier / lan-proxy 曾各复刻一份，现统一引用本导出。
+ */
+export declare function warnLog(ctx: unknown, message: string): void;
+
+/**
+ * 注册插件自有 settings 命名空间（服务面注入，无包依赖）。
+ * 等值语义参考官方 `installSettingsSection`（@deepseek-ai/dsh-settings@0.1.0-rc.7）。
+ * @param ctx - 插件宿主端 apply 收到的 cordis 上下文。
+ * @param ns - 插件自有命名空间（小写 kebab，须唯一）。
+ * @param schema - schemastery schema，解析该命名空间的值（通常为插件 Config）。
+ * @param entry - 组合层配置，作为命名空间的 `base` 层。
+ * @param hooks - source 收藏与变更通知。
+ */
+export declare function installSettingsNamespace(
+  ctx: unknown,
+  ns: string,
+  schema: unknown,
+  entry: unknown,
+  hooks: SettingsNamespaceHooks,
+): void;

package/shared/sse-hub.d.ts

@@ -0,0 +1,76 @@
+import type { ServerResponse } from "node:http";
+
+/**
+ * 连接表项状态（stalledAt 缺省 = 未 stalled）。
+ * failStreak：连续写抛错次数（≥3 ≈ 3 心跳周期判死，对齐 dsh-notifier 原版）。
+ */
+export interface SseConnState {
+  /** 连续写抛错次数。 */
+  failStreak: number;
+  /** 自上次成功写/心跳以来的"写被拒"起始时刻（ms epoch；缺省 = 未 stalled）。 */
+  stalledAt?: number;
+  /** 注册时刻（ms epoch；maxAge 轮换依据）。 */
+  registeredAt: number;
+  /** 最近一次成功写时刻（ms epoch；idle 判定依据）。 */
+  lastWriteAt: number;
+}
+
+/** 回收/淘汰原因（health 观测 + 调试）。`dispose` = 卸载时统一关连接那一次。 */
+export type SseEvictReason = "close" | "error" | "stalled" | "maxage" | "destroyed" | "dispose";
+
+/** evict 原因计数（health 观测：先量化残留构成再调参）。键集与 `SseEvictReason` 一一对应。 */
+export interface SseEvictStats {
+  close: number;
+  error: number;
+  stalled: number;
+  maxage: number;
+  destroyed: number;
+  dispose: number;
+}
+
+/** 连接健康观测：排障用明细，**故意不进 `/health`**——它随连接数增长，
+ *  而 `/health` 是常量大小的聚合面且经 lan-proxy 对局域网可见。真要暴露请单开路由。 */
+export interface SseConnHealth {
+  /** 连接已存活时长（ms）。 */
+  ageMs: number;
+  /** 距最近成功写已过去时长（ms；-1 = 从未写过）。 */
+  lastWriteAgoMs: number;
+  /** 当前 stalled 持续时长（ms；-1 = 未 stalled）。 */
+  stalledMs: number;
+}
+
+/** createSseHub 选项。 */
+export interface SseHubOptions {
+  /** 心跳间隔（默认 30s；测试注入短值）。 */
+  heartbeatMs?: number;
+  /** stalled 回收窗口：连续写被拒超过此时长即 evict（默认 90s）。 */
+  stalledTimeoutMs?: number;
+  /** maxAge 轮换上限（默认 120min；0 = 关闭轮换）。 */
+  maxAgeMs?: number;
+  /** maxAge 轮换的"空闲"门槛：距最近成功写超过此时长才算空闲（默认 15min）。 */
+  idleTimeoutMs?: number;
+}
+
+/**
+ * SSE 连接枢纽（共享核心，取代各包自建连接表）。
+ * 连接表 + 心跳 + stalled/maxAge 主动回收（#515）。
+ * 广播负载生成留调用方：hub 只向全部连接写现成 text 帧并判死收口；
+ * ?since 补拉（notifier 路由层行为）不进 hub。
+ */
+export interface SseHub {
+  /** 注册一条 SSE 连接：入表 + 挂 close/error 监听。 */
+  register(res: ServerResponse): void;
+  /** 向全部连接写一帧 text（调用方生成，通常经 sseData()）；判死收口在内部。 */
+  broadcast(text: string): void;
+  /** 当前连接数（语义 = 服务端未释放句柄数）。 */
+  size(): number;
+  /** evict 原因计数（health 观测）。 */
+  evictStats(): SseEvictStats;
+  /** 连接健康快照（按注册序；排障用明细，不进 `/health`，理由见 `SseConnHealth`）。 */
+  connHealth(now?: number): SseConnHealth[];
+  /** 停止心跳定时器。 */
+  dispose(): void;
+}
+
+/** 创建 SSE 枢纽并启动心跳（unref：不阻止进程退出）。 */
+export declare function createSseHub(options: SseHubOptions): SseHub;