handmux 0.23.0 → 0.25.0

package/dist/src/cli/options.js

@@ -0,0 +1,245 @@
+// Pure CLI option handling: a tiny hand-rolled flag parser (no dependency) + config resolution.
+// 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'];
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isTunnel = (value) => typeof value === 'string' && TUNNELS.includes(value);
+const camel = (value) => value.replace(/-([a-z])/g, (_match, char) => char.toUpperCase());
+// argv = process.argv.slice(2). `command` is the first bare word; flags are `--key value`,
+// `--key` (boolean true), `--no-key` (boolean false), and `-f` (alias for --foreground).
+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 === undefined)
+            continue;
+        if (a === '-f') {
+            flags.foreground = true;
+            continue;
+        }
+        if (!a.startsWith('--')) {
+            if (a.startsWith('-'))
+                unknownShortFlags.push(a);
+            else
+                positionals.push(a);
+            continue;
+        }
+        const key = a.slice(2);
+        if (key.startsWith('no-')) {
+            assign(camel(key.slice(3)), false);
+            continue;
+        }
+        const next = rest[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+            assign(camel(key), true);
+        }
+        else {
+            assign(camel(key), next);
+            i++;
+        }
+    }
+    return {
+        command,
+        flags,
+        ...(positionals.length ? { positionals } : {}),
+        ...(unknownShortFlags.length ? { unknownShortFlags } : {}),
+    };
+}
+// ssh 回退公网地址:SSH 不生成 URL,无 --public-url 时用 host:remotePort(去掉 user@ 与 :sshPort)。
+export function sshPublicFallback(sshHost, remotePort) {
+    const host = sshHost.replace(/^[^@]*@/, '').replace(/:\d+$/, '');
+    return `http://${host}:${remotePort}`;
+}
+export function resolveConfig(flags = {}, fileCfg = {}, env = process.env, gen = defaultGen) {
+    const pick = (key, ...fallbacks) => {
+        for (const v of [flags[key], fileCfg[key], ...fallbacks])
+            if (v !== undefined && v !== null)
+                return v;
+        return undefined;
+    };
+    const tunnel = pick('tunnel', 'none');
+    if (!isTunnel(tunnel))
+        throw new Error(`unknown tunnel: ${String(tunnel)} (use: ${TUNNELS.join(', ')})`);
+    const port = Number(pick('port', env.HANDMUX_PORT, 19999));
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error(`bad port: ${pick('port', env.HANDMUX_PORT, 19999)}`);
+    const cfg = {
+        tunnel,
+        port,
+        name: optionalString(pick('name', env.HANDMUX_APP_NAME), 'name'),
+        host: optionalString(pick('host', env.HANDMUX_HOST, '0.0.0.0'), 'host') ?? '0.0.0.0',
+        token: optionalString(pick('token', env.HANDMUX_TOKEN), 'token') ?? gen(),
+        foreground: !!pick('foreground', false),
+        qr: pick('qr', true) !== false,
+        // Unified config — what used to live in .env. The supervisor injects these into the server child's
+        // environment (HANDMUX_STATIC_DIR / VAPID_* / XFYUN_* …), which is exactly where the server reads them.
+        staticDir: optionalString(pick('staticDir', env.HANDMUX_STATIC_DIR), 'static-dir'),
+        uploadExts: optionalString(pick('uploadExts', env.HANDMUX_UPLOAD_EXTS), 'upload-exts'),
+        previewDomain: optionalString(pick('previewDomain', env.HANDMUX_PREVIEW_DOMAIN), 'preview-domain'),
+        vapid: parseVapid(fileCfg.vapid), // { public, private, subject } — push notifications
+        xfyun: parseXfyun(fileCfg.xfyun), // { 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.
+        //
+        // Guard: a publicUrl in the FILE was set for the file's tunnel, so it only carries over when the
+        // resolved tunnel still matches (or the file pins no tunnel). Otherwise a `--tunnel B` override would
+        // advertise tunnel A's URL. A flag/env publicUrl is explicit for THIS run and always wins.
+        publicUrl: optionalString(resolvePublicUrl(flags, fileCfg, env, tunnel), 'public-url'),
+        // 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') {
+        cfg.sshHost = optionalString(pick('sshHost', env.HANDMUX_SSH_HOST), 'ssh-host');
+        if (!cfg.sshHost)
+            throw new Error('ssh tunnel needs --ssh-host user@host (or HANDMUX_SSH_HOST)');
+        const rp = Number(pick('remotePort', env.HANDMUX_REMOTE_PORT, port));
+        if (!Number.isInteger(rp) || rp < 1 || rp > 65535)
+            throw new Error(`bad remote-port: ${pick('remotePort', env.HANDMUX_REMOTE_PORT, port)}`);
+        cfg.remotePort = rp;
+        cfg.sshJump = optionalString(pick('sshJump', env.HANDMUX_SSH_JUMP), 'ssh-jump');
+        cfg.publicUrl = cfg.publicUrl || sshPublicFallback(cfg.sshHost, rp);
+    }
+    if (tunnel === 'cloudflare-named') {
+        cfg.cfHostname = optionalString(pick('cfHostname', env.HANDMUX_CF_HOSTNAME), 'cf-hostname');
+        if (!cfg.cfHostname)
+            throw new Error('cloudflare-named needs --cf-hostname handmux.example.com (or HANDMUX_CF_HOSTNAME)');
+        cfg.cfTunnelName = optionalString(pick('cfTunnelName', env.HANDMUX_CF_TUNNEL_NAME), 'cf-tunnel-name') || 'handmux';
+        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 = optionalString(pick('authtoken', env.HANDMUX_AUTHTOKEN), 'authtoken');
+        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 = optionalString(pick('cpolarRegion', env.HANDMUX_CPOLAR_REGION), 'cpolar-region');
+    }
+    return cfg;
+}
+// publicUrl resolution with the cross-tunnel guard (see resolveConfig). flag > file(if tunnel matches) > env.
+function optionalString(value, name) {
+    if (value === undefined || value === null || value === '')
+        return null;
+    if (typeof value !== 'string')
+        throw new Error(`bad ${name}: expected text`);
+    return value;
+}
+function stringFields(value, keys) {
+    if (!isRecord(value))
+        return null;
+    const result = {};
+    for (const key of keys)
+        if (typeof value[key] === 'string')
+            result[key] = value[key];
+    return result;
+}
+function parseVapid(value) {
+    return stringFields(value, ['public', 'private', 'subject']);
+}
+function parseXfyun(value) {
+    return stringFields(value, ['appId', 'apiKey', 'apiSecret']);
+}
+function resolvePublicUrl(flags, fileCfg, env, tunnel) {
+    if (flags.publicUrl != null)
+        return flags.publicUrl;
+    const fileTunnel = fileCfg.tunnel;
+    const fileApplies = fileTunnel == null || fileTunnel === tunnel;
+    if (fileApplies && fileCfg.publicUrl != null)
+        return fileCfg.publicUrl;
+    if (env.HANDMUX_PUBLIC_URL != null)
+        return env.HANDMUX_PUBLIC_URL;
+    return null;
+}
+// Default token: 8 chars from a typing-friendly alphabet (lowercase + digits, look-alikes 0/o/1/l dropped)
+// so it's quick to thumb in on a phone. A user-supplied token (flag/config/env) is used verbatim — any
+// length, never regenerated. 8 chars over a 32-char alphabet ≈ 40 bits, fine for a single secret URL.
+const TOKEN_ALPHABET = '23456789abcdefghijkmnpqrstuvwxyz';
+export function defaultGen() {
+    let s = '';
+    for (let i = 0; i < 8; i++)
+        s += TOKEN_ALPHABET[crypto.randomInt(TOKEN_ALPHABET.length)];
+    return s;
+}
+function trace(flags, fileCfg, env, cfgPath, key, envKey, def) {
+    if (flags[key] != null)
+        return { value: flags[key], origin: 'flag' };
+    if (fileCfg[key] != null)
+        return { value: fileCfg[key], origin: cfgPath || 'file' };
+    if (envKey && env[envKey] != null)
+        return { value: env[envKey], origin: 'env' };
+    return { value: def, origin: 'default' };
+}
+// Build the rows for `handmux config`: the value each key WOULD resolve to plus where it came from.
+// Lenient (never throws — unlike resolveConfig — so a half-finished config still prints) and secret-safe
+// (token masked; push/voice shown only as on/off). Tunnel-specific rows appear only for the live tunnel.
+export function explainConfig(flags = {}, fileCfg = {}, cfgPath = null, env = process.env) {
+    const rows = [];
+    const mask = (value) => (String(value).length <= 8 ? '••••' : `••••${String(value).slice(-4)}`);
+    const add = (key, traced, display) => {
+        rows.push({ key, origin: traced.origin, display: display ?? String(traced.value) });
+    };
+    const tunnel = trace(flags, fileCfg, env, cfgPath, 'tunnel', null, 'none');
+    add('tunnel', tunnel);
+    add('port', trace(flags, fileCfg, env, cfgPath, 'port', 'HANDMUX_PORT', 19999));
+    add('host', trace(flags, fileCfg, env, cfgPath, 'host', 'HANDMUX_HOST', '0.0.0.0'));
+    const name = trace(flags, fileCfg, env, cfgPath, 'name', 'HANDMUX_APP_NAME', null);
+    add('name', name, name.value == null ? '(default)' : String(name.value));
+    const lang = trace(flags, fileCfg, env, cfgPath, 'lang', 'HANDMUX_LANG', null);
+    add('lang', lang, lang.value == null ? '(auto — shell locale)' : String(lang.value));
+    const token = trace(flags, fileCfg, env, cfgPath, 'token', 'HANDMUX_TOKEN', null);
+    add('token', token, token.value == null ? '(generated each start)' : mask(token.value));
+    // publicUrl honours the same cross-tunnel guard as resolveConfig (file value only when tunnel matches).
+    const t = tunnel.value;
+    let pub = trace(flags, fileCfg, env, cfgPath, 'publicUrl', 'HANDMUX_PUBLIC_URL', null);
+    if (pub.origin !== 'flag' && pub.origin !== 'env' && fileCfg.tunnel != null && fileCfg.tunnel !== t) {
+        pub = { value: null, origin: 'default' };
+    }
+    add('publicUrl', pub, pub.value == null ? '(none — derived from tunnel if any)' : String(pub.value));
+    const previewDomain = trace(flags, fileCfg, env, cfgPath, 'previewDomain', 'HANDMUX_PREVIEW_DOMAIN', null);
+    add('previewDomain', previewDomain, previewDomain.value == null ? '(none)' : String(previewDomain.value));
+    if (t === 'ssh') {
+        add('sshHost', trace(flags, fileCfg, env, cfgPath, 'sshHost', 'HANDMUX_SSH_HOST', null));
+        add('remotePort', trace(flags, fileCfg, env, cfgPath, 'remotePort', 'HANDMUX_REMOTE_PORT', '(= port)'));
+        const jump = trace(flags, fileCfg, env, cfgPath, 'sshJump', 'HANDMUX_SSH_JUMP', null);
+        add('sshJump', jump, jump.value == null ? '(none)' : String(jump.value));
+    }
+    if (t === 'cloudflare-named') {
+        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' });
+    rows.push({ key: 'voice (xfyun)', origin: fileCfg.xfyun ? (cfgPath || 'file') : 'default', display: fileCfg.xfyun ? 'on' : 'off' });
+    return rows;
+}

package/dist/src/cli/piExtension.js

@@ -0,0 +1,155 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+const MANAGED_MARK = '// handmux-managed-pi-extension:v1';
+const ENTRY_MARK = '// handmux-entry:';
+export class PiExtensionInstallError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'PiExtensionInstallError';
+    }
+}
+function extensionDirectory(home) {
+    return path.join(home, '.pi', 'agent', 'extensions', 'handmux');
+}
+export function piExtensionFile(home = homedir()) {
+    return path.join(extensionDirectory(home), 'index.ts');
+}
+function errorCode(error) {
+    if (!error || typeof error !== 'object' || !('code' in error))
+        return null;
+    return typeof error.code === 'string' ? error.code : null;
+}
+function readManaged(file) {
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile())
+            return 'conflict';
+        const content = fs.readFileSync(file, 'utf8');
+        const lines = content.split('\n');
+        if (lines[0] !== MANAGED_MARK || !lines[1]?.startsWith(ENTRY_MARK))
+            return 'conflict';
+        const entryUrl = lines[1].slice(ENTRY_MARK.length);
+        if (!entryUrl.startsWith('file:'))
+            return 'conflict';
+        try {
+            fileURLToPath(entryUrl);
+        }
+        catch {
+            return 'conflict';
+        }
+        return { content, entryUrl };
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+function expectedEntryUrl(entryFile) {
+    try {
+        return pathToFileURL(fs.realpathSync(entryFile)).href;
+    }
+    catch {
+        return pathToFileURL(path.resolve(entryFile)).href;
+    }
+}
+function wrapper(entryFile) {
+    const entryUrl = expectedEntryUrl(entryFile);
+    return [
+        MANAGED_MARK,
+        `${ENTRY_MARK}${entryUrl}`,
+        '// This tiny wrapper is owned by Handmux. Pi loads it from its documented global extension path.',
+        `export { default } from ${JSON.stringify(entryUrl)};`,
+        '',
+    ].join('\n');
+}
+function validateEntry(entryFile) {
+    if (!path.isAbsolute(entryFile)) {
+        throw new PiExtensionInstallError('invalid_entry', 'Pi Extension entry must be absolute');
+    }
+    try {
+        const resolved = fs.realpathSync(entryFile);
+        if (!fs.statSync(resolved).isFile())
+            throw new Error('not a file');
+        return resolved;
+    }
+    catch {
+        throw new PiExtensionInstallError('entry_missing', 'Bundled Pi Extension entry is unavailable');
+    }
+}
+function referencedEntryExists(entryUrl) {
+    try {
+        return fs.statSync(fileURLToPath(entryUrl)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function piExtensionStatus(home = homedir(), options) {
+    const installed = readManaged(piExtensionFile(home));
+    if (installed === null)
+        return 'absent';
+    if (installed === 'conflict')
+        return 'conflict';
+    if (!referencedEntryExists(installed.entryUrl))
+        return 'stale';
+    if (options?.entryFile !== undefined
+        && installed.entryUrl !== expectedEntryUrl(options.entryFile))
+        return 'stale';
+    return 'installed';
+}
+function writeAtomic(file, content) {
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    fs.chmodSync(directory, 0o700);
+    const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        fs.writeFileSync(temporary, content, { flag: 'wx', mode: 0o600 });
+        fs.renameSync(temporary, file);
+        fs.chmodSync(file, 0o600);
+    }
+    finally {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { /* renamed or never created */ }
+    }
+}
+export function installPiExtension(home = homedir(), { entryFile }) {
+    const resolvedEntry = validateEntry(entryFile);
+    const file = piExtensionFile(home);
+    const existing = readManaged(file);
+    if (existing === 'conflict') {
+        throw new PiExtensionInstallError('conflict', 'Pi Extension target exists and is not owned by Handmux');
+    }
+    const content = wrapper(resolvedEntry);
+    const changed = existing?.content !== content;
+    if (changed)
+        writeAtomic(file, content);
+    return { status: 'installed', changed, file, entryFile: resolvedEntry };
+}
+export function syncPiExtension(home = homedir(), options) {
+    const status = piExtensionStatus(home, options);
+    if (status === 'absent' || status === 'conflict')
+        return null;
+    return installPiExtension(home, options);
+}
+export function uninstallPiExtension(home = homedir()) {
+    const file = piExtensionFile(home);
+    const existing = readManaged(file);
+    if (existing === null)
+        return { changed: false, file };
+    if (existing === 'conflict') {
+        throw new PiExtensionInstallError('conflict', 'Pi Extension target exists and is not owned by Handmux');
+    }
+    fs.unlinkSync(file);
+    try {
+        fs.rmdirSync(path.dirname(file));
+    }
+    catch { /* preserve non-empty/user-owned directory */ }
+    return { changed: true, file };
+}

package/dist/src/cli/probe.js

@@ -0,0 +1,16 @@
+export async function probe(url, { fetchImpl = globalThis.fetch, timeoutMs = 6000, } = {}) {
+    if (!url)
+        return false;
+    const ac = new AbortController();
+    const t = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+        await fetchImpl(url, { method: 'GET', redirect: 'manual', signal: ac.signal });
+        return true; // any HTTP response (even 401/404) means the chain is reachable
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(t);
+    }
+}

package/{src → dist/src}/cli/prompt.js

@@ -2,16 +2,14 @@
 // 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;
+    const v = await promptResult;
+    if (isCancel(v))
+        throw CANCELLED;
+    return v;
 }

package/dist/src/cli/pushCmd.js

@@ -0,0 +1,102 @@
+// `handmux push <title> <body> [--session X]... [--device K]... [--tag T] [--url U]` — fire one
+// notification to the phone through the already-running server (loopback + the server's own token).
+// Scope is mutually exclusive: --device (by key) or --session, else all. Pure parse + injectable
+// runner so it unit-tests without spawning or real fetch.
+import { readState } from './state.js';
+import { sanitizeNotificationUrl } from '../urlPolicy.js';
+const collect = (acc, value) => acc.concat(String(value ?? '').split(',').map((item) => item.trim()).filter(Boolean));
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const finiteNumber = (value) => typeof value === 'number' && Number.isFinite(value) ? value : 0;
+// argv is process.argv.slice(2), i.e. ['push', title, body, ...flags]. The shared parseArgs() drops bare
+// words after the command, so title/body are taken positionally; --session/--device may repeat.
+export function parsePushArgs(argv) {
+    const rest = argv.slice(1);
+    const positional = [];
+    let sessions = [];
+    let devices = [];
+    let tag;
+    let url;
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i] ?? '';
+        if (a === '--session') {
+            sessions = collect(sessions, rest[++i]);
+        }
+        else if (a === '--device') {
+            devices = collect(devices, rest[++i]);
+        }
+        else if (a === '--tag') {
+            tag = rest[++i];
+        }
+        else if (a === '--url') {
+            url = rest[++i];
+        }
+        else if (!a.startsWith('--'))
+            positional.push(a);
+    }
+    const [title, body] = positional;
+    if (!title || !body)
+        return { error: 'usage: handmux push <title> <body> [--session X]... [--device K]... [--tag T] [--url U]' };
+    if (sessions.length && devices.length)
+        return { error: 'use --session or --device, not both' };
+    const safeUrl = url == null ? null : sanitizeNotificationUrl(url);
+    if (url != null && !safeUrl)
+        return { error: '--url must be an http(s) URL or a relative path' };
+    const out = { title, body };
+    if (sessions.length)
+        out.sessions = sessions;
+    if (devices.length)
+        out.devices = devices;
+    if (tag)
+        out.tag = tag;
+    if (safeUrl)
+        out.url = safeUrl;
+    return out;
+}
+export async function runPush({ argv, home, fetchImpl = globalThis.fetch, log = console.log, err = console.error, }) {
+    const parsed = parsePushArgs(argv);
+    if (parsed.error) {
+        err(parsed.error);
+        return 1;
+    }
+    const st = readState(home);
+    if (!st || typeof st.localUrl !== 'string' || !st.localUrl
+        || typeof st.token !== 'string' || !st.token) {
+        err('handmux is not running — run `handmux start` first.');
+        return 1;
+    }
+    try {
+        const res = await fetchImpl(`${st.localUrl}/api/push/send-local`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${st.token}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify(parsed),
+        });
+        if (!res.ok) {
+            err(`push failed: ${res.status ?? 'unknown'}`);
+            return 1;
+        }
+        const raw = await res.json();
+        const out = isRecord(raw) ? raw : {};
+        if (out.configured === false) {
+            err('push is not configured (no VAPID keys) — run `handmux setup`.');
+            return 1;
+        }
+        const sent = finiteNumber(out.sent);
+        const failed = finiteNumber(out.failed);
+        const gone = finiteNumber(out.gone);
+        const counts = `sent: ${sent}, failed: ${failed}, gone: ${gone}`;
+        if (sent === 0) {
+            err(`no notification delivered (${counts})`);
+            return 1;
+        }
+        if (failed > 0) {
+            err(`push partially failed (${counts})`);
+            return 1;
+        }
+        log(`pushed (${counts})`);
+        return 0;
+    }
+    catch (e) {
+        err(`push failed: ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+    }
+}

package/{src → dist/src}/cli/qr.js

@@ -10,25 +10,25 @@
 //
 // matrix[r][c] === true means a DARK module. renderCompactQr is pure (no I/O) so it's unit-tested; the CLI
 // builds the matrix from qrcode-terminal's QR model and hands it here.
-
 export function renderCompactQr(matrix, { quiet = 2 } = {}) {
-  const n = matrix.length;
-  const side = n + quiet * 2;
-  // A module is LIGHT when it's outside the code (quiet zone, incl. a dangling final half-row) or the matrix
-  // cell is not dark.
-  const light = (r, c) => {
-    const mr = r - quiet, mc = c - quiet;
-    if (mr < 0 || mr >= n || mc < 0 || mc >= n) return true;
-    return !matrix[mr][mc];
-  };
-  let out = '';
-  for (let r = 0; r < side; r += 2) {
-    for (let c = 0; c < side; c++) {
-      const top = light(r, c);
-      const bottom = light(r + 1, c); // overflow row (odd side) is out-of-range → LIGHT, i.e. quiet border
-      out += top && bottom ? '█' : top ? '▀' : bottom ? '▄' : ' ';
+    const n = matrix.length;
+    const side = n + quiet * 2;
+    // A module is LIGHT when it's outside the code (quiet zone, incl. a dangling final half-row) or the matrix
+    // cell is not dark.
+    const light = (r, c) => {
+        const mr = r - quiet, mc = c - quiet;
+        if (mr < 0 || mr >= n || mc < 0 || mc >= n)
+            return true;
+        return !(matrix[mr]?.[mc] ?? false);
+    };
+    let out = '';
+    for (let r = 0; r < side; r += 2) {
+        for (let c = 0; c < side; c++) {
+            const top = light(r, c);
+            const bottom = light(r + 1, c); // overflow row (odd side) is out-of-range → LIGHT, i.e. quiet border
+            out += top && bottom ? '█' : top ? '▀' : bottom ? '▄' : ' ';
+        }
+        out += '\n';
     }
-    out += '\n';
-  }
-  return out;
+    return out;
 }