vibelet 0.1.37 → 1.0.0

package/bin/vibelet.mjs

@@ -0,0 +1,1062 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, openSync, writeSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import QRCode from 'qrcode';
+import { extractQuickTunnelUrl } from './cloudflared-quick-tunnel.mjs';
+import { formatCloudflaredFailureMessage, resolveCloudflaredLaunchSpec } from './cloudflared-resolver.mjs';
+import { doesHealthMatchRequestedConnectionConfig, shouldReuseHealthyDaemon } from './vibelet-runtime-policy.mjs';
+
+// ─── Paths & constants ─────────────────────────────────────────────────────────
+
+const rootDir = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const packageJson = JSON.parse(readFileSync(join(rootDir, 'package.json'), 'utf8'));
+const daemonDistDir = resolve(rootDir, 'dist');
+const daemonEntryPath = resolve(daemonDistDir, 'index.cjs');
+const port = Number(process.env.VIBE_PORT) || 9876;
+const vibeletDir = join(homedir(), '.vibelet');
+const pairingQrPngPath = join(vibeletDir, 'pairing-qr.png');
+const logDir = join(vibeletDir, 'logs');
+const runtimeDir = join(vibeletDir, 'runtime');
+const runtimeCurrentDir = join(runtimeDir, 'current');
+const runtimeMetadataPath = join(runtimeCurrentDir, 'runtime.json');
+const runtimeDaemonEntryPath = join(runtimeCurrentDir, 'dist', 'index.cjs');
+const stdoutLogPath = join(logDir, 'daemon.stdout.log');
+const stderrLogPath = join(logDir, 'daemon.stderr.log');
+const pidFilePath = join(vibeletDir, 'daemon.pid');
+const relayConfigPath = join(vibeletDir, 'relay.json');
+const tunnelStatePath = join(vibeletDir, 'tunnel.json');
+const updateCheckPath = join(vibeletDir, 'update-check.json');
+const OFFICIAL_SITE_URL = 'https://vibelet.icu';
+const UPDATE_CHECK_INTERVAL_MS = 4 * 60 * 60 * 1000; // 4 hours
+
+let officialSitePrinted = false;
+let updateMessage = '';
+
+function printOfficialSite() {
+  if (officialSitePrinted) return;
+  officialSitePrinted = true;
+  try {
+    if (updateMessage) writeSync(2, `\n${updateMessage}\n`);
+    writeSync(1, `\nOfficial site: ${OFFICIAL_SITE_URL}\n`);
+  } catch {
+    // Best-effort branding footer; ignore broken pipes and closed stdio.
+  }
+}
+
+// ─── Update check ──────────────────────────────────────────────────────────────
+
+function readUpdateCheck() {
+  try {
+    return JSON.parse(readFileSync(updateCheckPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeUpdateCheck(data) {
+  try {
+    mkdirSync(vibeletDir, { recursive: true });
+    writeFileSync(updateCheckPath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  } catch {
+    // Best-effort; failing to persist is fine.
+  }
+}
+
+function compareVersions(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+  }
+  return 0;
+}
+
+function checkForUpdateFromCache() {
+  const cached = readUpdateCheck();
+  if (!cached?.latestVersion) return;
+  if (compareVersions(packageJson.version, cached.latestVersion) < 0) {
+    updateMessage =
+      `\x1b[33m╭───────────────────────────────────────────╮\x1b[0m\n` +
+      `\x1b[33m│\x1b[0m  Update available: \x1b[90m${packageJson.version}\x1b[0m → \x1b[32m${cached.latestVersion}\x1b[0m${' '.repeat(Math.max(0, 14 - packageJson.version.length - cached.latestVersion.length))}\x1b[33m│\x1b[0m\n` +
+      `\x1b[33m│\x1b[0m  Run \x1b[36mnpx @vibelet/cli@latest\x1b[0m to upgrade   \x1b[33m│\x1b[0m\n` +
+      `\x1b[33m╰───────────────────────────────────────────╯\x1b[0m`;
+  }
+}
+
+function fetchLatestVersionInBackground() {
+  const cached = readUpdateCheck();
+  const now = Date.now();
+  if (cached?.checkedAt && now - cached.checkedAt < UPDATE_CHECK_INTERVAL_MS) {
+    return; // Checked recently; skip.
+  }
+
+  // Fire-and-forget: spawn a detached process to query the registry so we
+  // never block the CLI. Results are read on the *next* invocation.
+  const script = `
+    const https = await import('node:https');
+    const fs = await import('node:fs');
+    const url = 'https://registry.npmjs.org/@vibelet/cli/latest';
+    https.get(url, { headers: { 'Accept': 'application/json' }, timeout: 8000 }, (res) => {
+      let data = '';
+      res.on('data', (c) => data += c);
+      res.on('end', () => {
+        try {
+          const version = JSON.parse(data).version;
+          if (version) {
+            fs.writeFileSync(${JSON.stringify(updateCheckPath)}, JSON.stringify({
+              latestVersion: version,
+              checkedAt: Date.now(),
+            }, null, 2) + '\\n');
+          }
+        } catch {}
+      });
+    }).on('error', () => {});
+  `;
+
+  const child = spawn(process.execPath, ['--input-type=module', '-e', script], {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+  });
+  child.unref();
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────────
+
+function fail(message, details) {
+  process.stderr.write(`${message}\n`);
+  if (details) {
+    process.stderr.write(`${details}\n`);
+  }
+  process.exit(1);
+}
+
+function readRuntimeMetadata() {
+  if (!existsSync(runtimeMetadataPath)) return null;
+  try {
+    return JSON.parse(readFileSync(runtimeMetadataPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function ensureRuntimeInstalled() {
+  if (!existsSync(daemonEntryPath)) {
+    fail('The compiled daemon runtime is missing.', 'Run `pnpm build` before invoking `npx @vibelet/cli` from a source checkout.');
+  }
+
+  const sourceDaemonStat = statSync(daemonEntryPath);
+  const runtimeMetadata = readRuntimeMetadata();
+  const runtimeLooksFresh =
+    existsSync(runtimeDaemonEntryPath) &&
+    runtimeMetadata?.version === packageJson.version &&
+    runtimeMetadata?.daemonEntryMtimeMs === sourceDaemonStat.mtimeMs;
+
+  if (runtimeLooksFresh) {
+    return;
+  }
+
+  mkdirSync(runtimeDir, { recursive: true });
+  const nextRuntimeDir = join(runtimeDir, `current.${Date.now()}.${process.pid}`);
+  rmSync(nextRuntimeDir, { recursive: true, force: true });
+  mkdirSync(nextRuntimeDir, { recursive: true });
+  mkdirSync(logDir, { recursive: true });
+
+  writeFileSync(join(nextRuntimeDir, 'package.json'), JSON.stringify({
+    name: 'vibelet-runtime',
+    private: true,
+    type: 'module',
+  }, null, 2) + '\n', 'utf8');
+
+  cpSync(daemonDistDir, join(nextRuntimeDir, 'dist'), {
+    recursive: true,
+    dereference: true,
+    force: true,
+  });
+
+  writeFileSync(runtimeMetadataPath.replace(runtimeCurrentDir, nextRuntimeDir), JSON.stringify({
+    version: packageJson.version,
+    daemonEntryMtimeMs: sourceDaemonStat.mtimeMs,
+    installedAt: new Date().toISOString(),
+  }, null, 2) + '\n', 'utf8');
+
+  rmSync(runtimeCurrentDir, { recursive: true, force: true });
+  renameSync(nextRuntimeDir, runtimeCurrentDir);
+}
+
+// ─── PID file helpers ───────────────────────────────────────────────────────────
+
+function writePidFile(pid) {
+  mkdirSync(dirname(pidFilePath), { recursive: true });
+  writeFileSync(pidFilePath, String(pid), 'utf8');
+}
+
+function readPidFile() {
+  try {
+    const pid = Number(readFileSync(pidFilePath, 'utf8').trim());
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function removePidFile() {
+  rmSync(pidFilePath, { force: true });
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Platform service backends ──────────────────────────────────────────────────
+
+function createDarwinBackend() {
+  const label = 'dev.vibelet.daemon';
+  const uid = process.getuid?.();
+  const launchDomain = `gui/${uid ?? 0}`;
+  const launchAgentsDir = join(homedir(), 'Library', 'LaunchAgents');
+  const plistPath = join(launchAgentsDir, `${label}.plist`);
+
+  function launchctl(args) {
+    return spawnSync('launchctl', args, { encoding: 'utf8' });
+  }
+
+  function plistContents() {
+    const programArgs = [
+      process.execPath,
+      runtimeDaemonEntryPath,
+    ].map((value) => `      <string>${value}</string>`).join('\n');
+
+    const envVars = { VIBE_PORT: String(port) };
+    if (process.env.VIBELET_RELAY_URL) envVars.VIBELET_RELAY_URL = process.env.VIBELET_RELAY_URL;
+    if (process.env.VIBELET_CANONICAL_HOST) envVars.VIBELET_CANONICAL_HOST = process.env.VIBELET_CANONICAL_HOST;
+    if (process.env.VIBELET_FALLBACK_HOSTS) envVars.VIBELET_FALLBACK_HOSTS = process.env.VIBELET_FALLBACK_HOSTS;
+    const envSection = Object.keys(envVars).length > 0
+      ? `    <key>EnvironmentVariables</key>
+    <dict>
+${Object.entries(envVars).map(([k, v]) => `      <key>${k}</key>\n      <string>${v}</string>`).join('\n')}
+    </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>
+${programArgs}
+    </array>
+    <key>WorkingDirectory</key>
+    <string>${runtimeCurrentDir}</string>
+    <key>StandardOutPath</key>
+    <string>${stdoutLogPath}</string>
+    <key>StandardErrorPath</key>
+    <string>${stderrLogPath}</string>
+${envSection}
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+  </dict>
+</plist>
+`;
+  }
+
+  return {
+    name: 'launchd',
+    handlesProcessLifecycle: true,
+
+    isServiceInstalled() {
+      return launchctl(['print', `${launchDomain}/${label}`]).status === 0;
+    },
+
+    install() {
+      mkdirSync(launchAgentsDir, { recursive: true });
+      mkdirSync(logDir, { recursive: true });
+      const nextContents = plistContents();
+      const currentContents = existsSync(plistPath) ? readFileSync(plistPath, 'utf8') : null;
+      const serviceLoaded = this.isServiceInstalled();
+      const changed = currentContents !== nextContents;
+      if (changed) {
+        writeFileSync(plistPath, nextContents, 'utf8');
+      }
+
+      if (changed && serviceLoaded) {
+        launchctl(['bootout', `${launchDomain}/${label}`]);
+      }
+
+      if (changed || !serviceLoaded) {
+        const result = launchctl(['bootstrap', launchDomain, plistPath]);
+        if (result.status !== 0) {
+          fail('Failed to bootstrap vibelet launch agent.', result.stderr || result.stdout);
+        }
+      }
+    },
+
+    start() {
+      const result = launchctl(['kickstart', `${launchDomain}/${label}`]);
+      if (result.status !== 0 && !this.isServiceInstalled()) {
+        fail('Failed to start vibelet daemon.', result.stderr || result.stdout);
+      }
+    },
+
+    stop() {
+      if (this.isServiceInstalled()) {
+        launchctl(['bootout', `${launchDomain}/${label}`]);
+      }
+    },
+
+    statusLabel() {
+      return this.isServiceInstalled() ? 'loaded' : 'not loaded';
+    },
+  };
+}
+
+function createLinuxBackend() {
+  const unitName = 'vibelet-daemon.service';
+  const unitDir = join(homedir(), '.config', 'systemd', 'user');
+  const unitPath = join(unitDir, unitName);
+
+  function systemctl(args) {
+    return spawnSync('systemctl', ['--user', ...args], { encoding: 'utf8' });
+  }
+
+  function hasSystemd() {
+    return spawnSync('systemctl', ['--user', '--version'], { encoding: 'utf8' }).status === 0;
+  }
+
+  function unitContents() {
+    return `[Unit]
+Description=Vibelet Daemon
+After=network.target
+
+[Service]
+ExecStart=${process.execPath} ${runtimeDaemonEntryPath}
+WorkingDirectory=${runtimeCurrentDir}
+Restart=always
+RestartSec=3
+StandardOutput=append:${stdoutLogPath}
+StandardError=append:${stderrLogPath}
+Environment=VIBE_PORT=${port}${process.env.VIBELET_RELAY_URL ? `\nEnvironment=VIBELET_RELAY_URL=${process.env.VIBELET_RELAY_URL}` : ''}${process.env.VIBELET_CANONICAL_HOST ? `\nEnvironment=VIBELET_CANONICAL_HOST=${process.env.VIBELET_CANONICAL_HOST}` : ''}${process.env.VIBELET_FALLBACK_HOSTS ? `\nEnvironment=VIBELET_FALLBACK_HOSTS=${process.env.VIBELET_FALLBACK_HOSTS}` : ''}
+
+[Install]
+WantedBy=default.target
+`;
+  }
+
+  // Fallback: detached process with PID file (no systemd)
+  const fallback = createDetachedBackend();
+
+  const useSystemd = hasSystemd();
+  return {
+    name: useSystemd ? 'systemd' : 'detached',
+    handlesProcessLifecycle: useSystemd,
+
+    isServiceInstalled() {
+      if (!hasSystemd()) return fallback.isServiceInstalled();
+      return systemctl(['is-enabled', unitName]).status === 0;
+    },
+
+    install() {
+      if (!hasSystemd()) {
+        fallback.install();
+        return;
+      }
+      mkdirSync(unitDir, { recursive: true });
+      mkdirSync(logDir, { recursive: true });
+      const nextContents = unitContents();
+      const currentContents = existsSync(unitPath) ? readFileSync(unitPath, 'utf8') : null;
+      if (currentContents !== nextContents) {
+        writeFileSync(unitPath, nextContents, 'utf8');
+        systemctl(['daemon-reload']);
+      }
+      systemctl(['enable', unitName]);
+    },
+
+    start() {
+      if (!hasSystemd()) {
+        fallback.start();
+        return;
+      }
+      const result = systemctl(['start', unitName]);
+      if (result.status !== 0) {
+        fail('Failed to start vibelet daemon.', result.stderr || result.stdout);
+      }
+    },
+
+    stop() {
+      if (!hasSystemd()) {
+        fallback.stop();
+        return;
+      }
+      systemctl(['stop', unitName]);
+    },
+
+    statusLabel() {
+      if (!hasSystemd()) return fallback.statusLabel();
+      const result = systemctl(['is-active', unitName]);
+      return result.stdout?.trim() || 'unknown';
+    },
+  };
+}
+
+function createDetachedBackend() {
+  return {
+    name: 'detached',
+    handlesProcessLifecycle: false,
+
+    isServiceInstalled() {
+      const pid = readPidFile();
+      return pid !== null && isProcessAlive(pid);
+    },
+
+    install() {
+      mkdirSync(logDir, { recursive: true });
+    },
+
+    start() {
+      if (this.isServiceInstalled()) return;
+      const stdoutFd = openSync(stdoutLogPath, 'a');
+      const stderrFd = openSync(stderrLogPath, 'a');
+      const child = spawn(process.execPath, [runtimeDaemonEntryPath], {
+        detached: true,
+        stdio: ['ignore', stdoutFd, stderrFd],
+        cwd: runtimeCurrentDir,
+        env: { ...process.env, VIBE_PORT: String(port) },
+      });
+      child.unref();
+      writePidFile(child.pid);
+    },
+
+    stop() {
+      const pid = readPidFile();
+      if (pid && isProcessAlive(pid)) {
+        try {
+          process.kill(pid, 'SIGTERM');
+        } catch { /* already dead */ }
+      }
+      removePidFile();
+    },
+
+    statusLabel() {
+      const pid = readPidFile();
+      if (!pid) return 'not running';
+      return isProcessAlive(pid) ? `running (pid ${pid})` : 'not running (stale pid)';
+    },
+  };
+}
+
+function createWindowsBackend() {
+  // Windows: detached process with PID file
+  // Node.js detached on Windows creates a new console window — use windowsHide
+  return {
+    name: 'detached',
+    handlesProcessLifecycle: false,
+
+    isServiceInstalled() {
+      const pid = readPidFile();
+      return pid !== null && isProcessAlive(pid);
+    },
+
+    install() {
+      mkdirSync(logDir, { recursive: true });
+    },
+
+    start() {
+      if (this.isServiceInstalled()) return;
+      const stdoutFd = openSync(stdoutLogPath, 'a');
+      const stderrFd = openSync(stderrLogPath, 'a');
+      const child = spawn(process.execPath, [runtimeDaemonEntryPath], {
+        detached: true,
+        stdio: ['ignore', stdoutFd, stderrFd],
+        cwd: runtimeCurrentDir,
+        env: { ...process.env, VIBE_PORT: String(port) },
+        windowsHide: true,
+      });
+      child.unref();
+      writePidFile(child.pid);
+    },
+
+    stop() {
+      const pid = readPidFile();
+      if (pid && isProcessAlive(pid)) {
+        try {
+          process.kill(pid, 'SIGTERM');
+        } catch { /* already dead */ }
+      }
+      removePidFile();
+    },
+
+    statusLabel() {
+      const pid = readPidFile();
+      if (!pid) return 'not running';
+      return isProcessAlive(pid) ? `running (pid ${pid})` : 'not running (stale pid)';
+    },
+  };
+}
+
+function resolveBackend() {
+  switch (process.platform) {
+    case 'darwin': return createDarwinBackend();
+    case 'linux': return createLinuxBackend();
+    case 'win32': return createWindowsBackend();
+    default: return createDetachedBackend();
+  }
+}
+
+// ─── HTTP helpers ───────────────────────────────────────────────────────────────
+
+async function probeHealth(timeoutMs = 0) {
+  const deadline = Date.now() + timeoutMs;
+  do {
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/health`);
+      if (response.ok) {
+        return await response.json();
+      }
+    } catch {
+      // Retry until timeout.
+    }
+    if (timeoutMs <= 0) break;
+    await new Promise((resolvePromise) => setTimeout(resolvePromise, 250));
+  } while (Date.now() < deadline);
+  return null;
+}
+
+async function waitForHealth(timeoutMs = 10_000) {
+  const health = await probeHealth(timeoutMs);
+  if (health) {
+    return health;
+  }
+  fail(`Timed out waiting for vibelet daemon on port ${port}.`);
+}
+
+async function postJson(pathname, body = undefined) {
+  const response = await fetch(`http://127.0.0.1:${port}${pathname}`, {
+    method: 'POST',
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    fail(`Request to ${pathname} failed.`, JSON.stringify(payload, null, 2));
+  }
+  return payload;
+}
+
+async function requestShutdown() {
+  try {
+    await fetch(`http://127.0.0.1:${port}/shutdown`, { method: 'POST' });
+    // Wait for daemon to actually stop
+    const deadline = Date.now() + 5_000;
+    while (Date.now() < deadline) {
+      const health = await probeHealth(0);
+      if (!health) return true;
+      await new Promise((r) => setTimeout(r, 200));
+    }
+    return false;
+  } catch {
+    return true; // Already dead
+  }
+}
+
+function isDaemonStartCommand(command) {
+  return command === 'default' || command === 'start' || command === 'restart' || command === 'reset';
+}
+
+async function stopRunningDaemon(backend) {
+  await requestShutdown();
+  backend.stop();
+  const stillAlive = await probeHealth(5_000);
+  if (stillAlive) {
+    fail('Daemon did not stop in time.');
+  }
+}
+
+function createCompactPairingPayload(pairingPayload) {
+  const compactPayload = {
+    t: 'vp',
+    d: pairingPayload.daemonId,
+    n: pairingPayload.displayName,
+    h: pairingPayload.canonicalHost,
+    p: pairingPayload.port,
+    c: pairingPayload.pairNonce,
+    e: pairingPayload.expiresAt,
+  };
+  if (pairingPayload.fallbackHosts) compactPayload.f = pairingPayload.fallbackHosts;
+  return compactPayload;
+}
+
+async function printPairingQr(pairingPayload) {
+  const payload = JSON.stringify(createCompactPairingPayload(pairingPayload));
+  mkdirSync(vibeletDir, { recursive: true });
+  await QRCode.toFile(pairingQrPngPath, payload, {
+    type: 'png',
+    errorCorrectionLevel: 'M',
+    margin: 1,
+    scale: 8,
+  });
+  const qr = await QRCode.toString(payload, {
+    type: 'terminal',
+    small: true,
+    errorCorrectionLevel: 'M',
+  });
+  process.stdout.write(`\nScan this QR code with the Vibelet app:\n\n${qr}\n`);
+  process.stdout.write(`If Vibelet app can't scan the terminal QR, open this PNG instead:\n${pairingQrPngPath}\n`);
+}
+
+// ─── Commands ───────────────────────────────────────────────────────────────────
+
+async function printPairingSummary(existingHealth = null) {
+  const health = existingHealth ?? await waitForHealth();
+  const pairingPayload = await postJson('/pair/open');
+
+  process.stdout.write(`Vibelet daemon is ready.\n\n`);
+  process.stdout.write(`Device: ${health.displayName}\n`);
+  process.stdout.write(`Daemon ID: ${health.daemonId}\n`);
+  process.stdout.write(`Host: ${pairingPayload.canonicalHost}\n`);
+  process.stdout.write(`Port: ${pairingPayload.port}\n`);
+  process.stdout.write(`Paired devices: ${health.pairedDevices}\n`);
+  await printPairingQr(pairingPayload);
+}
+
+function printHelp() {
+  process.stdout.write(`Vibelet ${packageJson.version}\n\n`);
+  process.stdout.write(`Package names:\n`);
+  process.stdout.write(`  @vibelet/cli\n`);
+  process.stdout.write(`  vibelet\n\n`);
+  process.stdout.write(`Usage:\n`);
+  process.stdout.write(`  npx ${packageJson.name}           Install/start the daemon, auto-enable remote access, and print a pairing QR code\n`);
+  process.stdout.write(`  npx ${packageJson.name} start     Same as above\n`);
+  process.stdout.write(`  npx ${packageJson.name} --local   Skip the default Cloudflare Tunnel for this run\n`);
+  process.stdout.write(`  npx ${packageJson.name} --remote --force  Force a new Cloudflare Tunnel URL\n`);
+  process.stdout.write(`  npx ${packageJson.name} --relay <url>  Use a custom tunnel URL for remote access\n`);
+  process.stdout.write(`  npx ${packageJson.name} --host <ip>   Set the primary host/IP address\n`);
+  process.stdout.write(`  npx ${packageJson.name} --fallback-hosts <ips>  Comma-separated fallback IPs\n`);
+  process.stdout.write(`  npx ${packageJson.name} stop      Stop the daemon\n`);
+  process.stdout.write(`  npx ${packageJson.name} restart   Restart the daemon\n`);
+  process.stdout.write(`  npx ${packageJson.name} status    Show service and daemon status\n`);
+  process.stdout.write(`  npx ${packageJson.name} logs      Print recent daemon logs\n`);
+  process.stdout.write(`  npx ${packageJson.name} reset     Reset pairings and print a fresh QR code\n`);
+  process.stdout.write(`  npx ${packageJson.name} --help    Show this help text\n`);
+  process.stdout.write(`  npx ${packageJson.name} --version Show the installed CLI version\n`);
+  process.stdout.write(`\n`);
+  process.stdout.write(`You can also invoke the published alias with:\n`);
+  process.stdout.write(`  npx ${packageJson.name === 'vibelet' ? '@vibelet/cli' : 'vibelet'}\n`);
+  process.stdout.write(`  vibelet\n\n`);
+  process.stdout.write(`Remote access:\n`);
+  process.stdout.write(`  # Remote access is on by default for start/reset/restart\n`);
+  process.stdout.write(`  npx ${packageJson.name}\n\n`);
+  process.stdout.write(`  # Want LAN-only pairing for this run?\n`);
+  process.stdout.write(`  npx ${packageJson.name} --local\n\n`);
+  process.stdout.write(`  # Need a fresh Cloudflare Tunnel URL?\n`);
+  process.stdout.write(`  npx ${packageJson.name} --remote --force\n\n`);
+  process.stdout.write(`  # Or bring your own tunnel and pass the URL manually:\n`);
+  process.stdout.write(`  npx cloudflared tunnel --protocol http2 --url http://localhost:${port}\n`);
+  process.stdout.write(`  ngrok http ${port}\n`);
+  process.stdout.write(`  npx ${packageJson.name} --relay=https://<your-tunnel-url>\n\n`);
+  process.stdout.write(`  # Tailscale (P2P VPN, no tunnel needed)\n`);
+  process.stdout.write(`  npx ${packageJson.name} --host=<tailscale-ip>\n`);
+}
+
+function consumeFlag(name) {
+  const idx = process.argv.indexOf(`--${name}`);
+  if (idx === -1) return false;
+  process.argv.splice(idx, 1);
+  return true;
+}
+
+function readNpmConfigFlag(name) {
+  const value = process.env[`npm_config_${name.replace(/-/g, '_')}`];
+  return value === '' || value === 'true';
+}
+
+function parseNamedArg(name, errorHint) {
+  const inlinePrefix = `--${name}=`;
+  const inlineArg = process.argv.find((arg) => arg.startsWith(inlinePrefix));
+  if (inlineArg) {
+    const idx = process.argv.indexOf(inlineArg);
+    process.argv.splice(idx, 1);
+    return inlineArg.slice(inlinePrefix.length);
+  }
+
+  const idx = process.argv.indexOf(`--${name}`);
+  if (idx === -1) return null;
+  const value = process.argv[idx + 1];
+  if (!value || value.startsWith('-')) {
+    fail(`--${name} requires an argument${errorHint ? ` (e.g. --${name} ${errorHint})` : ''}`);
+  }
+  process.argv.splice(idx, 2);
+  return value;
+}
+
+function parseRelayArg() {
+  return parseNamedArg('relay', 'https://abc.trycloudflare.com');
+}
+
+function loadRelayConfig() {
+  try {
+    const data = JSON.parse(readFileSync(relayConfigPath, 'utf8'));
+    return data.relayUrl || '';
+  } catch {
+    return '';
+  }
+}
+
+function saveRelayConfig(relayUrl) {
+  mkdirSync(vibeletDir, { recursive: true });
+  writeFileSync(relayConfigPath, JSON.stringify({ relayUrl }, null, 2) + '\n', 'utf8');
+}
+
+function clearRelayConfig() {
+  rmSync(relayConfigPath, { force: true });
+}
+
+// ─── Tunnel management ──────────────────────────────────────────────────────────
+
+function loadTunnelState() {
+  try {
+    return JSON.parse(readFileSync(tunnelStatePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function saveTunnelState(pid, url) {
+  mkdirSync(vibeletDir, { recursive: true });
+  writeFileSync(tunnelStatePath, JSON.stringify({ pid, url }, null, 2) + '\n', 'utf8');
+}
+
+function clearTunnelState() {
+  rmSync(tunnelStatePath, { force: true });
+}
+
+function stopTunnel() {
+  const state = loadTunnelState();
+  if (state?.pid && isProcessAlive(state.pid)) {
+    try { process.kill(state.pid, 'SIGTERM'); } catch { /* already dead */ }
+  }
+  clearTunnelState();
+}
+
+function getAliveTunnel() {
+  const state = loadTunnelState();
+  if (state?.pid && state?.url && isProcessAlive(state.pid)) {
+    return state;
+  }
+  return null;
+}
+
+function readCloudflaredLog(logPath) {
+  try {
+    return readFileSync(logPath, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function startTunnel() {
+  return new Promise((resolve, reject) => {
+    const logPath = join(logDir, 'tunnel.stderr.log');
+    mkdirSync(logDir, { recursive: true });
+
+    const launchSpec = resolveCloudflaredLaunchSpec();
+
+    // Strategy: start cloudflared with output to log files (so it survives detach),
+    // then tail the log to capture the URL.
+    // Truncate log so we don't match a stale URL from a previous run.
+    writeFileSync(logPath, '', 'utf8');
+    const logFd = openSync(logPath, 'a');
+    const child = spawn(launchSpec.command, [
+      ...launchSpec.args,
+      'tunnel',
+      '--protocol',
+      'http2',
+      '--url',
+      `http://localhost:${port}`,
+    ], {
+      detached: true,
+      stdio: ['ignore', logFd, logFd],
+    });
+    child.unref();
+
+    const pid = child.pid;
+    let url = null;
+
+    const timeout = setTimeout(() => {
+      if (!url) {
+        try { process.kill(pid, 'SIGTERM'); } catch { /* */ }
+        reject(new Error(formatCloudflaredFailureMessage({
+          launchSpec,
+          logContent: readCloudflaredLog(logPath),
+          logPath,
+          phase: 'timeout',
+        })));
+      }
+    }, launchSpec.urlTimeoutMs);
+
+    // Poll the log file for the tunnel URL
+    const poll = setInterval(() => {
+      try {
+        const content = readFileSync(logPath, 'utf8');
+        const tunnelUrl = extractQuickTunnelUrl(content);
+        if (tunnelUrl) {
+          url = tunnelUrl;
+          clearInterval(poll);
+          clearTimeout(timeout);
+          saveTunnelState(pid, url);
+          resolve({ pid, url });
+          return;
+        }
+        // Check if process died before producing URL
+        if (!isProcessAlive(pid)) {
+          clearInterval(poll);
+          clearTimeout(timeout);
+          reject(new Error(formatCloudflaredFailureMessage({
+            launchSpec,
+            logContent: content,
+            logPath,
+            phase: 'exit',
+          })));
+        }
+      } catch { /* file not ready yet */ }
+    }, 300);
+
+    child.on('error', (err) => {
+      clearInterval(poll);
+      clearTimeout(timeout);
+      reject(new Error(formatCloudflaredFailureMessage({
+        launchSpec,
+        logContent: readCloudflaredLog(logPath),
+        logPath,
+        err,
+        phase: 'spawn',
+      })));
+    });
+  });
+}
+
+async function main() {
+  // Update check: read cached result (sync, instant) and spawn background fetch.
+  checkForUpdateFromCache();
+  fetchLatestVersionInBackground();
+
+  consumeFlag('remote') || consumeFlag('tunnel') || readNpmConfigFlag('remote') || readNpmConfigFlag('tunnel');
+  const localFlag = consumeFlag('local') || readNpmConfigFlag('local');
+  const forceFlag = consumeFlag('force') || readNpmConfigFlag('force');
+  const relayArg = parseRelayArg();
+  const hostArg = parseNamedArg('host', '100.x.x.x');
+  const fallbackHostsArg = parseNamedArg('fallback-hosts', '100.x.x.x,192.168.1.x');
+  const command = process.argv[2] ?? 'default';
+  const startCommand = isDaemonStartCommand(command);
+  // --remote/--tunnel remain accepted for compatibility, but startup commands
+  // now default to managed remote access unless another connection target wins.
+  const shouldManageTunnel = startCommand
+    && !localFlag
+    && relayArg === null
+    && !hostArg
+    && !fallbackHostsArg;
+
+  if (command === '--help' || command === '-h' || command === 'help') {
+    printHelp();
+    return;
+  }
+
+  if (command === '--version' || command === '-v' || command === 'version') {
+    process.stdout.write(`${packageJson.version}\n`);
+    return;
+  }
+
+  if (shouldManageTunnel) {
+    const existing = forceFlag ? null : getAliveTunnel();
+    if (existing) {
+      process.stdout.write(`Reusing tunnel: ${existing.url} (pid ${existing.pid})\n`);
+      saveRelayConfig(existing.url);
+    } else {
+      if (forceFlag) stopTunnel();
+      process.stdout.write('Starting Cloudflare Tunnel...\n');
+      try {
+        const tunnel = await startTunnel();
+        process.stdout.write(`Tunnel ready: ${tunnel.url}\n`);
+        saveRelayConfig(tunnel.url);
+      } catch (err) {
+        fail(err.message);
+      }
+    }
+  }
+
+  // --relay "" clears saved relay; --relay <url> saves it; omitted uses saved value
+  if (relayArg !== null) {
+    if (relayArg) {
+      saveRelayConfig(relayArg);
+    } else {
+      clearRelayConfig();
+    }
+  }
+  const shouldIgnoreSavedRelay = relayArg === null && (localFlag || Boolean(hostArg) || Boolean(fallbackHostsArg));
+  const relayUrl = relayArg !== null
+    ? relayArg
+    : (shouldIgnoreSavedRelay ? '' : loadRelayConfig());
+  if (relayUrl) {
+    process.env.VIBELET_RELAY_URL = relayUrl;
+  } else {
+    delete process.env.VIBELET_RELAY_URL;
+  }
+  if (hostArg) {
+    process.env.VIBELET_CANONICAL_HOST = hostArg;
+  } else {
+    delete process.env.VIBELET_CANONICAL_HOST;
+  }
+  if (fallbackHostsArg) {
+    process.env.VIBELET_FALLBACK_HOSTS = fallbackHostsArg;
+  } else {
+    delete process.env.VIBELET_FALLBACK_HOSTS;
+  }
+  const backend = resolveBackend();
+
+  if (command === 'stop') {
+    process.stdout.write('Stopping vibelet daemon...\n');
+    // Always try graceful HTTP shutdown first — gives the daemon time to
+    // close sessions and flush logs before the service manager kills it.
+    await stopRunningDaemon(backend);
+    // Also stop tunnel if running
+    const tunnelState = getAliveTunnel();
+    if (tunnelState) {
+      stopTunnel();
+      process.stdout.write('Tunnel stopped.\n');
+    }
+    process.stdout.write('Daemon stopped.\n');
+    return;
+  }
+
+  if (command === 'status') {
+    process.stdout.write(`Service (${backend.name}): ${backend.statusLabel()}\n`);
+    process.stdout.write(`Runtime: ${existsSync(runtimeDaemonEntryPath) ? runtimeDaemonEntryPath : 'not installed'}\n`);
+    const tunnelState = getAliveTunnel();
+    if (tunnelState) {
+      process.stdout.write(`Tunnel: ${tunnelState.url} (pid ${tunnelState.pid})\n`);
+    }
+    const savedRelay = loadRelayConfig();
+    if (savedRelay) {
+      process.stdout.write(`Relay: ${savedRelay}\n`);
+    }
+    const health = await probeHealth(1_500);
+    if (health) {
+      process.stdout.write(JSON.stringify(health, null, 2) + '\n');
+    } else {
+      process.stdout.write('Daemon is not responding.\n');
+    }
+    return;
+  }
+
+  if (command === 'logs') {
+    process.stdout.write(`Stdout: ${stdoutLogPath}\n`);
+    process.stdout.write(`Stderr: ${stderrLogPath}\n\n`);
+    const logFiles = [stdoutLogPath, stderrLogPath].filter((filePath) => existsSync(filePath));
+    if (logFiles.length === 0) {
+      process.stdout.write('No daemon logs have been written yet.\n');
+      return;
+    }
+    if (process.platform === 'win32') {
+      for (const logFile of logFiles) {
+        const content = readFileSync(logFile, 'utf8');
+        const lines = content.split('\n').slice(-80).join('\n');
+        process.stdout.write(`==> ${logFile} <==\n${lines}\n`);
+      }
+    } else {
+      const result = spawnSync('tail', ['-n', '80', ...logFiles], { encoding: 'utf8' });
+      if (result.stdout) process.stdout.write(result.stdout);
+      if (result.stderr) process.stderr.write(result.stderr);
+    }
+    return;
+  }
+
+  if (command === 'restart') {
+    process.stdout.write('Restarting vibelet daemon...\n');
+    await stopRunningDaemon(backend);
+    process.stdout.write('Daemon stopped. Starting...\n');
+    ensureRuntimeInstalled();
+    backend.install();
+    backend.start();
+    await printPairingSummary();
+    return;
+  }
+
+  if (command === 'reset') {
+    const healthyDaemon = await probeHealth(1_500);
+    const hasExplicitConfigOverrides = !doesHealthMatchRequestedConnectionConfig({
+      health: healthyDaemon,
+      relayUrl,
+      canonicalHost: hostArg || '',
+      fallbackHosts: fallbackHostsArg || '',
+      localMode: localFlag,
+    }) && (localFlag || Boolean(relayUrl) || Boolean(hostArg) || Boolean(fallbackHostsArg));
+    if (healthyDaemon && hasExplicitConfigOverrides) {
+      await stopRunningDaemon(backend);
+    }
+    ensureRuntimeInstalled();
+    backend.install();
+    backend.start();
+    await waitForHealth();
+    await postJson('/pair/reset');
+    await printPairingSummary();
+    return;
+  }
+
+  if (command !== 'default' && command !== 'start') {
+    printHelp();
+    fail(`Unknown command: ${command}`);
+  }
+
+  const healthyDaemon = await probeHealth(1_500);
+  const hasExplicitConfigOverrides = !doesHealthMatchRequestedConnectionConfig({
+    health: healthyDaemon,
+    relayUrl,
+    canonicalHost: hostArg || '',
+    fallbackHosts: fallbackHostsArg || '',
+    localMode: localFlag,
+  }) && (localFlag || Boolean(relayUrl) || Boolean(hostArg) || Boolean(fallbackHostsArg));
+  const existingHealth = shouldReuseHealthyDaemon({
+    command,
+    daemonHealthy: Boolean(healthyDaemon),
+    hasExplicitConfigOverrides,
+  }) ? healthyDaemon : null;
+
+  if (existingHealth) {
+    process.stdout.write('Vibelet daemon is already running.\n');
+    process.stdout.write('Reusing the current runtime so active sessions stay alive.\n');
+    process.stdout.write('Run `npx vibelet restart` to apply freshly built daemon code.\n\n');
+    await printPairingSummary(existingHealth);
+    return;
+  }
+
+  if (healthyDaemon && hasExplicitConfigOverrides) {
+    await stopRunningDaemon(backend);
+  }
+
+  ensureRuntimeInstalled();
+  backend.install();
+  backend.start();
+  await printPairingSummary();
+}
+
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));
+process.on('exit', printOfficialSite);
+await main();
+// On Windows + Node 24, process.exit(0) can trigger a libuv assertion
+// (UV_HANDLE_CLOSING) when detached child handles haven't fully released.
+// Letting the event loop drain naturally avoids this.
+if (process.platform !== 'win32') process.exit(0);