dsh-remote-workspaces 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-remote-workspaces 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

@@ -0,0 +1,149 @@
+# dsh-remote-workspaces
+
+English | [中文](README.zh.md)
+
+Open folders on remote hosts over SSH as first-class [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) workspaces.
+
+## What it does
+
+Once a remote directory is opened as a workspace, the agent's file tools (`read` / `write` / `edit` / `grep` / `glob`) and shell commands land **directly on the remote host** over SSH, not a local mirror. There is no mirroring and no sync: every operation is executed remotely in real time, and local workspaces keep their full sandbox behavior.
+
+## Features
+
+- **Open a remote folder as a workspace** — browse the remote filesystem, pick a directory, and the harness adopts it as if it were local. All I/O routes to the remote.
+- **Multi-machine registry** — add, edit, and remove SSH hosts (alias, host, port, user, key or password). Credentials are AES-256-GCM encrypted at rest and never sent back to the browser.
+- **`~/.ssh/config` import** — list configured aliases and pre-fill the connection form.
+- **Connection test** — verify a host before using it.
+- **Transparent tool routing** — `read`/`write`/`edit` go through SFTP, `grep`/`glob` run ripgrep on the remote, and `bash`/`pwsh` commands execute over ssh2 exec. Local paths keep the harness's own sandbox.
+- **Policy-aware remote mutations** — the harness file policy applies to remote workspaces too: `read-only` denies `write`/`edit` and remote shell commands, `workspace-write` confines `write`/`edit` to the remote workspace root (plus `/tmp`) while remote shell commands need a `danger-full-access` approval, and `danger-full-access` delegates to the SSH account.
+
+## How it works
+
+The bundle has a host half and a browser half:
+
+- **Host** (`src/index.js`) — an SSH/SFTP transport built on [`ssh2`](https://github.com/mscdex/ssh2), an encrypted machine store, the routing filesystem (`ctx.fs`) and shell (`ctx.shell`) providers, remote-aware `grep`/`glob` tools, and a `remoteWorkspaces` Remote namespace exposed through Typert.
+- **Browser** (`src/client.js`) — a "Remote Workspaces" settings section (hosts grouped by machine) and a workspace-add picker.
+
+Opening a remote directory creates an **anchor**: a real but empty local directory adopted by the harness as the workspace identity, plus a metadata file recording its remote origin. A registry (`anchors.json`) maps that anchor to its remote host and path, and every file/command operation is routed to the remote by that lookup:
+
+```
+$DSH_HOME/remote-workspaces/
+├── machines.json              # host registry (credentials encrypted at rest)
+├── anchors.json               # anchor → remote origin routing registry
+└── <host>-<user>-<port>/      # per-host anchors
+    └── <encoded-path>/        # one empty anchor per remote path
+    │   └── .dsh-remote-meta.json
+```
+
+The full remote path is encoded into the anchor name (path separators and Windows-illegal characters become `--`), so `/home/test` and `/data/test` map to distinct directories (`home--test` vs `data--test`).
+
+## Requirements
+
+- A DeepSeek Harness installation (the plugin resolves its host services at runtime).
+- Node.js ≥ 18 (the harness itself runs on Node 22+).
+- `ssh2` is the only transport dependency; no external `ssh` binary is needed.
+- The remote host needs `rg` (ripgrep) for `grep`/`glob`, and `sha256sum` (or `shasum`) for post-write verification — both degrade gracefully when absent.
+
+## Installation
+
+Install from this repository:
+
+```sh
+dsh plugin --profile web add github:januory/dsh-remote-workspaces
+```
+
+Once published to npm, install the released package directly:
+
+```sh
+dsh plugin --profile web add dsh-remote-workspaces
+```
+
+Install from source:
+
+```sh
+git clone https://github.com/januory/dsh-remote-workspaces.git
+
+cd dsh-remote-workspaces
+
+pnpm install  # install the ssh2 transport dependency
+
+dsh plugin --profile web add .
+```
+
+Remove it with:
+
+```sh
+dsh plugin --profile web remove dsh-remote-workspaces
+```
+
+> Maintainer note: the npm package name is now `dsh-remote-workspaces` (the early git install used `remote-workspaces`); older installs must first run `dsh plugin --profile <name> remove remote-workspaces`, then install under the new name.
+
+## Usage
+
+1. Open **Settings → Remote Workspaces**.
+2. Add an SSH host (or import one from `~/.ssh/config`), then **Test connection**.
+3. In the workspace-add flow, choose a remote host, browse to a directory, and open it. The harness adopts the empty anchor as a workspace, and reads, writes, searches, and shell commands all execute on the remote.
+
+## Remote API
+
+The host exposes a `remoteWorkspaces` Remote namespace (Typert) with these invocations: `listMachines`, `saveMachine`, `deleteMachine`, `listSshAliases`, `sshAliasDetail`, `testConnection`, `listRemoteDir`, and `openRemoteWorkspace`.
+
+## Repository structure
+
+```
+src/                          # the DSH bundle source
+  index.js                    # host entry (routing fs/shell, search tools, Remote namespace)
+  client.js                   # browser entry (settings UI + picker)
+  transport.js                # ssh2 transport (SshClient, exec, sha256)
+  routing-fs.js               # routing filesystem (remote SFTP / local fence)
+  fs-sftp.js                  # SFTP filesystem backend
+  local-backend.js            # local filesystem backend
+  containment.js              # local sandbox containment fence
+  shell-exec.js               # SshShellExecutor (remote ssh2 exec / local subprocess)
+  search.js                   # remote-aware grep/glob tools
+  anchor.js                   # local anchor layout (empty dir + meta)
+  registry.js                 # anchors.json routing registry
+  machine-store.js            # host registry (encrypted at rest)
+  ssh-config.js               # ~/.ssh/config parser
+  ssh-uri.js                  # ssh:// URI parsing + detection
+  errors.js                   # error codes
+cordis.patch.yml              # DSH bundle patch (swap in the routing providers)
+package.json                  # package + dsh manifest
+test/                         # unit + integration tests
+```
+
+## Testing
+
+Pure unit tests (no host required) run anywhere:
+
+```sh
+pnpm test
+```
+
+The integration suite exercises a real SSH host and expects the machine registry to be configured first (it targets the first machine in the registry, or the one aliased `test`):
+
+```sh
+pnpm test:integration
+```
+
+## Publishing (maintainers)
+
+Releases are fully manual with **zero input**: the version comes straight from `package.json` — commit the new `version` on `main` first, then GitHub Actions → **release** → **Run workflow**. The workflow runs the unit tests (`npm test`), guards that the `v<version>` tag does not exist yet (prevents duplicate releases), publishes to npm with provenance (`npm publish --provenance`), creates and pushes the `v<version>` tag, and creates a GitHub Release with `--generate-notes`.
+
+Prerequisites: configure an `NPM_TOKEN` secret in **Settings → Secrets and variables → Actions** (an npm automation token, or a granular token with publish permission on the package); the publishing account must be the npm user owning the package name.
+
+Equivalent manual flow:
+
+```sh
+npm login
+
+npm publish --provenance
+
+git tag "v$(node -p \"require('./package.json').version\")"
+
+git push origin --tags
+```
+
+## License
+
+[MIT](./LICENSE)

package/README.zh.md

@@ -0,0 +1,151 @@
+# dsh-remote-workspaces
+
+[English](README.md) | 中文
+
+通过 SSH 把远程主机上的目录，像打开本地文件夹一样，作为[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的工作区打开工作。
+
+## 它做了什么
+
+远程目录一旦被打开为工作区，agent 的文件工具（`read` / `write` / `edit` /`grep` / `glob`）和 shell 命令都会**直接落到远主机**上执行，而不是本地镜像。这里没有镜像、没有同步：每个操作都在远端实时执行，而本地工作区仍保留 harness 自身的完整沙箱行为。
+
+## 功能特性
+
+- **把远程目录当作工作区打开** —— 浏览远程文件系统、选中目录，harness 会像对待本地目录一样接纳它；所有 I/O 都路由到远端。
+- **多主机注册表** —— 增删改 SSH 主机（别名 / 主机 / 端口 / 用户 / 密钥或密码）。凭据在本地用 AES-256-GCM 加密落盘，绝不会回传到浏览器。
+- **`~/.ssh/config` 导入** —— 列出已配置的别名并自动填充连接表单。
+- **连接测试** —— 使用前先验证主机连通性。
+- **透明的工具路由** —— `read`/`write`/`edit` 走 SFTP，`grep`/`glob` 在远端跑ripgrep，`bash`/`pwsh` 命令通过 ssh2 exec 执行。本地路径沿用 harness 自身的沙箱。
+- **感知权限策略的远端写操作** —— harness 的文件策略同样作用于远程工作区：`read-only` 会拒绝 `write`/`edit` 和远程 shell 命令，`workspace-write` 把 `write`/`edit` 限制在远程工作区根目录（以及 `/tmp`）内、而远程 shell 命令需经 `danger-full-access` 审批后放行，`danger-full-access` 则交由 SSH 账号自身权限决定。
+
+## 工作原理
+
+bundle 分为宿主机侧（host）和浏览器侧（browser）两半：
+
+- **Host**（`src/index.js`）—— 基于
+  [`ssh2`](https://github.com/mscdex/ssh2) 的 SSH/SFTP 传输、加密主机存储、分流文件系统（`ctx.fs`）与 shell（`ctx.shell`）provider、远程感知的`grep`/`glob` 工具，以及通过 Typert 暴露的 `remoteWorkspaces` Remote 命名空间。
+- **Browser**（`src/client.js`）—— “远程工作区”设置页（按主机分组）以及一个“添加工作区”的选择器。
+
+打开远程目录会创建一个**锚点（anchor）**：一个被 harness 接纳为工作区身份的真实但为空的本地目录，外加一个记录其远程来源的元数据文件。注册表（`anchors.json`）把该锚点映射到远程主机与路径，所有文件/命令操作都据此查表路由到远端：
+
+```
+$DSH_HOME/remote-workspaces/
+├── machines.json              # 主机注册表（凭据加密落盘）
+├── anchors.json               # 锚点 → 远程来源 路由注册表
+└── <host>-<user>-<port>/      # 每台主机的锚点
+    └── <encoded-path>/        # 每个远程路径对应一个空锚点
+    │   └── .dsh-remote-meta.json
+```
+
+远程完整路径会被编码进锚点目录名（路径分隔符和 Windows 非法字符变成 `--`），因此 `/home/test` 和 `/data/test` 会落到不同的目录（`home--test` vs `data--test`）。
+
+## 环境要求
+
+- 一个 DeepSeek Harness 安装（插件在运行时解析其宿主服务）。
+- Node.js ≥ 18（harness 本身运行在 Node 22+）。
+- `ssh2` 是唯一的传输依赖；不需要外部 `ssh` 命令。
+- 远端主机需要 `rg`（ripgrep）以支持 `grep`/`glob`，以及 `sha256sum`（或`shasum`）用于写入后校验——二者缺失时都会优雅降级。
+
+## 安装
+
+从本仓库在线安装：
+
+```sh
+dsh plugin --profile web add github:januory/dsh-remote-workspaces
+```
+
+发布到 npm 后，也可以直接安装已发布的包：
+
+```sh
+dsh plugin --profile web add dsh-remote-workspaces
+```
+
+从源码安装：
+
+```sh
+git clone https://github.com/januory/dsh-remote-workspaces.git
+
+cd dsh-remote-workspaces
+
+pnpm install  # 安装 ssh2 传输依赖
+
+dsh plugin --profile web add .
+```
+
+卸载：
+
+```sh
+dsh plugin --profile web remove dsh-remote-workspaces
+```
+
+> 维护者注：npm 包名现为 `dsh-remote-workspaces`（早期 git 安装时的包名是 `remote-workspaces`）；旧安装请先 `dsh plugin --profile <name> remove remote-workspaces`，再按新名安装。
+
+## 使用
+
+1. 打开 **设置 → 远程工作区**。
+2. 添加一台 SSH 主机（或从 `~/.ssh/config` 导入），然后点 **测试连接**。
+3. 在“添加工作区”流程里选择远程主机、浏览到某个目录并打开。harness 会把空锚点接纳为工作区，之后的读取、写入、搜索和 shell 命令都在远端执行。
+
+## Remote API
+
+宿主通过 Typert 暴露 `remoteWorkspaces` Remote 命名空间，包含这些调用：
+`listMachines`、`saveMachine`、`deleteMachine`、`listSshAliases`、`sshAliasDetail`、`testConnection`、`listRemoteDir`、`openRemoteWorkspace`。
+
+## 目录结构
+
+```
+src/                          # DSH bundle 源码
+  index.js                    # 宿主入口（分流 fs/shell、搜索工具、Remote 命名空间）
+  client.js                   # 浏览器入口（设置页 UI + 选择器）
+  transport.js                # ssh2 传输（SshClient、exec、sha256）
+  routing-fs.js               # 分流文件系统（远端 SFTP / 本地围栏）
+  fs-sftp.js                  # SFTP 文件系统后端
+  local-backend.js            # 本地文件系统后端
+  containment.js              # 本地沙箱围栏
+  shell-exec.js               # SshShellExecutor（远端 ssh2 exec / 本地 subprocess）
+  search.js                   # 远程感知的 grep/glob 工具
+  anchor.js                   # 本地锚点布局（空目录 + 元数据）
+  registry.js                 # anchors.json 路由注册表
+  machine-store.js            # 主机注册表（加密落盘）
+  ssh-config.js               # ~/.ssh/config 解析
+  ssh-uri.js                  # ssh:// URI 解析与识别
+  errors.js                   # 错误码
+cordis.patch.yml              # DSH bundle patch（换入分流 provider）
+package.json                  # 包 + dsh 清单
+test/                         # 单元 + 集成测试
+```
+
+## 测试
+
+纯单元测试（无需任何主机）可在任意环境运行：
+
+```sh
+pnpm test
+```
+
+集成测试需要访问真实 SSH 主机，且需先配置好主机注册表（默认使用注册表里的第一台主机，或别名为 `test` 的那台）：
+
+```sh
+pnpm test:integration
+```
+
+## 发布（维护者）
+
+发布完全手动触发、**零输入**：版本号直接取自 `package.json`，发布前先在 `main` 上提交改好的 `version`，然后 GitHub Actions → **release** → **Run workflow** 即可。工作流会自动执行：跑单元测试（`npm test`）→ 校验 `v<version>` tag 尚未存在（防止重复发布）→ `npm publish`（带 provenance）→ 打 `v<version>` tag 并推送 → 用 `--generate-notes` 创建 GitHub Release。
+
+前提：在仓库 **Settings → Secrets and variables → Actions** 中配置名为 `NPM_TOKEN` 的 secret（npm automation token，或对该包有 publish 权限的 granular token）；发布账号须是持有该包名的 npm 用户。
+
+等价的手工流程：
+
+```sh
+npm login
+
+npm publish --provenance
+
+git tag "v$(node -p \"require('./package.json').version\")"
+
+git push origin --tags
+```
+
+## 开源协议
+
+[MIT](./LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,25 @@
+# SSH remote workspace bundle layer.
+#
+# the host half (mounted at the bare package name) provides the routing
+# `ctx.fs` and `ctx.shell` in addition to `ctx.sshClient` and the
+# `remoteWorkspaces` Remote namespace. The base sandbox providers are disabled
+# here so the plugin's routing providers (local half sandboxed via
+# `ctx.sandboxPolicy`/`ctx.sandbox`/`ctx.subprocess`, remote half SFTP/ssh2)
+# register without a duplicate-service throw.
+
+- id: fs-sandbox
+  name: '@deepseek-ai/dsh-fs-sandbox'
+  disabled: true
+- id: bash-sandbox
+  name: '@deepseek-ai/dsh-bash-sandbox'
+  disabled: true
+- id: pwsh-sandbox
+  name: '@deepseek-ai/dsh-pwsh-sandbox'
+  disabled: true
+- id: tool-fs-search
+  name: '@deepseek-ai/dsh-tool-fs-search'
+  disabled: true
+
+- insert:
+    - id: dsh-remote-workspaces
+      name: 'dsh-remote-workspaces'

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "dsh-remote-workspaces",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Open folders on remote hosts over SSH as DeepSeek Harness workspaces — a non-invasive DSH bundle.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/januory/dsh-remote-workspaces.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js"
+  },
+  "files": [
+    "src",
+    "cordis.patch.yml"
+  ],
+  "scripts": {
+    "test": "node test/unit-anchor-path.mjs && node test/unit-secrets-encryption.mjs && node test/unit-fs.mjs && node test/unit-shell.mjs && node test/unit-routing.mjs && node test/unit-remote-policy.mjs && node test/unit-search-registration.mjs",
+    "test:integration": "node test/integration-remote.mjs"
+  },
+  "dependencies": {
+    "ssh2": "^1.17.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-api-remotes"
+      ],
+      "platform": "web"
+    }
+  }
+}

package/src/anchor.js

@@ -0,0 +1,67 @@
+/**
+ * Local anchor of a remote workspace — the "open a remote folder as a DSH
+ * workspace" half.
+ *
+ * An anchor is a plain EMPTY local directory under
+ * `<dsh-home>/remote-workspaces/<host>-<user>-<port>/<encoded-path>` plus a
+ * `.dsh-remote-meta.json` describing its remote origin. Because it is a real
+ * local directory, `fs.realpath` succeeds and the harness adopts it through
+ * `ctx.workspaceRegistry.create` with zero core modification — but it holds NO
+ * file content: all file and command I/O is routed straight to the remote over
+ * SSH (see registry.js / routing-fs.js / shell-exec.js).
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { machinesRoot } from './machine-store.js'
+
+/** Root holding every remote host's anchors (alongside machines.json). */
+export function remoteWorkspacesRoot() {
+  return join(machinesRoot(), 'remote-workspaces')
+}
+
+/** Per-machine anchor root: `<dsh-home>/remote-workspaces/<host>-<user>-<port>`. */
+export function anchorRootFor(machine) {
+  const m = machine ?? {}
+  const tag = [m.host, m.user, m.port]
+    .filter((x) => x !== null && x !== undefined && x !== '')
+    .join('-')
+    .replace(/[^a-zA-Z0-9._-]/g, '_') || 'host'
+  return join(remoteWorkspacesRoot(), tag)
+}
+
+function safeBase(name) {
+  const base = String(name || '')
+    .replace(/[\\/:*?"<>|]+/g, '--') // path separators + Windows-illegal chars → '--'
+    .replace(/^--+|--+$/g, '')       // trim leading/trailing separators
+  return base === '' || base === '.' || base === '..' ? 'workspace' : base
+}
+
+/**
+ * Local anchor dir for a specific remote path (idempotent). The FULL remote
+ * path is encoded (not just its basename), so two different directories that
+ * share a basename — e.g. `/home/test` vs `/data/test` — land in distinct
+ * local dirs (`home--test` vs `data--test`) instead of colliding on `test`.
+ */
+export function anchorDirFor(machine, remotePath) {
+  const rel = String(remotePath || '').replace(/^\/+/, '')
+  return join(anchorRootFor(machine), safeBase(rel))
+}
+
+/** Create the anchor dir and stamp its remote-origin metadata. */
+export function ensureAnchor(machine, remotePath) {
+  const dir = anchorDirFor(machine, remotePath)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(
+    join(dir, '.dsh-remote-meta.json'),
+    JSON.stringify({
+      host: machine?.host ?? null,
+      port: machine?.port ?? null,
+      username: machine?.user ?? null,
+      remotePath,
+      createdAt: new Date().toISOString(),
+    }, null, 2) + '\n',
+    'utf8',
+  )
+  return dir
+}