handmux 0.17.7 → 0.18.0

package/src/cli/i18n/zh.js

@@ -12,6 +12,41 @@ export default {
   'config.loaded': '配置:{path}',
   'config.none': '(无 —— 使用 flag + 默认值)',
 
+  // 快捷项编辑器
+  'shortcuts.title': '共享常用快捷项',
+  'shortcuts.command': '命令模式',
+  'shortcuts.chat': '聊天模式',
+  'shortcuts.count': '{n} 项',
+  'shortcuts.save': '保存并退出',
+  'shortcuts.exit': '放弃修改',
+  'shortcuts.addKey': '添加按键',
+  'shortcuts.addText': '添加文字',
+  'shortcuts.back': '返回',
+  'shortcuts.edit': '编辑',
+  'shortcuts.move': '移动位置',
+  'shortcuts.addPositionPrompt': '放到哪里',
+  'shortcuts.movePrompt': '选择新位置（当前：第 {n} 位）',
+  'shortcuts.positionFirst': '最前（第 1 位）',
+  'shortcuts.positionAfter': '放在 {item} 后（第 {n} 位）',
+  'shortcuts.positionLast': '最后（第 {n} 位）',
+  'shortcuts.delete': '删除',
+  'shortcuts.type': '快捷项类型',
+  'shortcuts.key': '按键',
+  'shortcuts.text': '文字',
+  'shortcuts.textEnter': '文字 · 发送后回车',
+  'shortcuts.textOnly': '文字 · 只输入',
+  'shortcuts.textPrompt': '输入文字内容',
+  'shortcuts.badText': '请输入一行非空文字',
+  'shortcuts.enter': '文字后敲 Enter？',
+  'shortcuts.modifier': '修饰键',
+  'shortcuts.noModifier': '无',
+  'shortcuts.base': '基础键',
+  'shortcuts.needTty': 'handmux shortcuts 需要交互式终端。',
+  'shortcuts.wrote': '已保存 {path}',
+  'shortcuts.exited': '未保存修改',
+  'shortcuts.applied': '已立即应用到正在运行的 handmux。',
+  'shortcuts.applyFailed': '配置已保存，但无法立即应用：{msg}。请运行 `handmux restart`。',
+
   // ssh 预检
   'ssh.confirmSetup': '到 {host} 的免密 SSH 还没配置。现在配置吗?',
   'ssh.notSetup': '免密 SSH 未配置 —— 请运行:{bin} setup-key {host}',
@@ -135,6 +170,7 @@ export default {
   'setup.choose': '选择 1-6',
   'setup.invalid': '无效选择',
   'setup.askPort': '服务端口',
+  'setup.askPreviewDomain': '预览域名（不要填 http://、https:// 或 *.）',
   'setup.askHostname': '公网域名(例如 handmux.example.com)',
   'setup.askTunnelName': '隧道名称',
   'setup.askSshHost': 'ssh 主机(user@host[:port])',
@@ -156,6 +192,7 @@ export default {
   'setup.secName': '名称',
   'setup.secPort': '端口',
   'setup.secToken': '令牌',
+  'setup.secPreview': '动态预览',
   'setup.tokenAuto': '自动 · 每次启动新生成',
   'setup.tokenCustom': '自定义令牌…',
   'setup.tokenRandom': '随机生成一个',
@@ -168,6 +205,7 @@ export default {
   'setup.secPush': '推送',
   'setup.secVoice': '语音',
   'setup.default': '(默认)',
+  'setup.previewOff': '未配置',
   'setup.on': '开',
   'setup.off': '关',
   'setup.yes': '是',
@@ -192,6 +230,7 @@ export default {
   'setup.valPort': '端口需为 1–65535 的整数',
   'setup.valRequired': '{label} 不能为空',
   'setup.valHost': '请输入有效域名(如 myapp.example.com)',
+  'setup.valPreviewDomain': '只填域名，如 preview.example.com；不要填 http://、https://、端口或 *.',
   'setup.valContact': '请填 mailto:you@example.com 或 https://你的站点(要真实域名 —— 苹果会拒收假域名)',
   'setup.sumTemp': '临时',
   'setup.sumFixed': '固定',
@@ -247,20 +286,66 @@ export default {
   'setup.sshHelp1': '服务端(一次性):把反向代理指向被转发的 loopback 端口。',
   'setup.sshHelpNginx': '  nginx:  proxy_pass http://127.0.0.1:{port};  (加上 client_max_body_size 60m; proxy_read_timeout 90s;)',
   'setup.sshHelpCaddy': '  caddy:  {url} {  reverse_proxy 127.0.0.1:{port}  }',
-  'setup.previewHelp1': '可选 —— 动态端口预览(在手机上按端口打开一个 dev server):',
-  'setup.previewHelp2': '  在配置里设  "previewDomain": "..."  ,并把通配预览域名路由到网关。',
+  'setup.previewAbout': '用于在手机上按端口打开本机正在运行的开发服务；不配置时，静态目录预览仍可使用。',
+  'setup.previewRoute': '只填预览域名（如 preview.example.com）。handmux 会使用 <项目名>.preview.example.com；请将 *.preview.example.com 路由到 handmux 网关。',
+  'setup.previewHttps': '预览域名本身必须支持 HTTPS；本机开发服务可使用 HTTP 或 HTTPS。',
   'setup.previewTlsCf': '  TLS:Cloudflare 的免费证书只覆盖一级(*.example.com);更深一层(*.preview.example.com)需要 Advanced Certificate Manager。',
   'setup.previewTlsEdge': '  TLS:由你自己的边缘提供通配证书(例如 Let\'s Encrypt 的 *.preview.your.domain)。',
 
+  // 工作区恢复
+  'restore.usage': '用法: handmux restore [--dry-run] [--checkpoint <id>] [--session <name>] | handmux restore --list',
+  'restore.badFlag': '未知的恢复参数 {flag}。',
+  'restore.unexpectedArgument': '未预期的恢复参数: {value}。',
+  'restore.unknownShortFlag': '未知的恢复参数 {flag}。',
+  'restore.flagBoolean': '{flag} 不接受参数值。',
+  'restore.checkpointValue': '--checkpoint 需要一个 id（或 latest）。',
+  'restore.checkpointId': '--checkpoint 必须是有效 id，只能包含字母、数字、点、下划线或连字符。',
+  'restore.sessionValue': '--session 需要一个非空会话名。',
+  'restore.listExclusive': '--list 必须独占使用，不能与 --dry-run、--checkpoint 或 --session 组合。',
+  'restore.listRow': '{id}  {time}  {sessions} 个会话 · {windows} 个窗口 · {panes} 个窗格 · {agents} 个 agent',
+  'restore.listUnavailable': '{id}  不可用: {error}',
+  'restore.listEmpty': '目前还没有已归档的工作区备份。',
+  'restore.selectCheckpoint': '选择要恢复的工作区备份',
+  'restore.selectHint': '{time} · {sessions} 个会话 · {windows} 个窗口 · {panes} 个窗格',
+  'restore.noCheckpoint': '没有可用的历史备份。handmux 正在静默保护当前工作区；请在电脑或 tmux 下次重启后再试。',
+  'restore.selectionCancelled': '没有选择备份。准备好后可再次运行 `{command}`。',
+  'restore.planCheckpoint': '备份: {time}（{id}；{sessions} 个会话，{windows} 个窗口，{panes} 个窗格）',
+  'restore.planCurrent': '当前: {sessions} 个在线会话',
+  'restore.planCreate': '+ {session}',
+  'restore.planRenamed': '+ {session} -> {target}（名称已被占用）',
+  'restore.planAlready': '= {session}（已经恢复）',
+  'restore.planUnavailable': '! {session}（不可用: {reason}）',
+  'restore.reason.linkedWindows': '该备份含有当前版本无法安全恢复的链接窗口',
+  'restore.reason.invalidTopology': '该备份的 tmux 拓扑不完整或无效',
+  'restore.reason.unknown': '不支持的备份拓扑（{reason}）',
+  'restore.manualRecovery': '请改为手动恢复这个会话: {command}',
+  'restore.warning': '警告: {warning}',
+  'restore.sessionWarning': '  {session} 警告: {warning}',
+  'restore.nonDestructive': '不会停止或修改任何现有会话或进程。',
+  'restore.nonDestructivePast': '现有会话没有被修改。',
+  'restore.dryRunHint': '运行 `{command}` 继续。',
+  'restore.resultRestored': '✓ {session}',
+  'restore.resultRenamed': '✓ {session} 已恢复为 {target}',
+  'restore.resultAlready': '= {session}（已经恢复）',
+  'restore.sessionFailed': '备份 {checkpoint}；会话 {session}；阶段 {stage}: {error}',
+  'restore.operationFailed': '备份 {checkpoint}；阶段 {stage}: {error}',
+  'restore.retrySession': '只重试这个会话: {command}',
+  'restore.resultSummary': '已恢复 {restored} 个会话；{already} 个已存在；{failed} 个失败。',
+  'restore.error': '备份 {checkpoint} 在恢复命令阶段失败: {error}',
+  'restore.retry': '修复上面报告的原因后，运行 `{command}` 重试。',
+
   // help
   'help.body': `handmux —— 从手机驱动你的 tmux
 
   handmux start            直接运行(默认仅局域网;无需配置)
   handmux open <会话名>     接入 tmux 会话,不存在则新建——手机上建的也能一键接管
   handmux setup            配置隧道 / 名称 / 通知(写入配置;重跑即可修改)
+  handmux shortcuts        配置命令/聊天模式的共享常用快捷项
   handmux stop | restart | status
   handmux logs [--follow] [--lines N]
   handmux push <标题> <正文>    从脚本推一条通知到手机（--session 会话 · --device 设备key · --tag · --url）
+  handmux restore [--dry-run] [--checkpoint <id>] [--session <name>]
+  handmux restore --list
   handmux update           升级到最新发布版本(npm i -g handmux@latest)
 
 第一次用?跑 'handmux setup' —— 它会带你配好外网访问 + 手机通知。

package/src/cli/options.js

@@ -2,6 +2,7 @@
 // Resolution order is flags > config file > env > built-in default. The token is ALWAYS materialised
 // (generated when unset) so a public tunnel can never come up token-less.
 import crypto from 'node:crypto';
+import { normalizeShortcuts } from '../shortcutConfig.js';
 
 export const TUNNELS = ['none', 'cloudflare', 'cloudflare-named', 'ssh', 'natapp', 'cpolar'];
 
@@ -12,17 +13,33 @@ const camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 export function parseArgs(argv) {
   const [command = 'help', ...rest] = argv;
   const flags = {};
+  const positionals = [];
+  const unknownShortFlags = [];
+  const multiFlags = new Set(['session']);
+  const assign = (key, value) => {
+    if (!multiFlags.has(key) || flags[key] === undefined) { flags[key] = value; return; }
+    flags[key] = Array.isArray(flags[key]) ? [...flags[key], value] : [flags[key], value];
+  };
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === '-f') { flags.foreground = true; continue; }
-    if (!a.startsWith('--')) continue;
+    if (!a.startsWith('--')) {
+      if (a.startsWith('-')) unknownShortFlags.push(a);
+      else positionals.push(a);
+      continue;
+    }
     const key = a.slice(2);
-    if (key.startsWith('no-')) { flags[camel(key.slice(3))] = false; continue; }
+    if (key.startsWith('no-')) { assign(camel(key.slice(3)), false); continue; }
     const next = rest[i + 1];
-    if (next === undefined || next.startsWith('--')) { flags[camel(key)] = true; }
-    else { flags[camel(key)] = next; i++; }
+    if (next === undefined || next.startsWith('--')) { assign(camel(key), true); }
+    else { assign(camel(key), next); i++; }
   }
-  return { command, flags };
+  return {
+    command,
+    flags,
+    ...(positionals.length ? { positionals } : {}),
+    ...(unknownShortFlags.length ? { unknownShortFlags } : {}),
+  };
 }
 
 // ssh 回退公网地址:SSH 不生成 URL,无 --public-url 时用 host:remotePort(去掉 user@ 与 :sshPort)。
@@ -58,6 +75,7 @@ export function resolveConfig(flags = {}, fileCfg = {}, env = process.env, gen =
     previewTtl: pick('previewTtl', env.HANDMUX_PREVIEW_TTL) || null,
     vapid: fileCfg.vapid || null,   // { public, private, subject } — push notifications
     xfyun: fileCfg.xfyun || null,   // { appId, apiKey, apiSecret } — voice input
+    shortcuts: normalizeShortcuts(fileCfg.shortcuts),
     // An explicit public URL is honoured for ANY tunnel mode — including 'none', so someone who runs their
     // own tunnel/reverse-proxy can still have handmux advertise (print + QR) their real domain. The
     // tunnel-specific blocks below only fill a *fallback* when it wasn't given.

package/src/cli/prompt.js

@@ -1,4 +1,4 @@
-// The ONLY module that touches @clack/prompts — the interactive shell for `handmux setup`. Everything else
+// The ONLY module that touches @clack/prompts — shared by the interactive setup and shortcut editors. 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';

package/src/cli/setupModel.js

@@ -39,11 +39,11 @@ export function findTunnelId(listJsonOut, name) {
 
 // The config keys the wizard owns: everything it can set. mergeConfig wipes these from the existing config
 // before re-applying the answers, so switching a tunnel (or clearing an optional field) cleanly drops the
-// old value instead of leaving a stale field behind. Anything NOT here (staticDir, previewDomain…) is
+// old value instead of leaving a stale field behind. Anything NOT here (staticDir, previewTtl…) is
 // preserved untouched. `token` IS owned so the Token row can pin one AND clear it back to auto — but it
 // round-trips through answersFromConfig, so a re-run that never touches the row still writes it back.
 const WIZARD_KEYS = [
-  'lang', 'name', 'port', 'tunnel', 'token',
+  'lang', 'name', 'port', 'tunnel', 'token', 'previewDomain',
   'sshHost', 'remotePort', 'sshJump', 'cfHostname', 'cfTunnelName', 'publicUrl',
   'authtoken', 'cpolarRegion',
   'vapid', 'xfyun',
@@ -58,6 +58,7 @@ export function configFromAnswers(a) {
   if (a.lang) cfg.lang = a.lang;
   if (a.name) cfg.name = a.name;
   if (a.token) cfg.token = a.token;   // blank = don't pin one → the server mints a fresh token each start
+  if (a.previewDomain) cfg.previewDomain = a.previewDomain;
   if (a.tunnel === 'ssh') {
     cfg.sshHost = a.sshHost;
     cfg.remotePort = a.remotePort;
@@ -94,6 +95,7 @@ export function answersFromConfig(cfg = {}) {
     lang: cfg.lang || getLocale(),
     name: cfg.name || '',
     token: cfg.token || '',   // '' = not pinned (auto each start); seeded so an untouched re-run rewrites it
+    previewDomain: cfg.previewDomain || '',
     tunnel: cfg.tunnel || 'none',
     port: Number(cfg.port) || 19999,
   };
@@ -125,6 +127,13 @@ export function validateHost(v) {
   const s = String(v || '').trim().replace(/^https?:\/\//, '').replace(/\/.*$/, '');
   return /^[a-z0-9-]+(\.[a-z0-9-]+)+$/i.test(s) ? undefined : t('setup.valHost');
 }
+// Dynamic previews use `https://<name>.<previewDomain>/`; only the base domain belongs in config. Blank
+// deliberately disables the optional feature, while a URL / wildcard would produce a broken host name.
+export function validatePreviewDomain(v) {
+  const s = String(v || '').trim();
+  if (!s) return undefined;
+  return /^[a-z0-9-]+(\.[a-z0-9-]+)+$/i.test(s) ? undefined : t('setup.valPreviewDomain');
+}
 // VAPID subject: Apple (APNs) rejects a fake/.local domain with BadJwtToken, so require a real-looking
 // mailto:you@host.tld or an https:// URL and reject the known-bad .local. Keeps push from silently
 // failing on iOS. (Can't fully validate "real" client-side — this just catches the obvious footguns.)

package/src/cli/setupWizard.js

@@ -23,13 +23,13 @@ import { intro, outro, note, cancel, select, text, password, confirm, ask, CANCE
 import {
   cfConfigYaml, parseTunnelCreate, findTunnelId,
   mergeConfig, answersFromConfig, summarizeConnection,
-  validatePort, validateHost, validateNonEmpty, validateContact, validateToken,
+  validatePort, validateHost, validatePreviewDomain, validateNonEmpty, validateContact, validateToken,
   TUNNEL_KEYS,
 } from './setupModel.js';
 export {
   cfConfigYaml, parseTunnelCreate, findTunnelId,
   configFromAnswers, mergeConfig, answersFromConfig, summarizeConnection,
-  validatePort, validateHost, validateNonEmpty, validateContact, validateToken,
+  validatePort, validateHost, validatePreviewDomain, validateNonEmpty, validateContact, validateToken,
 } from './setupModel.js';
 
 function readExisting(file) {
@@ -73,6 +73,7 @@ export async function runSetup({ home = homedir(), target = configPath(home), lo
           { value: 'name', label: t('setup.secName'), hint: a.name || t('setup.default') },
           { value: 'port', label: t('setup.secPort'), hint: String(a.port) },
           { value: 'token', label: t('setup.secToken'), hint: a.token ? maskSecret(a.token) : t('setup.tokenAuto') },
+          { value: 'preview', label: t('setup.secPreview'), hint: a.previewDomain || t('setup.previewOff') },
           { value: 'push', label: t('setup.secPush'), hint: a.vapid ? (a.vapid.subject || t('setup.on')) : t('setup.off') },
           { value: 'voice', label: t('setup.secVoice'), hint: a.xfyun ? (a.xfyun.appId || t('setup.on')) : t('setup.off') },
           // A CLI-tool preference (language of handmux's own terminal output), not an app setting — so it
@@ -91,7 +92,6 @@ export async function runSetup({ home = homedir(), target = configPath(home), lo
         fs.writeFileSync(target, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
         outro(t('setup.wrote', { path: target }));
         if (a.tunnel === 'ssh') printSshServerHelp(a, log);
-        if (a.tunnel === 'cloudflare-named' || a.tunnel === 'ssh') printPreviewHelp(a.tunnel, log);
         return { cfg, start: choice === 'start' };
       }
       cursor = choice;   // remember the row so returning from an edit re-highlights it
@@ -101,6 +101,7 @@ export async function runSetup({ home = homedir(), target = configPath(home), lo
         else if (choice === 'name') a.name = await editName(a);
         else if (choice === 'port') a.port = await editPort(a);
         else if (choice === 'token') a.token = await editToken(a);
+        else if (choice === 'preview') a.previewDomain = await editPreviewDomain(a);
         else if (choice === 'language') a.lang = await editLanguage(a);
         else if (choice === 'push') a.vapid = await editPush(a);
         else if (choice === 'voice') a.xfyun = await editVoice(a);
@@ -139,6 +140,21 @@ async function editPort(a) {
   return Number(v);
 }
 
+async function editPreviewDomain(a) {
+  note(t('setup.previewAbout'));
+  note(t('setup.previewRoute'));
+  note(t('setup.previewHttps'));
+  if (a.tunnel === 'cloudflare-named') note(t('setup.previewTlsCf'));
+  else if (a.tunnel === 'ssh') note(t('setup.previewTlsEdge'));
+  const value = await ask(text({
+    message: withBack(t('setup.askPreviewDomain')),
+    placeholder: 'preview.example.com',
+    initialValue: a.previewDomain || '',
+    validate: validatePreviewDomain,
+  }));
+  return String(value || '').trim().toLowerCase();
+}
+
 // The access token — the one secret in the phone's URL. Unset = the server mints a fresh one each start
 // (printed + QR'd), so the link changes every restart; pinning one keeps the same URL. A mini-hub (like
 // push/voice): type your own, generate + pin a strong random one, or reset back to auto. Editing custom
@@ -492,18 +508,3 @@ function printSshServerHelp(a, log) {
   log.log(t('setup.sshHelpCaddy', { url: a.publicUrl || '<your-domain>', port: a.remotePort }));
   log.log('');
 }
-
-// FYI on dynamic port preview: it's optional and NOT wired by this wizard (separate wildcard domain). Print
-// the requirement + a TLS note that fits the chosen tunnel — Cloudflare's free cert only covers one level
-// (so deeper needs ACM), whereas on the ssh/own-edge path the user serves their own wildcard cert. Shown
-// only for wildcard-capable tunnels (a quick tunnel can't do wildcards at all).
-function printPreviewHelp(tunnel, log) {
-  log.log(t('setup.previewHelp1'));
-  log.log(t('setup.previewHelp2'));
-  if (tunnel === 'cloudflare-named') {
-    log.log(t('setup.previewTlsCf'));
-  } else {
-    log.log(t('setup.previewTlsEdge'));
-  }
-  log.log('');
-}

package/src/cli/shortcutEditor.js

@@ -0,0 +1,288 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { normalizeShortcuts, shortcutIdentity } from '../shortcutConfig.js';
+import { t } from './i18n/index.js';
+import * as prompts from './prompt.js';
+import { acquireLifecycleLock, isAlive, readState } from './state.js';
+
+const MODIFIERS = {
+  none: { prefixes: [], labels: [] },
+  ctrl: { prefixes: ['C-'], labels: ['Ctrl'] },
+  shift: { prefixes: ['S-'], labels: ['Shift'] },
+  alt: { prefixes: ['M-'], labels: ['Alt'] },
+  'ctrl-shift': { prefixes: ['C-', 'S-'], labels: ['Ctrl', 'Shift'] },
+  'ctrl-alt': { prefixes: ['C-', 'M-'], labels: ['Ctrl', 'Alt'] },
+};
+const NAMED_BASES = ['Up', 'Down', 'Left', 'Right', 'Tab', 'Enter', 'Escape', 'Space', 'BSpace', 'Home', 'End', 'PageUp', 'PageDown'];
+const CHAR_BASES = [...'abcdefghijklmnopqrstuvwxyz', ...'0123456789'];
+const DISPLAY = { Escape: 'Esc', BSpace: '⌫', PageUp: 'PgUp', PageDown: 'PgDn' };
+
+export function buildShortcutKey(modifier, base) {
+  const mod = MODIFIERS[modifier];
+  if (!mod) throw new Error(`unknown modifier: ${modifier}`);
+  if (!NAMED_BASES.includes(base) && !CHAR_BASES.includes(base)) throw new Error(`unsupported base key: ${base}`);
+  if (CHAR_BASES.includes(base) && modifier === 'none') throw new Error('a character key needs a modifier');
+  if (CHAR_BASES.includes(base) && mod.prefixes.includes('S-')) throw new Error('Shift + character is not a distinct tmux key');
+  const key = base === 'Tab' && modifier === 'shift'
+    ? 'BTab'
+    : `${mod.prefixes.join('')}${CHAR_BASES.includes(base) ? base.toLowerCase() : base}`;
+  const shownBase = CHAR_BASES.includes(base) ? base.toUpperCase() : (DISPLAY[base] || base);
+  return { type: 'key', key, label: [...mod.labels, shownBase].join('+') };
+}
+
+export function moveShortcut(items, index, target) {
+  if (index < 0 || target < 0 || index >= items.length || target >= items.length || target === index) return items;
+  const next = items.slice();
+  const [item] = next.splice(index, 1);
+  next.splice(target, 0, item);
+  return next;
+}
+
+function readExisting(target) {
+  try { return JSON.parse(fs.readFileSync(target, 'utf8')); }
+  catch (error) {
+    if (error.code === 'ENOENT') return {};
+    throw error;
+  }
+}
+
+export function saveShortcutConfig(target, shortcuts) {
+  const existing = readExisting(target);
+  const cfg = { ...existing, shortcuts: normalizeShortcuts(shortcuts) };
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const tmp = `${target}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, target);
+  fs.chmodSync(target, 0o600);
+  return cfg;
+}
+
+const defaultUi = {
+  intro: prompts.intro,
+  outro: prompts.outro,
+  cancel: prompts.cancel,
+  select: prompts.select,
+  text: prompts.text,
+  confirm: prompts.confirm,
+  ask: prompts.ask,
+};
+
+const modeLabel = (mode) => t(mode === 'command' ? 'shortcuts.command' : 'shortcuts.chat');
+const itemLabel = (item) => item.type === 'key' ? item.label : item.text;
+const itemHint = (item) => item.type === 'key'
+  ? t('shortcuts.key')
+  : t(item.enter ? 'shortcuts.textEnter' : 'shortcuts.textOnly');
+const positionOptions = (items, index = null) => {
+  const remaining = index === null ? items : items.filter((_item, i) => i !== index);
+  const count = remaining.length + 1;
+  if (remaining.length === 0) return [{ value: 0, label: t('shortcuts.positionLast', { n: 1 }) }];
+  return Array.from({ length: count }, (_item, target) => {
+    if (target === 0) return { value: target, label: t('shortcuts.positionFirst') };
+    if (target === count - 1) return { value: target, label: t('shortcuts.positionLast', { n: count }) };
+    return {
+      value: target,
+      label: t('shortcuts.positionAfter', { n: target + 1, item: itemLabel(remaining[target - 1]) }),
+    };
+  });
+};
+const validateText = (value) => {
+  if (typeof value !== 'string' || !value.length || /[\r\n\x00-\x1f\x7f]/.test(value)) return t('shortcuts.badText');
+  return undefined;
+};
+
+function parseShortcutKey(item) {
+  if (!item || item.type !== 'key') return { modifier: 'none', base: 'Escape' };
+  if (item.key === 'BTab') return { modifier: 'shift', base: 'Tab' };
+  let key = item.key;
+  const ctrl = key.startsWith('C-'); if (ctrl) key = key.slice(2);
+  const alt = key.startsWith('M-'); if (alt) key = key.slice(2);
+  const shift = key.startsWith('S-'); if (shift) key = key.slice(2);
+  const modifier = ctrl && alt ? 'ctrl-alt' : ctrl && shift ? 'ctrl-shift'
+    : ctrl ? 'ctrl' : alt ? 'alt' : shift ? 'shift' : 'none';
+  return { modifier, base: key };
+}
+
+const modifierOptions = () => Object.entries(MODIFIERS).map(([value, item]) => ({
+  value, label: item.labels.length ? item.labels.join('+') : t('shortcuts.noModifier'),
+}));
+const baseOptions = (modifier) => {
+  const allowChars = modifier !== 'none' && !MODIFIERS[modifier].prefixes.includes('S-');
+  return [...NAMED_BASES, ...(allowChars ? CHAR_BASES : [])].map((value) => ({
+    value, label: DISPLAY[value] || value.toUpperCase?.() || value,
+  }));
+};
+
+async function editItem(mode, seed, ui, forcedType = null) {
+  const type = forcedType || await ui.ask(ui.select({
+    message: t('shortcuts.type'), initialValue: seed?.type || 'text',
+    options: [
+      { value: 'text', label: t('shortcuts.text') },
+      { value: 'key', label: t('shortcuts.key') },
+    ],
+  }));
+  if (type === 'text') {
+    const text = await ui.ask(ui.text({
+      message: t('shortcuts.textPrompt'), initialValue: seed?.type === 'text' ? seed.text : '', validate: validateText,
+    }));
+    const enter = await ui.ask(ui.confirm({
+      message: t('shortcuts.enter'), initialValue: seed?.type === 'text' ? seed.enter : mode === 'chat',
+    }));
+    return { type: 'text', text, enter };
+  }
+  const parsed = parseShortcutKey(seed);
+  const modifier = await ui.ask(ui.select({
+    message: t('shortcuts.modifier'), initialValue: parsed.modifier, options: modifierOptions(),
+  }));
+  const available = baseOptions(modifier);
+  const base = await ui.ask(ui.select({
+    message: t('shortcuts.base'),
+    initialValue: available.some((option) => option.value === parsed.base) ? parsed.base : available[0].value,
+    options: available,
+  }));
+  return buildShortcutKey(modifier, base);
+}
+
+async function editMode(mode, initial, ui) {
+  let items = initial.slice();
+  for (;;) {
+    const choice = await ui.ask(ui.select({
+      message: modeLabel(mode),
+      options: [
+        ...items.map((item, index) => ({ value: `item:${index}`, label: itemLabel(item), hint: itemHint(item) })),
+        { value: 'add-key', label: t('shortcuts.addKey') },
+        { value: 'add-text', label: t('shortcuts.addText') },
+        { value: 'back', label: t('shortcuts.back') },
+      ],
+    }));
+    if (choice === 'back') return items;
+    if (choice === 'add-key' || choice === 'add-text') {
+      const item = await editItem(mode, null, ui, choice === 'add-key' ? 'key' : 'text');
+      if (!items.some((existing) => shortcutIdentity(existing) === shortcutIdentity(item))) {
+        const target = await ui.ask(ui.select({
+          message: t('shortcuts.addPositionPrompt'), options: positionOptions(items),
+        }));
+        items = moveShortcut([...items, item], items.length, target);
+      }
+      continue;
+    }
+    const index = Number(choice.slice(5));
+    const action = await ui.ask(ui.select({
+      message: itemLabel(items[index]),
+      options: [
+        { value: 'edit', label: t('shortcuts.edit') },
+        ...(items.length > 1 ? [{ value: 'move', label: t('shortcuts.move') }] : []),
+        { value: 'delete', label: t('shortcuts.delete') },
+        { value: 'back', label: t('shortcuts.back') },
+      ],
+    }));
+    if (action === 'edit') {
+      const edited = await editItem(mode, items[index], ui);
+      if (!items.some((item, i) => i !== index && shortcutIdentity(item) === shortcutIdentity(edited))) {
+        items = items.map((item, i) => i === index ? edited : item);
+      }
+    } else if (action === 'move') {
+      const target = await ui.ask(ui.select({
+        message: t('shortcuts.movePrompt', { n: index + 1 }), options: positionOptions(items, index),
+      }));
+      items = moveShortcut(items, index, target);
+    } else if (action === 'delete') items = items.filter((_item, i) => i !== index);
+  }
+}
+
+export async function runShortcutEditor({
+  target, log = console, isTTY = process.stdin.isTTY, ui = defaultUi,
+  commit = async (file, shortcuts) => ({ cfg: saveShortcutConfig(file, shortcuts) }),
+} = {}) {
+  if (!isTTY) { log.error(t('shortcuts.needTty')); return { error: 'non-tty' }; }
+  const existing = readExisting(target);
+  let shortcuts = normalizeShortcuts(existing.shortcuts);
+  ui.intro('handmux shortcuts');
+  try {
+    for (;;) {
+      const choice = await ui.ask(ui.select({
+        message: t('shortcuts.title'),
+        options: [
+          { value: 'command', label: modeLabel('command'), hint: t('shortcuts.count', { n: shortcuts.command.length }) },
+          { value: 'chat', label: modeLabel('chat'), hint: t('shortcuts.count', { n: shortcuts.chat.length }) },
+          { value: 'save', label: t('shortcuts.save') },
+          { value: 'exit', label: t('shortcuts.exit') },
+        ],
+      }));
+      if (choice === 'exit') { ui.cancel(t('shortcuts.exited')); return null; }
+      if (choice === 'command' || choice === 'chat') {
+        shortcuts = { ...shortcuts, [choice]: await editMode(choice, shortcuts[choice], ui) };
+        continue;
+      }
+      const result = await commit(target, shortcuts);
+      ui.outro(t('shortcuts.wrote', { path: target }));
+      return result;
+    }
+  } catch (error) {
+    if (error === prompts.CANCELLED) { ui.cancel(t('shortcuts.exited')); return null; }
+    throw error;
+  }
+}
+
+export async function applyShortcutsLive({
+  state, shortcuts, fetchImpl = globalThis.fetch, timeoutMs = 8000,
+}) {
+  if (!state?.localUrl || !state?.token) throw new Error('running server state is incomplete');
+  const base = state.localUrl.replace(/\/$/, '');
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(`${base}/api/config/shortcuts`, {
+      method: 'PUT',
+      redirect: 'manual',
+      signal: controller.signal,
+      headers: { Authorization: `Bearer ${state.token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ shortcuts }),
+    });
+    if (!response.ok) throw new Error(`server returned HTTP ${response.status}`);
+    let acknowledgment;
+    try { acknowledgment = await response.json(); } catch { /* validated below */ }
+    if (acknowledgment?.ok !== true) throw new Error('invalid server response');
+  } catch (error) {
+    if (controller.signal.aborted) throw new Error(`server request timed out after ${timeoutMs}ms`);
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Keep the durable write and the runtime replacement in one short cross-process critical section.
+// Otherwise two editors can interleave their save/PUT calls and leave disk and memory disagreeing.
+export async function commitShortcuts({
+  home, target, shortcuts,
+  acquireLock = acquireLifecycleLock,
+  readStateImpl = readState,
+  isAliveImpl = isAlive,
+  saveImpl = saveShortcutConfig,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = 8000,
+}) {
+  const release = acquireLock(home);
+  try {
+    const cfg = saveImpl(target, shortcuts);
+    const state = readStateImpl(home);
+    if (!state || !isAliveImpl(state.supervisorPid)) return { cfg, running: false, applied: false };
+    try {
+      await applyShortcutsLive({ state, shortcuts: cfg.shortcuts, fetchImpl, timeoutMs });
+      return { cfg, running: true, applied: true };
+    } catch (error) {
+      return { cfg, running: true, applied: false, error };
+    }
+  } finally {
+    release();
+  }
+}
+
+export function reportShortcutCommit(result, output = console) {
+  if (!result.running) return 0;
+  if (result.applied) {
+    output.log(t('shortcuts.applied'));
+    return 0;
+  }
+  output.error(t('shortcuts.applyFailed', { msg: result.error?.message || 'unknown error' }));
+  return 1;
+}

package/src/cli/supervisor.js

@@ -95,6 +95,7 @@ export function supervise(cfg, { home, log = console } = {}) {
     if (cfg.staticDir) env.HANDMUX_STATIC_DIR = cfg.staticDir;
     if (cfg.uploadExts) env.HANDMUX_UPLOAD_EXTS = cfg.uploadExts;
     if (cfg.previewTtl) env.HANDMUX_PREVIEW_TTL = String(cfg.previewTtl);
+    env.HANDMUX_SHORTCUTS = JSON.stringify(cfg.shortcuts);
     if (cfg.vapid) {
       if (cfg.vapid.public) env.VAPID_PUBLIC = cfg.vapid.public;
       if (cfg.vapid.private) env.VAPID_PRIVATE = cfg.vapid.private;