happy-stacks 0.2.0 → 0.4.0

package/scripts/utils/proc/package_scripts.mjs

@@ -0,0 +1,31 @@
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+import { pathExists } from '../fs/fs.mjs';
+import { requirePnpm } from './pm.mjs';
+
+export async function detectPackageManagerCmd(dir) {
+  if (await pathExists(join(dir, 'yarn.lock'))) {
+    return { name: 'yarn', cmd: 'yarn', argsForScript: (script) => ['-s', script] };
+  }
+  await requirePnpm();
+  return { name: 'pnpm', cmd: 'pnpm', argsForScript: (script) => ['--silent', script] };
+}
+
+export async function readPackageJsonScripts(dir) {
+  try {
+    const raw = await readFile(join(dir, 'package.json'), 'utf-8');
+    const pkg = JSON.parse(raw);
+    const scripts = pkg?.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+    return scripts;
+  } catch {
+    return null;
+  }
+}
+
+export function pickFirstScript(scripts, candidates) {
+  if (!scripts) return null;
+  const list = Array.isArray(candidates) ? candidates : [];
+  return list.find((k) => typeof scripts[k] === 'string' && scripts[k].trim()) ?? null;
+}
+

package/scripts/utils/proc/parallel.mjs

@@ -0,0 +1,25 @@
+export async function runWithConcurrencyLimit({ items, limit, fn }) {
+  const list = Array.isArray(items) ? items : [];
+  const max = Number(limit);
+  const concurrency = Number.isFinite(max) && max > 0 ? Math.floor(max) : 4;
+
+  const results = new Array(list.length);
+  let nextIndex = 0;
+
+  const worker = async () => {
+    while (true) {
+      const i = nextIndex;
+      nextIndex += 1;
+      if (i >= list.length) return;
+      results[i] = await fn(list[i], i);
+    }
+  };
+
+  const workers = [];
+  for (let i = 0; i < Math.min(concurrency, list.length); i++) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+  return results;
+}
+

package/scripts/utils/proc/pids.mjs

@@ -0,0 +1,11 @@
+export function isPidAlive(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 1) return false;
+  try {
+    process.kill(n, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+

package/scripts/utils/{pm.mjs → proc/pm.mjs}

@@ -1,36 +1,20 @@
 import { homedir } from 'node:os';
 import { dirname, join, resolve, sep } from 'node:path';
 import { existsSync } from 'node:fs';
-import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 
-import { pathExists } from './fs.mjs';
+import { pathExists } from '../fs/fs.mjs';
+import { readJsonIfExists, writeJsonAtomic } from '../fs/json.mjs';
 import { run, runCapture, spawnProc } from './proc.mjs';
-import { getDefaultAutostartPaths, getHappyStacksHomeDir } from './paths.mjs';
-import { resolveInstalledPath, resolveInstalledCliRoot } from './runtime.mjs';
+import { commandExists } from './commands.mjs';
+import { getDefaultAutostartPaths, getHappyStacksHomeDir } from '../paths/paths.mjs';
+import { resolveInstalledPath, resolveInstalledCliRoot } from '../paths/runtime.mjs';
 
 function sha256Hex(s) {
   return createHash('sha256').update(String(s ?? ''), 'utf-8').digest('hex');
 }
 
-async function readJsonIfExists(path) {
-  try {
-    if (!path || !existsSync(path)) return null;
-    const raw = await readFile(path, 'utf-8');
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
-async function writeJsonAtomic(path, value) {
-  const dir = dirname(path);
-  await mkdir(dir, { recursive: true }).catch(() => {});
-  const tmp = join(dir, `.tmp.${Date.now()}.${Math.random().toString(16).slice(2)}.json`);
-  await writeFile(tmp, JSON.stringify(value, null, 2) + '\n', 'utf-8');
-  await rename(tmp, path);
-}
-
 function resolveBuildStatePath({ label, dir }) {
   const homeDir = getHappyStacksHomeDir();
   const key = sha256Hex(resolve(dir));
@@ -56,15 +40,6 @@ async function computeGitWorktreeSignature(dir) {
   }
 }
 
-async function commandExists(cmd, options = {}) {
-  try {
-    await runCapture(cmd, ['--version'], options);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 export async function requirePnpm() {
   if (await commandExists('pnpm')) {
     return;
@@ -138,14 +113,37 @@ export async function ensureDepsInstalled(dir, label, { quiet = false } = {}) {
       }
     };
 
+    const patchesMtimeMs = async () => {
+      // Happy's mobile app (and some other repos) use patch-package and keep patches under `patches/`.
+      // If a patch file changes but yarn.lock/package.json do not, Yarn won't reinstall and
+      // patch-package won't re-apply the patch, leading to confusing "why isn't my patch wired?"
+      // failures later (e.g. during iOS pod install).
+      const patchesDir = join(dir, 'patches');
+      if (!(await pathExists(patchesDir))) return 0;
+      try {
+        const entries = await readdir(patchesDir, { withFileTypes: true });
+        let max = 0;
+        for (const e of entries) {
+          if (!e.isFile()) continue;
+          if (!e.name.endsWith('.patch')) continue;
+          const m = await mtimeMs(join(patchesDir, e.name));
+          if (m > max) max = m;
+        }
+        return max;
+      } catch {
+        return 0;
+      }
+    };
+
     if (pm.name === 'yarn' && (await pathExists(yarnLock))) {
       const lockM = await mtimeMs(yarnLock);
       const pkgM = await mtimeMs(pkgJson);
       const intM = await mtimeMs(yarnIntegrity);
-      if (!intM || lockM > intM || pkgM > intM) {
+      const patchM = await patchesMtimeMs();
+      if (!intM || lockM > intM || pkgM > intM || patchM > intM) {
         if (!quiet) {
           // eslint-disable-next-line no-console
-          console.log(`[local] refreshing ${label} dependencies (yarn.lock/package.json changed)...`);
+          console.log(`[local] refreshing ${label} dependencies (yarn.lock/package.json/patches changed)...`);
         }
         await run(pm.cmd, ['install'], { cwd: dir, stdio });
       }
@@ -186,14 +184,20 @@ export async function ensureCliBuilt(cliDir, { buildCli }) {
   // - HAPPY_STACKS_CLI_BUILD=0 (legacy: HAPPY_LOCAL_CLI_BUILD=0)
   const modeRaw = (process.env.HAPPY_STACKS_CLI_BUILD_MODE ?? process.env.HAPPY_LOCAL_CLI_BUILD_MODE ?? 'auto').trim().toLowerCase();
   const mode = modeRaw === 'always' || modeRaw === 'auto' || modeRaw === 'never' ? modeRaw : 'auto';
-  if (mode === 'never') {
-    return { built: false, reason: 'mode_never' };
-  }
   const distEntrypoint = join(cliDir, 'dist', 'index.mjs');
   const buildStatePath = resolveBuildStatePath({ label: 'happy-cli', dir: cliDir });
   const gitSig = await computeGitWorktreeSignature(cliDir);
   const prev = await readJsonIfExists(buildStatePath);
 
+  // "never" should prevent rebuild churn, but it must not make the stack unrunnable.
+  // If the dist entrypoint is missing, build once even in "never" mode.
+  if (mode === 'never') {
+    if (await pathExists(distEntrypoint)) {
+      return { built: false, reason: 'mode_never' };
+    }
+    // fallthrough to build
+  }
+
   if (mode === 'auto') {
     // If dist doesn't exist, we must build.
     if (!(await pathExists(distEntrypoint))) {
@@ -211,6 +215,18 @@ export async function ensureCliBuilt(cliDir, { buildCli }) {
   const pm = await getComponentPm(cliDir);
   await run(pm.cmd, ['build'], { cwd: cliDir });
 
+  // Sanity check: happy-cli daemon entrypoint must exist after a successful build.
+  // Without this, watch-based rebuilds can restart the daemon into a MODULE_NOT_FOUND crash,
+  // which looks like the UI "dies out of nowhere" even though the root cause is missing build output.
+  if (!(await pathExists(distEntrypoint))) {
+    throw new Error(
+      `[local] happy-cli build finished but did not produce expected entrypoint.\n` +
+        `Expected: ${distEntrypoint}\n` +
+        `Fix: run the component build directly and inspect its output:\n` +
+        `  cd "${cliDir}" && ${pm.cmd} build`
+    );
+  }
+
   // Persist new build state (best-effort).
   const nowSig = gitSig ?? (await computeGitWorktreeSignature(cliDir));
   if (nowSig) {
@@ -258,147 +274,101 @@ HAPPYS="$BIN_DIR/happys"
 if [[ -x "$HAPPYS" ]]; then
   exec "$HAPPYS" happy "$@"
 fi
-exec happys happy "$@"
+
+# Fallback: run happy-stacks from runtime install if present.
+HOME_DIR="\${HAPPY_STACKS_HOME_DIR:-\${HAPPY_LOCAL_HOME_DIR:-$HOME/.happy-stacks}}"
+RUNTIME="$HOME_DIR/runtime/node_modules/happy-stacks/bin/happys.mjs"
+if [[ -f "$RUNTIME" ]]; then
+  exec node "$RUNTIME" happy "$@"
+fi
+
+echo "error: cannot find happys shim or runtime install" >&2
+exit 1
 `;
 
-  await writeFile(happyShim, shim, 'utf-8');
+  const writeIfChanged = async (path, text) => {
+    let existing = '';
+    try {
+      existing = await readFile(path, 'utf-8');
+    } catch {
+      existing = '';
+    }
+    if (existing === text) return false;
+    await writeFile(path, text, 'utf-8');
+    return true;
+  };
+
+  await writeIfChanged(happyShim, shim);
   await chmod(happyShim, 0o755).catch(() => {});
 
-  // eslint-disable-next-line no-console
-  console.log(`[local] installed 'happy' shim at ${happyShim}`);
-  if (!existsSync(happysShim)) {
+  // happys shim: use node + CLI root; if runtime install exists, prefer it.
+  const cliRoot = resolveInstalledCliRoot(rootDir);
+  const happysShimText = `#!/bin/bash
+set -euo pipefail
+exec node "${resolveInstalledPath(rootDir, 'bin/happys.mjs')}" "$@"
+`;
+  await writeIfChanged(happysShim, happysShimText);
+  await chmod(happysShim, 0o755).catch(() => {});
+
+  // If user’s PATH points at a legacy install path, try to make it sane (best-effort).
+  const entries = getPathEntries();
+  const legacyBin = join(homedir(), '.happy-stacks', 'bin');
+  const newBin = join(getDefaultAutostartPaths().baseDir, 'bin');
+  if (entries.some((p) => isPathInside(p, legacyBin)) && !entries.some((p) => isPathInside(p, newBin))) {
     // eslint-disable-next-line no-console
-    console.log(`[local] note: run \`happys init\` to install a stable ${happysShim} shim for services/SwiftBar.`);
+    console.log(`[local] note: your PATH includes ${legacyBin}; recommended path is ${newBin}`);
   }
-}
 
-export async function pmSpawnScript({ label, dir, script, env, options = {} }) {
-  const pm = await getComponentPm(dir);
-  if (pm.name === 'yarn') {
-    return spawnProc(label, pm.cmd, ['-s', script], env, { ...options, cwd: dir });
-  }
-  return spawnProc(label, pm.cmd, ['--silent', script], env, { ...options, cwd: dir });
+  return { ok: true, cliRoot, binDir, happyShim, happysShim };
 }
 
-export async function pmSpawnBin({ label, dir, bin, args, env, options = {} }) {
-  const pm = await getComponentPm(dir);
-  if (pm.name === 'yarn') {
-    return spawnProc(label, pm.cmd, [bin, ...args], env, { ...options, cwd: dir });
-  }
-  return spawnProc(label, pm.cmd, ['exec', bin, ...args], env, { ...options, cwd: dir });
-}
+export async function pmExecBin(dirOrOpts, binArg, argsArg, optsArg) {
+  const usesObjectStyle = typeof dirOrOpts === 'object' && dirOrOpts !== null;
 
-export async function pmExecBin({ dir, bin, args, env, quiet = false }) {
-  const pm = await getComponentPm(dir);
+  const dir = usesObjectStyle ? dirOrOpts.dir : dirOrOpts;
+  const bin = usesObjectStyle ? dirOrOpts.bin : binArg;
+  const args = usesObjectStyle ? (dirOrOpts.args ?? []) : (argsArg ?? []);
+
+  const env = usesObjectStyle ? (dirOrOpts.env ?? process.env) : (optsArg?.env ?? process.env);
+  const quiet = usesObjectStyle ? Boolean(dirOrOpts.quiet) : Boolean(optsArg?.quiet);
   const stdio = quiet ? 'ignore' : 'inherit';
+
+  const pm = await getComponentPm(dir);
   if (pm.name === 'yarn') {
-    await run(pm.cmd, [bin, ...args], { env, cwd: dir, stdio });
+    await run(pm.cmd, ['run', bin, ...args], { cwd: dir, env, stdio });
     return;
   }
-  await run(pm.cmd, ['exec', bin, ...args], { env, cwd: dir, stdio });
+  await run(pm.cmd, ['exec', bin, ...args], { cwd: dir, env, stdio });
 }
 
-export async function ensureMacAutostartEnabled({ rootDir, label = 'com.happy.local', env = {} }) {
-  if (process.platform !== 'darwin') {
-    throw new Error('[local] autostart is currently only implemented for macOS (LaunchAgents).');
-  }
+export async function pmSpawnBin(dir, label, bin, args, { env = process.env } = {}) {
+  const usesObjectStyle = typeof dir === 'object' && dir !== null;
+  const componentDir = usesObjectStyle ? dir.dir : dir;
+  const componentLabel = usesObjectStyle ? dir.label : label;
+  const componentBin = usesObjectStyle ? dir.bin : bin;
+  const componentArgs = usesObjectStyle ? (dir.args ?? []) : (args ?? []);
+  const componentEnv = usesObjectStyle ? (dir.env ?? process.env) : (env ?? process.env);
+  const options = usesObjectStyle ? (dir.options ?? {}) : {};
 
-  const {
-    logsDir,
-    stdoutPath,
-    stderrPath,
-    plistPath,
-    primaryLabel,
-    legacyLabel,
-    primaryPlistPath,
-    legacyPlistPath,
-    primaryStdoutPath,
-    primaryStderrPath,
-    legacyStdoutPath,
-    legacyStderrPath,
-  } = getDefaultAutostartPaths();
-  await mkdir(logsDir, { recursive: true });
-
-  const nodePath = process.env.HAPPY_STACKS_NODE?.trim()
-    ? process.env.HAPPY_STACKS_NODE.trim()
-    : process.env.HAPPY_LOCAL_NODE?.trim()
-      ? process.env.HAPPY_LOCAL_NODE.trim()
-      : process.execPath;
-  const installedRoot = resolveInstalledCliRoot(rootDir);
-  const happysEntrypoint = resolveInstalledPath(rootDir, join('bin', 'happys.mjs'));
-  const happysShim = join(getHappyStacksHomeDir(), 'bin', 'happys');
-  const useShim = existsSync(happysShim);
-
-  // Ensure we write to the plist path that matches the label we're installing, instead of the
-  // "active" plist path (which might be legacy and cause filename/label mismatches).
-  const resolvedPlistPath =
-    label === primaryLabel ? primaryPlistPath : label === legacyLabel ? legacyPlistPath : join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
-  const resolvedStdoutPath = label === primaryLabel ? primaryStdoutPath : label === legacyLabel ? legacyStdoutPath : stdoutPath;
-  const resolvedStderrPath = label === primaryLabel ? primaryStderrPath : label === legacyLabel ? legacyStderrPath : stderrPath;
-
-  const plist = `<?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>
-      ${useShim ? `<string>${happysShim}</string>` : `<string>${nodePath}</string>\n      <string>${happysEntrypoint}</string>`}
-      <string>start</string>
-    </array>
-    <key>WorkingDirectory</key>
-    <string>${installedRoot}</string>
-    <key>RunAtLoad</key>
-    <true/>
-    <key>KeepAlive</key>
-    <true/>
-    <key>StandardOutPath</key>
-    <string>${resolvedStdoutPath}</string>
-    <key>StandardErrorPath</key>
-    <string>${resolvedStderrPath}</string>
-    <key>EnvironmentVariables</key>
-    <dict>
-${Object.entries(env)
-  .map(([k, v]) => `      <key>${k}</key>\n      <string>${String(v)}</string>`)
-  .join('\n')}
-    </dict>
-  </dict>
-</plist>
-`;
-
-  await mkdir(dirname(resolvedPlistPath), { recursive: true });
-  await writeFile(resolvedPlistPath, plist, 'utf-8');
-
-  // Best-effort (works on most macOS setups). If it fails, the plist still exists and can be loaded manually.
-  try {
-    await run('launchctl', ['unload', '-w', resolvedPlistPath]);
-  } catch {
-    // ignore
+  const pm = await getComponentPm(componentDir);
+  if (pm.name === 'yarn') {
+    return spawnProc(componentLabel, pm.cmd, ['run', componentBin, ...componentArgs], componentEnv, { cwd: componentDir, ...options });
   }
-  await run('launchctl', ['load', '-w', resolvedPlistPath]);
+  return spawnProc(componentLabel, pm.cmd, ['exec', componentBin, ...componentArgs], componentEnv, { cwd: componentDir, ...options });
 }
 
-export async function ensureMacAutostartDisabled({ label = 'com.happy.local' }) {
-  if (process.platform !== 'darwin') {
-    return;
-  }
-  const { primaryLabel, legacyLabel, primaryPlistPath, legacyPlistPath } = getDefaultAutostartPaths();
-  const resolvedPlistPath =
-    label === primaryLabel ? primaryPlistPath : label === legacyLabel ? legacyPlistPath : join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
-  try {
-    await run('launchctl', ['unload', '-w', resolvedPlistPath]);
-  } catch {
-    // Old-style unload can fail on newer macOS; fall back to modern bootout.
-    try {
-      const uid = typeof process.getuid === 'function' ? process.getuid() : null;
-      if (uid != null) {
-        await run('launchctl', ['bootout', `gui/${uid}/${label}`]);
-      }
-    } catch {
-      // ignore
-    }
+export async function pmSpawnScript(dir, label, script, args, { env = process.env } = {}) {
+  const usesObjectStyle = typeof dir === 'object' && dir !== null;
+  const componentDir = usesObjectStyle ? dir.dir : dir;
+  const componentLabel = usesObjectStyle ? dir.label : label;
+  const componentScript = usesObjectStyle ? dir.script : script;
+  const componentArgs = usesObjectStyle ? (dir.args ?? []) : (args ?? []);
+  const componentEnv = usesObjectStyle ? (dir.env ?? process.env) : (env ?? process.env);
+  const options = usesObjectStyle ? (dir.options ?? {}) : {};
+
+  const pm = await getComponentPm(componentDir);
+  if (pm.name === 'yarn') {
+    return spawnProc(componentLabel, pm.cmd, ['run', componentScript, ...componentArgs], componentEnv, { cwd: componentDir, ...options });
   }
-  // eslint-disable-next-line no-console
-  console.log(`[local] autostart disabled (${label})`);
+  return spawnProc(componentLabel, pm.cmd, ['run', componentScript, ...componentArgs], componentEnv, { cwd: componentDir, ...options });
 }

package/scripts/utils/{proc.mjs → proc/proc.mjs}

@@ -1,13 +1,27 @@
 import { spawn } from 'node:child_process';
 
+function nextLineBreakIndex(s) {
+  const n = s.indexOf('\n');
+  const r = s.indexOf('\r');
+  if (n < 0) return r;
+  if (r < 0) return n;
+  return Math.min(n, r);
+}
+
+function consumeLineBreak(buf) {
+  if (buf.startsWith('\r\n')) return buf.slice(2);
+  if (buf.startsWith('\n') || buf.startsWith('\r')) return buf.slice(1);
+  return buf;
+}
+
 function writeWithPrefix(stream, prefix, bufState, chunk) {
   const s = chunk.toString();
   bufState.buf += s;
   while (true) {
-    const idx = bufState.buf.indexOf('\n');
+    const idx = nextLineBreakIndex(bufState.buf);
     if (idx < 0) break;
     const line = bufState.buf.slice(0, idx);
-    bufState.buf = bufState.buf.slice(idx + 1);
+    bufState.buf = consumeLineBreak(bufState.buf.slice(idx));
     stream.write(`${prefix}${line}\n`);
   }
 }
@@ -132,3 +146,64 @@ export async function runCapture(cmd, args, options = {}) {
     });
   });
 }
+
+export async function runCaptureResult(cmd, args, options = {}) {
+  const { timeoutMs, ...spawnOptions } = options ?? {};
+  const startedAt = Date.now();
+  return await new Promise((resolvePromise) => {
+    const proc = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], shell: false, ...spawnOptions });
+    let out = '';
+    let err = '';
+    const t =
+      Number.isFinite(timeoutMs) && timeoutMs > 0
+        ? setTimeout(() => {
+            try {
+              proc.kill('SIGKILL');
+            } catch {
+              // ignore
+            }
+            resolvePromise({
+              ok: false,
+              exitCode: null,
+              signal: null,
+              out,
+              err,
+              timedOut: true,
+              startedAt,
+              finishedAt: Date.now(),
+              durationMs: Date.now() - startedAt,
+            });
+          }, timeoutMs)
+        : null;
+    proc.stdout?.on('data', (d) => (out += d.toString()));
+    proc.stderr?.on('data', (d) => (err += d.toString()));
+    proc.on('error', (e) => {
+      if (t) clearTimeout(t);
+      resolvePromise({
+        ok: false,
+        exitCode: null,
+        signal: null,
+        out,
+        err: err + (err.endsWith('\n') || !err ? '' : '\n') + String(e) + '\n',
+        timedOut: false,
+        startedAt,
+        finishedAt: Date.now(),
+        durationMs: Date.now() - startedAt,
+      });
+    });
+    proc.on('close', (code, signal) => {
+      if (t) clearTimeout(t);
+      resolvePromise({
+        ok: code === 0,
+        exitCode: code,
+        signal: signal ?? null,
+        out,
+        err,
+        timedOut: false,
+        startedAt,
+        finishedAt: Date.now(),
+        durationMs: Date.now() - startedAt,
+      });
+    });
+  });
+}

package/scripts/utils/review/base_ref.mjs

@@ -0,0 +1,74 @@
+import { inferRemoteNameForOwner, parseGithubOwner } from '../git/worktrees.mjs';
+import { gitCapture, gitOk, normalizeRemoteName, resolveRemoteDefaultBranch, ensureRemoteRefAvailable } from '../git/git.mjs';
+
+async function currentBranchName({ cwd }) {
+  const branch = (await gitCapture({ cwd, args: ['branch', '--show-current'] }).catch(() => '')).trim();
+  return branch;
+}
+
+function branchOwnerPrefix(branch) {
+  const b = String(branch ?? '').trim();
+  if (!b || !b.includes('/')) return '';
+  return b.split('/')[0] ?? '';
+}
+
+async function inferRemoteFromBranchOwner({ cwd }) {
+  const branch = await currentBranchName({ cwd });
+  const owner = branchOwnerPrefix(branch);
+  if (!owner) return '';
+
+  // Confirm this "owner" is plausible (matches at least one remote's GitHub owner).
+  for (const remoteName of ['upstream', 'origin', 'fork']) {
+    try {
+      const url = (await gitCapture({ cwd, args: ['remote', 'get-url', remoteName] })).trim();
+      const parsedOwner = parseGithubOwner(url);
+      if (parsedOwner && parsedOwner === owner) {
+        return remoteName;
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  // Fall back to the generic inference helper (it checks remotes in priority order).
+  return await inferRemoteNameForOwner({ repoDir: cwd, owner });
+}
+
+export async function resolveBaseRef({
+  cwd,
+  baseRefOverride = '',
+  baseRemoteOverride = '',
+  baseBranchOverride = '',
+  stackRemoteFallback = '',
+} = {}) {
+  const repoDir = String(cwd ?? '').trim();
+  if (!repoDir) {
+    throw new Error('[review] missing cwd for base resolution');
+  }
+
+  if (!(await gitOk({ cwd: repoDir, args: ['rev-parse', '--is-inside-work-tree'] }))) {
+    throw new Error(`[review] not a git repository: ${repoDir}`);
+  }
+
+  const explicitRef = String(baseRefOverride ?? '').trim();
+  if (explicitRef) {
+    return { baseRef: explicitRef, remote: '', branch: '' };
+  }
+
+  const stackFallback = String(stackRemoteFallback ?? '').trim();
+  const inferredRemote = await inferRemoteFromBranchOwner({ cwd: repoDir });
+  const rawRemote = String(baseRemoteOverride ?? '').trim() || inferredRemote || stackFallback || 'upstream';
+  const remote = await normalizeRemoteName({ cwd: repoDir, remote: rawRemote });
+
+  const branch = String(baseBranchOverride ?? '').trim() || (await resolveRemoteDefaultBranch({ cwd: repoDir, remote }));
+  const ok = await ensureRemoteRefAvailable({ cwd: repoDir, remote, branch });
+  if (!ok) {
+    throw new Error(
+      `[review] unable to resolve base ref refs/remotes/${remote}/${branch} in ${repoDir}\n` +
+        `[review] hint: ensure remote "${remote}" exists and has a configured HEAD/default branch (or pass --base-ref).`
+    );
+  }
+
+  return { baseRef: `${remote}/${branch}`, remote, branch };
+}
+

package/scripts/utils/review/base_ref.test.mjs

@@ -0,0 +1,54 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runCapture } from '../proc/proc.mjs';
+import { resolveBaseRef } from './base_ref.mjs';
+
+async function runGit(cwd, args) {
+  await runCapture('git', args, { cwd });
+}
+
+async function makeRepoWithRemoteHead() {
+  const root = await mkdtemp(join(tmpdir(), 'hs-review-base-ref-'));
+  const remote = join(root, 'remote.git');
+  const local = join(root, 'local');
+
+  await runGit(root, ['init', '--bare', remote]);
+  await runGit(root, ['init', '-b', 'main', local]);
+  await runGit(local, ['config', 'user.email', 'test@example.com']);
+  await runGit(local, ['config', 'user.name', 'Test User']);
+  await writeFile(join(local, 'file.txt'), 'hello\n', 'utf-8');
+  await runGit(local, ['add', '.']);
+  await runGit(local, ['commit', '-m', 'initial']);
+  await runGit(local, ['remote', 'add', 'upstream', remote]);
+  await runGit(local, ['push', '-u', 'upstream', 'main']);
+  // Ensure refs/remotes/upstream/HEAD exists.
+  await runGit(local, ['remote', 'set-head', 'upstream', '--auto']);
+
+  return { root, local };
+}
+
+test('resolveBaseRef uses explicit --base-ref override', async () => {
+  const { root, local } = await makeRepoWithRemoteHead();
+  try {
+    const res = await resolveBaseRef({ cwd: local, baseRefOverride: 'upstream/main' });
+    assert.equal(res.baseRef, 'upstream/main');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('resolveBaseRef infers default branch from refs/remotes/<remote>/HEAD', async () => {
+  const { root, local } = await makeRepoWithRemoteHead();
+  try {
+    const res = await resolveBaseRef({ cwd: local, baseRemoteOverride: 'upstream' });
+    assert.equal(res.baseRef, 'upstream/main');
+    assert.equal(res.remote, 'upstream');
+    assert.equal(res.branch, 'main');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+