handmux 0.10.0 → 0.11.0

package/README.md

@@ -59,10 +59,10 @@ handmux start --tunnel cloudflare   # instant public URL (cloudflared auto-insta
 
 ## Networking: one decision
 
-LAN-only by default, nothing exposed. To reach it from outside, just ask: **does your machine already have a public address?**
+No tunnel by default — the phone connects **straight to your own computer**, nothing exposed and no middleman. To reach it from outside, just ask: **does your machine already have a public address?**
 
 - **Yes** (cloud box / public IP / forwarded port) — no tunnel needed, connect directly; fastest and most private.
-- **No** — open a tunnel: `cloudflare` (zero-config, up in seconds, but its public nodes can be slow or unreliable in some regions) · `cloudflare-named` (your own domain, steadier) · `ssh` self-hosted (through your own server — the pick where Cloudflare is unreliable, e.g. mainland China).
+- **No** — open a tunnel. Each runs on **your own free third-party account** — handmux just wires it up and operates no relay of its own: `cloudflare` (zero-config, up in seconds, but its public edge can be slow or unreliable in some regions) · `cloudflare-named` (your own domain, steadier) · `natapp` / `cpolar` (domestic providers that stay reachable inside mainland China) · `ssh` self-hosted (through your own server).
 
 > Tunnel config, server-side reverse proxy, autostart, voice/push credentials, and port previews → see the **[docs](https://handmux.com/docs)**.
 

package/README.zh-CN.md

@@ -59,10 +59,10 @@ handmux start --tunnel cloudflare   # 即时公网地址(自动装 cloudflared)
 
 ## 联网:一句话决策
 
-默认只在局域网、什么都不暴露。想从外面连,只问一句:**电脑有没有公网地址?**
+默认不开隧道——手机**直连你自己的电脑**,什么都不暴露、也没有中间人。想从外面连,只问一句:**电脑有没有公网地址?**
 
 - **有**(云主机 / 公网 IP / 已端口转发)—— 不用隧道,直接连,最快也最私密。
-- **没有** —— 开一条隧道:`cloudflare`(零配置秒通,但公共节点在国内常不稳定)· `cloudflare-named`(你的域名,更稳)· `ssh` 自建(接你自己的服务器,**国内网络首选**)。
+- **没有** —— 开一条隧道。每条都跑在**你自己的免费第三方账号**上,handmux 只负责接通、自身不设中转:`cloudflare`(零配置秒通,但公共边缘在国内常不稳)· `cloudflare-named`(你的域名,更稳)· `natapp` / `cpolar`(国内厂商,大陆境内可达)· `ssh` 自建(接你自己的服务器)。
 
 > 隧道配置、服务端反向代理、开机自启、语音 / 推送凭证、端口预览等细节 → 见 **[文档](https://handmux.com/docs)**。
 

package/bin/handmux.js

@@ -7,8 +7,8 @@
 //                     let you try variations for one run (e.g. --tunnel cloudflare).
 //   handmux setup   — the one place to configure persistently. Interactive; writes ~/.handmux/config.json
 //                     (name, tunnel, push, voice). Re-run it to change anything.
-// `start` reads that file; with no file it uses defaults. Precedence: flag > file > default — a flag
-// overrides one value for one run and never persists. Advanced: `--config PATH` (a different file, for
+// `start` reads that file; with no file it uses defaults. Precedence: flag > file > env (HANDMUX_*) >
+// default — a flag overrides one value for one run and never persists. Advanced: `--config PATH` (a different file, for
 // dev / multiple configs), `handmux config` (show what's in effect and where each value came from).
 //
 // Tunnels: `none` (LAN only, nothing exposed) · `cloudflare` (instant random https URL) ·
@@ -26,6 +26,7 @@ import { renderCompactQr } from '../src/cli/qr.js';
 import { supervise, bareUrl, publicUrlWithToken } from '../src/cli/supervisor.js';
 import { resolveCloudflared } from '../src/cli/cloudflared.js';
 import { resolveTunlite, checkSshAuth } from '../src/cli/tunlite.js';
+import { resolveNatapp, resolveCpolar } from '../src/cli/tunnelClients.js';
 import { installService, uninstallService } from '../src/cli/service.js';
 import { checkTmux, MIN_TMUX, tmuxInstallHint } from '../src/cli/tmuxVersion.js';
 import { readState, clearState, isAlive, pocketHome, logPath, configPath, claudeStatePath } from '../src/cli/state.js';
@@ -115,6 +116,20 @@ async function preflightSsh(cfg) {
   throw new Error(t('ssh.notSetup', { bin: cfg.tunliteBin, host: cfg.sshHost }));
 }
 
+// natapp/cpolar preflight: resolve the client binary (cpolar auto-downloads; natapp must be pre-installed),
+// and for cpolar seed the authtoken into its own config so the detached `cpolar http` authenticates. Throws
+// a friendly message the caller prints.
+async function preflightNgrok(cfg) {
+  if (cfg.tunnel === 'natapp') {
+    cfg.natappBin = resolveNatapp(HOME);
+  } else {
+    cfg.cpolarBin = await resolveCpolar(HOME);
+    if (spawnSync(cfg.cpolarBin, ['authtoken', cfg.authtoken], { stdio: 'ignore' }).status !== 0) {
+      throw new Error(t('client.cpolarAuthFail'));
+    }
+  }
+}
+
 async function main() {
   switch (command) {
     case 'start': return start();
@@ -228,6 +243,10 @@ async function start() {
     try { await preflightSsh(cfg); }
     catch (e) { console.error(t('err.generic', { msg: e.message })); process.exit(1); }
   }
+  if (cfg.tunnel === 'natapp' || cfg.tunnel === 'cpolar') {
+    try { await preflightNgrok(cfg); }
+    catch (e) { console.error(t('err.generic', { msg: e.message })); process.exit(1); }
+  }
 
   if (cfg.foreground) {
     supervise(cfg, { home: HOME });
@@ -305,6 +324,10 @@ async function serviceInstall() {
       console.error(t('err.generic', { msg: t('ssh.notSetup', { bin: cfg.tunliteBin, host: cfg.sshHost }) })); process.exit(1);
     }
   }
+  if (cfg.tunnel === 'natapp' || cfg.tunnel === 'cpolar') {
+    try { await preflightNgrok(cfg); }
+    catch (e) { console.error(t('err.generic', { msg: e.message })); process.exit(1); }
+  }
   const payload = Buffer.from(JSON.stringify(cfg)).toString('base64');
   const args = [process.execPath, SELF, '__supervise', '--payload', payload];
   try { installService(args, { home: HOME }); }
@@ -314,8 +337,14 @@ async function serviceInstall() {
 
 async function setupCmd() {
   const target = flags.config ? path.resolve(flags.config) : configPath(HOME);
-  const cfg = await runSetup({ home: HOME, target });
-  if (!cfg) { process.exit(2); }
+  // Is an instance already up? Then the run-action reads "Save & restart" and applying means a real restart
+  // (a running supervisor won't pick up the new config on its own). Captured before the interactive setup so
+  // the label and the action agree; stop() below is a safe no-op if it died meanwhile.
+  const st = readState(HOME);
+  const running = !!(st && isAlive(st.supervisorPid));
+  const res = await runSetup({ home: HOME, target, running });
+  if (!res) { process.exit(2); }
+  const { cfg, start: doStart } = res;   // hub's "save & start/restart" carries the intent — no separate confirm
   // Offer to enable the inbox hooks when an agent is present but not yet wired (Claude 'absent', or Codex
   // 'absent'). installAgentHooks() then wires every present agent (idempotent for any already installed).
   const offerHooks = hooksStatus(HOME) === 'absent' || codexHooksStatus(HOME) === 'absent';
@@ -323,8 +352,12 @@ async function setupCmd() {
     installAgentHooks();
   }
   await maybeOfferStatusLine();
-  if (await confirm(t('setup.confirmStart'))) { Object.assign(flags, cfg); return start(); }
-  console.log(t('setup.later'));
+  if (doStart) {
+    Object.assign(flags, cfg);
+    if (running) { stop(); await sleep(600); }   // restart into the new config
+    return start();
+  }
+  console.log(t(running ? 'setup.laterRestart' : 'setup.later'));
 }
 
 // Offer to enable the Claude statusLine usage capturer — it feeds the phone Usage page's 5h/weekly bars
@@ -488,6 +521,7 @@ function openCmd() {
 }
 
 function help() {
+  if (process.argv[3] === 'flags') { console.log(t('help.flags')); return; }
   console.log(t('help.body'));
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handmux",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "A mobile vibe-coding cockpit — built on tmux: drive your live session, Claude Code / Codex — anything a terminal can run — from your phone.",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -13,7 +13,14 @@
   "bugs": {
     "url": "https://github.com/handmux/handmux/issues"
   },
-  "keywords": ["tmux", "mobile", "terminal", "claude-code", "remote", "pwa"],
+  "keywords": [
+    "tmux",
+    "mobile",
+    "terminal",
+    "claude-code",
+    "remote",
+    "pwa"
+  ],
   "engines": {
     "node": ">=18"
   },
@@ -36,6 +43,7 @@
     "test": "vitest run"
   },
   "dependencies": {
+    "@clack/prompts": "^1.7.0",
     "busboy": "^1.6.0",
     "express": "^4.19.2",
     "tunlite": "^0.10.0",
@@ -49,6 +57,7 @@
     "vitest": "^2.0.0"
   },
   "whatsNew": [
+    {"version":"0.11.0","date":"2026-07-08","zh":"国内可用隧道 natapp/cpolar · 配置向导重做","en":"China-usable tunnels · setup redesigned"},
     {"version":"0.10.0","date":"2026-07-06","zh":"升级前预览新功能 · 电脑 handmux open 接管","en":"Preview an update before installing · handmux open"},
     {"version":"0.9.1","date":"2026-07-06","zh":"「添加到主屏」引导","en":"\"Add to Home Screen\" coach"},
     {"version":"0.9.0","date":"2026-07-05","zh":"聊天输入框多行重做","en":"Multi-line chat composer redone"},