handmux 0.14.0 → 0.16.0

package/src/httpApi.js

@@ -1,78 +1,27 @@
+// API composition root. Applies auth + JSON parsing, then mounts the per-domain route modules under
+// /api. Each module (routes/*.js) owns one domain and receives only the deps it needs; the closure deps
+// (commands, docs, git, previews, token, home, …) pass straight through. Behaviour is unchanged from when
+// every route lived here — this file is just the wiring.
 import express from 'express';
 import { expressAuth } from './auth.js';
-import { isPaneId, isWindowId, isSessionId, isValidSessionName, isValidStartupCmd } from './tmux/commands.js';
 import * as defaultCommands from './tmux/commands.js';
-import { createHash } from 'node:crypto';
-import { gzipSync } from 'node:zlib';
-import { capTrailingBlankRows } from './trimCapture.js';
 import { defaultDocs, MAX_TRANSFER_BYTES } from './docs.js';
 import { defaultGit } from './git.js';
 import * as push from './push.js';
-import { buildIatSignedUrl } from './asr/iflySign.js';
-import { asrConfig, isAsrConfigured } from './asr/iflyConfig.js';
 import { createClaudeEvents } from './claudeEvents.js';
-import busboy from 'busboy';
-import { promises as fsp, createWriteStream } from 'node:fs';
-import { join as joinPath, dirname, resolve as resolvePath } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import { randomBytes } from 'node:crypto';
-import { safeUploadName } from './docPath.js';
-import { safePreviewName } from './previews.js';
-import { isAllowedUploadExt, DEFAULT_UPLOAD_EXTS } from './uploadTypes.js';
-import { hooksStatus, installHooks } from './cli/claudeHooks.js';
-import { codexHooksStatus, installCodexHooks } from './cli/codexHooks.js';
+import { DEFAULT_UPLOAD_EXTS } from './uploadTypes.js';
 import { claudeStatePath } from './cli/state.js';
-import { scanOrphans, takeoverOrphan, defaultProjectsDir } from './orphans.js';
-import { getUsageCached } from './usage.js';
-import { readFileSync } from 'node:fs';
-import { readCache, isNewer, shouldRefresh, refreshLatestAsync } from './cli/updateCheck.js';
+import { sessionRoutes } from './routes/sessions.js';
+import { terminalRoutes } from './routes/terminal.js';
+import { gitRoutes } from './routes/git.js';
+import { fileRoutes } from './routes/files.js';
+import { pushRoutes } from './routes/push.js';
+import { systemRoutes } from './routes/system.js';
+import { previewRoutes } from './routes/previews.js';
 
-const here = dirname(fileURLToPath(import.meta.url));
-const HOOKS_SRC = resolvePath(here, '../hooks'); // server/hooks (bundled scripts)
-
-// The installed CLI version (server/package.json) — read once. The phone compares this against the cached
-// npm "latest" to surface an update hint ("run `handmux update` on your computer"); see the /version route.
-const PKG_VERSION = (() => {
-  try { return JSON.parse(readFileSync(resolvePath(here, '../package.json'), 'utf8')).version || null; }
-  catch { return null; }
-})();
-
-// Summarize inbox-hook state across every coding agent for the phone: 'installed' if any agent is wired,
-// 'absent' if an agent is present but none wired (→ offer the one-tap enable), 'no-claude' if there's no
-// agent at all (→ hide the prompt).
-function combinedHooksStatus(home) {
-  const c = hooksStatus(home);      // 'no-claude' | 'installed' | 'absent'
-  const x = codexHooksStatus(home); // 'no-codex' | 'installed' | 'absent'
-  if (c === 'installed' || x === 'installed') return 'installed';
-  if (c !== 'no-claude' || x !== 'no-codex') return 'absent';
-  return 'no-claude';
-}
-
-// 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]`.
-const NAMED = 'Up|Down|Left|Right|Space|Enter|Escape|Tab|BTab|BSpace|Home|End|PageUp|PageDown';
-// A named tmux key with any (optional) modifier prefixes, in the canonical C- M- S- order buildChord emits.
-// Covers the plain keys (Up, Tab, …) AND modifier combos on them — C-Up, M-Up, S-Left, C-Tab, C-S-Up, … —
-// so the 按键 editor can bind e.g. Ctrl+Arrow or Ctrl+Tab, not just Ctrl + a letter.
-const NAMED_KEY = new RegExp(`^(?:C-)?(?:M-)?(?:S-)?(?:${NAMED})$`);
-// Ctrl and/or Alt + one letter or digit — C-r, C-a, M-b, C-M-k. Must carry a modifier (never a bare char;
-// Shift+letter folds to the uppercase character, so no S- here).
-const CHAR_KEY = /^(?:C-)?(?:M-)?[a-z0-9]$/;
-export function isAllowedKey(k) {
-  if (typeof k !== 'string') return false;
-  return NAMED_KEY.test(k) || (CHAR_KEY.test(k) && k.includes('-'));
-}
-
-// Pause between typing the text and pressing Enter on a /send. A TUI like Claude Code needs a
-// beat to ingest the pasted line; without it, the Enter can fold into the input as a newline
-// instead of submitting. 120ms is imperceptible but enough to settle.
-const SUBMIT_GAP_MS = 120;
-const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+// Re-exported for tests (test/keys.test.js) and any caller that imported it by this path historically.
+export { isAllowedKey } from './routes/terminal.js';
 
 export function createApiRouter({
   token, commands = defaultCommands, docs = defaultDocs, git = defaultGit, events,
@@ -85,651 +34,18 @@ export function createApiRouter({
   r.use(express.json());
   const claudeEvents = events || createClaudeEvents({ commands, push });
 
-  r.get('/sessions', async (req, res, next) => {
-    try { res.json(await commands.listSessions()); } catch (e) { next(e); }
-  });
-
-  r.post('/sessions', async (req, res, next) => {
-    const name = typeof req.body?.name === 'string' ? req.body.name.trim() : '';
-    if (!isValidSessionName(name)) return res.status(400).json({ error: 'bad session name' });
-    const { cwd } = req.body || {};
-    const cmd = typeof req.body?.cmd === 'string' ? req.body.cmd.trim() : '';
-    if (cmd && !isValidStartupCmd(cmd)) return res.status(400).json({ error: 'bad startup command' });
-    try {
-      if ((await commands.listSessions()).some((s) => s.name === name)) {
-        return res.status(409).json({ error: 'exists' });
-      }
-      let startDir; // undefined → newSession uses $HOME (old behavior)
-      if (cwd != null) {
-        const out = await docs.resolveCwd(cwd);
-        if (out.error) return res.status(out.status).json({ error: out.error });
-        startDir = out.real;
-      }
-      const id = await commands.newSession(name, startDir, cmd || undefined);
-      res.status(201).json({ id, name });
-    } catch (e) { next(e); }
-  });
-
-  r.get('/windows', async (req, res, next) => {
-    if (!isSessionId(req.query.session)) return res.status(400).json({ error: 'bad session id' });
-    try { res.json(await commands.listWindows(req.query.session)); } catch (e) { next(e); }
-  });
-
-  r.post('/windows', async (req, res, next) => {
-    const { session, pane, name, cwd } = req.body || {};
-    if (!isSessionId(session)) return res.status(400).json({ error: 'bad session id' });
-    if (!isPaneId(pane)) return res.status(400).json({ error: 'bad pane id' });
-    // The window name is optional (blank → tmux auto-names); when given it shares the session name rule.
-    const wname = typeof name === 'string' ? name.trim() : '';
-    if (wname && !isValidSessionName(wname)) return res.status(400).json({ error: 'bad window name' });
-    const cmd = typeof req.body?.cmd === 'string' ? req.body.cmd.trim() : '';
-    if (cmd && !isValidStartupCmd(cmd)) return res.status(400).json({ error: 'bad startup command' });
-    try {
-      let startDir;
-      if (cwd != null) {
-        const out = await docs.resolveCwd(cwd);
-        if (out.error) return res.status(out.status).json({ error: out.error });
-        startDir = out.real;
-      } else {
-        startDir = await commands.paneCurrentPath(pane); // old behavior: inherit the pane's dir
-      }
-      const id = await commands.newWindow(session, startDir, wname || undefined, cmd || undefined);
-      res.status(201).json({ id });
-    } catch (e) { next(e); }
-  });
-
-  r.patch('/sessions', async (req, res, next) => {
-    const { id } = req.body || {};
-    const name = typeof req.body?.name === 'string' ? req.body.name.trim() : '';
-    if (!isSessionId(id)) return res.status(400).json({ error: 'bad session id' });
-    if (!isValidSessionName(name)) return res.status(400).json({ error: 'bad session name' });
-    try {
-      // Block only a collision with a DIFFERENT session — renaming to the current name is a no-op,
-      // not a conflict (the user may have opened the modal and kept the name).
-      if ((await commands.listSessions()).some((s) => s.name === name && s.id !== id)) {
-        return res.status(409).json({ error: 'exists' });
-      }
-      await commands.renameSession(id, name);
-      res.json({ id, name });
-    } catch (e) { next(e); }
-  });
-
-  r.patch('/windows', async (req, res, next) => {
-    const { id } = req.body || {};
-    const name = typeof req.body?.name === 'string' ? req.body.name.trim() : '';
-    if (!isWindowId(id)) return res.status(400).json({ error: 'bad window id' });
-    // Window names share the session-name rule. tmux allows duplicate window names, so no 409 check.
-    if (!isValidSessionName(name)) return res.status(400).json({ error: 'bad window name' });
-    try {
-      await commands.renameWindow(id, name);
-      res.json({ id, name });
-    } catch (e) { next(e); }
-  });
-
-  r.post('/windows/swap', async (req, res, next) => {
-    const { a, b } = req.body || {};
-    if (!isWindowId(a) || !isWindowId(b)) return res.status(400).json({ error: 'bad window id' });
-    if (a === b) return res.status(400).json({ error: 'same window' });
-    // swap-window is non-destructive and reversible, so unlike DELETE we don't re-verify the windows
-    // server-side — the client only ever swaps adjacent windows of the open session.
-    try {
-      await commands.swapWindows(a, b);
-      res.json({ ok: true });
-    } catch (e) { next(e); }
-  });
-
-  r.delete('/windows', async (req, res, next) => {
-    if (!isWindowId(req.query.window)) return res.status(400).json({ error: 'bad window id' });
-    try {
-      // Killing the only window takes the whole session down with it — that's allowed and intended.
-      // The client warns ("确认后将删除整个会话") before sending, so there's no last-window guard here.
-      await commands.killWindow(req.query.window);
-      res.status(204).end();
-    } catch (e) { next(e); }
-  });
-
-  r.get('/panes', async (req, res, next) => {
-    if (!isWindowId(req.query.window)) return res.status(400).json({ error: 'bad window id' });
-    try { res.json(await commands.listPanes(req.query.window)); } catch (e) { next(e); }
-  });
-
-  // A pane's current working directory — the file browser uses it to land on (and "jump to") the
-  // session's dir. Absolute path; the client folds it to a home-relative path and lets the existing
-  // /dir listing enforce the under-$HOME boundary (a cwd outside $HOME just fails to browse).
-  r.get('/pane-cwd', async (req, res, next) => {
-    if (!isPaneId(req.query.pane)) return res.status(400).json({ error: 'bad pane id' });
-    try { res.json({ cwd: await commands.paneCurrentPath(req.query.pane) }); } catch (e) { next(e); }
-  });
-
-  // --- git viewer (read-only) ----------------------------------------------------------------
-  // Each route calls the git data layer and maps its {error,status} to an HTTP status (same shape
-  // as the docs routes); the layer enforces the under-$HOME containment and validation.
-  const q = (v) => (typeof v === 'string' ? v : '');
-  r.get('/git/repos', async (req, res, next) => {
-    try {
-      const out = await git.detectRepos(q(req.query.dir));
-      if (out.error) return res.status(out.status).json({ error: out.error });
-      res.json({ repos: out.repos });
-    } catch (e) { next(e); }
-  });
-  r.get('/git/status', async (req, res, next) => {
-    try {
-      const out = await git.status(q(req.query.repo));
-      if (out.error) return res.status(out.status).json({ error: out.error });
-      res.json({ changes: out.changes });
-    } catch (e) { next(e); }
-  });
-  r.get('/git/log', async (req, res, next) => {
-    try {
-      const out = await git.log(q(req.query.repo), req.query.limit, req.query.ref ? q(req.query.ref) : undefined);
-      if (out.error) return res.status(out.status).json({ error: out.error });
-      res.json({ commits: out.commits });
-    } catch (e) { next(e); }
-  });
-  r.get('/git/branches', async (req, res, next) => {
-    try {
-      const out = await git.branches(q(req.query.repo));
-      if (out.error) return res.status(out.status).json({ error: out.error });
-      res.json({ branches: out.branches });
-    } catch (e) { next(e); }
-  });
-  r.get('/git/diff', async (req, res, next) => {
-    try {
-      const out = await git.diff(q(req.query.repo), {
-        path: q(req.query.path),
-        commit: req.query.commit ? q(req.query.commit) : undefined,
-        staged: req.query.staged === '1',
-      });
-      if (out.error) return res.status(out.status).json({ error: out.error });
-      res.json({ diff: out.diff, truncated: out.truncated });
-    } catch (e) { next(e); }
-  });
-  r.get('/git/commit', async (req, res, next) => {
-    try {
-      const out = await git.commit(q(req.query.repo), q(req.query.hash));
-      if (out.error) return res.status(out.status).json({ error: out.error });
-      res.json({ message: out.message, files: out.files });
-    } catch (e) { next(e); }
-  });
-
-  // Read a single doc (md/html) under $HOME. The docs layer realpaths and enforces containment;
-  // the route only maps its {error,status} to an HTTP status.
-  r.get('/file', async (req, res, next) => {
-    try {
-      // Conditional read: `?mtime=<ms>` (the client's last-known mtime) lets the server answer
-      // `{ notModified: true }` without re-reading/re-sending an unchanged doc.
-      const m = Number(req.query.mtime);
-      const knownMtime = Number.isFinite(m) ? m : null;
-      const out = await docs.readDoc(typeof req.query.path === 'string' ? req.query.path : '', knownMtime);
-      if (out.error) return res.status(out.status).json({ error: out.error });
-      if (out.notModified) return res.json({ name: out.name, type: out.type, mtimeMs: out.mtimeMs, notModified: true });
-      res.json({ name: out.name, type: out.type, content: out.content, mtimeMs: out.mtimeMs });
-    } catch (e) { next(e); }
-  });
-
-  // List a directory under $HOME (empty path → $HOME). Only subdirs + md/html files are returned.
-  r.get('/dir', async (req, res, next) => {
-    try {
-      const out = await docs.listDir(typeof req.query.path === 'string' ? req.query.path : '');
-      if (out.error) return res.status(out.status).json({ error: out.error });
-      res.json(out);
-    } catch (e) { next(e); }
-  });
-
-  // Create a directory `name` inside `dir` (both must be under $HOME). docs.makeDir enforces the
-  // boundary check and validates the name; the route maps {error,status} to an HTTP response.
-  r.post('/dir', async (req, res, next) => {
-    const { dir, name } = req.body || {};
-    if (typeof dir !== 'string' || typeof name !== 'string') return res.status(400).json({ error: 'bad request' });
-    try {
-      const out = await docs.makeDir(dir, name);
-      if (out.error) return res.status(out.status).json({ error: out.error });
-      res.status(201).json({ path: out.real });
-    } catch (e) { next(e); }
-  });
-
-  // Download ANY regular file under $HOME (no extension white-list). docs.statForDownload enforces
-  // the realpath+isUnder boundary and the 50MB cap; res.download streams it and forces
-  // Content-Disposition: attachment (so HTML/SVG can never render inline → no stored-XSS via open).
-  r.get('/download', async (req, res, next) => {
-    try {
-      const out = await docs.statForDownload(typeof req.query.path === 'string' ? req.query.path : '');
-      if (out.error) return res.status(out.status).json({ error: out.error });
-      // Conditional download for the inline image viewer: `?mtime=<ms>` (the client's last-known mtime)
-      // → 304 when unchanged, so a large image isn't re-streamed just to re-view it. `X-Mtime` on the
-      // 200 lets the client store the current mtime for the next check. Plain downloads pass no mtime.
-      const m = Number(req.query.mtime);
-      if (Number.isFinite(m) && m === out.mtimeMs) return res.status(304).end();
-      res.setHeader('X-Mtime', String(out.mtimeMs));
-      res.download(out.real, out.name, (err) => { if (err && !res.headersSent) next(err); });
-    } catch (e) { next(e); }
-  });
-
-  // First free filename in `dir`: the name as-is, else Finder-style "base (1).ext", "base (2).ext", …
-  // (the suffix goes before the extension). Bounded; a pathological fallback keeps it from looping.
-  async function freeUploadName(dir, name) {
-    const dot = name.lastIndexOf('.');
-    const base = dot > 0 ? name.slice(0, dot) : name;
-    const ext = dot > 0 ? name.slice(dot) : '';
-    let cand = name;
-    for (let n = 1; n <= 999; n++) {
-      try { await fsp.access(joinPath(dir, cand)); } // exists → try the next suffix
-      catch { return cand; }                          // ENOENT → free
-      cand = `${base} (${n})${ext}`;
-    }
-    return `${base} (${randomBytes(3).toString('hex')})${ext}`;
-  }
-
-  // Upload a file into a directory under $HOME. Multipart streamed via busboy (the file never fully
-  // buffers in memory, and the size cap aborts mid-stream). Guards, in order: target dir must be a
-  // non-hidden subdir of home (resolveUploadDir); filename sanitised to a dotless basename; extension
-  // in the allow-list. A name clash auto-suffixes (never overwrites). The client appends `dir` BEFORE
-  // the file part, so the field is known by the time the file event fires.
-  r.post('/upload', (req, res) => {
-    let bb;
-    // defParamCharset:'utf8' — browsers put a non-ASCII (e.g. Chinese) filename into the multipart
-    // Content-Disposition as raw UTF-8 bytes; busboy's default 'latin1' would decode it to mojibake.
-    try { bb = busboy({ headers: req.headers, defParamCharset: 'utf8', limits: { files: 1, fileSize: maxUploadBytes + 1 } }); }
-    catch { return res.status(400).json({ error: 'bad multipart request' }); }
-
-    let dir = '';
-    let stash = false; // stash=1 → upload into the per-cwd space under ~/.handmux/uploads; `dir` is the cwd
-    let sawFile = false;
-    let handled = false;
-    let ws = null;
-    let tmp = null;
-    const done = (status, body) => { if (!handled) { handled = true; res.status(status).json(body); } };
-    const cleanup = () => (tmp ? fsp.rm(tmp, { force: true }).catch(() => {}) : Promise.resolve());
-
-    bb.on('field', (name, val) => {
-      if (name === 'dir') dir = val;
-      else if (name === 'stash') stash = val === '1';
-    });
-
-    bb.on('file', async (_field, file, info) => {
-      sawFile = true;
-      try {
-        const name = safeUploadName(info.filename);
-        if (!name) { file.resume(); return done(400, { error: 'bad filename' }); }
-        if (!isAllowedUploadExt(name, uploadExts)) { file.resume(); return done(415, { error: 'type not allowed' }); }
-
-        const target = stash ? await docs.resolveStashDir(dir) : await docs.resolveUploadDir(dir);
-        if (target.error) { file.resume(); return done(target.status, { error: target.error }); }
-
-        // Finder-style de-dup: never 409 / overwrite on a name clash — pick the first free "base (n).ext".
-        // Resolved up front for the response; re-resolved at link time if the race is lost (see below).
-        const origName = name;
-        let finalName = await freeUploadName(target.real, origName);
-        let dest = joinPath(target.real, finalName);
-
-        tmp = joinPath(target.real, `.${finalName}.uploading-${randomBytes(6).toString('hex')}`);
-        ws = createWriteStream(tmp);
-        ws.on('error', () => { file.resume(); cleanup().finally(() => done(500, { error: 'write failed' })); });
-        ws.on('finish', async () => {
-          // busboy sets file.truncated synchronously when it emits 'limit'; it's reliably true here
-          // if the stream exceeded the cap. (We size the limit at cap+1 so a file of EXACTLY
-          // maxUploadBytes is allowed; only strictly-larger trips it.)
-          if (file.truncated) { await cleanup(); return done(413, { error: 'too large' }); }
-          try {
-            // link (NOT rename): if the name appeared meanwhile (a concurrent upload won the race) link
-            // throws EEXIST → we pick the NEXT free suffix and retry, so we still never overwrite another
-            // file, and a clash auto-suffixes rather than 409s.
-            let linked = false;
-            for (let attempt = 0; attempt < 6 && !linked; attempt++) {
-              try { await fsp.link(tmp, dest); linked = true; }
-              catch (e) {
-                if (e.code !== 'EEXIST') throw e;
-                finalName = await freeUploadName(target.real, origName);
-                dest = joinPath(target.real, finalName);
-              }
-            }
-            if (!linked) { await cleanup(); return done(409, { error: 'exists' }); }
-            await cleanup(); // link made dest a second name for the data; drop the temp name
-            const st = await fsp.stat(dest);
-            done(201, { name: finalName, size: st.size, path: dest }); // absolute path: the dock pastes it in
-          } catch { await cleanup(); done(500, { error: 'finalize failed' }); }
-        });
-        file.pipe(ws);
-      } catch {
-        // resolveUploadDir / fs errors etc. — never let the async handler reject (busboy won't catch
-        // it → unhandledRejection + hung request).
-        file.resume();
-        await cleanup();
-        done(500, { error: 'upload failed' });
-      }
-    });
-
-    bb.on('error', () => { cleanup().finally(() => done(400, { error: 'parse error' })); });
-    bb.on('close', () => { if (!sawFile) done(400, { error: 'no file' }); });
-    // Client aborted mid-upload (mobile networks drop constantly). req.pipe(bb) does NOT forward the
-    // source's destroy to busboy, so ws/file/bb emit nothing — we'd leak the half-written temp file
-    // and its fd on every dropped upload. Clean up ourselves on abort.
-    req.on('aborted', () => { if (handled) return; handled = true; if (ws) ws.destroy(); cleanup(); });
-    req.pipe(bb);
-  });
-
-  r.get('/history', async (req, res, next) => {
-    if (!isPaneId(req.query.pane)) 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(req.query.pane);
-      // 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 raw = await commands.capturePane(req.query.pane, altScreen ? 0 : lines);
-      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 = (s) => (s.endsWith('\n') ? s.slice(0, -1) : s).split('\n').length;
-      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, 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.
-        res.end(gzipSync(json));
-      } else {
-        res.end(json);
-      }
-    } catch (e) { next(e); }
-  });
-
-  r.post('/send', async (req, res, next) => {
-    const { pane, text, enter } = req.body || {};
-    if (!isPaneId(pane)) return res.status(400).json({ error: 'bad pane id' });
-    const body = typeof text === 'string' ? text : '';
-    try {
-      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);
-      }
-      res.json({ ok: true });
-    } catch (e) { next(e); }
-  });
-
-  // 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 { res.json({ layout: await commands.getWindowLayout(req.query.window) }); }
-    catch (e) { next(e); }
-  });
-
-  r.post('/resize', async (req, res, next) => {
-    const { window, pane, cols, rows, auto, layout } = req.body || {};
-    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' });
-      }
-      res.json({ ok: true });
-    } catch (e) { next(e); }
-  });
-
-  r.post('/keys', async (req, res, next) => {
-    const { pane, keys } = req.body || {};
-    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 commands.exitCopyModeIfActive(pane);
-      for (const k of keys) await commands.sendKey(pane, k);
-      res.json({ ok: true });
-    } catch (e) { 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 } = req.body || {};
-    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, lines, {
-        sgr: mouseSgr,
-        col: Math.max(1, Math.floor((width || 2) / 2)),
-        row: Math.max(1, Math.floor((height || 2) / 2)),
-      });
-      res.json({ ok: true });
-    } catch (e) { next(e); }
-  });
-
-  // --- Capabilities probe ---------------------------------------------------------------------
-  // Optional integrations are configured per-install (open-source installs ship without keys), so the
-  // client asks what's actually available and hides controls that can't work — e.g. the mic when no
-  // ASR engine is configured. Add more flags here as optional integrations land.
-  // `claudeHooks` (name kept for web back-compat) now summarizes EVERY coding agent: 'installed' if any is
-  // wired, 'absent' if an agent is present but none wired (→ offer enable), 'no-claude' if no agent at all.
-  r.get('/config', (req, res) => {
-    res.json({ asr: isAsrConfigured(asrEnv), claudeHooks: combinedHooksStatus(home) });
-  });
-
-  // Update hint for the phone: is the globally-installed CLI behind the latest npm release? `current` is
-  // this server's version; `latest` comes from the same cache the CLI maintains (~/.handmux/update-check.json).
-  // We never block on the network here — if the cache is stale we kick a best-effort async refresh (throttled
-  // to once an hour, like the CLI) and return the currently-known value. The upgrade itself is a computer-side
-  // `handmux update`; the phone only shows the notice.
-  r.get('/version', (req, res) => {
-    const cache = readCache(home);
-    if (shouldRefresh(cache)) refreshLatestAsync(home);
-    const latest = cache?.latest ?? null;
-    const updateAvailable = !!(latest && PKG_VERSION && isNewer(latest, PKG_VERSION));
-    // `whatsNew` is the concise per-version highlights the newer package carries (via npm). Trim to the
-    // versions the user would actually GAIN by upgrading (strictly newer than what's installed here).
-    const whatsNew = (updateAvailable && Array.isArray(cache?.whatsNew))
-      ? cache.whatsNew.filter((e) => e && e.version && isNewer(e.version, PKG_VERSION))
-      : [];
-    res.json({ current: PKG_VERSION, latest, updateAvailable, whatsNew });
-  });
-
-  // One-tap enable from the phone: install the hooks for every present agent (Claude Code, Codex) on the
-  // host (token-gated, like every API here). Opt-in — the inbox only offers this when status is 'absent'.
-  // Never creates ~/.claude or ~/.codex; a user's own Codex `notify` is left untouched (see codexHooks.js).
-  r.post('/hooks/install', (req, res) => {
-    try {
-      let installed = 0;
-      if (hooksStatus(home) !== 'no-claude') { installHooks(home, { srcDir: HOOKS_SRC, stateFile }); installed++; }
-      if (codexHooksStatus(home) !== 'no-codex') { installCodexHooks(home, { srcDir: HOOKS_SRC, stateFile }); installed++; }
-      res.json({ ok: installed > 0, status: combinedHooksStatus(home) });
-    } catch (e) { res.status(500).json({ ok: false, error: String(e) }); }
-  });
-
-  // --- Voice input: iFlytek IAT signed-URL handoff -------------------------------------------
-  // The browser connects to iFlytek directly; we only mint a short-lived signed wss URL so the
-  // apiSecret never reaches the phone. 503 if creds aren't configured (front-end hides the mic).
-  r.get('/asr/sign', (req, res) => {
-    if (!isAsrConfigured(asrEnv)) return res.status(503).json({ error: 'asr not configured' });
-    const { appId, apiKey, apiSecret } = asrConfig(asrEnv);
-    res.json(buildIatSignedUrl({ appId, apiKey, apiSecret, date: new Date().toUTCString() }));
-  });
-
-  // --- Web Push (minimal slice) ---------------------------------------------------------------
-  // The client needs the VAPID public key to subscribe; 503 if the server has no keys configured.
-  r.get('/push/vapid', (req, res) => {
-    if (!push.isConfigured()) return res.status(503).json({ error: 'push not configured' });
-    res.json({ key: push.publicKey() });
-  });
-
-  // Store a browser PushSubscription, then immediately fire a welcome push back to it — so enabling
-  // the toggle proves the whole pipe (subscribe → push service → SW → notification) end to end.
-  r.post('/push/subscribe', async (req, res, next) => {
-    const sub = req.body?.subscription;
-    const boundSessions = Array.isArray(req.body?.boundSessions) ? req.body.boundSessions : [];
-    if (!sub || typeof sub.endpoint !== 'string') return res.status(400).json({ error: 'bad subscription' });
-    try {
-      push.addSubscription(sub, boundSessions);
-      await push.sendToOne(sub, { title: '通知已开启 ✅', body: '会话「需要你」或「已完成」时提醒你', tag: 'handmux-welcome' }, { topic: 'handmux', urgency: 'high' });
-      res.json({ ok: true, count: push.count(), pushKey: push.getPushKey(sub.endpoint) });
-    } catch (e) { next(e); }
-  });
-
-  r.post('/push/unsubscribe', (req, res) => {
-    const endpoint = req.body?.endpoint;
-    if (typeof endpoint === 'string') push.removeSubscription(endpoint);
-    res.json({ ok: true });
-  });
-
-  // Manual "send me a test" — pushes to every stored subscription.
-  r.post('/push/test', async (req, res, next) => {
-    try {
-      const out = await push.sendToAll(
-        { title: 'handmux 测试', body: '这是一条测试通知 — 点我回到 app', tag: 'handmux-test' },
-        { topic: 'handmux', urgency: 'high' },
-      );
-      res.json(out);
-    } catch (e) { next(e); }
-  });
-
-  // Client reports which sessions this device cares about; updates the stored subscription.
-  r.post('/push/bound', (req, res) => {
-    const endpoint = req.body?.endpoint;
-    const boundSessions = Array.isArray(req.body?.boundSessions) ? req.body.boundSessions : [];
-    if (typeof endpoint === 'string') push.updateBound(endpoint, boundSessions);
-    res.json({ ok: true });
-  });
-
-  // Local script push (`handmux push`): loopback + server token. Scope is mutually exclusive —
-  // devices (by pushKey) > sessions > all. This is the ONLY push-send entry; no public/remote variant.
-  r.post('/push/send-local', async (req, res, next) => {
-    const { sessions, devices, title, body, tag, url } = req.body || {};
-    if (typeof title !== 'string' || !title.trim()) return res.status(400).json({ error: 'title required' });
-    if (typeof body !== 'string' || !body.trim()) return res.status(400).json({ error: 'body required' });
-    const hasSessions = Array.isArray(sessions) && sessions.length > 0;
-    const hasDevices = Array.isArray(devices) && devices.length > 0;
-    if (hasSessions && hasDevices) return res.status(400).json({ error: 'use --session or --device, not both' });
-    const payload = { title, body };
-    if (typeof tag === 'string' && tag) payload.tag = tag;
-    if (typeof url === 'string' && url) payload.data = { url };
-    const opts = { urgency: 'normal', ttl: 1800 };
-    if (payload.tag) opts.topic = payload.tag;
-    try {
-      const out = hasDevices ? await push.sendToDevices(devices, payload, opts)
-        : hasSessions ? await push.sendToSessions(sessions, payload, opts)
-        : await push.sendToAll(payload, opts);
-      res.json(out);
-    } catch (e) { next(e); }
-  });
-
-  // This device's addressing key (server-token auth) — the script push sheet reads it to show `--device`.
-  r.post('/push/key', (req, res) => {
-    const endpoint = req.body?.endpoint;
-    if (typeof endpoint !== 'string') return res.status(400).json({ error: 'endpoint required' });
-    res.json({ pushKey: push.getPushKey(endpoint) });
-  });
-
-  // ?sessions=a,b scopes the roster to the session NAMES this device subscribed to (per-device inbox
-  // isolation). Omitted → null → all (back-compat); present-but-empty → [] → nothing.
-  r.get('/states', async (req, res, next) => {
-    const q = req.query.sessions;
-    const allowed = q === undefined ? null : String(q).split(',').map((s) => s.trim()).filter(Boolean);
-    try { res.json(await claudeEvents.getStates(allowed)); } catch (e) { next(e); }
-  });
-
-  // Agent usage/quota for the Usage page. Disk-only, no credentials: Claude's 5h/weekly % from the
-  // statusLine snapshot (if the capturer is opted in), Codex's rate_limits + tokens from its newest
-  // rollout. Either side is null when unavailable. Cached briefly (see usage.js); never throws.
-  r.get('/usage', (req, res, next) => {
-    try { res.json(getUsageCached(home)); } catch (e) { next(e); }
-  });
-
-  // Orphan Claude sessions: `claude` processes running on this host but NOT inside a tmux pane, so
-  // handmux can't steer them. Surfaced at the bottom of the Inbox with a "takeover" (spawn
-  // `claude --resume` in tmux). Best-effort process scan (see orphans.js); never throws.
-  r.get('/orphans', async (req, res, next) => {
-    try { res.json(await scanOrphans({ projectsDir: defaultProjectsDir(home) })); } catch (e) { next(e); }
-  });
-
-  // Take over an orphan: spawn `claude --resume <sessionId>` in tmux and (default) SIGTERM the original.
-  // pid/sessionId are re-verified against a fresh scan server-side; sessionId must be a UUID (it's typed
-  // into a shell). target.mode 'new' (fresh session) or 'window' (into an existing session id).
-  r.post('/orphans/takeover', async (req, res, next) => {
-    const { pid, sessionId, kill, target } = req.body || {};
-    const t = target && target.mode === 'window' && isSessionId(target.session)
-      ? { mode: 'window', session: target.session } : { mode: 'new' };
-    try {
-      const out = await takeoverOrphan(
-        { commands, scanOpts: { projectsDir: defaultProjectsDir(home) } },
-        { pid, sessionId, target: t, kill: kill !== false },
-      );
-      if (out.error) return res.status(out.status).json({ error: out.error });
-      res.json(out);
-    } catch (e) { next(e); }
-  });
-
-  // --- Preview registry (static dir OR dynamic port) -----------------------------------------
-  // POST {name,dir} registers a static dir served at /preview/<name>/; POST {name,port} registers a
-  // dynamic reverse-proxy reachable at https://<name>.<DOMAIN>/ (only when previewDomain is set). The
-  // url carries ?token= so the browser's first navigation sets the preview cookie.
-  r.post('/previews', async (req, res, next) => {
-    if (!previews) return res.status(503).json({ error: 'previews disabled' });
-    const { name, dir, port } = req.body || {};
-    if (typeof name !== 'string' || !name) return res.status(400).json({ error: 'bad request' });
-    const hasPort = port !== undefined && port !== null && port !== '';
-    if (!hasPort && (typeof dir !== 'string' || !dir)) return res.status(400).json({ error: 'bad request' });
-    try {
-      const out = await previews.register(hasPort ? { name, port } : { name, dir });
-      if (out.error) return res.status(out.status).json({ error: out.error });
-      const url = out.kind === 'dynamic'
-        ? `https://${encodeURIComponent(out.name)}.${previewDomain}/?token=${encodeURIComponent(token)}`
-        : `/preview/${encodeURIComponent(out.name)}/?token=${encodeURIComponent(token)}`;
-      res.json({ name: out.name, kind: out.kind, url, expiresAt: out.expiresAt });
-    } catch (e) { next(e); }
-  });
-
-  r.get('/previews', (req, res) => {
-    if (!previews) return res.status(503).json({ error: 'previews disabled' });
-    res.json({ previews: previews.list(), dynamicEnabled: !!previewDomain, domain: previewDomain });
-  });
-
-  r.delete('/previews/:name', (req, res) => {
-    if (!previews) return res.status(503).json({ error: 'previews disabled' });
-    if (!safePreviewName(req.params.name)) return res.status(400).json({ error: 'bad name' });
-    previews.remove(req.params.name);
-    res.status(204).end();
-  });
+  const deps = {
+    token, commands, docs, git, push, claudeEvents,
+    uploadExts, maxUploadBytes, asrEnv, previews, previewDomain, home, stateFile,
+  };
+
+  r.use(sessionRoutes(deps));
+  r.use(terminalRoutes(deps));
+  r.use(gitRoutes(deps));
+  r.use(fileRoutes(deps));
+  r.use(pushRoutes(deps));
+  r.use(systemRoutes(deps));
+  r.use(previewRoutes(deps));
 
   return r;
 }