@reed-io/dsh-workspace-move 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0
+
+- Move a workspace folder, its tree, its nested workspace registrations and its
+  sessions to a new location from the workspace context menu.
+- Rename the workspace by giving the folder a new name at the destination.
+- Rewrite session logs in place (header `cwd` only) so history and titles survive
+  byte for byte.
+- Refuse moves while any of the workspace's sessions is running, on destination
+  collisions, and on names this platform rejects.
+- Roll a failed move back: folder, registrations and sessions return to where they
+  were.
+- Undo the last move of the current run from the toast or the workspace menu.
+- Expose the same engine as the `move_workspace` agent tool.
+- Chinese and English UI.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 reed-io
+
+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,108 @@
-# Temporary Holding Version
+# @reed-io/dsh-workspace-move
 
-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.
+Move a DeepSeek Harness workspace — the folder itself, everything inside it, the
+workspaces registered inside it, and the sessions stored for it — to another
+place on disk, from the workspace menu. It behaves like `mv`: one target path, one
+atomic result. Changing the folder name renames the workspace at the same time.
+
+## What a move carries
+
+| Carried with the workspace | How |
+| --- | --- |
+| The workspace folder and its whole tree | One rename on the same volume; copy, verify, then delete the source across volumes. |
+| Workspaces registered inside that folder | Their registered paths are rewritten to follow the folder. Registrations, titles and session lists are kept. |
+| Sessions listed in the workspace | Each session log moves to the destination project directory and its stored `cwd` header is rewritten in place, so history and titles are kept byte for byte. |
+| The workspace title | Only when the moving folder also renames the workspace and the title was still the folder name. |
+
+Nothing else moves. The source folder is deleted only when the move emptied it,
+and its parent folder is never touched.
+
+## Use it
+
+Right-click a workspace in the sidebar (or use its `…` button) and choose
+**Move workspace…**. Pick the destination folder in the built-in browser, type
+the folder name the workspace should have there, review what travels with it, and
+confirm.
+
+A move is refused, with a reason, when:
+
+- a workspace folder already exists at the destination — pick another name;
+- the destination is inside the workspace, or the workspace is inside the
+  destination's own path;
+- any of the sessions still has work running — stop them first;
+- the name is not a legal folder name on this platform.
+
+After a successful move the toast offers **Undo**, and the workspace menu offers
+**Undo last move** while the move is still the most recent one of this run. Undo
+is kept in memory only: it lasts until DeepSeek Harness restarts.
+
+A move either completes or fails as a whole. If any step fails, the plugin rolls
+back the folder, the registrations and every session it had already touched, and
+reports the failure.
+
+## Agent tool
+
+The same engine is one tool, so an agent can do it too:
+
+```text
+move_workspace(workspaceId, targetParent, folderName?)
+```
+
+`folderName` defaults to the current folder name. The tool reports the final
+destination, how many sessions and nested workspaces came along, and whether the
+move can still be undone.
+
+## Behaviour notes
+
+- The move runs in the Host process, which owns both the workspace registry and
+  the session store; the browser only drives it.
+- Sessions are rewritten in place: only the compressed header frame carrying
+  `cwd` is re-encoded, every event frame is copied byte for byte.
+- A moved session is re-attached to its workspace after its log has landed at the
+  new path, so the workspace keeps its session order.
+- Running DeepSeek Harness does not need a restart after a move for the moved
+  sessions to be usable; a session that is itself currently running cannot be
+  moved, which the running-work check enforces.
+- Developed and verified on Windows first. The path handling, volume detection
+  and folder-name rules are platform-aware, so macOS and Linux use the same code
+  path — with the native shared-folder case handled by the copy-and-verify branch.
+
+## Requirements
+
+- DeepSeek Harness `>=0.2.0-rc.1 <0.3.0-0`
+- Node `^22.19.0 || >=24.0.0`
+- A local (owner) desktop session: the destination dialog talks to the Host over a
+  loopback-only route.
+
+## Install
+
+Requires a running DeepSeek Harness. Replace `desktop` with the profile you use
+(`web`, `desktop`, …).
+
+```bash
+dsh plugin --profile desktop add @reed-io/dsh-workspace-move@latest
+```
+
+Or add the bundle to a profile's `dsh.profile.bundles` and restart DeepSeek
+Harness. After installing, reload the page (`Ctrl+R`) so the sidebar picks up the
+new menu entries.
+
+## Development
+
+```bash
+npm run build     # src/client.js -> lib/client.js (browser bundle)
+npm run check     # build, then verify the client bundle contract and containment
+npm test          # unit tests: path encoding, folder rules, session log rewriting
+```
+
+`lib/client.js` is generated — edit `src/client.js` instead. The Host half
+(`lib/*.js` except `client.js`) is plain ESM, loaded straight by Node.
+
+A separate end-to-end harness drives real Cordis services (move, rename, refusal,
+rollback, undo) against a scratch session store. It needs the Harness packages
+resolvable from `node_modules`, so it lives in the development checkout rather
+than in a fresh clone.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,84 @@
+# @reed-io/dsh-workspace-move
+
+把 DeepSeek Harness 的工作区连同它的文件夹、文件夹里的全部内容、其下注册的子工作区以及它保存的会话，一起搬到磁盘上的另一个位置。行为类似 `mv`：一个目标路径，一个原子结果。修改文件夹名时，工作区也会一并重命名。
+
+## 一次移动会带上什么
+
+| 跟着工作区一起走的东西 | 方式 |
+| --- | --- |
+| 工作区文件夹及其整个目录树 | 同一分区用 rename；跨分区复制、校验后再删源。 |
+| 注册在该文件夹内的子工作区 | 它们的注册路径会跟着文件夹一起改写，注册、标题和会话列表全部保留。 |
+| 工作区列出的会话 | 每个会话日志移动到目标项目目录，并就地改写日志头里的 `cwd`，历史与标题逐字节保留。 |
+| 工作区标题 | 仅当这次移动同时改了文件夹名、且标题仍是文件夹名时才改。 |
+
+除此之外什么都不动。只有当移动把源目录搬空时才会删除源目录本身，它的上级目录永远不会被触碰。
+
+## 使用方法
+
+在侧边栏右键工作区（或点它的 `…` 按钮），选择 **移动工作区…**。在内置的目录浏览器里选目标文件夹，填写工作区在新位置的文件夹名，确认要一起搬走的内容，然后确认。
+
+以下情况会拒绝移动并给出原因：
+
+- 目标位置已经存在同名文件夹 —— 换个名字；
+- 目标在工作区内部，或工作区在目标自身的路径链里；
+- 还有会话正在运行 —— 先停掉它们；
+- 名字在这个平台上不是合法文件夹名。
+
+移动成功后，浮动提示会提供 **撤销**；只要该次移动仍是本轮最近的一次，工作区菜单也会提供 **撤销上次移动**。撤销记录只保存在内存中，Harness 重启后失效。
+
+一次移动要么完整完成，要么整体失败。任何一步出错，插件都会把文件夹、注册信息和已经动过的会话全部回滚，并报告失败原因。
+
+## Agent 工具
+
+同一套引擎也注册为一个工具，Agent 可以直接调用：
+
+```text
+move_workspace(workspaceId, targetParent, folderName?)
+```
+
+`folderName` 省略时沿用原文件夹名。工具会返回最终位置、一起搬走的会话数与子工作区数，以及这次移动是否还能撤销。
+
+## 行为说明
+
+- 移动在 Host 进程内完成，工作区注册表和会话存储都由 Host 拥有；浏览器端只负责驱动。
+- 会话是就地改写：只重新压缩承载 `cwd` 的头部帧，其余事件帧逐字节复制。
+- 会话日志落到新路径后，再重新挂回工作区，因此工作区的会话顺序保持不变。
+- 移动后不需要重启 Harness 才能使用被移动的会话；正在运行的那个会话本身不能被移动，运行检查会拦住它。
+- 首先在 Windows 上开发与验证。路径处理、分区判定和文件夹命名规则都按平台区分，macOS 与 Linux 走同一套代码路径；原生共享文件夹的情况由"复制后校验"分支处理。
+
+## 依赖
+
+- DeepSeek Harness `>=0.2.0-rc.1 <0.3.0-0`
+- Node `^22.19.0 || >=24.0.0`
+- 本机（owner）桌面会话：目标选择对话框通过一条仅限回环地址的路由与 Host 通信。
+
+## 安装
+
+需要已安装并能正常运行 DeepSeek Harness。下面的 `desktop` 请换成你实际使用的
+profile（`web`、`desktop`……）。
+
+```bash
+dsh plugin --profile desktop add @reed-io/dsh-workspace-move@latest
+```
+
+或者把该 bundle 加入某个 profile 的 `dsh.profile.bundles`，然后重启 DeepSeek Harness。
+安装后刷新页面（`Ctrl+R`），侧边栏才会出现新的菜单项。
+
+## 开发
+
+```bash
+npm run build     # src/client.js -> lib/client.js（浏览器 bundle）
+npm run check     # 构建后校验客户端 bundle 契约与失败隔离
+npm test          # 单元测试：路径编码、文件夹命名规则、会话日志改写
+```
+
+`lib/client.js` 是构建产物，请改 `src/client.js`。宿主侧（`lib/*.js` 中除
+`client.js` 外）是普通 ESM，由 Node 直接加载。
+
+另有一套端到端 harness，会拉起真实的 Cordis 服务，在临时会话存储上跑移动、重命名、
+拒绝、回滚与撤销。它需要 `node_modules` 里能解析到 Harness 的包，因此留在开发用的
+检出目录里，不随新克隆的仓库分发。
+
+## 许可证
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: workspace-move
+      name: '@reed-io/dsh-workspace-move'

package/icon/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="48" height="48">
+  <rect x="3" y="3" width="42" height="42" rx="11" fill="#eaf1f8"/>
+  <rect x="9" y="19" width="12" height="18" rx="2.6" fill="#4f86b8"/>
+  <path d="M9 24V14.6c0-1.4 1.1-2.6 2.6-2.6h4.6c.9 0 1.7.5 2.2 1.2l1.2 1.8h-8.6c-.7 0-1.2.4-1.2 1.1V24z" fill="#4f86b8"/>
+  <path d="M25 28h9.2" stroke="#6ea8d8" stroke-width="4.2" stroke-linecap="round"/>
+  <path d="M31.4 22.2 38 28l-6.6 5.8" fill="none" stroke="#6ea8d8" stroke-width="4.2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/lib/artifact.js

@@ -0,0 +1,236 @@
+/**
+ * Physical rewriting of one session artifact when its working directory changes.
+ *
+ * Only the header frame is re-encoded — it carries the single `cwd` field the
+ * backend uses to locate and validate the log. Every other byte, including every
+ * event record inside the payload frame, is preserved verbatim, so recorded
+ * history keeps saying what actually ran and the artifact stays a valid log for
+ * the backend's own scanner.
+ * @module @reed-io/dsh-workspace-move
+ */
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { constants, zstdCompress, zstdDecompressSync } from "node:zlib";
+import { promisify } from "node:util";
+
+const zstdCompressAsync = promisify(zstdCompress);
+
+/**
+ * Decompress one complete zstd frame. zlib's async decode can answer an empty
+ * buffer for a frame smaller than its output chunk, so the frame is decoded in
+ * place; frames here are single header lines, never large.
+ * @param frame - one complete zstd frame.
+ * @returns the decompressed bytes.
+ */
+function zstdDecompressFrame(frame, options = undefined) {
+  return Promise.resolve(zstdDecompressSync(frame, options));
+}
+const ZSTD_MAGIC = 4247762216;
+const CHECKSUM_OPTS = { params: { [constants.ZSTD_c_checksumFlag]: 1 } };
+
+/**
+ * Detect zstd framing from the bytes themselves — staging files may not carry the
+ * `.zstd` suffix while a rewrite is in flight.
+ * @param buffer - artifact bytes.
+ * @returns whether the artifact starts with a zstd frame.
+ */
+export function isZstdFramed(buffer) {
+  return buffer.length >= 4 && buffer.readUInt32LE(0) === ZSTD_MAGIC;
+}
+
+/**
+ * Measure every complete Zstandard frame in a buffer without decoding them.
+ * @param buffer - artifact bytes.
+ * @returns frame boundaries plus the offset of a torn trailing frame, if any.
+ */
+export function scanFrames(buffer) {
+  const frames = [];
+  let start = 0;
+  while (start < buffer.length) {
+    let offset = start;
+    if (buffer.length - offset < 4) return { frames, tornStart: start };
+    if (buffer.readUInt32LE(offset) !== ZSTD_MAGIC) {
+      if (frames.length === 0) throw new Error("session artifact is not zstd framed");
+      return { frames, tornStart: start };
+    }
+    offset += 4;
+    if (buffer.length - offset < 1) return { frames, tornStart: start };
+    const descriptor = buffer.readUInt8(offset);
+    offset += 1;
+    if ((descriptor & 24) !== 0) throw new Error("zstd frame carries reserved bits");
+    const contentSizeFlag = descriptor >>> 6;
+    const singleSegment = (descriptor & 32) !== 0;
+    const checksum = (descriptor & 4) !== 0;
+    const dictionaryFlag = descriptor & 3;
+    const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag;
+    const contentSizeBytes = contentSizeFlag === 0 ? (singleSegment ? 1 : 0) : 1 << contentSizeFlag;
+    offset += (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes;
+    if (offset > buffer.length) return { frames, tornStart: start };
+    for (;;) {
+      if (buffer.length - offset < 3) return { frames, tornStart: start };
+      const blockHeader = buffer.readUIntLE(offset, 3);
+      offset += 3;
+      const lastBlock = (blockHeader & 1) !== 0;
+      const blockType = (blockHeader >>> 1) & 3;
+      const blockSize = blockHeader >>> 3;
+      if (blockType === 3) throw new Error("zstd frame holds a reserved block type");
+      offset += blockType === 1 ? 1 : blockSize;
+      if (offset > buffer.length) return { frames, tornStart: start };
+      if (lastBlock) break;
+    }
+    if (checksum) {
+      if (buffer.length - offset < 4) return { frames, tornStart: start };
+      offset += 4;
+    }
+    frames.push({ start, end: offset });
+    start = offset;
+  }
+  return { frames };
+}
+
+/**
+ * Split an artifact into its header line text and the untouched byte tail.
+ * @param buffer - artifact bytes.
+ * @param compressed - whether the artifact is zstd framed.
+ * @returns the header text (without its newline) and the tail to preserve.
+ */
+async function splitHeader(buffer, compressed) {
+  if (!compressed) {
+    const newline = buffer.indexOf(10);
+    const text = (newline < 0 ? buffer : buffer.subarray(0, newline)).toString("utf8");
+    return { text, tail: newline < 0 ? Buffer.alloc(0) : buffer.subarray(newline + 1) };
+  }
+  const { frames } = scanFrames(buffer);
+  if (frames.length === 0) throw new Error("session artifact holds no complete zstd frame");
+  const first = frames[0];
+  const text = (await zstdDecompressFrame(buffer.subarray(first.start, first.end))).toString("utf8");
+  return { text: text.replace(/\n$/u, ""), tail: buffer.subarray(first.end) };
+}
+
+/**
+ * Read the header of an artifact this module just wrote.
+ * @param path - artifact path.
+ * @returns the parsed header.
+ */
+async function readTranscodedHeader(path) {
+  const buffer = await readFile(path);
+  const { frames } = scanFrames(buffer);
+  const text = (await zstdDecompressFrame(buffer.subarray(frames[0].start, frames[0].end))).toString("utf8");
+  return JSON.parse(text);
+}
+
+/**
+ * Read one artifact's header line as an object.
+ * @param path - artifact path.
+ * @returns the parsed header.
+ */
+export async function readArtifactHeader(path) {
+  const buffer = await readFile(path);
+  const { text } = await splitHeader(buffer, isZstdFramed(buffer));
+  return JSON.parse(text);
+}
+
+/**
+ * Re-encode one header line in the artifact's own framing.
+ * @param header - header object to encode.
+ * @param compressed - whether the artifact is zstd framed.
+ * @returns encoded header frame including its newline.
+ */
+async function encodeHeader(header, compressed) {
+  const line = Buffer.from(`${JSON.stringify(header)}\n`, "utf8");
+  return compressed ? zstdCompressAsync(line, CHECKSUM_OPTS) : line;
+}
+
+/**
+ * Rewrite one artifact's header cwd in place, keeping its payload byte-identical.
+ * @param path - artifact path.
+ * @param cwd - replacement working directory.
+ * @param expectedId - session id the artifact must carry.
+ * @returns whether the artifact changed.
+ */
+export async function rewriteArtifactCwd(path, cwd, expectedId) {
+  const buffer = await readFile(path);
+  const compressed = isZstdFramed(buffer);
+  const { text, tail } = await splitHeader(buffer, compressed);
+  const header = JSON.parse(text);
+  if (header.id !== expectedId) throw new Error(`session artifact '${path}' holds '${String(header.id)}', expected '${expectedId}'`);
+  if (header.cwd === cwd) return false;
+  const stage = join(dirname(path), `.stage-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  const bytes = Buffer.concat([await encodeHeader({ ...header, cwd }, compressed), tail]);
+  try {
+    await writeFile(stage, bytes);
+    await rename(stage, path);
+  } catch (error) {
+    await rm(stage, { force: true }).catch(() => {});
+    throw error;
+  }
+  const written = await readArtifactHeader(path);
+  if (written.id !== expectedId || written.cwd !== cwd) throw new Error(`session artifact '${path}' did not accept cwd '${cwd}'`);
+  return true;
+}
+
+/**
+ * Write one session's artifact at a new path with a rewritten header, then read
+ * it back. Fails when the target already exists.
+ * @param source - original artifact path.
+ * @param target - new artifact path (its parent must exist).
+ * @param cwd - replacement working directory.
+ * @param expectedId - session id the artifact must carry.
+ * @returns nothing; throws when the copy cannot be verified.
+ */
+export async function copyArtifactWithCwd(source, target, cwd, expectedId) {
+  const buffer = await readFile(source);
+  const compressed = isZstdFramed(buffer);
+  const { text, tail } = await splitHeader(buffer, compressed);
+  const header = JSON.parse(text);
+  if (header.id !== expectedId) throw new Error(`session artifact '${source}' holds '${String(header.id)}', expected '${expectedId}'`);
+  await writeFile(target, Buffer.concat([await encodeHeader({ ...header, cwd }, compressed), tail]), { flag: "wx" });
+  const reread = await readFile(target);
+  const written = JSON.parse((await splitHeader(reread, isZstdFramed(reread))).text);
+  if (written.id !== expectedId || written.cwd !== cwd) throw new Error(`copied session artifact '${target}' did not accept cwd '${cwd}'`);
+}
+
+/**
+ * Decode and re-encode one artifact into a new file, rewriting its header cwd and
+ * re-compressing every record — the fallback for an artifact whose payload could
+ * not be copied verbatim after a provable header rewrite.
+ * @param source - original artifact path.
+ * @param target - new artifact path (its parent must exist, file must not exist).
+ * @param cwd - replacement working directory.
+ * @param expectedId - session id the artifact must carry.
+ * @returns the number of event records re-encoded.
+ */
+export async function transcodeArtifactWithCwd(source, target, cwd, expectedId) {
+  const buffer = await readFile(source);
+  const compressed = isZstdFramed(buffer);
+  const { text } = await splitHeader(buffer, compressed);
+  const header = JSON.parse(text);
+  if (header.id !== expectedId) throw new Error(`session artifact '${source}' holds '${String(header.id)}', expected '${expectedId}'`);
+  let plain;
+  if (compressed) {
+    const { frames, tornStart } = scanFrames(buffer);
+    const parts = [];
+    for (const frame of frames) parts.push(await zstdDecompressFrame(buffer.subarray(frame.start, frame.end)));
+    plain = Buffer.concat(parts).toString("utf8");
+    if (tornStart !== undefined) plain += (await zstdDecompressFrame(buffer.subarray(tornStart), { finishFlush: constants.ZSTD_e_flush })).toString("utf8");
+  } else {
+    plain = buffer.toString("utf8");
+  }
+  const newline = plain.indexOf("\n");
+  const body = newline < 0 ? "" : plain.slice(newline + 1).replace(/\n$/u, "");
+  const records = body === "" ? [] : body.split("\n");
+  for (const record of records) JSON.parse(record);
+  const bytes = [await encodeHeader({ ...header, cwd }, compressed)];
+  if (records.length > 0) {
+    const payload = Buffer.from(`${records.join("\n")}\n`, "utf8");
+    bytes.push(compressed ? await zstdCompressAsync(payload, CHECKSUM_OPTS) : payload);
+  }
+  const staged = `${target}.stage-${process.pid}-${Date.now()}`;
+  await mkdir(dirname(staged), { recursive: true });
+  await writeFile(staged, Buffer.concat(bytes), { flag: "wx" });
+  await rm(target, { force: true });
+  await rename(staged, target);
+  const written = await readTranscodedHeader(target);
+  if (written.id !== expectedId || written.cwd !== cwd) throw new Error(`transcoded session artifact '${target}' did not accept cwd '${cwd}'`);
+  return records.length;
+}