happy-stacks 0.2.0 → 0.3.0

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

@@ -2,7 +2,9 @@ import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './sandbox.mjs';
+
+import { expandHome } from './canonical_home.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from '../env/sandbox.mjs';
 
 const PRIMARY_APP_SLUG = 'happy-stacks';
 const LEGACY_APP_SLUG = 'happy-local';
@@ -16,10 +18,10 @@ export function getRootDir(importMetaUrl) {
   return dirname(dirname(fileURLToPath(importMetaUrl)));
 }
 
-export function getHappyStacksHomeDir() {
-  const fromEnv = (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim();
+export function getHappyStacksHomeDir(env = process.env) {
+  const fromEnv = (env.HAPPY_STACKS_HOME_DIR ?? env.HAPPY_LOCAL_HOME_DIR ?? '').trim();
   if (fromEnv) {
-    return fromEnv.replace(/^~(?=\/)/, homedir());
+    return expandHome(fromEnv);
   }
   return PRIMARY_HOME_DIR;
 }
@@ -27,7 +29,7 @@ export function getHappyStacksHomeDir() {
 export function getWorkspaceDir(cliRootDir = null) {
   const fromEnv = (process.env.HAPPY_STACKS_WORKSPACE_DIR ?? '').trim();
   if (fromEnv) {
-    return fromEnv.replace(/^~(?=\/)/, homedir());
+    return expandHome(fromEnv);
   }
   const homeDir = getHappyStacksHomeDir();
   const defaultWorkspace = join(homeDir, 'workspace');
@@ -53,7 +55,7 @@ function normalizePathForEnv(rootDir, raw) {
   if (!trimmed) {
     return '';
   }
-  const expanded = trimmed.replace(/^~(?=\/)/, homedir());
+  const expanded = expandHome(trimmed);
   // If the path is relative, treat it as relative to the workspace root (default: repo root).
   const workspaceDir = getWorkspaceDir(rootDir);
   return expanded.startsWith('/') ? expanded : resolve(workspaceDir, expanded);
@@ -89,7 +91,7 @@ export function getLegacyStackLabel(stackName = getStackName()) {
 export function getStacksStorageRoot() {
   const fromEnv = (process.env.HAPPY_STACKS_STORAGE_DIR ?? process.env.HAPPY_LOCAL_STORAGE_DIR ?? '').trim();
   if (fromEnv) {
-    return fromEnv.replace(/^~(?=\/)/, homedir());
+    return expandHome(fromEnv);
   }
   return PRIMARY_STORAGE_ROOT;
 }
@@ -185,3 +187,4 @@ export function getDefaultAutostartPaths() {
     legacyStderrPath,
   };
 }
+

package/scripts/utils/{runtime.mjs → paths/runtime.mjs}

@@ -9,7 +9,9 @@ export function getRuntimeDir() {
   if (fromEnv) {
     return expandHome(fromEnv);
   }
-  const homeDir = (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim() ? expandHome(process.env.HAPPY_STACKS_HOME_DIR.trim()) : join(homedir(), '.happy-stacks');
+  const homeDir = (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim()
+    ? expandHome(process.env.HAPPY_STACKS_HOME_DIR.trim())
+    : join(homedir(), '.happy-stacks');
   return join(homeDir, 'runtime');
 }
 

package/scripts/utils/proc/commands.mjs

@@ -0,0 +1,34 @@
+import { runCapture } from './proc.mjs';
+
+export async function resolveCommandPath(cmd, { cwd, env, timeoutMs } = {}) {
+  const c = String(cmd ?? '').trim();
+  if (!c) return '';
+
+  try {
+    if (process.platform === 'win32') {
+      const out = (await runCapture('where', [c], { cwd, env, timeoutMs })).trim();
+      const first = out.split(/\r?\n/).map((s) => s.trim()).find(Boolean) || '';
+      return first;
+    }
+    return (
+      await runCapture('sh', ['-lc', `command -v "${c}" 2>/dev/null || true`], { cwd, env, timeoutMs })
+    ).trim();
+  } catch {
+    return '';
+  }
+}
+
+export async function runCaptureIfCommandExists(cmd, args, { cwd, env, timeoutMs } = {}) {
+  const resolved = await resolveCommandPath(cmd, { cwd, env, timeoutMs });
+  if (!resolved) return '';
+  try {
+    return await runCapture(resolved, args, { cwd, env, timeoutMs });
+  } catch {
+    return '';
+  }
+}
+
+export async function commandExists(cmd, { cwd } = {}) {
+  return Boolean(await resolveCommandPath(cmd, { cwd }));
+}
+

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

@@ -1,5 +1,5 @@
 import { runCapture } from './proc.mjs';
-import { killPid } from './expo.mjs';
+import { killPid } from '../expo/expo.mjs';
 
 export async function getPsEnvLine(pid) {
   const n = Number(pid);

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/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}

@@ -4,33 +4,17 @@ import { existsSync } from 'node:fs';
 import { chmod, mkdir, readFile, 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;
@@ -258,147 +233,85 @@ 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}`);
   }
+
+  return { ok: true, cliRoot, binDir, happyShim, happysShim };
 }
 
-export async function pmSpawnScript({ label, dir, script, env, options = {} }) {
+export async function pmExecBin(dirOrOpts, binArg, argsArg, optsArg) {
+  const usesObjectStyle = typeof dirOrOpts === 'object' && dirOrOpts !== null;
+
+  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') {
-    return spawnProc(label, pm.cmd, ['-s', script], env, { ...options, cwd: dir });
+    await run(pm.cmd, ['run', bin, ...args], { cwd: dir, env, stdio });
+    return;
   }
-  return spawnProc(label, pm.cmd, ['--silent', script], env, { ...options, cwd: dir });
+  await run(pm.cmd, ['exec', bin, ...args], { cwd: dir, env, stdio });
 }
 
-export async function pmSpawnBin({ label, dir, bin, args, env, options = {} }) {
+export async function pmSpawnBin(dir, label, bin, args, { env = process.env } = {}) {
   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, ['run', bin, ...args], env, { cwd: dir });
   }
-  return spawnProc(label, pm.cmd, ['exec', bin, ...args], env, { ...options, cwd: dir });
+  return spawnProc(label, pm.cmd, ['exec', bin, ...args], env, { cwd: dir });
 }
 
-export async function pmExecBin({ dir, bin, args, env, quiet = false }) {
+export async function pmSpawnScript(dir, label, script, args, { env = process.env } = {}) {
   const pm = await getComponentPm(dir);
-  const stdio = quiet ? 'ignore' : 'inherit';
   if (pm.name === 'yarn') {
-    await run(pm.cmd, [bin, ...args], { env, cwd: dir, stdio });
-    return;
-  }
-  await run(pm.cmd, ['exec', bin, ...args], { env, cwd: dir, 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).');
+    return spawnProc(label, pm.cmd, ['run', script, ...args], env, { cwd: dir });
   }
-
-  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
-  }
-  await run('launchctl', ['load', '-w', resolvedPlistPath]);
-}
-
-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
-    }
-  }
-  // eslint-disable-next-line no-console
-  console.log(`[local] autostart disabled (${label})`);
+  return spawnProc(label, pm.cmd, ['run', script, ...args], env, { cwd: dir });
 }

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

@@ -132,3 +132,4 @@ export async function runCapture(cmd, args, options = {}) {
     });
   });
 }
+

package/scripts/utils/{happy_server_infra.mjs → server/infra/happy_server_infra.mjs}

@@ -1,50 +1,18 @@
-import { randomBytes } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 
-import { parseDotenv } from './dotenv.mjs';
-import { ensureEnvFileUpdated } from './env_file.mjs';
-import { pickNextFreeTcpPort } from './ports.mjs';
-import { pmExecBin } from './pm.mjs';
-import { run, runCapture } from './proc.mjs';
-
-function base64Url(buf) {
-  return Buffer.from(buf)
-    .toString('base64')
-    .replaceAll('+', '-')
-    .replaceAll('/', '_')
-    .replaceAll('=', '');
-}
-
-function randomToken(lenBytes = 24) {
-  return base64Url(randomBytes(lenBytes));
-}
-
-function sanitizeDnsLabel(raw, { fallback = 'happy' } = {}) {
-  const s = String(raw ?? '')
-    .toLowerCase()
-    .replace(/[^a-z0-9-]+/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^-+/, '')
-    .replace(/-+$/, '');
-  return s || fallback;
-}
+import { ensureEnvFileUpdated } from '../../env/env_file.mjs';
+import { readEnvObjectFromFile } from '../../env/read.mjs';
+import { sanitizeDnsLabel } from '../../net/dns.mjs';
+import { pickNextFreeTcpPort } from '../../net/ports.mjs';
+import { pmExecBin } from '../../proc/pm.mjs';
+import { run, runCapture } from '../../proc/proc.mjs';
+import { randomToken } from '../../crypto/tokens.mjs';
+import { coercePort, INFRA_RESERVED_PORT_KEYS } from '../port.mjs';
 
-function coercePort(v) {
-  const n = typeof v === 'string' ? Number(v) : typeof v === 'number' ? v : NaN;
-  return Number.isFinite(n) && n > 0 ? n : null;
-}
-
-async function readEnvObject(envPath) {
-  try {
-    const raw = await readFile(envPath, 'utf-8');
-    return Object.fromEntries(parseDotenv(raw).entries());
-  } catch {
-    return {};
-  }
-}
+const readEnvObject = readEnvObjectFromFile;
 
 async function ensureTextFile({ path, generate }) {
   if (existsSync(path)) {
@@ -318,14 +286,7 @@ export async function ensureHappyServerManagedInfra({
   const reservedPorts = new Set();
 
   // Reserve known ports (if present) to avoid picking duplicates when auto-filling.
-  for (const key of [
-    'HAPPY_STACKS_SERVER_PORT',
-    'HAPPY_LOCAL_SERVER_PORT',
-    'HAPPY_STACKS_PG_PORT',
-    'HAPPY_STACKS_REDIS_PORT',
-    'HAPPY_STACKS_MINIO_PORT',
-    'HAPPY_STACKS_MINIO_CONSOLE_PORT',
-  ]) {
+  for (const key of INFRA_RESERVED_PORT_KEYS) {
     const p = coercePort(existingEnv[key] ?? env[key]);
     if (p) reservedPorts.add(p);
   }

package/scripts/utils/server/port.mjs

@@ -0,0 +1,68 @@
+import { readEnvValueFromFile } from '../env/read.mjs';
+
+export const STACK_RESERVED_PORT_KEYS = [
+  'HAPPY_STACKS_SERVER_PORT',
+  'HAPPY_LOCAL_SERVER_PORT',
+  'HAPPY_STACKS_HAPPY_SERVER_BACKEND_PORT',
+  'HAPPY_LOCAL_HAPPY_SERVER_BACKEND_PORT',
+  'HAPPY_STACKS_PG_PORT',
+  'HAPPY_STACKS_REDIS_PORT',
+  'HAPPY_STACKS_MINIO_PORT',
+  'HAPPY_STACKS_MINIO_CONSOLE_PORT',
+];
+
+export const INFRA_RESERVED_PORT_KEYS = [
+  'HAPPY_STACKS_SERVER_PORT',
+  'HAPPY_LOCAL_SERVER_PORT',
+  'HAPPY_STACKS_PG_PORT',
+  'HAPPY_STACKS_REDIS_PORT',
+  'HAPPY_STACKS_MINIO_PORT',
+  'HAPPY_STACKS_MINIO_CONSOLE_PORT',
+];
+
+export function coercePort(v) {
+  const s = String(v ?? '').trim();
+  if (!s) return null;
+  const n = Number(s);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+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);
+}
+
+export function listPortsFromEnvObject(env, keys) {
+  const obj = env && typeof env === 'object' ? env : {};
+  const list = Array.isArray(keys) ? keys : [];
+  const out = [];
+  for (const k of list) {
+    const p = coercePort(obj[k]);
+    if (p) out.push(p);
+  }
+  return out;
+}
+
+export async function readServerPortFromEnvFile(envPath, { defaultPort = 3005 } = {}) {
+  const v =
+    (await readEnvValueFromFile(envPath, 'HAPPY_STACKS_SERVER_PORT')) ||
+    (await readEnvValueFromFile(envPath, 'HAPPY_LOCAL_SERVER_PORT')) ||
+    '';
+  const n = v ? Number(String(v).trim()) : Number(defaultPort);
+  return Number.isFinite(n) && n > 0 ? n : Number(defaultPort);
+}
+
+// For stack env files, "missing" means "ephemeral stack" (no pinned port).
+export async function readPinnedServerPortFromEnvFile(envPath) {
+  const v =
+    (await readEnvValueFromFile(envPath, 'HAPPY_STACKS_SERVER_PORT')) ||
+    (await readEnvValueFromFile(envPath, 'HAPPY_LOCAL_SERVER_PORT')) ||
+    '';
+  const n = v ? Number(String(v).trim()) : NaN;
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+

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

@@ -59,6 +59,18 @@ export async function isHappyServerRunning(baseUrl) {
   return true;
 }
 
+export async function waitForHappyHealthOk(baseUrl, { timeoutMs = 60_000, intervalMs = 300 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    // eslint-disable-next-line no-await-in-loop
+    const health = await fetchHappyHealth(baseUrl);
+    if (health.ok) return true;
+    // eslint-disable-next-line no-await-in-loop
+    await delay(intervalMs);
+  }
+  return false;
+}
+
 export async function waitForServerReady(url) {
   const deadline = Date.now() + 60_000;
   while (Date.now() < deadline) {