handmux 0.9.1 → 0.11.0

package/README.md

@@ -16,7 +16,7 @@ handmux is more than a terminal on your phone. It puts the *same* live **tmux**
   <em>Real phone browser, real panes — say what you need and Claude Code writes it, then tap a filename to preview (left); a push pings you when needed, and you review the git repo &amp; each agent's usage (right).</em>
 </p>
 
-**[📖 Docs](https://handmux.com/docs.html)** · **[📝 Changelog](CHANGELOG.md)** · **[📦 npm](https://www.npmjs.com/package/handmux)**
+**[📖 Docs](https://handmux.com/docs)** · **[📝 Changelog](CHANGELOG.md)** · **[📦 npm](https://www.npmjs.com/package/handmux)**
 
 ## Quick start · about a minute
 
@@ -35,7 +35,7 @@ Want to reach it from **anywhere**? Add one flag for a free public HTTPS link:
 handmux start --tunnel cloudflare   # instant public URL (cloudflared auto-installed)
 ```
 
-> Tunnel types, self-hosting, Windows/WSL2, and the full command & flag reference → see the **[docs](https://handmux.com/docs.html)**.
+> Tunnel types, self-hosting, Windows/WSL2, and the full command & flag reference → see the **[docs](https://handmux.com/docs)**.
 
 ## Why handmux
 
@@ -59,19 +59,19 @@ 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.html)**.
+> Tunnel config, server-side reverse proxy, autostart, voice/push credentials, and port previews → see the **[docs](https://handmux.com/docs)**.
 
 ## Requirements
 
-Your computer needs **Node ≥ 18** and **tmux ≥ 3.0**; the phone just needs a browser. On **Windows**, run it inside **WSL2** (a real Linux kernel + real tmux) — see the [docs](https://handmux.com/docs.html#windows).
+Your computer needs **Node ≥ 18** and **tmux ≥ 3.0**; the phone just needs a browser. On **Windows**, run it inside **WSL2** (a real Linux kernel + real tmux) — see the [docs](https://handmux.com/docs#windows).
 
 ## More
 
-**[📖 Docs](https://handmux.com/docs.html)** · **[📝 Changelog](CHANGELOG.md)** · **[🔒 Security](SECURITY.md)** · License **AGPL-3.0**
+**[📖 Docs](https://handmux.com/docs)** · **[📝 Changelog](CHANGELOG.md)** · **[🔒 Security](SECURITY.md)** · License **AGPL-3.0**
 
 Found a security issue? Please report it privately (see [SECURITY.md](SECURITY.md)), not via a public issue.

package/README.zh-CN.md

@@ -16,7 +16,7 @@ handmux 不只是把终端搬上手机。它把你电脑上**正跑着的 tmux
   <em>真实手机浏览器、真实 pane——左:说出需求,Claude Code 直接写好,点文件名即可预览;右:需要你时推送提醒,查看 git 仓库与各 agent 用量。</em>
 </p>
 
-**[📖 文档](https://handmux.com/docs.html)** · **[📝 更新日志](CHANGELOG.md)** · **[📦 npm](https://www.npmjs.com/package/handmux)**
+**[📖 文档](https://handmux.com/docs)** · **[📝 更新日志](CHANGELOG.md)** · **[📦 npm](https://www.npmjs.com/package/handmux)**
 
 ## 快速上手 · 约一分钟
 
@@ -35,7 +35,7 @@ handmux start        # 跑起来 —— 仅本机 / 同 wifi,不对外暴露
 handmux start --tunnel cloudflare   # 即时公网地址(自动装 cloudflared)
 ```
 
-> 隧道类型、自建、Windows/WSL2、完整命令与参数 → 见 **[文档](https://handmux.com/docs.html)**。
+> 隧道类型、自建、Windows/WSL2、完整命令与参数 → 见 **[文档](https://handmux.com/docs)**。
 
 ## 为什么是 handmux
 
@@ -59,19 +59,19 @@ handmux start --tunnel cloudflare   # 即时公网地址(自动装 cloudflared)
 
 ## 联网:一句话决策
 
-默认只在局域网、什么都不暴露。想从外面连,只问一句:**电脑有没有公网地址?**
+默认不开隧道——手机**直连你自己的电脑**,什么都不暴露、也没有中间人。想从外面连,只问一句:**电脑有没有公网地址?**
 
 - **有**(云主机 / 公网 IP / 已端口转发)—— 不用隧道,直接连,最快也最私密。
-- **没有** —— 开一条隧道:`cloudflare`(零配置秒通,但公共节点在国内常不稳定)· `cloudflare-named`(你的域名,更稳)· `ssh` 自建(接你自己的服务器,**国内网络首选**)。
+- **没有** —— 开一条隧道。每条都跑在**你自己的免费第三方账号**上,handmux 只负责接通、自身不设中转:`cloudflare`(零配置秒通,但公共边缘在国内常不稳)· `cloudflare-named`(你的域名,更稳)· `natapp` / `cpolar`(国内厂商,大陆境内可达)· `ssh` 自建(接你自己的服务器)。
 
-> 隧道配置、服务端反向代理、开机自启、语音 / 推送凭证、端口预览等细节 → 见 **[文档](https://handmux.com/docs.html)**。
+> 隧道配置、服务端反向代理、开机自启、语音 / 推送凭证、端口预览等细节 → 见 **[文档](https://handmux.com/docs)**。
 
 ## 环境要求
 
-电脑需 **Node ≥ 18** 与 **tmux ≥ 3.0**;手机只要浏览器。**Windows** 请装进 **WSL2**(真 Linux 内核 + 真 tmux)——见 [文档](https://handmux.com/docs.html#windows)。
+电脑需 **Node ≥ 18** 与 **tmux ≥ 3.0**;手机只要浏览器。**Windows** 请装进 **WSL2**(真 Linux 内核 + 真 tmux)——见 [文档](https://handmux.com/docs#windows)。
 
 ## 更多
 
-**[📖 文档](https://handmux.com/docs.html)** · **[📝 更新日志](CHANGELOG.md)** · **[🔒 安全](SECURITY.md)** · 许可证 **AGPL-3.0**
+**[📖 文档](https://handmux.com/docs)** · **[📝 更新日志](CHANGELOG.md)** · **[🔒 安全](SECURITY.md)** · 许可证 **AGPL-3.0**
 
 发现安全问题请私下报告(见 [SECURITY.md](SECURITY.md)),别开公开 issue。

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,9 +116,24 @@ 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();
+    case 'open': return openCmd();
     case 'stop': stop(); return;
     case 'restart': { stop(); await sleep(600); return start(); }
     case 'status': return status();
@@ -227,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 });
@@ -304,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 }); }
@@ -313,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';
@@ -322,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
@@ -469,7 +503,25 @@ async function maybeQr(url, st) {
   } catch { /* no qrcode-terminal — URL alone is fine */ }
 }
 
+// `open` is deliberately DECOUPLED from the server lifecycle: it never starts/stops anything. It's the
+// desk-side quick attach — `handmux open foo` attaches session foo (creating it if missing), including
+// sessions that were created from the phone. Inside tmux it refuses (don't nest tmux in tmux).
+function openCmd() {
+  const name = process.argv[3];
+  if (!name || name.startsWith('-')) { console.error(t('open.usage')); process.exit(2); }
+  if (process.env.TMUX) { console.error(t('open.insideTmux')); process.exit(1); }
+  const tmux = checkTmux();
+  if (!tmux.present) {
+    console.error(t('tmux.notFound'));
+    console.error(t('tmux.install', { hint: tmuxInstallHint() }));
+    process.exit(1);
+  }
+  const r = spawnSync('tmux', ['new-session', '-A', '-s', name], { stdio: 'inherit' });
+  process.exit(r.status ?? 0);
+}
+
 function help() {
+  if (process.argv[3] === 'flags') { console.log(t('help.flags')); return; }
   console.log(t('help.body'));
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "handmux",
-  "version": "0.9.1",
-  "description": "A mobile vibe-coding cockpit — built on tmux: drive your live session, Claude Code & Codex from your phone.",
+  "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",
   "author": "yuanyuanzijin",
@@ -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",
@@ -47,5 +55,15 @@
   "devDependencies": {
     "supertest": "^7.0.0",
     "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"},
+    {"version":"0.8.0","date":"2026-07-05","zh":"快捷栏可自定义 · 上传体验重做","en":"Customizable quick-bars · upload redone"},
+    {"version":"0.7.0","date":"2026-07-03","zh":"新增「用量」页","en":"New \"Usage\" page"},
+    {"version":"0.6.0","date":"2026-07-02","zh":"新增 Codex 支持","en":"Codex support added"},
+    {"version":"0.5.0","date":"2026-06-28","zh":"首个公开版 · 多语言界面","en":"First public release · multi-language UI"}
+  ]
 }