handmux 0.23.0 → 0.25.0

package/dist/src/cli/service.js

@@ -0,0 +1,154 @@
+// Boot/login autostart. The OS keeps the handmux SUPERVISOR (`__supervise`) alive; the supervisor
+// keeps server + tunnel alive — same model as a foreground run, just parented by launchd/systemd.
+// The service definition receives only a private supervisor-config path. Secrets stay out of argv, plist,
+// and unit text. Text generators are pure (unit-tested); the launchctl/systemctl calls inject `exec`.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { pocketHome, logPath } from './state.js';
+import { ensurePrivateDirectorySync } from '../privateStateStore.js';
+export const LABEL = 'com.handmux.agent';
+export const UNIT = 'handmux.service';
+const defaultExec = (command, args, options) => {
+    const result = options.encoding
+        ? spawnSync(command, [...args], { encoding: options.encoding })
+        : spawnSync(command, [...args], { stdio: options.stdio });
+    return { status: result.status, stderr: result.stderr };
+};
+const failureDetail = (result) => String(result.stderr || result.status);
+export function plistPath(home) { return path.join(home, 'Library', 'LaunchAgents', `${LABEL}.plist`); }
+export function unitPath(home) { return path.join(home, '.config', 'systemd', 'user', UNIT); }
+export function isServiceInstalled(home, platform = process.platform) {
+    if (platform === 'darwin')
+        return fs.existsSync(plistPath(home));
+    if (platform === 'linux')
+        return fs.existsSync(unitPath(home));
+    return false;
+}
+const xmlEscape = (value) => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+// launchd does not inherit the interactive shell PATH. Persist the caller's PATH so the supervised Server
+// resolves the same npm/Homebrew/nvm/volta Agent executables that `handmux start` could resolve.
+// args = full argv for the process (node, script, __supervise, --payload-file, path).
+export function plistFor({ args, log, label = LABEL, pathEnv }) {
+    const items = args.map((a) => `    <string>${xmlEscape(a)}</string>`).join('\n');
+    const environment = pathEnv ? `
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key><string>${xmlEscape(pathEnv)}</string>
+  </dict>` : '';
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${label}</string>
+  <key>ProgramArguments</key>
+  <array>
+${items}
+  </array>
+${environment}
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${xmlEscape(log)}</string>
+  <key>StandardErrorPath</key><string>${xmlEscape(log)}</string>
+</dict>
+</plist>
+`;
+}
+// systemd --user may likewise start with a manager PATH rather than the invoking shell's. ExecStart needs
+// a single command line; args are space-joined (our args have no spaces except an absolute path with none
+// in practice — quote the script path defensively).
+export function unitFor({ args, pathEnv }) {
+    const cmd = args.map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ');
+    const environment = pathEnv ? `Environment=${JSON.stringify(`PATH=${pathEnv}`)}\n` : '';
+    return `[Unit]
+Description=handmux — drive your tmux from your phone
+After=network-online.target
+
+[Service]
+ExecStart=${cmd}
+${environment}Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=default.target
+`;
+}
+export function installService(args, { home, platform = process.platform, exec = defaultExec, log = console, pathEnv = process.env.PATH, }) {
+    ensurePrivateDirectorySync(pocketHome(home));
+    const runtimeLog = logPath(home);
+    const descriptor = fs.openSync(runtimeLog, 'a', 0o600);
+    fs.closeSync(descriptor);
+    fs.chmodSync(runtimeLog, 0o600);
+    if (platform === 'darwin') {
+        const p = plistPath(home);
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, plistFor({ args, log: runtimeLog, ...(pathEnv ? { pathEnv } : {}) }), { mode: 0o600 });
+        fs.chmodSync(p, 0o600);
+        exec('launchctl', ['unload', p], { stdio: 'ignore' }); // best-effort: clear any prior load
+        const r = exec('launchctl', ['load', '-w', p], { encoding: 'utf8' });
+        if (r.status !== 0)
+            throw new Error(`launchctl load failed: ${failureDetail(r)}`);
+        log.log?.(`installed launchd agent: ${p}`);
+        return p;
+    }
+    if (platform === 'linux') {
+        const p = unitPath(home);
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, unitFor({ args, ...(pathEnv ? { pathEnv } : {}) }), { mode: 0o600 });
+        fs.chmodSync(p, 0o600);
+        exec('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore' });
+        const enabled = exec('systemctl', ['--user', 'enable', UNIT], { encoding: 'utf8' });
+        if (enabled.status !== 0)
+            throw new Error(`systemctl enable failed: ${failureDetail(enabled)}`);
+        // `enable --now` does not restart an already-active unit. Always restart after rewriting ExecStart so
+        // an npm/brew upgrade (new CLI/Node path) and a changed baked config take effect immediately.
+        const restarted = exec('systemctl', ['--user', 'restart', UNIT], { encoding: 'utf8' });
+        if (restarted.status !== 0)
+            throw new Error(`systemctl restart failed: ${failureDetail(restarted)}`);
+        log.log?.(`installed systemd --user unit: ${p}`);
+        log.log?.('(for autostart before login: loginctl enable-linger "$USER")');
+        return p;
+    }
+    throw new Error(`autostart not supported on ${platform} yet`);
+}
+// Stop the currently-loaded service without removing/disable-ing its login registration. This is what the
+// ordinary `handmux stop` command needs: stay stopped for this login session, then start normally again at
+// the next login/boot. In particular, do NOT SIGTERM the supervisor directly while KeepAlive/Restart=always
+// is active — the service manager would immediately resurrect it and race a second manual supervisor.
+export function stopService({ home, platform = process.platform, exec = defaultExec }) {
+    if (platform === 'darwin') {
+        const r = exec('launchctl', ['unload', plistPath(home)], { encoding: 'utf8' });
+        // unload returns non-zero when it was already unloaded; `stop` stays idempotent.
+        return r.status === 0;
+    }
+    if (platform === 'linux') {
+        const r = exec('systemctl', ['--user', 'stop', UNIT], { encoding: 'utf8' });
+        if (r.status !== 0)
+            throw new Error(`systemctl stop failed: ${failureDetail(r)}`);
+        return true;
+    }
+    throw new Error(`autostart not supported on ${platform} yet`);
+}
+export function uninstallService({ home, platform = process.platform, exec = defaultExec, log = console }) {
+    if (platform === 'darwin') {
+        const p = plistPath(home);
+        exec('launchctl', ['unload', '-w', p], { stdio: 'ignore' });
+        try {
+            fs.unlinkSync(p);
+        }
+        catch { /* already gone */ }
+        log.log?.(`removed launchd agent: ${p}`);
+        return;
+    }
+    if (platform === 'linux') {
+        exec('systemctl', ['--user', 'disable', '--now', UNIT], { stdio: 'ignore' });
+        try {
+            fs.unlinkSync(unitPath(home));
+        }
+        catch { /* already gone */ }
+        exec('systemctl', ['--user', 'daemon-reload'], { stdio: 'ignore' });
+        log.log?.(`removed systemd --user unit: ${unitPath(home)}`);
+        return;
+    }
+    throw new Error(`autostart not supported on ${platform} yet`);
+}

package/dist/src/cli/setupModel.js

@@ -0,0 +1,194 @@
+// Pure model for `handmux setup`: the answer↔config mappers, the wizard-owned key sets, the connection
+// summary, the cloudflared provisioning text helpers, and the clack validators. Extracted from the
+// interactive shell (setupWizard.ts) so the tested, side-effect-free logic stands on its own. Depends only
+// on i18n (t/getLocale) for user-facing strings — otherwise deterministic given its inputs.
+import { t, getLocale } from './i18n/index.js';
+import { TUNNELS } from './options.js';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isTunnel = (value) => typeof value === 'string' && TUNNELS.includes(value);
+const optionalString = (value) => typeof value === 'string' && value ? value : undefined;
+const stringObject = (value, keys) => {
+    if (!isRecord(value))
+        return undefined;
+    const result = {};
+    for (const key of keys)
+        if (typeof value[key] === 'string')
+            result[key] = value[key];
+    return result;
+};
+// ~/.cloudflared/config.yml for a named tunnel: route the hostname to the local handmux port.
+export function cfConfigYaml({ tunnelName, credentialsFile, hostname, port, }) {
+    return [
+        `tunnel: ${tunnelName}`,
+        `credentials-file: ${credentialsFile}`,
+        'ingress:',
+        `  - hostname: ${hostname}`,
+        `    service: http://localhost:${port}`,
+        '  - service: http_status:404',
+        '',
+    ].join('\n');
+}
+// Extract the tunnel UUID + credentials path from `cloudflared tunnel create <name>` stdout.
+export function parseTunnelCreate(out) {
+    const s = String(out || '');
+    const id = (s.match(/Created tunnel \S+ with id ([0-9a-fA-F-]+)/) || [])[1] || null;
+    const credentialsFile = (s.match(/credentials written to (\S+\.json)/i) || [])[1]?.replace(/\.$/, '') || null;
+    return { id, credentialsFile };
+}
+// Find an existing named tunnel's UUID in `cloudflared tunnel list --output json`. A named tunnel is a
+// PERSISTENT object in the Cloudflare account, so a second `setup` would hit `cloudflared tunnel create`'s
+// "tunnel with name X already exists" error — which used to force a rename and pile up junk tunnels in the
+// account. Looking it up first lets provisioning REUSE it idempotently. Tolerates non-JSON / errors → null.
+export function findTunnelId(listJsonOut, name) {
+    let arr;
+    try {
+        arr = JSON.parse(String(listJsonOut || ''));
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(arr))
+        return null;
+    const hit = arr.find((candidate) => isRecord(candidate) && candidate.name === name);
+    return isRecord(hit) && typeof hit.id === 'string' && hit.id ? hit.id : null;
+}
+// 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, uploadExts…) 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', 'previewDomain',
+    'sshHost', 'remotePort', 'sshJump', 'cfHostname', 'cfTunnelName', 'publicUrl',
+    'authtoken', 'cpolarRegion',
+    'vapid', 'xfyun',
+];
+// The tunnel-specific keys, cleared whenever the tunnel changes so a switch never carries a stale field.
+export const TUNNEL_KEYS = ['sshHost', 'remotePort', 'sshJump', 'cfHostname', 'cfTunnelName', 'publicUrl', 'authtoken', 'cpolarRegion'];
+// Wizard answers → the config fragment the user actually set (omit empty optional fields).
+export function configFromAnswers(a) {
+    const cfg = { tunnel: a.tunnel, port: a.port };
+    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;
+        if (a.publicUrl)
+            cfg.publicUrl = a.publicUrl;
+        if (a.sshJump)
+            cfg.sshJump = a.sshJump;
+    }
+    if (a.tunnel === 'cloudflare-named') {
+        cfg.cfHostname = a.cfHostname;
+        cfg.cfTunnelName = a.cfTunnelName;
+    }
+    if (a.tunnel === 'natapp' || a.tunnel === 'cpolar') {
+        if (a.authtoken)
+            cfg.authtoken = a.authtoken;
+        if (a.publicUrl)
+            cfg.publicUrl = a.publicUrl; // fixed/reserved domain (blank = temporary random)
+        if (a.cpolarRegion)
+            cfg.cpolarRegion = a.cpolarRegion;
+    }
+    if (a.vapid)
+        cfg.vapid = a.vapid;
+    if (a.xfyun)
+        cfg.xfyun = a.xfyun;
+    return cfg;
+}
+// Fold this run's answers into an existing config: preserve every non-wizard field, replace the wizard's
+// own fields wholesale. This is why re-running `setup` to switch tunnels (or edit the name) never drops
+// your token / push keys / static dir, yet also never leaves the previous tunnel's stale keys around.
+export function mergeConfig(existing = {}, answers) {
+    const out = isRecord(existing) ? { ...existing } : {};
+    for (const k of WIZARD_KEYS)
+        delete out[k];
+    return { ...out, ...configFromAnswers(answers) };
+}
+// Seed the working answers from an existing config so the hub shows current values and each edit starts
+// from what's already there. A brand-new config yields safe defaults (none/LAN, port 19999).
+export function answersFromConfig(config = {}) {
+    const cfg = isRecord(config) ? config : {};
+    const a = {
+        lang: optionalString(cfg.lang) || getLocale(),
+        name: optionalString(cfg.name) || '',
+        token: optionalString(cfg.token) || '', // '' = not pinned (auto each start); seeded so an untouched re-run rewrites it
+        previewDomain: optionalString(cfg.previewDomain) || '',
+        tunnel: isTunnel(cfg.tunnel) ? cfg.tunnel : 'none',
+        port: Number(cfg.port) || 19999,
+    };
+    const stringKeys = ['sshHost', 'sshJump', 'cfHostname', 'cfTunnelName', 'publicUrl', 'authtoken', 'cpolarRegion'];
+    for (const key of stringKeys) {
+        const value = optionalString(cfg[key]);
+        if (value)
+            a[key] = value;
+    }
+    if (typeof cfg.remotePort === 'number' && Number.isFinite(cfg.remotePort))
+        a.remotePort = cfg.remotePort;
+    const vapid = stringObject(cfg.vapid, ['public', 'private', 'subject']);
+    const xfyun = stringObject(cfg.xfyun, ['appId', 'apiKey', 'apiSecret']);
+    if (vapid)
+        a.vapid = vapid;
+    if (xfyun)
+        a.xfyun = xfyun;
+    return a;
+}
+// The dim one-line summary shown next to the Connection row (and reused nowhere else). Pure.
+export function summarizeConnection(a) {
+    const bare = (url) => String(url || '').replace(/^https?:\/\//, '');
+    switch (a.tunnel) {
+        case 'cloudflare': return `cloudflare · ${t('setup.sumTemp')}`;
+        case 'cloudflare-named': return `cloudflare-named · ${a.cfHostname || '?'}`;
+        case 'ssh': return `ssh · ${a.sshHost || '?'}`;
+        case 'natapp':
+        case 'cpolar': return `${a.tunnel} · ${a.publicUrl ? `${t('setup.sumFixed')} ${bare(a.publicUrl)}` : t('setup.sumTemp')}`;
+        default: return `${t('setup.tunnelNone')} · ${t('setup.sumNoRelay')}`;
+    }
+}
+// ---- validators (clack: return a string to reject + show inline, undefined to accept). Pure. ----
+export function validatePort(v) {
+    const n = Number(v);
+    if (!Number.isInteger(n) || n < 1 || n > 65535)
+        return t('setup.valPort');
+    return undefined;
+}
+export const validateNonEmpty = (label) => (value) => (String(value || '').trim() ? undefined : t('setup.valRequired', { label }));
+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');
+}
+// The built-in browser maps proxy origins below this domain. Blank deliberately leaves proxy mode disabled;
+// a URL, wildcard, or port would produce an invalid host when Handmux adds its own stable subdomain.
+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.)
+export function validateContact(v) {
+    const s = String(v || '').trim();
+    const wellFormed = /^mailto:[^@\s]+@[a-z0-9-]+(\.[a-z0-9-]+)+$/i.test(s)
+        || /^https:\/\/[a-z0-9-]+(\.[a-z0-9-]+)+/i.test(s);
+    if (!wellFormed || /\.local(?:[:/]|$)/i.test(s))
+        return t('setup.valContact');
+    return undefined;
+}
+// Access token: it rides in the phone's URL as ?token=…, so require something and reject whitespace (a space
+// would break the link). Length/charset are otherwise up to the user — a pinned token is used verbatim.
+export function validateToken(v) {
+    const s = String(v || '').trim();
+    if (!s)
+        return t('setup.valToken');
+    if (/\s/.test(s))
+        return t('setup.valTokenSpace');
+    return undefined;
+}