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

package/lib/host-api.js

@@ -0,0 +1,159 @@
+/**
+ * Transport between the Client surface and this Host plugin.
+ *
+ * The Host owns every filesystem and registry write, so the Client dialog talks
+ * to it over a same-origin JSON route. The route only answers requests a page
+ * served by this same Harness instance could make: the request must arrive from
+ * the loopback interface, carry the plugin header, come from a same-origin
+ * fetch or a non-browser client, and name this Host in an Origin header when it
+ * sends one. Anything else is refused, so the route stays inert for other
+ * origins a browser might visit.
+ * @module @reed-io/dsh-workspace-move
+ */
+
+import { API_HEADER, API_PREFIX } from "./host-api-client.js";
+
+export { API_HEADER, API_PREFIX };
+
+/** Largest request body accepted, in bytes. */
+const MAX_BODY_BYTES = 64 * 1024;
+
+/**
+ * Whether an address literal belongs to the loopback interface.
+ * @param address - socket remote address.
+ * @returns whether it is loopback.
+ */
+function isLoopbackAddress(address) {
+  if (typeof address !== "string" || address === "") return false;
+  if (address === "::1" || address === "127.0.0.1") return true;
+  if (address.startsWith("127.")) return true;
+  return address.startsWith("::ffff:127.");
+}
+
+/**
+ * Resolve the http origin part of a header value.
+ * @param value - header value such as `http://127.0.0.1:4379`.
+ * @returns the origin, or undefined when the value is not an origin.
+ */
+function originOf(value) {
+  if (typeof value !== "string" || value === "" || value === "null") return undefined;
+  try {
+    return new URL(value).origin;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Decide whether one request may reach the Host API.
+ * @param request - incoming request.
+ * @returns whether the request is trusted.
+ */
+export function isTrustedRequest(request) {
+  if (request.headers[API_HEADER] !== "1") return false;
+  if (!isLoopbackAddress(request.socket?.remoteAddress)) return false;
+  const site = request.headers["sec-fetch-site"];
+  if (site !== undefined && site !== "same-origin" && site !== "none") return false;
+  const host = request.headers.host;
+  if (typeof host !== "string" || host === "") return false;
+  const origin = request.headers.origin;
+  if (origin === undefined) return true;
+  const parsed = originOf(origin);
+  if (parsed === undefined) return false;
+  try {
+    return new URL(parsed).host === host;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read a request body, refusing oversized payloads.
+ * @param request - incoming request.
+ * @returns the decoded UTF-8 body.
+ */
+async function readBody(request) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > MAX_BODY_BYTES) throw new Error("request body is too large");
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * Write one JSON reply.
+ * @param response - server response.
+ * @param status - HTTP status.
+ * @param payload - JSON-serializable payload.
+ * @returns nothing.
+ */
+function send(response, status, payload) {
+  const body = Buffer.from(JSON.stringify(payload), "utf8");
+  response.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": String(body.length),
+    "cache-control": "no-store",
+    "x-content-type-options": "nosniff"
+  });
+  response.end(body);
+}
+
+/**
+ * Build the request handler over one action table.
+ * @param actions - map of action name to async function of the parsed body.
+ * @param logger - Host logger used for contained failures.
+ * @returns a node request handler.
+ */
+export function createHandler(actions, logger) {
+  return (request, response) => {
+    const run = async () => {
+      if (request.method !== "POST") {
+        send(response, 405, { ok: false, code: "method-not-allowed" });
+        return;
+      }
+      if (!isTrustedRequest(request)) {
+        send(response, 403, { ok: false, code: "untrusted-request" });
+        return;
+      }
+      const url = new URL(request.url ?? "/", "http://localhost");
+      const name = url.pathname.slice(API_PREFIX.length).replace(/^\//u, "");
+      const action = actions[name];
+      if (action === undefined) {
+        send(response, 404, { ok: false, code: "unknown-action" });
+        return;
+      }
+      let body;
+      try {
+        const text = await readBody(request);
+        body = text === "" ? {} : JSON.parse(text);
+      } catch (error) {
+        send(response, 400, { ok: false, code: "bad-request", message: String(error) });
+        return;
+      }
+      try {
+        const result = await action(body);
+        send(response, 200, { ok: true, result });
+      } catch (error) {
+        const failure = error instanceof Error ? error : new Error(String(error));
+        logger?.warn?.(`workspace-move: action '${name}' failed: ${failure.message}`);
+        send(response, 200, {
+          ok: false,
+          code: failure.code ?? "failed",
+          message: failure.message,
+          details: failure.details ?? {}
+        });
+      }
+    };
+    run().catch((error) => {
+      logger?.warn?.(`workspace-move: request handling failed: ${String(error)}`);
+      try {
+        send(response, 500, { ok: false, code: "internal" });
+      } catch {
+        response.destroy?.();
+      }
+    });
+  };
+}

package/lib/index.js

@@ -0,0 +1,7 @@
+/**
+ * Host half of the workspace move plugin: the route the Client dialog calls, the
+ * agent tool, and the in-memory record that makes a move undoable until the
+ * Harness restarts.
+ * @module @reed-io/dsh-workspace-move
+ */
+export { apply, inject, name, undoState } from "./plugin.js";

package/lib/paths.js

@@ -0,0 +1,99 @@
+/**
+ * Session artifact layout helpers. The jsonl backend derives the on-disk folder
+ * from a session's `cwd` and its header; these mirrors let the move engine place
+ * and verify artifacts without importing backend internals.
+ * @module @reed-io/dsh-workspace-move
+ */
+import { join } from "node:path";
+
+const PROJECT_KEY_LIMIT = 251;
+
+/**
+ * Encode one path segment the way the backend encodes session folders.
+ * @param value - segment to encode.
+ * @returns the portable segment.
+ */
+export function encodeSegment(value) {
+  if (value.length === 0) throw new Error("cannot encode an empty path segment");
+  if (value === ".") return "~002E";
+  if (value === "..") return "~002E~002E";
+  let out = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    const char = String.fromCharCode(code);
+    if (char !== "~" && /^[A-Za-z0-9._-]$/u.test(char)) out += char;
+    else out += `~${code.toString(16).toUpperCase().padStart(4, "0")}`;
+  }
+  return out;
+}
+
+/**
+ * Fold a working directory into a project folder name.
+ * @param cwd - session working directory.
+ * @returns the project key used as a storage folder name.
+ */
+export function projectKey(cwd) {
+  if (cwd.length === 0) throw new Error("cannot encode an empty project path");
+  let readable = "";
+  let separatorRun = false;
+  for (let index = 0; index < cwd.length; index += 1) {
+    const code = cwd.charCodeAt(index);
+    const char = String.fromCharCode(code);
+    if (char === "/" || char === "\\" || char === ":") {
+      if (!separatorRun) readable += "-";
+      separatorRun = true;
+    } else if (char !== "~" && /^[A-Za-z0-9._-]$/u.test(char)) {
+      readable += char;
+      separatorRun = false;
+    } else {
+      readable += `~${code.toString(16).toUpperCase().padStart(4, "0")}`;
+      separatorRun = false;
+    }
+  }
+  return `--${(readable.replace(/^-+/u, "") || "root").slice(0, PROJECT_KEY_LIMIT)}--`;
+}
+
+/**
+ * Locate the folder holding every session of one working directory.
+ * @param root - persistence root.
+ * @param cwd - session working directory, or undefined for the cwd-less group.
+ * @returns absolute project folder.
+ */
+export function projectDir(root, cwd) {
+  return cwd === undefined ? join(root, "_no-cwd") : join(root, projectKey(cwd));
+}
+
+/**
+ * Locate one session's artifact folder.
+ * @param root - persistence root.
+ * @param cwd - session working directory.
+ * @param id - session id.
+ * @returns absolute session folder.
+ */
+export function sessionDir(root, cwd, id) {
+  return join(projectDir(root, cwd), encodeSegment(id));
+}
+
+/**
+ * Tag one artifact filename with its format version and compression.
+ * @param version - session format version.
+ * @param compression - artifact compression ("zstd" by default, "none" when raw).
+ * @returns artifact filename.
+ */
+export function logFilename(version, compression = "zstd") {
+  const suffix = compression === undefined || compression === "none" ? "" : `.${compression}`;
+  return version === 0 ? `session.jsonl${suffix}` : `session.v${version}.jsonl${suffix}`;
+}
+
+/**
+ * Locate one session's current-format artifact.
+ * @param root - persistence root.
+ * @param cwd - session working directory.
+ * @param id - session id.
+ * @param version - session format version.
+ * @param compression - artifact compression.
+ * @returns absolute artifact path.
+ */
+export function logPath(root, cwd, id, version = 4, compression = "zstd") {
+  return join(sessionDir(root, cwd, id), logFilename(version, compression));
+}

package/lib/plan.js

@@ -0,0 +1,156 @@
+/**
+ * Planning a move before anything is written: which workspace is the subject,
+ * where it lands, which nested registrations must follow it, and why a request
+ * has to be refused.
+ *
+ * A plan is pure data. Everything it claims was read from the filesystem and the
+ * registry, so the UI can show exactly what will happen and the engine can later
+ * refuse a plan whose preconditions no longer hold.
+ * @module @reed-io/dsh-workspace-move
+ */
+import { basename, join, resolve } from "node:path";
+import { canonicalPath, exists, isInside, samePath } from "./fsx.js";
+import { recordOf } from "./registry-ops.js";
+import { collectSessions, isWithin } from "./sessions.js";
+
+/**
+ * Build one failure object the surfaces can render.
+ * @param code - stable machine-readable reason.
+ * @param message - human-readable explanation.
+ * @param details - extra structured context.
+ * @returns the failure.
+ */
+export function fail(code, message, details = {}) {
+  return { code, message, details };
+}
+
+/**
+ * Problems that make a folder name unusable as a workspace folder.
+ * @param name - proposed folder name.
+ * @returns a failure, or undefined when the name is fine.
+ */
+export function nameProblem(name) {
+  if (typeof name !== "string" || name.trim() === "") return fail("name-empty", "Enter a folder name.");
+  if (name !== name.trim()) return fail("name-padded", "A folder name cannot start or end with a space.");
+  if (name === "." || name === "..") return fail("name-relative", "A folder name cannot be '.' or '..'.");
+  if (/[\\/:*?"<>|\u0000-\u001F]/u.test(name)) return fail("name-invalid", "A folder name cannot contain \\ / : * ? \" < > |.");
+  if (/[. ]$/u.test(name)) return fail("name-trailing", "A folder name cannot end with a dot or a space.");
+  return undefined;
+}
+
+/**
+ * Describe where a workspace lives and where a move would send it.
+ * @param sourcePath - the workspace's current directory.
+ * @param targetParent - the destination parent folder.
+ * @param folderName - the folder name at the destination (defaults to the current name).
+ * @returns the resolved destination paths.
+ */
+export async function resolveTarget(sourcePath, targetParent, folderName) {
+  const parent = resolve(targetParent);
+  if (!isAbsolute(targetParent)) return { failure: fail("target-relative", "Choose an absolute destination folder.") };
+  if (!(await exists(parent))) return { failure: fail("target-missing", `The folder '${parent}' does not exist.`, { parent }) };
+  const name = typeof folderName === "string" && folderName.trim() !== "" ? folderName.trim() : basename(sourcePath);
+  const problem = nameProblem(name);
+  if (problem !== undefined) return { failure: problem };
+  const destination = join(parent, name);
+  if (samePath(destination, sourcePath)) {
+    return { failure: fail("target-same", "The workspace is already in that folder.") };
+  }
+  if (isInside(destination, sourcePath)) {
+    return { failure: fail("target-inside", "A workspace cannot be moved into its own folder.") };
+  }
+  if (isInside(sourcePath, destination)) {
+    return { failure: fail("target-ancestor", "That destination is inside the workspace's own current folder chain.") };
+  }
+  if (await exists(destination)) {
+    return { failure: fail("target-exists", `'${destination}' already exists. Pick another name.`, { destination }) };
+  }
+  return { canonicalParent: await canonicalPath(parent), destination, folderName: name, renamed: !samePath(destination, sourcePath) && basename(sourcePath) !== name };
+}
+
+/**
+ * Whether a path is absolute on the running platform.
+ * @param value - candidate path.
+ * @returns whether it is absolute.
+ */
+function isAbsolute(value) {
+  if (typeof value !== "string" || value === "") return false;
+  if (process.platform === "win32") return /^[A-Za-z]:[\\/]/u.test(value) || /^\\\\/u.test(value);
+  return value.startsWith("/");
+}
+
+/**
+ * Nested registrations whose path lives inside the moving folder.
+ * @param registry - workspace registry service.
+ * @param workspaceId - the workspace being moved.
+ * @param sourcePath - the folder that will move.
+ * @param destination - where that folder will be.
+ * @returns one entry per affected registration, with its planned path and title.
+ */
+export function nestedMoves(registry, workspaceId, sourcePath, destination) {
+  return registry
+    .list()
+    .filter((entity) => entity.id !== workspaceId && isWithin(entity.path, sourcePath))
+    .map((entity) => {
+      const next = join(destination, entity.path.slice(sourcePath.length).replace(/^[\\/]+/u, ""));
+      return { id: entity.id, from: entity.path, to: next, title: entity.title };
+    });
+}
+
+/**
+ * Sessions of one workspace that currently have running work.
+ * @param ctx - Host context.
+ * @param sessionIds - sessions to check.
+ * @returns the active sessions with the kind of work each reports.
+ */
+export async function activeSessions(ctx, sessionIds) {
+  const active = [];
+  for (const sessionId of sessionIds) {
+    let activities = [];
+    try {
+      activities = await ctx.waterfall("workspace/session-activity", { sessionId }, () => Promise.resolve([]));
+    } catch {
+      activities = [];
+    }
+    const kinds = (Array.isArray(activities) ? activities : []).flat().map((item) => item?.kind ?? "busy").filter(Boolean);
+    if (kinds.length > 0) active.push({ sessionId, kinds: [...new Set(kinds)] });
+  }
+  return active;
+}
+
+/**
+ * Build the full plan for one requested move.
+ * @param ctx - Host context.
+ * @param request - workspace id, destination parent and optional folder name.
+ * @returns `{ plan }` or `{ failure }`.
+ */
+export async function buildPlan(ctx, request) {
+  const registry = ctx.workspaceRegistry;
+  if (registry === undefined) return { failure: fail("registry-unavailable", "The workspace registry is unavailable.") };
+  const workspaceId = typeof request?.workspaceId === "string" ? request.workspaceId : "";
+  const entity = registry.list().find((candidate) => candidate.id === workspaceId);
+  const record = recordOf(registry, workspaceId);
+  if (entity === undefined || record === undefined) return { failure: fail("workspace-unknown", "That workspace is no longer registered.") };
+  const resolved = await resolveTarget(record.path, request?.targetParent ?? "", request?.folderName);
+  if (resolved.failure !== undefined) return { failure: resolved.failure };
+  const active = await activeSessions(ctx, record.sessionIds);
+  const sessions = await collectSessions(ctx, record);
+  const nested = nestedMoves(registry, workspaceId, record.path, resolved.destination);
+  const currentName = basename(record.path);
+  return {
+    plan: {
+      workspaceId,
+      title: record.title,
+      source: record.path,
+      sourceCanonical: await canonicalPath(record.path),
+      destination: resolved.destination,
+      targetParent: resolved.canonicalParent,
+      folderName: resolved.folderName,
+      renamed: resolved.folderName !== currentName,
+      sessionIds: [...record.sessionIds],
+      sessions: sessions.map((session) => ({ id: session.id, listed: session.listed, path: session.path })),
+      nested,
+      active
+    }
+  };
+}

package/lib/plugin.js

@@ -0,0 +1,159 @@
+/**
+ * Host half of the workspace move plugin: wires the move engine to the Client
+ * dialog route, the agent tool, and the in-memory undo record.
+ * @module @reed-io/dsh-workspace-move
+ */
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { exists, samePath } from "./fsx.js";
+import { performMove, toError, undoMove } from "./engine.js";
+import { API_PREFIX, createHandler } from "./host-api.js";
+import { browse, createFolder } from "./directory-browse.js";
+import { buildPlan } from "./plan.js";
+
+/** Cordis plugin name. */
+export const name = "workspace-move";
+
+/** Services the plugin needs before it can answer a move request. */
+export const inject = ["webServer", "workspaceRegistry", "sessionPersistence", "tools"];
+
+/**
+ * The single move a running Harness can undo. Kept in memory on purpose: the
+ * record describes live folders and a registry that only exist for this run.
+ */
+export const undoState = { last: undefined };
+
+/**
+ * Product view of one finished move: what a caller may report, and whether undo
+ * is offered for it.
+ * @param record - the undo record kept by the engine.
+ * @returns the summarized outcome.
+ */
+function summarize(record) {
+  undoState.last = record.allowed ? record : undefined;
+  return {
+    destination: record.destination,
+    source: record.source,
+    title: record.title,
+    sessions: record.sessions.length,
+    nested: record.nested.length,
+    undoable: undoState.last !== undefined
+  };
+}
+
+/**
+ * Mount the plugin.
+ * @param ctx - Cordis context.
+ */
+export function apply(ctx) {
+  const logger = ctx.logger;
+  const actions = {
+    /**
+     * Review a requested move without touching anything.
+     * @param body - workspace id and destination.
+     * @returns the plan or the reason it cannot proceed.
+     */
+    async plan(body) {
+      const built = await buildPlan(ctx, body);
+      if (built.failure !== undefined) throw toError(built.failure);
+      return built.plan;
+    },
+    /**
+     * Execute a requested move and remember it for undo.
+     * @param body - workspace id and destination.
+     * @returns the resulting locations.
+     */
+    async move(body) {
+      return summarize(await performMove(ctx, body));
+    },
+    /**
+     * Report what could be undone right now.
+     * @returns the recorded move, or nothing.
+     */
+    async undoInfo() {
+      const last = undoState.last;
+      if (last === undefined) return { available: false };
+      const registered = ctx.workspaceRegistry?.list().find((entity) => entity.id === last.workspaceId);
+      const occupied = await exists(last.source).catch(() => false);
+      const available = registered !== undefined && samePath(registered.path, last.destination) && !occupied;
+      return { available, title: last.title, source: last.source, destination: last.destination, workspaceId: last.workspaceId, occupied };
+    },
+    /**
+     * Undo the recorded move.
+     * @returns nothing.
+     */
+    async undo() {
+      const last = undoState.last;
+      if (last === undefined) throw toError({ code: "nothing-to-undo", message: "There is no move to undo.", details: {} });
+      await undoMove(ctx, last);
+      undoState.last = undefined;
+      return { restored: last.source };
+    },
+    /**
+     * List the subfolders of one destination folder.
+     * @param body - the folder to list.
+     * @returns folders, breadcrumbs and the entry cap.
+     */
+    async browse(body) {
+      return browse(body?.path);
+    },
+    /**
+     * Create one folder inside a destination folder.
+     * @param body - parent folder and new folder name.
+     * @returns the new folder path.
+     */
+    async createFolder(body) {
+      return { path: await createFolder(body?.parent, body?.name) };
+    }
+  };
+  try {
+    ctx.webServer.register({ kind: "prefix", path: API_PREFIX, handler: createHandler(actions, logger) });
+  } catch (error) {
+    // A hot reload can re-apply this plugin while the previous route is still
+    // mounted. The handler only reads module-level state, so the existing route
+    // serves the new instance just as well; failing here would take the plugin
+    // down for no reason.
+    if (!/duplicate prefix route/i.test(String(error?.message ?? error))) throw error;
+    logger?.warn?.(`workspace-move: ${API_PREFIX} is already mounted; reusing the existing route`);
+  }
+
+  const tool = defineTool({
+    name: "move_workspace",
+    description:
+      "Move one registered workspace to another folder, together with its folder tree, nested workspaces registered inside it, and its stored sessions. A different folder name renames the workspace. Fails while its sessions are running; the Harness GUI offers undo for the last move of this run.",
+    parameters: {
+      workspaceId: { type: "string", description: "Id of the workspace to move, as reported by the workspace list." },
+      targetParent: { type: "string", description: "Absolute path of the folder that will contain the moved workspace." },
+      folderName: { type: "string", description: "Folder name inside the destination parent. Omit to keep the current folder name." }
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          destination: { type: "string", required: true },
+          source: { type: "string", required: true },
+          title: { type: "string", required: true },
+          sessions: { type: "number", required: true },
+          nested: { type: "number", required: true },
+          undoable: { type: "boolean", required: true }
+        }
+      },
+      render: (_args, value) => [{ type: "text", text: JSON.stringify(value) }]
+    },
+    async execute(args) {
+      return summarize(
+        await performMove(ctx, { workspaceId: args.workspaceId, targetParent: args.targetParent, folderName: args.folderName })
+      );
+    },
+    presentCall: (args) => ({ card: "generic", title: "move_workspace", rawInput: args })
+  });
+
+  try {
+    ctx.tools.register(tool);
+  } catch (error) {
+    // Same reload situation as the route above: an earlier copy of this plugin
+    // may still own the tool name.
+    if (!/already (?:registered|exists)|duplicate/i.test(String(error?.message ?? error))) throw error;
+    logger?.warn?.("workspace-move: move_workspace is already registered; keeping the existing tool");
+  }
+}