happy-stacks 0.3.0 → 0.4.0

package/scripts/utils/dev/expo_dev.test.mjs

@@ -0,0 +1,76 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildExpoStartArgs, resolveExpoDevHost } from './expo_dev.mjs';
+
+test('resolveExpoDevHost defaults to lan and normalizes values', () => {
+  assert.equal(resolveExpoDevHost({ env: {} }), 'lan');
+  assert.equal(resolveExpoDevHost({ env: { HAPPY_STACKS_EXPO_HOST: 'LAN' } }), 'lan');
+  assert.equal(resolveExpoDevHost({ env: { HAPPY_STACKS_EXPO_HOST: 'localhost' } }), 'localhost');
+  assert.equal(resolveExpoDevHost({ env: { HAPPY_STACKS_EXPO_HOST: 'tunnel' } }), 'tunnel');
+  assert.equal(resolveExpoDevHost({ env: { HAPPY_STACKS_EXPO_HOST: 'nope' } }), 'lan');
+});
+
+test('buildExpoStartArgs builds dev-client args (preferred when mobile enabled)', () => {
+  const args = buildExpoStartArgs({
+    port: 8081,
+    host: 'lan',
+    wantWeb: true,
+    wantDevClient: true,
+    scheme: 'happy',
+    clearCache: true,
+  });
+  assert.deepEqual(args, ['start', '--dev-client', '--host', 'lan', '--port', '8081', '--scheme', 'happy', '--clear']);
+});
+
+test('buildExpoStartArgs builds web args when dev-client is not requested', () => {
+  const args = buildExpoStartArgs({
+    port: 8081,
+    host: 'lan',
+    wantWeb: true,
+    wantDevClient: false,
+    scheme: '',
+    clearCache: false,
+  });
+  assert.deepEqual(args, ['start', '--web', '--host', 'lan', '--port', '8081']);
+});
+
+test('buildExpoStartArgs omits --scheme when empty', () => {
+  const args = buildExpoStartArgs({
+    port: 8081,
+    host: 'lan',
+    wantWeb: false,
+    wantDevClient: true,
+    scheme: '',
+    clearCache: false,
+  });
+  assert.deepEqual(args, ['start', '--dev-client', '--host', 'lan', '--port', '8081']);
+});
+
+test('buildExpoStartArgs throws on invalid requests', () => {
+  assert.throws(
+    () =>
+      buildExpoStartArgs({
+        port: 0,
+        host: 'lan',
+        wantWeb: true,
+        wantDevClient: false,
+        scheme: '',
+        clearCache: false,
+      }),
+    /invalid Metro port/i
+  );
+  assert.throws(
+    () =>
+      buildExpoStartArgs({
+        port: 8081,
+        host: 'lan',
+        wantWeb: false,
+        wantDevClient: false,
+        scheme: '',
+        clearCache: false,
+      }),
+    /neither web nor dev-client requested/i
+  );
+});
+

package/scripts/utils/dev/server.mjs

@@ -7,36 +7,26 @@ import { isTcpPortFree, pickNextFreeTcpPort } from '../net/ports.mjs';
 import { readStackRuntimeStateFile, recordStackRuntimeUpdate } from '../stack/runtime_state.mjs';
 import { killProcessGroupOwnedByStack } from '../proc/ownership.mjs';
 import { watchDebounced } from '../proc/watch.mjs';
-
-function hashStringToInt(s) {
-  let h = 0;
-  const str = String(s ?? '');
-  for (let i = 0; i < str.length; i++) {
-    h = (h * 31 + str.charCodeAt(i)) >>> 0;
-  }
-  return h >>> 0;
-}
+import { pickMetroPort, resolveStablePortStart } from '../expo/metro_ports.mjs';
 
 export function resolveStackUiDevPortStart({ env = process.env, stackName }) {
-  const baseRaw = (env.HAPPY_STACKS_UI_DEV_PORT_BASE ?? env.HAPPY_LOCAL_UI_DEV_PORT_BASE ?? '8081').toString().trim();
-  const rangeRaw = (env.HAPPY_STACKS_UI_DEV_PORT_RANGE ?? env.HAPPY_LOCAL_UI_DEV_PORT_RANGE ?? '1000').toString().trim();
-  const base = Number(baseRaw);
-  const range = Number(rangeRaw);
-  const b = Number.isFinite(base) ? base : 8081;
-  const r = Number.isFinite(range) && range > 0 ? range : 1000;
-  return b + (hashStringToInt(stackName) % r);
+  return resolveStablePortStart({
+    env: {
+      ...env,
+      HAPPY_STACKS_UI_DEV_PORT_BASE: (env.HAPPY_STACKS_UI_DEV_PORT_BASE ?? env.HAPPY_LOCAL_UI_DEV_PORT_BASE ?? '8081').toString(),
+      HAPPY_STACKS_UI_DEV_PORT_RANGE: (env.HAPPY_STACKS_UI_DEV_PORT_RANGE ?? env.HAPPY_LOCAL_UI_DEV_PORT_RANGE ?? '1000').toString(),
+    },
+    stackName,
+    baseKey: 'HAPPY_STACKS_UI_DEV_PORT_BASE',
+    rangeKey: 'HAPPY_STACKS_UI_DEV_PORT_RANGE',
+    defaultBase: 8081,
+    defaultRange: 1000,
+  });
 }
 
 export async function pickDevMetroPort({ startPort, reservedPorts = new Set(), host = '127.0.0.1' } = {}) {
-  const forcedRaw = (process.env.HAPPY_STACKS_UI_DEV_PORT ?? process.env.HAPPY_LOCAL_UI_DEV_PORT ?? '').toString().trim();
-  if (forcedRaw) {
-    const forced = Number(forcedRaw);
-    if (Number.isFinite(forced) && forced > 0) {
-      const ok = await isTcpPortFree(forced, { host });
-      if (ok) return forced;
-    }
-  }
-  return await pickNextFreeTcpPort(startPort, { reservedPorts, host });
+  const forcedPort = (process.env.HAPPY_STACKS_UI_DEV_PORT ?? process.env.HAPPY_LOCAL_UI_DEV_PORT ?? '').toString().trim();
+  return await pickMetroPort({ startPort, forcedPort, reservedPorts, host });
 }
 
 export async function startDevServer({

package/scripts/utils/dev_auth_key.mjs

@@ -0,0 +1,169 @@
+import { chmod, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { expandHome } from './paths/canonical_home.mjs';
+
+export function resolveHappyStacksHomeDir(env = process.env) {
+  const fromEnv = (env.HAPPY_STACKS_HOME_DIR ?? env.HAPPY_LOCAL_HOME_DIR ?? '').toString().trim();
+  return fromEnv ? expandHome(fromEnv) : join(homedir(), '.happy-stacks');
+}
+
+export function getDevAuthKeyPath(env = process.env) {
+  return join(resolveHappyStacksHomeDir(env), 'keys', 'dev-auth.json');
+}
+
+function base64UrlToBytes(s) {
+  try {
+    const raw = String(s ?? '').trim();
+    if (!raw) return null;
+    const b64 = raw.replace(/-/g, '+').replace(/_/g, '/');
+    const pad = b64.length % 4 === 0 ? '' : '='.repeat(4 - (b64.length % 4));
+    return new Uint8Array(Buffer.from(b64 + pad, 'base64'));
+  } catch {
+    return null;
+  }
+}
+
+function bytesToBase64Url(bytes) {
+  const b64 = Buffer.from(bytes).toString('base64');
+  return b64.replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+
+// Base32 alphabet (RFC 4648)
+const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+
+function bytesToBase32(bytes) {
+  let result = '';
+  let buffer = 0;
+  let bufferLength = 0;
+
+  for (const byte of bytes) {
+    buffer = (buffer << 8) | byte;
+    bufferLength += 8;
+    while (bufferLength >= 5) {
+      bufferLength -= 5;
+      result += BASE32_ALPHABET[(buffer >> bufferLength) & 0x1f];
+    }
+  }
+  if (bufferLength > 0) {
+    result += BASE32_ALPHABET[(buffer << (5 - bufferLength)) & 0x1f];
+  }
+  return result;
+}
+
+function base32ToBytes(base32) {
+  let normalized = String(base32 ?? '')
+    .toUpperCase()
+    .replace(/0/g, 'O')
+    .replace(/1/g, 'I')
+    .replace(/8/g, 'B')
+    .replace(/9/g, 'G');
+  const cleaned = normalized.replace(/[^A-Z2-7]/g, '');
+  if (!cleaned) throw new Error('no valid base32 characters');
+
+  const bytes = [];
+  let buffer = 0;
+  let bufferLength = 0;
+  for (const char of cleaned) {
+    const value = BASE32_ALPHABET.indexOf(char);
+    if (value === -1) throw new Error('invalid base32 character');
+    buffer = (buffer << 5) | value;
+    bufferLength += 5;
+    if (bufferLength >= 8) {
+      bufferLength -= 8;
+      bytes.push((buffer >> bufferLength) & 0xff);
+    }
+  }
+  return new Uint8Array(bytes);
+}
+
+export function normalizeDevAuthKeyInputToBytes(input) {
+  const raw = String(input ?? '').trim();
+  if (!raw) return null;
+
+  // Match Happy UI behavior:
+  // - backup format is base32 and is long (usually grouped with '-' / spaces)
+  // - base64url is short (~43 chars) and may contain '-' / '_' legitimately
+  //
+  // Key point: avoid mis-parsing backup base32 as base64.
+  if (raw.length > 50) {
+    try {
+      const b32 = base32ToBytes(raw);
+      return b32.length === 32 ? b32 : null;
+    } catch {
+      return null;
+    }
+  }
+
+  const b64 = base64UrlToBytes(raw);
+  if (b64 && b64.length === 32) return b64;
+  try {
+    const b32 = base32ToBytes(raw);
+    return b32.length === 32 ? b32 : null;
+  } catch {
+    return null;
+  }
+}
+
+export function formatDevAuthKeyBackup(secretKeyBase64Url) {
+  const bytes = base64UrlToBytes(secretKeyBase64Url);
+  if (!bytes || bytes.length !== 32) throw new Error('invalid secret key (expected base64url 32 bytes)');
+  const base32 = bytesToBase32(bytes);
+  const groups = [];
+  for (let i = 0; i < base32.length; i += 5) groups.push(base32.slice(i, i + 5));
+  return groups.join('-');
+}
+
+export async function readDevAuthKey({ env = process.env } = {}) {
+  if ((env.HAPPY_STACKS_DEV_AUTH_SECRET_KEY ?? '').toString().trim()) {
+    const bytes = normalizeDevAuthKeyInputToBytes(env.HAPPY_STACKS_DEV_AUTH_SECRET_KEY);
+    if (!bytes) return { ok: false, error: 'invalid_env_key', source: 'env', secretKeyBase64Url: null, backup: null };
+    const base64url = bytesToBase64Url(bytes);
+    return { ok: true, source: 'env:HAPPY_STACKS_DEV_AUTH_SECRET_KEY', secretKeyBase64Url: base64url, backup: formatDevAuthKeyBackup(base64url) };
+  }
+
+  const path = getDevAuthKeyPath(env);
+  try {
+    if (!existsSync(path)) return { ok: true, source: `file:${path}`, secretKeyBase64Url: null, backup: null, path };
+    const raw = await readFile(path, 'utf-8');
+    const parsed = JSON.parse(raw);
+    const input = parsed?.secretKeyBase64Url ?? parsed?.secretKey ?? parsed?.key ?? null;
+    const bytes = normalizeDevAuthKeyInputToBytes(input);
+    if (!bytes) return { ok: false, error: 'invalid_file_key', source: `file:${path}`, secretKeyBase64Url: null, backup: null, path };
+    const base64url = bytesToBase64Url(bytes);
+    return { ok: true, source: `file:${path}`, secretKeyBase64Url: base64url, backup: formatDevAuthKeyBackup(base64url), path };
+  } catch (e) {
+    return { ok: false, error: 'failed_to_read', source: `file:${path}`, secretKeyBase64Url: null, backup: null, path, details: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+export async function writeDevAuthKey({ env = process.env, input } = {}) {
+  const bytes = normalizeDevAuthKeyInputToBytes(input);
+  if (!bytes || bytes.length !== 32) {
+    throw new Error('invalid secret key (expected 32 bytes; accept base64url or backup format)');
+  }
+  const secretKeyBase64Url = bytesToBase64Url(bytes);
+  const path = getDevAuthKeyPath(env);
+  await mkdir(dirname(path), { recursive: true });
+  const payload = {
+    v: 1,
+    createdAt: new Date().toISOString(),
+    secretKeyBase64Url,
+  };
+  await writeFile(path, JSON.stringify(payload, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+  await chmod(path, 0o600).catch(() => {});
+  return { ok: true, path, secretKeyBase64Url, backup: formatDevAuthKeyBackup(secretKeyBase64Url) };
+}
+
+export async function clearDevAuthKey({ env = process.env } = {}) {
+  const path = getDevAuthKeyPath(env);
+  try {
+    if (!existsSync(path)) return { ok: true, deleted: false, path };
+    await unlink(path);
+    return { ok: true, deleted: true, path };
+  } catch (e) {
+    return { ok: false, deleted: false, path, error: e instanceof Error ? e.message : String(e) };
+  }
+}

package/scripts/utils/expo/command.mjs

@@ -0,0 +1,52 @@
+import { ensureDepsInstalled, pmExecBin, pmSpawnBin } from '../proc/pm.mjs';
+import { ensureExpoIsolationEnv, getExpoStatePaths, wantsExpoClearCache } from './expo.mjs';
+
+export async function prepareExpoCommandEnv({
+  baseDir,
+  kind,
+  projectDir,
+  baseEnv,
+  stateFileName,
+}) {
+  const env = { ...(baseEnv ?? process.env) };
+  const paths = getExpoStatePaths({ baseDir, kind, projectDir, stateFileName });
+  await ensureExpoIsolationEnv({ env, stateDir: paths.stateDir, expoHomeDir: paths.expoHomeDir, tmpDir: paths.tmpDir });
+  return { env, paths };
+}
+
+export function maybeAddExpoClear({ args, env }) {
+  const next = [...(args ?? [])];
+  if (wantsExpoClearCache({ env: env ?? process.env })) {
+    // Expo supports `--clear` for start, and `-c` for export.
+    // Callers should pass the right flag for their subcommand; we only add when missing.
+    if (!next.includes('--clear') && !next.includes('-c')) {
+      // Prefer `--clear` as a safe default; callers can override per-command.
+      next.push('--clear');
+    }
+  }
+  return next;
+}
+
+export async function expoExec({
+  dir,
+  args,
+  env,
+  ensureDepsLabel = 'happy',
+  quiet = false,
+}) {
+  await ensureDepsInstalled(dir, ensureDepsLabel, { quiet });
+  await pmExecBin({ dir, bin: 'expo', args, env, quiet });
+}
+
+export async function expoSpawn({
+  label,
+  dir,
+  args,
+  env,
+  ensureDepsLabel = 'happy',
+  options,
+}) {
+  await ensureDepsInstalled(dir, ensureDepsLabel);
+  return await pmSpawnBin({ label, dir, bin: 'expo', args, env, options });
+}
+

package/scripts/utils/expo/expo.mjs

@@ -4,6 +4,7 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { isPidAlive } from '../proc/pids.mjs';
+import { isTcpPortFree } from '../net/ports.mjs';
 
 export { isPidAlive };
 
@@ -63,7 +64,25 @@ export async function isStateProcessRunning(statePath) {
   const state = await readPidState(statePath);
   if (!state) return { running: false, state: null };
   const pid = Number(state.pid);
-  return { running: isPidAlive(pid), state };
+  if (isPidAlive(pid)) {
+    return { running: true, state, reason: 'pid' };
+  }
+
+  // Expo/Metro can sometimes be “up” even if the original wrapper pid exited (pm/yarn layers).
+  // If we have a port and something is listening on it, treat it as running.
+  const port = Number(state?.port);
+  if (Number.isFinite(port) && port > 0) {
+    try {
+      const free = await isTcpPortFree(port, { host: '127.0.0.1' });
+      if (!free) {
+        return { running: true, state, reason: 'port' };
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  return { running: false, state };
 }
 
 export async function writePidState(statePath, state) {

package/scripts/utils/expo/metro_ports.mjs

@@ -0,0 +1,114 @@
+import { isTcpPortFree, pickNextFreeTcpPort } from '../net/ports.mjs';
+
+function hashStringToInt(s) {
+  let h = 0;
+  const str = String(s ?? '');
+  for (let i = 0; i < str.length; i++) {
+    h = (h * 31 + str.charCodeAt(i)) >>> 0;
+  }
+  return h >>> 0;
+}
+
+function coercePositiveInt(v) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+export function resolveStablePortStart({
+  env = process.env,
+  stackName,
+  baseKey,
+  rangeKey,
+  defaultBase,
+  defaultRange,
+}) {
+  const baseRaw = (env[baseKey] ?? '').toString().trim();
+  const rangeRaw = (env[rangeKey] ?? '').toString().trim();
+  const base = coercePositiveInt(baseRaw) ?? defaultBase;
+  const range = coercePositiveInt(rangeRaw) ?? defaultRange;
+  return base + (hashStringToInt(stackName) % range);
+}
+
+export async function pickMetroPort({
+  startPort,
+  forcedPort,
+  reservedPorts = new Set(),
+  host = '127.0.0.1',
+} = {}) {
+  const forced = coercePositiveInt(forcedPort);
+  if (forced) {
+    const ok = await isTcpPortFree(forced, { host });
+    if (ok) return forced;
+  }
+  return await pickNextFreeTcpPort(startPort, { reservedPorts, host });
+}
+
+export function wantsStablePortStrategy({ env = process.env, strategyKey, legacyStrategyKey } = {}) {
+  const raw = (env[strategyKey] ?? env[legacyStrategyKey] ?? 'ephemeral').toString().trim() || 'ephemeral';
+  return raw === 'stable';
+}
+
+export async function pickUiDevMetroPort({
+  env = process.env,
+  stackMode,
+  stackName,
+  reservedPorts = new Set(),
+  host = '127.0.0.1',
+} = {}) {
+  // Legacy alias: UI dev Metro is now the unified Expo dev server port.
+  return await pickExpoDevMetroPort({ env, stackMode, stackName, reservedPorts, host });
+}
+
+export async function pickMobileDevMetroPort({
+  env = process.env,
+  stackMode,
+  stackName,
+  reservedPorts = new Set(),
+  host = '127.0.0.1',
+} = {}) {
+  // Legacy alias: mobile dev Metro is now the unified Expo dev server port.
+  return await pickExpoDevMetroPort({ env, stackMode, stackName, reservedPorts, host });
+}
+
+export async function pickExpoDevMetroPort({
+  env = process.env,
+  stackMode,
+  stackName,
+  reservedPorts = new Set(),
+  host = '127.0.0.1',
+} = {}) {
+  const forcedPort =
+    (env.HAPPY_STACKS_EXPO_DEV_PORT ??
+      env.HAPPY_LOCAL_EXPO_DEV_PORT ??
+      // Back-compat: older knobs.
+      env.HAPPY_STACKS_UI_DEV_PORT ??
+      env.HAPPY_LOCAL_UI_DEV_PORT ??
+      env.HAPPY_STACKS_MOBILE_DEV_PORT ??
+      env.HAPPY_LOCAL_MOBILE_DEV_PORT ??
+      env.HAPPY_STACKS_MOBILE_PORT ??
+      env.HAPPY_LOCAL_MOBILE_PORT ??
+      '')
+      .toString()
+      .trim() || '';
+
+  const stable =
+    stackMode &&
+    wantsStablePortStrategy({
+      env,
+      strategyKey: 'HAPPY_STACKS_EXPO_DEV_PORT_STRATEGY',
+      legacyStrategyKey: 'HAPPY_LOCAL_EXPO_DEV_PORT_STRATEGY',
+    });
+  const startPort = stable
+    ? resolveStablePortStart({
+        env,
+        stackName,
+        baseKey: 'HAPPY_STACKS_EXPO_DEV_PORT_BASE',
+        rangeKey: 'HAPPY_STACKS_EXPO_DEV_PORT_RANGE',
+        defaultBase: 8081,
+        defaultRange: 1000,
+      })
+    : 8081;
+
+  return await pickMetroPort({ startPort, forcedPort, reservedPorts, host });
+}
+

package/scripts/utils/git/git.mjs

@@ -0,0 +1,67 @@
+import { runCapture } from '../proc/proc.mjs';
+
+export async function gitCapture({ cwd, args }) {
+  return String(await runCapture('git', args, { cwd }));
+}
+
+export async function gitOk({ cwd, args }) {
+  try {
+    await runCapture('git', args, { cwd });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function normalizeRemoteName({ cwd, remote }) {
+  const want = String(remote ?? '').trim();
+  if (!want) return want;
+
+  if (await gitOk({ cwd, args: ['remote', 'get-url', want] })) return want;
+
+  // Treat origin/fork as interchangeable if one exists.
+  if (want === 'origin' && (await gitOk({ cwd, args: ['remote', 'get-url', 'fork'] }))) return 'fork';
+  if (want === 'fork' && (await gitOk({ cwd, args: ['remote', 'get-url', 'origin'] }))) return 'origin';
+
+  return want;
+}
+
+export async function resolveRemoteDefaultBranch({ cwd, remote }) {
+  const r = String(remote ?? '').trim();
+  if (!r) return 'main';
+
+  // Prefer refs/remotes/<remote>/HEAD when available.
+  try {
+    const headRef = (await gitCapture({ cwd, args: ['symbolic-ref', '-q', '--short', `refs/remotes/${r}/HEAD`] })).trim();
+    if (headRef.startsWith(`${r}/`)) {
+      return headRef.slice(r.length + 1);
+    }
+  } catch {
+    // ignore
+  }
+
+  // Fallback: parse `git remote show` output.
+  try {
+    const out = await gitCapture({ cwd, args: ['remote', 'show', r] });
+    for (const line of out.split('\n')) {
+      const m = line.match(/^\s*HEAD branch:\s*(.+)\s*$/);
+      if (m?.[1]) return m[1].trim();
+    }
+  } catch {
+    // ignore
+  }
+
+  return 'main';
+}
+
+export async function ensureRemoteRefAvailable({ cwd, remote, branch }) {
+  const r = String(remote ?? '').trim();
+  const b = String(branch ?? '').trim();
+  if (!r || !b) return false;
+  const ref = `refs/remotes/${r}/${b}`;
+  if (await gitOk({ cwd, args: ['show-ref', '--verify', '--quiet', ref] })) return true;
+  // Best-effort fetch of the default branch.
+  await gitCapture({ cwd, args: ['fetch', '--quiet', r, b] }).catch(() => '');
+  return await gitOk({ cwd, args: ['show-ref', '--verify', '--quiet', ref] });
+}
+

package/scripts/utils/git/worktrees.mjs

@@ -15,28 +15,28 @@ export function parseGithubOwner(remoteUrl) {
   return m?.groups?.owner ?? null;
 }
 
-export function getWorktreesRoot(rootDir) {
-  return join(getComponentsDir(rootDir), '.worktrees');
+export function getWorktreesRoot(rootDir, env = process.env) {
+  return join(getComponentsDir(rootDir, env), '.worktrees');
 }
 
-export function componentRepoDir(rootDir, component) {
-  return join(getComponentsDir(rootDir), component);
+export function componentRepoDir(rootDir, component, env = process.env) {
+  return join(getComponentsDir(rootDir, env), component);
 }
 
-export function isComponentWorktreePath({ rootDir, component, dir }) {
+export function isComponentWorktreePath({ rootDir, component, dir, env = process.env }) {
   const raw = String(dir ?? '').trim();
   if (!raw) return false;
   const abs = resolve(raw);
-  const root = resolve(join(getWorktreesRoot(rootDir), component)) + '/';
+  const root = resolve(join(getWorktreesRoot(rootDir, env), component)) + '/';
   return abs.startsWith(root);
 }
 
-export function worktreeSpecFromDir({ rootDir, component, dir }) {
+export function worktreeSpecFromDir({ rootDir, component, dir, env = process.env }) {
   const raw = String(dir ?? '').trim();
   if (!raw) return null;
-  if (!isComponentWorktreePath({ rootDir, component, dir: raw })) return null;
+  if (!isComponentWorktreePath({ rootDir, component, dir: raw, env })) return null;
   const abs = resolve(raw);
-  const root = resolve(join(getWorktreesRoot(rootDir), component)) + '/';
+  const root = resolve(join(getWorktreesRoot(rootDir, env), component)) + '/';
   const rel = abs.slice(root.length).split('/').filter(Boolean);
   if (rel.length < 2) return null;
   // rel = [owner, ...branchParts]
@@ -69,17 +69,18 @@ export async function createWorktreeFromBaseWorktree({
   baseWorktreeSpec,
   remoteName = 'upstream',
   depsMode = '',
+  env = process.env,
 }) {
   const args = ['wt', 'new', component, slug, `--remote=${remoteName}`, `--base-worktree=${baseWorktreeSpec}`];
   if (depsMode) args.push(`--deps=${depsMode}`);
-  await run(process.execPath, [join(rootDir, 'bin', 'happys.mjs'), ...args], { cwd: rootDir });
+  await run(process.execPath, [join(rootDir, 'bin', 'happys.mjs'), ...args], { cwd: rootDir, env });
 
-  const repoDir = componentRepoDir(rootDir, component);
+  const repoDir = componentRepoDir(rootDir, component, env);
   const owner = await getRemoteOwner({ repoDir, remoteName });
-  return join(getWorktreesRoot(rootDir), component, owner, ...slug.split('/'));
+  return join(getWorktreesRoot(rootDir, env), component, owner, ...slug.split('/'));
 }
 
-export function resolveComponentSpecToDir({ rootDir, component, spec }) {
+export function resolveComponentSpecToDir({ rootDir, component, spec, env = process.env }) {
   const raw = (spec ?? '').trim();
   if (!raw || raw === 'default') {
     return null;
@@ -88,11 +89,11 @@ export function resolveComponentSpecToDir({ rootDir, component, spec }) {
     return raw;
   }
   // Treat as <owner>/<branch...> under components/.worktrees/<component>/...
-  return join(getWorktreesRoot(rootDir), component, ...raw.split('/'));
+  return join(getWorktreesRoot(rootDir, env), component, ...raw.split('/'));
 }
 
-export async function listWorktreeSpecs({ rootDir, component }) {
-  const dir = join(getWorktreesRoot(rootDir), component);
+export async function listWorktreeSpecs({ rootDir, component, env = process.env }) {
+  const dir = join(getWorktreesRoot(rootDir, env), component);
   const specs = [];
   try {
     const walk = async (d, prefixParts) => {
@@ -125,10 +126,13 @@ export async function getRemoteOwner({ repoDir, remoteName = 'upstream' }) {
   return owner;
 }
 
-export async function createWorktree({ rootDir, component, slug, remoteName = 'upstream' }) {
+export async function createWorktree({ rootDir, component, slug, remoteName = 'upstream', env = process.env }) {
   // Create without modifying env.local (unless caller passes --use elsewhere).
-  await run(process.execPath, [join(rootDir, 'bin', 'happys.mjs'), 'wt', 'new', component, slug, `--remote=${remoteName}`], { cwd: rootDir });
-  const repoDir = componentRepoDir(rootDir, component);
+  await run(process.execPath, [join(rootDir, 'bin', 'happys.mjs'), 'wt', 'new', component, slug, `--remote=${remoteName}`], {
+    cwd: rootDir,
+    env,
+  });
+  const repoDir = componentRepoDir(rootDir, component, env);
   const owner = await getRemoteOwner({ repoDir, remoteName });
-  return join(getWorktreesRoot(rootDir), component, owner, ...slug.split('/'));
+  return join(getWorktreesRoot(rootDir, env), component, owner, ...slug.split('/'));
 }