@zhangfengshun/dsh-remote-ssh 2.4.2 → 2.4.3

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 本文件的版本号与 `package.json` 的 `version` 保持一致。每个版本对应一个 Cordis Package 快照（`pkg-N`）。
 
+## [2.4.3] — 适配 better-sidebar 0.19 新增端点（fs.rename / fs.remove）+ 版本兼容性核查
+### 新增
+- **拦截 better-sidebar 0.19 新增的 `fs.rename` / `fs.remove` 端点**（exact 路由从 4 条增至 6 条）：远程工作区的「重命名 / 删除」此前会落到本地镜像目录（0.19 之前 better-sidebar 没有这两个端点，操作走客户端 API，不存在该问题）。现在：
+  - 远程工作区 → 走 SSH（`mv -f --` / `rm -rf --`），语义对齐 better-sidebar（单个路径段校验、目标已存在返回 409、禁止操作工作区根），并失效相关读/列举缓存；
+  - 本地工作区 → 本地实现（不覆盖、lstat 判定符号链接、目录递归删除），契约与 better-sidebar 完全一致；
+  - 旧版 better-sidebar（无此端点）不调用这两个路由，注册无副作用。
+
+### 兼容性核查（重要）
+- **dsh-better-sidebar 0.19.0 / 0.19.1（以及 0.18.1）在当前 DSH Desktop（v2.0.9，DSH 0.1.5-rc.1）上主机半边无法加载**：其 `lib/index.js` 以**值**方式导入 `SessionLogOffset`（`import { SessionLogOffset } from "@deepseek-ai/dsh-session"`），而 DSH 2.0.9 面向插件的模块面只提供该符号的**类型**声明，运行时导入抛 `does not provide an export named 'SessionLogOffset'` → better-sidebar 主机半边（fs/git/terminal/jobs 等全部 API）整体失效，侧边栏文件页签因此回落到「这类内容还没有可用的查看方式。」
+- **已验证的版本矩阵**：`0.19.1`（导入该符号）、`0.19.0`（导入）、`0.18.1`（导入）→ 在 DSH 2.0.9 上不可用；`0.18.0`、`0.17.1`（不导入）→ 可用。本插件在 `0.18.0` 上逐点验证：`fs.tree/read/write/search` 返回形状、`betterSidebar` 服务与 `registerTab`、`/sidebar/upload` 上传拦截全部咬合。
+- 建议：在 better-sidebar 修复该导入（或 DSH 恢复该运行时导出）之前，desktop profile 使用 **dsh-better-sidebar@0.18.0**；本插件对 0.18/0.19 两套契约均已适配。
+
 ## [2.4.2] — 修复设置导航显示器图标「先齿轮后显示器」闪现
 ### 修复
 - **图标替换从防抖路径改为同步执行**：此前设置面板挂载后，显示器图标替换走 500ms 防抖定时器，用户会先看到半秒壳层默认齿轮再变成显示器图标。现在在 MutationObserver 回调里**同步原位替换**——回调是微任务、在浏览器绘制前执行，齿轮刚插入 DOM 就被换掉，**第一帧即最终图标**，无闪现。

package/README.md

@@ -32,12 +32,14 @@
 ## 安装
 
 ```bash
-dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.1
+dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.3
 ```
 
 > 安装后需**重启 DSH**。`@zhangfengshun/dsh-remote-ssh` 必须在 bundles 列表中排在 `dsh-better-sidebar` **之后**。
 >
-> 内置「文件」页签的 SSH 直读依赖 **dsh-better-sidebar ≥ 0.15** 的文件 API（`/sidebar/api/fs.*` 端点），请勿使用更早版本；当前已逐点验证至 **dsh-better-sidebar 0.19.0** 与 **DSH 0.1.5-rc.1**（主机服务 / settings / tools / slot / 上传下载拦截全部咬合）。
+> 内置「文件」页签的 SSH 直读依赖 **dsh-better-sidebar ≥ 0.15** 的文件 API（`/sidebar/api/fs.*` 端点），请勿使用更早版本。
+>
+> ⚠️ **版本兼容性（2026-09 实测）**：`dsh-better-sidebar` **0.18.1 / 0.19.0 / 0.19.1** 在 DSH Desktop v2.0.9（DSH 0.1.5-rc.1）上**主机半边无法加载**——它们以值方式导入 `SessionLogOffset`，而当前 DSH 面向插件的模块面只提供该类型声明，导入直接抛错，导致侧边栏文件页签显示「这类内容还没有可用的查看方式。」。请使用 **0.18.0**（本插件已逐点验证）直到上游修复；本插件对 0.18（4 端点）与 0.19（6 端点，含 `fs.rename`/`fs.remove`）两套契约均已适配。
 
 ## 使用
 
@@ -77,7 +79,7 @@ dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.1
 
 ## 原理
 
-插件注册 4 个 exact 路由（`/sidebar/api/fs.tree`、`fs.read`、`fs.write`、`fs.search`），在 better-sidebar 的 prefix 路由之前拦截。会话 cwd 含 `.remote-ssh.json` 时走 SSH，否则走本地 fs。客户端看到的是本地镜像路径，Host 自动转换为远程路径——对客户端完全透明。
+插件注册 6 个 exact 路由（`/sidebar/api/fs.tree`、`fs.read`、`fs.write`、`fs.search`，以及 better-sidebar 0.19 新增的 `fs.rename`、`fs.remove`），在 better-sidebar 的 prefix 路由之前拦截。会话 cwd 含 `.remote-ssh.json` 时走 SSH，否则走本地 fs。客户端看到的是本地镜像路径，Host 自动转换为远程路径——对客户端完全透明。
 
 远程读取采用**单往返合并读**：一条池化命令同时返回 `size/mtime` 帧与文件内容（文本类扩展名优先 raw 直传，字节长 + U+FFFD 双校验失败自动回退 base64，结果逐字节一致）；配合主机侧结果缓存与变更失效（见下节）。
 

package/README_EN.md

@@ -32,12 +32,14 @@ A **DSH** plugin like **VSCode Remote-SSH**: connect to remote HPC / servers via
 ## Installation
 
 ```bash
-dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.1
+dsh plugin --profile <name> add @zhangfengshun/dsh-remote-ssh@2.4.3
 ```
 
 > **Restart DSH** after installation. `@zhangfengshun/dsh-remote-ssh` must come **after** `dsh-better-sidebar` in the bundles list.
 >
-> The built-in **Files** tab SSH interception relies on the file API of **dsh-better-sidebar ≥ 0.15** (`/sidebar/api/fs.*` endpoints) — do not use older versions; verified point-by-point against **dsh-better-sidebar 0.19.0** and **DSH 0.1.5-rc.1** (host services / settings / tools / slots / upload & download interception all compatible).
+> The built-in **Files** tab SSH interception relies on the file API of **dsh-better-sidebar ≥ 0.15** (`/sidebar/api/fs.*` endpoints) — do not use older versions.
+>
+> ⚠️ **Version compatibility (measured 2026-09)**: `dsh-better-sidebar` **0.18.1 / 0.19.0 / 0.19.1** cannot load their host half on DSH Desktop v2.0.9 (DSH 0.1.5-rc.1) — they value-import `SessionLogOffset`, which the current DSH plugin-facing module surface exposes only as a type, so the import throws and the sidebar Files tab falls back to "Nothing here can view this kind of content yet." Use **0.18.0** (verified point-by-point) until upstream fixes it; this plugin supports both contracts (4 endpoints on 0.18, 6 including `fs.rename`/`fs.remove` on 0.19).
 
 ## Usage
 
@@ -77,7 +79,7 @@ All SSH commands default to a **120-second** timeout (issue #5): a hung remote c
 
 ## How It Works
 
-The plugin registers 4 exact routes (`/sidebar/api/fs.tree`, `fs.read`, `fs.write`, `fs.search`) that intercept better-sidebar's prefix route. When the session cwd contains `.remote-ssh.json`, requests go through SSH; otherwise local fs. The client sees local mirror paths — the Host transparently translates them to remote paths.
+The plugin registers 6 exact routes (`/sidebar/api/fs.tree`, `fs.read`, `fs.write`, `fs.search`, plus `fs.rename` and `fs.remove` added by better-sidebar 0.19) that intercept better-sidebar's prefix route. When the session cwd contains `.remote-ssh.json`, requests go through SSH; otherwise local fs. The client sees local mirror paths — the Host transparently translates them to remote paths.
 
 Remote reads use a **single-roundtrip merged read**: one pooled command returns the `size/mtime` frame plus the file content (text extensions prefer raw transfer with byte-length + U+FFFD validation and automatic base64 fallback — results are byte-identical), combined with host-side result caching and change invalidation (see below).
 

package/lib/index.js

@@ -10,10 +10,10 @@
  */
 import z from "schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { mkdir, rm, writeFile, readFile, opendir, stat, open, rename, readdir } from "node:fs/promises";
+import { mkdir, rm, writeFile, readFile, opendir, stat, open, rename, readdir, lstat } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, dirname } from "node:path";
+import { join, dirname, basename } from "node:path";
 
 /** Plugin identity for cordis.yml rows. */
 const name = "@zhangfengshun/dsh-remote-ssh";
@@ -2139,6 +2139,28 @@ function apply(ctx, config) {
     return { ok: true };
   }
 
+  // 本地 rename（对齐 better-sidebar 0.19 的 fs.rename 契约：单段名、不覆盖、返回新绝对路径）
+  async function localRenameEntry(path, name) {
+    if (!path) return { ok: false, error: "path 为必填项" };
+    if (!name || name === "." || name === ".." || /[\\/]/.test(name)) {
+      return { ok: false, error: "name 必须是单个路径段" };
+    }
+    if (basename(path) === name) return { ok: true, path: path };
+    const dest = join(dirname(path), name);
+    if (existsSync(dest)) return { ok: false, error: "\"" + name + "\" 已存在" };
+    await rename(path, dest);
+    return { ok: true, path: dest };
+  }
+
+  // 本地 remove（文件 unlink / 目录递归；lstat 判定，符号链接只删链接本身）
+  async function localRemoveEntry(path) {
+    if (!path) return { ok: false, error: "path 为必填项" };
+    const st = await lstat(path);
+    if (st.isDirectory()) await rm(path, { recursive: true, force: true });
+    else await rm(path, { force: true });
+    return { ok: true, path: path };
+  }
+
   // 本地 searchFiles（简单递归文件名搜索）
   async function localSearchFiles(root, query) {
     if (!query) return { entries: [] };
@@ -2247,6 +2269,46 @@ function apply(ctx, config) {
           result = { entries: (r.files || []).map(function (f) {
             return { path: join(remoteBase, f), isDir: false };
           }), truncated: !!r.truncated };
+        } else if (method === "fs.rename") {
+          // better-sidebar 0.19 新增端点：重命名必须落在远端，绝不能让本地镜像目录被改。
+          const localPath = payload.path || "";
+          const name = String(payload.name || "");
+          if (!localPath) { writeJson(res, 400, { ok: false, error: { code: "bad-request", message: "path is required" } }); return; }
+          if (!name || name === "." || name === ".." || /[\\/]/.test(name)) {
+            writeJson(res, 400, { ok: false, error: { code: "bad-request", message: "name must be a single path segment" } }); return;
+          }
+          const srcRemote = localToRemote(localPath, remoteBase, remoteInfo.remotePath);
+          if (srcRemote === remoteInfo.remotePath) {
+            writeJson(res, 400, { ok: false, error: { code: "fs-error", message: "cannot rename the workspace root" } }); return;
+          }
+          const dstRemote = posixDirname(srcRemote) + "/" + name;
+          const exists = await runPooled(profile, "test -e " + shellQuotePath(dstRemote), undefined, 4096);
+          if (exists.ok) {
+            writeJson(res, 409, { ok: false, error: { code: "fs-error", message: "\"" + name + "\" already exists" } }); return;
+          }
+          const mv = await runPooled(profile, "mv -f -- " + shellQuotePath(srcRemote) + " " + shellQuotePath(dstRemote), undefined, 4096);
+          if (!mv.ok) {
+            writeJson(res, 400, { ok: false, error: { code: "fs-error", message: String(mv.stderr || mv.error || "rename failed").trim().slice(0, 500) } }); return;
+          }
+          invalidateRemoteCaches(profile, srcRemote, { subtree: true });
+          invalidateRemoteCaches(profile, dstRemote, { subtree: true });
+          result = { path: join(dirname(localPath), name) };
+        } else if (method === "fs.remove") {
+          // better-sidebar 0.19 新增端点：删除同样必须在远端执行（本地镜像仅供注册工作区）。
+          const localPath = payload.path || "";
+          if (!localPath) { writeJson(res, 400, { ok: false, error: { code: "bad-request", message: "path is required" } }); return; }
+          const srcRemote = localToRemote(localPath, remoteBase, remoteInfo.remotePath);
+          if (srcRemote === remoteInfo.remotePath) {
+            writeJson(res, 400, { ok: false, error: { code: "fs-error", message: "cannot remove the workspace root" } }); return;
+          }
+          const rmv = await runPooled(profile, "rm -rf -- " + shellQuotePath(srcRemote), undefined, 4096);
+          if (!rmv.ok) {
+            writeJson(res, 400, { ok: false, error: { code: "fs-error", message: String(rmv.stderr || rmv.error || "remove failed").trim().slice(0, 500) } }); return;
+          }
+          // 本地镜像若有同名副本一并清理（镜像不是事实来源，失败可忽略）。
+          try { await rm(localPath, { recursive: true, force: true }); } catch (e) {}
+          invalidateRemoteCaches(profile, srcRemote, { subtree: true });
+          result = { path: localPath };
         } else {
           writeJson(res, 404, { ok: false, error: { code: "not-found", message: "unknown method " + method } }); return;
         }
@@ -2261,6 +2323,10 @@ function apply(ctx, config) {
           result = await localWriteFile(payload.path, payload.content || "");
         } else if (method === "fs.search") {
           result = await localSearchFiles(sessionCwd, payload.query || "");
+        } else if (method === "fs.rename") {
+          result = await localRenameEntry(payload.path, String(payload.name || ""));
+        } else if (method === "fs.remove") {
+          result = await localRemoveEntry(payload.path);
         } else {
           writeJson(res, 404, { ok: false, error: { code: "not-found", message: "unknown method " + method } }); return;
         }
@@ -2275,7 +2341,9 @@ function apply(ctx, config) {
     }
   }
 
-  ["fs.tree", "fs.read", "fs.write", "fs.search"].forEach(function (m) {
+  // fs.rename / fs.remove 是 better-sidebar 0.19 新增端点：旧版客户端不会调用，
+  // 注册它们对旧版无副作用；新版下远程工作区的重命名/删除才不会落到本地镜像。
+  ["fs.tree", "fs.read", "fs.write", "fs.search", "fs.rename", "fs.remove"].forEach(function (m) {
     ctx.effect(() => ctx.webServer.register({
       kind: "exact",
       path: "/sidebar/api/" + m,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhangfengshun/dsh-remote-ssh",
-  "version": "2.4.2",
+  "version": "2.4.3",
   "description": "DSH web plugin: VSCode Remote-SSH-like remote development (SSH to supercomputers/servers, remote workspace, file explorer, integrated terminal), integrated with dsh-better-sidebar and DSH settings.",
   "keywords": [
     "dsh",