happy-stacks 0.1.0 → 0.2.0

package/scripts/utils/pm.mjs

@@ -1,13 +1,61 @@
 import { homedir } from 'node:os';
 import { dirname, join, resolve, sep } from 'node:path';
 import { existsSync } from 'node:fs';
-import { chmod, mkdir, rm, stat, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 
 import { pathExists } from './fs.mjs';
 import { run, runCapture, spawnProc } from './proc.mjs';
 import { getDefaultAutostartPaths, getHappyStacksHomeDir } from './paths.mjs';
 import { resolveInstalledPath, resolveInstalledCliRoot } from './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));
+  return join(homeDir, 'cache', 'build', label, `${key}.json`);
+}
+
+async function computeGitWorktreeSignature(dir) {
+  try {
+    // Fast path: only if this is a git worktree.
+    const inside = (await runCapture('git', ['-C', dir, 'rev-parse', '--is-inside-work-tree'])).trim();
+    if (inside !== 'true') return null;
+    const head = (await runCapture('git', ['-C', dir, 'rev-parse', 'HEAD'])).trim();
+    // Includes staged + unstaged + untracked changes; captures “dirty” vs “clean”.
+    const status = await runCapture('git', ['-C', dir, 'status', '--porcelain=v1']);
+    return {
+      kind: 'git',
+      head,
+      statusHash: sha256Hex(status),
+      signature: sha256Hex(`${head}\n${status}`),
+    };
+  } catch {
+    return null;
+  }
+}
+
 async function commandExists(cmd, options = {}) {
   try {
     await runCapture(cmd, ['--version'], options);
@@ -53,7 +101,7 @@ export async function requireDir(label, dir) {
   );
 }
 
-export async function ensureDepsInstalled(dir, label) {
+export async function ensureDepsInstalled(dir, label, { quiet = false } = {}) {
   const pkgJson = join(dir, 'package.json');
   if (!(await pathExists(pkgJson))) {
     return;
@@ -62,6 +110,7 @@ export async function ensureDepsInstalled(dir, label) {
   const nodeModules = join(dir, 'node_modules');
   const pnpmModulesMeta = join(dir, 'node_modules', '.modules.yaml');
   const pm = await getComponentPm(dir);
+  const stdio = quiet ? 'ignore' : 'inherit';
 
   if (await pathExists(nodeModules)) {
     const yarnLock = join(dir, 'yarn.lock');
@@ -71,10 +120,12 @@ export async function ensureDepsInstalled(dir, label) {
     // If this repo is Yarn-managed (yarn.lock present) but node_modules was created by pnpm,
     // reinstall with Yarn to restore upstream-locked dependency versions.
     if (pm.name === 'yarn' && (await pathExists(pnpmModulesMeta))) {
-      // eslint-disable-next-line no-console
-      console.log(`[local] converting ${label} dependencies back to yarn (reinstalling node_modules)...`);
+      if (!quiet) {
+        // eslint-disable-next-line no-console
+        console.log(`[local] converting ${label} dependencies back to yarn (reinstalling node_modules)...`);
+      }
       await rm(nodeModules, { recursive: true, force: true });
-      await run(pm.cmd, ['install'], { cwd: dir });
+      await run(pm.cmd, ['install'], { cwd: dir, stdio });
     }
 
     // If dependencies changed since the last install, re-run install even if node_modules exists.
@@ -92,9 +143,11 @@ export async function ensureDepsInstalled(dir, label) {
       const pkgM = await mtimeMs(pkgJson);
       const intM = await mtimeMs(yarnIntegrity);
       if (!intM || lockM > intM || pkgM > intM) {
-        // eslint-disable-next-line no-console
-        console.log(`[local] refreshing ${label} dependencies (yarn.lock/package.json changed)...`);
-        await run(pm.cmd, ['install'], { cwd: dir });
+        if (!quiet) {
+          // eslint-disable-next-line no-console
+          console.log(`[local] refreshing ${label} dependencies (yarn.lock/package.json changed)...`);
+        }
+        await run(pm.cmd, ['install'], { cwd: dir, stdio });
       }
     }
 
@@ -102,29 +155,75 @@ export async function ensureDepsInstalled(dir, label) {
       const lockM = await mtimeMs(pnpmLock);
       const metaM = await mtimeMs(pnpmModulesMeta);
       if (!metaM || lockM > metaM) {
-        // eslint-disable-next-line no-console
-        console.log(`[local] refreshing ${label} dependencies (pnpm-lock changed)...`);
-        await run(pm.cmd, ['install'], { cwd: dir });
+        if (!quiet) {
+          // eslint-disable-next-line no-console
+          console.log(`[local] refreshing ${label} dependencies (pnpm-lock changed)...`);
+        }
+        await run(pm.cmd, ['install'], { cwd: dir, stdio });
       }
     }
 
     return;
   }
 
-  // eslint-disable-next-line no-console
-  console.log(`[local] installing ${label} dependencies (first run)...`);
-  await run(pm.cmd, ['install'], { cwd: dir });
+  if (!quiet) {
+    // eslint-disable-next-line no-console
+    console.log(`[local] installing ${label} dependencies (first run)...`);
+  }
+  await run(pm.cmd, ['install'], { cwd: dir, stdio });
 }
 
 export async function ensureCliBuilt(cliDir, { buildCli }) {
   await ensureDepsInstalled(cliDir, 'happy-cli');
   if (!buildCli) {
-    return;
+    return { built: false, reason: 'disabled' };
+  }
+  // Default: build only when needed (fast + reliable for worktrees that haven't been built yet).
+  //
+  // You can force always-build by setting:
+  // - HAPPY_STACKS_CLI_BUILD_MODE=always (legacy: HAPPY_LOCAL_CLI_BUILD_MODE=always)
+  // Or disable via:
+  // - 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);
+
+  if (mode === 'auto') {
+    // If dist doesn't exist, we must build.
+    if (!(await pathExists(distEntrypoint))) {
+      // fallthrough to build
+    } else if (gitSig && prev?.signature && prev.signature === gitSig.signature) {
+      return { built: false, reason: 'up_to_date' };
+    } else if (!gitSig) {
+      // No git info: best-effort skip if dist exists (keeps this fast outside git worktrees).
+      return { built: false, reason: 'no_git_info' };
+    }
   }
+
   // eslint-disable-next-line no-console
   console.log('[local] building happy-cli...');
   const pm = await getComponentPm(cliDir);
   await run(pm.cmd, ['build'], { cwd: cliDir });
+
+  // Persist new build state (best-effort).
+  const nowSig = gitSig ?? (await computeGitWorktreeSignature(cliDir));
+  if (nowSig) {
+    await writeJsonAtomic(buildStatePath, {
+      label: 'happy-cli',
+      dir: resolve(cliDir),
+      signature: nowSig.signature,
+      head: nowSig.head,
+      statusHash: nowSig.statusHash,
+      builtAt: new Date().toISOString(),
+    }).catch(() => {});
+  }
+  return { built: true, reason: mode === 'always' ? 'mode_always' : 'changed' };
 }
 
 function getPathEntries() {
@@ -153,8 +252,9 @@ export async function ensureHappyCliLocalNpmLinked(rootDir, { npmLinkCli }) {
 
   const shim = `#!/bin/bash
 set -euo pipefail
-HOME_DIR="\${HAPPY_STACKS_HOME_DIR:-$HOME/.happy-stacks}"
-HAPPYS="$HOME_DIR/bin/happys"
+# Prefer the sibling happys shim (works for sandbox installs too).
+BIN_DIR="$(cd "$(dirname "$0")" && pwd)"
+HAPPYS="$BIN_DIR/happys"
 if [[ -x "$HAPPYS" ]]; then
   exec "$HAPPYS" happy "$@"
 fi
@@ -180,13 +280,22 @@ export async function pmSpawnScript({ label, dir, script, env, options = {} }) {
   return spawnProc(label, pm.cmd, ['--silent', script], env, { ...options, cwd: dir });
 }
 
-export async function pmExecBin({ dir, bin, args, env }) {
+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({ dir, bin, args, env, quiet = false }) {
   const pm = await getComponentPm(dir);
+  const stdio = quiet ? 'ignore' : 'inherit';
   if (pm.name === 'yarn') {
-    await run(pm.cmd, [bin, ...args], { env, cwd: dir });
+    await run(pm.cmd, [bin, ...args], { env, cwd: dir, stdio });
     return;
   }
-  await run(pm.cmd, ['exec', bin, ...args], { env, cwd: dir });
+  await run(pm.cmd, ['exec', bin, ...args], { env, cwd: dir, stdio });
 }
 
 export async function ensureMacAutostartEnabled({ rootDir, label = 'com.happy.local', env = {} }) {
@@ -217,6 +326,8 @@ export async function ensureMacAutostartEnabled({ rootDir, label = 'com.happy.lo
       : 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).
@@ -233,8 +344,7 @@ export async function ensureMacAutostartEnabled({ rootDir, label = 'com.happy.lo
     <string>${label}</string>
     <key>ProgramArguments</key>
     <array>
-      <string>${nodePath}</string>
-      <string>${happysEntrypoint}</string>
+      ${useShim ? `<string>${happysShim}</string>` : `<string>${nodePath}</string>\n      <string>${happysEntrypoint}</string>`}
       <string>start</string>
     </array>
     <key>WorkingDirectory</key>

package/scripts/utils/ports.mjs

@@ -1,17 +1,10 @@
 import { setTimeout as delay } from 'node:timers/promises';
+import net from 'node:net';
 import { runCapture } from './proc.mjs';
 
-/**
- * Best-effort: kill any processes LISTENing on a TCP port.
- * Used to avoid EADDRINUSE when a previous run left a server behind.
- */
-export async function killPortListeners(port, { label = 'port' } = {}) {
-  if (!Number.isFinite(port) || port <= 0) {
-    return [];
-  }
-  if (process.platform === 'win32') {
-    return [];
-  }
+async function listListenPids(port) {
+  if (!Number.isFinite(port) || port <= 0) return [];
+  if (process.platform === 'win32') return [];
 
   let raw = '';
   try {
@@ -21,10 +14,10 @@ export async function killPortListeners(port, { label = 'port' } = {}) {
       `command -v lsof >/dev/null 2>&1 && lsof -nP -iTCP:${port} -sTCP:LISTEN -t 2>/dev/null || true`,
     ]);
   } catch {
-    return [];
+    raw = '';
   }
 
-  const pids = Array.from(
+  return Array.from(
     new Set(
       raw
         .split(/\s+/g)
@@ -34,6 +27,21 @@ export async function killPortListeners(port, { label = 'port' } = {}) {
         .filter((n) => Number.isInteger(n) && n > 1)
     )
   );
+}
+
+/**
+ * Best-effort: kill any processes LISTENing on a TCP port.
+ * Used to avoid EADDRINUSE when a previous run left a server behind.
+ */
+export async function killPortListeners(port, { label = 'port' } = {}) {
+  if (!Number.isFinite(port) || port <= 0) {
+    return [];
+  }
+  if (process.platform === 'win32') {
+    return [];
+  }
+
+  const pids = await listListenPids(port);
 
   if (!pids.length) {
     return [];
@@ -64,3 +72,33 @@ export async function killPortListeners(port, { label = 'port' } = {}) {
   return pids;
 }
 
+export async function isTcpPortFree(port, { host = '127.0.0.1' } = {}) {
+  if (!Number.isFinite(port) || port <= 0) return false;
+
+  // Prefer lsof-based detection to catch IPv6 listeners (e.g. TCP *:8081 (LISTEN))
+  // which can make a "bind 127.0.0.1" probe incorrectly report "free" on macOS.
+  const pids = await listListenPids(port);
+  if (pids.length) return false;
+
+  // Fallback: attempt to bind.
+  return await new Promise((resolvePromise) => {
+    const srv = net.createServer();
+    srv.unref();
+    srv.on('error', () => resolvePromise(false));
+    srv.listen({ port, host }, () => {
+      srv.close(() => resolvePromise(true));
+    });
+  });
+}
+
+export async function pickNextFreeTcpPort(startPort, { reservedPorts = new Set(), host = '127.0.0.1', tries = 200 } = {}) {
+  let port = startPort;
+  for (let i = 0; i < tries; i++) {
+    // eslint-disable-next-line no-await-in-loop
+    if (!reservedPorts.has(port) && (await isTcpPortFree(port, { host }))) {
+      return port;
+    }
+    port += 1;
+  }
+  throw new Error(`[local] unable to find a free TCP port starting at ${startPort}`);
+}

package/scripts/utils/proc.mjs

@@ -1,5 +1,23 @@
 import { spawn } from 'node:child_process';
 
+function writeWithPrefix(stream, prefix, bufState, chunk) {
+  const s = chunk.toString();
+  bufState.buf += s;
+  while (true) {
+    const idx = bufState.buf.indexOf('\n');
+    if (idx < 0) break;
+    const line = bufState.buf.slice(0, idx);
+    bufState.buf = bufState.buf.slice(idx + 1);
+    stream.write(`${prefix}${line}\n`);
+  }
+}
+
+function flushPrefixed(stream, prefix, bufState) {
+  if (!bufState.buf) return;
+  stream.write(`${prefix}${bufState.buf}\n`);
+  bufState.buf = '';
+}
+
 export function spawnProc(label, cmd, args, env, options = {}) {
   const child = spawn(cmd, args, {
     env,
@@ -10,8 +28,17 @@ export function spawnProc(label, cmd, args, env, options = {}) {
     ...options,
   });
 
-  child.stdout?.on('data', (d) => process.stdout.write(`[${label}] ${d.toString()}`));
-  child.stderr?.on('data', (d) => process.stderr.write(`[${label}] ${d.toString()}`));
+  const outState = { buf: '' };
+  const errState = { buf: '' };
+  const outPrefix = `[${label}] `;
+  const errPrefix = `[${label}] `;
+
+  child.stdout?.on('data', (d) => writeWithPrefix(process.stdout, outPrefix, outState, d));
+  child.stderr?.on('data', (d) => writeWithPrefix(process.stderr, errPrefix, errState, d));
+  child.on('close', () => {
+    flushPrefixed(process.stdout, outPrefix, outState);
+    flushPrefixed(process.stderr, errPrefix, errState);
+  });
   child.on('exit', (code, sig) => {
     if (code !== 0) {
       process.stderr.write(`[${label}] exited (code=${code}, sig=${sig})\n`);
@@ -39,28 +66,69 @@ export function killProcessTree(child, signal) {
 }
 
 export async function run(cmd, args, options = {}) {
+  const { timeoutMs, ...spawnOptions } = options ?? {};
   await new Promise((resolvePromise, rejectPromise) => {
-    const proc = spawn(cmd, args, { stdio: 'inherit', shell: false, ...options });
+    const proc = spawn(cmd, args, { stdio: 'inherit', shell: false, ...spawnOptions });
+    const t =
+      Number.isFinite(timeoutMs) && timeoutMs > 0
+        ? setTimeout(() => {
+            try {
+              proc.kill('SIGKILL');
+            } catch {
+              // ignore
+            }
+            const e = new Error(`${cmd} timed out after ${timeoutMs}ms`);
+            e.code = 'ETIMEDOUT';
+            rejectPromise(e);
+          }, timeoutMs)
+        : null;
     proc.on('error', rejectPromise);
     proc.on('exit', (code) => (code === 0 ? resolvePromise() : rejectPromise(new Error(`${cmd} failed (code=${code})`))));
+    proc.on('exit', () => {
+      if (t) clearTimeout(t);
+    });
   });
 }
 
 export async function runCapture(cmd, args, options = {}) {
+  const { timeoutMs, ...spawnOptions } = options ?? {};
   return await new Promise((resolvePromise, rejectPromise) => {
-    const proc = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], shell: false, ...options });
+    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
+            }
+            const e = new Error(`${cmd} ${args.join(' ')} timed out after ${timeoutMs}ms`);
+            e.code = 'ETIMEDOUT';
+            e.out = out;
+            e.err = err;
+            rejectPromise(e);
+          }, timeoutMs)
+        : null;
     proc.stdout?.on('data', (d) => (out += d.toString()));
     proc.stderr?.on('data', (d) => (err += d.toString()));
     proc.on('error', rejectPromise);
-    proc.on('exit', (code) => {
+    proc.on('exit', (code, signal) => {
+      if (t) clearTimeout(t);
       if (code === 0) {
         resolvePromise(out);
       } else {
-        rejectPromise(new Error(`${cmd} ${args.join(' ')} failed (code=${code}): ${err.trim()}`));
+        const e = new Error(
+          `${cmd} ${args.join(' ')} failed (code=${code ?? 'null'}, sig=${signal ?? 'null'}): ${err.trim()}`
+        );
+        e.code = 'EEXIT';
+        e.exitCode = code;
+        e.signal = signal;
+        e.out = out;
+        e.err = err;
+        rejectPromise(e);
       }
     });
   });
 }
-

package/scripts/utils/runtime.mjs

@@ -2,9 +2,7 @@ import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-function expandHome(p) {
-  return p.replace(/^~(?=\/)/, homedir());
-}
+import { expandHome } from './canonical_home.mjs';
 
 export function getRuntimeDir() {
   const fromEnv = (process.env.HAPPY_STACKS_RUNTIME_DIR ?? '').trim();

package/scripts/utils/sandbox.mjs

@@ -0,0 +1,14 @@
+export function getSandboxDir() {
+  const v = (process.env.HAPPY_STACKS_SANDBOX_DIR ?? '').trim();
+  return v || '';
+}
+
+export function isSandboxed() {
+  return Boolean(getSandboxDir());
+}
+
+export function sandboxAllowsGlobalSideEffects() {
+  const raw = (process.env.HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL ?? '').trim().toLowerCase();
+  return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'y';
+}
+

package/scripts/utils/server.mjs

@@ -22,6 +22,43 @@ export function getServerComponentName({ kv } = {}) {
   return raw;
 }
 
+export async function fetchHappyHealth(baseUrl) {
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort(), 1500);
+  try {
+    const url = baseUrl.replace(/\/+$/, '') + '/health';
+    const res = await fetch(url, { method: 'GET', signal: ctl.signal });
+    const text = await res.text();
+    let json = null;
+    try {
+      json = text ? JSON.parse(text) : null;
+    } catch {
+      json = null;
+    }
+    return { ok: res.ok, status: res.status, json, text };
+  } catch {
+    return { ok: false, status: null, json: null, text: null };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+export async function isHappyServerRunning(baseUrl) {
+  const health = await fetchHappyHealth(baseUrl);
+  if (!health.ok) return false;
+  // Both happy-server and happy-server-light use `service: 'happy-server'` today.
+  // Treat any ok health response as "running" to avoid duplicate spawns.
+  const svc = typeof health.json?.service === 'string' ? health.json.service : '';
+  const status = typeof health.json?.status === 'string' ? health.json.status : '';
+  if (svc && svc !== 'happy-server') {
+    return false;
+  }
+  if (status && status !== 'ok') {
+    return false;
+  }
+  return true;
+}
+
 export async function waitForServerReady(url) {
   const deadline = Date.now() + 60_000;
   while (Date.now() < deadline) {
@@ -39,3 +76,27 @@ export async function waitForServerReady(url) {
   throw new Error(`Timed out waiting for server at ${url}`);
 }
 
+// Used for UI readiness checks (Expo / gateway / server). Treat any HTTP response as "up".
+export async function waitForHttpOk(url, { timeoutMs = 15_000, intervalMs = 250 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const ctl = new AbortController();
+      const t = setTimeout(() => ctl.abort(), Math.min(2500, Math.max(250, intervalMs)));
+      try {
+        const res = await fetch(url, { method: 'GET', signal: ctl.signal });
+        if (res.status >= 100 && res.status < 600) {
+          return;
+        }
+      } finally {
+        clearTimeout(t);
+      }
+    } catch {
+      // ignore
+    }
+    // eslint-disable-next-line no-await-in-loop
+    await delay(intervalMs);
+  }
+  throw new Error(`Timed out waiting for HTTP response from ${url} after ${timeoutMs}ms`);
+}
+

package/scripts/utils/server_port.mjs

@@ -0,0 +1,9 @@
+export function resolveServerPortFromEnv({ env = process.env, defaultPort = 3005 } = {}) {
+  const raw =
+    (env.HAPPY_STACKS_SERVER_PORT ?? '').toString().trim() ||
+    (env.HAPPY_LOCAL_SERVER_PORT ?? '').toString().trim() ||
+    '';
+  const n = raw ? Number(raw) : Number(defaultPort);
+  return Number.isFinite(n) && n > 0 ? n : Number(defaultPort);
+}
+

package/scripts/utils/server_urls.mjs

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from 'node:fs';
+
+import { getStackName, resolveStackEnvPath } from './paths.mjs';
+import { resolvePublicServerUrl } from '../tailscale.mjs';
+import { resolveServerPortFromEnv } from './server_port.mjs';
+
+function stackEnvExplicitlySetsPublicUrl({ env, stackName }) {
+  try {
+    const envPath =
+      (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString().trim() ||
+      resolveStackEnvPath(stackName).envPath;
+    if (!envPath || !existsSync(envPath)) return false;
+    const raw = readFileSync(envPath, 'utf-8');
+    return /^(HAPPY_STACKS_SERVER_URL|HAPPY_LOCAL_SERVER_URL)=/m.test(raw);
+  } catch {
+    return false;
+  }
+}
+
+export function getPublicServerUrlEnvOverride({ env = process.env, serverPort } = {}) {
+  const defaultPublicUrl = `http://localhost:${serverPort}`;
+  const stackName = (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim() || getStackName();
+
+  let envPublicUrl =
+    (env.HAPPY_STACKS_SERVER_URL ?? env.HAPPY_LOCAL_SERVER_URL ?? '').toString().trim() || '';
+
+  // Safety: for non-main stacks, ignore a global SERVER_URL unless it was explicitly set in the stack env file.
+  if (stackName !== 'main' && envPublicUrl && !stackEnvExplicitlySetsPublicUrl({ env, stackName })) {
+    envPublicUrl = '';
+  }
+
+  return { defaultPublicUrl, envPublicUrl, publicServerUrl: envPublicUrl || defaultPublicUrl };
+}
+
+export async function resolveServerUrls({ env = process.env, serverPort, allowEnable = true } = {}) {
+  const internalServerUrl = `http://127.0.0.1:${serverPort}`;
+  const { defaultPublicUrl, envPublicUrl } = getPublicServerUrlEnvOverride({ env, serverPort });
+  const resolved = await resolvePublicServerUrl({
+    internalServerUrl,
+    defaultPublicUrl,
+    envPublicUrl,
+    allowEnable,
+  });
+  return {
+    internalServerUrl,
+    defaultPublicUrl,
+    envPublicUrl,
+    publicServerUrl: resolved.publicServerUrl,
+    publicServerUrlSource: resolved.source,
+  };
+}
+
+export { resolveServerPortFromEnv };
+

package/scripts/utils/stack_context.mjs

@@ -0,0 +1,23 @@
+import { getStackName, resolveStackEnvPath } from './paths.mjs';
+import { getStackRuntimeStatePath } from './stack_runtime_state.mjs';
+
+export function resolveStackContext({ env = process.env, autostart = null } = {}) {
+  const explicitStack = (env.HAPPY_STACKS_STACK ?? env.HAPPY_LOCAL_STACK ?? '').toString().trim();
+  const stackName = explicitStack || (autostart?.stackName ?? '') || getStackName();
+  const stackMode = Boolean(explicitStack);
+
+  const envPath =
+    (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString().trim() ||
+    resolveStackEnvPath(stackName).envPath;
+
+  const runtimeStatePath =
+    (env.HAPPY_STACKS_RUNTIME_STATE_PATH ?? env.HAPPY_LOCAL_RUNTIME_STATE_PATH ?? '').toString().trim() ||
+    getStackRuntimeStatePath(stackName);
+
+  const explicitEphemeral =
+    (env.HAPPY_STACKS_EPHEMERAL_PORTS ?? env.HAPPY_LOCAL_EPHEMERAL_PORTS ?? '').toString().trim() === '1';
+  const ephemeral = explicitEphemeral || (stackMode && stackName !== 'main');
+
+  return { stackMode, stackName, envPath, runtimeStatePath, ephemeral };
+}
+