handmux 0.5.0

package/src/cli/tmuxConf.js

@@ -0,0 +1,90 @@
+// Opt-in wiring of the per-window Claude status dot into ~/.tmux.conf. The handmux hook writes a colour
+// markup into each window's `@claude_dot` option on every Claude event (see hooks/handmux-write.cjs); tmux
+// only RENDERS it if `window-status-format` references `#{@claude_dot}`. This module appends that display
+// config PLUS the two enhancements (cold-start seed + focus-auto-clear), and — crucially — installs the
+// scripts those enhancements need into a STABLE location so the wiring never breaks.
+//
+// Why a stable location: the scripts must be referenced by absolute path from ~/.tmux.conf. Pointing that
+// at a repo checkout breaks the moment the repo moves or is renamed (the original failure: a stale
+// `…/tmux-web/tmux/claude-tab-seen.sh` returned 127 on every window switch). So, exactly like the Claude
+// hook copies its notify script into ~/.claude/hooks/, we copy the tmux scripts into ~/.handmux/tmux/ and
+// the conf block references THAT — a path tied to $HOME, not to where handmux happens to be installed.
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { pocketHome } from './state.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const PKG_TMUX = path.resolve(here, '../../tmux'); // server/tmux — shipped in the package ("files": [...,"tmux"])
+const SCRIPTS = ['claude-tab-seed.py', 'claude-tab-seen.sh'];
+
+const BEGIN = '# >>> handmux claude-dot >>>';
+const END = '# <<< handmux claude-dot <<<';
+
+export function tmuxConfPath(home = homedir()) { return path.join(home, '.tmux.conf'); }
+
+// Where the seed/seen scripts are installed — stable across repo moves / renames / a global npm install.
+export function tmuxScriptsDir(home = homedir()) { return path.join(pocketHome(home), 'tmux'); }
+
+// The marked block we append. `status-style` resets the default green status bar (which would swallow the
+// green "done" dot) to neutral grey; the window-status-format lines inject `#{@claude_dot}` before the
+// window name; the seed paints existing windows on (re)load; the two hooks clear a "done" dot when you
+// actually focus that window. All script references use the stable ~/.handmux/tmux path (see top comment).
+export function dotBlock(home = homedir()) {
+  const dir = tmuxScriptsDir(home);
+  const seed = path.join(dir, 'claude-tab-seed.py');
+  const seen = path.join(dir, 'claude-tab-seen.sh');
+  return [
+    BEGIN,
+    '# Per-window Claude status dot (live via the handmux hook) + cold-start seed + focus-auto-clear.',
+    `# Scripts live in ${dir} (installed by handmux). Delete this whole block to disable.`,
+    "set -g status-style 'bg=colour236,fg=colour250'",
+    "set -g window-status-current-style 'bg=colour248,fg=colour234,bold'",
+    "set -g window-status-format '#{@claude_dot}#I:#W#{?window_flags,#{window_flags}, }'",
+    "set -g window-status-current-format '#{@claude_dot}#I:#W#{?window_flags,#{window_flags}, }'",
+    'set -g focus-events on',
+    `run-shell -b '${seed}'`,
+    `set-hook -g after-select-window 'run-shell -b "${seen} #{window_id}"'`,
+    `set-hook -g pane-focus-in 'run-shell -b "${seen} #{window_id}"'`,
+    END,
+    '',
+  ].join('\n');
+}
+
+// Pure: does this ~/.tmux.conf text already wire the dot? Keys on `@claude_dot` so a user who hand-rolled
+// their own is recognised as configured and never nagged or double-installed.
+export function dotConfigured(text) {
+  return typeof text === 'string' && text.includes('@claude_dot');
+}
+
+function readConf(home) {
+  try { return fs.readFileSync(tmuxConfPath(home), 'utf8'); } catch { return null; }
+}
+
+// 'present' if the dot is already wired, else 'absent'. A missing ~/.tmux.conf is 'absent'.
+export function tmuxDotStatus(home = homedir()) {
+  return dotConfigured(readConf(home) || '') ? 'present' : 'absent';
+}
+
+// Copy the seed/seen scripts into the stable ~/.handmux/tmux dir (executable). Idempotent overwrite, so a
+// reinstall after an upgrade refreshes them. Returns the dir. srcDir defaults to the shipped server/tmux.
+export function installTmuxScripts(home = homedir(), srcDir = PKG_TMUX) {
+  const dir = tmuxScriptsDir(home);
+  fs.mkdirSync(dir, { recursive: true });
+  for (const f of SCRIPTS) fs.copyFileSync(path.join(srcDir, f), path.join(dir, f));
+  for (const f of SCRIPTS) { try { fs.chmodSync(path.join(dir, f), 0o755); } catch { /* best effort */ } }
+  return dir;
+}
+
+// Install the scripts to ~/.handmux/tmux and append the marked block to ~/.tmux.conf (creating it if
+// absent), idempotently. Returns { status }: 'present' if already wired (no-op), 'installed' if just added.
+// Never touches the user's own lines — appends after them, separated by a newline.
+export function installTmuxDot(home = homedir(), { srcDir = PKG_TMUX } = {}) {
+  const existing = readConf(home);
+  if (dotConfigured(existing || '')) return { status: 'present' };
+  installTmuxScripts(home, srcDir);
+  const prefix = existing && !existing.endsWith('\n') ? existing + '\n' : (existing || '');
+  fs.writeFileSync(tmuxConfPath(home), `${prefix}\n${dotBlock(home)}`);
+  return { status: 'installed' };
+}

package/src/cli/tmuxVersion.js

@@ -0,0 +1,49 @@
+// handmux's terminal rendering depends on `capture-pane -e -N` semantics, and those have drifted
+// across tmux versions before (e.g. how -N pads trailing whitespace). So we check the host's tmux at
+// start: absent → hard error; below the version we've validated → warn (don't block). exec injectable.
+import { spawnSync } from 'node:child_process';
+
+// Lowest tmux handmux has been validated against. Bump as the CI matrix (see release plan) widens.
+export const MIN_TMUX = '3.0';
+
+// "tmux 3.6a" / "tmux 3.4" / "tmux next-3.5" / "tmux openbsd-7.4" → {major,minor,suffix,raw}.
+export function parseTmuxVersion(out) {
+  const m = /tmux\s+(?:next-|openbsd-)?(\d+)\.(\d+)([a-z]?)/i.exec(String(out || ''));
+  if (!m) return null;
+  return { major: +m[1], minor: +m[2], suffix: m[3] || '', raw: `${m[1]}.${m[2]}${m[3] || ''}` };
+}
+
+// v >= min, comparing major.minor only (patch letters don't change the capture behaviour we rely on).
+export function versionAtLeast(v, minStr = MIN_TMUX) {
+  if (!v) return false;
+  const [maj, min] = minStr.split('.').map(Number);
+  return v.major > maj || (v.major === maj && v.minor >= min);
+}
+
+export function checkTmux(exec = spawnSync) {
+  const r = exec('tmux', ['-V'], { encoding: 'utf8' });
+  if (!r || r.status !== 0 || !r.stdout) return { present: false };
+  const version = parseTmuxVersion(r.stdout);
+  return { present: true, version, ok: versionAtLeast(version), raw: version ? version.raw : String(r.stdout).trim() };
+}
+
+// In install-command order: probe for the package manager that's actually on this Linux box.
+const LINUX_PKG_MANAGERS = [
+  ['apt-get', 'sudo apt install tmux'],
+  ['dnf', 'sudo dnf install tmux'],
+  ['pacman', 'sudo pacman -S tmux'],
+  ['zypper', 'sudo zypper install tmux'],
+  ['apk', 'sudo apk add tmux'],
+  ['yum', 'sudo yum install tmux'],
+];
+
+// The exact "install tmux" command for THIS host, so a tmux-less newcomer gets a copy-paste line instead
+// of a dead end. macOS → Homebrew; Linux → whichever package manager is present; Windows → tmux is a
+// Unix tool, so point at WSL. exec/platform injectable for tests.
+export function tmuxInstallHint(exec = spawnSync, platform = process.platform) {
+  if (platform === 'darwin') return 'brew install tmux';
+  if (platform === 'win32') return 'tmux is a Unix tool — install WSL (`wsl --install`), then inside it: sudo apt install tmux';
+  const has = (bin) => { const r = exec('which', [bin], { encoding: 'utf8' }); return !!r && r.status === 0; };
+  for (const [bin, cmd] of LINUX_PKG_MANAGERS) if (has(bin)) return cmd;
+  return 'install tmux with your package manager (e.g. `sudo apt install tmux`)';
+}

package/src/cli/tunlite.js

@@ -0,0 +1,22 @@
+// Resolve the tunlite binary (bundled dependency first → PATH) and probe passwordless SSH. tunlite is an
+// npm dependency of handmux, so the bundled node_modules/.bin/tunlite means users need no separate install.
+// `run`/`exists` injectable so the pure resolution logic unit-tests without spawning.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const BUNDLED = path.resolve(here, '../../node_modules/.bin/tunlite');
+
+export function resolveTunlite({ run = spawnSync, exists = fs.existsSync, bundled = BUNDLED } = {}) {
+  const candidate = exists(bundled) ? bundled : 'tunlite';
+  const r = run(candidate, ['--version'], { encoding: 'utf8' });
+  if (r && r.status === 0) return candidate;
+  throw new Error('tunlite not found — install it (npm i -g tunlite / npx tunlite install)');
+}
+
+// 0 = passwordless SSH ready; non-zero (tunlite exit 4 = needs-auth) means key setup required.
+export function checkSshAuth(sshHost, { run = spawnSync, bin = 'tunlite' } = {}) {
+  return run(bin, ['check', sshHost], { stdio: 'ignore' }).status;
+}

package/src/config.js

@@ -0,0 +1,6 @@
+export function loadConfig(env = process.env) {
+  return {
+    host: env.HANDMUX_HOST || '0.0.0.0',
+    port: Number(env.HANDMUX_PORT) || 4000,
+  };
+}

package/src/docPath.js

@@ -0,0 +1,46 @@
+const EXT = {
+  '.md': 'markdown', '.markdown': 'markdown', '.html': 'html', '.htm': 'html',
+  // Plain-text files: rendered verbatim in a <pre> (no markdown parsing).
+  '.txt': 'text', '.log': 'text', '.sh': 'text',
+};
+
+// Map a filename to our renderable doc type by extension, or null. Case-insensitive.
+export function docTypeFor(name) {
+  const m = /\.[A-Za-z0-9]+$/.exec(name || '');
+  return m ? (EXT[m[0].toLowerCase()] ?? null) : null;
+}
+
+// Image extensions the in-app viewer can show inline via <img> (GIF animates natively). SVG is safe
+// here because <img>-loaded SVG never runs its scripts. Returns 'image' or null. Case-insensitive.
+const IMG_EXT = new Set(['png', 'jpg', 'jpeg', 'jfif', 'gif', 'webp', 'svg', 'bmp', 'ico', 'avif', 'apng']);
+export function imageTypeFor(name) {
+  const m = /\.([A-Za-z0-9]+)$/.exec(name || '');
+  return m && IMG_EXT.has(m[1].toLowerCase()) ? 'image' : null;
+}
+
+// True if `child` equals `parent` or sits inside it. Both are expected to be realpaths.
+// Guards the sibling-prefix trap: /home/ab is NOT under /home/a.
+export function isUnder(child, parent) {
+  if (child === parent) return true;
+  const p = parent.endsWith('/') ? parent : parent + '/';
+  return child.startsWith(p);
+}
+
+// Sanitize a client-supplied upload filename to a single safe path segment, or null if unsafe.
+// Takes the basename (drops any dir part, handling both / and \), then rejects empty / '.' / '..'
+// and dotfiles (no hidden files). The result never contains a path separator.
+export function safeUploadName(raw) {
+  if (typeof raw !== 'string') return null;
+  const base = raw.split('/').pop().split('\\').pop();
+  if (!base || base === '.' || base === '..' || base[0] === '.') return null;
+  return base;
+}
+
+// True if `real` (a realpath at/under `home`) has any path segment BELOW home that starts with '.'
+// — i.e. it lives inside a hidden directory like ~/.ssh or ~/.config. `home` is the realpath of
+// $HOME. The home root itself is not hidden.
+export function hasHiddenSegment(real, home) {
+  if (real === home) return false;
+  const rel = real.startsWith(home.endsWith('/') ? home : home + '/') ? real.slice(home.length) : real;
+  return rel.split('/').filter(Boolean).some((seg) => seg.startsWith('.'));
+}

package/src/docs.js

@@ -0,0 +1,222 @@
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, basename } from 'node:path';
+import { docTypeFor, imageTypeFor, isUnder, hasHiddenSegment } from './docPath.js';
+
+const MAX_READ_BYTES = 2 * 1024 * 1024;        // 2MB cap for in-app text reads (readDoc)
+// Single source of truth for the 50MB transfer cap, shared by download (maxDownloadBytes default
+// below) and upload (httpApi.js imports this as the maxUploadBytes default). Server-side only.
+export const MAX_TRANSFER_BYTES = 50 * 1024 * 1024;
+
+// Flatten an absolute cwd into ONE filesystem-safe path segment for the per-project upload space,
+// Claude-Code style: '/' → '-' (so /Users/x/proj → -Users-x-proj), and any other non-portable char
+// → '_'. A valid cwd always starts with '/', so the key always starts with '-' — it can never be
+// '..'/'.' and, having no separators, can never escape the uploads root. Empty/relative → '_default'.
+export function encodeCwdKey(cwd) {
+  if (typeof cwd !== 'string' || cwd[0] !== '/') return '_default';
+  return cwd.replace(/\//g, '-').replace(/[^A-Za-z0-9._-]/g, '_') || '_default';
+}
+
+// Factory bound to a `home` root. All reads pass through fs.realpath then isUnder(realHome):
+// realpath collapses ../ and resolves symlinks, so the home-containment check is the final word —
+// a symlink whose target escapes home resolves outside and gets rejected.
+export function createDocs({ home, extraRoots = [], maxDownloadBytes = MAX_TRANSFER_BYTES } = {}) {
+  // $HOME is constant at runtime — resolve once at construction, reuse the same promise everywhere.
+  const realHomeP = fs.realpath(home);
+  // Browse / read / download / upload may also reach a few EXTRA roots OUTSIDE $HOME (e.g. /tmp,
+  // $TMPDIR) so transient files an agent drops there are reachable from the phone. Resolved once:
+  // realpath'd, deduped, missing ones skipped, and any extra already inside home dropped (home
+  // covers it). `home` is always roots[0]. Session-cwd (resolveCwd) and the upload stash stay
+  // home-only on purpose. The "under one of these roots" check replaces the old single isUnder(home).
+  const rootsP = (async () => {
+    const rh = await realHomeP;
+    const out = [rh];
+    for (const r of extraRoots) {
+      if (typeof r !== 'string' || !r) continue;
+      let real;
+      try { real = await fs.realpath(r); } catch { continue; } // not present on this host → skip
+      if (isUnder(real, rh) || out.includes(real)) continue;   // already covered by home / dup
+      out.push(real);
+    }
+    return out;
+  })();
+  // The allowed root that contains `real` (longest match wins should roots ever nest), or null.
+  const rootOf = (real, roots) => {
+    let best = null;
+    for (const r of roots) if (isUnder(real, r) && (!best || r.length > best.length)) best = r;
+    return best;
+  };
+
+  async function readDoc(rawPath) {
+    if (typeof rawPath !== 'string' || rawPath[0] !== '/') return { error: 'not absolute', status: 400 };
+    const type = docTypeFor(rawPath);
+    if (!type) return { error: 'bad extension', status: 400 };
+    let real;
+    try { real = await fs.realpath(rawPath); }
+    catch { return { error: 'not found', status: 404 }; }
+    if (!rootOf(real, await rootsP)) return { error: 'outside home', status: 400 };
+    let st;
+    try { st = await fs.stat(real); }
+    catch { return { error: 'not accessible', status: 404 }; }
+    if (!st.isFile()) return { error: 'not a file', status: 400 };
+    if (st.size > MAX_READ_BYTES) return { error: 'too large', status: 413 };
+    const content = await fs.readFile(real, 'utf8');
+    return { name: basename(real), type, content };
+  }
+
+  async function listDir(rawPath) {
+    const rh = await realHomeP;
+    const roots = await rootsP;
+    let real;
+    try { real = await fs.realpath(rawPath ? rawPath : home); }
+    catch { return { error: 'not found', status: 404 }; }
+    if (!rootOf(real, roots)) return { error: 'outside home', status: 400 };
+    const st = await fs.stat(real);
+    if (!st.isDirectory()) return { error: 'not a directory', status: 400 };
+    const dirents = await fs.readdir(real, { withFileTypes: true });
+    // withFileTypes uses lstat semantics: d.isFile() is false for symlinks, so symlinks are
+    // intentionally NOT listed (security property). Every regular file is listed now (not just
+    // docs); the extension decides whether it opens in-app as a doc ('doc'), an image viewer
+    // ('image'), or can only be downloaded ('file').
+    const dirEntries = [];
+    const fileDirents = [];
+    for (const d of dirents) {
+      if (d.isDirectory()) dirEntries.push({ name: d.name, type: 'dir' });
+      else if (d.isFile()) fileDirents.push(d);
+    }
+    // stat every file IN PARALLEL — a big dir is thousands of files, and one awaited stat each
+    // (serial) is what made listing hang for seconds. Promise.all lets the OS pipeline them.
+    const fileEntries = await Promise.all(fileDirents.map(async (d) => {
+      const type = docTypeFor(d.name) ? 'doc' : imageTypeFor(d.name) ? 'image' : 'file';
+      let size = 0;
+      try { size = (await fs.stat(join(real, d.name))).size; } catch { /* gone mid-list → size 0 */ }
+      return { name: d.name, type, size };
+    }));
+    const entries = [...dirEntries, ...fileEntries];
+    // dirs first; files (doc+file) interleaved alphabetically
+    entries.sort((a, b) =>
+      (a.type === 'dir' ? 0 : 1) - (b.type === 'dir' ? 0 : 1) || a.name.localeCompare(b.name));
+    // "up" stops at whichever allowed root we're in (each root is a ceiling), not only at home.
+    const parent = roots.includes(real) ? null : join(real, '..');
+    return { path: real, home: rh, roots, parent, entries };
+  }
+
+  // Resolve a path for DOWNLOAD: any regular file under home, no extension white-list (unlike
+  // readDoc). Same realpath+isUnder boundary; symlinks escaping home resolve outside → rejected.
+  async function statForDownload(rawPath) {
+    if (typeof rawPath !== 'string' || rawPath[0] !== '/') return { error: 'not absolute', status: 400 };
+    let real;
+    try { real = await fs.realpath(rawPath); }
+    catch { return { error: 'not found', status: 404 }; }
+    if (!rootOf(real, await rootsP)) return { error: 'outside home', status: 400 };
+    let st;
+    try { st = await fs.stat(real); }
+    catch { return { error: 'not accessible', status: 404 }; }
+    if (!st.isFile()) return { error: 'not a file', status: 400 };
+    if (st.size > maxDownloadBytes) return { error: 'too large', status: 413 };
+    return { real, name: basename(real), size: st.size };
+  }
+
+  // Resolve a path for UPLOAD TARGET: a directory under one of the allowed roots, not inside any
+  // hidden directory (relative to its own root). The $HOME root itself is off-limits (don't litter
+  // the home dir); an extra root like /tmp IS uploadable directly, since dropping files there is the
+  // whole point. Same realpath boundary as the rest.
+  async function resolveUploadDir(rawDir) {
+    if (typeof rawDir !== 'string' || rawDir[0] !== '/') return { error: 'not absolute', status: 400 };
+    const rh = await realHomeP;
+    let real;
+    try { real = await fs.realpath(rawDir); }
+    catch { return { error: 'not found', status: 404 }; }
+    const root = rootOf(real, await rootsP);
+    if (!root) return { error: 'outside home', status: 400 };
+    if (real === rh) return { error: 'home root not allowed', status: 400 };
+    if (hasHiddenSegment(real, root)) return { error: 'hidden directory not allowed', status: 400 };
+    let st;
+    try { st = await fs.stat(real); }
+    catch { return { error: 'not accessible', status: 404 }; }
+    if (!st.isDirectory()) return { error: 'not a directory', status: 400 };
+    return { real };
+  }
+
+  // Resolve the STASH upload target: a per-project folder under ~/.handmux/uploads, created on
+  // demand. Deliberately OUTSIDE the user's project trees (so uploads can never be `git add`-ed by
+  // accident) yet still under $HOME, so the absolute path the chat box pastes stays readable by an
+  // agent running anywhere. Mirrors Claude Code's per-project layout: the caller's cwd is flattened
+  // ('/'→'-') into a single path segment (see encodeCwdKey), so each working directory gets its own
+  // space; an unknown cwd falls into `_default`. Returns the realpath'd dir.
+  async function resolveStashDir(rawCwd) {
+    const rh = await realHomeP;
+    const target = join(rh, '.handmux', 'uploads', encodeCwdKey(rawCwd));
+    try { await fs.mkdir(target, { recursive: true }); }
+    catch { return { error: 'mkdir failed', status: 500 }; }
+    let real;
+    try { real = await fs.realpath(target); }       // re-resolve in case a segment is a symlink
+    catch { return { error: 'not accessible', status: 404 }; }
+    if (!isUnder(real, rh)) return { error: 'outside home', status: 400 };
+    return { real };
+  }
+
+  // Resolve a path for use as a NEW session/window CWD: any directory under home (home root IS
+  // allowed, and hidden dirs ARE allowed — the browser can navigate into them). Same realpath +
+  // isUnder boundary as the rest; symlinks escaping home resolve outside → rejected.
+  async function resolveCwd(rawDir) {
+    if (typeof rawDir !== 'string' || rawDir[0] !== '/') return { error: 'not absolute', status: 400 };
+    const rh = await realHomeP;
+    let real;
+    try { real = await fs.realpath(rawDir); }
+    catch { return { error: 'not found', status: 404 }; }
+    if (!isUnder(real, rh)) return { error: 'outside home', status: 400 };
+    let st;
+    try { st = await fs.stat(real); }
+    catch { return { error: 'not accessible', status: 404 }; }
+    if (!st.isDirectory()) return { error: 'not a directory', status: 400 };
+    return { real };
+  }
+
+  // Resolve a directory for BROWSE-side ops (the mkdir target): a directory under ANY allowed root
+  // (the root itself + hidden dirs allowed, like resolveCwd but multi-root). resolveCwd stays
+  // home-only — a new session's cwd should never land in a temp root by accident.
+  async function resolveBrowseDir(rawDir) {
+    if (typeof rawDir !== 'string' || rawDir[0] !== '/') return { error: 'not absolute', status: 400 };
+    let real;
+    try { real = await fs.realpath(rawDir); }
+    catch { return { error: 'not found', status: 404 }; }
+    if (!rootOf(real, await rootsP)) return { error: 'outside home', status: 400 };
+    let st;
+    try { st = await fs.stat(real); }
+    catch { return { error: 'not accessible', status: 404 }; }
+    if (!st.isDirectory()) return { error: 'not a directory', status: 400 };
+    return { real };
+  }
+
+  // Create a new directory `name` inside `parentRaw`. The parent must be a directory under one of
+  // the allowed roots (root + hidden dirs allowed). `name` must be a single safe path segment.
+  async function makeDir(parentRaw, name) {
+    const nm = typeof name === 'string' ? name.trim() : '';
+    if (!nm || nm === '.' || nm === '..' || nm.includes('/') || nm.includes('\\') || nm.includes('\0')) {
+      return { error: 'bad name', status: 400 };
+    }
+    const parent = await resolveBrowseDir(parentRaw); // realpath + under-a-root + isDirectory
+    if (parent.error) return parent;
+    const target = join(parent.real, nm);
+    try {
+      await fs.mkdir(target);
+    } catch (e) {
+      if (e.code === 'EEXIST') return { error: 'exists', status: 409 };
+      return { error: 'mkdir failed', status: 500 };
+    }
+    return { real: target };
+  }
+
+  return { readDoc, listDir, statForDownload, resolveUploadDir, resolveStashDir, resolveCwd, makeDir };
+}
+
+// The extra (outside-$HOME) roots the file browser may reach: the system temp dir and, if set, the
+// per-user $TMPDIR (on macOS that's /var/folders/.../T). Missing ones are skipped at resolve time.
+export function defaultExtraRoots(env = process.env) {
+  const roots = ['/tmp'];
+  if (env.TMPDIR) roots.push(env.TMPDIR);
+  return roots;
+}
+
+export const defaultDocs = createDocs({ home: homedir(), extraRoots: defaultExtraRoots() });

package/src/git.js

@@ -0,0 +1,185 @@
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, basename, isAbsolute } from 'node:path';
+import { execFile } from 'node:child_process';
+import { isUnder } from './docPath.js';
+
+// 只读子命令白名单：命令层硬过滤，杜绝任何写操作混入。
+const READONLY = new Set(['rev-parse', 'status', 'log', 'for-each-ref', 'diff', 'show', 'diff-tree']);
+const MAX_BUFFER = 8 * 1024 * 1024;
+
+export function createGit({ home } = {}) {
+  const realHomeP = fs.realpath(home);
+
+  function git(cwd, args) {
+    const sub = args[0];
+    if (!READONLY.has(sub)) return Promise.reject(new Error(`blocked subcommand: ${sub}`));
+    return new Promise((resolve, reject) => {
+      execFile('git', ['-C', cwd, '-c', 'core.quotepath=false', ...args], { maxBuffer: MAX_BUFFER }, (err, stdout) => {
+        if (err) reject(err); else resolve(stdout);
+      });
+    });
+  }
+
+  async function resolveRepo(rawPath) {
+    if (typeof rawPath !== 'string' || !isAbsolute(rawPath)) return { error: 'not absolute', status: 400 };
+    const rh = await realHomeP;
+    let real;
+    try { real = await fs.realpath(rawPath); } catch { return { error: 'not found', status: 404 }; }
+    if (!isUnder(real, rh)) return { error: 'outside home', status: 400 };
+    return { real };
+  }
+
+  async function isRepo(dir) {
+    try { return (await git(dir, ['rev-parse', '--is-inside-work-tree'])).trim() === 'true'; }
+    catch { return false; }
+  }
+
+  // `realDir` is used for git operations; `displayPath` is what we expose (the caller's original path,
+  // avoiding macOS /private/var vs /var confusion when the caller passed a non-realpath'd path).
+  async function repoMeta(realDir, displayPath) {
+    const p = displayPath ?? realDir;
+    let branch = 'HEAD';
+    try { branch = (await git(realDir, ['rev-parse', '--abbrev-ref', 'HEAD'])).trim(); } catch { /* empty repo */ }
+    let dirty = false;
+    try { dirty = (await git(realDir, ['status', '--porcelain'])).trim().length > 0; } catch { /* ignore */ }
+    return { name: basename(p), path: p, branch, dirty };
+  }
+
+  async function detectRepos(rawDir) {
+    const r = await resolveRepo(rawDir);
+    if (r.error) return r;
+    if (await isRepo(r.real)) return { repos: [await repoMeta(r.real, rawDir)] };
+    const repos = [];
+    let dirents = [];
+    try { dirents = await fs.readdir(r.real, { withFileTypes: true }); } catch { /* ignore */ }
+    for (const d of dirents) {
+      if (!d.isDirectory()) continue;
+      const child = join(r.real, d.name);
+      const childDisplay = join(rawDir, d.name);
+      if (await isRepo(child)) repos.push(await repoMeta(child, childDisplay));
+    }
+    repos.sort((a, b) => a.name.localeCompare(b.name));
+    return { repos };
+  }
+
+  async function status(rawRepo) {
+    const r = await resolveRepo(rawRepo);
+    if (r.error) return r;
+    if (!(await isRepo(r.real))) return { error: 'not a repo', status: 400 };
+    let out;
+    try { out = await git(r.real, ['status', '--porcelain']); }
+    catch { return { error: 'git error', status: 500 }; }
+    const changes = out.split('\n').filter(Boolean).map((line) => {
+      const x = line[0], y = line[1];
+      let path = line.slice(3);
+      const arrow = path.indexOf(' -> ');
+      if (arrow >= 0) path = path.slice(arrow + 4);
+      return { x: x === ' ' ? '' : x, y: y === ' ' ? '' : y, path };
+    });
+    return { changes };
+  }
+
+  const SEP = '\x1f';
+
+  // 分支 / ref 名校验:挡选项注入(开头 '-')、路径穿越('..')、NUL,并限定到安全字符子集。
+  // 只读 git log 用,失败时 git 自己会再拒一次。
+  function safeRef(ref) {
+    if (typeof ref !== 'string' || !ref) return null;
+    if (ref[0] === '-' || ref.includes('..') || ref.includes('\0')) return null;
+    if (!/^[A-Za-z0-9._/-]+$/.test(ref)) return null;
+    return ref;
+  }
+
+  async function log(rawRepo, limit = 50, ref) {
+    const r = await resolveRepo(rawRepo);
+    if (r.error) return r;
+    if (!(await isRepo(r.real))) return { error: 'not a repo', status: 400 };
+    const n = Math.max(1, Math.min(500, Number(limit) || 50));
+    const safeR = ref == null || ref === '' ? null : safeRef(ref);
+    if (ref && !safeR) return { error: 'bad ref', status: 400 };
+    const args = ['log', `-n${n}`, `--pretty=format:%H${SEP}%h${SEP}%s${SEP}%an${SEP}%ar`];
+    if (safeR) args.push(safeR); // git log <ref> …(指定分支只读看历史,不动工作树)
+    let out = '';
+    try { out = await git(r.real, args); }
+    catch { return { commits: [] }; } // 空仓库(无提交)/ 无此 ref → 空列表
+    const commits = out.split('\n').filter(Boolean).map((line) => {
+      const [hash, short, subject, author, relDate] = line.split(SEP);
+      return { hash, short, subject, author, relDate };
+    });
+    return { commits };
+  }
+
+  async function branches(rawRepo) {
+    const r = await resolveRepo(rawRepo);
+    if (r.error) return r;
+    if (!(await isRepo(r.real))) return { error: 'not a repo', status: 400 };
+    const fmt = ['%(refname:short)', '%(HEAD)', '%(upstream:short)', '%(upstream:track)'].join(SEP);
+    let out;
+    try { out = await git(r.real, ['for-each-ref', `--format=${fmt}`, 'refs/heads']); }
+    catch { return { branches: [] }; }
+    const branches = out.split('\n').filter(Boolean).map((line) => {
+      const [name, head, upstream, track] = line.split(SEP);
+      const ahead = Number((track.match(/ahead (\d+)/) || [])[1] || 0);
+      const behind = Number((track.match(/behind (\d+)/) || [])[1] || 0);
+      return { name, current: head === '*', upstream: upstream || null, ahead, behind };
+    });
+    return { branches };
+  }
+
+  // 文件路径校验:相对、非绝对、不以 '-' 开头(防选项注入)、无 '..' 段、无 NUL。
+  function safeRelPath(p) {
+    if (typeof p !== 'string' || !p || p[0] === '-' || isAbsolute(p)) return null;
+    if (p.includes('\0') || p.split('/').some((seg) => seg === '..')) return null;
+    return p;
+  }
+
+  const MAX_DIFF_BYTES = 512 * 1024;
+  function cap(text) {
+    if (text.length <= MAX_DIFF_BYTES) return { diff: text, truncated: false };
+    return { diff: text.slice(0, MAX_DIFF_BYTES), truncated: true };
+  }
+
+  // diff 语义:仅 path → 工作区 vs HEAD;staged → 暂存区 vs HEAD;commit → 该提交 vs 其父。
+  async function diff(rawRepo, { path, commit, staged } = {}) {
+    const r = await resolveRepo(rawRepo);
+    if (r.error) return r;
+    if (!(await isRepo(r.real))) return { error: 'not a repo', status: 400 };
+    const rel = safeRelPath(path);
+    if (!rel) return { error: 'bad path', status: 400 };
+    let args;
+    if (commit) {
+      if (!/^[0-9a-fA-F]{4,40}$/.test(commit)) return { error: 'bad commit', status: 400 };
+      args = ['show', '--format=', commit, '--', rel];
+    } else if (staged) {
+      args = ['diff', '--staged', '--', rel];
+    } else {
+      args = ['diff', 'HEAD', '--', rel];
+    }
+    let out = '';
+    try { out = await git(r.real, args); } catch (e) { return { error: 'diff failed', status: 500 }; }
+    return cap(out);
+  }
+
+  async function commit(rawRepo, hash) {
+    const r = await resolveRepo(rawRepo);
+    if (r.error) return r;
+    if (!(await isRepo(r.real))) return { error: 'not a repo', status: 400 };
+    if (!/^[0-9a-fA-F]{4,40}$/.test(hash)) return { error: 'bad commit', status: 400 };
+    let message, ns;
+    try {
+      message = (await git(r.real, ['show', '-s', '--format=%B', hash])).trim();
+      // --root 让首次提交(无父)也能列出文件。
+      ns = await git(r.real, ['diff-tree', '--no-commit-id', '--name-status', '-r', '--root', hash]);
+    } catch { return { error: 'git error', status: 500 }; }
+    const files = ns.split('\n').filter(Boolean).map((line) => {
+      const [code, ...rest] = line.split('\t');
+      return { x: code[0], y: '', path: rest[rest.length - 1] };
+    });
+    return { message, files };
+  }
+
+  return { resolveRepo, isRepo, detectRepos, status, log, branches, diff, commit };
+}
+
+export const defaultGit = createGit({ home: homedir() });