happy-stacks 0.2.0 → 0.4.0

package/scripts/utils/auth/sources.mjs

@@ -0,0 +1,38 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+import { resolveStackEnvPath } from '../paths/paths.mjs';
+
+export function isLegacyAuthSourceName(name) {
+  const s = String(name ?? '').trim().toLowerCase();
+  return s === 'legacy' || s === 'system' || s === 'local-install';
+}
+
+export function getLegacyHappyBaseDir() {
+  return join(homedir(), '.happy');
+}
+
+export function stackHasAccessKey(stackName) {
+  try {
+    const { baseDir, envPath } = resolveStackEnvPath(stackName);
+    if (!existsSync(envPath)) return false;
+    return existsSync(join(baseDir, 'cli', 'access.key'));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Seed sources that are safe to reuse locally.
+ *
+ * Note: deliberately does NOT include legacy ~/.happy sources; in many contexts we cannot reliably
+ * seed DB Account rows, which leads to broken stacks.
+ */
+export function detectSeedableAuthSources() {
+  const out = [];
+  if (stackHasAccessKey('dev-auth')) out.push('dev-auth');
+  if (stackHasAccessKey('main')) out.push('main');
+  return out;
+}
+

package/scripts/utils/auth/stack_guided_login.mjs

@@ -0,0 +1,353 @@
+import { existsSync } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+import { run, runCapture } from '../proc/proc.mjs';
+import { preferStackLocalhostUrl } from '../paths/localhost_host.mjs';
+import { guidedStackWebSignupThenLogin } from './guided_stack_web_login.mjs';
+import { resolveStackEnvPath, getWorkspaceDir } from '../paths/paths.mjs';
+import { getExpoStatePaths, isStateProcessRunning } from '../expo/expo.mjs';
+import { resolveLocalhostHost } from '../paths/localhost_host.mjs';
+import { getStackRuntimeStatePath, isPidAlive, readStackRuntimeStateFile } from '../stack/runtime_state.mjs';
+import { readEnvObjectFromFile } from '../env/read.mjs';
+import { expandHome } from '../paths/canonical_home.mjs';
+
+function extractEnvVar(cmd, key) {
+  const re = new RegExp(`${key}="([^"]+)"`);
+  const m = String(cmd ?? '').match(re);
+  return m?.[1] ? String(m[1]) : '';
+}
+
+async function resolveRuntimeExpoWebappUrlForAuth({ stackName }) {
+  try {
+    const runtimeStatePath = getStackRuntimeStatePath(stackName);
+    const st = await readStackRuntimeStateFile(runtimeStatePath);
+    const ownerPid = Number(st?.ownerPid);
+    if (!isPidAlive(ownerPid)) return '';
+    const port = Number(st?.expo?.port ?? st?.expo?.webPort ?? st?.expo?.mobilePort);
+    if (!Number.isFinite(port) || port <= 0) return '';
+    const host = resolveLocalhostHost({ stackMode: true, stackName });
+    return `http://${host}:${port}`;
+  } catch {
+    return '';
+  }
+}
+
+async function resolveExpoWebappUrlForAuth({ rootDir, stackName, timeoutMs }) {
+  const baseDir = resolveStackEnvPath(stackName).baseDir;
+  void rootDir; // kept for API stability; url resolution is stack-dir based
+
+  // IMPORTANT:
+  // In PR stacks (and especially in sandbox), the UI directory is typically a worktree path.
+  // Expo state paths include a hash derived from projectDir, so we cannot assume a stable uiDir
+  // here (e.g. `components/happy`). Instead, scan the stack's expo-dev state directory and pick
+  // the running Expo instance.
+  const expoDevRoot = join(baseDir, 'expo-dev');
+
+  async function resolveExpectedUiDir() {
+    try {
+      const { envPath } = resolveStackEnvPath(stackName);
+      const stackEnv = await readEnvObjectFromFile(envPath);
+      const raw = (stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY ?? stackEnv.HAPPY_LOCAL_COMPONENT_DIR_HAPPY ?? '').trim();
+      if (!raw) return '';
+
+      const expanded = expandHome(raw);
+      if (expanded.startsWith('/')) return resolve(expanded);
+
+      const wsRaw = (stackEnv.HAPPY_STACKS_WORKSPACE_DIR ?? stackEnv.HAPPY_LOCAL_WORKSPACE_DIR ?? '').trim();
+      const wsExpanded = wsRaw ? expandHome(wsRaw) : '';
+      const workspaceDir = wsExpanded ? (wsExpanded.startsWith('/') ? wsExpanded : resolve(getWorkspaceDir(rootDir), wsExpanded)) : getWorkspaceDir(rootDir);
+      return resolve(workspaceDir, expanded);
+    } catch {
+      return '';
+    }
+  }
+
+  async function looksLikeExpoMetro({ port }) {
+    const p = Number(port);
+    if (!Number.isFinite(p) || p <= 0) return false;
+
+    // Metro exposes `/status` which returns "packager-status:running".
+    const url = `http://127.0.0.1:${p}/status`;
+    try {
+      const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+      const timeout = setTimeout(() => controller?.abort(), 800);
+      try {
+        const res = await fetch(url, { signal: controller?.signal });
+        const txt = await res.text().catch(() => '');
+        return res.ok && String(txt).toLowerCase().includes('packager-status:running');
+      } finally {
+        clearTimeout(timeout);
+      }
+    } catch {
+      return false;
+    }
+  }
+
+  async function findRunningExpoStateUrl() {
+    if (!existsSync(expoDevRoot)) return '';
+    let entries = [];
+    try {
+      entries = await readdir(expoDevRoot, { withFileTypes: true });
+    } catch {
+      return '';
+    }
+
+    const expectedUiDir = await resolveExpectedUiDir();
+    const expectedUiDirResolved = expectedUiDir ? resolve(expectedUiDir) : '';
+
+    let best = null;
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue;
+      const statePath = join(expoDevRoot, ent.name, 'expo.state.json');
+      if (!existsSync(statePath)) continue;
+      // eslint-disable-next-line no-await-in-loop
+      const running = await isStateProcessRunning(statePath);
+      if (!running.running) continue;
+
+      // If the state includes capabilities, require web for auth (dev-client-only isn't enough).
+      const hasCaps = running.state && typeof running.state === 'object' && 'webEnabled' in running.state;
+      const webEnabled = hasCaps ? Boolean(running.state?.webEnabled) : true;
+      if (!webEnabled) continue;
+
+      // Tighten: if the stack env specifies an explicit UI directory, only accept Expo state that
+      // matches it. This avoids accidentally selecting stale Expo state left under this stack dir.
+      if (expectedUiDirResolved) {
+        const uiDirRaw = String(running.state?.uiDir ?? '').trim();
+        if (!uiDirRaw) continue;
+        if (resolve(uiDirRaw) !== expectedUiDirResolved) continue;
+      }
+
+      const port = Number(running.state?.port);
+      if (!Number.isFinite(port) || port <= 0) continue;
+
+      // If we're only considering this "running" because the port is occupied (pid not alive),
+      // do a quick Metro probe so we don't accept an unrelated process reusing the port.
+      if (running.reason === 'port') {
+        // eslint-disable-next-line no-await-in-loop
+        const ok = await looksLikeExpoMetro({ port });
+        if (!ok) continue;
+      }
+
+      // Prefer newest (startedAt) and prefer real pid-verified instances.
+      const startedAtMs = Date.parse(String(running.state?.startedAt ?? '')) || 0;
+      const score = (running.reason === 'pid' ? 1_000_000_000 : 0) + startedAtMs;
+      if (!best || score > best.score) {
+        best = { port, score };
+      }
+    }
+
+    if (!best) return '';
+    const host = resolveLocalhostHost({ stackMode: stackName !== 'main', stackName });
+    return `http://${host}:${best.port}`;
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    // eslint-disable-next-line no-await-in-loop
+    const url = await findRunningExpoStateUrl();
+    if (url) return url;
+    // eslint-disable-next-line no-await-in-loop
+    await delay(200);
+  }
+  return '';
+}
+
+async function fetchText(url, { timeoutMs = 2000 } = {}) {
+  const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+  const timeout = setTimeout(() => controller?.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: controller?.signal });
+    const text = await res.text().catch(() => '');
+    return { ok: res.ok, status: res.status, text, headers: res.headers };
+  } catch (e) {
+    return { ok: false, status: 0, text: String(e?.message ?? e), headers: null };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function pickHtmlBundlePath(html) {
+  const m = String(html ?? '').match(/<script[^>]+src="([^"]+)"[^>]*><\/script>/i);
+  return m?.[1] ? String(m[1]) : '';
+}
+
+async function detectSymlinkedNodeModules({ worktreeDir }) {
+  try {
+    const p = join(worktreeDir, 'node_modules');
+    const st = await stat(p);
+    return Boolean(st.isSymbolicLink && st.isSymbolicLink());
+  } catch {
+    return false;
+  }
+}
+
+export async function assertExpoWebappBundlesOrThrow({ rootDir, stackName, webappUrl }) {
+  const u = new URL(webappUrl);
+  const port = u.port ? Number(u.port) : null;
+  const probeHost = Number.isFinite(port) ? '127.0.0.1' : u.hostname;
+  const base = `${u.protocol}//${probeHost}${u.port ? `:${u.port}` : ''}`;
+
+  // Retry briefly: Metro can be up while the first bundle compile is still warming.
+  const deadline = Date.now() + 60_000;
+  let lastError = '';
+  while (Date.now() < deadline) {
+    // eslint-disable-next-line no-await-in-loop
+    const htmlRes = await fetchText(`${base}/`, { timeoutMs: 2500 });
+    if (!htmlRes.ok) {
+      lastError = `HTTP ${htmlRes.status} loading ${base}/`;
+      // eslint-disable-next-line no-await-in-loop
+      await delay(500);
+      continue;
+    }
+
+    const bundlePath = pickHtmlBundlePath(htmlRes.text);
+    if (!bundlePath) {
+      lastError = `could not find bundle <script src> in ${base}/`;
+      // eslint-disable-next-line no-await-in-loop
+      await delay(500);
+      continue;
+    }
+
+    // eslint-disable-next-line no-await-in-loop
+    const bundleRes = await fetchText(`${base}${bundlePath.startsWith('/') ? '' : '/'}${bundlePath}`, { timeoutMs: 8000 });
+    if (bundleRes.ok) {
+      return;
+    }
+
+    // Metro resolver errors are deterministic: surface immediately with actionable hints.
+    try {
+      const parsed = JSON.parse(String(bundleRes.text ?? ''));
+      const type = String(parsed?.type ?? '').trim();
+      const msg = String(parsed?.message ?? '').trim();
+      if (type === 'UnableToResolveError' || msg.includes('Unable to resolve module')) {
+        let hint = '';
+        try {
+          const { envPath } = resolveStackEnvPath(stackName);
+          const stackEnv = await readEnvObjectFromFile(envPath);
+          const uiDir = (stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY ?? stackEnv.HAPPY_LOCAL_COMPONENT_DIR_HAPPY ?? '').trim();
+          const symlinked = uiDir ? await detectSymlinkedNodeModules({ worktreeDir: uiDir }) : false;
+          if (symlinked) {
+            hint =
+              '\n' +
+              '[auth] Hint: this looks like an Expo/Metro resolution failure with symlinked node_modules.\n' +
+              '[auth] Fix: re-run review-pr/setup-pr with `--deps=install` (avoid linking node_modules for happy).\n';
+          }
+        } catch {
+          // ignore
+        }
+        throw new Error(
+          '[auth] Expo web UI is running, but the web bundle failed to build.\n' +
+            `[auth] URL: ${webappUrl}\n` +
+            `[auth] Error: ${msg || type || `HTTP ${bundleRes.status}`}\n` +
+            hint
+        );
+      }
+    } catch {
+      // not JSON / not a known error
+    }
+
+    lastError = `HTTP ${bundleRes.status} loading bundle ${bundlePath}`;
+    // eslint-disable-next-line no-await-in-loop
+    await delay(500);
+  }
+
+  if (lastError) {
+    throw new Error(
+      '[auth] Expo web UI did not become ready for guided login (bundle not loadable).\n' +
+        `[auth] URL: ${webappUrl}\n` +
+        `[auth] Last error: ${lastError}\n` +
+        '[auth] Tip: re-run with --verbose to see Expo logs (or open the stack runner log file).'
+    );
+  }
+}
+
+export async function resolveStackWebappUrlForAuth({ rootDir, stackName, env = process.env }) {
+  // Fast path: if the stack runner already recorded Expo webPort in stack.runtime.json,
+  // use it immediately (runtime state is authoritative).
+  const runtimeExpoUrl = await resolveRuntimeExpoWebappUrlForAuth({ stackName });
+  if (runtimeExpoUrl) {
+    return await preferStackLocalhostUrl(runtimeExpoUrl, { stackName });
+  }
+
+  const authFlow =
+    (env.HAPPY_STACKS_AUTH_FLOW ?? env.HAPPY_LOCAL_AUTH_FLOW ?? '').toString().trim() === '1' ||
+    (env.HAPPY_STACKS_DAEMON_WAIT_FOR_AUTH ?? env.HAPPY_LOCAL_DAEMON_WAIT_FOR_AUTH ?? '').toString().trim() === '1';
+
+  // Prefer the Expo web UI URL when running in dev mode.
+  // This is crucial for guided login: the browser needs the UI origin, not the server port.
+  const timeoutMsRaw =
+    (env.HAPPY_STACKS_AUTH_UI_READY_TIMEOUT_MS ?? env.HAPPY_LOCAL_AUTH_UI_READY_TIMEOUT_MS ?? '180000').toString().trim();
+  const timeoutMs = timeoutMsRaw ? Number(timeoutMsRaw) : 180_000;
+  const expoUrl = await resolveExpoWebappUrlForAuth({
+    rootDir,
+    stackName,
+    timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 180_000,
+  });
+  if (expoUrl) {
+    return await preferStackLocalhostUrl(expoUrl, { stackName });
+  }
+
+  // Fail closed for guided auth flows: falling back to server URLs opens the wrong origin.
+  if (authFlow) {
+    throw new Error(
+      `[auth] failed to resolve Expo web UI URL for guided login.\n` +
+        `[auth] Reason: Expo web UI did not become ready within ${Number.isFinite(timeoutMs) ? timeoutMs : 180_000}ms.\n` +
+        `[auth] Fix: re-run and wait for Expo to start, or run in prod mode (--start) if you want server-served UI.`
+    );
+  }
+
+  try {
+    const raw = await runCapture(
+      process.execPath,
+      [join(rootDir, 'scripts', 'stack.mjs'), 'auth', stackName, '--', 'login', '--print', '--json'],
+      {
+        cwd: rootDir,
+        env,
+      }
+    );
+    const parsed = JSON.parse(String(raw ?? '').trim());
+    const cmd = typeof parsed?.cmd === 'string' ? parsed.cmd : '';
+    const url = extractEnvVar(cmd, 'HAPPY_WEBAPP_URL');
+    return url ? await preferStackLocalhostUrl(url, { stackName }) : '';
+  } catch {
+    return '';
+  }
+}
+
+export async function guidedStackAuthLoginNow({ rootDir, stackName, env = process.env, webappUrl = null }) {
+  const resolved = (webappUrl ?? '').toString().trim() || (await resolveStackWebappUrlForAuth({ rootDir, stackName, env }));
+  if (!resolved) {
+    throw new Error('[auth] cannot start guided login: web UI URL is empty');
+  }
+
+  const skipBundleCheck = (env.HAPPY_STACKS_AUTH_SKIP_BUNDLE_CHECK ?? env.HAPPY_LOCAL_AUTH_SKIP_BUNDLE_CHECK ?? '').toString().trim() === '1';
+  // Surface common "blank page" issues (Metro resolver errors) even in quiet mode.
+  if (!skipBundleCheck) {
+    await assertExpoWebappBundlesOrThrow({ rootDir, stackName, webappUrl: resolved });
+  }
+
+  await guidedStackWebSignupThenLogin({ webappUrl: resolved, stackName });
+  await run(process.execPath, [join(rootDir, 'scripts', 'stack.mjs'), 'auth', stackName, '--', 'login'], {
+    cwd: rootDir,
+    env,
+  });
+}
+
+export async function stackAuthCopyFrom({ rootDir, stackName, fromStackName, env = process.env, link = true }) {
+  await run(
+    process.execPath,
+    [
+      join(rootDir, 'scripts', 'stack.mjs'),
+      'auth',
+      stackName,
+      '--',
+      'copy-from',
+      fromStackName,
+      ...(link ? ['--link'] : []),
+    ],
+    { cwd: rootDir, env }
+  );
+}
+

package/scripts/utils/cli/cli_registry.mjs

@@ -37,6 +37,14 @@ export function getHappysRegistry() {
       rootUsage: 'happys setup-pr --happy=<pr-url|number> [--happy-cli=<pr-url|number>] [--dev]',
       description: 'One-shot: set up + run a PR stack (maintainer-friendly)',
     },
+    {
+      name: 'review-pr',
+      aliases: ['reviewPR', 'reviewpr'],
+      kind: 'node',
+      scriptRelPath: 'scripts/review_pr.mjs',
+      rootUsage: 'happys review-pr --happy=<pr-url|number> [--happy-cli=<pr-url|number>] [--dev]',
+      description: 'Run setup-pr in a temporary sandbox (auto-cleaned)',
+    },
     {
       name: 'uninstall',
       kind: 'node',
@@ -88,6 +96,14 @@ export function getHappysRegistry() {
       rootUsage: 'happys build [-- ...]',
       description: 'Build UI bundle',
     },
+    {
+      name: 'review',
+      kind: 'node',
+      scriptRelPath: 'scripts/review.mjs',
+      rootUsage:
+        'happys review [component...] [--reviewers=coderabbit,codex] [--base-remote=<remote>] [--base-branch=<branch>] [--base-ref=<ref>] [--json]',
+      description: 'Run CodeRabbit/Codex reviews for component worktrees',
+    },
     {
       name: 'lint',
       kind: 'node',
@@ -131,6 +147,14 @@ export function getHappysRegistry() {
       rootUsage: 'happys mobile [-- ...]',
       description: 'Mobile helper (iOS)',
     },
+    {
+      name: 'mobile-dev-client',
+      aliases: ['dev-client', 'devclient'],
+      kind: 'node',
+      scriptRelPath: 'scripts/mobile_dev_client.mjs',
+      rootUsage: 'happys mobile-dev-client --install [--device=...] [--clean] [--configuration=Debug|Release] [--json]',
+      description: 'Install the shared Happy Stacks dev-client app (iOS)',
+    },
     {
       name: 'doctor',
       kind: 'node',

package/scripts/utils/cli/cwd_scope.mjs

@@ -0,0 +1,82 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+
+import { getWorktreesRoot } from '../git/worktrees.mjs';
+import { getComponentsDir } from '../paths/paths.mjs';
+
+export function getInvokedCwd(env = process.env) {
+  return String(env.HAPPY_STACKS_INVOKED_CWD ?? env.HAPPY_LOCAL_INVOKED_CWD ?? env.PWD ?? '').trim();
+}
+
+function hasGitMarker(dir) {
+  try {
+    // In a worktree, `.git` is typically a file; in the primary checkout it may be a directory.
+    return existsSync(join(dir, '.git'));
+  } catch {
+    return false;
+  }
+}
+
+function isPathInside(path, parentDir) {
+  const p = resolve(path);
+  const d = resolve(parentDir);
+  return p === d || p.startsWith(d.endsWith(sep) ? d : d + sep);
+}
+
+function findGitRoot(startDir, stopAtDir) {
+  let cur = resolve(startDir);
+  const stop = stopAtDir ? resolve(stopAtDir) : '';
+
+  while (true) {
+    if (hasGitMarker(cur)) {
+      return cur;
+    }
+    if (stop && cur === stop) {
+      return null;
+    }
+    const parent = dirname(cur);
+    if (parent === cur) {
+      return null;
+    }
+    if (stop && !isPathInside(parent, stop)) {
+      return null;
+    }
+    cur = parent;
+  }
+}
+
+export function inferComponentFromCwd({ rootDir, invokedCwd, components }) {
+  const cwd = String(invokedCwd ?? '').trim();
+  const list = Array.isArray(components) ? components : [];
+  if (!rootDir || !cwd || !list.length) {
+    return null;
+  }
+
+  const abs = resolve(cwd);
+  const componentsDir = getComponentsDir(rootDir);
+  const worktreesRoot = getWorktreesRoot(rootDir);
+
+  for (const component of list) {
+    const c = String(component ?? '').trim();
+    if (!c) continue;
+
+    const wtBase = resolve(join(worktreesRoot, c));
+    if (isPathInside(abs, wtBase)) {
+      const repoDir = findGitRoot(abs, wtBase);
+      if (repoDir) {
+        return { component: c, repoDir };
+      }
+    }
+
+    const primaryBase = resolve(join(componentsDir, c));
+    if (isPathInside(abs, primaryBase)) {
+      const repoDir = findGitRoot(abs, primaryBase);
+      if (repoDir) {
+        return { component: c, repoDir };
+      }
+    }
+  }
+
+  return null;
+}
+

package/scripts/utils/cli/cwd_scope.test.mjs

@@ -0,0 +1,77 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { inferComponentFromCwd } from './cwd_scope.mjs';
+
+async function withTempRoot(t) {
+  const dir = await mkdtemp(join(tmpdir(), 'happy-stacks-cwd-scope-'));
+  t.after(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+  return dir;
+}
+
+test('inferComponentFromCwd resolves components/<component> repo root', async (t) => {
+  const rootDir = await withTempRoot(t);
+  const prevWorkspace = process.env.HAPPY_STACKS_WORKSPACE_DIR;
+  process.env.HAPPY_STACKS_WORKSPACE_DIR = rootDir;
+  t.after(() => {
+    if (prevWorkspace == null) {
+      delete process.env.HAPPY_STACKS_WORKSPACE_DIR;
+    } else {
+      process.env.HAPPY_STACKS_WORKSPACE_DIR = prevWorkspace;
+    }
+  });
+
+  const repoRoot = join(rootDir, 'components', 'happy');
+  await mkdir(join(repoRoot, 'src'), { recursive: true });
+  await writeFile(join(repoRoot, '.git'), 'gitdir: /tmp/fake\n', 'utf-8');
+
+  const invokedCwd = join(repoRoot, 'src');
+  const inferred = inferComponentFromCwd({ rootDir, invokedCwd, components: ['happy', 'happy-cli'] });
+  assert.deepEqual(inferred, { component: 'happy', repoDir: repoRoot });
+});
+
+test('inferComponentFromCwd resolves components/.worktrees/<component>/<owner>/<branch> repo root', async (t) => {
+  const rootDir = await withTempRoot(t);
+  const prevWorkspace = process.env.HAPPY_STACKS_WORKSPACE_DIR;
+  process.env.HAPPY_STACKS_WORKSPACE_DIR = rootDir;
+  t.after(() => {
+    if (prevWorkspace == null) {
+      delete process.env.HAPPY_STACKS_WORKSPACE_DIR;
+    } else {
+      process.env.HAPPY_STACKS_WORKSPACE_DIR = prevWorkspace;
+    }
+  });
+
+  const wtRoot = join(rootDir, 'components', '.worktrees', 'happy', 'slopus', 'pr', '123-fix', 'nested');
+  await mkdir(wtRoot, { recursive: true });
+  const repoRoot = join(rootDir, 'components', '.worktrees', 'happy', 'slopus', 'pr', '123-fix');
+  await writeFile(join(repoRoot, '.git'), 'gitdir: /tmp/fake\n', 'utf-8');
+
+  const invokedCwd = join(repoRoot, 'nested');
+  const inferred = inferComponentFromCwd({ rootDir, invokedCwd, components: ['happy'] });
+  assert.deepEqual(inferred, { component: 'happy', repoDir: repoRoot });
+});
+
+test('inferComponentFromCwd returns null outside known component roots', async (t) => {
+  const rootDir = await withTempRoot(t);
+  const prevWorkspace = process.env.HAPPY_STACKS_WORKSPACE_DIR;
+  process.env.HAPPY_STACKS_WORKSPACE_DIR = rootDir;
+  t.after(() => {
+    if (prevWorkspace == null) {
+      delete process.env.HAPPY_STACKS_WORKSPACE_DIR;
+    } else {
+      process.env.HAPPY_STACKS_WORKSPACE_DIR = prevWorkspace;
+    }
+  });
+
+  const invokedCwd = join(rootDir, 'somewhere', 'else');
+  await mkdir(invokedCwd, { recursive: true });
+  const inferred = inferComponentFromCwd({ rootDir, invokedCwd, components: ['happy'] });
+  assert.equal(inferred, null);
+});
+

package/scripts/utils/cli/flags.mjs

@@ -0,0 +1,17 @@
+export function boolFromFlags({ flags, onFlag, offFlag, defaultValue }) {
+  if (flags.has(offFlag)) return false;
+  if (flags.has(onFlag)) return true;
+  return defaultValue;
+}
+
+export function boolFromFlagsOrKv({ flags, kv, onFlag, offFlag, key, defaultValue }) {
+  if (flags.has(offFlag)) return false;
+  if (flags.has(onFlag)) return true;
+  if (key && kv.has(key)) {
+    const raw = String(kv.get(key) ?? '').trim().toLowerCase();
+    if (raw === '1' || raw === 'true' || raw === 'yes' || raw === 'y') return true;
+    if (raw === '0' || raw === 'false' || raw === 'no' || raw === 'n') return false;
+  }
+  return defaultValue;
+}
+