handmux 0.9.1 → 0.11.0

package/src/cli/i18n/zh.js

@@ -20,6 +20,8 @@ export default {
   'tmux.explain2': '  所以这台机器上必须先装好 tmux。',
   'tmux.install': '  安装:  {hint}',
   'tmux.thenStart': '  然后再运行 `handmux start`。',
+  'open.usage': '用法: handmux open <会话名>   接入该 tmux 会话(不存在则新建)',
+  'open.insideTmux': '你已经在 tmux 里了——切换会话请用 tmux 自己的方式(如 `tmux switch-client -t <会话名>`),不要嵌套。',
   'tmux.tooOld': '⚠ tmux {raw} 低于测试过的最低版本 {min};终端渲染可能有偏差',
 
   // start —— 已在运行
@@ -54,6 +56,12 @@ export default {
   // cloudflared 自动下载
   'cf.downloading': '  ↓ 正在下载 cloudflared({file})…',
 
+  // natapp / cpolar 客户端二进制
+  'client.downloading': '  ↓ 正在下载 {name}({file})…',
+  'client.cpolarManual': '✗ cpolar 不可用 —— 到 https://www.cpolar.com/download 下载,解压出二进制放进 ~/.handmux/bin/ 后重试。',
+  'client.cpolarAuthFail': '✗ cpolar 拒绝了该 authtoken —— 到 https://dashboard.cpolar.com 核对一下。',
+  'client.natappManual': '✗ 未找到 natapp —— 到 https://natapp.cn 下载(需先登录,非公开下载),把 `natapp` 二进制放到 {dir}(或 PATH 上任意位置)后重试。',
+
   // 访问信息块(printAccess)
   'access.noState': '  (无状态)',
   'access.error': '  ✗ {msg}',
@@ -97,8 +105,9 @@ export default {
   // setup 向导
   'setup.confirmStart': '现在启动 handmux 吗?',
   'setup.later': "准备好后运行 'handmux start' 即可。",
+  'setup.laterRestart': "已在运行 —— 运行 'handmux restart' 让改动生效。",
   'setup.needTty': 'handmux setup 需要一个交互式终端',
-  'setup.langQ': 'Language / 语言',
+  'setup.langQ': '命令行语言(handmux 终端输出)/ Command-line language',
   'setup.lang1': '  1) English',
   'setup.lang2': '  2) 中文',
   'setup.askName': '应用名称(显示在浏览器标签 / 主屏图标;留空 = 默认)',
@@ -107,21 +116,97 @@ export default {
   'setup.tunnel2': '  2) cloudflare        —— 即时、随机的临时 https 地址',
   'setup.tunnel3': '  3) cloudflare-named  —— 用你自己的域名,稳定 HTTPS(最省心)',
   'setup.tunnel4': '  4) ssh (tunlite)     —— 你自己的服务器 / 边缘',
-  'setup.choose': '选择 1-4',
+  'setup.tunnel5': '  5) natapp            —— 国内可用的隧道(需要 natapp authtoken)',
+  'setup.tunnel6': '  6) cpolar            —— 国内可用的隧道(自动安装;需要 cpolar authtoken)',
+  'setup.choose': '选择 1-6',
   'setup.invalid': '无效选择',
   'setup.askPort': '服务端口',
   'setup.askHostname': '公网域名(例如 handmux.example.com)',
   'setup.askTunnelName': '隧道名称',
   'setup.askSshHost': 'ssh 主机(user@host[:port])',
   'setup.askRemotePort': 'ssh 主机上的远程端口',
-  'setup.askPublicUrl': '公网地址(留空 = http://host:remotePort)',
+  'setup.askPublicUrl': '公网地址,http(s):// 按情况填(留空 = http://host:remotePort)',
+  'setup.natappGuide': '去哪拿 authtoken:到 https://natapp.cn 免费注册 → 新建一条隧道 → 复制它的 authtoken(免费额度够上手)。',
+  'setup.cpolarGuide': '去哪拿 authtoken:到 https://cpolar.com 免费注册 → 打开后台 → 验证/Verify → 复制你的 authtoken。',
+  'setup.askAuthtoken': 'authtoken',
+  'setup.askFixed': '用固定域名吗?(否 = 免费临时域名,每次重启都会变)',
+  'setup.askNatappDomain': '你在 natapp 后台为该 authtoken 绑定的固定域名(例如 myapp.natapp1.cc)',
+  'setup.askCpolarDomain': '你保留的二级域名或绑定的自有域名(例如 myapp.cpolar.top)',
+  'setup.askCpolarRegion': 'cpolar 区域(cn = 中国大陆,国内更快;留空 = cpolar 默认)',
+  'setup.natappReady': '✓ natapp 客户端就绪',
+  'setup.cpolarReady': '✓ cpolar 客户端就绪',
+  // setup 中枢(菜单模型)
+  'setup.welcome': 'handmux 开源、自身不设中转——手机连的始终是你自己的电脑,更私密安全;同一 Wi-Fi 下就是纯直连、开箱即用(选「直连」即可)。想在外网也能连,下面几个是内置帮你打通的方式,用你自己的免费账号即可。不确定就在高亮项上按 Enter,之后随时能改。',
+  'setup.hubTitle': '要改什么吗?(或直接保存并启动)',
+  'setup.secConnection': '连接',
+  'setup.secName': '名称',
+  'setup.secPort': '端口',
+  'setup.secLanguage': '命令行语言 / CLI language',
+  'setup.secPush': '推送',
+  'setup.secVoice': '语音',
+  'setup.default': '(默认)',
+  'setup.on': '开',
+  'setup.off': '关',
+  'setup.yes': '是',
+  'setup.no': '否',
+  'setup.escBack': '(Esc 返回)',
+  'setup.actStart': '保存并启动',
+  'setup.actRestart': '保存并重启(立即生效)',
+  'setup.actSave': '保存',
+  'setup.actExit': '退出(丢弃改动)',
+  'setup.exited': '已取消 —— 未保存任何改动',
+  'setup.tunnelNone': '直连',
+  'setup.hintNone': '不经隧道,直连本机 —— 同一 Wi-Fi 或本机有公网 IP 均可;最简单',
+  'setup.hintCf': '在外面也能访问、免注册(临时地址;国内可能不稳)',
+  'setup.hintCfNamed': '你自己的域名,稳定 HTTPS(最省心)',
+  'setup.hintSsh': '你已经有一台服务器可以中转',
+  'setup.hintNatapp': '在外面也能访问、国内稳(需免费 natapp 账号)',
+  'setup.hintCpolar': '在外面也能访问、国内稳、自动安装(需免费 cpolar 账号)',
+  'setup.domainQ': '临时还是固定域名?',
+  'setup.domainTemp': '免费临时域名',
+  'setup.domainTempHint': '每次重启会变',
+  'setup.domainFixed': '固定/保留域名',
+  'setup.valPort': '端口需为 1–65535 的整数',
+  'setup.valRequired': '{label} 不能为空',
+  'setup.valHost': '请输入有效域名(如 myapp.example.com)',
+  'setup.valContact': '请填 mailto:you@example.com 或 https://你的站点(要真实域名 —— 苹果会拒收假域名)',
+  'setup.sumTemp': '临时',
+  'setup.sumFixed': '固定',
+  'setup.sumNoRelay': '无中转',
+  // 连接迷你中枢(各隧道字段行)
+  'setup.connTunnel': '隧道',
+  'setup.connMode': '模式',
+  'setup.connHostname': '域名',
+  'setup.connTunnelName': '隧道名',
+  'setup.connSshHost': 'SSH 主机',
+  'setup.connRemotePort': '远程端口',
+  'setup.connPublicUrl': '公网地址',
+  'setup.connJump': '跳板机',
+  'setup.connDomain': '域名',
+  'setup.connRegion': '区域',
+  'setup.connNone': '(未设置)',
+  'setup.connAuto': '(自动)',
+  'setup.askSshJump': 'ssh 跳板机(user@host,留空=无)',
+  'setup.cfModeQ': 'cloudflare 地址',
+  'setup.cfTemp': '临时地址(免登录)',
+  'setup.cfTempHint': '即时随机 https,重启会变',
+  'setup.cfNamed': '命名隧道(你的域名)',
+  'setup.cfNamedHint': '稳定 HTTPS,需登录 Cloudflare',
   'setup.wrote': '✓ 已写入 {path}',
   'setup.pushKeep': '保留已配置的推送通知吗?',
-  'setup.pushSetup': '现在配置推送通知吗?(会生成 VAPID 密钥)',
-  'setup.pushContact': '联系方式(mailto: 或 https 地址,供推送服务使用)',
-  'setup.pushGenerated': '✓ 已生成 VAPID 密钥对',
+  'setup.pushSetup': '开启手机通知吗?(编程 agent 干完活时提醒你)',
+  'setup.pushAbout': 'handmux 会为你自动生成一把私有签名密钥,存在 ~/.handmux/config.json,始终不出本机。下面的联系方式只是给推送服务留的联系地址,别人看不到。',
+  'setup.pushContact': '给推送服务留的联系方式 —— mailto: 或 https://(用默认即可;保留 mailto: 前缀)',
+  'setup.pushGenerated': '✓ 已生成签名密钥对(存在本机配置里)',
+  'setup.pushContactLabel': '联系人',
+  'setup.pushRegen': '重新生成密钥',
+  'setup.pushRegenHint': '会重置所有手机的订阅',
+  'setup.pushRegenConfirm': '重新生成密钥?已订阅的每台手机都会收不到通知,直到重新打开网页 App 再订阅一次。只有密钥泄露时才需要这么做。',
+  'setup.pushRegenerated': '✓ 已重新生成密钥 —— 手机需重新订阅',
+  'setup.pushOff': '关闭推送',
+  'setup.voiceOff': '关闭语音',
   'setup.voiceKeep': '保留已配置的语音输入吗?',
-  'setup.voiceSetup': '现在配置语音输入吗?(需要讯飞/xfyun 密钥)',
+  'setup.voiceSetup': '开启语音输入吗?(对着手机说话转文字;需讯飞账号)',
   'setup.voiceAppId': 'xfyun appId',
   'setup.voiceApiKey': 'xfyun apiKey',
   'setup.voiceApiSecret': 'xfyun apiSecret',
@@ -148,38 +233,51 @@ export default {
   'help.body': `handmux —— 从手机驱动你的 tmux
 
   handmux start            直接运行(默认仅局域网;无需配置)
+  handmux open <会话名>     接入 tmux 会话,不存在则新建——手机上建的也能一键接管
   handmux setup            配置隧道 / 名称 / 通知(写入配置;重跑即可修改)
   handmux stop | restart | status
   handmux logs [--follow] [--lines N]
   handmux update           升级到最新发布版本(npm i -g handmux@latest)
 
+第一次用?跑 'handmux setup' —— 它会带你配好外网访问 + 手机通知。
 模型:'start' 运行 · 'setup' 配置(写入 ~/.handmux/config.json)· 重跑 setup 即可修改。
-flag 仅本次覆盖某一项、绝不持久化(优先级 flag > file > default)。
-
-进阶(脚本 / 多套配置):
-  handmux config                        显示生效的配置 + 每一项来自哪里
-  handmux hooks install|uninstall         启用/停用 Claude Code 通知(收件箱)
-  handmux service install [start-flags]   开机自启(launchd/systemd)
-  handmux service uninstall               移除自启项
-  --config PATH             使用指定配置文件,替代 ~/.handmux/config.json(开发 / 多套配置)
-  --lang en|zh              CLI 语言(默认:根据你的 shell locale 自动检测)
-  --version, -v            打印 handmux 版本
-
-start flag(仅本次覆盖 —— 要持久化请用 'handmux setup'):
-  --tunnel none|cloudflare|cloudflare-named|ssh   暴露方式(默认:none)
-  --ssh-host user@host[:port]   ssh 隧道目标(tunlite)
-  --remote-port N               绑定在 ssh 主机上的端口(默认:--port)
-  --public-url URL              对外公布的公网地址(任意隧道均可,包括自建的 none;
-                                ssh 默认 http://host:remotePort)
-  --ssh-jump u@h[,…]            ssh 的可选跳板机
-  --cf-hostname H               cloudflare-named 的公网域名
-  --cf-tunnel-name N            cloudflare-named 的隧道名(默认:handmux)
-  --port N                  服务端口(默认:19999)
-  --host H                  绑定地址(默认:0.0.0.0)
-  --token S                 鉴权令牌(默认:自动生成)
-  --name "My Box"           浏览器标签 + 主屏图标里的应用名
-  --preview-domain D        启用动态预览(需要通配子域名)
-  --foreground, -f          前台运行(不后台化)
-  --no-qr                   不渲染二维码
+
+更多:
+  handmux config                          显示生效的配置 + 每一项来自哪里
+  handmux hooks install|uninstall         启用/停用 agent 通知(收件箱)
+  handmux service install|uninstall       开机自启(launchd/systemd)
+  handmux help flags                      一次性 flag + 环境变量(脚本 / 无头 / Docker)
+  --config PATH · --lang en|zh · --version, -v
+`,
+  'help.flags': `handmux flag —— 一次性覆盖 & 无头配置
+
+优先级:flag > 文件(~/.handmux/config.json)> 环境变量(HANDMUX_*)> 默认值。
+flag 仅本次覆盖某一项、绝不持久化 —— 要持久化请用 'handmux setup'。
+环境变量是无头场景(Docker / systemd / CI)的配置面,会跨多次运行生效。
+
+start flag(括号内为对应环境变量):
+  --tunnel none|cloudflare|cloudflare-named|ssh|natapp|cpolar   暴露方式(默认:none)
+  --port N                      服务端口(HANDMUX_PORT,默认:19999)
+  --host H                      绑定地址(HANDMUX_HOST,默认:0.0.0.0)
+  --token S                     鉴权令牌(HANDMUX_TOKEN,默认:每次启动自动生成)
+  --name "My Box"               浏览器标签 + 主屏图标里的应用名(HANDMUX_APP_NAME)
+  --public-url URL              对外公布的公网地址(HANDMUX_PUBLIC_URL;任意隧道均可,包括自建的 none;
+                                ssh 默认 http://host:remotePort;natapp/cpolar 填你的固定/保留域名 ——
+                                留空则用临时域名)
+  --ssh-host user@host[:port]   ssh 隧道目标(HANDMUX_SSH_HOST)
+  --remote-port N               绑定在 ssh 主机上的端口(HANDMUX_REMOTE_PORT,默认:--port)
+  --ssh-jump u@h[,…]            ssh 的可选跳板机(HANDMUX_SSH_JUMP)
+  --cf-hostname H               cloudflare-named 的公网域名(HANDMUX_CF_HOSTNAME)
+  --cf-tunnel-name N            cloudflare-named 的隧道名(HANDMUX_CF_TUNNEL_NAME,默认:handmux)
+  --authtoken T                 natapp / cpolar 的 authtoken(HANDMUX_AUTHTOKEN)
+  --cpolar-region R             cpolar 边缘区域,如 cn(HANDMUX_CPOLAR_REGION)
+  --preview-domain D            启用动态预览,需要通配子域名(HANDMUX_PREVIEW_DOMAIN)
+  --foreground, -f              前台运行(不后台化)
+  --no-qr                       不渲染二维码
+
+很少用到(环境变量或 flag):--static-dir / --upload-exts / --preview-ttl
+  (HANDMUX_STATIC_DIR / HANDMUX_UPLOAD_EXTS / HANDMUX_PREVIEW_TTL)
+
+'handmux service install' 也接受上面这些 start flag —— 它们会被烘进自启项。
 `,
 };

package/src/cli/natappUrl.js

@@ -0,0 +1,11 @@
+// natapp is an ngrok-derived domestic tunnel. On the FREE tier it hands out a random http(s)://<sub>.natappfree.cc
+// each run, printed in natapp's `-log=stdout` output — scrape it exactly like the cloudflare quick tunnel.
+// A reserved/paid domain (e.g. *.natapp1.cc or your own) is bound to the authtoken server-side and known up
+// front (→ publicUrl, gated on that host appearing), so scraping is only ever for the free zone. Pure →
+// unit-tested against captured log lines.
+const RE = /https?:\/\/[a-z0-9][a-z0-9-]*\.natappfree\.cc/;
+
+export function extractNatappUrl(text) {
+  const m = RE.exec(String(text || ''));
+  return m ? m[0] : null;
+}

package/src/cli/options.js

@@ -3,7 +3,7 @@
 // (generated when unset) so a public tunnel can never come up token-less.
 import crypto from 'node:crypto';
 
-export const TUNNELS = ['none', 'cloudflare', 'cloudflare-named', 'ssh'];
+export const TUNNELS = ['none', 'cloudflare', 'cloudflare-named', 'ssh', 'natapp', 'cpolar'];
 
 const camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 
@@ -69,6 +69,7 @@ export function resolveConfig(flags = {}, fileCfg = {}, env = process.env, gen =
     // tunnel-specific (null unless the relevant tunnel is selected)
     sshHost: null, remotePort: null, sshJump: null,
     cfHostname: null, cfTunnelName: null,
+    authtoken: null, cpolarRegion: null,
   };
 
   if (tunnel === 'ssh') {
@@ -88,6 +89,19 @@ export function resolveConfig(flags = {}, fileCfg = {}, env = process.env, gen =
     cfg.publicUrl = cfg.publicUrl || `https://${cfg.cfHostname}`;
   }
 
+  // natapp / cpolar: one shared credential (--authtoken), and named/fixed mode is just --public-url (the
+  // reserved domain) — no separate concept. A bare host is normalised to https:// so the user can paste the
+  // domain the provider gave them. cpolar also takes an optional edge --cpolar-region (cn = mainland China).
+  if (tunnel === 'natapp' || tunnel === 'cpolar') {
+    cfg.authtoken = pick('authtoken', env.HANDMUX_AUTHTOKEN) || null;
+    if (!cfg.authtoken) {
+      const where = tunnel === 'natapp' ? 'natapp.cn' : 'cpolar.com';
+      throw new Error(`${tunnel} needs --authtoken <token> (or HANDMUX_AUTHTOKEN) — get it from ${where} after logging in`);
+    }
+    if (cfg.publicUrl && !/^https?:\/\//i.test(cfg.publicUrl)) cfg.publicUrl = `https://${cfg.publicUrl}`;
+    if (tunnel === 'cpolar') cfg.cpolarRegion = pick('cpolarRegion', env.HANDMUX_CPOLAR_REGION) || null;
+  }
+
   return cfg;
 }
 
@@ -164,6 +178,14 @@ export function explainConfig(flags = {}, fileCfg = {}, cfgPath = null, env = pr
     add('cfHostname', trace(flags, fileCfg, env, cfgPath, 'cfHostname', 'HANDMUX_CF_HOSTNAME', null));
     add('cfTunnelName', trace(flags, fileCfg, env, cfgPath, 'cfTunnelName', 'HANDMUX_CF_TUNNEL_NAME', 'handmux'));
   }
+  if (t === 'natapp' || t === 'cpolar') {
+    const at = trace(flags, fileCfg, env, cfgPath, 'authtoken', 'HANDMUX_AUTHTOKEN', null);
+    add('authtoken', at, at.value == null ? '(required — from the provider dashboard)' : mask(at.value));
+  }
+  if (t === 'cpolar') {
+    const rg = trace(flags, fileCfg, env, cfgPath, 'cpolarRegion', 'HANDMUX_CPOLAR_REGION', null);
+    add('cpolarRegion', rg, rg.value == null ? '(cpolar default)' : String(rg.value));
+  }
 
   // Integrations live only in the file (secrets); show presence, never the keys.
   rows.push({ key: 'push (vapid)', origin: fileCfg.vapid ? (cfgPath || 'file') : 'default', display: fileCfg.vapid ? 'on' : 'off' });

package/src/cli/prompt.js

@@ -0,0 +1,17 @@
+// The ONLY module that touches @clack/prompts — the interactive shell for `handmux setup`. Everything else
+// imports from here, so the prompt library stays swappable behind one seam and the wizard's pure logic
+// (configFromAnswers / validators / …) never depends on it.
+import { select, text, password, confirm, note, intro, outro, cancel, isCancel } from '@clack/prompts';
+
+export { select, text, password, confirm, note, intro, outro, cancel };
+
+// Thrown by ask() when the user cancels a prompt (Esc / Ctrl-C), so the wizard catches ONCE at the top
+// instead of checking isCancel after every call.
+export const CANCELLED = Symbol('setup-cancelled');
+
+// Await a clack prompt, converting a cancel into a throw. Usage: `const v = await ask(select({…}))`.
+export async function ask(promptResult) {
+  const v = await promptResult;
+  if (isCancel(v)) throw CANCELLED;
+  return v;
+}