handmux 0.23.0 → 0.25.0

package/dist/src/routes/terminal.js

@@ -0,0 +1,244 @@
+// Terminal pane I/O routes: read the screen (/history), type text/keys, resize/reflow, and forward
+// wheel scroll to full-screen apps. This is the hot path the phone polls. Mounted under /api.
+import express from 'express';
+import { createHash } from 'node:crypto';
+import { gzipSync } from 'node:zlib';
+import { isPaneId, isWindowId } from '../tmux/commands.js';
+import { capTrailingBlankRows } from '../trimCapture.js';
+import { isAllowedKey } from '../keyNames.js';
+import { restoreCaptureBackgrounds } from '../captureBackground.js';
+import { serializePaneInput } from '../paneInput.js';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const requestBody = (req) => isRecord(req.body) ? req.body : {};
+export { isAllowedKey } from '../keyNames.js';
+// Keys the mobile keyboard may send via /keys. A controlled vocabulary of named tmux keys, PLUS
+// live-modifier combinations (Ctrl/Alt + a single letter or digit) so the keyboard's Ctrl modifier
+// can compose any readline/tmux binding (C-r, C-w, C-a, the tmux prefix, …) without enumerating each
+// one here. tmux send-keys key names are themselves a closed set, so this stays a strict allowlist
+// (never a passthrough): a key either names an approved token or matches the modifier shape, or it's
+// rejected. The old fixed C-c/C-d/C-z/C-l/C-r/C-o/C-e all still match `C-[a-z0-9]`.
+// Keep a short fallback gap for applications that do not negotiate bracketed paste. Supporting TUIs get
+// an explicit paste boundary from commands.sendText; the delay is no longer the correctness mechanism.
+const RAW_INPUT_MAX_BYTES = 16 * 1024;
+const SUBMIT_GAP_MS = 120;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const validHexInput = (hex) => typeof hex === 'string'
+    && hex.length >= 2
+    && hex.length <= RAW_INPUT_MAX_BYTES * 2
+    && hex.length % 2 === 0
+    && /^[0-9a-f]+$/i.test(hex);
+const isMissingPane = (error) => /(?:can't find|cannot find|no such|unknown|not found).*\bpane\b|\bpane\b.*(?:can't find|cannot find|no such|unknown|not found)/i
+    .test(error instanceof Error ? error.message : String(error));
+export function terminalRoutes({ commands }) {
+    const r = express.Router();
+    r.get('/history', async (req, res, next) => {
+        const paneId = req.query.pane;
+        if (!isPaneId(paneId))
+            return res.status(400).json({ error: 'bad pane id' });
+        const lines = Math.min(Math.max(Number(req.query.lines) || 1000, 1), 5000);
+        try {
+            // Read the pane's state FIRST — whether it's on the alternate screen decides how we capture it.
+            const { width, height, cursorX, cursorY, cursorVisible, altScreen, mouseAware } = await commands.paneInfo(paneId);
+            // An ALT-screen pane (a full-screen app: vim/less/htop) is a fixed height×width screen with NO
+            // scrollback. Asking tmux for history (-S -lines) there bleeds the MAIN screen's scrollback in
+            // ABOVE the app — you'd scroll up into terminal history that isn't the app's — and capping its
+            // trailing blank rows mangles the fixed screen (those blanks are real cells). So capture an alt
+            // pane as exactly its visible screen (lines=0) and skip the blank-trim. A normal pane still pulls
+            // `lines` of scrollback and caps the empty grid below the cursor (fresh shell = "prompt + a wall of
+            // blank rows") so the phone's bottom-anchored render shows content, not blank. See trimCapture.js.
+            const captured = await commands.capturePane(paneId, altScreen ? 0 : lines);
+            const capturePaneRow = commands.capturePaneRow;
+            const restored = typeof capturePaneRow === 'function'
+                ? await restoreCaptureBackgrounds(captured, height, (row) => capturePaneRow(paneId, row))
+                : {
+                    ansi: captured,
+                    historyLines: Math.max(0, (captured.endsWith('\n') ? captured.slice(0, -1) : captured).split('\n').length - height),
+                };
+            const raw = restored.ansi;
+            const ansi = altScreen ? raw : capTrailingBlankRows(raw);
+            // The cursor's row counted from the BOTTOM of the (trimmed) capture. The live screen is the
+            // capture's last `height` rows, so the cursor sits `height-1-cursorY` rows above the bottom —
+            // less however many trailing blank rows capTrailingBlankRows dropped (all of them below the
+            // cursor). The client re-places xterm's cursor this many rows up from the seed's last row.
+            const rowsOf = (value) => (value.endsWith('\n') ? value.slice(0, -1) : value).split('\n').length;
+            const historyLines = altScreen ? 0 : restored.historyLines;
+            const cur = {
+                row: Math.max(0, (height - 1 - cursorY) - (rowsOf(raw) - rowsOf(ansi))),
+                col: cursorX, vis: cursorVisible,
+            };
+            // Short content hash over size + cursor + ansi. The client echoes its last hash as ?since=… ;
+            // an unchanged screen returns 204 (empty) so an idle pane stops re-sending the whole capture.
+            // The cursor is folded in so a bare left/right (which moves the cursor but not the text) still
+            // yields a fresh frame — otherwise the move would 204 and the cursor would never visibly track.
+            // mouseAware is folded in too: toggling an app's mouse mode (e.g. `:set mouse=a` in vim) changes
+            // whether a swipe should wheel-scroll or just hint, and the client only re-reads it on a fresh frame.
+            const hash = createHash('sha1')
+                .update(`${width}x${height}\n${cur.col},${cursorY},${cur.vis ? 1 : 0}\n${altScreen ? 1 : 0}${mouseAware ? 'm' : ''}\n${ansi}`)
+                .digest('hex').slice(0, 16);
+            if (req.query.since === hash)
+                return res.status(204).end();
+            const json = JSON.stringify({
+                ansi, width, height, historyLines, hash, cur, alt: altScreen, mouseAware,
+            });
+            res.set('Content-Type', 'application/json');
+            res.set('Vary', 'Accept-Encoding'); // both 200 branches vary on encoding (correct for any caching proxy)
+            // Capture text is mostly SGR codes + spaces — gzip crushes it ~10x. (204s are empty, never gzipped.)
+            if (/\bgzip\b/.test(req.headers['accept-encoding'] || '')) {
+                res.set('Content-Encoding', 'gzip');
+                // gzipSync is fine here — captures are KBs; the event-loop stall is sub-ms.
+                return res.end(gzipSync(json));
+            }
+            else {
+                return res.end(json);
+            }
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    r.post('/send', async (req, res, next) => {
+        const { pane, text, enter } = requestBody(req);
+        if (!isPaneId(pane))
+            return res.status(400).json({ error: 'bad pane id' });
+        const body = typeof text === 'string' ? text : '';
+        try {
+            await serializePaneInput(pane, async () => {
+                await commands.exitCopyModeIfActive(pane);
+                await commands.sendText(pane, body);
+                if (enter) {
+                    if (body)
+                        await delay(SUBMIT_GAP_MS); // a bare Enter has nothing to settle — send at once
+                    await commands.sendEnter(pane);
+                }
+            });
+            return res.json({ ok: true });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    r.post('/input', async (req, res, next) => {
+        const { pane, hex } = requestBody(req);
+        if (!isPaneId(pane))
+            return res.status(400).json({ error: 'bad pane id' });
+        if (!validHexInput(hex))
+            return res.status(400).json({ error: 'bad input bytes' });
+        try {
+            await serializePaneInput(pane, async () => {
+                await commands.exitCopyModeIfActive(pane);
+                await commands.sendHexInput(pane, hex);
+            });
+            return res.json({ ok: true });
+        }
+        catch (error) {
+            if (isMissingPane(error))
+                return res.status(404).json({ error: 'pane not found' });
+            return next(error);
+        }
+    });
+    // Resize the tmux window so it reflows to the phone (auto:false), or hand sizing back to
+    // attached clients (auto:true). NOTE: this mutates the shared window — the PC's view of it
+    // changes too.
+    r.get('/layout', async (req, res, next) => {
+        if (!isWindowId(req.query.window))
+            return res.status(400).json({ error: 'bad window id' });
+        try {
+            return res.json({ layout: await commands.getWindowLayout(req.query.window) });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    // Restore only the pane arrangement. Window sizing remains untouched; handing the whole window
+    // back to an attached client is the separate `auto` resize operation below.
+    r.post('/layout', async (req, res, next) => {
+        const { window, layout } = requestBody(req);
+        if (!isWindowId(window))
+            return res.status(400).json({ error: 'bad window id' });
+        if (typeof layout !== 'string' || !layout)
+            return res.status(400).json({ error: 'bad window layout' });
+        try {
+            await commands.applyWindowLayout(window, layout);
+            return res.json({ ok: true });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    r.post('/resize', async (req, res, next) => {
+        const { window, pane, cols, rows, auto, layout } = requestBody(req);
+        const c = Math.min(Math.max(Number(cols) || 0, 20), 500);
+        try {
+            if (auto) {
+                if (!isWindowId(window))
+                    return res.status(400).json({ error: 'bad window id' });
+                // restore the split arrangement (resizePane) then hand window sizing back (resizeWindow)
+                if (typeof layout === 'string' && layout)
+                    await commands.applyWindowLayout(window, layout);
+                await commands.restoreWindowSize(window);
+            }
+            else if (isPaneId(pane)) {
+                await commands.resizePane(pane, c); // a pane in a split — resize only it
+            }
+            else if (isWindowId(window)) {
+                const rw = rows != null ? Math.min(Math.max(Number(rows) || 0, 5), 500) : null;
+                await commands.resizeWindow(window, c, rw); // a lone pane fills the window
+            }
+            else {
+                return res.status(400).json({ error: 'bad resize target' });
+            }
+            return res.json({ ok: true });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    r.post('/keys', async (req, res, next) => {
+        const { pane, keys } = requestBody(req);
+        if (!isPaneId(pane))
+            return res.status(400).json({ error: 'bad pane id' });
+        if (!Array.isArray(keys) || keys.some((k) => !isAllowedKey(k))) {
+            return res.status(400).json({ error: 'disallowed key' });
+        }
+        try {
+            await serializePaneInput(pane, async () => {
+                await commands.exitCopyModeIfActive(pane);
+                for (const k of keys)
+                    await commands.sendKey(pane, k);
+            });
+            return res.json({ ok: true });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    // Swipe-to-scroll for full-screen (ALT-screen) apps: the client can't scroll the alt buffer itself
+    // (no scrollback), so it forwards the finger travel here and we inject wheel events the app scrolls on.
+    // SAFETY: we re-read the pane's mouse state at inject time and REFUSE unless it's actually reporting
+    // mouse — otherwise the raw escape bytes would print into the shell as literal `<65;…M` garbage. The
+    // client's cached mouseAware is only a UX hint; this check is the real guard (mouse mode can toggle
+    // between the poll and the gesture). Positioned at the pane centre so a split-aware app scrolls the
+    // region the finger is over; a lone full-screen app ignores the position.
+    r.post('/scroll', async (req, res, next) => {
+        const { pane, dir, lines } = requestBody(req);
+        if (!isPaneId(pane))
+            return res.status(400).json({ error: 'bad pane id' });
+        if (dir !== 'up' && dir !== 'down')
+            return res.status(400).json({ error: 'bad dir' });
+        try {
+            const { altScreen, mouseAware, mouseSgr, width, height } = await commands.paneInfo(pane);
+            if (!altScreen || !mouseAware)
+                return res.json({ ok: false, reason: 'no-mouse' });
+            await commands.sendWheel(pane, dir, Number(lines), {
+                sgr: mouseSgr,
+                col: Math.max(1, Math.floor((width || 2) / 2)),
+                row: Math.max(1, Math.floor((height || 2) / 2)),
+            });
+            return res.json({ ok: true });
+        }
+        catch (e) {
+            return next(e);
+        }
+    });
+    return r;
+}

package/dist/src/routes/workspace.js

@@ -0,0 +1,267 @@
+import express from 'express';
+import { validateRecoveryMapping } from '../workspace/mapping.js';
+import { isWorkspaceSafeId, parseWorkspaceRestoreRequest, } from '../workspaceProtocol.js';
+const CHANGE_REASONS = new Set(['boot-changed', 'tmux-changed']);
+const OPERATION_STATUSES = new Set(['pending', 'running', 'succeeded', 'partial', 'failed', 'interrupted']);
+const RESULT_STATUSES = new Set(['restored', 'already-present', 'failed']);
+const RESULT_STAGES = new Set(['plan', 'topology', 'agent', 'restore', 'reconcile']);
+const WARNING_CODES = new Set(['cwd-fallback', 'layout-fallback', 'agent-warning', 'live-reconcile-failed', 'workspace-unavailable', 'restore-warning']);
+const ERROR_MESSAGES = {
+    'restore-interrupted': 'restore was interrupted; retry the restore',
+    'checkpoint-not-found': 'checkpoint is unavailable; choose another checkpoint',
+    'storage-full': 'workspace storage is full; free disk space and retry',
+    'permission-denied': 'workspace storage is not writable; check permissions and retry',
+    'plan-failed': 'restore plan is no longer usable; refresh and retry',
+    'agent-unavailable': 'agent resume failed; open the restored shell and retry manually',
+    'tmux-unavailable': 'tmux is unavailable; retry the restore',
+    'restore-failed': 'workspace restore failed; retry the restore',
+};
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const record = (value) => (typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : null);
+function isCheckpointMissing(error) {
+    const details = record(error);
+    if (details?.code === 'WORKSPACE_CHECKPOINT_NOT_FOUND' || details?.status === 404)
+        return true;
+    const message = error instanceof Error ? error.message : String(error);
+    return /(?:checkpoint.*(?:missing|not found)|no valid checkpoint)/i.test(message);
+}
+function sendFailure(res, error, { checkpoint = false } = {}) {
+    if (checkpoint && isCheckpointMissing(error)) {
+        return res.status(404).json({ error: 'checkpoint not found' });
+    }
+    return res.status(500).json({ error: 'workspace unavailable' });
+}
+function asyncHandler(handler, options = {}) {
+    return async (req, res) => {
+        try {
+            await handler(req, res);
+        }
+        catch (error) {
+            sendFailure(res, error, options);
+        }
+    };
+}
+function checkpointId(value, fallback) {
+    const id = value === undefined ? fallback : value;
+    return isWorkspaceSafeId(id) ? id : null;
+}
+function timestamp(value) {
+    return typeof value === 'string' && Number.isFinite(Date.parse(value)) ? value : null;
+}
+function count(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+function displayName(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= 256
+        && !/[\x00-\x1f\x7f]/.test(value) ? value : null;
+}
+function projectCheckpoint(row) {
+    const source = record(row);
+    const id = isWorkspaceSafeId(source?.id) ? source.id : null;
+    const value = record(source?.value);
+    if (source?.status !== 'ok' || !value) {
+        const corrupt = source?.status === 'corrupt';
+        return {
+            status: corrupt ? 'corrupt' : 'unavailable',
+            id,
+            capturedAt: null,
+            archivedAt: null,
+            sessionCount: 0,
+            windowCount: 0,
+            paneCount: 0,
+            agentCount: 0,
+            endedReason: null,
+            errorCode: corrupt ? 'checkpoint-corrupt' : 'checkpoint-unavailable',
+        };
+    }
+    const sessions = Array.isArray(value.sessions) ? value.sessions : [];
+    const windows = Array.isArray(value.windows) ? value.windows : [];
+    const panes = windows.flatMap((window) => {
+        const item = record(window);
+        return Array.isArray(item?.panes) ? item.panes : [];
+    });
+    const environment = record(value.environment);
+    return {
+        status: 'ok',
+        id,
+        capturedAt: timestamp(value.capturedAt),
+        archivedAt: timestamp(value.archivedAt),
+        sessionCount: sessions.length,
+        windowCount: windows.length,
+        paneCount: panes.length,
+        agentCount: panes.filter((pane) => record(record(pane)?.agent) !== null).length,
+        endedReason: typeof environment?.endedReason === 'string' && CHANGE_REASONS.has(environment.endedReason) ? environment.endedReason : null,
+        errorCode: null,
+    };
+}
+function errorText(error) {
+    if (typeof error === 'string')
+        return error.toLowerCase();
+    if (error instanceof Error)
+        return error.message.toLowerCase();
+    return '';
+}
+function errorCode(error, { stage = null, status = null } = {}) {
+    const text = errorText(error);
+    if (status === 'interrupted' || /interrupt|process restart/.test(text))
+        return 'restore-interrupted';
+    if (/enospc|disk full|no space/.test(text))
+        return 'storage-full';
+    if (/eacces|eperm|permission|not writable/.test(text))
+        return 'permission-denied';
+    if (/checkpoint.*(?:missing|not found|unavailable)/.test(text))
+        return 'checkpoint-not-found';
+    if (stage === 'plan' || /restore plan|planning/.test(text))
+        return 'plan-failed';
+    if (stage === 'agent' || /\b(?:agent|claude|codex)\b|command not found|cli unavailable/.test(text))
+        return 'agent-unavailable';
+    if (stage === 'topology' || /\btmux\b|topology|server disappeared/.test(text))
+        return 'tmux-unavailable';
+    if (text || status === 'failed')
+        return 'restore-failed';
+    return null;
+}
+function warningCode(warning) {
+    const text = errorText(warning);
+    if (/live reconcile|reconcile.*(?:fail|unavailable)/.test(text))
+        return 'live-reconcile-failed';
+    if (/\blayout\b/.test(text))
+        return 'layout-fallback';
+    if (/\b(?:agent|claude|codex)\b|command not found|cli unavailable/.test(text))
+        return 'agent-warning';
+    if (/\bcwd\b|\bdirectory\b|fallback.*home|missing.*path/.test(text))
+        return 'cwd-fallback';
+    if (/enospc|disk full|no space|eacces|eperm|permission|not writable/.test(text))
+        return 'workspace-unavailable';
+    return 'restore-warning';
+}
+function projectWarningCodes(value, existing) {
+    const codes = [];
+    if (Array.isArray(existing)) {
+        for (const code of existing) {
+            if (typeof code === 'string' && WARNING_CODES.has(code))
+                codes.push(code);
+        }
+    }
+    if (Array.isArray(value))
+        for (const warning of value)
+            codes.push(warningCode(warning));
+    return [...new Set(codes)];
+}
+function projectMapping(value, id) {
+    if (!value || !id)
+        return null;
+    try {
+        const mapping = validateRecoveryMapping(value, id);
+        const copyEntries = (entries) => Object.fromEntries(Object.entries(entries));
+        return {
+            id: mapping.id,
+            checkpointId: mapping.checkpointId,
+            restoredAt: mapping.restoredAt,
+            names: copyEntries(mapping.names),
+            runtime: {
+                sessions: copyEntries(mapping.runtime.sessions),
+                windows: copyEntries(mapping.runtime.windows),
+                panes: copyEntries(mapping.runtime.panes),
+            },
+            logical: {
+                sessions: copyEntries(mapping.logical.sessions),
+                windows: copyEntries(mapping.logical.windows),
+                panes: copyEntries(mapping.logical.panes),
+            },
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function projectResult(result) {
+    const source = record(result);
+    const status = typeof source?.status === 'string' && RESULT_STATUSES.has(source.status)
+        ? source.status : 'failed';
+    const stage = typeof source?.stage === 'string' && RESULT_STAGES.has(source.stage)
+        ? source.stage : null;
+    const code = errorCode(source?.error, { stage, status });
+    return {
+        logicalId: typeof source?.logicalId === 'string' && UUID.test(source.logicalId) ? source.logicalId : null,
+        sourceName: displayName(source?.sourceName),
+        targetName: displayName(source?.targetName),
+        status,
+        stage,
+        errorCode: code,
+        errorMessage: code ? ERROR_MESSAGES[code] : null,
+        warningCodes: projectWarningCodes(source?.warnings, source?.warningCodes),
+    };
+}
+function projectOperation(operation) {
+    const source = record(operation);
+    const request = record(source?.request) ?? {};
+    const id = checkpointId(request.checkpointId, null);
+    const status = typeof source?.status === 'string' && OPERATION_STATUSES.has(source.status)
+        ? source.status : 'failed';
+    const code = errorCode(source?.error, { status });
+    const progress = record(source?.progress);
+    const summary = record(source?.summary);
+    return {
+        id: isWorkspaceSafeId(source?.id) ? source.id : null,
+        status,
+        request: {
+            checkpointId: id,
+            sessions: Array.isArray(request.sessions) ? request.sessions.map(displayName).filter(Boolean) : [],
+            historical: request.historical === true,
+        },
+        createdAt: timestamp(source?.createdAt),
+        updatedAt: timestamp(source?.updatedAt),
+        startedAt: timestamp(source?.startedAt),
+        completedAt: timestamp(source?.completedAt),
+        progress: {
+            completed: count(progress?.completed),
+            total: count(progress?.total),
+        },
+        summary: {
+            sessions: count(summary?.sessions),
+            windows: count(summary?.windows),
+            panes: count(summary?.panes),
+        },
+        results: Array.isArray(source?.results) ? source.results.map(projectResult) : [],
+        errorCode: code,
+        errorMessage: code ? ERROR_MESSAGES[code] : null,
+        warningCodes: projectWarningCodes(source?.warnings, source?.warningCodes),
+        mapping: projectMapping(source?.mapping, id),
+    };
+}
+export function workspaceRoutes({ workspace }) {
+    const r = express.Router();
+    r.get('/workspace/status', asyncHandler(async (_req, res) => {
+        return res.json(await workspace.getProtectionStatus());
+    }));
+    r.get('/workspace/checkpoints', asyncHandler(async (_req, res) => {
+        const checkpoints = await workspace.listCheckpoints();
+        return res.json(Array.isArray(checkpoints) ? checkpoints.map(projectCheckpoint) : []);
+    }));
+    r.get('/workspace/restore-plan', asyncHandler(async (req, res) => {
+        const id = checkpointId(req.query.checkpoint, 'latest');
+        if (!id)
+            return res.status(400).json({ error: 'bad checkpoint id' });
+        // serverNow, promptEligible, pending recovery state, and mapping are runtime-authored. The route
+        // deliberately passes them through without interpreting expiresAt using a client-supplied clock.
+        return res.json(await workspace.getRestorePlan({ checkpointId: id }));
+    }, { checkpoint: true }));
+    r.post('/workspace/restore', asyncHandler(async (req, res) => {
+        const restoreRequest = parseWorkspaceRestoreRequest(req.body);
+        if (!restoreRequest)
+            return res.status(400).json({ error: 'bad request' });
+        return res.status(202).json(await workspace.startRestore(restoreRequest));
+    }, { checkpoint: true }));
+    r.get('/workspace/restore/:operationId', asyncHandler(async (req, res) => {
+        if (!isWorkspaceSafeId(req.params.operationId))
+            return res.status(400).json({ error: 'bad operation id' });
+        const operation = await workspace.getOperation(req.params.operationId);
+        if (!operation)
+            return res.status(404).json({ error: 'operation not found' });
+        return res.json(projectOperation(operation));
+    }));
+    return r;
+}