happy-stacks 0.0.0 → 0.1.2

package/scripts/utils/happy_server_infra.mjs

@@ -0,0 +1,430 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import net from 'node:net';
+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 { 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;
+}
+
+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 isPortFree(port) {
+  return await new Promise((resolvePromise) => {
+    const srv = net.createServer();
+    srv.unref();
+    srv.on('error', () => resolvePromise(false));
+    srv.listen({ port, host: '127.0.0.1' }, () => {
+      srv.close(() => resolvePromise(true));
+    });
+  });
+}
+
+async function pickNextFreePort(startPort, { reservedPorts = new Set() } = {}) {
+  let port = startPort;
+  for (let i = 0; i < 200; i++) {
+    // eslint-disable-next-line no-await-in-loop
+    if (!reservedPorts.has(port) && (await isPortFree(port))) {
+      return port;
+    }
+    port += 1;
+  }
+  throw new Error(`[infra] unable to find a free port starting at ${startPort}`);
+}
+
+async function readEnvObject(envPath) {
+  try {
+    const raw = await readFile(envPath, 'utf-8');
+    return Object.fromEntries(parseDotenv(raw).entries());
+  } catch {
+    return {};
+  }
+}
+
+async function ensureTextFile({ path, generate }) {
+  if (existsSync(path)) {
+    const v = (await readFile(path, 'utf-8')).trim();
+    if (v) return v;
+  }
+  const next = String(generate()).trim();
+  await mkdir(join(path, '..'), { recursive: true }).catch(() => {});
+  await writeFile(path, next + '\n', 'utf-8');
+  return next;
+}
+
+function composeProjectName(stackName) {
+  return sanitizeDnsLabel(`happy-stacks-${stackName}-happy-server`, { fallback: 'happy-stacks-happy-server' });
+}
+
+export async function stopHappyServerManagedInfra({ stackName, baseDir, removeVolumes = false }) {
+  const infraDir = join(baseDir, 'happy-server', 'infra');
+  const composePath = join(infraDir, 'docker-compose.yml');
+  if (!existsSync(composePath)) {
+    return { ok: true, skipped: true, reason: 'missing_compose', composePath };
+  }
+
+  try {
+    await ensureDockerCompose();
+  } catch (e) {
+    return {
+      ok: false,
+      skipped: true,
+      reason: 'docker_unavailable',
+      error: e instanceof Error ? e.message : String(e),
+      composePath,
+    };
+  }
+
+  const projectName = composeProjectName(stackName);
+  const args = ['down', '--remove-orphans', ...(removeVolumes ? ['--volumes'] : [])];
+  await dockerCompose({ composePath, projectName, args, options: { cwd: baseDir } });
+  return { ok: true, skipped: false, projectName, composePath };
+}
+
+function buildComposeYaml({
+  infraDir,
+  pgPort,
+  pgUser,
+  pgPassword,
+  pgDb,
+  redisPort,
+  minioPort,
+  minioConsolePort,
+  s3AccessKey,
+  s3SecretKey,
+  s3Bucket,
+}) {
+  // Keep it explicit (no env substitution); we generate this file per stack.
+  return `services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: ${pgUser}
+      POSTGRES_PASSWORD: ${pgPassword}
+      POSTGRES_DB: ${pgDb}
+    ports:
+      - "127.0.0.1:${pgPort}:5432"
+    volumes:
+      - "${join(infraDir, 'pgdata')}:/var/lib/postgresql/data"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${pgUser} -d ${pgDb}"]
+      interval: 2s
+      timeout: 3s
+      retries: 30
+
+  redis:
+    image: redis:7-alpine
+    command: ["redis-server", "--appendonly", "yes"]
+    ports:
+      - "127.0.0.1:${redisPort}:6379"
+    volumes:
+      - "${join(infraDir, 'redis')}:/data"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 2s
+      timeout: 3s
+      retries: 30
+
+  minio:
+    image: minio/minio:latest
+    command: ["server", "/data", "--console-address", ":9001"]
+    environment:
+      MINIO_ROOT_USER: ${s3AccessKey}
+      MINIO_ROOT_PASSWORD: ${s3SecretKey}
+    ports:
+      - "127.0.0.1:${minioPort}:9000"
+      - "127.0.0.1:${minioConsolePort}:9001"
+    volumes:
+      - "${join(infraDir, 'minio')}:/data"
+
+  minio-init:
+    image: minio/mc:latest
+    depends_on:
+      - minio
+    entrypoint: ["/bin/sh", "-lc"]
+    command: >
+      mc alias set local http://minio:9000 ${s3AccessKey} ${s3SecretKey} &&
+      mc mb -p local/${s3Bucket} || true &&
+      mc anonymous set download local/${s3Bucket} || true
+    restart: "no"
+`;
+}
+
+async function ensureDockerCompose() {
+  const waitMsRaw = (process.env.HAPPY_STACKS_DOCKER_WAIT_MS ?? process.env.HAPPY_LOCAL_DOCKER_WAIT_MS ?? '').trim();
+  const waitMs = waitMsRaw ? Number(waitMsRaw) : process.stdout.isTTY ? 0 : 60_000;
+  const deadline = waitMs > 0 ? Date.now() + waitMs : Date.now();
+
+  try {
+    await runCapture('docker', ['compose', 'version'], { timeoutMs: 10_000 });
+  } catch (e) {
+    const msg = e?.message ? String(e.message) : String(e);
+    throw new Error(
+      `[infra] docker compose is required for managed happy-server stacks.\n` +
+        `Fix: install Docker Desktop and ensure \`docker compose\` works.\n` +
+        `Details: ${msg}`
+    );
+  }
+
+  const autostartRaw = (process.env.HAPPY_STACKS_DOCKER_AUTOSTART ?? process.env.HAPPY_LOCAL_DOCKER_AUTOSTART ?? '').trim();
+  const autostart = autostartRaw ? autostartRaw !== '0' : !process.stdout.isTTY;
+
+  // Ensure the Docker daemon is ready (launchd/SwiftBar often runs before Docker Desktop starts).
+  // If not ready, wait up to waitMs (non-interactive default: 60s) to avoid restart loops.
+  while (true) {
+    try {
+      await runCapture('docker', ['info'], { timeoutMs: 10_000 });
+      return;
+    } catch (e) {
+      if (autostart) {
+        await maybeStartDockerDaemon().catch(() => {});
+      }
+      if (Date.now() >= deadline) {
+        const msg = e?.message ? String(e.message) : String(e);
+        throw new Error(
+          `[infra] docker is installed but the daemon is not ready.\n` +
+            `Fix: start Docker Desktop, or disable managed infra (HAPPY_STACKS_MANAGED_INFRA=0).\n` +
+            `You can also increase wait time with HAPPY_STACKS_DOCKER_WAIT_MS, or disable auto-start with HAPPY_STACKS_DOCKER_AUTOSTART=0.\n` +
+            `Details: ${msg}`
+        );
+      }
+      // eslint-disable-next-line no-await-in-loop
+      await delay(1000);
+    }
+  }
+}
+
+async function maybeStartDockerDaemon() {
+  // Best-effort. This may be a no-op depending on platform/permissions.
+  if (process.platform === 'darwin') {
+    const app = (process.env.HAPPY_STACKS_DOCKER_APP ?? process.env.HAPPY_LOCAL_DOCKER_APP ?? '/Applications/Docker.app').trim();
+    // `open` exits quickly; Docker Desktop will start in the background.
+    await runCapture('open', ['-gj', '-a', app], { timeoutMs: 5_000 }).catch(() => {});
+    return;
+  }
+
+  if (process.platform === 'linux') {
+    // Rootless / Docker Desktop / system Docker can differ. Try a few user-scope units first.
+    const candidates = ['docker.service', 'docker.socket', 'docker-desktop.service', 'docker-desktop'];
+    for (const unit of candidates) {
+      // eslint-disable-next-line no-await-in-loop
+      await runCapture('systemctl', ['--user', 'start', unit], { timeoutMs: 5_000 }).catch(() => {});
+    }
+    // As a last resort, try system scope (may fail without sudo; ignore).
+    await runCapture('systemctl', ['start', 'docker'], { timeoutMs: 5_000 }).catch(() => {});
+  }
+}
+
+async function dockerCompose({ composePath, projectName, args, options = {} }) {
+  await run('docker', ['compose', '-f', composePath, '-p', projectName, ...args], options);
+}
+
+async function waitForHealthyPostgres({ composePath, projectName, pgUser, pgDb }) {
+  const deadline = Date.now() + 60_000;
+  while (Date.now() < deadline) {
+    try {
+      await runCapture(
+        'docker',
+        ['compose', '-f', composePath, '-p', projectName, 'exec', '-T', 'postgres', 'pg_isready', '-U', pgUser, '-d', pgDb],
+        { timeoutMs: 5_000 }
+      );
+      return;
+    } catch {
+      // ignore
+    }
+    // eslint-disable-next-line no-await-in-loop
+    await delay(800);
+  }
+  throw new Error('[infra] timed out waiting for postgres to become ready');
+}
+
+async function waitForHealthyRedis({ composePath, projectName }) {
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    try {
+      const out = await runCapture('docker', ['compose', '-f', composePath, '-p', projectName, 'exec', '-T', 'redis', 'redis-cli', 'ping'], {
+        timeoutMs: 5_000,
+      });
+      if (out.trim().toUpperCase().includes('PONG')) {
+        return;
+      }
+    } catch {
+      // ignore
+    }
+    // eslint-disable-next-line no-await-in-loop
+    await delay(600);
+  }
+  throw new Error('[infra] timed out waiting for redis to become ready');
+}
+
+export async function ensureHappyServerManagedInfra({
+  stackName,
+  baseDir,
+  serverPort,
+  publicServerUrl,
+  envPath,
+  env = process.env,
+}) {
+  await ensureDockerCompose();
+
+  const infraDir = join(baseDir, 'happy-server', 'infra');
+  await mkdir(infraDir, { recursive: true });
+
+  const existingEnv = envPath ? await readEnvObject(envPath) : {};
+  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',
+  ]) {
+    const p = coercePort(existingEnv[key] ?? env[key]);
+    if (p) reservedPorts.add(p);
+  }
+  if (Number.isFinite(serverPort) && serverPort > 0) reservedPorts.add(serverPort);
+
+  const pgPort = coercePort(existingEnv.HAPPY_STACKS_PG_PORT ?? env.HAPPY_STACKS_PG_PORT) ?? (await pickNextFreePort(serverPort + 1000, { reservedPorts }));
+  reservedPorts.add(pgPort);
+  const redisPort =
+    coercePort(existingEnv.HAPPY_STACKS_REDIS_PORT ?? env.HAPPY_STACKS_REDIS_PORT) ?? (await pickNextFreePort(pgPort + 1, { reservedPorts }));
+  reservedPorts.add(redisPort);
+  const minioPort =
+    coercePort(existingEnv.HAPPY_STACKS_MINIO_PORT ?? env.HAPPY_STACKS_MINIO_PORT) ?? (await pickNextFreePort(redisPort + 1, { reservedPorts }));
+  reservedPorts.add(minioPort);
+  const minioConsolePort =
+    coercePort(existingEnv.HAPPY_STACKS_MINIO_CONSOLE_PORT ?? env.HAPPY_STACKS_MINIO_CONSOLE_PORT) ??
+    (await pickNextFreePort(minioPort + 1, { reservedPorts }));
+  reservedPorts.add(minioConsolePort);
+
+  const pgUser = (existingEnv.HAPPY_STACKS_PG_USER ?? env.HAPPY_STACKS_PG_USER ?? 'handy').trim() || 'handy';
+  const pgPassword = (existingEnv.HAPPY_STACKS_PG_PASSWORD ?? env.HAPPY_STACKS_PG_PASSWORD ?? '').trim() || randomToken(24);
+  const pgDb = (existingEnv.HAPPY_STACKS_PG_DATABASE ?? env.HAPPY_STACKS_PG_DATABASE ?? 'handy').trim() || 'handy';
+
+  const s3Bucket =
+    (existingEnv.S3_BUCKET ?? env.S3_BUCKET ?? '').trim() || sanitizeDnsLabel(`happy-${stackName}`, { fallback: 'happy' });
+  const s3AccessKey = (existingEnv.S3_ACCESS_KEY ?? env.S3_ACCESS_KEY ?? '').trim() || randomToken(12);
+  const s3SecretKey = (existingEnv.S3_SECRET_KEY ?? env.S3_SECRET_KEY ?? '').trim() || randomToken(24);
+
+  const secretFile = (existingEnv.HAPPY_STACKS_HANDY_MASTER_SECRET_FILE ?? env.HAPPY_STACKS_HANDY_MASTER_SECRET_FILE ?? '').trim()
+    ? (existingEnv.HAPPY_STACKS_HANDY_MASTER_SECRET_FILE ?? env.HAPPY_STACKS_HANDY_MASTER_SECRET_FILE).trim()
+    : join(baseDir, 'happy-server', 'handy-master-secret.txt');
+  const handyMasterSecret = (existingEnv.HANDY_MASTER_SECRET ?? env.HANDY_MASTER_SECRET ?? '').trim()
+    ? (existingEnv.HANDY_MASTER_SECRET ?? env.HANDY_MASTER_SECRET).trim()
+    : await ensureTextFile({ path: secretFile, generate: () => randomToken(32) });
+
+  const databaseUrl = `postgresql://${encodeURIComponent(pgUser)}:${encodeURIComponent(pgPassword)}@127.0.0.1:${pgPort}/${encodeURIComponent(pgDb)}`;
+  const redisUrl = `redis://127.0.0.1:${redisPort}`;
+  const s3Host = '127.0.0.1';
+  const s3UseSsl = 'false';
+  const pub = String(publicServerUrl ?? '').trim().replace(/\/+$/, '');
+  if (!pub) {
+    throw new Error('[infra] publicServerUrl is required for managed infra (to set S3_PUBLIC_URL)');
+  }
+  const s3PublicUrl = `${pub}/files`;
+
+  if (envPath) {
+    await ensureEnvFileUpdated({
+      envPath,
+      updates: [
+        { key: 'HAPPY_STACKS_PG_PORT', value: String(pgPort) },
+        { key: 'HAPPY_STACKS_REDIS_PORT', value: String(redisPort) },
+        { key: 'HAPPY_STACKS_MINIO_PORT', value: String(minioPort) },
+        { key: 'HAPPY_STACKS_MINIO_CONSOLE_PORT', value: String(minioConsolePort) },
+        { key: 'HAPPY_STACKS_PG_USER', value: pgUser },
+        { key: 'HAPPY_STACKS_PG_PASSWORD', value: pgPassword },
+        { key: 'HAPPY_STACKS_PG_DATABASE', value: pgDb },
+        { key: 'HAPPY_STACKS_HANDY_MASTER_SECRET_FILE', value: secretFile },
+        // Vars consumed by happy-server:
+        { key: 'DATABASE_URL', value: databaseUrl },
+        { key: 'REDIS_URL', value: redisUrl },
+        { key: 'S3_HOST', value: s3Host },
+        { key: 'S3_PORT', value: String(minioPort) },
+        { key: 'S3_USE_SSL', value: s3UseSsl },
+        { key: 'S3_ACCESS_KEY', value: s3AccessKey },
+        { key: 'S3_SECRET_KEY', value: s3SecretKey },
+        { key: 'S3_BUCKET', value: s3Bucket },
+        { key: 'S3_PUBLIC_URL', value: s3PublicUrl },
+      ],
+    });
+  }
+
+  const composePath = join(infraDir, 'docker-compose.yml');
+  const projectName = composeProjectName(stackName);
+  const yaml = buildComposeYaml({
+    infraDir,
+    pgPort,
+    pgUser,
+    pgPassword,
+    pgDb,
+    redisPort,
+    minioPort,
+    minioConsolePort,
+    s3AccessKey,
+    s3SecretKey,
+    s3Bucket,
+  });
+  await writeFile(composePath, yaml, 'utf-8');
+
+  await dockerCompose({ composePath, projectName, args: ['up', '-d', '--remove-orphans'], options: { cwd: baseDir } });
+  await waitForHealthyPostgres({ composePath, projectName, pgUser, pgDb });
+  await waitForHealthyRedis({ composePath, projectName });
+
+  // Ensure bucket exists (idempotent)
+  await dockerCompose({ composePath, projectName, args: ['run', '--rm', 'minio-init'], options: { cwd: baseDir } });
+
+  return {
+    composePath,
+    projectName,
+    infraDir,
+    env: {
+      DATABASE_URL: databaseUrl,
+      REDIS_URL: redisUrl,
+      S3_HOST: s3Host,
+      S3_PORT: String(minioPort),
+      S3_USE_SSL: s3UseSsl,
+      S3_ACCESS_KEY: s3AccessKey,
+      S3_SECRET_KEY: s3SecretKey,
+      S3_BUCKET: s3Bucket,
+      S3_PUBLIC_URL: s3PublicUrl,
+      HANDY_MASTER_SECRET: handyMasterSecret,
+    },
+  };
+}
+
+export async function applyHappyServerMigrations({ serverDir, env }) {
+  // Non-interactive + idempotent. Safe for dev; also safe for managed stacks on start.
+  await pmExecBin({ dir: serverDir, bin: 'prisma', args: ['migrate', 'deploy'], env });
+}
+

package/scripts/utils/pm.mjs

@@ -180,6 +180,14 @@ export async function pmSpawnScript({ label, dir, script, env, options = {} }) {
   return spawnProc(label, pm.cmd, ['--silent', script], env, { ...options, cwd: dir });
 }
 
+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 }) {
   const pm = await getComponentPm(dir);
   if (pm.name === 'yarn') {
@@ -217,6 +225,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 +243,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

@@ -39,28 +39,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/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) {