@cerbur/clutch-dsh-worktree 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# @cerbur/clutch-dsh-worktree
+
+`@cerbur/clutch-dsh-worktree` 为 DSH Web UI 增加按 Git Worktree 组织 Session 的视角，同时继续由 DSH 管理原始 Project/Workspace 和 Session 数据。
+
+English marketplace description:
+
+> Adds a Worktree view to DSH Web UI that groups Sessions by Git worktree while keeping DSH as the source of truth.
+
+## 功能
+
+从 DSH Sidebar footer 打开 Worktree mode 后，可以：
+
+- 按 Workspace → Worktree → Session 查看会话；
+- 搜索 Workspace，并从已有 local branch 创建新的 Git Worktree 和 branch；
+- 在 Main 或指定 Worktree 下创建 Session，并直接打开新 Session；
+- 查看 active、detached 和 repair 状态；
+- 继续使用 DSH 原生的 Workspace rename/delete/reorder 和 Session 菜单、排序能力。
+
+Worktree Session 仍属于原始 DSH Project/Workspace，因此切回原生 Project/Session 视角时仍可由 DSH 展示。插件不复制 Session 内容，也不修改消息、prompt、transcript 或历史记录。
+
+## 兼容性与前置条件
+
+- DSH CLI 和目标 Web profile 使用 `dsh-v0.1.0-rc.8`；
+- 已有可启动的 DSH profile，例如 `web` 或 `demo`；
+- plugin 安装在实际启动 Web UI 的同一个 profile；
+- 要使用 Worktree 功能，目标 Workspace 必须位于 Git repository 中。
+
+package manifest 已声明可安装的 `dsh.bundle`，并随 package 提供 `cordis.patch.yml`；Web UI 使用另行声明的 `dsh.client` browser entry。
+
+## 安装
+
+### 从本地 checkout 安装
+
+先在 `clutch-dsh` 根目录构建 package：
+
+```bash
+cd /path/to/clutch-dsh
+pnpm install
+pnpm --filter @cerbur/clutch-dsh-worktree build
+```
+
+再在本地 `deepseek-harness` 根目录构建 DSH，并把 package 安装到目标 profile：
+
+```bash
+cd /path/to/deepseek-harness
+pnpm install
+pnpm run build
+pnpm dsh plugin --profile web add /path/to/clutch-dsh/packages/clutch-dsh-worktree
+pnpm dsh web --dump-config
+pnpm dsh web
+```
+
+建议使用绝对路径。`--dump-config` 输出中应能看到 `@cerbur/clutch-dsh-worktree` 的 bundle layer。
+
+如果 profile 之前安装过旧的 unscoped package，先移除旧条目：
+
+```bash
+pnpm dsh plugin --profile web remove clutch-dsh-worktree
+```
+
+### 从 package registry 安装
+
+package 发布到 registry 后，可以在 `deepseek-harness` 根目录执行：
+
+```bash
+pnpm dsh plugin --profile web add @cerbur/clutch-dsh-worktree
+pnpm dsh web
+```
+
+从已链接的本地 checkout 更新时，只需重新构建 package 并重启 DSH：
+
+```bash
+cd /path/to/clutch-dsh
+pnpm --filter @cerbur/clutch-dsh-worktree build
+cd /path/to/deepseek-harness
+pnpm dsh web
+```
+
+修改 `package.json`、`cordis.patch.yml` 或 profile bundle 成员后，需要重新执行 `dsh plugin add`。
+
+### 卸载
+
+```bash
+cd /path/to/deepseek-harness
+pnpm dsh plugin --profile web remove @cerbur/clutch-dsh-worktree
+```
+
+## 使用说明
+
+1. 启动 DSH Web UI，在 Sidebar footer 打开 Worktree mode。
+2. 使用 Workspace 的 `+` 选择基线 local branch，填写新的 Worktree name；默认 branch 名为 `dsh/<8位随机串>`。
+3. 使用 Main 旁边的 `+` 创建普通 DSH Session。
+4. 使用 Worktree 旁边的 `+` 创建 cwd 指向该 Worktree 的 Session；插件完成关系绑定后打开它。
+5. 观察 Worktree 的 ready、repair 或 detached 状态。当前 Worktree surface 不提供 Remove Worktree 入口。
+
+Workspace 删除只删除 DSH 的 Workspace registration；其目录、Session、Git Worktree 和 plugin sidecar 会保留。
+
+## 当前限制
+
+DSH rc.8 的原生 `session.create` 不能同时接收 `workspaceId` 和独立 `cwd`。Worktree Session 因此先以 `cwd` 创建，再由插件保存关系，并在当前浏览器内投影 Workspace membership；这不会修改 DSH 源码或 Session metadata。需要 DSH 原生持久 attach 时，仍需 DSH 提供同时支持 Workspace 与独立 cwd 的 API。
+
+如果 Connection、Gateway 或 Worktree 操作失败，界面会保留可重试的错误，不把失败伪装为空列表。删除 Worktree 不会删除 Session；detached 关系会保留，直到显式解绑。
+
+## 开发与验证
+
+在 workspace 根目录执行：
+
+```bash
+pnpm install
+pnpm run check:workspace
+pnpm run check:patches
+pnpm --filter @cerbur/clutch-dsh-worktree typecheck
+pnpm --filter @cerbur/clutch-dsh-worktree build
+pnpm --filter @cerbur/clutch-dsh-worktree test
+```
+
+完整 workspace 校验：
+
+```bash
+pnpm run check
+```
+
+维护者请先阅读 [AGENTS.md](AGENTS.md) 了解数据边界、模块权责、生命周期和验证约束；浏览器 Consumer 的实现说明位于 [`src/client/README.md`](src/client/README.md)。
+
+## 插件市场条目建议
+
+向 `awesome-dsh-plugin` 提交时，建议使用 `git` 分类，并保持描述与实际代码一致：
+
+```yaml
+category: git
+description:
+  en: Adds a Worktree view to DSH Web UI that groups Sessions by Git worktree while keeping DSH as the source of truth.
+  zh: 为 DSH Web UI 增加按 Git Worktree 组织 Session 的视角，同时继续由 DSH 管理原始 Project 和 Session 数据。
+```
+
+市场投稿还需要在外部仓库中确认 `dsh-plugin` topic、仓库年龄和提交数；这些不是 package README 可以代替设置的内容。

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+- insert:
+    - id: clutch-dsh-worktree-host
+      name: '@cerbur/clutch-dsh-worktree'
+      config:
+        dshHome: !!js dshHomePath()

package/lib/client/WorktreeModeAction.d.ts

@@ -0,0 +1,11 @@
+import type { PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots';
+import type { createWorktreeViewStore } from './view-mode-store.js';
+/** Apply-time facts and callbacks owned by the Consumer entry. */
+export interface WorktreeModeActionInjected {
+    readonly available: boolean;
+}
+/** Props derived from the footer slot, shared store, and injected availability face. */
+export type WorktreeModeActionProps = PropsRuntime<'sidebar.footer.action'> & PropsStore<ReturnType<typeof createWorktreeViewStore>> & WorktreeModeActionInjected;
+/** Footer action that enters/exits the peer Worktree navigation mode. */
+export declare function WorktreeModeAction({ wide, useStore, actions, available, }: WorktreeModeActionProps): import("react").JSX.Element | null;
+//# sourceMappingURL=WorktreeModeAction.d.ts.map

package/lib/client/WorktreeModeAction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorktreeModeAction.d.ts","sourceRoot":"","sources":["../../src/client/WorktreeModeAction.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAGjF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAGpE,kEAAkE;AAClE,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,wFAAwF;AACxF,MAAM,MAAM,uBAAuB,GAAG,YAAY,CAAC,uBAAuB,CAAC,GACzE,UAAU,CAAC,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAC,GACtD,0BAA0B,CAAC;AAE7B,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,EACjC,IAAI,EACJ,QAAQ,EACR,OAAO,EACP,SAAS,GACV,EAAE,uBAAuB,sCAsBzB"}

package/lib/client/WorktreeModeAction.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { IconBranchOutline16 } from '@deepseek-ai/dsh-client-ui-primitives';
+import styles from './worktree.css';
+/** Footer action that enters/exits the peer Worktree navigation mode. */
+export function WorktreeModeAction({ wide, useStore, actions, available, }) {
+    if (!available)
+        return null;
+    const mode = useStore((state) => state.viewMode);
+    const active = mode === 'worktree';
+    return (_jsxs("button", { type: "button", className: styles.action, "data-worktree-mode-action": true, "data-active": active || undefined, "data-collapsed": !wide || undefined, "aria-label": active ? 'Exit Worktree mode' : 'Open Worktree mode', "aria-pressed": active, title: active ? 'Exit Worktree mode' : 'Worktree mode', onClick: () => {
+            actions.setViewMode(active ? 'workspace-session' : 'worktree');
+        }, children: [_jsx(IconBranchOutline16, { size: wide ? 16 : 18 }), wide && _jsx("span", { className: styles.actionLabel, children: "Worktree" })] }));
+}
+//# sourceMappingURL=WorktreeModeAction.js.map

package/lib/client/WorktreeModeAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorktreeModeAction.js","sourceRoot":"","sources":["../../src/client/WorktreeModeAction.tsx"],"names":[],"mappings":";AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAE5E,OAAO,MAAM,MAAM,gBAAgB,CAAC;AAYpC,yEAAyE;AACzE,MAAM,UAAU,kBAAkB,CAAC,EACjC,IAAI,EACJ,QAAQ,EACR,OAAO,EACP,SAAS,GACe;IACxB,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAC5B,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,IAAI,KAAK,UAAU,CAAC;IACnC,OAAO,CACL,kBACE,IAAI,EAAC,QAAQ,EACb,SAAS,EAAE,MAAM,CAAC,MAAM,oDAEX,MAAM,IAAI,SAAS,oBAChB,CAAC,IAAI,IAAI,SAAS,gBACtB,MAAM,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,oBAAoB,kBAClD,MAAM,EACpB,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,eAAe,EACtD,OAAO,EAAE,GAAG,EAAE;YACZ,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QACjE,CAAC,aAED,KAAC,mBAAmB,IAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAI,EAC5C,IAAI,IAAI,eAAM,SAAS,EAAE,MAAM,CAAC,WAAW,yBAAiB,IACtD,CACV,CAAC;AACJ,CAAC"}

package/lib/client/WorktreeSurface.d.ts

@@ -0,0 +1,33 @@
+import type { PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots';
+import type { WorktreeManager } from '../contract/index.js';
+import type { createWorktreeViewStore } from './view-mode-store.js';
+import { type CreateSessionForWorktreeInput } from './worktree-view.js';
+/** Apply-time facts and DSH navigation callbacks used by the surface. */
+export interface WorktreeSurfaceInjected {
+    readonly available: boolean;
+    readonly manager?: WorktreeManager;
+    readonly createWorkspace?: () => Promise<void>;
+    readonly createSessionForWorktree?: (input: CreateSessionForWorktreeInput) => Promise<string>;
+    readonly createMainSession?: (workspaceId: string) => void;
+    readonly renameWorkspace?: (workspaceId: string, title: string) => Promise<void>;
+    readonly deleteWorkspace?: (workspaceId: string) => Promise<void>;
+    readonly insertWorkspaceBefore?: (workspaceId: string, beforeWorkspaceId?: string) => Promise<void>;
+    readonly insertSessionBefore?: (workspaceId: string, sessionId: string, beforeSessionId?: string) => Promise<void>;
+    readonly renameSession?: (sessionId: string, title: string) => Promise<void>;
+    readonly forkSession?: (sessionId: string) => void;
+    readonly archiveSession?: (sessionId: string) => Promise<void>;
+    readonly ensureSessionWorkspace?: (workspaceId: string, sessionId: string) => void;
+    readonly syncSessionWorkspaces?: (bindings: readonly {
+        workspaceId: string;
+        sessionId: string;
+    }[]) => void;
+    readonly openSession: (sessionId: string) => void;
+}
+/** Props derived from the frame overlay slot, shared state, and injected face. */
+export type WorktreeSurfaceProps = PropsRuntime<'shell.overlay'> & PropsStore<ReturnType<typeof createWorktreeViewStore>> & WorktreeSurfaceInjected;
+/**
+ * Peer Worktree navigation surface. It keeps the original DSH Workspace mode
+ * intact and renders a browser-local Workspace → Worktree → Session projection.
+ */
+export declare function WorktreeSurface({ useStore, actions, useSessions, useWorkspaces, available, manager, createWorkspace, createSessionForWorktree: createSessionCallback, createMainSession, renameWorkspace, deleteWorkspace, insertWorkspaceBefore, insertSessionBefore, renameSession, forkSession, archiveSession, ensureSessionWorkspace, syncSessionWorkspaces, openSession, }: WorktreeSurfaceProps): import("react").JSX.Element | null;
+//# sourceMappingURL=WorktreeSurface.d.ts.map

package/lib/client/WorktreeSurface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorktreeSurface.d.ts","sourceRoot":"","sources":["../../src/client/WorktreeSurface.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAqBjF,OAAO,KAAK,EAAkB,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG5E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAEpE,OAAO,EASL,KAAK,6BAA6B,EAGnC,MAAM,oBAAoB,CAAC;AAmB5B,yEAAyE;AACzE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,QAAQ,CAAC,wBAAwB,CAAC,EAAE,CAClC,KAAK,EAAE,6BAA6B,KACjC,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjF,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAC/B,WAAW,EAAE,MAAM,EACnB,iBAAiB,CAAC,EAAE,MAAM,KACvB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAC7B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,eAAe,CAAC,EAAE,MAAM,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACnF,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAC/B,QAAQ,EAAE,SAAS;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,KAC5D,IAAI,CAAC;IACV,QAAQ,CAAC,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CACnD;AAED,kFAAkF;AAClF,MAAM,MAAM,oBAAoB,GAAG,YAAY,CAAC,eAAe,CAAC,GAC9D,UAAU,CAAC,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAC,GACtD,uBAAuB,CAAC;AA2jB1B;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,OAAO,EACP,WAAW,EACX,aAAa,EACb,SAAS,EACT,OAAO,EACP,eAAe,EACf,wBAAwB,EAAE,qBAAqB,EAC/C,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,WAAW,GACZ,EAAE,oBAAoB,sCA+jCtB"}