happy-stacks 0.1.2 → 0.2.0

package/scripts/utils/dev_expo_web.mjs

@@ -0,0 +1,112 @@
+import { ensureDepsInstalled, pmSpawnBin } from './pm.mjs';
+import { ensureExpoIsolationEnv, getExpoStatePaths, isStateProcessRunning, wantsExpoClearCache, writePidState } from './expo.mjs';
+import { pickDevMetroPort, resolveStackUiDevPortStart } from './dev_server.mjs';
+import { recordStackRuntimeUpdate } from './stack_runtime_state.mjs';
+import { killProcessGroupOwnedByStack } from './ownership.mjs';
+
+export async function startDevExpoWebUi({
+  startUi,
+  uiDir,
+  autostart,
+  baseEnv,
+  apiServerUrl,
+  restart,
+  stackMode,
+  runtimeStatePath,
+  stackName,
+  envPath,
+  children,
+  spawnOptions = {},
+}) {
+  if (!startUi) return { ok: true, skipped: true, reason: 'disabled' };
+
+  await ensureDepsInstalled(uiDir, 'happy');
+  const uiEnv = { ...baseEnv };
+  delete uiEnv.CI;
+  uiEnv.EXPO_PUBLIC_HAPPY_SERVER_URL = apiServerUrl;
+  uiEnv.EXPO_PUBLIC_DEBUG = uiEnv.EXPO_PUBLIC_DEBUG ?? '1';
+
+  // We own the browser opening behavior in Happy Stacks so we can reliably open the correct origin.
+  uiEnv.EXPO_NO_BROWSER = '1';
+  uiEnv.BROWSER = 'none';
+
+  const uiPaths = getExpoStatePaths({
+    baseDir: autostart.baseDir,
+    kind: 'ui-dev',
+    projectDir: uiDir,
+    stateFileName: 'ui.state.json',
+  });
+
+  await ensureExpoIsolationEnv({
+    env: uiEnv,
+    stateDir: uiPaths.stateDir,
+    expoHomeDir: uiPaths.expoHomeDir,
+    tmpDir: uiPaths.tmpDir,
+  });
+
+  const uiRunning = await isStateProcessRunning(uiPaths.statePath);
+  const uiAlreadyRunning = Boolean(uiRunning.running);
+
+  if (uiAlreadyRunning && !restart) {
+    const pid = Number(uiRunning.state?.pid);
+    const port = Number(uiRunning.state?.port);
+    if (stackMode && runtimeStatePath && Number.isFinite(pid) && pid > 1) {
+      await recordStackRuntimeUpdate(runtimeStatePath, {
+        processes: { expoWebPid: pid },
+        expo: { webPort: Number.isFinite(port) && port > 0 ? port : null },
+      }).catch(() => {});
+    }
+    return {
+      ok: true,
+      skipped: true,
+      reason: 'already_running',
+      pid: Number.isFinite(pid) ? pid : null,
+      port: Number.isFinite(port) ? port : null,
+    };
+  }
+
+  const strategy =
+    (baseEnv.HAPPY_STACKS_UI_DEV_PORT_STRATEGY ?? baseEnv.HAPPY_LOCAL_UI_DEV_PORT_STRATEGY ?? 'ephemeral').toString().trim() ||
+    'ephemeral';
+  const stable = strategy === 'stable';
+  const startPort = stackMode && stable ? resolveStackUiDevPortStart({ env: baseEnv, stackName }) : 8081;
+  const metroPort = await pickDevMetroPort({ startPort });
+  uiEnv.RCT_METRO_PORT = String(metroPort);
+
+  const uiArgs = ['start', '--web', '--port', String(metroPort)];
+  if (wantsExpoClearCache({ env: baseEnv })) {
+    uiArgs.push('--clear');
+  }
+
+  if (restart && uiRunning.state?.pid) {
+    const prevPid = Number(uiRunning.state.pid);
+    const res = await killProcessGroupOwnedByStack(prevPid, { stackName, envPath, label: 'expo-web', json: true });
+    if (!res.killed) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[local] ui: not stopping existing Expo pid=${prevPid} because it does not look stack-owned.\n` +
+          `[local] ui: continuing by starting a new Expo process on a free port.`
+      );
+    }
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(`[local] ui: starting Expo web (metro port=${metroPort})`);
+  const ui = await pmSpawnBin({ label: 'ui', dir: uiDir, bin: 'expo', args: uiArgs, env: uiEnv, options: spawnOptions });
+  children.push(ui);
+
+  if (stackMode && runtimeStatePath) {
+    await recordStackRuntimeUpdate(runtimeStatePath, {
+      processes: { expoWebPid: ui.pid },
+      expo: { webPort: metroPort },
+    }).catch(() => {});
+  }
+
+  try {
+    await writePidState(uiPaths.statePath, { pid: ui.pid, port: metroPort, uiDir, startedAt: new Date().toISOString() });
+  } catch {
+    // ignore
+  }
+
+  return { ok: true, skipped: false, pid: ui.pid, port: metroPort, proc: ui };
+}

package/scripts/utils/dev_server.mjs

@@ -0,0 +1,183 @@
+import { join, resolve } from 'node:path';
+
+import { ensureDepsInstalled, pmSpawnScript } from './pm.mjs';
+import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from './happy_server_infra.mjs';
+import { waitForServerReady } from './server.mjs';
+import { isTcpPortFree, pickNextFreeTcpPort } from './ports.mjs';
+import { readStackRuntimeStateFile, recordStackRuntimeUpdate } from './stack_runtime_state.mjs';
+import { killProcessGroupOwnedByStack } from './ownership.mjs';
+import { watchDebounced } from './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;
+}
+
+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);
+}
+
+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 });
+}
+
+export async function startDevServer({
+  serverComponentName,
+  serverDir,
+  autostart,
+  baseEnv,
+  serverPort,
+  internalServerUrl,
+  publicServerUrl,
+  envPath,
+  stackMode,
+  runtimeStatePath,
+  serverAlreadyRunning,
+  restart,
+  children,
+}) {
+  const serverEnv = {
+    ...baseEnv,
+    PORT: String(serverPort),
+    PUBLIC_URL: publicServerUrl,
+    // Avoid noisy failures if a previous run left the metrics port busy.
+    METRICS_ENABLED: baseEnv.METRICS_ENABLED ?? 'false',
+  };
+
+  if (serverComponentName === 'happy-server-light') {
+    const dataDir = baseEnv.HAPPY_SERVER_LIGHT_DATA_DIR?.trim()
+      ? baseEnv.HAPPY_SERVER_LIGHT_DATA_DIR.trim()
+      : join(autostart.baseDir, 'server-light');
+    serverEnv.HAPPY_SERVER_LIGHT_DATA_DIR = dataDir;
+    serverEnv.HAPPY_SERVER_LIGHT_FILES_DIR = baseEnv.HAPPY_SERVER_LIGHT_FILES_DIR?.trim()
+      ? baseEnv.HAPPY_SERVER_LIGHT_FILES_DIR.trim()
+      : join(dataDir, 'files');
+    serverEnv.DATABASE_URL = baseEnv.DATABASE_URL?.trim() ? baseEnv.DATABASE_URL.trim() : `file:${join(dataDir, 'happy-server-light.sqlite')}`;
+  }
+
+  if (serverComponentName === 'happy-server') {
+    const managed = (baseEnv.HAPPY_STACKS_MANAGED_INFRA ?? baseEnv.HAPPY_LOCAL_MANAGED_INFRA ?? '1') !== '0';
+    if (managed) {
+      const infra = await ensureHappyServerManagedInfra({
+        stackName: autostart.stackName,
+        baseDir: autostart.baseDir,
+        serverPort,
+        publicServerUrl,
+        envPath,
+        env: baseEnv,
+      });
+      Object.assign(serverEnv, infra.env);
+    }
+
+    const autoMigrate = (baseEnv.HAPPY_STACKS_PRISMA_MIGRATE ?? baseEnv.HAPPY_LOCAL_PRISMA_MIGRATE ?? '1') !== '0';
+    if (autoMigrate) {
+      await applyHappyServerMigrations({ serverDir, env: serverEnv });
+    }
+  }
+
+  // Ensure server deps exist before any Prisma/docker work.
+  await ensureDepsInstalled(serverDir, serverComponentName);
+
+  const prismaPush = (baseEnv.HAPPY_STACKS_PRISMA_PUSH ?? baseEnv.HAPPY_LOCAL_PRISMA_PUSH ?? '1').toString().trim() !== '0';
+  const serverScript =
+    serverComponentName === 'happy-server'
+      ? 'start'
+      : serverComponentName === 'happy-server-light' && !prismaPush
+        ? 'start'
+        : 'dev';
+
+  // Restart behavior (stack-safe): only kill when we can prove ownership via runtime state.
+  if (restart && stackMode && runtimeStatePath && serverAlreadyRunning) {
+    const st = await readStackRuntimeStateFile(runtimeStatePath);
+    const pid = Number(st?.processes?.serverPid);
+    if (pid > 1) {
+      const res = await killProcessGroupOwnedByStack(pid, { stackName: autostart.stackName, envPath, label: 'server', json: true });
+      if (!res.killed) {
+        // Fail-closed if the port is still occupied.
+        const free = await isTcpPortFree(serverPort, { host: '127.0.0.1' });
+        if (!free) {
+          throw new Error(
+            `[local] restart refused: server port ${serverPort} is occupied and the PID is not provably stack-owned.\n` +
+              `[local] Fix: run 'happys stack stop ${autostart.stackName}' then re-run, or re-run without --restart.`
+          );
+        }
+      }
+    }
+  }
+
+  if (serverAlreadyRunning && !restart) {
+    return { serverEnv, serverScript, serverProc: null };
+  }
+
+  const server = await pmSpawnScript({ label: 'server', dir: serverDir, script: serverScript, env: serverEnv });
+  children.push(server);
+  if (stackMode && runtimeStatePath) {
+    await recordStackRuntimeUpdate(runtimeStatePath, { processes: { serverPid: server.pid } }).catch(() => {});
+  }
+  await waitForServerReady(internalServerUrl);
+  return { serverEnv, serverScript, serverProc: server };
+}
+
+export function watchDevServerAndRestart({
+  enabled,
+  stackMode,
+  serverComponentName,
+  serverDir,
+  serverPort,
+  internalServerUrl,
+  serverScript,
+  serverEnv,
+  runtimeStatePath,
+  stackName,
+  envPath,
+  children,
+  serverProcRef,
+  isShuttingDown,
+}) {
+  if (!enabled) return null;
+
+  // Only watch full server by default; happy-server-light already has a good upstream dev loop.
+  if (serverComponentName !== 'happy-server') return null;
+
+  return watchDebounced({
+    paths: [resolve(serverDir)],
+    debounceMs: 600,
+    onChange: async () => {
+      if (isShuttingDown?.()) return;
+      const pid = Number(serverProcRef?.current?.pid);
+      if (!Number.isFinite(pid) || pid <= 1) return;
+
+      // eslint-disable-next-line no-console
+      console.log('[local] watch: server changed → restarting...');
+      await killProcessGroupOwnedByStack(pid, { stackName, envPath, label: 'server', json: false });
+
+      const next = await pmSpawnScript({ label: 'server', dir: serverDir, script: serverScript, env: serverEnv });
+      children.push(next);
+      serverProcRef.current = next;
+      if (stackMode && runtimeStatePath) {
+        await recordStackRuntimeUpdate(runtimeStatePath, { processes: { serverPid: next.pid } }).catch(() => {});
+      }
+      await waitForServerReady(internalServerUrl);
+      // eslint-disable-next-line no-console
+      console.log(`[local] watch: server restarted (pid=${next.pid}, port=${serverPort})`);
+    },
+  });
+}

package/scripts/utils/env.mjs

@@ -4,13 +4,32 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseDotenv } from './dotenv.mjs';
+import { expandHome, getCanonicalHomeEnvPathFromEnv } from './canonical_home.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './sandbox.mjs';
 
 async function loadEnvFile(path, { override = false, overridePrefix = null } = {}) {
   try {
     const contents = await readFile(path, 'utf-8');
     const parsed = parseDotenv(contents);
+    const allowTransientComponentDirOverrides =
+      !overridePrefix &&
+      override &&
+      ((process.env.HAPPY_STACKS_TRANSIENT_COMPONENT_OVERRIDES ?? '').trim() === '1' ||
+        (process.env.HAPPY_LOCAL_TRANSIENT_COMPONENT_OVERRIDES ?? '').trim() === '1');
     for (const [k, v] of parsed.entries()) {
       const allowOverride = override && (!overridePrefix || k.startsWith(overridePrefix));
+      // Special-case: allow one-shot CLI overrides (e.g. `happys stack typecheck <stack> --happy-cli=...`)
+      // to win over stack env files for component directories.
+      //
+      // This keeps stack env files authoritative by default (we also scrub HAPPY_STACKS_* from the parent
+      // environment in `withStackEnv()`), but lets the stack wrappers inject a temporary override when explicitly requested.
+      if (
+        allowTransientComponentDirOverrides &&
+        (k.startsWith('HAPPY_STACKS_COMPONENT_DIR_') || k.startsWith('HAPPY_LOCAL_COMPONENT_DIR_')) &&
+        (process.env[k] ?? '').trim()
+      ) {
+        continue;
+      }
       if (allowOverride || process.env[k] == null || process.env[k] === '') {
         process.env[k] = v;
       }
@@ -20,16 +39,29 @@ async function loadEnvFile(path, { override = false, overridePrefix = null } = {
   }
 }
 
+async function loadEnvFileIgnoringPrefixes(path, { ignorePrefixes = [] } = {}) {
+  try {
+    const contents = await readFile(path, 'utf-8');
+    const parsed = parseDotenv(contents);
+    for (const [k, v] of parsed.entries()) {
+      if (ignorePrefixes.some((p) => k.startsWith(p))) {
+        continue;
+      }
+      if (process.env[k] == null || process.env[k] === '') {
+        process.env[k] = v;
+      }
+    }
+  } catch {
+    // ignore missing/invalid env file
+  }
+}
+
 // Load happy-stacks env (optional). This is intentionally lightweight and does not require extra deps.
 // This file lives under scripts/utils/, so repo root is two directories up.
 const __utilsDir = dirname(fileURLToPath(import.meta.url));
 const __scriptsDir = dirname(__utilsDir);
 const __cliRootDir = dirname(__scriptsDir);
 
-function expandHome(p) {
-  return p.replace(/^~(?=\/)/, homedir());
-}
-
 function resolveHomeDir() {
   const fromEnv = (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim();
   if (fromEnv) {
@@ -65,11 +97,11 @@ function applyStacksPrefixMapping() {
   }
 }
 
-// If HAPPY_STACKS_HOME_DIR isn't set, try the canonical pointer file at ~/.happy-stacks/.env first.
+// If HAPPY_STACKS_HOME_DIR isn't set, try the canonical pointer file at <canonicalHomeDir>/.env first.
 //
 // This allows installs where the "real" home/workspace/runtime are elsewhere, while still
 // giving us a stable discovery location for launchd/SwiftBar/minimal shells.
-const canonicalEnvPath = join(homedir(), '.happy-stacks', '.env');
+const canonicalEnvPath = getCanonicalHomeEnvPathFromEnv(process.env);
 if (!(process.env.HAPPY_STACKS_HOME_DIR ?? '').trim() && existsSync(canonicalEnvPath)) {
   await loadEnvFile(canonicalEnvPath, { override: false });
   await loadEnvFile(canonicalEnvPath, { override: true, overridePrefix: 'HAPPY_STACKS_' });
@@ -83,12 +115,15 @@ process.env.HAPPY_STACKS_HOME_DIR = process.env.HAPPY_STACKS_HOME_DIR ?? __homeD
 //   ~/.happy-stacks/.env
 //   ~/.happy-stacks/env.local
 //
-// Backwards compatible fallback for cloned-repo usage (when home config doesn't exist yet):
-//   <repo>/.env
-//   <repo>/env.local
+// Additionally: when running from a cloned repo, load <repo>/.env as a *fallback* even if home config exists.
+// This helps keep repo-local dev settings (e.g. custom Codex binaries) working without requiring users to
+// duplicate them into ~/.happy-stacks/env.local.
 const homeEnv = join(__homeDir, '.env');
 const homeLocal = join(__homeDir, 'env.local');
-const hasHomeConfig = existsSync(homeEnv) || existsSync(homeLocal);
+// In sandbox mode, never load repo env.local (it can contain "real" machine paths/URLs).
+// Treat sandbox runs as having home config even if the sandbox home env files don't exist yet.
+const hasHomeConfig = isSandboxed() || existsSync(homeEnv) || existsSync(homeLocal);
+const repoEnv = join(__cliRootDir, '.env');
 
 // 1) Load defaults first (lowest precedence)
 if (hasHomeConfig) {
@@ -101,6 +136,19 @@ if (hasHomeConfig) {
   await loadEnvFile(join(__cliRootDir, 'env.local'), { override: true, overridePrefix: 'HAPPY_STACKS_' });
 }
 
+// Repo-local fallback (dev convenience):
+// If the repo has a .env, load it without overriding anything already set by the environment or home config.
+// Note: we intentionally do NOT load repo env.local here, because env.local is treated as higher-precedence
+// overrides and could unexpectedly fight with stack/home configuration when present.
+if (hasHomeConfig) {
+  // IMPORTANT:
+  // When home config exists, do not let repo-local .env set HAPPY_STACKS_* / HAPPY_LOCAL_* keys.
+  // Otherwise a cloned repo's .env can accidentally leak global URLs/ports into every stack.
+  await loadEnvFileIgnoringPrefixes(repoEnv, { ignorePrefixes: ['HAPPY_STACKS_', 'HAPPY_LOCAL_'] });
+} else {
+  await loadEnvFile(repoEnv, { override: false });
+}
+
 // If no explicit env file is set, and we're on the default "main" stack, prefer the stack-scoped env file
 // if it exists: ~/.happy/stacks/main/env
 (() => {
@@ -112,7 +160,8 @@ if (hasHomeConfig) {
   const stackName = (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').trim() || 'main';
   const stacksStorageRootRaw = (process.env.HAPPY_STACKS_STORAGE_DIR ?? process.env.HAPPY_LOCAL_STORAGE_DIR ?? '').trim();
   const stacksStorageRoot = stacksStorageRootRaw ? expandHome(stacksStorageRootRaw) : join(homedir(), '.happy', 'stacks');
-  const legacyStacksRoot = join(homedir(), '.happy', 'local', 'stacks');
+  const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
+  const legacyStacksRoot = allowLegacy ? join(homedir(), '.happy', 'local', 'stacks') : join(stacksStorageRoot, '__legacy_disabled__');
 
   const candidates = [
     join(stacksStorageRoot, stackName, 'env'),

package/scripts/utils/env_file.mjs

@@ -10,6 +10,17 @@ export async function ensureEnvFileUpdated({ envPath, updates }) {
   await writeFileIfChanged(envPath, applyEnvUpdates(await readText(envPath), updates), envPath);
 }
 
+export async function ensureEnvFilePruned({ envPath, removeKeys }) {
+  const keys = Array.from(new Set((removeKeys ?? []).map((k) => String(k).trim()).filter(Boolean)));
+  if (!keys.length) {
+    return;
+  }
+  await mkdir(dirname(envPath), { recursive: true });
+  const existing = await readText(envPath);
+  const next = pruneEnvKeys(existing, keys);
+  await writeFileIfChanged(existing, next, envPath);
+}
+
 async function readText(path) {
   try {
     return (await pathExists(path)) ? await readFile(path, 'utf-8') : '';
@@ -42,6 +53,31 @@ function applyEnvUpdates(existing, updates) {
   return next.join('\n');
 }
 
+function pruneEnvKeys(existing, removeKeys) {
+  const keys = new Set(removeKeys);
+  const lines = (existing ?? '').split('\n');
+  const kept = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      kept.push(line);
+      continue;
+    }
+    // Remove any "KEY=..." line for keys in removeKeys.
+    const eq = trimmed.indexOf('=');
+    if (eq <= 0) {
+      kept.push(line);
+      continue;
+    }
+    const key = trimmed.slice(0, eq).trim();
+    if (keys.has(key)) {
+      continue;
+    }
+    kept.push(line);
+  }
+  return kept.join('\n');
+}
+
 async function writeFileIfChanged(existingContent, nextContent, path) {
   const normalizedNext = nextContent.endsWith('\n') ? nextContent : nextContent + '\n';
   const normalizedExisting = existingContent.endsWith('\n') ? existingContent : existingContent + (existingContent ? '\n' : '');

package/scripts/utils/expo.mjs

@@ -26,10 +26,12 @@ export async function ensureExpoIsolationEnv({ env, stateDir, expoHomeDir, tmpDi
   await mkdir(tmpDir, { recursive: true });
 
   // Expo CLI uses this to override ~/.expo.
-  env.__UNSAFE_EXPO_HOME_DIRECTORY = env.__UNSAFE_EXPO_HOME_DIRECTORY ?? expoHomeDir;
+  // Always override: stack/worktree isolation must not fall back to the user's global ~/.expo.
+  env.__UNSAFE_EXPO_HOME_DIRECTORY = expoHomeDir;
 
   // Metro default cache root is `path.join(os.tmpdir(), 'metro-cache')`, so TMPDIR isolates it.
-  env.TMPDIR = env.TMPDIR ?? tmpDir;
+  // Always override: macOS sets TMPDIR by default, so a "set-if-missing" guard would not isolate Metro.
+  env.TMPDIR = tmpDir;
 }
 
 export function wantsExpoClearCache({ env }) {

package/scripts/utils/handy_master_secret.mjs

@@ -0,0 +1,94 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { parseDotenv } from './dotenv.mjs';
+import { resolveStackEnvPath } from './paths.mjs';
+import { getLegacyHappyBaseDir, isLegacyAuthSourceName } from './auth_sources.mjs';
+
+async function readTextIfExists(path) {
+  try {
+    if (!path || !existsSync(path)) return null;
+    const raw = await readFile(path, 'utf-8');
+    const t = raw.trim();
+    return t ? t : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseEnvToObject(raw) {
+  const parsed = parseDotenv(raw ?? '');
+  return Object.fromEntries(parsed.entries());
+}
+
+function getEnvValue(env, key) {
+  const v = (env?.[key] ?? '').toString().trim();
+  return v || '';
+}
+
+function stackExistsSync(stackName) {
+  if (stackName === 'main') return true;
+  const envPath = resolveStackEnvPath(stackName).envPath;
+  return existsSync(envPath);
+}
+
+export async function resolveHandyMasterSecretFromStack({
+  stackName,
+  requireStackExists = false,
+  allowLegacyAuthSource = true,
+  allowLegacyMainFallback = true,
+} = {}) {
+  const name = String(stackName ?? '').trim() || 'main';
+
+  if (isLegacyAuthSourceName(name)) {
+    if (!allowLegacyAuthSource) {
+      throw new Error(
+        '[auth] legacy auth source is disabled in sandbox mode.\n' +
+          'Reason: it reads from ~/.happy (global user state).\n' +
+          'If you really want this, set: HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1'
+      );
+    }
+    const baseDir = getLegacyHappyBaseDir();
+    const legacySecretPath = join(baseDir, 'server-light', 'handy-master-secret.txt');
+    const secret = await readTextIfExists(legacySecretPath);
+    return secret ? { secret, source: legacySecretPath } : { secret: null, source: null };
+  }
+
+  if (requireStackExists && !stackExistsSync(name)) {
+    throw new Error(`[auth] cannot copy auth: source stack "${name}" does not exist`);
+  }
+
+  const resolved = resolveStackEnvPath(name);
+  const sourceBaseDir = resolved.baseDir;
+  const sourceEnvPath = resolved.envPath;
+  const raw = await readTextIfExists(sourceEnvPath);
+  const env = raw ? parseEnvToObject(raw) : {};
+
+  const inline = getEnvValue(env, 'HANDY_MASTER_SECRET');
+  if (inline) {
+    return { secret: inline, source: `${sourceEnvPath} (HANDY_MASTER_SECRET)` };
+  }
+
+  const secretFile = getEnvValue(env, 'HAPPY_STACKS_HANDY_MASTER_SECRET_FILE');
+  if (secretFile) {
+    const secret = await readTextIfExists(secretFile);
+    if (secret) return { secret, source: secretFile };
+  }
+
+  const dataDir = getEnvValue(env, 'HAPPY_SERVER_LIGHT_DATA_DIR') || join(sourceBaseDir, 'server-light');
+  const secretPath = join(dataDir, 'handy-master-secret.txt');
+  const secret = await readTextIfExists(secretPath);
+  if (secret) return { secret, source: secretPath };
+
+  // Last-resort legacy: if main has never been migrated to stack dirs.
+  if (name === 'main' && allowLegacyMainFallback) {
+    const legacy = join(homedir(), '.happy', 'server-light', 'handy-master-secret.txt');
+    const legacySecret = await readTextIfExists(legacy);
+    if (legacySecret) return { secret: legacySecret, source: legacy };
+  }
+
+  return { secret: null, source: null };
+}
+