@ohmynpm/dsh-baton 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Baton contributors
+
+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.

package/README.md

@@ -1,3 +1,160 @@
-# Temporary Holding Version
+# Baton DSH plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [中文](README.zh-CN.md)
+
+The DSH side of Baton: receive a teammate's task, approve it, and start a Session
+in a directory you configured. The relay server lives in a separate repository:
+[dsh-team-baton](https://github.com/Of-qinhai/dsh-team-baton).
+
+Public source does not connect to any server by default. You deploy the server
+yourself, or get your team's endpoint and shared secret from its administrator.
+
+## Requirements
+
+- DSH Desktop. Verified on Electron 44 / Node 24; other versions may change the
+  `sessionController` / `workspaceRegistry` / `uiWorkspace` interfaces used here.
+- A running `baton-server`, or your team's endpoint and secret.
+- Node 22+ only for the development tests and preview; the installed plugin uses
+  DSH's own React and needs no build.
+
+## Install
+
+The package ships a **safe placeholder** `cordis.patch.yml` (empty `serverUrl`),
+so the bundle can be installed before it is configured. Configure it through your
+DSH profile after installation.
+
+### 1. Put the team secret in place
+
+```sh
+mkdir -p ~/.config/baton
+printf '%s\n' '<team secret>' > ~/.config/baton/secret
+chmod 700 ~/.config/baton
+chmod 600 ~/.config/baton/secret
+```
+
+`secretFile` defaults to this path; `BATON_SECRET` in the environment takes
+precedence when non-empty.
+
+### 2. Install the plugin
+
+Paste the repository URL into the plugin manager's Git repository field (the
+dialog that shows **Git 仓库**), or clone and install the local directory:
+
+```sh
+git clone https://github.com/Of-qinhai/dsh-team-baton-client.git
+# then, in DSH:
+plugin_manager install_bundle target=/absolute/path/to/dsh-team-baton-client
+```
+
+The install requires approval.
+
+### 3. Configure in the profile patch
+
+Open the profile's `cordis.patch.yml`:
+
+- macOS/Linux: `~/.dsh/profiles/<profile>/cordis.patch.yml`
+- Windows: `%USERPROFILE%\.dsh\profiles\<profile>\cordis.patch.yml`
+
+Add a **complete override row** (the same id replaces the whole config, so keep
+`serverUrl`):
+
+```yaml
+- id: baton
+  name: '@ohmynpm/dsh-baton'
+  config:
+    serverUrl: wss://baton.example.com/ws
+    # secretFile: /absolute/path/to/secret   # defaults to ~/.config/baton/secret
+    displayName: Your name
+    environments:
+      - { key: frontend, label: Frontend, cwd: /absolute/path/to/web }
+      - { key: backend,  label: Backend,  cwd: /absolute/path/to/api }
+```
+
+Do not edit the copy under `node_modules`; it is replaced on reinstall.
+
+### 4. Restart and refresh
+
+Restart DSH, then refresh the page. The sidebar entry sits below Automation Tasks.
+
+A non-localhost `serverUrl` must use `wss://`; `secretFile` must be absolute and
+mode 0600. Never commit your endpoint, secret, or local paths.
+
+## Environments
+
+Each install configures its own directories visually: the folder button in the
+panel header opens **本机执行环境**. Add a key, a display label, and an absolute
+local directory per environment. The list is saved to
+`~/.dsh/baton/environments.json` (0600).
+
+Only the key and label are advertised to room members; absolute paths never leave
+the machine. A sender therefore picks an environment from the recipient's own
+advertised list, and the recipient still resolves it to its own directory. The
+`environments` block in the profile config is only the initial seed for a fresh
+install; once the visual editor saves, the local file is authoritative.
+
+## Panel
+
+The sidebar entry sits below Automation Tasks. Clicking it opens the inbox in the
+main area: rooms on the left, tasks in the middle, task detail on the right. Only
+**Accept and start** creates a Session and submits the brief. Declining only
+updates state. A `needs review` task can only be dismissed manually.
+
+The sender chooses an environment key; this install maps it to its own absolute
+`cwd`. Remote paths are never sent and there is no fallback directory.
+
+## Task visibility and layout
+
+Both inbox and sent items support **Delete** (move to the deleted-items tab),
+restore, and a separately confirmed permanent deletion. One participant's action
+does not remove the other participant's copy. After both permanently delete,
+the relay removes the live task/brief and retains only its ID and original expiry
+to prevent retry resurrection. The existing seven-day expiry remains in effect;
+older backups expire on their normal retention schedule. DSH sessions and messages
+are never deleted or resubmitted by any of these actions.
+
+The left navigation can collapse, and all three lists scroll within their pane,
+including short desktop windows and narrow screens. Directory configuration is
+validated and persisted locally, with only keys/labels advertised to room peers.
+Offline saves sync on reconnect; publication failures explicitly say that the
+local save succeeded but peers have not yet received the change.
+
+## Agent tools
+
+Only three tools are registered: `team_rooms`, `team_task_send`, and `team_tasks`.
+Approval is not exposed to the agent, and remote titles, briefs, and display names
+never enter the current Agent context.
+
+## Updates
+
+The package version is bumped for every release. Automatic update checks only
+work when the plugin is installed from an npm registry package:
+
+- **npm install**: the plugin manager can compare the installed version with the
+  registry and offer an update.
+- **Git URL or local directory**: there is no default registry source, so the
+  plugin manager shows "unable to check for updates"; reinstall the latest
+  commit or release tarball instead.
+
+This package is currently `private: true`, so it is not published to npm and a
+Git/local install cannot auto-check. Publishing requires setting `private` to
+`false`, choosing a reachable package name/registry, and bumping the version for
+each release.
+
+## Development
+
+```sh
+npm ci
+npm test          # Host, connection, checkpoint and local setup regressions
+npm run preview   # http://127.0.0.1:4371, in-memory sample data
+```
+
+`npm run test:flow` and `npm run test:integration` additionally need the Rust
+server checkout; see the comments in those scripts. Browser regression
+(`npm run test:client`) needs `playwright/test` and Chromium installed separately.
+`npm run test:tasks` additionally covers directory configuration, independent
+deletion/restoration, navigation collapse and 160-task scrolling at desktop and
+mobile sizes, using fixture data and the actual embedded React client.
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,135 @@
+# Baton DSH 插件
+
+[English](README.md) | 中文
+
+Baton 的 DSH 侧：接收队友的任务、人工确认后在你配置的目录里启动会话。
+中继服务端在独立仓库：[dsh-team-baton](https://github.com/Of-qinhai/dsh-team-baton)。
+
+公开源码默认不连接任何服务器。你需要自己部署服务端，或向团队管理员获取服务地址和共享密钥。
+
+## 要求
+
+- DSH Desktop。已在 Electron 44 / Node 24 验证；其他版本可能改变
+  `sessionController` / `workspaceRegistry` / `uiWorkspace` 的接口。
+- 一个运行中的 `baton-server`，或团队的服务地址和密钥。
+- Node 22+ 仅用于开发测试和预览；安装版复用 DSH 的 React，不需要构建。
+
+## 安装
+
+插件包自带一个**安全的占位** `cordis.patch.yml`（`serverUrl` 为空），所以可以先安装、
+再通过 DSH profile 配置，不会因为缺少 patch 文件安装失败。
+
+### 1. 放团队密钥
+
+```sh
+mkdir -p ~/.config/baton
+printf '%s\n' '<团队密钥>' > ~/.config/baton/secret
+chmod 700 ~/.config/baton
+chmod 600 ~/.config/baton/secret
+```
+
+`secretFile` 默认读这个路径；环境变量 `BATON_SECRET` 非空时优先。
+
+### 2. 安装插件
+
+在插件管理器的 Git 仓库输入框粘贴仓库地址（就是截图里显示「Git 仓库」的弹窗），
+或 clone 后安装本地目录：
+
+```sh
+git clone https://github.com/Of-qinhai/dsh-team-baton-client.git
+# 然后在 DSH 里：
+plugin_manager install_bundle target=/绝对路径/dsh-team-baton-client
+```
+
+安装需要批准。
+
+### 3. 在 profile patch 里配置
+
+打开 profile 的 `cordis.patch.yml`：
+
+- macOS/Linux：`~/.dsh/profiles/<profile>/cordis.patch.yml`
+- Windows：`%USERPROFILE%\.dsh\profiles\<profile>\cordis.patch.yml`
+
+加一条**完整覆盖行**（同 id 会替换整个 config，所以 `serverUrl` 必须一起写）：
+
+```yaml
+- id: baton
+  name: '@ohmynpm/dsh-baton'
+  config:
+    serverUrl: wss://baton.example.com/ws
+    # secretFile: /绝对路径/secret   # 默认 ~/.config/baton/secret
+    displayName: 你的名字
+    environments:
+      - { key: frontend, label: 前端, cwd: /绝对路径/前端 }
+      - { key: backend,  label: 后端, cwd: /绝对路径/后端 }
+```
+
+不要修改 `node_modules` 下的那份 patch，它会在重装时被替换。
+
+### 4. 重启并刷新
+
+重启 DSH，再刷新页面。侧边栏入口在「自动化任务」下面。
+
+非 localhost 的 `serverUrl` 必须用 `wss://`；`secretFile` 必须是绝对路径且权限 0600。
+永远不要提交服务地址、密钥或本机路径。
+
+## 执行环境
+
+每个安装自己可视化配置目录：点面板顶部的文件夹按钮打开「本机执行环境」，
+为每个环境填写 key、显示名称和本机绝对目录。配置保存在
+`~/.dsh/baton/environments.json`（0600）。
+
+只有 key 和名称会暴露给同房间成员，绝对路径不会离开本机。因此发送方是从
+**对方的**已公开环境列表里选择，接收方仍映射到自己的目录。profile 配置里的
+`environments` 只是新安装的初始种子；可视化编辑器保存后，以本机文件为准。
+
+保存时会验证目录存在并转换为规范化绝对路径。断线时可以保存，重连后上报；
+如果本机保存成功但上报失败，面板会明确提示，避免把“已保存”误认为“对方已收到”。
+
+## 任务删除与列表
+
+- 收件箱和已发出的任务均可首次删除，移入“已删除”；对方的列表和关联会话不受影响。
+- 在“已删除”中可以恢复，也可以二次确认永久删除。你确认后无法再恢复或审批该任务。
+- 只有双方都确认永久删除，服务端才清理在线数据库中的任务正文；保留最小的任务 ID/有效期，
+  避免网络重试重新创建已删除任务。原有七天过期策略继续生效，已有备份按保留周期过期。
+- 删除或恢复任务始终不会删除 DSH 会话，也不会重新提交消息。
+- 左侧导航支持折叠/展开，任务列表在收件箱、已发出的和已删除三个标签中独立滚动。
+
+## 面板
+
+侧边栏入口在「自动化任务」下面。点开后右侧主区域显示收件箱：左侧房间、中间任务、
+右侧详情。只有「接受并启动」才创建会话并提交 brief；拒绝只更新状态。
+`需核对` 只能人工确认后收起。
+
+发送方选择环境 key，本机把它映射到自己的绝对 `cwd`；不传远端路径，也没有默认回退目录。
+
+## Agent 工具
+
+只注册三个工具：`team_rooms`、`team_task_send`、`team_tasks`。
+审批入口不暴露给 Agent，远端标题、brief 和显示名不会进入当前 Agent 上下文。
+
+## 更新
+
+每次发布都会递增版本号。**只有从 npm registry 安装**时，插件管理器才能检查更新：
+
+- **npm 安装**：插件管理器可以比较本地版本和 registry 版本并提示更新。
+- **Git 地址或本地目录安装**：没有默认 registry 来源，所以会显示“无法检查更新”；
+  需要重新安装最新提交或 Release 包。
+
+当前包仍是 `private: true`，没有发布到 npm，所以 Git/本地安装不能自动检查。
+启用自动检查需要把 `private` 改为 `false`、选择可访问的包名/registry，并在每次发布递增版本号。
+
+## 开发
+
+```sh
+npm ci
+npm test          # 51 个单元测试
+npm run preview   # http://127.0.0.1:4371，内存示例数据
+```
+
+`npm run test:flow` / `npm run test:integration` 还需要 Rust 服务端源码；
+浏览器回归 `npm run test:client` 需要单独安装 `playwright/test` 和 Chromium。
+
+## 许可证
+
+[MIT](LICENSE)