handmux 0.23.0 → 0.24.0

package/src/workspace/operations.js

@@ -1,252 +0,0 @@
-import crypto from 'node:crypto';
-
-const ACTIVE = new Set(['pending', 'running']);
-const TERMINAL = new Set(['succeeded', 'partial', 'failed']);
-
-function iso(now) {
-  return new Date(typeof now === 'function' ? now() : now).toISOString();
-}
-
-function errorMessage(error) {
-  return error instanceof Error ? error.message : String(error);
-}
-
-const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-const unavailableLock = async () => { throw new Error('workspace operation lock is unavailable'); };
-const INACTIVE_OPERATION = 'WORKSPACE_OPERATION_INACTIVE';
-
-export function normalizeRestoreRequest(request = {}) {
-  const checkpointId = typeof request.checkpointId === 'string' && request.checkpointId ? request.checkpointId : 'latest';
-  const rawSessions = Array.isArray(request.sessions) ? request.sessions : request.sessions ? [request.sessions] : [];
-  const sessions = [...new Set(rawSessions.filter((name) => typeof name === 'string' && name))].sort();
-  return { checkpointId, sessions, historical: request.historical === true };
-}
-
-export function restoreRequestHash(request) {
-  return crypto.createHash('sha256').update(JSON.stringify(normalizeRestoreRequest(request))).digest('hex');
-}
-
-export function createOperationManager({
-  store,
-  now = Date.now,
-  randomUUID = crypto.randomUUID,
-  pid = process.pid,
-  tryAcquireOperationLock = unavailableLock,
-  pendingGraceMs = 250,
-  wait = delay,
-} = {}) {
-  const values = new Map();
-  const activeByHash = new Map();
-  const localIds = new Set();
-
-  async function persist(operation) {
-    if (localIds.has(operation.id)) values.set(operation.id, operation);
-    await store.writeOperation(operation);
-    return operation;
-  }
-
-  async function readFresh(id) {
-    const result = await store.readOperation(id);
-    return result.status === 'ok' ? result.value : null;
-  }
-
-  async function assessExternal(operation, { allowPendingGrace = true } = {}) {
-    let current = await readFresh(operation.id);
-    if (!current) return { active: false, operation: null };
-    if (!ACTIVE.has(current?.status)) return { active: false, operation: current };
-    if (current.status === 'pending' && allowPendingGrace) {
-      const createdAt = Date.parse(current.createdAt);
-      const age = Number.isFinite(createdAt) ? Math.max(0, now() - createdAt) : Number.POSITIVE_INFINITY;
-      const remaining = pendingGraceMs - age;
-      if (remaining > 0) {
-        await wait(remaining);
-        current = await readFresh(current.id);
-        if (!current || !ACTIVE.has(current.status)) return { active: false, operation: current };
-      }
-    }
-    let handle;
-    try {
-      handle = await tryAcquireOperationLock({ operationId: `assess-${current.id}` });
-    } catch {
-      return { active: true, operation: current };
-    }
-    if (!handle) return { active: true, operation: current };
-    try {
-      current = await readFresh(current.id);
-      if (!current || !ACTIVE.has(current.status)) return { active: false, operation: current };
-      const interrupted = {
-        ...current,
-        status: 'interrupted',
-        error: 'restore interrupted by process restart; retry the restore',
-        completedAt: iso(now),
-        updatedAt: iso(now),
-      };
-      await store.writeOperation(interrupted);
-      return { active: false, operation: interrupted, interrupted: true };
-    } finally {
-      await handle.release();
-    }
-  }
-
-  async function findExternalActive(requestHash) {
-    const rows = typeof store.listOperations === 'function' ? await store.listOperations() : [];
-    for (const row of rows) {
-      if (row.status !== 'ok' || localIds.has(row.value?.id) || !ACTIVE.has(row.value?.status)) continue;
-      if (row.value.requestHash !== requestHash || row.value.requestHash !== restoreRequestHash(row.value.request)) continue;
-      const assessed = await assessExternal(row.value);
-      if (assessed.active) return assessed.operation;
-    }
-    return null;
-  }
-
-  async function execute(operation, runner, { deferRunning = false } = {}) {
-    let current = operation;
-    let running = false;
-    let terminalStatus = null;
-    const onRunning = async () => {
-      if (running) return current;
-      const persisted = await readFresh(current.id);
-      if (!persisted || !ACTIVE.has(persisted.status)) {
-        if (persisted) {
-          current = persisted;
-          if (localIds.has(current.id)) values.set(current.id, current);
-        } else {
-          localIds.delete(current.id);
-          values.delete(current.id);
-        }
-        const error = new Error(`restore operation ${current.id} is no longer active`);
-        error.code = INACTIVE_OPERATION;
-        error.operation = persisted;
-        throw error;
-      }
-      current = persisted;
-      current = await persist({
-        ...current,
-        status: 'running',
-        startedAt: iso(now),
-        updatedAt: iso(now),
-      });
-      running = true;
-      return current;
-    };
-    const onTerminal = async (value) => {
-      await onRunning();
-      const result = value instanceof Error
-        ? { status: 'failed', error: errorMessage(value) }
-        : value;
-      const requestedStatus = TERMINAL.has(result?.status) ? result.status : 'failed';
-      if (terminalStatus && requestedStatus !== terminalStatus) return current;
-      const status = terminalStatus || requestedStatus;
-      const candidate = {
-        ...current,
-        ...result,
-        status,
-        progress: { completed: result?.results?.length ?? current.progress.completed, total: current.progress.total },
-        completedAt: current.completedAt || iso(now),
-      };
-      if (terminalStatus && JSON.stringify(candidate) === JSON.stringify(current)) return current;
-      current = await persist({ ...candidate, updatedAt: iso(now) });
-      terminalStatus = status;
-      return current;
-    };
-    try {
-      if (!deferRunning) await onRunning();
-      const result = await runner({
-        operationId: current.id,
-        request: current.request,
-        onRunning,
-        onTerminal,
-        onProgress: async ({ completed, total, result: row }) => {
-          await onRunning();
-          const results = row ? [...(current.results || []), row] : (current.results || []);
-          current = await persist({
-            ...current,
-            progress: { completed, total },
-            results,
-            updatedAt: iso(now),
-          });
-        },
-      });
-      await onTerminal(result);
-    } catch (error) {
-      if (error?.code === INACTIVE_OPERATION) {
-        if (error.operation) current = error.operation;
-      } else {
-        try { await onTerminal(error); } catch { /* pending/running file is interrupted on restart */ }
-      }
-    } finally {
-      if (activeByHash.get(operation.requestHash) === operation.id) activeByHash.delete(operation.requestHash);
-    }
-    return current;
-  }
-
-  async function createPending(request) {
-    const normalized = normalizeRestoreRequest(request);
-    const requestHash = restoreRequestHash(normalized);
-    const existingId = activeByHash.get(requestHash);
-    if (existingId) return { reused: true, operation: values.get(existingId) };
-    const external = await findExternalActive(requestHash);
-    if (external) return { reused: true, operation: external };
-    const id = randomUUID();
-    const operation = {
-      id,
-      kind: 'workspace-restore',
-      status: 'pending',
-      request: normalized,
-      requestHash,
-      ownerPid: pid,
-      createdAt: iso(now),
-      updatedAt: iso(now),
-      startedAt: null,
-      completedAt: null,
-      progress: { completed: 0, total: 0 },
-      results: [],
-      mapping: null,
-      error: null,
-    };
-    localIds.add(id);
-    activeByHash.set(requestHash, id);
-    try {
-      await persist(operation);
-    } catch (error) {
-      activeByHash.delete(requestHash);
-      localIds.delete(id);
-      values.delete(id);
-      throw error;
-    }
-    return { reused: false, operation };
-  }
-
-  async function start(request, runner, options) {
-    const pending = await createPending(request);
-    if (pending.reused) {
-      return { operationId: pending.operation.id, status: pending.operation.status, reused: true };
-    }
-    Promise.resolve().then(() => execute(pending.operation, runner, options)).catch(() => {});
-    return { operationId: pending.operation.id, status: 'pending', reused: false };
-  }
-
-  async function run(request, runner, options) {
-    const pending = await createPending(request);
-    if (pending.reused) return pending.operation;
-    return execute(pending.operation, runner, options);
-  }
-
-  async function get(id) {
-    if (localIds.has(id) && values.has(id)) return values.get(id);
-    return readFresh(id);
-  }
-
-  async function interruptOrphans() {
-    const rows = typeof store.listOperations === 'function' ? await store.listOperations() : [];
-    let interrupted = 0;
-    for (const row of rows) {
-      if (row.status !== 'ok' || localIds.has(row.value?.id) || !ACTIVE.has(row.value?.status)) continue;
-      const assessed = await assessExternal(row.value);
-      if (assessed.interrupted) interrupted += 1;
-    }
-    return interrupted;
-  }
-
-  return { start, run, get, interruptOrphans };
-}

package/src/workspace/paths.js

@@ -1,16 +0,0 @@
-import path from 'node:path';
-
-export function workspacePaths(home) {
-  const root = path.join(home, '.handmux', 'workspaces');
-  return {
-    root,
-    liveDir: path.join(root, 'live'),
-    liveCurrent: path.join(root, 'live', 'current.json'),
-    liveMirror: path.join(root, 'live', 'mirror.json'),
-    checkpointsDir: path.join(root, 'checkpoints'),
-    recoveryDir: path.join(root, 'recovery'),
-    operationsDir: path.join(root, 'operations'),
-    latest: path.join(root, 'latest.json'),
-    lockDir: path.join(root, 'restore.lock'),
-  };
-}

package/src/workspace/planner.js

@@ -1,247 +0,0 @@
-function deepFreeze(value, seen = new Set()) {
-  if (!value || typeof value !== 'object' || seen.has(value)) return value;
-  seen.add(value);
-  for (const nested of Object.values(value)) deepFreeze(nested, seen);
-  return Object.freeze(value);
-}
-
-function uniqueStrings(values) {
-  return [...new Set(values.filter((value) => typeof value === 'string' && value))];
-}
-
-function stringOrNull(value) {
-  return typeof value === 'string' ? value : null;
-}
-
-function nonEmptyStringOrNull(value) {
-  return typeof value === 'string' && value ? value : null;
-}
-
-function indexOrNull(value) {
-  return Number.isInteger(value) && value >= 0 ? value : null;
-}
-
-function restoredName(sourceName, names) {
-  if (!names.has(sourceName)) return sourceName;
-  const restored = `${sourceName}-restored`;
-  if (!names.has(restored)) return restored;
-  for (let suffix = 2; ; suffix += 1) {
-    const candidate = `${restored}-${suffix}`;
-    if (!names.has(candidate)) return candidate;
-  }
-}
-
-function runtimeIdList(items, kind) {
-  return items.map((item) => {
-    const runtimeId = nonEmptyStringOrNull(item?.runtimeId);
-    if (runtimeId === null) throw new Error(`invalid live ${kind} runtime id`);
-    return runtimeId;
-  });
-}
-
-function runtimeIds(live) {
-  const sessions = Array.isArray(live?.sessions) ? live.sessions : [];
-  const windows = Array.isArray(live?.windows) ? live.windows : [];
-  const panes = windows.flatMap((window) => Array.isArray(window?.panes) ? window.panes : []);
-  return {
-    sessions: runtimeIdList(sessions, 'session'),
-    windows: runtimeIdList(windows, 'window'),
-    panes: runtimeIdList(panes, 'pane'),
-  };
-}
-
-function countTopology(windows) {
-  const panes = windows.flatMap((window) => Array.isArray(window.panes) ? window.panes : []);
-  return {
-    windows: windows.length,
-    panes: panes.length,
-    agents: panes.filter((pane) => pane.agent !== null && pane.agent !== undefined).length,
-  };
-}
-
-function warningList(...sources) {
-  return uniqueStrings(sources.flatMap((source) => Array.isArray(source) ? source : [source]));
-}
-
-function unwrapCheckpoint(input) {
-  if (input?.status === 'ok' && input.value) {
-    return { checkpoint: input.value, warnings: warningList(input.warnings, input.warning) };
-  }
-  return { checkpoint: input, warnings: warningList(input?.warnings, input?.warning) };
-}
-
-function linkedOwners(sessions) {
-  const owners = new Map();
-  for (const session of sessions) {
-    if (!Array.isArray(session?.windowLinks)) continue;
-    for (const link of session.windowLinks) {
-      if (typeof link?.windowId !== 'string') continue;
-      if (!owners.has(link.windowId)) owners.set(link.windowId, new Set());
-      owners.get(link.windowId).add(session.id);
-    }
-  }
-  return owners;
-}
-
-function topologyIssue(session, windowsById, owners, supportsLinkedWindows) {
-  if (!Array.isArray(session.windowLinks) || session.windowLinks.length === 0) return 'missing-window-links';
-  const ids = session.windowLinks.map((link) => link?.windowId);
-  const indexes = session.windowLinks.map((link) => link?.index);
-  if (ids.some((id) => typeof id !== 'string' || !id)) return 'invalid-window-link';
-  if (indexes.some((index) => !Number.isInteger(index) || index < 0)) return 'invalid-window-link-index';
-  if (new Set(ids).size !== ids.length) return 'duplicate-window-link';
-  if (new Set(indexes).size !== indexes.length) return 'duplicate-window-link-index';
-  if (ids.some((id) => !windowsById.has(id))) return 'dangling-window-link';
-  if (!ids.includes(session.activeWindowId)) return 'dangling-active-window';
-  if (!supportsLinkedWindows && ids.some((id) => owners.get(id)?.size > 1)) return 'linked-windows-unsupported';
-
-  for (const id of ids) {
-    const window = windowsById.get(id);
-    if (!Array.isArray(window.panes) || window.panes.length === 0) return 'missing-window-panes';
-    const paneIds = window.panes.map((pane) => pane?.id);
-    if (paneIds.some((paneId) => typeof paneId !== 'string' || !paneId)) return 'invalid-pane';
-    if (new Set(paneIds).size !== paneIds.length) return 'duplicate-pane';
-    if (!paneIds.includes(window.activePaneId)) return 'dangling-active-pane';
-  }
-  return null;
-}
-
-function sourceProjection(session) {
-  const validSession = session && typeof session === 'object' && !Array.isArray(session);
-  const rawLinks = validSession && Array.isArray(session.windowLinks) ? session.windowLinks : [];
-  const source = {
-    logicalId: nonEmptyStringOrNull(validSession ? session.id : null),
-    sourceName: nonEmptyStringOrNull(validSession ? session.name : null),
-    activeWindowId: nonEmptyStringOrNull(validSession ? session.activeWindowId : null),
-    windowLinks: rawLinks.map((link) => ({
-      windowId: nonEmptyStringOrNull(link && typeof link === 'object' && !Array.isArray(link) ? link.windowId : null),
-      index: indexOrNull(link && typeof link === 'object' && !Array.isArray(link) ? link.index : null),
-    })),
-  };
-  let issue = null;
-  if (!validSession) issue = 'invalid-session';
-  else if (source.logicalId === null) issue = 'invalid-session-id';
-  else if (source.sourceName === null) issue = 'invalid-session-name';
-  else if (source.activeWindowId === null) issue = 'invalid-active-window-id';
-  else if (!Array.isArray(session.windowLinks)) issue = 'invalid-window-links';
-  else if (source.windowLinks.some((link) => link.windowId === null)) issue = 'invalid-window-link';
-  else if (source.windowLinks.some((link) => link.index === null)) issue = 'invalid-window-link-index';
-  return { source, issue };
-}
-
-function activeProjection(active) {
-  if (active === null || active === undefined) return null;
-  return {
-    sessionId: stringOrNull(active.sessionId),
-    windowId: stringOrNull(active.windowId),
-    paneId: stringOrNull(active.paneId),
-  };
-}
-
-function selectedTopology(items, windowsById) {
-  const windowIds = new Set();
-  for (const item of items) {
-    if (item.action !== 'create' && item.action !== 'create-renamed') continue;
-    for (const link of item.windowLinks) windowIds.add(link.windowId);
-  }
-  return [...windowIds].map((id) => windowsById.get(id)).filter(Boolean);
-}
-
-function windowDispositions(items, live) {
-  const liveWindows = new Map((Array.isArray(live?.windows) ? live.windows : []).map((window) => [window.id, window.runtimeId]));
-  const dispositions = new Map();
-  for (const item of items) {
-    if (item.action !== 'create' && item.action !== 'create-renamed') continue;
-    for (const { windowId } of item.windowLinks) {
-      if (dispositions.has(windowId)) continue;
-      if (liveWindows.has(windowId)) {
-        const runtimeId = nonEmptyStringOrNull(liveWindows.get(windowId));
-        if (runtimeId === null) throw new Error('invalid live window runtime id');
-        dispositions.set(windowId, { logicalId: nonEmptyStringOrNull(windowId), action: 'reuse', runtimeId });
-      } else {
-        dispositions.set(windowId, {
-          logicalId: nonEmptyStringOrNull(windowId),
-          action: 'create',
-          ownerSessionId: nonEmptyStringOrNull(item.logicalId),
-        });
-      }
-    }
-  }
-  return [...dispositions.values()];
-}
-
-export function buildRestorePlan(checkpointInput, live, {
-  sessionNames = [],
-  recovery = null,
-  historical = false,
-  supportsLinkedWindows = true,
-  warnings = [],
-  warning = null,
-} = {}) {
-  const unwrapped = unwrapCheckpoint(checkpointInput);
-  const checkpoint = unwrapped.checkpoint;
-  if (!checkpoint || !Array.isArray(checkpoint.sessions) || !Array.isArray(checkpoint.windows)) {
-    throw new Error('invalid checkpoint for restore planning');
-  }
-  if (recovery !== null && recovery?.checkpointId !== checkpoint.id) {
-    throw new Error('recovery checkpoint id mismatch');
-  }
-
-  const windowsById = new Map(checkpoint.windows.map((window) => [window.id, window]));
-  const owners = linkedOwners(checkpoint.sessions);
-  const pendingIds = recovery && Array.isArray(recovery.pendingSessionIds)
-    ? new Set(recovery.pendingSessionIds)
-    : null;
-  const requestedNames = new Set(Array.isArray(sessionNames) ? sessionNames : [sessionNames]);
-  const selected = checkpoint.sessions.filter((session) => {
-    if (!historical && pendingIds && !pendingIds.has(session?.id)) return false;
-    return requestedNames.size === 0 || requestedNames.has(session?.name);
-  });
-
-  const currentSessions = Array.isArray(live?.sessions) ? live.sessions : [];
-  const logicalIds = new Set(currentSessions.map((session) => session.id));
-  const names = new Set(currentSessions.map((session) => session.name));
-  const sessions = selected.map((session) => {
-    const { source, issue } = sourceProjection(session);
-    if (issue) return { ...source, action: 'unsupported', reason: issue };
-    if (logicalIds.has(source.logicalId)) return { ...source, action: 'already-present' };
-    const reason = topologyIssue(source, windowsById, owners, supportsLinkedWindows);
-    if (reason) return { ...source, action: 'unsupported', reason };
-    const targetName = restoredName(source.sourceName, names);
-    names.add(targetName);
-    return {
-      ...source,
-      targetName,
-      action: targetName === source.sourceName ? 'create' : 'create-renamed',
-    };
-  });
-
-  const actions = { create: 0, renamed: 0, alreadyPresent: 0, unsupported: 0 };
-  for (const session of sessions) {
-    if (session.action === 'create') actions.create += 1;
-    else if (session.action === 'create-renamed') actions.renamed += 1;
-    else if (session.action === 'already-present') actions.alreadyPresent += 1;
-    else if (session.action === 'unsupported') actions.unsupported += 1;
-  }
-
-  const checkpointTopology = countTopology(checkpoint.windows);
-  const planTopology = countTopology(selectedTopology(sessions, windowsById));
-  const plan = {
-    checkpointId: stringOrNull(checkpoint.id),
-    capturedAt: stringOrNull(checkpoint.capturedAt),
-    archivedAt: stringOrNull(checkpoint.archivedAt),
-    changeReason: stringOrNull(checkpoint.environment?.endedReason),
-    detectedAt: stringOrNull(recovery?.detectedAt),
-    expiresAt: stringOrNull(recovery?.expiresAt),
-    resolved: Boolean(recovery?.resolvedAt),
-    pendingCount: pendingIds?.size ?? null,
-    summary: { sessions: checkpoint.sessions.length, ...checkpointTopology },
-    planSummary: { ...actions, ...planTopology },
-    sessions,
-    windows: windowDispositions(sessions, live),
-    active: activeProjection(checkpoint.active),
-    preExistingRuntimeIds: runtimeIds(live),
-    warnings: warningList(unwrapped.warnings, checkpoint.warnings, checkpoint.warning, warnings, warning),
-  };
-  return deepFreeze(plan);
-}