npm - handmux - Versions diffs - 0.5.0 - Mend

handmux 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (58) hide show

package/LICENSE +21 -0
package/README.md +303 -0
package/README.zh-CN.md +285 -0
package/bin/handmux.js +417 -0
package/hooks/handmux-notify.sh +20 -0
package/hooks/handmux-write.cjs +92 -0
package/package.json +52 -0
package/public/assets/index-BN-IwtP6.css +32 -0
package/public/assets/index-BUQ0R83h.js +157 -0
package/public/fonts/JetBrainsMonoNerdFontMono-Regular.woff2 +0 -0
package/public/fonts/TWUnifont.woff2 +0 -0
package/public/icons/apple-touch-icon.png +0 -0
package/public/icons/badge-96.png +0 -0
package/public/icons/icon-192.png +0 -0
package/public/icons/icon-512.png +0 -0
package/public/icons/logo.svg +32 -0
package/public/index.html +105 -0
package/public/manifest.webmanifest +37 -0
package/public/offline.html +50 -0
package/public/sw.js +117 -0
package/src/.gitkeep +0 -0
package/src/appName.js +23 -0
package/src/asr/iflyConfig.js +10 -0
package/src/asr/iflySign.js +16 -0
package/src/auth.js +30 -0
package/src/claudeEvents.js +212 -0
package/src/cli/cfNamed.js +5 -0
package/src/cli/claudeHooks.js +116 -0
package/src/cli/cloudflareUrl.js +9 -0
package/src/cli/cloudflared.js +53 -0
package/src/cli/drivers.js +59 -0
package/src/cli/options.js +169 -0
package/src/cli/probe.js +16 -0
package/src/cli/qr.js +34 -0
package/src/cli/service.js +98 -0
package/src/cli/setupWizard.js +248 -0
package/src/cli/sshTunnel.js +12 -0
package/src/cli/state.js +42 -0
package/src/cli/supervisor.js +172 -0
package/src/cli/tmuxConf.js +90 -0
package/src/cli/tmuxVersion.js +49 -0
package/src/cli/tunlite.js +22 -0
package/src/config.js +6 -0
package/src/docPath.js +46 -0
package/src/docs.js +222 -0
package/src/git.js +185 -0
package/src/httpApi.js +546 -0
package/src/previewServer.js +182 -0
package/src/previews.js +118 -0
package/src/push.js +121 -0
package/src/server.js +97 -0
package/src/staticCache.js +8 -0
package/src/tmux/commands.js +223 -0
package/src/trimCapture.js +28 -0
package/src/uploadTypes.js +28 -0
package/tmux/README.md +77 -0
package/tmux/claude-tab-seed.py +67 -0
package/tmux/claude-tab-seen.sh +14 -0

package/src/previewServer.js ADDED Viewed

@@ -0,0 +1,182 @@
+// server/src/previewServer.js
+// Serves registered static-preview directories under /preview, reusing the system token via a cookie
+// (a browser opening a URL can't send a Bearer header). Absolute-rooted assets (/assets/...) are
+// served from the right preview dir via a Referer fallback (design's "方案 A").
+// Also handles dynamic preview: Host-based dispatch to loopback ports (HTTP + WS upgrade).
+import net from 'node:net';
+import http from 'node:http';
+import express from 'express';
+import { tokenEquals } from './auth.js';
+import { safePreviewName } from './previews.js';
+const COOKIE = 'tw_preview';
+// Read one cookie value from a raw Cookie header, URL-decoded. No cookie-parser dep (zero-dep house style).
+export function parseCookie(header, name) {
+  if (!header) return null;
+  const m = new RegExp(`(?:^|;\\s*)${name}=([^;]*)`).exec(header);
+  return m ? decodeURIComponent(m[1]) : null;
+}
+// Credential check shared by the /preview gate AND the referer fallback. Accepts the token via
+// ?token= (first visit) or the tw_preview cookie (subsequent). timing-safe via tokenEquals.
+export function credOk(req, token) {
+  const q = req.query?.token;
+  const provided = (typeof q === 'string' && q) ? q : parseCookie(req.headers?.cookie, COOKIE);
+  if (!provided) return false;
+  try { return tokenEquals(provided, token); } catch { return false; }
+}
+export { COOKIE };
+// A preview host is exactly `<name>.<domain>` where <name> is one safe label. Anything deeper, the
+// base domain itself, or a foreign domain → not ours (null). domain unset → dynamic disabled → null.
+// The configured domain may carry a :port (the edge runs on a non-standard port, e.g. :39999) — that
+// port belongs in the browser URL, but Host matching is hostname-only, so strip it here. The incoming
+// `host` already has its port stripped by the caller.
+export function isPreviewHost(host, domain) {
+  if (!domain || !host) return null;
+  const base = domain.split(':')[0];
+  const suffix = `.${base}`;
+  if (!host.endsWith(suffix)) return null;
+  const label = host.slice(0, -suffix.length);
+  if (!label || label.includes('.')) return null; // single label only
+  return safePreviewName(label);
+}
+// Cookie scope = base domain minus its first label (preview.example.com → example.com) so the token
+// cookie set on a preview subdomain is also sent to the main app and every sibling preview. A cookie
+// Domain attribute can't carry a port, so strip any :port from the configured domain first.
+function cookieScope(domain) {
+  if (!domain) return null;
+  const base = domain.split(':')[0];
+  const dot = base.indexOf('.');
+  return dot === -1 ? base : base.slice(dot + 1);
+}
+// Resolve the on-disk file for a request path under a preview: '' or '<dir>/' → its index.html.
+function fileFor(rest) { return (!rest || rest.endsWith('/')) ? `${rest}index.html` : rest; }
+export function createPreview({ previews, token, domain = null }) {
+  const router = express.Router();
+  const cookieDomain = cookieScope(domain);
+  // Gate: ?token= (set cookie + 302 strip) OR a valid cookie; else 401.
+  router.use((req, res, next) => {
+    const q = req.query?.token;
+    if (typeof q === 'string' && q && credOk(req, token)) {
+      res.setHeader('Set-Cookie', `${COOKIE}=${encodeURIComponent(token)}; Path=/; HttpOnly; SameSite=Lax`);
+      const u = new URL(req.originalUrl, 'http://x');
+      u.searchParams.delete('token');
+      return res.redirect(302, u.pathname + u.search);
+    }
+    if (!credOk(req, token)) return res.status(401).send('unauthorized');
+    next();
+  });
+  function serve(name, rest, res) {
+    const { state, entry } = previews.get(name);
+    if (state === 'missing') return res.status(404).type('html').send('<!doctype html><meta charset="utf-8"><h1>预览不存在</h1>');
+    if (state === 'expired') return res.status(410).type('html').send('<!doctype html><meta charset="utf-8"><h1>预览已过期</h1><p>请回到 app 重新启动预览。</p>');
+    res.setHeader('Cache-Control', 'no-store');
+    res.sendFile(fileFor(rest), { root: entry.dir, dotfiles: 'deny' }, (err) => {
+      if (err && !res.headersSent) res.status(err.statusCode || 404).end();
+    });
+  }
+  // /:name catches both '/live' (no trailing slash → redirect) and '/live/' (trailing slash → serve root).
+  // /:name/* catches '/live/index.html', '/live/assets/x.js', etc.
+  router.get('/:name', (req, res, next) => {
+    if (req.url.endsWith('/')) return serve(req.params.name, '', res);
+    res.redirect(301, `/preview/${encodeURIComponent(req.params.name)}/`);
+  });
+  router.get('/:name/*', (req, res) => serve(req.params.name, req.params[0], res));
+  // Referer fallback (mount AFTER /preview, BEFORE express.static): an absolute /assets/... request
+  // whose Referer is a preview page is served from that preview's dir. Reuses credOk so it can never
+  // read a dir without a valid token/cookie. Misses fall through to the normal static/SPA layer.
+  function refererFallback(req, res, next) {
+    if (req.method !== 'GET') return next();
+    if (req.path.startsWith('/api') || req.path.startsWith('/preview')) return next();
+    const ref = req.headers.referer;
+    if (!ref) return next();
+    let refPath;
+    try { refPath = new URL(ref).pathname; } catch { return next(); }
+    const m = /^\/preview\/([^/]+)\//.exec(refPath);
+    if (!m) return next();
+    if (!credOk(req, token)) return next();
+    const { state, entry } = previews.get(decodeURIComponent(m[1]));
+    if (state !== 'active') return next();
+    res.setHeader('Cache-Control', 'no-store');
+    res.sendFile(req.path, { root: entry.dir, dotfiles: 'deny' }, (err) => {
+      if (err && !res.headersSent) next();
+    });
+  }
+  // Reverse-proxy one request to the dynamic preview's loopback port. No prefix strip — the app owns
+  // its own root, so path/method/headers/body forward as-is. `host` is the loopback family the app was
+  // found on at register time ('127.0.0.1' or '::1'); the Host header stays 127.0.0.1:<port> so a dev
+  // server's host check (e.g. Vite, whose allowedHosts include localhost/127.0.0.1) is satisfied.
+  function proxyHttp(port, host, req, res) {
+    const headers = { ...req.headers, host: `127.0.0.1:${port}` };
+    const up = http.request({ host: host || '127.0.0.1', port, method: req.method, path: req.url, headers }, (upRes) => {
+      res.writeHead(upRes.statusCode, upRes.headers);
+      upRes.on('error', () => res.destroy()); // mid-stream upstream reset (after headers) → tear down the client socket
+      upRes.pipe(res);
+    });
+    up.on('error', () => { if (!res.headersSent) res.status(502).type('text').end('preview upstream error'); });
+    req.pipe(up);
+  }
+  // Host-based dispatch middleware. Mount FIRST (before /api). A non-preview Host just calls next() →
+  // the request falls through to the existing app, zero impact.
+  function dynamicProxy(req, res, next) {
+    const host = (req.headers.host || '').split(':')[0];
+    const name = isPreviewHost(host, domain);
+    if (!name) return next();
+    const q = req.query?.token;
+    if (typeof q === 'string' && q && credOk(req, token)) {
+      const scope = cookieDomain ? `; Domain=${cookieDomain}` : '';
+      res.setHeader('Set-Cookie', `${COOKIE}=${encodeURIComponent(token)}${scope}; Path=/; HttpOnly; SameSite=Lax`);
+      const u = new URL(req.originalUrl, 'http://x');
+      u.searchParams.delete('token');
+      return res.redirect(302, u.pathname + u.search);
+    }
+    if (!credOk(req, token)) return res.status(401).send('unauthorized');
+    const { state, entry } = previews.get(name);
+    if (state === 'missing') return res.status(404).type('html').send('<!doctype html><meta charset="utf-8"><h1>预览不存在</h1>');
+    if (state === 'expired') return res.status(410).type('html').send('<!doctype html><meta charset="utf-8"><h1>预览已过期</h1><p>请回到 app 重新启动预览。</p>');
+    if (entry.kind !== 'dynamic') return res.status(404).end(); // a static name reached via subdomain — not served here
+    proxyHttp(entry.port, entry.host, req, res);
+  }
+  // WebSocket (and any raw Upgrade) for a dynamic preview: same cookie auth, then a bare TCP pipe to
+  // the loopback port — covers HMR, SSE-over-ws, and an app's own websockets. Wired via
+  // server.on('upgrade'). A non-preview host or failed auth just destroys the socket (the app has no
+  // other ws endpoints).
+  function onUpgrade(req, socket, head) {
+    const host = (req.headers.host || '').split(':')[0];
+    const name = isPreviewHost(host, domain);
+    if (!name) return socket.destroy();
+    // ws handshakes rarely carry ?token=; the Domain-scoped cookie set on the first HTTP load is what
+    // authorizes them. Build a minimal req-shape for credOk (query parsed from the URL for parity).
+    let query = {};
+    try { query = Object.fromEntries(new URL(req.url, 'http://x').searchParams); } catch { /* none */ }
+    if (!credOk({ query, headers: req.headers }, token)) return socket.destroy();
+    const { state, entry } = previews.get(name);
+    if (state !== 'active' || entry.kind !== 'dynamic') return socket.destroy();
+    const up = net.connect(entry.port, entry.host || '127.0.0.1', () => {
+      const fwd = { ...req.headers, host: `127.0.0.1:${entry.port}` };
+      up.write(`GET ${req.url} HTTP/1.1\r\n`);
+      for (const [k, v] of Object.entries(fwd)) up.write(`${k}: ${v}\r\n`);
+      up.write('\r\n');
+      if (head && head.length) up.write(head);
+      up.pipe(socket);
+      socket.pipe(up);
+    });
+    up.on('error', () => socket.destroy());
+    socket.on('error', () => up.destroy());
+  }
+  return { router, refererFallback, dynamicProxy, onUpgrade };
+}

package/src/previews.js ADDED Viewed

@@ -0,0 +1,118 @@
+// server/src/previews.js
+// Preview registry. Maps a safe single-segment name → either an on-disk directory under $HOME
+// (kind:'static') or a local port (kind:'dynamic'), with a TTL. Persistence mirrors push.js: a JSON
+// array at server/data/previews.json, read fresh on each op. Pure-ish: home/now/store/ttl plus the
+// dynamic switch and port probe are injected so it unit-tests on its own.
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { isUnder } from './docPath.js';
+export function safePreviewName(raw) {
+  if (typeof raw !== 'string') return null;
+  if (!/^[A-Za-z0-9._-]+$/.test(raw)) return null;
+  if (raw === '.' || raw === '..' || raw[0] === '.') return null;
+  // Normalize to lowercase: a dynamic preview is reached via a subdomain, and browsers lowercase the
+  // hostname — so a stored name with uppercase (from a tmux window name) could never be matched. Keep
+  // register/get/subdomain all on the same lowercased key.
+  return raw.toLowerCase();
+}
+// Is something listening on a loopback `host:port`? A quick TCP connect with a short timeout.
+function probeHost(port, host, timeout) {
+  return new Promise((resolve) => {
+    const s = net.connect({ port, host });
+    const finish = (ok) => { s.destroy(); resolve(ok); };
+    s.setTimeout(timeout, () => finish(false));
+    s.once('connect', () => finish(true));
+    s.once('error', () => finish(false));
+  });
+}
+// Which loopback host answers on `port` — '127.0.0.1', '::1', or null if neither. macOS dev servers
+// often bind ONLY IPv6 localhost (::1), so a 127.0.0.1-only probe wrongly reports "not listening".
+// The answering host is stored on the entry so the proxy connects to the same family the app is on.
+async function probeListening(port, timeout = 300) {
+  if (await probeHost(port, '127.0.0.1', timeout)) return '127.0.0.1';
+  if (await probeHost(port, '::1', timeout)) return '::1';
+  return null;
+}
+export function createPreviews({
+  home = homedir(),
+  store = process.env.PREVIEW_STORE || path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../data/previews.json'),
+  now = () => Date.now(),
+  ttlMs = Number(process.env.HANDMUX_PREVIEW_TTL) || 3_600_000,
+  dynamicEnabled = false,
+  probePort = probeListening,
+} = {}) {
+  let realHome;
+  try { realHome = fs.realpathSync(home); } catch { realHome = home; }
+  const loadStore = () => {
+    try { return JSON.parse(fs.readFileSync(store, 'utf8')) || []; } catch { return []; }
+  };
+  const saveStore = (arr) => {
+    try { fs.mkdirSync(path.dirname(store), { recursive: true }); fs.writeFileSync(store, JSON.stringify(arr)); }
+    catch { /* best effort: a lost registry just means previews must be re-started */ }
+  };
+  // Common upsert: drop any prior entry with this name (so static↔dynamic switching just replaces),
+  // stamp a single now() into createdAt/expiresAt, persist.
+  const upsert = (fields) => {
+    const all = loadStore().filter((e) => e && e.name !== fields.name);
+    const ts = now();
+    const entry = { ...fields, createdAt: ts, expiresAt: ts + ttlMs };
+    all.push(entry);
+    saveStore(all);
+    return { name: entry.name, kind: entry.kind, expiresAt: entry.expiresAt };
+  };
+  async function register({ name, dir, port }) {
+    const nm = safePreviewName(name);
+    if (!nm) return { error: 'bad name', status: 400 };
+    if (port !== undefined && port !== null && port !== '') {
+      if (!dynamicEnabled) return { error: 'dynamic disabled', status: 400 };
+      const p = Number(port);
+      if (!Number.isInteger(p) || p < 1 || p > 65535) return { error: 'bad port', status: 400 };
+      const host = await probePort(p); // '127.0.0.1' | '::1' | null
+      if (!host) return { error: 'port not listening', status: 400 };
+      return upsert({ name: nm, kind: 'dynamic', port: p, host });
+    }
+    if (typeof dir !== 'string' || dir[0] !== '/') return { error: 'not absolute', status: 400 };
+    let real;
+    try { real = fs.realpathSync(dir); } catch { return { error: 'not found', status: 404 }; }
+    if (!isUnder(real, realHome)) return { error: 'outside home', status: 400 };
+    let st;
+    try { st = fs.statSync(real); } catch { return { error: 'not accessible', status: 404 }; }
+    if (!st.isDirectory()) return { error: 'not a directory', status: 400 };
+    return upsert({ name: nm, kind: 'static', dir: real });
+  }
+  function get(name) {
+    const all = loadStore();
+    const entry = all.find((e) => e && e.name === name);
+    if (!entry) return { state: 'missing' };
+    if (entry.expiresAt <= now()) { saveStore(all.filter((e) => e.name !== name)); return { state: 'expired' }; }
+    return { state: 'active', entry: { kind: 'static', ...entry } }; // legacy rows (no kind) → static
+  }
+  function list() {
+    const all = loadStore();
+    const active = all.filter((e) => e && e.expiresAt > now());
+    if (active.length !== all.length) saveStore(active);
+    return active.map((e) => (e.kind === 'dynamic'
+      ? { name: e.name, kind: 'dynamic', port: e.port, expiresAt: e.expiresAt }
+      : { name: e.name, kind: 'static', dir: e.dir, expiresAt: e.expiresAt }));
+  }
+  function remove(name) {
+    const all = loadStore();
+    const next = all.filter((e) => e && e.name !== name);
+    if (next.length !== all.length) saveStore(next);
+  }
+  return { register, get, list, remove };
+}

package/src/push.js ADDED Viewed

@@ -0,0 +1,121 @@
+// Web Push (VAPID) — minimal delivery layer. Sends notifications to subscribed devices via the
+// browser/OS push services (Android=FCM, iOS=APNs); the server only talks to those services, never
+// to the phone directly, so device reachability/queueing is their problem (see TTL/topic below).
+//
+// Subscriptions are stored as records: { subscription, boundSessions }. The subscription field is
+// the raw PushSubscription the browser hands us ({endpoint, keys:{p256dh, auth}}); boundSessions is
+// the list of session names this device cares about (used by sendToSession for targeted delivery). A
+// dead subscription (404/410 from the push service) is pruned on the next send.
+import webpush from 'web-push';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const STORE = process.env.PUSH_STORE || path.resolve(here, '../data/push-subs.json');
+// VAPID is optional: without keys every send is a no-op, so the server still boots in an
+// environment that hasn't generated keys (configured=false surfaces as a 503 on /vapid). Push delivers
+// whenever VAPID is configured — there is no separate "dev vs prod server" anymore (one config file, one
+// `handmux start`). If you run a second instance on the same host and don't want it to deliver, leave
+// `vapid` out of that instance's config. Init is LAZY (first use) so the module is import-safe.
+let inited = false;
+let configured = false;
+function ensureInit() {
+  if (inited) return;
+  inited = true;
+  configured = !!(process.env.VAPID_PUBLIC && process.env.VAPID_PRIVATE);
+  if (configured) {
+    webpush.setVapidDetails(
+      // Apple (APNs) rejects a VAPID subject on a fake/.local domain with BadJwtToken — it must be a
+      // valid mailto:/https: with a real-looking domain. example.com is reserved and accepted by both.
+      process.env.VAPID_SUBJECT || 'mailto:admin@example.com',
+      process.env.VAPID_PUBLIC,
+      process.env.VAPID_PRIVATE,
+    );
+  }
+}
+let subs = load();
+function load() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(STORE, 'utf8')) || [];
+    return raw.map((e) => (e && e.subscription)
+      ? { subscription: e.subscription, boundSessions: e.boundSessions || [] }
+      : { subscription: e, boundSessions: [] }); // migrate old bare-subscription entries
+  } catch { return []; }
+}
+function persist() {
+  try {
+    fs.mkdirSync(path.dirname(STORE), { recursive: true });
+    fs.writeFileSync(STORE, JSON.stringify(subs));
+  } catch { /* best effort — a lost subscription just means the client re-subscribes next launch */ }
+}
+export function isConfigured() { ensureInit(); return configured; }
+export function publicKey() { ensureInit(); return process.env.VAPID_PUBLIC || null; }
+export function count() { return subs.length; }
+export function addSubscription(sub, boundSessions = []) {
+  if (!sub || typeof sub.endpoint !== 'string') return false;
+  const i = subs.findIndex((s) => s.subscription.endpoint === sub.endpoint);
+  if (i === -1) subs.push({ subscription: sub, boundSessions });
+  else subs[i] = { subscription: sub, boundSessions };
+  persist();
+  return true;
+}
+export function updateBound(endpoint, boundSessions = []) {
+  const rec = subs.find((s) => s.subscription.endpoint === endpoint);
+  if (rec) { rec.boundSessions = boundSessions; persist(); }
+}
+export function removeSubscription(endpoint) {
+  const before = subs.length;
+  subs = subs.filter((s) => s.subscription.endpoint !== endpoint);
+  if (subs.length !== before) persist();
+}
+// The push-service Topic header (RFC 8030) must be ≤32 URL/filename-safe base64 chars [A-Za-z0-9_-].
+// An invalid topic makes the service reject the ENTIRE send with a non-404/410 error that deliver()
+// swallows — a silent zero-delivery, no log, no prune. tmux pane ids carry a '%' (e.g. %4), so a
+// pane-derived topic ("pane-%4") breaks every per-pane push (需要你 / 已完成). Sanitize here, the layer
+// that owns the web-push contract, so no caller has to know the rule.
+function safeTopic(t) {
+  if (!t) return undefined;
+  const s = t.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 32);
+  return s || undefined;
+}
+// TTL bounds staleness (a phone offline longer than this drops the push instead of getting it
+// hours later); topic collapses older undelivered messages with the same key so a device coming
+// back online sees only the latest per topic. urgency hints the OS how aggressively to wake.
+function options(opts = {}) {
+  return { TTL: opts.ttl ?? 90, urgency: opts.urgency || 'normal', topic: safeTopic(opts.topic) };
+}
+async function deliver(records, payload, opts = {}) {
+  ensureInit();
+  if (!configured) return { sent: 0, configured: false };
+  const data = JSON.stringify(payload);
+  const dead = [];
+  let sent = 0;
+  await Promise.all(records.map(async (rec) => {
+    try { await webpush.sendNotification(rec.subscription, data, options(opts)); sent += 1; }
+    catch (e) { if (e?.statusCode === 404 || e?.statusCode === 410) dead.push(rec.subscription.endpoint); }
+  }));
+  if (dead.length) { subs = subs.filter((s) => !dead.includes(s.subscription.endpoint)); persist(); }
+  return { sent, configured: true };
+}
+export const sendToAll = (payload, opts = {}) => deliver(subs, payload, opts);
+export const sendToSession = (session, payload, opts = {}) =>
+  deliver(subs.filter((s) => s.boundSessions.includes(session)), payload, opts);
+// Back-compat: the /push/subscribe welcome still pushes to a single just-added subscription.
+export async function sendToOne(sub, payload, opts = {}) {
+  const rec = subs.find((s) => s.subscription.endpoint === sub.endpoint)
+    ?? { subscription: sub, boundSessions: [] };
+  return deliver([rec], payload, opts);
+}

package/src/server.js ADDED Viewed

@@ -0,0 +1,97 @@
+import express from 'express';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadConfig } from './config.js';
+import { loadToken } from './auth.js';
+import { createApiRouter } from './httpApi.js';
+import { loadUploadExts } from './uploadTypes.js';
+import { createClaudeEvents } from './claudeEvents.js';
+import * as commands from './tmux/commands.js';
+import * as push from './push.js';
+import { cacheControlFor } from './staticCache.js';
+import { applyAppName, applyManifestName } from './appName.js';
+import { homedir } from 'node:os';
+import { createPreviews } from './previews.js';
+import { createPreview } from './previewServer.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+// There is ONE config source — ~/.handmux/config.json — and ONE way to run handmux: `handmux start`
+// (the CLI; `node bin/handmux.js start` from a source checkout is the same thing). The CLI resolves
+// the config and spawns this server with everything it needs in the environment, so the server reads
+// only process.env here (no .env files, no NODE_ENV branching). Running this file directly is not a
+// supported entry point — go through the CLI.
+const cfg = loadConfig();
+const token = loadToken();
+const uploadExts = loadUploadExts();
+// The inbox is driven by a JSON state file the Claude hooks maintain (server/hooks/handmux-notify.sh →
+// handmux-write.js). We only READ it. start() watches it so idle/permission push fires even when no
+// client is polling; getStates reads it fresh on each /states.
+const events = createClaudeEvents({ commands, push });
+events.start();
+// Static-site + dynamic preview. The dynamic side is enabled by HANDMUX_PREVIEW_DOMAIN (the wildcard
+// base domain, e.g. preview.example.com); unset → static only. One registry instance is shared by the
+// API (register/list/remove), the /preview static layer, and the Host-based dynamic proxy.
+const previewDomain = process.env.HANDMUX_PREVIEW_DOMAIN || null;
+const previews = createPreviews({ home: homedir(), dynamicEnabled: !!previewDomain });
+const preview = createPreview({ previews, token, domain: previewDomain });
+const app = express();
+// Host-based dispatch FIRST: a request to <name>.<domain> is reverse-proxied to its dynamic preview;
+// every other Host falls straight through (next()) to the app below, unaffected.
+app.use(preview.dynamicProxy);
+app.use('/api', createApiRouter({ token, events, uploadExts, previews, previewDomain }));
+app.use('/preview', preview.router);
+app.use(preview.refererFallback);
+// Serve the built web client so one process hosts both the API and the frontend (single origin, no dev
+// proxy). Prefer the bundled copy inside the package (server/public — what `npm publish` ships); fall back
+// to the sibling web/dist of a source checkout. Override either with HANDMUX_STATIC_DIR.
+const bundledDir = path.resolve(here, '../public');
+const sourceDir = path.resolve(here, '../../web/dist');
+const staticDir = process.env.HANDMUX_STATIC_DIR || (fs.existsSync(bundledDir) ? bundledDir : sourceDir);
+const indexPath = path.join(staticDir, 'index.html');
+// Optional custom instance name (handmux start --name). When set, the prebuilt shell + manifest are
+// rewritten on the way out so the browser-tab title and "Add to Home Screen" label match the user's
+// name — the bundle ships generic and is renamed at serve time, never rebuilt. Unset → serve as-is.
+const appName = process.env.HANDMUX_APP_NAME || null;
+let renamedIndex = null; // computed once; the name is fixed for the process lifetime
+if (appName) {
+  app.get('/manifest.webmanifest', (req, res, next) => {
+    try {
+      const raw = fs.readFileSync(path.join(staticDir, 'manifest.webmanifest'), 'utf8');
+      res.type('application/manifest+json').send(JSON.stringify(applyManifestName(JSON.parse(raw), appName)));
+    } catch { next(); }
+  });
+}
+// index:false so the renamed shell below owns "/" too (otherwise static would serve the generic one).
+app.use(express.static(staticDir, {
+  index: false,
+  // Cache-Control policy lives in staticCache.js (unit-tested): index.html + sw.js are never cached
+  // (stale-shell / stale-SW trap), content-hashed assets cache forever.
+  setHeaders: (res, filePath) => res.setHeader('Cache-Control', cacheControlFor(filePath)),
+}));
+// SPA fallback: serve index.html for any non-API GET (client routing lives in the URL hash, so
+// the server only ever needs to hand back the one HTML shell). API 404s pass through untouched.
+app.get('*', (req, res, next) => {
+  if (req.path.startsWith('/api/')) return next();
+  res.setHeader('Cache-Control', 'no-store');
+  if (appName) {
+    try {
+      if (renamedIndex == null) renamedIndex = applyAppName(fs.readFileSync(indexPath, 'utf8'), appName);
+      return res.type('html').send(renamedIndex);
+    } catch { /* fall through to sendFile */ }
+  }
+  res.sendFile(indexPath);
+});
+const server = app.listen(cfg.port, cfg.host, () => {
+  console.log(`[handmux] listening on http://${cfg.host}:${cfg.port} (serving ${staticDir})`);
+});
+// WebSocket/HMR for dynamic previews: route raw Upgrade by Host to the right loopback port.
+server.on('upgrade', preview.onUpgrade);

package/src/staticCache.js ADDED Viewed

@@ -0,0 +1,8 @@
+// Cache-Control policy for the static web bundle. index.html and the service worker must NEVER be
+// HTTP-cached — an installed PWA would otherwise keep loading a stale shell (pointing at missing
+// hashed assets) or a stale SW. Everything else under dist carries a content hash in its name, so
+// it's safe to cache forever. Pure so it unit-tests on its own.
+export function cacheControlFor(filePath) {
+  if (filePath.endsWith('.html') || filePath.endsWith('/sw.js')) return 'no-store';
+  return 'public, max-age=31536000, immutable';
+}