happy-stacks 0.1.2 → 0.3.0

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

@@ -1,73 +1,18 @@
-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}`);
-}
+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';
 
-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)) {
@@ -243,8 +188,26 @@ async function maybeStartDockerDaemon() {
   }
 }
 
-async function dockerCompose({ composePath, projectName, args, options = {} }) {
-  await run('docker', ['compose', '-f', composePath, '-p', projectName, ...args], options);
+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 }) {
@@ -285,6 +248,25 @@ async function waitForHealthyRedis({ composePath, projectName }) {
   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,
@@ -292,6 +274,8 @@ export async function ensureHappyServerManagedInfra({
   publicServerUrl,
   envPath,
   env = process.env,
+  quiet = false,
+  skipMinioInit = false,
 }) {
   await ensureDockerCompose();
 
@@ -302,30 +286,27 @@ 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);
   }
   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 }));
+  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 pickNextFreePort(pgPort + 1, { reservedPorts }));
+    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 pickNextFreePort(redisPort + 1, { reservedPorts }));
+    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 pickNextFreePort(minioPort + 1, { reservedPorts }));
+    (await pickNextFreeTcpPort(minioPort + 1, { reservedPorts }));
   reservedPorts.add(minioConsolePort);
 
   const pgUser = (existingEnv.HAPPY_STACKS_PG_USER ?? env.HAPPY_STACKS_PG_USER ?? 'handy').trim() || 'handy';
@@ -355,27 +336,45 @@ export async function ensureHappyServerManagedInfra({
   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: [
-        { 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) },
+        // 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 },
-        // 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 },
+        // 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 },
+            ]),
       ],
     });
   }
@@ -397,12 +396,28 @@ export async function ensureHappyServerManagedInfra({
   });
   await writeFile(composePath, yaml, 'utf-8');
 
-  await dockerCompose({ composePath, projectName, args: ['up', '-d', '--remove-orphans'], options: { cwd: baseDir } });
+  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 });
 
-  // Ensure bucket exists (idempotent)
-  await dockerCompose({ composePath, projectName, args: ['run', '--rm', 'minio-init'], options: { cwd: baseDir } });
+  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,
@@ -423,8 +438,8 @@ export async function ensureHappyServerManagedInfra({
   };
 }
 
-export async function applyHappyServerMigrations({ serverDir, env }) {
+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 });
+  await pmExecBin({ dir: serverDir, bin: 'prisma', args: ['migrate', 'deploy'], env, quiet });
 }
 

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) {
@@ -76,3 +88,27 @@ export async function waitForServerReady(url) {
   throw new Error(`Timed out waiting for server at ${url}`);
 }
 
+// Used for UI readiness checks (Expo / gateway / server). Treat any HTTP response as "up".
+export async function waitForHttpOk(url, { timeoutMs = 15_000, intervalMs = 250 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const ctl = new AbortController();
+      const t = setTimeout(() => ctl.abort(), Math.min(2500, Math.max(250, intervalMs)));
+      try {
+        const res = await fetch(url, { method: 'GET', signal: ctl.signal });
+        if (res.status >= 100 && res.status < 600) {
+          return;
+        }
+      } finally {
+        clearTimeout(t);
+      }
+    } catch {
+      // ignore
+    }
+    // eslint-disable-next-line no-await-in-loop
+    await delay(intervalMs);
+  }
+  throw new Error(`Timed out waiting for HTTP response from ${url} after ${timeoutMs}ms`);
+}
+

package/scripts/utils/server/urls.mjs

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

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

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
-import { getComponentsDir } from './paths.mjs';
+import { getComponentsDir } from '../paths/paths.mjs';
 
 function isInside(path, dir) {
   const p = resolve(path);

package/scripts/utils/service/autostart_darwin.mjs

@@ -0,0 +1,142 @@
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+
+import { runCapture } from '../proc/proc.mjs';
+import { getDefaultAutostartPaths } from '../paths/paths.mjs';
+import { resolveInstalledCliRoot, resolveInstalledPath } from '../paths/runtime.mjs';
+
+function plistPathForLabel(label) {
+  return join(homedir(), 'Library', 'LaunchAgents', `${label}.plist`);
+}
+
+function xmlEscape(s) {
+  return String(s ?? '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
+function plistXml({ label, programArgs, env = {}, stdoutPath, stderrPath, workingDirectory }) {
+  const envEntries = Object.entries(env ?? {}).filter(([k, v]) => String(k).trim() && String(v ?? '').trim());
+  const programArgsXml = programArgs.map((a) => `      <string>${xmlEscape(a)}</string>`).join('\n');
+  const envXml = envEntries
+    .map(([k, v]) => `      <key>${xmlEscape(k)}</key>\n      <string>${xmlEscape(v)}</string>`)
+    .join('\n');
+  const workingDirXml = workingDirectory
+    ? `\n    <key>WorkingDirectory</key>\n    <string>${xmlEscape(workingDirectory)}</string>\n`
+    : '\n';
+
+  return `<?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>${xmlEscape(label)}</string>
+
+    <key>ProgramArguments</key>
+    <array>
+${programArgsXml}
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+${workingDirXml}    <key>StandardOutPath</key>
+    <string>${xmlEscape(stdoutPath)}</string>
+    <key>StandardErrorPath</key>
+    <string>${xmlEscape(stderrPath)}</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+${envXml}
+    </dict>
+  </dict>
+</plist>
+`;
+}
+
+export async function ensureMacAutostartEnabled({ rootDir, label, env }) {
+  if (process.platform !== 'darwin') {
+    throw new Error('[local] macOS autostart is only supported on Darwin');
+  }
+  const l = String(label ?? '').trim();
+  if (!l) throw new Error('[local] missing launchd label');
+
+  const plistPath = plistPathForLabel(l);
+  const { stdoutPath, stderrPath } = getDefaultAutostartPaths();
+  await mkdir(dirname(plistPath), { recursive: true }).catch(() => {});
+  await mkdir(dirname(stdoutPath), { recursive: true }).catch(() => {});
+  await mkdir(dirname(stderrPath), { recursive: true }).catch(() => {});
+
+  const programArgs = [process.execPath, resolveInstalledPath(rootDir, 'bin/happys.mjs'), 'start'];
+  const mergedEnv = {
+    ...(env ?? {}),
+    // Ensure a reasonable PATH for subprocesses (git/docker/etc) in launchd’s minimal environment.
+    PATH: (process.env.PATH ?? '').trim() || '/usr/bin:/bin:/usr/sbin:/sbin',
+  };
+
+  const xml = plistXml({
+    label: l,
+    programArgs,
+    env: mergedEnv,
+    stdoutPath,
+    stderrPath,
+    workingDirectory: resolveInstalledCliRoot(rootDir),
+  });
+
+  const tmp = join(dirname(plistPath), `.tmp.${l}.${Date.now()}.plist`);
+  await writeFile(tmp, xml, 'utf-8');
+  await rename(tmp, plistPath);
+
+  // Best-effort load/enable; `scripts/service.mjs` has a more robust bootstrap fallback.
+  try {
+    await runCapture('launchctl', ['load', '-w', plistPath]);
+  } catch {
+    // ignore
+  }
+}
+
+export async function ensureMacAutostartDisabled({ label }) {
+  if (process.platform !== 'darwin') {
+    return;
+  }
+  const l = String(label ?? '').trim();
+  if (!l) return;
+  const plistPath = plistPathForLabel(l);
+
+  const uidRaw = Number(process.env.UID);
+  const uid = Number.isFinite(uidRaw) ? uidRaw : null;
+
+  try {
+    await runCapture('launchctl', ['unload', '-w', plistPath]);
+  } catch {
+    // ignore
+  }
+  try {
+    await runCapture('launchctl', ['unload', plistPath]);
+  } catch {
+    // ignore
+  }
+  if (uid != null) {
+    try {
+      await runCapture('launchctl', ['disable', `gui/${uid}/${l}`]);
+    } catch {
+      // ignore
+    }
+    try {
+      await runCapture('launchctl', ['bootout', `gui/${uid}`, plistPath]);
+    } catch {
+      // ignore
+    }
+  }
+  try {
+    await runCapture('launchctl', ['remove', l]);
+  } catch {
+    // ignore
+  }
+}
+

package/scripts/utils/stack/context.mjs

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