@happier-dev/stack 0.1.0-preview.100.1 → 0.1.0-preview.138.1

package/scripts/mobile.mjs

@@ -14,6 +14,7 @@ import { expoExec } from './utils/expo/command.mjs';
 import { ensureDevExpoServer } from './utils/dev/expo_dev.mjs';
 import { resolveMobileReachableServerUrl } from './utils/server/mobile_api_url.mjs';
 import { patchIosXcodeProjectsForSigningAndIdentity, resolveIosAppXcodeProjects } from './utils/mobile/ios_xcodeproj_patch.mjs';
+import { pickMetroPort, resolveStablePortStart } from './utils/expo/metro_ports.mjs';
 
 /**
  * Mobile dev helper for the Happier UI Expo app (typically `apps/ui`).
@@ -75,6 +76,7 @@ async function main() {
   const uiRepoDir = getComponentDir(rootDir, 'happier-ui');
   await requireDir('happier-ui', uiRepoDir);
   await ensureDepsInstalled(uiRepoDir, 'happier-ui');
+  const happyDir = uiRepoDir;
 
   // Happy monorepo layouts (historical):
   // - legacy: <happyDir>/expo-app (split-repo era)
@@ -104,7 +106,9 @@ async function main() {
   // (Info.plist includes `dev.happier.app.dev`), so iOS will open the dev build instead of the App Store app.
   const appEnv = process.env.APP_ENV ?? kv.get('--app-env') ?? 'development';
   const host = kv.get('--host') ?? process.env.HAPPIER_STACK_MOBILE_HOST ?? 'lan';
-  const portRaw = kv.get('--port') ?? process.env.HAPPIER_STACK_MOBILE_PORT ?? '8081';
+  const portFromArg = kv.get('--port') ?? '';
+  const portFromEnv = process.env.HAPPIER_STACK_MOBILE_PORT ?? '';
+  const portRaw = portFromArg || portFromEnv || '8081';
   // Default behavior:
   // - `hstack mobile` starts Metro and keeps running.
   // - `hstack mobile --run-ios` / `hstack mobile:ios` just builds/installs and exits (unless --metro is provided).
@@ -126,6 +130,29 @@ async function main() {
   const stackCtx = resolveStackContext({ env, autostart });
   const { stackMode, runtimeStatePath, stackName, envPath } = stackCtx;
 
+  // Expo/React Native native build steps can probe the Metro port even when we pass `--no-bundler`.
+  // Defaulting to 8081 makes builds much more likely to fail late if another Metro/Expo starts on the same port.
+  //
+  // Strategy:
+  // - If the user explicitly sets --port or HAPPIER_STACK_MOBILE_PORT, honor it.
+  // - Otherwise pick a stable, collision-resistant port in a higher range for build-only steps.
+  const needsNativeBuildPort = flags.has('--prebuild') || flags.has('--run-ios');
+  if (needsNativeBuildPort) {
+    const forcedPort = (portFromArg || portFromEnv).toString().trim();
+    const stableKey = (stackMode && stackName ? stackName : '') || iosBundleId || scheme || 'happier';
+    const startPort = resolveStablePortStart({
+      env,
+      stackName: stableKey,
+      baseKey: 'HAPPIER_STACK_MOBILE_BUILD_PORT_BASE',
+      rangeKey: 'HAPPIER_STACK_MOBILE_BUILD_PORT_RANGE',
+      defaultBase: 19000,
+      defaultRange: 10000,
+    });
+    const metroPort = await pickMetroPort({ startPort, forcedPort, host: '127.0.0.1' });
+    env.RCT_METRO_PORT = String(metroPort);
+    env.EXPO_PACKAGER_PORT = String(metroPort);
+  }
+
   // Ensure the built iOS app registers the same scheme we use for dev-client QR links.
   // (Happy app reads EXPO_APP_SCHEME in app.config.js; default remains unchanged when unset.)
   env.EXPO_APP_SCHEME = scheme;
@@ -306,7 +333,11 @@ async function main() {
     }
 
     const configuration = kv.get('--configuration') ?? 'Debug';
+    const buildMetroPort = (env.RCT_METRO_PORT ?? env.EXPO_PACKAGER_PORT ?? '').toString().trim();
     const args = ['run:ios', '--no-bundler', '--no-build-cache', '--configuration', configuration];
+    if (buildMetroPort) {
+      args.push('-p', buildMetroPort);
+    }
     if (device) {
       args.push('-d', device);
     }

package/scripts/mobile_prebuild_happyDir_defined.test.mjs

@@ -0,0 +1,47 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { getStackRootFromMeta, runNodeCapture } from './testkit/auth_testkit.mjs';
+
+test('hstack mobile --prebuild does not crash with undefined happyDir', async () => {
+  const rootDir = getStackRootFromMeta(import.meta.url);
+  const mobileScript = join(rootDir, 'scripts', 'mobile.mjs');
+
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-mobile-'));
+  const repoDir = join(tmp, 'repo');
+  const storageDir = join(tmp, 'storage');
+
+  try {
+    // Minimal fixture: the script expects a "happier-ui" dir to exist at <repo>/apps/ui.
+    // Avoid creating package.json to keep the run hermetic (ensureDepsInstalled will no-op).
+    await mkdir(join(repoDir, 'apps', 'ui'), { recursive: true });
+
+    // Ensure stack storage stays within this tmp dir (avoid touching real ~/.happier paths).
+    await mkdir(join(storageDir, 'main'), { recursive: true });
+
+    const env = {
+      ...process.env,
+      HAPPIER_STACK_REPO_DIR: repoDir,
+      HAPPIER_STACK_HOME_DIR: join(tmp, 'home'),
+      HAPPIER_STACK_STORAGE_DIR: storageDir,
+      HAPPIER_STACK_STACK: 'main',
+      // Keep resolveServerUrls from probing tailscale in tests.
+      HAPPIER_STACK_TAILSCALE_PREFER_PUBLIC_URL: '0',
+      HAPPIER_STACK_TAILSCALE_SERVE: '0',
+      // Prevent env auto-loading from a real machine stack env file.
+      HAPPIER_STACK_ENV_FILE: join(tmp, 'nonexistent-env'),
+    };
+
+    const res = await runNodeCapture([mobileScript, '--prebuild', '--no-metro'], { cwd: rootDir, env });
+    assert.doesNotMatch(
+      res.stderr,
+      /\bhappyDir is not defined\b/,
+      `expected prebuild to fail for a real reason (e.g. missing expo), not a ReferenceError\nstderr:\n${res.stderr}\nstdout:\n${res.stdout}`
+    );
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});

package/scripts/mobile_prebuild_sets_rct_metro_port.test.mjs

@@ -0,0 +1,81 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { chmod, mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { getStackRootFromMeta, runNodeCapture } from './testkit/auth_testkit.mjs';
+
+function parseKeyValueLines(text) {
+  const out = {};
+  for (const line of String(text ?? '').split(/\r?\n/)) {
+    const idx = line.indexOf('=');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim();
+    if (key) out[key] = value;
+  }
+  return out;
+}
+
+test('hstack mobile --prebuild sets RCT_METRO_PORT for native build steps', async () => {
+  const rootDir = getStackRootFromMeta(import.meta.url);
+  const mobileScript = join(rootDir, 'scripts', 'mobile.mjs');
+
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-mobile-port-'));
+  const repoDir = join(tmp, 'repo');
+  const storageDir = join(tmp, 'storage');
+
+  try {
+    const uiDir = join(repoDir, 'apps', 'ui');
+    const expoBin = join(uiDir, 'node_modules', '.bin', 'expo');
+    await mkdir(join(uiDir, 'node_modules', '.bin'), { recursive: true });
+
+    // Stub Expo CLI so the test doesn't require installing or running the real toolchain.
+    await writeFile(
+      expoBin,
+      `#!/usr/bin/env node
+console.log('RCT_METRO_PORT=' + (process.env.RCT_METRO_PORT ?? ''));
+console.log('EXPO_PACKAGER_PORT=' + (process.env.EXPO_PACKAGER_PORT ?? ''));
+process.exit(0);
+`,
+      'utf-8'
+    );
+    if (process.platform !== 'win32') {
+      await chmod(expoBin, 0o755);
+    }
+
+    // Ensure stack storage stays within this tmp dir (avoid touching real ~/.happier paths).
+    await mkdir(join(storageDir, 'main'), { recursive: true });
+
+    const env = {
+      ...process.env,
+      HAPPIER_STACK_REPO_DIR: repoDir,
+      HAPPIER_STACK_HOME_DIR: join(tmp, 'home'),
+      HAPPIER_STACK_STORAGE_DIR: storageDir,
+      HAPPIER_STACK_STACK: 'main',
+      // Keep resolveServerUrls from probing tailscale in tests.
+      HAPPIER_STACK_TAILSCALE_PREFER_PUBLIC_URL: '0',
+      HAPPIER_STACK_TAILSCALE_SERVE: '0',
+      // Prevent env auto-loading from a real machine stack env file.
+      HAPPIER_STACK_ENV_FILE: join(tmp, 'nonexistent-env'),
+    };
+
+    const res = await runNodeCapture([mobileScript, '--prebuild', '--platform=android', '--no-metro'], { cwd: rootDir, env });
+    const kv = parseKeyValueLines(res.stdout);
+    assert.ok(kv.RCT_METRO_PORT, `expected stub expo to print RCT_METRO_PORT\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+    assert.equal(
+      kv.EXPO_PACKAGER_PORT,
+      kv.RCT_METRO_PORT,
+      `expected EXPO_PACKAGER_PORT to match RCT_METRO_PORT\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`
+    );
+    assert.notEqual(
+      kv.RCT_METRO_PORT,
+      '8081',
+      `expected native build steps to avoid default Metro port 8081 (more collision-prone)\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`
+    );
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+

package/scripts/mobile_run_ios_passes_port.integration.test.mjs

@@ -0,0 +1,101 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { chmod, mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { getStackRootFromMeta, runNodeCapture } from './testkit/auth_testkit.mjs';
+
+function parseKeyValueLines(text) {
+  const out = {};
+  for (const line of String(text ?? '').split(/\r?\n/)) {
+    const idx = line.indexOf('=');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim();
+    if (key) out[key] = value;
+  }
+  return out;
+}
+
+test('hstack mobile --run-ios passes -p/--port to Expo (avoids default 8081)', async () => {
+  const rootDir = getStackRootFromMeta(import.meta.url);
+  const mobileScript = join(rootDir, 'scripts', 'mobile.mjs');
+
+  const tmp = await mkdtemp(join(tmpdir(), 'hstack-mobile-runios-port-'));
+  const repoDir = join(tmp, 'repo');
+  const storageDir = join(tmp, 'storage');
+
+  try {
+    const binDir = join(tmp, 'bin');
+    await mkdir(binDir, { recursive: true });
+    const xcrunStub = join(binDir, 'xcrun');
+    await writeFile(
+      xcrunStub,
+      `#!/bin/bash
+set -euo pipefail
+if [[ "\${1:-}" == "xcdevice" && "\${2:-}" == "list" ]]; then
+  echo "[]"
+  exit 0
+fi
+echo "xcrun stub: unsupported args: $*" >&2
+exit 1
+`,
+      'utf-8'
+    );
+    if (process.platform !== 'win32') {
+      await chmod(xcrunStub, 0o755);
+    }
+
+    const uiDir = join(repoDir, 'apps', 'ui');
+    const expoBin = join(uiDir, 'node_modules', '.bin', 'expo');
+    await mkdir(join(uiDir, 'node_modules', '.bin'), { recursive: true });
+
+    // Stub Expo CLI: print argv + env-derived ports and exit successfully.
+    // Use an absolute node shebang so the test can safely clear PATH.
+    await writeFile(
+      expoBin,
+      `#!${process.execPath}
+console.log('ARGS=' + JSON.stringify(process.argv.slice(2)));
+console.log('RCT_METRO_PORT=' + (process.env.RCT_METRO_PORT ?? ''));
+console.log('EXPO_PACKAGER_PORT=' + (process.env.EXPO_PACKAGER_PORT ?? ''));
+process.exit(0);
+`,
+      'utf-8'
+    );
+    if (process.platform !== 'win32') {
+      await chmod(expoBin, 0o755);
+    }
+
+    await mkdir(join(storageDir, 'main'), { recursive: true });
+
+    const env = {
+      ...process.env,
+      // Ensure xcrun runs fast/deterministically in tests.
+      PATH: binDir,
+      HAPPIER_STACK_REPO_DIR: repoDir,
+      HAPPIER_STACK_HOME_DIR: join(tmp, 'home'),
+      HAPPIER_STACK_STORAGE_DIR: storageDir,
+      HAPPIER_STACK_STACK: 'main',
+      HAPPIER_STACK_TAILSCALE_PREFER_PUBLIC_URL: '0',
+      HAPPIER_STACK_TAILSCALE_SERVE: '0',
+      HAPPIER_STACK_ENV_FILE: join(tmp, 'nonexistent-env'),
+    };
+
+    const res = await runNodeCapture([mobileScript, '--run-ios', '--no-metro'], { cwd: rootDir, env });
+    const kv = parseKeyValueLines(res.stdout);
+
+    const args = JSON.parse(kv.ARGS ?? '[]');
+    const port = kv.RCT_METRO_PORT ?? '';
+
+    assert.ok(port, `expected RCT_METRO_PORT to be set\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+    assert.equal(kv.EXPO_PACKAGER_PORT, port, `expected EXPO_PACKAGER_PORT to match\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+    assert.ok(args.includes('-p') || args.includes('--port'), `expected expo args to include -p/--port\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+    const pIdx = args.indexOf('-p') !== -1 ? args.indexOf('-p') : args.indexOf('--port');
+    assert.equal(args[pIdx + 1], port, `expected expo -p to match RCT_METRO_PORT\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+    assert.notEqual(port, '8081', `expected non-default port to reduce collisions\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  } finally {
+    await rm(tmp, { recursive: true, force: true });
+  }
+});
+

package/scripts/providers_cmd.mjs

@@ -0,0 +1,262 @@
+import './utils/env/env.mjs';
+
+import { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { createStepPrinter, runCommandLogged } from './utils/cli/progress.mjs';
+import { AGENT_IDS, getProviderCliInstallSpec } from '@happier-dev/agents';
+import { installProviderCli, planProviderCliInstall, resolvePlatformFromNodePlatform } from '@happier-dev/cli-common/providers';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+function usageText() {
+  return [
+    '[providers] usage:',
+    '  hstack providers list [--json]',
+    '  hstack providers install --providers=<id1,id2> [--dry-run] [--force] [--json]',
+    '  hstack providers install <id1> <id2> [--dry-run] [--force] [--json]',
+    '',
+    'notes:',
+    '  - Provider CLIs are external binaries used by Happier backends (claude/codex/gemini/etc).',
+    '  - This command installs provider CLIs (best-effort). Some providers require manual installation.',
+    '  - Claude install uses the upstream native installer by default (not npm).',
+    '  - Use --force to re-run the installer even if the binary is already present on PATH.',
+  ].join('\n');
+}
+
+function splitProviders(raw) {
+  const v = String(raw ?? '').trim();
+  if (!v) return [];
+  return v
+    .split(',')
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function resolvePlatform() {
+  return resolvePlatformFromNodePlatform(process.platform) ?? 'unsupported';
+}
+
+function commandExists(cmd, env) {
+  const name = String(cmd ?? '').trim();
+  if (!name) return false;
+
+  const pathEnv = env?.PATH ?? process.env.PATH;
+  if (process.platform === 'win32') {
+    const res = spawnSync('where', [name], { stdio: 'ignore', env: { ...process.env, ...(env ?? {}), PATH: pathEnv } });
+    return (res.status ?? 1) === 0;
+  }
+  const res = spawnSync('sh', ['-lc', `command -v ${name} >/dev/null 2>&1`], { stdio: 'ignore', env: { ...process.env, ...(env ?? {}), PATH: pathEnv } });
+  return (res.status ?? 1) === 0;
+}
+
+function resolveProviderInstallLogPath(providerId) {
+  const base = join(tmpdir(), 'happier-provider-installs');
+  mkdirSync(base, { recursive: true });
+  return join(base, `install-provider-${providerId}-${Date.now()}.log`);
+}
+
+function planForProvider(providerId) {
+  const platform = resolvePlatform();
+  if (platform === 'unsupported') {
+    return { ok: false, provider: providerId, error: 'Unsupported platform' };
+  }
+  const planned = planProviderCliInstall({ providerId, platform });
+  if (!planned.ok) {
+    return { ok: false, provider: providerId, error: planned.errorMessage };
+  }
+  return { ok: true, provider: providerId, commands: planned.plan.commands };
+}
+
+async function cmdList({ argv }) {
+  const { flags } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+  const platform = resolvePlatform();
+  const rows = AGENT_IDS.map((id) => {
+    const spec = getProviderCliInstallSpec(id);
+    const planned = planForProvider(id);
+    return {
+      id: spec.id,
+      title: spec.title,
+      binaries: spec.binaries,
+      autoInstall: planned.ok,
+      note: planned.ok ? null : planned.error,
+      platform,
+    };
+  });
+
+  printResult({
+    json,
+    data: { ok: true, platform, providers: rows },
+    text: json
+      ? null
+      : rows
+          .map((r) => `${r.autoInstall ? '✓' : '-'} ${r.id}${r.title ? `  (${r.title})` : ''}${r.note ? ` — ${r.note}` : ''}`)
+          .join('\n'),
+  });
+}
+
+async function cmdInstall({ argv }) {
+  const { flags, kv } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+  const dryRun = flags.has('--dry-run') || flags.has('--plan');
+  const force = flags.has('--force') || flags.has('--reinstall');
+  const skipIfInstalled = !force;
+
+  const positionals = argv.filter((a) => a && a !== '--' && !a.startsWith('-'));
+  const inputFromFlag = kv.get('--providers') ?? '';
+  const inputFromPositional = positionals;
+
+  const wanted = [
+    ...splitProviders(inputFromFlag),
+    ...inputFromPositional.flatMap((s) => splitProviders(String(s).trim().toLowerCase())),
+  ];
+
+  if (wanted.length === 0) {
+    throw new Error('[providers] missing providers. Use --providers=claude,codex or pass ids as positionals.');
+  }
+
+  const resolved = wanted.map((id) => {
+    if (!AGENT_IDS.includes(id)) {
+      const e = new Error(`[providers] unknown provider: ${id}`);
+      e.code = 'EUNKNOWN_PROVIDER';
+      throw e;
+    }
+    return id;
+  });
+
+  const platform = resolvePlatform();
+  if (platform === 'unsupported') {
+    throw new Error('[providers] unsupported platform');
+  }
+
+  // In json mode, preserve the existing structured behavior (no progress output).
+  if (json) {
+    const results = resolved.map((providerId) =>
+      installProviderCli({ providerId, platform, dryRun, skipIfInstalled, env: process.env }),
+    );
+    const failures = results.filter((r) => !r.ok);
+    if (failures.length > 0) {
+      const first = failures[0];
+      const extra = first.logPath ? `\nlog: ${first.logPath}` : '';
+      throw new Error(`[providers] install failed: ${first.errorMessage}${extra}`.trim());
+    }
+
+    const plan = results.map((r) => (r.ok ? r.plan : null)).filter(Boolean);
+
+    printResult({
+      json,
+      data: {
+        ok: true,
+        providers: resolved,
+        dryRun,
+        skipIfInstalled,
+        plan,
+        results: results.map((r) => (r.ok ? { ok: true, providerId: r.plan.providerId, alreadyInstalled: r.alreadyInstalled, logPath: r.logPath } : r)),
+      },
+      text: null,
+    });
+    return;
+  }
+
+  // Human-friendly progress output (TTY spinner when interactive; simple lines otherwise).
+  const steps = createStepPrinter({ enabled: true });
+  const results = [];
+  for (const providerId of resolved) {
+    const spec = getProviderCliInstallSpec(providerId);
+    const planned = planProviderCliInstall({ providerId, platform });
+    if (!planned.ok) {
+      throw new Error(`[providers] install failed: ${planned.errorMessage}`);
+    }
+
+    const label = `Installing ${spec.title || `${providerId} CLI`}`;
+    const binariesPresent = skipIfInstalled && spec.binaries.every((b) => commandExists(b, process.env));
+    if (binariesPresent) {
+      steps.info(`- [✓] ${label} (already installed)`);
+      results.push({ ok: true, providerId, alreadyInstalled: true, logPath: null, plan: planned.plan });
+      continue;
+    }
+
+    steps.start(label);
+    if (dryRun) {
+      steps.stop('✓', `${label} (dry-run)`);
+      results.push({ ok: true, providerId, alreadyInstalled: false, logPath: null, plan: planned.plan });
+      continue;
+    }
+
+    const logPath = resolveProviderInstallLogPath(providerId);
+    writeFileSync(
+      logPath,
+      [`# providerId: ${providerId}`, `# platform: ${platform}`, ''].join('\n'),
+      'utf8',
+    );
+
+    try {
+      for (const c of planned.plan.commands) {
+        // eslint-disable-next-line no-await-in-loop
+        await runCommandLogged({
+          label,
+          cmd: c.cmd,
+          args: c.args,
+          cwd: process.cwd(),
+          env: process.env,
+          logPath,
+          showSteps: false,
+          quiet: true,
+        });
+      }
+    } catch (e) {
+      steps.stop('x', label);
+      const message = e instanceof Error ? e.message : String(e);
+      throw new Error(`[providers] install failed: ${message}\nlog: ${logPath}`);
+    }
+
+    steps.stop('✓', label);
+    results.push({ ok: true, providerId, alreadyInstalled: false, logPath, plan: planned.plan });
+  }
+
+  printResult({
+    json,
+    data: {
+      ok: true,
+      providers: resolved,
+      dryRun,
+      skipIfInstalled,
+      plan: results.map((r) => r.plan),
+      results: results.map((r) => ({ ok: true, providerId: r.providerId, alreadyInstalled: r.alreadyInstalled, logPath: r.logPath })),
+    },
+    text: json ? null : `✓ providers installed: ${resolved.join(', ')}`,
+  });
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+
+  if (argv.length === 0 || wantsHelp(argv, { flags })) {
+    printResult({ json, data: { usage: usageText() }, text: usageText() });
+    return;
+  }
+
+  const positionals = argv.filter((a) => a && a !== '--' && !a.startsWith('-'));
+  const sub = String(positionals[0] ?? '').trim();
+  if (sub === 'list') {
+    await cmdList({ argv: argv.slice(1) });
+    return;
+  }
+  if (sub === 'install') {
+    await cmdInstall({ argv: argv.slice(1) });
+    return;
+  }
+
+  printResult({ json, data: { usage: usageText() }, text: usageText() });
+  process.exit(2);
+}
+
+main().catch((error) => {
+  const msg = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${msg}\n`);
+  process.exit(1);
+});

package/scripts/release_binary_smoke.integration.test.mjs

@@ -27,6 +27,25 @@ function commandExists(cmd) {
   return spawnSync('bash', ['-lc', `command -v ${cmd} >/dev/null 2>&1`], { stdio: 'ignore' }).status === 0;
 }
 
+function runWithHardTimeout(command, args, options) {
+  const timeoutMs = Number(options.timeout ?? 0);
+  if (process.platform === 'linux' && commandExists('timeout') && timeoutMs > 0) {
+    const timeoutSeconds = Math.max(1, Math.ceil(timeoutMs / 1000));
+    return spawnSync('timeout', ['--signal=KILL', '--kill-after=30s', `${timeoutSeconds}s`, command, ...args], {
+      ...options,
+      timeout: undefined,
+    });
+  }
+  return spawnSync(command, args, options);
+}
+
+function didCommandTimeout(result) {
+  if (result?.error?.code === 'ETIMEDOUT') return true;
+  if (result?.status === 124 || result?.status === 137) return true;
+  if (result?.signal === 'SIGKILL') return true;
+  return false;
+}
+
 function currentTarget() {
   const os = process.platform === 'linux' ? 'linux' : process.platform === 'darwin' ? 'darwin' : '';
   const arch = process.arch === 'x64' ? 'x64' : process.arch === 'arm64' ? 'arm64' : '';
@@ -65,7 +84,7 @@ test('compiled happier and server binaries execute from isolated cwd', async (t)
   const repoRoot = resolve(fileURLToPath(new URL('../../..', import.meta.url)));
   const version = `0.0.0-smoke.${Date.now()}`;
 
-  const buildCli = spawnSync(
+  const buildCli = runWithHardTimeout(
     process.execPath,
     [
       'scripts/release/build-cli-binaries.mjs',
@@ -91,13 +110,13 @@ test('compiled happier and server binaries execute from isolated cwd', async (t)
   t.after(() => {
     spawnSync('bash', ['-lc', `rm -rf "${cliExtract.extractDir.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
   });
-  const cliVersion = spawnSync(cliExtract.binaryPath, ['--version'], {
+  const cliVersion = runWithHardTimeout(cliExtract.binaryPath, ['--version'], {
     cwd: '/tmp',
     encoding: 'utf-8',
     env: { ...process.env, HAPPIER_NONINTERACTIVE: '1' },
     timeout: 7000,
   });
-  const cliTimedOut = cliVersion.error && cliVersion.error.code === 'ETIMEDOUT';
+  const cliTimedOut = didCommandTimeout(cliVersion);
   const cliExited = (cliVersion.status ?? 1) === 0;
   assert.ok(cliTimedOut || cliExited, cliVersion.stderr || cliVersion.stdout);
   const versionText = `${cliVersion.stdout || ''}${cliVersion.stderr || ''}`.trim();
@@ -107,7 +126,7 @@ test('compiled happier and server binaries execute from isolated cwd', async (t)
   );
 
   if (isLinuxTarget(target)) {
-    const buildServer = spawnSync(
+    const buildServer = runWithHardTimeout(
       process.execPath,
       [
         'scripts/release/build-server-binaries.mjs',
@@ -135,7 +154,7 @@ test('compiled happier and server binaries execute from isolated cwd', async (t)
     t.after(() => {
       spawnSync('bash', ['-lc', `rm -rf "${serverDataDir.replaceAll('"', '\\"')}"`], { stdio: 'ignore' });
     });
-    const serverBoot = spawnSync(serverExtract.binaryPath, [], {
+    const serverBoot = runWithHardTimeout(serverExtract.binaryPath, [], {
       cwd: '/tmp',
       encoding: 'utf-8',
       env: {
@@ -150,7 +169,7 @@ test('compiled happier and server binaries execute from isolated cwd', async (t)
       },
       timeout: 7000,
     });
-    const timedOut = serverBoot.error && serverBoot.error.code === 'ETIMEDOUT';
+    const timedOut = didCommandTimeout(serverBoot);
     const cleanExit = (serverBoot.status ?? 1) === 0;
     const serverOutput = `${serverBoot.stderr || ''}\n${serverBoot.stdout || ''}`;
     assert.ok(timedOut || cleanExit, serverOutput);