happy-stacks 0.1.0 → 0.2.0

package/scripts/utils/happy_server_infra.mjs

@@ -0,0 +1,484 @@
+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;
+}
+
+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 {};
+  }
+}
+
+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 = {}, quiet = false, retries = 0 }) {
+  const cmdArgs = ['compose', '-f', composePath, '-p', projectName, ...args];
+  let attempt = 0;
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    try {
+      if (quiet) {
+        // Capture stderr so callers can surface it in structured JSON errors.
+        await runCapture('docker', cmdArgs, { timeoutMs: 120_000, ...options });
+      } else {
+        await run('docker', cmdArgs, { ...options, stdio: options?.stdio ?? 'inherit' });
+      }
+      return;
+    } catch (e) {
+      if (attempt >= retries) throw e;
+      attempt += 1;
+      // eslint-disable-next-line no-await-in-loop
+      await delay(800);
+    }
+  }
+}
+
+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');
+}
+
+async function waitForMinioReady({ composePath, projectName }) {
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    try {
+      // Minio doesn't ship a healthcheck in our compose; exec'ing a trivial command is a good enough
+      // readiness proxy for running/accepting execs before we run minio-init.
+      await runCapture('docker', ['compose', '-f', composePath, '-p', projectName, 'exec', '-T', 'minio', 'sh', '-lc', 'echo ok'], {
+        timeoutMs: 5_000,
+      });
+      return;
+    } catch {
+      // ignore
+    }
+    // eslint-disable-next-line no-await-in-loop
+    await delay(600);
+  }
+  throw new Error('[infra] timed out waiting for minio to become ready');
+}
+
+export async function ensureHappyServerManagedInfra({
+  stackName,
+  baseDir,
+  serverPort,
+  publicServerUrl,
+  envPath,
+  env = process.env,
+  quiet = false,
+  skipMinioInit = false,
+}) {
+  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 pickNextFreeTcpPort(serverPort + 1000, { reservedPorts }));
+  reservedPorts.add(pgPort);
+  const redisPort =
+    coercePort(existingEnv.HAPPY_STACKS_REDIS_PORT ?? env.HAPPY_STACKS_REDIS_PORT) ??
+    (await pickNextFreeTcpPort(pgPort + 1, { reservedPorts }));
+  reservedPorts.add(redisPort);
+  const minioPort =
+    coercePort(existingEnv.HAPPY_STACKS_MINIO_PORT ?? env.HAPPY_STACKS_MINIO_PORT) ??
+    (await pickNextFreeTcpPort(redisPort + 1, { reservedPorts }));
+  reservedPorts.add(minioPort);
+  const minioConsolePort =
+    coercePort(existingEnv.HAPPY_STACKS_MINIO_CONSOLE_PORT ?? env.HAPPY_STACKS_MINIO_CONSOLE_PORT) ??
+    (await pickNextFreeTcpPort(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) {
+    // Ephemeral stacks should not pin ports in env files. In stack runtime, callers set
+    // HAPPY_STACKS_EPHEMERAL_PORTS=1 (via stack.runtime.json overlay) while the stack owner is alive.
+    //
+    // For offline tooling (e.g. auth seeding) we still want to preserve the invariant:
+    // - non-main stacks are ephemeral-by-default unless the user explicitly pinned ports already.
+    const runtimeEphemeral = (env.HAPPY_STACKS_EPHEMERAL_PORTS ?? env.HAPPY_LOCAL_EPHEMERAL_PORTS ?? '').toString().trim() === '1';
+    const alreadyPinnedPorts =
+      Boolean((existingEnv.HAPPY_STACKS_PG_PORT ?? '').trim()) ||
+      Boolean((existingEnv.HAPPY_STACKS_REDIS_PORT ?? '').trim()) ||
+      Boolean((existingEnv.HAPPY_STACKS_MINIO_PORT ?? '').trim()) ||
+      Boolean((existingEnv.HAPPY_STACKS_MINIO_CONSOLE_PORT ?? '').trim());
+    const ephemeralPorts = runtimeEphemeral || (stackName !== 'main' && !alreadyPinnedPorts);
+    await ensureEnvFileUpdated({
+      envPath,
+      updates: [
+        // Stable credentials/files: persist these so restarts keep the same DB/user and S3 creds.
+        { 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 },
+        { key: 'S3_ACCESS_KEY', value: s3AccessKey },
+        { key: 'S3_SECRET_KEY', value: s3SecretKey },
+        { key: 'S3_BUCKET', value: s3Bucket },
+        // Ports + derived URLs: persist only when ports are explicitly pinned (non-ephemeral mode).
+        ...(ephemeralPorts
+          ? []
+          : [
+              { 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) },
+              // 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_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, stdio: quiet ? 'ignore' : 'inherit' },
+    quiet,
+  });
+  await waitForHealthyPostgres({ composePath, projectName, pgUser, pgDb });
+  await waitForHealthyRedis({ composePath, projectName });
+
+  if (!skipMinioInit) {
+    // Ensure bucket exists (idempotent). This can race with Minio startup; retry a few times.
+    await waitForMinioReady({ composePath, projectName });
+    await dockerCompose({
+      composePath,
+      projectName,
+      args: ['run', '--rm', '--no-deps', 'minio-init'],
+      options: { cwd: baseDir, stdio: quiet ? 'ignore' : 'inherit' },
+      quiet,
+      retries: 3,
+    });
+  }
+
+  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, quiet = false }) {
+  // Non-interactive + idempotent. Safe for dev; also safe for managed stacks on start.
+  await pmExecBin({ dir: serverDir, bin: 'prisma', args: ['migrate', 'deploy'], env, quiet });
+}
+

package/scripts/utils/localhost_host.mjs

@@ -0,0 +1,17 @@
+import { getStackName } from './paths.mjs';
+
+function sanitizeDnsLabel(raw, { fallback = 'stack' } = {}) {
+  const s = String(raw ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+/, '')
+    .replace(/-+$/, '');
+  return s || fallback;
+}
+
+export function resolveLocalhostHost({ stackMode, stackName = getStackName() } = {}) {
+  if (!stackMode) return 'localhost';
+  if (!stackName || stackName === 'main') return 'localhost';
+  return `happy-${sanitizeDnsLabel(stackName)}.localhost`;
+}

package/scripts/utils/ownership.mjs

@@ -0,0 +1,135 @@
+import { runCapture } from './proc.mjs';
+import { killPid } from './expo.mjs';
+
+export async function getPsEnvLine(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 1) return null;
+  if (process.platform === 'win32') return null;
+  try {
+    const out = await runCapture('ps', ['eww', '-p', String(n)]);
+    // Output usually includes a header line and then a single process line.
+    const lines = out.split('\n').map((l) => l.trim()).filter(Boolean);
+    if (lines.length >= 2) return lines[1];
+    if (lines.length === 1) return lines[0];
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export async function listPidsWithEnvNeedle(needle) {
+  const n = String(needle ?? '').trim();
+  if (!n) return [];
+  if (process.platform === 'win32') return [];
+  try {
+    // Include environment variables (eww) so we can match on HAPPY_STACKS_ENV_FILE=/.../env safely.
+    const out = await runCapture('ps', ['eww', '-ax', '-o', 'pid=,command=']);
+    const pids = [];
+    for (const line of out.split('\n')) {
+      if (!line.includes(n)) continue;
+      const m = line.trim().match(/^(\d+)\s+/);
+      if (!m) continue;
+      const pid = Number(m[1]);
+      if (Number.isFinite(pid) && pid > 1) {
+        pids.push(pid);
+      }
+    }
+    return Array.from(new Set(pids));
+  } catch {
+    return [];
+  }
+}
+
+export async function getProcessGroupId(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 1) return null;
+  if (process.platform === 'win32') return null;
+  try {
+    const out = await runCapture('ps', ['-o', 'pgid=', '-p', String(n)]);
+    const raw = out.trim();
+    const pgid = raw ? Number(raw) : NaN;
+    return Number.isFinite(pgid) && pgid > 1 ? pgid : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function isPidOwnedByStack(pid, { stackName, envPath, cliHomeDir } = {}) {
+  const line = await getPsEnvLine(pid);
+  if (!line) return false;
+  const sn = String(stackName ?? '').trim();
+  const ep = String(envPath ?? '').trim();
+  const ch = String(cliHomeDir ?? '').trim();
+
+  // Require at least one stack identifier.
+  const hasStack =
+    (sn && (line.includes(`HAPPY_STACKS_STACK=${sn}`) || line.includes(`HAPPY_LOCAL_STACK=${sn}`))) ||
+    (!sn && (line.includes('HAPPY_STACKS_STACK=') || line.includes('HAPPY_LOCAL_STACK=')));
+  if (!hasStack) return false;
+
+  // Prefer env-file binding (strongest).
+  if (ep) {
+    if (line.includes(`HAPPY_STACKS_ENV_FILE=${ep}`) || line.includes(`HAPPY_LOCAL_ENV_FILE=${ep}`)) {
+      return true;
+    }
+  }
+
+  // Fallback: CLI home dir binding (useful for daemon-related processes).
+  if (ch) {
+    if (line.includes(`HAPPY_HOME_DIR=${ch}`) || line.includes(`HAPPY_STACKS_CLI_HOME_DIR=${ch}`) || line.includes(`HAPPY_LOCAL_CLI_HOME_DIR=${ch}`)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export async function killPidOwnedByStack(pid, { stackName, envPath, cliHomeDir, label = 'process', json = false } = {}) {
+  const ok = await isPidOwnedByStack(pid, { stackName, envPath, cliHomeDir });
+  if (!ok) {
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.warn(`[stack] refusing to kill ${label} pid=${pid} (cannot prove it belongs to stack ${stackName ?? ''})`);
+    }
+    return { killed: false, reason: 'not_owned' };
+  }
+  await killPid(pid);
+  return { killed: true, reason: 'killed' };
+}
+
+export async function killProcessGroupOwnedByStack(
+  pid,
+  { stackName, envPath, cliHomeDir, label = 'process-group', json = false, signal = 'SIGTERM' } = {}
+) {
+  const ok = await isPidOwnedByStack(pid, { stackName, envPath, cliHomeDir });
+  if (!ok) {
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.warn(`[stack] refusing to kill ${label} pid=${pid} (cannot prove it belongs to stack ${stackName ?? ''})`);
+    }
+    return { killed: false, reason: 'not_owned' };
+  }
+  const pgid = await getProcessGroupId(pid);
+  if (!pgid) {
+    await killPid(pid);
+    return { killed: true, reason: 'killed_pid_only' };
+  }
+  try {
+    process.kill(-pgid, signal);
+  } catch {
+    // ignore
+  }
+  // Escalate if still alive.
+  try {
+    process.kill(pid, 0);
+    try {
+      process.kill(-pgid, 'SIGKILL');
+    } catch {
+      // ignore
+    }
+  } catch {
+    // exited
+  }
+  return { killed: true, reason: 'killed_pgid', pgid };
+}
+

package/scripts/utils/paths.mjs

@@ -2,6 +2,7 @@ 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';
 
 const PRIMARY_APP_SLUG = 'happy-stacks';
 const LEGACY_APP_SLUG = 'happy-local';
@@ -101,12 +102,13 @@ export function resolveStackBaseDir(stackName = getStackName()) {
   const preferredRoot = getStacksStorageRoot();
   const newBase = join(preferredRoot, stackName);
   const legacyBase = stackName === 'main' ? LEGACY_STORAGE_ROOT : join(LEGACY_STORAGE_ROOT, 'stacks', stackName);
+  const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
 
   // Prefer the new layout by default.
   //
   // For non-main stacks, keep legacy layout if the legacy env exists and the new env does not.
   // This avoids breaking existing stacks until `happys stack migrate` is run.
-  if (stackName !== 'main') {
+  if (allowLegacy && stackName !== 'main') {
     const newEnv = join(preferredRoot, stackName, 'env');
     const legacyEnv = join(LEGACY_STORAGE_ROOT, 'stacks', stackName, 'env');
     if (!existsSync(newEnv) && existsSync(legacyEnv)) {
@@ -123,11 +125,12 @@ export function resolveStackEnvPath(stackName = getStackName()) {
   const newEnv = join(getStacksStorageRoot(), stackName, 'env');
   // Legacy layout: ~/.happy/local/stacks/<name>/env
   const legacyEnv = join(LEGACY_STORAGE_ROOT, 'stacks', stackName, 'env');
+  const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
 
   if (existsSync(newEnv)) {
     return { envPath: newEnv, isLegacy: false, baseDir: join(getStacksStorageRoot(), stackName) };
   }
-  if (existsSync(legacyEnv)) {
+  if (allowLegacy && existsSync(legacyEnv)) {
     return { envPath: legacyEnv, isLegacy: true, baseDir: join(LEGACY_STORAGE_ROOT, 'stacks', stackName) };
   }
   return { envPath: newEnv, isLegacy, baseDir: activeBase };