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

package/lib/engine.js

@@ -0,0 +1,263 @@
+/**
+ * Executing a move: take the sessions down, move the folder once, put the
+ * sessions back where the new path says they live, then re-point every affected
+ * registration. Every step records how to reverse itself, and a failure walks
+ * that record backwards, so a move either lands completely or leaves nothing
+ * behind.
+ * @module @reed-io/dsh-workspace-move
+ */
+import { mkdir, rm } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { exists, isInside, moveDirectory, removeIfEmpty, samePath } from "./fsx.js";
+import { buildPlan, fail } from "./plan.js";
+import { attachOrdered, retargetWorkspace, snapshotWorkspace } from "./registry-ops.js";
+import { collectSessions, dropBackup, locateSession, persistenceInfo, restoreSession, takeDownSession, writeBackSession } from "./sessions.js";
+
+/** Backup folder name — distinct from other plugins' folders beside it. */
+const BACKUP_LEAF = "dshwm-move-backup";
+
+/**
+ * The backup area used while a move is in flight, beside the persistence root so
+ * it always shares a volume with the artifacts it holds.
+ * @param ctx - Host context.
+ * @returns the absolute backup root.
+ */
+export function backupRootOf(ctx) {
+  const { root } = persistenceInfo(ctx.sessionPersistence);
+  return join(dirname(root), BACKUP_LEAF);
+}
+
+/**
+ * Build a unique label for one move attempt.
+ * @returns a filesystem-safe tag.
+ */
+function newTag() {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/**
+ * Move a workspace, its folder tree, nested registrations and sessions.
+ * @param ctx - Host context.
+ * @param request - workspace id, destination parent, optional folder name and rename flags.
+ * @returns the record kept for undo.
+ */
+export async function performMove(ctx, request) {
+  const built = await buildPlan(ctx, request);
+  if (built.failure !== undefined) throw toError(built.failure);
+  const plan = built.plan;
+  if (plan.active.length > 0) {
+    const failure = fail("sessions-running", "Stop the running sessions before moving this workspace.", { active: plan.active });
+    throw toError(failure);
+  }
+  const registry = ctx.workspaceRegistry;
+  const workspace = registry.list().find((entity) => entity.id === plan.workspaceId);
+  if (workspace === undefined) throw toError(fail("workspace-unknown", "That workspace is no longer registered."));
+  const record = snapshotWorkspace(registry, plan.workspaceId);
+  const listedOrder = [...record.sessionIds];
+  const sessions = await collectSessions(ctx, { ...record, path: plan.sourceCanonical });
+  const backupRoot = backupRootOf(ctx);
+  const tag = newTag();
+  const undo = {
+    tag,
+    allowed: request?.allowUndo !== false,
+    workspaceId: plan.workspaceId,
+    title: record.title,
+    source: record.path,
+    sourceCanonical: plan.sourceCanonical,
+    destination: plan.destination,
+    folderName: plan.folderName,
+    titleChanged: false,
+    nested: plan.nested.map((entry) => ({ ...entry })),
+    sessions: sessions.map((session) => ({ id: session.id, dir: session.dir, path: session.path, cwd: session.header.cwd, listed: session.listed }))
+  };
+  const takenDown = [];
+  let moved = undefined;
+  try {
+    for (const session of sessions) {
+      const archived = await takeDownSession(backupRoot, tag, session).catch(async (error) => {
+        if (error?.code !== "ENOENT") throw error;
+        return undefined;
+      });
+      if (archived !== undefined) takenDown.push({ session, archived });
+    }
+    const how = await moveDirectory(plan.sourceCanonical, plan.destination);
+    moved = { from: plan.sourceCanonical, to: plan.destination, how };
+    const canonicalDestination = await canonicalOf(plan.destination);
+    for (const { session, archived } of takenDown) {
+      const relative = session.header.cwd.slice(plan.sourceCanonical.length).replace(/^[\\/]+/u, "");
+      const cwd = relative === "" ? canonicalDestination : join(canonicalDestination, relative);
+      await writeBackSession(session, archived, cwd);
+    }
+    await applyRegistry(registry, plan, canonicalDestination, workspace, listedOrder, undo);
+    await dropBackup(backupRoot, tag);
+    await removeIfEmpty(plan.sourceCanonical);
+    return undo;
+  } catch (error) {
+    await rollback(ctx, undo, takenDown, moved);
+    throw error;
+  }
+}
+
+/**
+ * Repoint several registrations in one durable step, then rebuild the entity
+ * cache once so every lookup sees the new paths.
+ * @param registry - workspace registry service.
+ * @param moves - `{ id, path }` pairs.
+ * @returns nothing.
+ */
+async function applyRetargets(registry, moves) {
+  for (const move of moves) await retargetWorkspace(registry, move.id, move.path, { rebuild: false });
+  registry.rebuildEntities?.();
+}
+
+/**
+ * Canonicalize a directory that exists.
+ * @param path - directory path.
+ * @returns its real path.
+ */
+async function canonicalOf(path) {
+  const { realpath } = await import("node:fs/promises");
+  return realpath(path);
+}
+
+/**
+ * Re-point the moved registration, the nested ones, and the session account.
+ * @param registry - workspace registry service.
+ * @param plan - the executed plan.
+ * @param destination - canonical destination folder.
+ * @param workspace - the moved entity.
+ * @param listedOrder - the workspace's session order before the move.
+ * @param undo - the undo record being filled in.
+ * @returns nothing.
+ */
+async function applyRegistry(registry, plan, destination, workspace, listedOrder, undo) {
+  const moves = [
+    { id: plan.workspaceId, path: destination },
+    ...plan.nested.map((nested) => ({ id: nested.id, path: join(destination, nested.from.slice(plan.sourceCanonical.length).replace(/^[\\/]+/u, "")) }))
+  ];
+  await applyRetargets(registry, moves);
+  const entity = registry.list().find((candidate) => candidate.id === plan.workspaceId) ?? workspace;
+  await attachOrdered(registry, entity, listedOrder);
+  const members = new Set(listedOrder);
+  for (const session of undo.sessions) {
+    if (!session.listed && !members.has(session.id)) await entity.attachSession(session.id).catch(() => {});
+  }
+  const wantTitle = plan.renamed;
+  if (wantTitle) {
+    const currentTitle = registry.list().find((candidate) => candidate.id === plan.workspaceId)?.title;
+    const previousName = basename(plan.source);
+    if (currentTitle === undefined || currentTitle === previousName) {
+      await entity.setTitle(plan.folderName);
+      undo.titleChanged = true;
+    }
+  }
+}
+
+/**
+ * Reverse a partially applied move.
+ * @param ctx - Host context.
+ * @param undo - the record describing the move.
+ * @param takenDown - sessions already archived.
+ * @param moved - folder move description, when it happened.
+ * @returns nothing; rollback problems are logged, not thrown.
+ */
+async function rollback(ctx, undo, takenDown, moved) {
+  const registry = ctx.workspaceRegistry;
+  const problems = [];
+  try {
+    if (moved !== undefined) {
+      if (await exists(moved.to)) {
+        if (await exists(moved.from)) await rm(moved.to, { recursive: true, force: true }).catch((error) => problems.push(String(error)));
+        else await moveDirectory(moved.to, moved.from).catch((error) => problems.push(String(error)));
+      }
+      await mkdir(moved.from, { recursive: true }).catch(() => {});
+      await applyRetargets(registry, [{ id: undo.workspaceId, path: undo.sourceCanonical }, ...undo.nested.map((nested) => ({ id: nested.id, path: nested.from }))]).catch((error) => problems.push(String(error)));
+      if (undo.titleChanged) {
+        const entity = registry.list().find((candidate) => candidate.id === undo.workspaceId);
+        if (entity !== undefined) await entity.setTitle(undo.title).catch((error) => problems.push(String(error)));
+      }
+    }
+    for (const { session, archived } of [...takenDown].reverse()) {
+      await restoreSession(session, session.header.cwd, archived).catch((error) => problems.push(String(error)));
+    }
+  } finally {
+    if (problems.length > 0) ctx.logger?.warn?.(`workspace-move: rollback left problems: ${problems.join("; ")}`);
+  }
+}
+
+/**
+ * Undo one recorded move: everything returns to where it was.
+ * @param ctx - Host context.
+ * @param undo - the record kept by {@link performMove}.
+ * @returns nothing.
+ */
+export async function undoMove(ctx, undo) {
+  const registry = ctx.workspaceRegistry;
+  if (undo === undefined) throw toError(fail("nothing-to-undo", "There is no move to undo."));
+  const current = registry.list().find((entity) => entity.id === undo.workspaceId);
+  if (current === undefined) throw toError(fail("workspace-unknown", "The workspace is no longer registered, so this move cannot be undone."));
+  if (!samePath(current.path, undo.destination)) throw toError(fail("undo-stale", "The workspace has moved again since; this move can no longer be undone."));
+  if (await exists(undo.source)) throw toError(fail("undo-blocked", `'${undo.source}' is occupied again.`, { path: undo.source }));
+  const sessions = [];
+  for (const session of undo.sessions) {
+    const fallback = { id: session.id, dir: session.dir, path: session.path, header: { id: session.id, cwd: session.cwd, version: 4 }, ...persistenceInfo(ctx.sessionPersistence) };
+    const found = await locateSession(ctx, session.id).catch(() => undefined);
+    sessions.push({ entry: found ?? fallback, original: session });
+  }
+  const takenDown = [];
+  const backupRoot = backupRootOf(ctx);
+  const tag = `${undo.tag}-undo`;
+  let moved;
+  try {
+    for (const { entry } of sessions) {
+      const archived = await takeDownSession(backupRoot, tag, entry).catch((error) => {
+        if (error?.code === "ENOENT") return undefined;
+        throw error;
+      });
+      takenDown.push({ entry, archived });
+    }
+    await moveDirectory(undo.destination, undo.source);
+    moved = { from: undo.destination, to: undo.source };
+    for (const { entry, original } of sessions) {
+      const source = takenDown.find((item) => item.entry.id === entry.id)?.archived ?? original.dir;
+      await restoreSession({ ...entry, dir: original.dir, path: original.path }, original.cwd, source);
+    }
+    await applyRetargets(registry, [{ id: undo.workspaceId, path: undo.sourceCanonical }, ...undo.nested.map((nested) => ({ id: nested.id, path: nested.from }))]);
+    if (undo.titleChanged) {
+      const entity = registry.list().find((candidate) => candidate.id === undo.workspaceId);
+      if (entity !== undefined) await entity.setTitle(undo.title).catch(() => {});
+    }
+    await dropBackup(backupRoot, tag);
+  } catch (error) {
+    if (moved !== undefined && !(await exists(undo.destination)) && (await exists(undo.source))) {
+      await moveDirectory(undo.source, undo.destination).catch(() => {});
+    }
+    for (const { entry, archived } of [...takenDown].reverse()) {
+      const cwd = entry.header?.cwd ?? entry.cwd;
+      if (cwd !== undefined) await restoreSession(entry, cwd, archived).catch(() => {});
+    }
+    throw error;
+  }
+}
+
+/**
+ * Turn a structured failure into a thrown error carrying its code.
+ * @param failure - the structured failure.
+ * @returns an Error with `code` and `details`.
+ */
+export function toError(failure) {
+  const error = new Error(failure.message);
+  error.code = failure.code;
+  error.details = failure.details ?? {};
+  return error;
+}
+
+/**
+ * Guard: a path that is the workspace itself or an ancestor of it.
+ * @param path - candidate path.
+ * @param workspacePath - workspace directory.
+ * @returns whether path is unsafe as a destination parent.
+ */
+export function isUnsafeParent(path, workspacePath) {
+  return samePath(path, workspacePath) || isInside(path, workspacePath);
+}

package/lib/fsx.js

@@ -0,0 +1,250 @@
+/**
+ * Filesystem primitives shared by the move engine: JSON-friendly errors for the
+ * HTTP boundary, existence checks, canonical-path normalization, and same-filesystem
+ * rename with a verified copy fallback (the `mv` semantics the feature promises).
+ * @module @reed-io/dsh-workspace-move
+ */
+import { constants } from "node:fs";
+import { copyFile, lstat, mkdir, readdir, realpath, rename, rm, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, parse, resolve } from "node:path";
+
+/** Failure carrying a stable machine code the Client maps onto localized text. */
+export class MoveError extends Error {
+  /**
+   * @param code - stable failure code.
+   * @param message - operator-facing description.
+   * @param details - optional structured context for the Client.
+   */
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "MoveError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+/**
+ * Is the failure a missing-path rejection?
+ * @param error - any rejection value.
+ * @returns whether the error code is ENOENT.
+ */
+export function isMissing(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+/**
+ * Resolve whether a path exists, without following a dangling link into an error.
+ * @param path - absolute path.
+ * @returns whether anything (file, directory, or link) occupies the path.
+ */
+export async function exists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (isMissing(error)) return false;
+    throw error;
+  }
+}
+
+/**
+ * Resolve one path to its canonical form: the real path when it exists, and the
+ * canonical form of the deepest existing ancestor joined with the remainder when
+ * it does not (a target that is about to be created).
+ * @param path - absolute path to canonicalize.
+ * @returns canonical absolute path.
+ */
+export async function canonicalPath(path) {
+  const absolute = resolve(path);
+  try {
+    return await realpath(absolute);
+  } catch (error) {
+    if (!isMissing(error)) throw error;
+  }
+  const missing = [];
+  let cursor = absolute;
+  for (;;) {
+    const parent = dirname(cursor);
+    if (parent === cursor) return absolute;
+    missing.unshift(cursor.slice(parent.length).replace(/^[\\/]+/, ""));
+    cursor = parent;
+    try {
+      return join(await realpath(cursor), ...missing);
+    } catch (error) {
+      if (!isMissing(error)) throw error;
+    }
+  }
+}
+
+/**
+ * Compare two paths after canonicalization, case-insensitively on Windows.
+ * @param left - first path.
+ * @param right - second path.
+ * @returns whether they name the same location.
+ */
+export function samePath(left, right) {
+  const normalize = (value) => {
+    const absolute = resolve(value);
+    return process.platform === "win32" ? absolute.toLowerCase() : absolute;
+  };
+  return normalize(left) === normalize(right);
+}
+
+/** Is `child` strictly inside `parent` (case-insensitive on Windows)? */
+export function isInside(child, parent) {
+  const norm = (value) => {
+    const absolute = resolve(value);
+    return (process.platform === "win32" ? absolute.toLowerCase() : absolute).replace(/[\\/]+$/, "");
+  };
+  const inner = norm(child);
+  const outer = norm(parent).replace(/^[\/]+/u, "");
+  if (inner === outer) return false;
+  if (outer === "") return true;
+  return inner.length > outer.length && inner.startsWith(outer) && /[\\/]/.test(inner.charAt(outer.length));
+}
+
+/**
+ * Whether two paths live on the same filesystem volume, where a rename is atomic.
+ * Falls back to "same volume" on platforms without a dev field.
+ * @param from - source path.
+ * @param to - destination path.
+ * @returns whether the paths share a device.
+ */
+export async function sameDevice(from, to) {
+  const nearest = async (path) => {
+    let cursor = path;
+    for (;;) {
+      try {
+        const info = await stat(cursor);
+        return info;
+      } catch (error) {
+        if (!isMissing(error)) throw error;
+      }
+      const parent = dirname(cursor);
+      if (parent === cursor) return undefined;
+      cursor = parent;
+    }
+  };
+  const [left, right] = await Promise.all([nearest(from), nearest(dirname(to))]);
+  if (left === undefined || right === undefined) return true;
+  if (typeof left.dev === "number" && typeof right.dev === "number") return left.dev === right.dev;
+  return parse(resolve(from)).root.toLowerCase() === parse(resolve(to)).root.toLowerCase();
+}
+
+/**
+ * Recursively copy a tree, preserving symlinks as links instead of following them.
+ * @param from - source root.
+ * @param to - destination root (must not exist).
+ * @param progress - optional callback receiving the number of entries copied.
+ */
+export async function copyTree(from, to, progress) {
+  let copied = 0;
+  const walk = async (source, target) => {
+    const info = await lstat(source);
+    if (info.isSymbolicLink()) return; // links are reported by the caller, never followed
+    if (info.isDirectory()) {
+      await mkdir(target, { recursive: false });
+      const entries = await readdir(source, { withFileTypes: true });
+      for (const entry of entries) await walk(join(source, entry.name), join(target, entry.name));
+      copied += 1;
+      progress?.(copied);
+      return;
+    }
+    await copyFile(source, target, constants.COPYFILE_EXCL);
+    copied += 1;
+    if (copied % 64 === 0) progress?.(copied);
+  };
+  await walk(from, to);
+  return copied;
+}
+
+/**
+ * Compare two trees entry by entry (names, kinds, sizes, link targets) without
+ * reading file contents — the verification a cross-volume `mv` performs before
+ * the source is removed.
+ * @param left - original root.
+ * @param right - copied root.
+ * @returns the first mismatch description, or undefined when the trees agree.
+ */
+export async function compareTree(left, right) {
+  const walk = async (source, target) => {
+    const info = await lstat(source);
+    const mirror = await lstat(target).catch(() => undefined);
+    if (mirror === undefined) return `missing at destination: ${target}`;
+    if (info.isSymbolicLink() || mirror.isSymbolicLink()) {
+      if (!info.isSymbolicLink() || !mirror.isSymbolicLink()) return `entry type differs: ${source}`;
+      const [leftTarget, rightTarget] = await Promise.all([readlinkOf(source), readlinkOf(target)]);
+      return leftTarget === rightTarget ? undefined : `link target differs: ${source}`;
+    }
+    if (info.isDirectory() !== mirror.isDirectory()) return `entry type differs: ${source}`;
+    if (!info.isDirectory()) return info.size === mirror.size ? undefined : `size differs: ${source}`;
+    const entries = await readdir(source, { withFileTypes: true });
+    for (const entry of entries) {
+      const mismatch = await walk(join(source, entry.name), join(target, entry.name));
+      if (mismatch !== undefined) return mismatch;
+    }
+    return undefined;
+  };
+  return walk(left, right);
+}
+
+async function readlinkOf(path) {
+  const { readlink } = await import("node:fs/promises");
+  return readlink(path);
+}
+
+/**
+ * Move a directory: a same-volume rename when possible, otherwise copy, verify,
+ * then remove the source. The destination must not exist.
+ * @param from - source directory.
+ * @param to - destination directory.
+ * @param progress - optional progress callback.
+ * @returns how the directory travelled.
+ */
+export async function moveDirectory(from, to, progress) {
+  await mkdir(dirname(to), { recursive: true });
+  if (await sameDevice(from, to)) {
+    await rename(from, to);
+    return "rename";
+  }
+  await copyTree(from, to, progress);
+  const mismatch = await compareTree(from, to);
+  if (mismatch !== undefined) {
+    await rm(to, { recursive: true, force: true }).catch(() => {});
+    throw new MoveError("copy-mismatch", `copied tree did not match the source (${mismatch})`);
+  }
+  await rm(from, { recursive: true, force: true });
+  return "copy";
+}
+
+/**
+ * Remove a directory only when it is empty; a parent or a non-empty folder is
+ * never touched, so whatever else lives there survives.
+ * @param path - directory to remove if empty.
+ * @returns whether it was removed.
+ */
+export async function removeIfEmpty(path) {
+  try {
+    const entries = await readdir(path);
+    if (entries.length > 0) return false;
+    await rm(path, { recursive: false });
+    return true;
+  } catch (error) {
+    if (isMissing(error)) return true;
+    return false;
+  }
+}
+
+/**
+ * Validate a single folder-name segment the way the OS would refuse it.
+ * @param name - candidate folder name.
+ * @returns undefined when valid, otherwise a stable reason code.
+ */
+export function folderNameProblem(name) {
+  const trimmed = name.trim();
+  if (trimmed === "" || trimmed === "." || trimmed === "..") return "name-invalid";
+  if (/[\\/:*?"<>|\u0000-\u001f]/u.test(trimmed)) return "name-invalid";
+  if (trimmed.endsWith(".") || trimmed.endsWith(" ")) return "name-invalid";
+  if (isAbsolute(trimmed)) return "name-invalid";
+  return undefined;
+}

package/lib/host-api-client.js

@@ -0,0 +1,41 @@
+/**
+ * The Host API transport contract: the route prefix, the header every call
+ * carries, and the one call helper. Host code imports the constants only; the
+ * Client half carries its own copy of both the constants and the helper, because
+ * it is bundled for the browser and cannot import this module.
+ * @module @reed-io/dsh-workspace-move
+ */
+
+/** Stable route prefix of the Host API. */
+export const API_PREFIX = "/dsh-workspace-move/api";
+
+/** Header every Client call carries. */
+export const API_HEADER = "x-dsh-workspace-move";
+
+/**
+ * POST one action to the Host and unwrap its envelope.
+ * @param action - action name.
+ * @param body - JSON body.
+ * @returns the action result.
+ */
+export async function callHost(action, body = {}) {
+  const response = await fetch(`${API_PREFIX}/${action}`, {
+    method: "POST",
+    headers: { "content-type": "application/json", [API_HEADER]: "1" },
+    body: JSON.stringify(body),
+    credentials: "same-origin"
+  });
+  if (!response.ok) {
+    const error = new Error(`request failed with status ${response.status}`);
+    error.code = `http-${response.status}`;
+    throw error;
+  }
+  const envelope = await response.json();
+  if (envelope.ok !== true) {
+    const error = new Error(envelope.message ?? envelope.code ?? "request failed");
+    error.code = envelope.code;
+    error.details = envelope.details ?? {};
+    throw error;
+  }
+  return envelope.result;
+}