handmux 0.23.0 → 0.25.0

package/dist/src/workspace/operations.js

@@ -0,0 +1,271 @@
+import crypto from 'node:crypto';
+const ACTIVE = new Set(['pending', 'running']);
+const TERMINAL = new Set(['succeeded', 'partial', 'failed']);
+const recordOf = (value) => (value && typeof value === 'object' && !Array.isArray(value)
+    ? value : null);
+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 record = recordOf(request) ?? {};
+    const checkpointId = typeof record.checkpointId === 'string' && record.checkpointId ? record.checkpointId : 'latest';
+    const rawSessions = Array.isArray(record.sessions) ? record.sessions : record.sessions ? [record.sessions] : [];
+    const sessions = [...new Set(rawSessions.filter((name) => typeof name === 'string' && Boolean(name)))].sort();
+    return { checkpointId, sessions, historical: record.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 ? 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) {
+            const value = row.value;
+            if (row.status !== 'ok' || !value || localIds.has(value.id) || !ACTIVE.has(value.status))
+                continue;
+            if (value.requestHash !== requestHash || value.requestHash !== restoreRequestHash(value.request))
+                continue;
+            const assessed = await assessExternal(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) }
+                : recordOf(value) ?? { status: 'failed', error: errorMessage(value) };
+            const requestedStatus = typeof result.status === 'string' && TERMINAL.has(result.status) ? result.status : 'failed';
+            if (terminalStatus && requestedStatus !== terminalStatus)
+                return current;
+            const status = terminalStatus || requestedStatus;
+            const candidate = {
+                ...current,
+                ...result,
+                status,
+                progress: {
+                    completed: Array.isArray(result.results) ? 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 && typeof error === 'object' && 'code' in error && error.code === INACTIVE_OPERATION) {
+                const inactive = error;
+                if (inactive.operation)
+                    current = inactive.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) {
+            const existing = values.get(existingId);
+            if (existing)
+                return { reused: true, operation: existing };
+            activeByHash.delete(requestHash);
+        }
+        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) ?? null;
+        return readFresh(id);
+    }
+    async function interruptOrphans() {
+        const rows = typeof store.listOperations === 'function' ? await store.listOperations() : [];
+        let interrupted = 0;
+        for (const row of rows) {
+            const value = row.value;
+            if (row.status !== 'ok' || !value || localIds.has(value.id) || !ACTIVE.has(value.status))
+                continue;
+            const assessed = await assessExternal(value);
+            if (assessed.interrupted)
+                interrupted += 1;
+        }
+        return interrupted;
+    }
+    return { start, run, get, interruptOrphans };
+}

package/dist/src/workspace/paths.js

@@ -0,0 +1,15 @@
+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/dist/src/workspace/planner.js

@@ -0,0 +1,292 @@
+const recordOf = (value) => (value && typeof value === 'object' && !Array.isArray(value) ? value : null);
+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' && Boolean(value)))];
+}
+function stringOrNull(value) {
+    return typeof value === 'string' ? value : null;
+}
+function nonEmptyStringOrNull(value) {
+    return typeof value === 'string' && value ? value : null;
+}
+function indexOrNull(value) {
+    return typeof value === 'number' && 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(recordOf(item)?.runtimeId);
+        if (runtimeId === null)
+            throw new Error(`invalid live ${kind} runtime id`);
+        return runtimeId;
+    });
+}
+function runtimeIds(live) {
+    const record = recordOf(live);
+    const sessions = Array.isArray(record?.sessions) ? record.sessions : [];
+    const windows = Array.isArray(record?.windows) ? record.windows : [];
+    const panes = windows.flatMap((window) => {
+        const panesValue = recordOf(window)?.panes;
+        return Array.isArray(panesValue) ? panesValue : [];
+    });
+    return {
+        sessions: runtimeIdList(sessions, 'session'),
+        windows: runtimeIdList(windows, 'window'),
+        panes: runtimeIdList(panes, 'pane'),
+    };
+}
+function countTopology(windows) {
+    const panes = windows.flatMap((window) => {
+        const panesValue = recordOf(window)?.panes;
+        return Array.isArray(panesValue) ? panesValue : [];
+    });
+    return {
+        windows: windows.length,
+        panes: panes.length,
+        agents: panes.filter((pane) => {
+            const agent = recordOf(pane)?.agent;
+            return agent !== null && agent !== undefined;
+        }).length,
+    };
+}
+function warningList(...sources) {
+    return uniqueStrings(sources.flatMap((source) => Array.isArray(source) ? source : [source]));
+}
+function unwrapCheckpoint(input) {
+    const record = recordOf(input);
+    if (record?.status === 'ok' && record.value) {
+        return { checkpoint: record.value, warnings: warningList(record.warnings, record.warning) };
+    }
+    return { checkpoint: input, warnings: warningList(record?.warnings, record?.warning) };
+}
+function linkedOwners(sessions) {
+    const owners = new Map();
+    for (const candidate of sessions) {
+        const session = recordOf(candidate);
+        if (!session || !Array.isArray(session.windowLinks))
+            continue;
+        for (const candidateLink of session.windowLinks) {
+            const link = recordOf(candidateLink);
+            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) => typeof index !== 'number' || !Number.isInteger(index) || index < 0))
+        return 'invalid-window-link-index';
+    const validIds = ids;
+    const validIndexes = indexes;
+    if (new Set(validIds).size !== validIds.length)
+        return 'duplicate-window-link';
+    if (new Set(validIndexes).size !== validIndexes.length)
+        return 'duplicate-window-link-index';
+    if (validIds.some((id) => !windowsById.has(id)))
+        return 'dangling-window-link';
+    if (!validIds.includes(session.activeWindowId))
+        return 'dangling-active-window';
+    if (!supportsLinkedWindows && validIds.some((id) => (owners.get(id)?.size ?? 0) > 1))
+        return 'linked-windows-unsupported';
+    for (const id of validIds) {
+        const window = windowsById.get(id);
+        if (!window || !Array.isArray(window.panes) || window.panes.length === 0)
+            return 'missing-window-panes';
+        const paneIds = window.panes.map((pane) => recordOf(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 record = validSession ? session : null;
+    const rawLinks = record && Array.isArray(record.windowLinks) ? record.windowLinks : [];
+    const source = {
+        logicalId: nonEmptyStringOrNull(record?.id),
+        sourceName: nonEmptyStringOrNull(record?.name),
+        activeWindowId: nonEmptyStringOrNull(record?.activeWindowId),
+        windowLinks: rawLinks.map((link) => ({
+            windowId: nonEmptyStringOrNull(recordOf(link)?.windowId),
+            index: indexOrNull(recordOf(link)?.index),
+        })),
+    };
+    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(record?.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;
+    const record = recordOf(active) ?? {};
+    return {
+        sessionId: stringOrNull(record.sessionId),
+        windowId: stringOrNull(record.windowId),
+        paneId: stringOrNull(record.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].flatMap((id) => {
+        const window = windowsById.get(id);
+        return window ? [window] : [];
+    });
+}
+function windowDispositions(items, live) {
+    const liveRecord = recordOf(live);
+    const liveWindows = new Map((Array.isArray(liveRecord?.windows) ? liveRecord.windows : []).map((window) => {
+        const record = recordOf(window);
+        return [record?.id, record?.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 = recordOf(unwrapped.checkpoint);
+    if (!checkpoint || !Array.isArray(checkpoint.sessions) || !Array.isArray(checkpoint.windows)) {
+        throw new Error('invalid checkpoint for restore planning');
+    }
+    const recoveryRecord = recordOf(recovery);
+    if (recovery !== null && recoveryRecord?.checkpointId !== checkpoint.id) {
+        throw new Error('recovery checkpoint id mismatch');
+    }
+    const windowsById = new Map(checkpoint.windows.flatMap((window) => {
+        const record = recordOf(window);
+        return record ? [[record.id, record]] : [];
+    }));
+    const owners = linkedOwners(checkpoint.sessions);
+    const pendingIds = recoveryRecord && Array.isArray(recoveryRecord.pendingSessionIds)
+        ? new Set(recoveryRecord.pendingSessionIds)
+        : null;
+    const requestedNames = new Set(Array.isArray(sessionNames) ? sessionNames : [sessionNames]);
+    const selected = checkpoint.sessions.filter((session) => {
+        const record = recordOf(session);
+        if (!historical && pendingIds && !pendingIds.has(record?.id))
+            return false;
+        return requestedNames.size === 0 || requestedNames.has(record?.name);
+    });
+    const liveRecord = recordOf(live);
+    const currentSessions = Array.isArray(liveRecord?.sessions) ? liveRecord.sessions : [];
+    const logicalIds = new Set(currentSessions.map((session) => recordOf(session)?.id));
+    const names = new Set(currentSessions.map((session) => recordOf(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(recordOf(checkpoint.environment)?.endedReason),
+        detectedAt: stringOrNull(recoveryRecord?.detectedAt),
+        expiresAt: stringOrNull(recoveryRecord?.expiresAt),
+        resolved: Boolean(recoveryRecord?.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);
+}