happy-stacks 0.6.11 → 0.6.13

package/docs/isolated-linux-vm.md

@@ -23,6 +23,18 @@ On your macOS host (this repo):
 This creates the VM if needed and configures **localhost port forwarding** for the port ranges used by our VM defaults.
 (This is important because the Expo web app uses WebCrypto and needs a secure context like `http://localhost`.)
 
+It also sets a higher default VM memory size (to avoid Expo/Metro getting OOM-killed and exiting with `code=137`).
+Override if needed:
+
+```bash
+LIMA_MEMORY=12GiB ./scripts/provision/macos-lima-happy-vm.sh happy-test
+```
+
+Port ranges note:
+- `review-pr` runs in a **fully isolated sandbox** (separate happy-stacks home dir), so VM defaults written to
+  `~/.happy-stacks/env.local` inside the VM won’t be read automatically.
+- Prefer passing `--vm-ports` (or explicit `--stack-port-start=...`) to `review-pr` so the sandbox uses the forwarded ranges.
+
 ### 2b) Manual setup (if you prefer)
 
 ```bash
@@ -30,6 +42,13 @@ limactl create --name happy-pr --tty=false template://ubuntu-24.04
 limactl start happy-pr
 ```
 
+If you run `review-pr` (Expo web / Metro) inside the VM, **allocate enough memory** (recommend **8GiB+**).
+Edit `~/.lima/happy-pr/lima.yaml` on the macOS host and set:
+
+```yaml
+memory: "8GiB"
+```
+
 ### 2c) Host access (ports + browser URLs)
 
 When you want to open Happy/Expo URLs in your macOS browser, **use localhost port forwarding**.
@@ -116,6 +135,7 @@ Inside the VM:
 ```bash
 npx --yes happy-stacks@latest review-pr \
   --happy=https://github.com/slopus/happy/pull/<PR_NUMBER> \
+  --vm-ports \
   --no-mobile \
   --keep-sandbox \
   --verbose \
@@ -126,6 +146,8 @@ Notes:
 - `--no-mobile` keeps the validation focused (Expo mobile dev-client adds more host requirements).
 - You can also add `--keep-sandbox` if you want to inspect the sandbox contents after a failure.
 - For full reproducibility, pin the version: `npx --yes happy-stacks@0.3.0 review-pr ...`
+- `--vm-ports` forces the stack/server and Expo dev-server (web) ports into the forwarded VM ranges
+  (pairs with the `portForwards` config in this doc).
 
 ### Optional: test **unreleased local changes**
 
@@ -170,7 +192,7 @@ On the macOS host:
 ```bash
 limactl stop happy-pr || true
 limactl delete happy-pr
-limactl create --name happy-pr --tty=false template://ubuntu-24.04
+limactl create --name happy-pr --tty=false template:ubuntu-24.04
 limactl start happy-pr
 ```
 

package/docs/stacks.md

@@ -312,9 +312,29 @@ happys stack auth <stack> login
 ```
 
 Notes:
+- You can run **multiple daemons for the same stack** on **different accounts** using `--identity=<name>`.
+  - `default` (no flag): `~/.happy/stacks/<stack>/cli/...`
+  - `--identity=account-b`: `~/.happy/stacks/<stack>/cli-identities/account-b/...`
+- To authenticate an identity without auto-opening a browser, use `--no-open` (it prints the URL so you can open it
+  in the browser profile/incognito window you want):
+
+```bash
+happys stack auth <stack> login --identity=account-a --no-open
+happys stack auth <stack> login --identity=account-b --no-open
+```
+
+- To start/stop an identity’s daemon explicitly:
+
+```bash
+happys stack daemon <stack> start --identity=account-a
+happys stack daemon <stack> stop  --identity=account-a
+```
+
 - For the **main** stack, use `<stack>=main` and the default `<port>=3005` (unless you changed it).
 - If you use Tailscale Serve, `HAPPY_WEBAPP_URL` should be your HTTPS URL (what you get from `happys tailscale url`).
-- Logs live under `~/.happy/stacks/<stack>/cli/logs/`.
+- Logs live under:
+  - default identity: `~/.happy/stacks/<stack>/cli/logs/`
+  - named identities: `~/.happy/stacks/<stack>/cli-identities/<identity>/logs/`
 
 ## JSON mode
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "happy-stacks",
   "type": "module",
-  "version": "0.6.11",
+  "version": "0.6.13",
   "packageManager": "pnpm@10.18.3",
   "bin": {
     "happys": "./bin/happys.mjs",

package/scripts/auth.mjs

@@ -28,6 +28,7 @@ import { resolveHandyMasterSecretFromStack } from './utils/auth/handy_master_sec
 import { ensureDir, readTextIfExists } from './utils/fs/ops.mjs';
 import { stackExistsSync } from './utils/stack/stacks.mjs';
 import { checkDaemonState } from './daemon.mjs';
+import { parseCliIdentityOrThrow, resolveCliHomeDirForIdentity } from './utils/stack/cli_identities.mjs';
 import {
   getCliHomeDirFromEnvOrDefault,
   getServerLightDataDirFromEnvOrDefault,
@@ -95,15 +96,35 @@ function resolveServerComponentForCurrentStack() {
 
 async function cmdDevKey({ argv, json }) {
   const { flags, kv } = parseArgs(argv);
+
+  // parseArgs currently only supports --k=v, but UX/docs commonly use: --k "value".
+  // Support both forms here (without changing global parsing semantics).
+  const argvKvValue = (name) => {
+    const n = String(name ?? '').trim();
+    if (!n) return '';
+    for (let i = 0; i < argv.length; i += 1) {
+      const a = String(argv[i] ?? '');
+      if (a === n) {
+        const next = String(argv[i + 1] ?? '');
+        if (next && !next.startsWith('--')) return next;
+        return '';
+      }
+      if (a.startsWith(`${n}=`)) {
+        return a.slice(`${n}=`.length);
+      }
+    }
+    return '';
+  };
+
   const wantPrint = flags.has('--print');
-  const fmtRaw = (kv.get('--format') ?? '').trim();
+  const fmtRaw = (argvKvValue('--format') || (kv.get('--format') ?? '')).trim();
   // UX: the Happy UI restore screen expects the "backup" (XXXXX-...) format.
   //
   // IMPORTANT: the Happy restore screen treats any key containing '-' as "backup format",
   // so printing a base64url key (which may contain '-') is *not reliably pasteable*.
   // Default to backup always unless explicitly overridden.
   const fmt = fmtRaw || 'backup'; // base64url | backup
-  const set = (kv.get('--set') ?? '').trim();
+  const set = (argvKvValue('--set') || (kv.get('--set') ?? '')).trim();
   const clear = flags.has('--clear');
 
   if (set) {
@@ -737,6 +758,9 @@ async function cmdCopyFrom({ argv, json }) {
 async function cmdStatus({ json }) {
   const rootDir = getRootDir(import.meta.url);
   const stackName = getStackName();
+  const argv = process.argv.slice(2);
+  const { kv } = parseArgs(argv);
+  const identity = parseCliIdentityOrThrow((kv.get('--identity') ?? '').trim());
 
   const { port, url: internalServerUrl } = getInternalServerUrlCompat();
   const { defaultPublicUrl, envPublicUrl } = getPublicServerUrlEnvOverride({ env: process.env, serverPort: port, stackName });
@@ -748,7 +772,7 @@ async function cmdStatus({ json }) {
     stackName,
   });
 
-  const cliHomeDir = resolveCliHomeDir();
+  const cliHomeDir = resolveCliHomeDirForIdentity({ cliHomeDir: resolveCliHomeDir(), identity });
   const accessKeyPath = join(cliHomeDir, 'access.key');
   const settingsPath = join(cliHomeDir, 'settings.json');
 
@@ -773,6 +797,7 @@ async function cmdStatus({ json }) {
     internalServerUrl,
     publicServerUrl,
     cliHomeDir,
+    cliIdentity: identity,
     auth,
     daemon,
     serverHealth: health,
@@ -844,11 +869,13 @@ async function cmdLogin({ argv, json }) {
   const webappUrl = await preferStackLocalhostUrl(webappUrlRaw, { stackName });
   const webappUrlSource = expoWebappUrl ? 'expo' : envWebappUrl ? 'stack env override' : 'server';
 
-  const cliHomeDir = resolveCliHomeDir();
+  const identity = parseCliIdentityOrThrow((kv.get('--identity') ?? '').trim());
+  const cliHomeDir = resolveCliHomeDirForIdentity({ cliHomeDir: resolveCliHomeDir(), identity });
   const cliBin = join(getComponentDir(rootDir, 'happy-cli'), 'bin', 'happy.mjs');
 
   const force = !argv.includes('--no-force');
   const wantPrint = argv.includes('--print');
+  const noOpen = flags.has('--no-open') || flags.has('--no-browser') || flags.has('--no-browser-open');
   const contextRaw =
     (kv.get('--context') ?? process.env.HAPPY_STACKS_AUTH_LOGIN_CONTEXT ?? process.env.HAPPY_LOCAL_AUTH_LOGIN_CONTEXT ?? '')
       .toString()
@@ -859,18 +886,29 @@ async function cmdLogin({ argv, json }) {
   if (force || argv.includes('--force')) {
     nodeArgs.push('--force');
   }
+  if (noOpen) {
+    nodeArgs.push('--no-open');
+  }
 
   const env = {
     ...process.env,
     HAPPY_HOME_DIR: cliHomeDir,
     HAPPY_SERVER_URL: internalServerUrl,
     HAPPY_WEBAPP_URL: webappUrl,
+    ...(noOpen ? { HAPPY_NO_BROWSER_OPEN: '1' } : {}),
   };
 
   if (wantPrint) {
-    const cmd = `HAPPY_HOME_DIR="${cliHomeDir}" HAPPY_SERVER_URL="${internalServerUrl}" HAPPY_WEBAPP_URL="${webappUrl}" node "${cliBin}" auth login${nodeArgs.includes('--force') ? ' --force' : ''}`;
+    const cmd =
+      `HAPPY_HOME_DIR="${cliHomeDir}" ` +
+      `HAPPY_SERVER_URL="${internalServerUrl}" ` +
+      `HAPPY_WEBAPP_URL="${webappUrl}" ` +
+      (noOpen ? `HAPPY_NO_BROWSER_OPEN="1" ` : '') +
+      `node "${cliBin}" auth login` +
+      (nodeArgs.includes('--force') ? ' --force' : '') +
+      (noOpen ? ' --no-open' : '');
     if (json) {
-      printResult({ json, data: { ok: true, stackName, cmd } });
+      printResult({ json, data: { ok: true, stackName, cliIdentity: identity, cmd } });
     } else {
       console.log(cmd);
     }
@@ -959,7 +997,7 @@ async function main() {
         sectionTitle('Usage (global)'),
         bullets([
           `${dim('status:')} ${cmdFmt('happys auth status')} ${dim('[--json]')}`,
-          `${dim('login:')}  ${cmdFmt('happys auth login')} ${dim('[--force] [--print] [--json]')}`,
+          `${dim('login:')}  ${cmdFmt('happys auth login')} ${dim('[--identity=<name>] [--no-open] [--force] [--print] [--json]')}`,
           `${dim('seed:')}   ${cmdFmt('happys auth copy-from <sourceStack|legacy> --all')} ${dim('[--except=main,dev-auth] [--force] [--with-infra] [--link] [--json]')}`,
           `${dim('dev key:')} ${cmdFmt('happys auth dev-key')} ${dim('[--print] [--format=base64url|backup] [--set=<secret>] [--clear] [--json]')}`,
         ]),
@@ -967,7 +1005,7 @@ async function main() {
         sectionTitle('Usage (stack-scoped)'),
         bullets([
           `${dim('status:')} ${cmdFmt('happys stack auth <name> status')} ${dim('[--json]')}`,
-          `${dim('login:')}  ${cmdFmt('happys stack auth <name> login')} ${dim('[--force] [--print] [--json]')}`,
+          `${dim('login:')}  ${cmdFmt('happys stack auth <name> login')} ${dim('[--identity=<name>] [--no-open] [--force] [--print] [--json]')}`,
           `${dim('seed:')}   ${cmdFmt('happys stack auth <name> copy-from <sourceStack|legacy>')} ${dim('[--force] [--with-infra] [--link] [--json]')}`,
         ]),
         '',

package/scripts/daemon.mjs

@@ -193,28 +193,37 @@ function resolveHappyCliDistEntrypoint(cliBin) {
 async function ensureHappyCliDistExists({ cliBin }) {
   const distEntrypoint = resolveHappyCliDistEntrypoint(cliBin);
   if (!distEntrypoint) return { ok: false, distEntrypoint: null, built: false, reason: 'unknown_cli_bin' };
-  if (existsSync(distEntrypoint)) return { ok: true, distEntrypoint, built: false, reason: 'exists' };
+  const cliDir = join(dirname(cliBin), '..');
 
   // Try to recover automatically: missing dist is a common first-run worktree issue.
   // We build in-place using the cliDir that owns this cliBin (../ from bin/).
-  const cliDir = join(dirname(cliBin), '..');
   const buildCli =
     (process.env.HAPPY_STACKS_CLI_BUILD ?? process.env.HAPPY_LOCAL_CLI_BUILD ?? '1').toString().trim() !== '0';
   if (!buildCli) {
     return { ok: false, distEntrypoint, built: false, reason: 'build_disabled' };
   }
 
+  let buildRes = null;
   try {
-    // eslint-disable-next-line no-console
-    console.warn(`[local] happy-cli build output missing; rebuilding (${cliDir})...`);
-    await ensureCliBuilt(cliDir, { buildCli: true });
+    // In auto mode, ensureCliBuilt() is a fast no-op when nothing changed.
+    buildRes = await ensureCliBuilt(cliDir, { buildCli: true });
+    if (buildRes?.built) {
+      // eslint-disable-next-line no-console
+      console.warn(`[local] happy-cli: rebuilt (${cliDir})`);
+    }
   } catch (e) {
     return { ok: false, distEntrypoint, built: false, reason: String(e?.message ?? e) };
   }
 
-  return existsSync(distEntrypoint)
-    ? { ok: true, distEntrypoint, built: true, reason: 'rebuilt' }
-    : { ok: false, distEntrypoint, built: true, reason: 'rebuilt_but_missing' };
+  if (existsSync(distEntrypoint)) {
+    return {
+      ok: true,
+      distEntrypoint,
+      built: Boolean(buildRes?.built),
+      reason: buildRes?.built ? (buildRes.reason ?? 'rebuilt') : 'exists',
+    };
+  }
+  return { ok: false, distEntrypoint, built: Boolean(buildRes?.built), reason: buildRes?.built ? 'rebuilt_but_missing' : 'missing' };
 }
 
 function excerptIndicatesMissingAuth(excerpt) {
@@ -243,14 +252,17 @@ function allowDaemonWaitForAuthWithoutTty() {
   return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'y';
 }
 
-function authLoginHint() {
-  const stackName = (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').trim() || 'main';
-  return stackName === 'main' ? 'happys auth login' : `happys stack auth ${stackName} login`;
+function authLoginHint({ stackName, cliIdentity }) {
+  const id = (cliIdentity ?? '').toString().trim();
+  const suffix = id && id !== 'default' ? ` --identity=${id} --no-open` : '';
+  return stackName === 'main' ? `happys auth login${suffix}` : `happys stack auth ${stackName} login${suffix}`;
 }
 
-function authCopyFromSeedHint() {
-  const stackName = (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').trim() || 'main';
+function authCopyFromSeedHint({ stackName, cliIdentity }) {
   if (stackName === 'main') return null;
+  // For multi-identity daemons, copying credentials defeats the purpose (multiple accounts).
+  const id = (cliIdentity ?? '').toString().trim();
+  if (id && id !== 'default') return null;
   const seed = resolveAuthSeedFromEnv(process.env);
   return `happys stack auth ${stackName} copy-from ${seed}`;
 }
@@ -456,11 +468,16 @@ export async function startLocalDaemonWithAuth({
   forceRestart = false,
   env = process.env,
   stackName = null,
+  cliIdentity = 'default',
 }) {
   const resolvedStackName =
     (stackName ?? '').toString().trim() ||
     (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim() ||
     'main';
+  const resolvedCliIdentity =
+    (cliIdentity ?? '').toString().trim() ||
+    (env.HAPPY_STACKS_CLI_IDENTITY ?? env.HAPPY_LOCAL_CLI_IDENTITY ?? '').toString().trim() ||
+    'default';
   const baseEnv = { ...env };
   const daemonEnv = getDaemonEnv({ baseEnv, cliHomeDir, internalServerUrl, publicServerUrl });
 
@@ -497,7 +514,7 @@ export async function startLocalDaemonWithAuth({
     return;
   }
 
-  if (!forceRestart && (existing.status === 'running' || existing.status === 'starting')) {
+  if (!forceRestart && existing.status === 'running') {
     const pid = existing.pid;
     const matches = await daemonEnvMatches({ pid, cliHomeDir, internalServerUrl, publicServerUrl });
     if (matches === true) {
@@ -518,6 +535,12 @@ export async function startLocalDaemonWithAuth({
       return;
     }
   }
+  if (!forceRestart && existing.status === 'starting') {
+    // A lock file without a stable daemon.state.json usually means the daemon never finished starting
+    // (common when auth is required but daemon start is non-interactive). Attempt a safe restart.
+    // eslint-disable-next-line no-console
+    console.warn(`[local] daemon appears stuck starting for stack home (pid=${existing.pid}); restarting...`);
+  }
 
   // Stop any existing daemon for THIS stack home dir.
   try {
@@ -569,7 +592,7 @@ export async function startLocalDaemonWithAuth({
     // daemon status separately.
     await delay(500);
     const stateAfter = checkDaemonState(cliHomeDir);
-    if (stateAfter.status === 'running' || stateAfter.status === 'starting') {
+    if (stateAfter.status === 'running') {
       return { ok: true, exitCode, excerpt: null, logPath: null };
     }
 
@@ -590,11 +613,11 @@ export async function startLocalDaemonWithAuth({
 
     if (excerptIndicatesMissingAuth(first.excerpt)) {
       const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY) || allowDaemonWaitForAuthWithoutTty();
-      const copyHint = authCopyFromSeedHint();
+      const copyHint = authCopyFromSeedHint({ stackName: resolvedStackName, cliIdentity: resolvedCliIdentity });
       const hint =
         `[local] daemon is not authenticated yet (expected on first run).\n` +
         `[local] In another terminal, run:\n` +
-        `${authLoginHint()}\n` +
+        `${authLoginHint({ stackName: resolvedStackName, cliIdentity: resolvedCliIdentity })}\n` +
         (copyHint ? `[local] Or (recommended if main is already logged in):\n${copyHint}\n` : '');
       if (!isInteractive) {
         throw new Error(`${hint}[local] Non-interactive mode: refusing to wait for credentials.`);
@@ -629,12 +652,12 @@ export async function startLocalDaemonWithAuth({
       try {
         await maybeAutoReseedInvalidAuth({ stackName });
       } catch (e) {
-        const copyHint = authCopyFromSeedHint();
+        const copyHint = authCopyFromSeedHint({ stackName: resolvedStackName, cliIdentity: resolvedCliIdentity });
         console.error(
           `[local] daemon credentials were rejected by the server (401).\n` +
             `[local] Fix:\n` +
             (copyHint ? `- ${copyHint}\n` : '') +
-            `- ${authLoginHint()}`
+            `- ${authLoginHint({ stackName: resolvedStackName, cliIdentity: resolvedCliIdentity })}`
         );
         throw e;
       }
@@ -648,13 +671,13 @@ export async function startLocalDaemonWithAuth({
         throw new Error('Failed to start daemon (after auth re-seed)');
       }
     } else {
-      const copyHint = authCopyFromSeedHint();
+      const copyHint = authCopyFromSeedHint({ stackName: resolvedStackName, cliIdentity: resolvedCliIdentity });
       console.error(
         `[local] daemon failed to start (server returned an error).\n` +
           `[local] Try:\n` +
           `- happys doctor\n` +
           (copyHint ? `- ${copyHint}\n` : '') +
-          `- ${authLoginHint()}`
+          `- ${authLoginHint({ stackName: resolvedStackName, cliIdentity: resolvedCliIdentity })}`
       );
       throw new Error('Failed to start daemon');
     }

package/scripts/doctor.mjs

@@ -63,7 +63,7 @@ async function fetchHealth(url) {
 
 async function main() {
   const argv = process.argv.slice(2);
-  const { flags, kv } = parseArgs(argv);
+  const { flags, kv: argsKv } = parseArgs(argv);
   const fix = flags.has('--fix');
   const json = wantsJson(argv, { flags });
 
@@ -117,7 +117,7 @@ async function main() {
     ? process.env.HAPPY_LOCAL_UI_BUILD_DIR.trim()
     : join(autostart.baseDir, 'ui');
 
-  const serverComponentName = getServerComponentName({ kv });
+  const serverComponentName = getServerComponentName({ kv: argsKv });
   if (serverComponentName === 'both') {
     throw new Error(`[doctor] --server=both is not supported (pick one: happy-server-light or happy-server)`);
   }

package/scripts/doctor_cmd.test.mjs

@@ -0,0 +1,67 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { mkdtemp, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function runNode(args, { cwd, env }) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(process.execPath, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', (d) => (stdout += String(d)));
+    proc.stderr.on('data', (d) => (stderr += String(d)));
+    proc.on('error', reject);
+    proc.on('exit', (code) => resolve({ code: code ?? 0, stdout, stderr }));
+  });
+}
+
+async function writeStubHappyCli({ dir }) {
+  await mkdir(join(dir, 'bin'), { recursive: true });
+  await mkdir(join(dir, 'dist'), { recursive: true });
+
+  // `scripts/doctor.mjs` runs: node <cliBin> daemon status
+  await writeFile(
+    join(dir, 'bin', 'happy.mjs'),
+    [
+      `if (process.argv.includes('daemon') && process.argv.includes('status')) {`,
+      `  console.log('Daemon is running');`,
+      `  process.exit(0);`,
+      `}`,
+      `console.log('ok');`,
+    ].join('\n'),
+    'utf-8'
+  );
+
+  // Keep dist present to avoid incidental MODULE_NOT_FOUND in other helper paths.
+  await writeFile(join(dir, 'dist', 'index.mjs'), `export {};`, 'utf-8');
+}
+
+test('doctor does not crash in non-json mode (kv helper not shadowed)', async () => {
+  const scriptsDir = dirname(fileURLToPath(import.meta.url));
+  const rootDir = dirname(scriptsDir);
+
+  const tmp = await mkdtemp(join(tmpdir(), 'happy-stacks-doctor-'));
+  const stubServer = join(tmp, 'happy-server-light');
+  const stubCli = join(tmp, 'happy-cli');
+  await mkdir(stubServer, { recursive: true });
+  await writeStubHappyCli({ dir: stubCli });
+
+  const env = {
+    ...process.env,
+    HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT: stubServer,
+    HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI: stubCli,
+    // Avoid UI build dir checks (keeps this test hermetic).
+    HAPPY_LOCAL_SERVE_UI: '0',
+    // Avoid any side effects in temp runs.
+    HAPPY_STACKS_CLI_ROOT_DISABLE: '1',
+  };
+
+  const res = await runNode([join(rootDir, 'scripts', 'doctor.mjs')], { cwd: rootDir, env });
+  assert.equal(res.code, 0, `expected exit 0, got ${res.code}\nstdout:\n${res.stdout}\nstderr:\n${res.stderr}`);
+  assert.match(res.stdout, /happy-stacks doctor/i);
+  assert.match(res.stdout, /Details/);
+});
+

package/scripts/happy.mjs

@@ -1,5 +1,5 @@
 import './utils/env/env.mjs';
-import { execFileSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseArgs } from './utils/cli/args.mjs';
@@ -43,7 +43,9 @@ async function main() {
   const cliDir = getComponentDir(rootDir, 'happy-cli');
   const entrypoint = join(cliDir, 'dist', 'index.mjs');
   if (!existsSync(entrypoint)) {
-    throw new Error(`[happy] missing happy-cli build at: ${entrypoint}\nRun: happys bootstrap`);
+    console.error(`[happy] missing happy-cli build at: ${entrypoint}`);
+    console.error('Run: happys bootstrap');
+    process.exit(1);
   }
 
   const env = { ...process.env };
@@ -51,14 +53,25 @@ async function main() {
   env.HAPPY_SERVER_URL = env.HAPPY_SERVER_URL || internalServerUrl;
   env.HAPPY_WEBAPP_URL = env.HAPPY_WEBAPP_URL || publicServerUrl;
 
-  execFileSync(process.execPath, ['--no-warnings', '--no-deprecation', entrypoint, ...argv], {
+  const res = spawnSync(process.execPath, ['--no-warnings', '--no-deprecation', entrypoint, ...argv], {
     stdio: 'inherit',
     env,
   });
+
+  if (res.error) {
+    const msg = res.error instanceof Error ? res.error.message : String(res.error);
+    console.error(`[happy] failed to run happy-cli: ${msg}`);
+    process.exit(1);
+  }
+
+  process.exit(res.status ?? 1);
 }
 
 main().catch((err) => {
-  console.error('[happy] failed:', err);
+  const message = err instanceof Error ? err.message : String(err);
+  console.error('[happy] failed:', message);
+  if (process.env.DEBUG && err instanceof Error && err.stack) {
+    console.error(err.stack);
+  }
   process.exit(1);
 });
-

package/scripts/import.mjs

@@ -18,6 +18,7 @@ import { readEnvObjectFromFile } from './utils/env/read.mjs';
 import { clipboardAvailable, copyTextToClipboard } from './utils/ui/clipboard.mjs';
 import { detectInstalledLlmTools } from './utils/llm/tools.mjs';
 import { launchLlmAssistant } from './utils/llm/assist.mjs';
+import { buildHappyStacksRunnerShellSnippet } from './utils/llm/happys_runner.mjs';
 
 function usage() {
   return [
@@ -505,30 +506,32 @@ function readPinnedComponentDirFromEnvObject(envObj, component) {
 }
 
 function buildLlmPromptForImport() {
+  const hs = buildHappyStacksRunnerShellSnippet();
   return [
     'You are an assistant helping the user migrate legacy Happy split repos into Happy Stacks.',
     '',
+    hs,
     'Goals:',
     '- Import legacy split repos (happy / happy-cli / happy-server) into a stack in Happy Stacks.',
     '- Optionally migrate commits into the slopus/happy monorepo layout (expo-app/cli/server).',
     '',
     'How to proceed:',
     '1) Run the guided import wizard:',
-    '   - `happys import`',
+    '   - `hs import`',
     '',
     'Non-interactive (LLM-friendly) variant:',
     '- Inspect candidate repos/worktrees/branches (JSON):',
-    '   - `happys import inspect --happy=<path|url> --happy-cli=<path|url> --happy-server=<path|url> --yes --json`',
+    '   - `hs import inspect --happy=<path|url> --happy-cli=<path|url> --happy-server=<path|url> --yes --json`',
     '- Apply pins to a stack (no prompts):',
-    '   - `happys import apply --stack=<name> --server=happy-server-light --happy=<path|url> --happy-ref=<ref> --happy-cli=<path|url> --happy-cli-ref=<ref> --happy-server=<path|url> --happy-server-ref=<ref> --yes`',
+    '   - `hs import apply --stack=<name> --server=happy-server-light --happy=<path|url> --happy-ref=<ref> --happy-cli=<path|url> --happy-cli-ref=<ref> --happy-server=<path|url> --happy-server-ref=<ref> --yes`',
     '2) If you want to migrate an existing imported stack later:',
-    '   - `happys import migrate --stack=<stack>`',
+    '   - `hs import migrate --stack=<stack>`',
     '',
     'Conflict handling (monorepo port):',
-    '- Prefer guided mode: `happys monorepo port guide --target=<monorepo-root>`',
+    '- Prefer guided mode: `hs monorepo port guide --target=<monorepo-root>`',
     '- For machine-readable state, use:',
-    '   - `happys monorepo port status --target=<monorepo-root> --json`',
-    '   - `happys monorepo port continue --target=<monorepo-root>`',
+    '   - `hs monorepo port status --target=<monorepo-root> --json`',
+    '   - `hs monorepo port continue --target=<monorepo-root>`',
     '',
     'Important:',
     '- A “stack” is an isolated runtime (ports + data + env) under ~/.happy/stacks/<name>.',
@@ -538,9 +541,11 @@ function buildLlmPromptForImport() {
 }
 
 function buildLlmPromptForMigrate({ stackName }) {
+  const hs = buildHappyStacksRunnerShellSnippet();
   return [
     'You are an assistant helping the user migrate an existing Happy Stacks stack to the monorepo.',
     '',
+    hs,
     `Target stack: ${stackName || '<stack>'}`,
     '',
     'Goal:',
@@ -548,17 +553,17 @@ function buildLlmPromptForMigrate({ stackName }) {
     '- Create a new monorepo stack by default (keep the legacy stack intact).',
     '',
     'Command:',
-    `- happys import migrate --stack=${stackName || '<stack>'}`,
+    `- hs import migrate --stack=${stackName || '<stack>'}`,
     '',
     'Conflict handling:',
-    '- This uses `happys monorepo port guide` which pauses on conflicts.',
-    '- To inspect machine-readably: `happys monorepo port status --target=<monorepo-root> --json`',
+    '- This uses `hs monorepo port guide` which pauses on conflicts.',
+    '- To inspect machine-readably: `hs monorepo port status --target=<monorepo-root> --json`',
   ].join('\n');
 }
 
 function buildMonorepoMigrationPrompt({ targetMonorepoRoot, branch, sources }) {
   const args = [
-    `happys monorepo port --target=${targetMonorepoRoot} --branch=${branch} --3way`,
+    `hs monorepo port --target=${targetMonorepoRoot} --branch=${branch} --3way`,
     sources.happy ? `--from-happy=${sources.happy}` : '',
     sources['happy-cli'] ? `--from-happy-cli=${sources['happy-cli']}` : '',
     sources['happy-server'] ? `--from-happy-server=${sources['happy-server']}` : '',
@@ -569,6 +574,7 @@ function buildMonorepoMigrationPrompt({ targetMonorepoRoot, branch, sources }) {
   return [
     'You are an assistant helping the user migrate split-repo commits into the Happy monorepo layout.',
     '',
+    buildHappyStacksRunnerShellSnippet(),
     `Target monorepo worktree: ${targetMonorepoRoot}`,
     `Port branch: ${branch}`,
     '',
@@ -580,10 +586,10 @@ function buildMonorepoMigrationPrompt({ targetMonorepoRoot, branch, sources }) {
     args,
     '',
     'If it stops with conflicts:',
-    `- Inspect: happys monorepo port status --target=${targetMonorepoRoot} --json`,
+    `- Inspect: hs monorepo port status --target=${targetMonorepoRoot} --json`,
     `- Resolve conflicted files (keep changes scoped to expo-app/, cli/, server/)`,
     `- Stage:  git -C ${targetMonorepoRoot} add <files>`,
-    `- Continue: happys monorepo port continue --target=${targetMonorepoRoot}`,
+    `- Continue: hs monorepo port continue --target=${targetMonorepoRoot}`,
     '',
     'Repeat status/resolve/continue until ok.',
   ].join('\n');