happy-stacks 0.1.0 → 0.2.0

package/scripts/utils/stack_runtime_state.mjs

@@ -0,0 +1,104 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { resolveStackEnvPath } from './paths.mjs';
+
+export function getStackRuntimeStatePath(stackName) {
+  const { baseDir } = resolveStackEnvPath(stackName);
+  return join(baseDir, 'stack.runtime.json');
+}
+
+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;
+  }
+}
+
+export async function readStackRuntimeStateFile(statePath) {
+  try {
+    if (!statePath || !existsSync(statePath)) return null;
+    const raw = await readFile(statePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeStackRuntimeStateFile(statePath, state) {
+  if (!statePath) {
+    throw new Error('[stack] missing runtime state path');
+  }
+  const dir = dirname(statePath);
+  await mkdir(dir, { recursive: true }).catch(() => {});
+  const tmp = join(dir, `.stack.runtime.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
+  await writeFile(tmp, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+  await rename(tmp, statePath);
+}
+
+function isPlainObject(v) {
+  return Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+}
+
+function deepMerge(a, b) {
+  if (!isPlainObject(a) || !isPlainObject(b)) {
+    return b;
+  }
+  const out = { ...a };
+  for (const [k, v] of Object.entries(b)) {
+    if (isPlainObject(out[k]) && isPlainObject(v)) {
+      out[k] = deepMerge(out[k], v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+export async function updateStackRuntimeStateFile(statePath, patch) {
+  const existing = (await readStackRuntimeStateFile(statePath)) ?? {};
+  const next = deepMerge(existing, patch ?? {});
+  await writeStackRuntimeStateFile(statePath, next);
+  return next;
+}
+
+export async function recordStackRuntimeStart(statePath, { stackName, script, ephemeral, ownerPid, ports } = {}) {
+  const now = new Date().toISOString();
+  const existing = (await readStackRuntimeStateFile(statePath)) ?? {};
+  const startedAt = typeof existing.startedAt === 'string' && existing.startedAt.trim() ? existing.startedAt : now;
+  const next = deepMerge(existing, {
+    version: 1,
+    stackName,
+    script,
+    ephemeral: Boolean(ephemeral),
+    ownerPid,
+    ports: ports ?? {},
+    startedAt,
+    updatedAt: now,
+  });
+  await writeStackRuntimeStateFile(statePath, next);
+  return next;
+}
+
+export async function recordStackRuntimeUpdate(statePath, patch = {}) {
+  return await updateStackRuntimeStateFile(statePath, {
+    ...(patch ?? {}),
+    updatedAt: new Date().toISOString(),
+  });
+}
+
+export async function deleteStackRuntimeStateFile(statePath) {
+  try {
+    if (!statePath || !existsSync(statePath)) return;
+    await unlink(statePath);
+  } catch {
+    // ignore
+  }
+}
+

package/scripts/utils/stack_startup.mjs

@@ -0,0 +1,208 @@
+import { runCapture } from './proc.mjs';
+import { ensureDepsInstalled, pmExecBin } from './pm.mjs';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+function looksLikeMissingTableError(msg) {
+  const s = String(msg ?? '').toLowerCase();
+  return s.includes('does not exist') || s.includes('no such table');
+}
+
+async function probeAccountCount({ serverDir, env }) {
+  const probe = `
+	let db;
+	try {
+	  const { PrismaClient } = await import('@prisma/client');
+	  db = new PrismaClient();
+	  const accountCount = await db.account.count();
+	  console.log(JSON.stringify({ accountCount }));
+	} catch (e) {
+	  console.log(
+	    JSON.stringify({
+	      error: {
+	        name: e?.name,
+	        message: e?.message,
+	        code: e?.code,
+	      },
+	    })
+	  );
+	} finally {
+	  try {
+	    await db?.$disconnect();
+	  } catch {
+	    // ignore
+	  }
+	}
+	`.trim();
+
+  const out = await runCapture(process.execPath, ['--input-type=module', '-e', probe], { cwd: serverDir, env, timeoutMs: 15_000 });
+  const parsed = out.trim() ? JSON.parse(out.trim()) : {};
+  if (parsed?.error) {
+    const e = new Error(parsed.error.message || 'unknown prisma probe error');
+    if (typeof parsed.error.name === 'string' && parsed.error.name) e.name = parsed.error.name;
+    if (typeof parsed.error.code === 'string' && parsed.error.code) e.code = parsed.error.code;
+    throw e;
+  }
+  return Number(parsed.accountCount ?? 0);
+}
+
+export function resolveAutoCopyFromMainEnabled({ env, stackName, isInteractive }) {
+  const raw = (env.HAPPY_STACKS_AUTO_AUTH_SEED ?? env.HAPPY_LOCAL_AUTO_AUTH_SEED ?? '').toString().trim();
+  if (raw) return raw !== '0';
+
+  // Legacy toggle (kept for existing setups):
+  // - if set, it only controls enable/disable; source stack remains configurable via HAPPY_STACKS_AUTH_SEED_FROM.
+  const legacy = (env.HAPPY_STACKS_AUTO_COPY_FROM_MAIN ?? env.HAPPY_LOCAL_AUTO_COPY_FROM_MAIN ?? '').toString().trim();
+  if (legacy) return legacy !== '0';
+
+  if (stackName === 'main') return false;
+
+  // Default:
+  // - always auto-seed in non-interactive contexts (agents/services)
+  // - in interactive shells, auto-seed only when the user explicitly configured a non-main seed stack
+  //   (this avoids silently spreading main identity for users who haven't opted in yet).
+  if (!isInteractive) return true;
+  const seed = (env.HAPPY_STACKS_AUTH_SEED_FROM ?? env.HAPPY_LOCAL_AUTH_SEED_FROM ?? '').toString().trim();
+  return Boolean(seed && seed !== 'main');
+}
+
+export function resolveAuthSeedFromEnv(env) {
+  // Back-compat for an earlier experimental var name:
+  // - if set to a non-bool-ish stack name, treat it as the seed source
+  // - if set to "1"/"true", ignore (source comes from HAPPY_STACKS_AUTH_SEED_FROM)
+  const legacyAutoFrom = (env.HAPPY_STACKS_AUTO_AUTH_SEED_FROM ?? env.HAPPY_LOCAL_AUTO_AUTH_SEED_FROM ?? '').toString().trim();
+  if (legacyAutoFrom && legacyAutoFrom !== '0' && legacyAutoFrom !== '1' && legacyAutoFrom.toLowerCase() !== 'true') {
+    return legacyAutoFrom;
+  }
+  // Legacy toggle: "on" implies main (historical behavior).
+  const legacy = (env.HAPPY_STACKS_AUTO_COPY_FROM_MAIN ?? env.HAPPY_LOCAL_AUTO_COPY_FROM_MAIN ?? '').toString().trim();
+  if (legacy && legacy !== '0') return 'main';
+  // Otherwise, use the general default seed stack.
+  const seed = (env.HAPPY_STACKS_AUTH_SEED_FROM ?? env.HAPPY_LOCAL_AUTH_SEED_FROM ?? '').toString().trim();
+  return seed || 'main';
+}
+
+export async function ensureServerLightSchemaReady({ serverDir, env }) {
+  await ensureDepsInstalled(serverDir, 'happy-server-light');
+
+  try {
+    const accountCount = await probeAccountCount({ serverDir, env });
+    return { ok: true, pushed: false, accountCount };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (!looksLikeMissingTableError(msg)) {
+      throw e;
+    }
+    await pmExecBin({ dir: serverDir, bin: 'prisma', args: ['db', 'push'], env });
+    const accountCount = await probeAccountCount({ serverDir, env });
+    return { ok: true, pushed: true, accountCount };
+  }
+}
+
+export async function ensureHappyServerSchemaReady({ serverDir, env }) {
+  await ensureDepsInstalled(serverDir, 'happy-server');
+
+  try {
+    const accountCount = await probeAccountCount({ serverDir, env });
+    return { ok: true, migrated: false, accountCount };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (!looksLikeMissingTableError(msg)) {
+      throw e;
+    }
+    // If tables are missing, try migrations (safe for postgres). Then re-probe.
+    await pmExecBin({ dir: serverDir, bin: 'prisma', args: ['migrate', 'deploy'], env });
+    const accountCount = await probeAccountCount({ serverDir, env });
+    return { ok: true, migrated: true, accountCount };
+  }
+}
+
+export async function getAccountCountForServerComponent({ serverComponentName, serverDir, env, bestEffort = false }) {
+  if (serverComponentName === 'happy-server-light') {
+    const ready = await ensureServerLightSchemaReady({ serverDir, env });
+    return { ok: true, accountCount: Number.isFinite(ready.accountCount) ? ready.accountCount : 0 };
+  }
+  if (serverComponentName === 'happy-server') {
+    try {
+      const ready = await ensureHappyServerSchemaReady({ serverDir, env });
+      return { ok: true, accountCount: Number.isFinite(ready.accountCount) ? ready.accountCount : 0 };
+    } catch (e) {
+      if (!bestEffort) throw e;
+      return { ok: false, accountCount: null, error: e instanceof Error ? e.message : String(e) };
+    }
+  }
+  return { ok: false, accountCount: null, error: `unknown server component: ${serverComponentName}` };
+}
+
+export async function maybeAutoCopyAuthFromMainIfNeeded({
+  rootDir,
+  env,
+  enabled,
+  stackName,
+  cliHomeDir,
+  accountCount,
+  quiet = false,
+  authEnv = null,
+}) {
+  const accessKeyPath = join(cliHomeDir, 'access.key');
+  const hasAccessKey = existsSync(accessKeyPath);
+
+  // "Initialized" heuristic:
+  // - if we have credentials AND (when known) at least one Account row, we don't need to seed from main.
+  const hasAccounts = typeof accountCount === 'number' ? accountCount > 0 : null;
+  const needsSeed = !hasAccessKey || hasAccounts === false;
+
+  if (!enabled || !needsSeed) {
+    return { ok: true, skipped: true, reason: !enabled ? 'disabled' : 'already_initialized' };
+  }
+
+  const reason = !hasAccessKey ? 'missing_credentials' : 'no_accounts';
+  const fromStackName = resolveAuthSeedFromEnv(env);
+  const linkAuth =
+    (env.HAPPY_STACKS_AUTH_LINK ?? env.HAPPY_LOCAL_AUTH_LINK ?? '').toString().trim() === '1' ||
+    (env.HAPPY_STACKS_AUTH_MODE ?? env.HAPPY_LOCAL_AUTH_MODE ?? '').toString().trim() === 'link';
+  if (!quiet) {
+    console.log(`[local] auth: auto seed from ${fromStackName} for ${stackName} (${reason})`);
+  }
+
+  // Best-effort: copy credentials/master secret + seed accounts from the configured seed stack.
+  // Keep this non-fatal; the daemon will emit actionable errors if it still can't authenticate.
+  try {
+    const out = await runCapture(
+      process.execPath,
+      [`${rootDir}/scripts/auth.mjs`, 'copy-from', fromStackName, '--json', ...(linkAuth ? ['--link'] : [])],
+      {
+      cwd: rootDir,
+      env: authEnv && typeof authEnv === 'object' ? authEnv : env,
+      }
+    );
+    return { ok: true, skipped: false, reason, out: out.trim() ? JSON.parse(out) : null };
+  } catch (e) {
+    return { ok: false, skipped: false, reason, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+export async function prepareDaemonAuthSeedIfNeeded({
+  rootDir,
+  env,
+  stackName,
+  cliHomeDir,
+  startDaemon,
+  isInteractive,
+  accountCount,
+  quiet = false,
+  authEnv = null,
+}) {
+  if (!startDaemon) return { ok: true, skipped: true, reason: 'no_daemon' };
+  const enabled = resolveAutoCopyFromMainEnabled({ env, stackName, isInteractive });
+  return await maybeAutoCopyAuthFromMainIfNeeded({
+    rootDir,
+    env,
+    enabled,
+    stackName,
+    cliHomeDir,
+    accountCount,
+    quiet,
+    authEnv,
+  });
+}

package/scripts/utils/stack_stop.mjs

@@ -0,0 +1,255 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { getComponentDir } from './paths.mjs';
+import { isPidAlive, readPidState } from './expo.mjs';
+import { stopLocalDaemon } from '../daemon.mjs';
+import { stopHappyServerManagedInfra } from './happy_server_infra.mjs';
+import { deleteStackRuntimeStateFile, getStackRuntimeStatePath, readStackRuntimeStateFile } from './stack_runtime_state.mjs';
+import { killPidOwnedByStack, killProcessGroupOwnedByStack, listPidsWithEnvNeedle } from './ownership.mjs';
+
+function parseIntOrNull(raw) {
+  const s = String(raw ?? '').trim();
+  if (!s) return null;
+  const n = Number(s);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+function resolveServerComponentFromStackEnv(env) {
+  const v =
+    (env.HAPPY_STACKS_SERVER_COMPONENT ?? env.HAPPY_LOCAL_SERVER_COMPONENT ?? '').toString().trim() || 'happy-server-light';
+  return v === 'happy-server' ? 'happy-server' : 'happy-server-light';
+}
+
+async function daemonControlPost({ httpPort, path, body = {} }) {
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort(), 1500);
+  try {
+    const res = await fetch(`http://127.0.0.1:${httpPort}${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: ctl.signal,
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      throw new Error(`daemon control ${path} failed (http ${res.status}): ${text.trim()}`);
+    }
+    return text.trim() ? JSON.parse(text) : null;
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+async function stopDaemonTrackedSessions({ cliHomeDir, json }) {
+  // Read daemon state file written by happy-cli; needed to call control server (/list, /stop-session).
+  const statePath = join(cliHomeDir, 'daemon.state.json');
+  if (!existsSync(statePath)) {
+    return { ok: true, skipped: true, reason: 'missing_state', stoppedSessionIds: [] };
+  }
+
+  let state = null;
+  try {
+    state = JSON.parse(await readFile(statePath, 'utf-8'));
+  } catch {
+    return { ok: false, skipped: true, reason: 'bad_state', stoppedSessionIds: [] };
+  }
+
+  const httpPort = Number(state?.httpPort);
+  const pid = Number(state?.pid);
+  if (!Number.isFinite(httpPort) || httpPort <= 0) {
+    return { ok: false, skipped: true, reason: 'missing_http_port', stoppedSessionIds: [] };
+  }
+  if (!Number.isFinite(pid) || pid <= 1) {
+    return { ok: false, skipped: true, reason: 'missing_pid', stoppedSessionIds: [] };
+  }
+  try {
+    process.kill(pid, 0);
+  } catch {
+    return { ok: true, skipped: true, reason: 'daemon_not_running', stoppedSessionIds: [] };
+  }
+
+  const listed = await daemonControlPost({ httpPort, path: '/list' }).catch((e) => {
+    if (!json) console.warn(`[stack] failed to list daemon sessions: ${e instanceof Error ? e.message : String(e)}`);
+    return null;
+  });
+  const children = Array.isArray(listed?.children) ? listed.children : [];
+
+  const stoppedSessionIds = [];
+  for (const child of children) {
+    const sid = String(child?.happySessionId ?? '').trim();
+    if (!sid) continue;
+    // eslint-disable-next-line no-await-in-loop
+    const res = await daemonControlPost({ httpPort, path: '/stop-session', body: { sessionId: sid } }).catch(() => null);
+    if (res?.success) {
+      stoppedSessionIds.push(sid);
+    }
+  }
+
+  return { ok: true, skipped: false, stoppedSessionIds };
+}
+
+async function stopExpoStateDir({ stackName, baseDir, kind, stateFileName, envPath, json }) {
+  const root = join(baseDir, kind);
+  let entries = [];
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    entries = [];
+  }
+
+  const killed = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const statePath = join(root, e.name, stateFileName);
+    // eslint-disable-next-line no-await-in-loop
+    const state = await readPidState(statePath);
+    if (!state) continue;
+    const pid = Number(state.pid);
+
+    if (!Number.isFinite(pid) || pid <= 1) continue;
+    if (!isPidAlive(pid)) continue;
+
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.log(`[stack] stopping ${kind} (pid=${pid}) for ${stackName}`);
+    }
+    // eslint-disable-next-line no-await-in-loop
+    await killProcessGroupOwnedByStack(pid, { stackName, envPath, label: kind, json });
+    killed.push({ pid, port: null, statePath });
+  }
+  return killed;
+}
+
+export async function stopStackWithEnv({ rootDir, stackName, baseDir, env, json, noDocker = false, aggressive = false, sweepOwned = false }) {
+  const actions = {
+    stackName,
+    baseDir,
+    aggressive,
+    sweepOwned,
+    runner: null,
+    daemonSessionsStopped: null,
+    daemonStopped: false,
+    killedPorts: [],
+    uiDev: [],
+    mobile: [],
+    infra: null,
+    errors: [],
+  };
+
+  const serverComponent = resolveServerComponentFromStackEnv(env);
+  const port = parseIntOrNull(env.HAPPY_STACKS_SERVER_PORT ?? env.HAPPY_LOCAL_SERVER_PORT);
+  const backendPort = parseIntOrNull(env.HAPPY_STACKS_HAPPY_SERVER_BACKEND_PORT ?? env.HAPPY_LOCAL_HAPPY_SERVER_BACKEND_PORT);
+  const cliHomeDir = (env.HAPPY_STACKS_CLI_HOME_DIR ?? env.HAPPY_LOCAL_CLI_HOME_DIR ?? join(baseDir, 'cli')).toString();
+  const cliBin = join(getComponentDir(rootDir, 'happy-cli'), 'bin', 'happy.mjs');
+  const envPath = (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString();
+
+  // Preferred: stop stack-started processes (by PID) recorded in stack.runtime.json.
+  // This is safer than killing whatever happens to listen on a port, and doesn't rely on the runner's shutdown handler.
+  const runtimeStatePath = getStackRuntimeStatePath(stackName);
+  const runtimeState = await readStackRuntimeStateFile(runtimeStatePath);
+  const runnerPid = Number(runtimeState?.ownerPid);
+  const processes = runtimeState?.processes && typeof runtimeState.processes === 'object' ? runtimeState.processes : {};
+
+  // Kill known child processes first (process groups), then stop daemon, then stop runner.
+  const killedProcessPids = [];
+  for (const [key, rawPid] of Object.entries(processes)) {
+    const pid = Number(rawPid);
+    if (!Number.isFinite(pid) || pid <= 1) continue;
+    if (!isPidAlive(pid)) continue;
+    // eslint-disable-next-line no-await-in-loop
+    const res = await killProcessGroupOwnedByStack(pid, { stackName, envPath, cliHomeDir, label: key, json });
+    if (res.killed) {
+      killedProcessPids.push({ key, pid, reason: res.reason, pgid: res.pgid ?? null });
+    }
+  }
+  actions.runner = { stopped: false, pid: Number.isFinite(runnerPid) ? runnerPid : null, reason: runtimeState ? 'not_running_or_not_owned' : 'missing_state' };
+  actions.killedPorts = actions.killedPorts ?? [];
+  actions.processes = { killed: killedProcessPids };
+
+  if (aggressive) {
+    try {
+      actions.daemonSessionsStopped = await stopDaemonTrackedSessions({ cliHomeDir, json });
+    } catch (e) {
+      actions.errors.push({ step: 'daemon-sessions', error: e instanceof Error ? e.message : String(e) });
+    }
+  }
+
+  try {
+    const internalServerUrl = port ? `http://127.0.0.1:${port}` : 'http://127.0.0.1:3005';
+    await stopLocalDaemon({ cliBin, internalServerUrl, cliHomeDir });
+    actions.daemonStopped = true;
+  } catch (e) {
+    actions.errors.push({ step: 'daemon', error: e instanceof Error ? e.message : String(e) });
+  }
+
+  // Now stop the runner PID last (if it exists). This should clean up any remaining state files it owns.
+  if (Number.isFinite(runnerPid) && runnerPid > 1 && isPidAlive(runnerPid)) {
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.log(`[stack] stopping runner (pid=${runnerPid}) for ${stackName}`);
+    }
+    const res = await killPidOwnedByStack(runnerPid, { stackName, envPath, cliHomeDir, label: 'runner', json });
+    actions.runner = { stopped: res.killed, pid: runnerPid, reason: res.reason };
+  }
+
+  // Only delete runtime state if the runner is confirmed stopped (or not running).
+  if (!isPidAlive(runnerPid)) {
+    await deleteStackRuntimeStateFile(runtimeStatePath);
+  }
+
+  try {
+    actions.uiDev = await stopExpoStateDir({ stackName, baseDir, kind: 'ui-dev', stateFileName: 'ui.state.json', envPath, json });
+  } catch (e) {
+    actions.errors.push({ step: 'expo-ui', error: e instanceof Error ? e.message : String(e) });
+  }
+  try {
+    actions.mobile = await stopExpoStateDir({ stackName, baseDir, kind: 'mobile', stateFileName: 'expo.state.json', envPath, json });
+  } catch (e) {
+    actions.errors.push({ step: 'expo-mobile', error: e instanceof Error ? e.message : String(e) });
+  }
+
+  // IMPORTANT:
+  // Never kill "whatever is listening on a port" in stack mode.
+  void backendPort;
+  void port;
+
+  const managed = (env.HAPPY_STACKS_MANAGED_INFRA ?? env.HAPPY_LOCAL_MANAGED_INFRA ?? '1').toString().trim() !== '0';
+  if (!noDocker && serverComponent === 'happy-server' && managed) {
+    try {
+      actions.infra = await stopHappyServerManagedInfra({ stackName, baseDir, removeVolumes: false });
+    } catch (e) {
+      actions.errors.push({ step: 'infra', error: e instanceof Error ? e.message : String(e) });
+    }
+  } else {
+    actions.infra = { ok: true, skipped: true, reason: noDocker ? 'no_docker' : 'not_managed_or_not_happy_server' };
+  }
+
+  // Last resort: sweep any remaining processes that still carry this stack env file in their environment.
+  // This is still safe because envPath is unique per stack; we also exclude our own PID.
+  if (sweepOwned && envPath) {
+    const needle1 = `HAPPY_STACKS_ENV_FILE=${envPath}`;
+    const needle2 = `HAPPY_LOCAL_ENV_FILE=${envPath}`;
+    const pids = [
+      ...(await listPidsWithEnvNeedle(needle1)),
+      ...(await listPidsWithEnvNeedle(needle2)),
+    ]
+      .filter((pid) => pid !== process.pid)
+      .filter((pid) => Number.isFinite(pid) && pid > 1);
+
+    const swept = [];
+    for (const pid of Array.from(new Set(pids))) {
+      if (!isPidAlive(pid)) continue;
+      // eslint-disable-next-line no-await-in-loop
+      const res = await killProcessGroupOwnedByStack(pid, { stackName, envPath, cliHomeDir, label: 'sweep', json });
+      if (res.killed) {
+        swept.push({ pid, reason: res.reason, pgid: res.pgid ?? null });
+      }
+    }
+    actions.sweep = { pids: swept };
+  }
+
+  return actions;
+}
+

package/scripts/utils/stacks.mjs

@@ -0,0 +1,38 @@
+import { readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { getLegacyStorageRoot, getStacksStorageRoot } from './paths.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './sandbox.mjs';
+
+export async function listAllStackNames() {
+  const names = new Set(['main']);
+  const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
+  const roots = [
+    // New layout: ~/.happy/stacks/<name>/env
+    getStacksStorageRoot(),
+    // Legacy layout: ~/.happy/local/stacks/<name>/env
+    ...(allowLegacy ? [join(getLegacyStorageRoot(), 'stacks')] : []),
+  ];
+
+  for (const root of roots) {
+    let entries = [];
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      entries = await readdir(root, { withFileTypes: true });
+    } catch {
+      entries = [];
+    }
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue;
+      const name = ent.name;
+      if (!name || name.startsWith('.')) continue;
+      const envPath = join(root, name, 'env');
+      if (existsSync(envPath)) {
+        names.add(name);
+      }
+    }
+  }
+
+  return Array.from(names).sort();
+}

package/scripts/utils/validate.mjs

@@ -1,4 +1,5 @@
-import { resolve, sep } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
 import { getComponentsDir } from './paths.mjs';
 
 function isInside(path, dir) {
@@ -45,3 +46,43 @@ export function assertServerComponentDirMatches({ rootDir, serverComponentName,
   );
 }
 
+function detectPrismaProvider(schemaText) {
+  // Best-effort parse of:
+  // datasource db { provider = "sqlite" ... }
+  const m = schemaText.match(/datasource\s+db\s*\{[\s\S]*?\bprovider\s*=\s*\"([a-zA-Z0-9_-]+)\"/m);
+  return m?.[1] ?? '';
+}
+
+export function assertServerPrismaProviderMatches({ serverComponentName, serverDir }) {
+  const schemaPath = join(serverDir, 'prisma', 'schema.prisma');
+  let schemaText = '';
+  try {
+    schemaText = readFileSync(schemaPath, 'utf-8');
+  } catch {
+    // If it doesn't exist, skip validation; not every server component necessarily uses Prisma.
+    return;
+  }
+
+  const provider = detectPrismaProvider(schemaText);
+  if (!provider) {
+    return;
+  }
+
+  if (serverComponentName === 'happy-server-light' && provider !== 'sqlite') {
+    throw new Error(
+      `[server] happy-server-light expects Prisma datasource provider \"sqlite\", but found \"${provider}\" in:\n` +
+        `- ${schemaPath}\n` +
+        `This usually means you're pointing happy-server-light at an upstream happy-server checkout/PR (Postgres).\n` +
+        `Fix: either switch server flavor to happy-server, or point happy-server-light at a fork checkout that keeps sqlite support.`
+    );
+  }
+
+  if (serverComponentName === 'happy-server' && provider === 'sqlite') {
+    throw new Error(
+      `[server] happy-server expects Prisma datasource provider \"postgresql\", but found \"sqlite\" in:\n` +
+        `- ${schemaPath}\n` +
+        `Fix: either switch server flavor to happy-server-light, or point happy-server at the full-server checkout.`
+    );
+  }
+}
+