happy-stacks 0.1.2 → 0.3.0

package/scripts/mobile.mjs

@@ -1,11 +1,13 @@
-import './utils/env.mjs';
-import { parseArgs } from './utils/args.mjs';
-import { killPortListeners, pickNextFreeTcpPort } from './utils/ports.mjs';
-import { run, runCapture, spawnProc } from './utils/proc.mjs';
-import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths.mjs';
-import { ensureDepsInstalled, pmExecBin, pmSpawnBin, requireDir } from './utils/pm.mjs';
-import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
-import { ensureExpoIsolationEnv, getExpoStatePaths, isStateProcessRunning, killPid, wantsExpoClearCache, writePidState } from './utils/expo.mjs';
+import './utils/env/env.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { pickNextFreeTcpPort } from './utils/net/ports.mjs';
+import { run, runCapture, spawnProc } from './utils/proc/proc.mjs';
+import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths/paths.mjs';
+import { ensureDepsInstalled, pmExecBin, pmSpawnBin, requireDir } from './utils/proc/pm.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { ensureExpoIsolationEnv, getExpoStatePaths, isStateProcessRunning, killPid, wantsExpoClearCache, writePidState } from './utils/expo/expo.mjs';
+import { killProcessGroupOwnedByStack } from './utils/proc/ownership.mjs';
+import { getPublicServerUrlEnvOverride, resolveServerPortFromEnv } from './utils/server/urls.mjs';
 
 /**
  * Mobile dev helper for the embedded `components/happy` Expo app.
@@ -57,7 +59,7 @@ async function main() {
         '',
         'Notes:',
         '- This script is designed to avoid editing upstream `components/happy` config in-place.',
-        '- It sets EXPO_PUBLIC_HAPPY_SERVER_URL from HAPPY_STACKS_SERVER_URL (legacy: HAPPY_LOCAL_SERVER_URL) if provided.',
+        '- If you explicitly set HAPPY_STACKS_SERVER_URL (legacy: HAPPY_LOCAL_SERVER_URL), it bakes that URL into the app via EXPO_PUBLIC_HAPPY_SERVER_URL.',
       ].join('\n'),
     });
     return;
@@ -140,10 +142,10 @@ async function main() {
 
   // Allow happy-stacks to define the default server URL baked into the app bundle.
   // This is read by the app via `process.env.EXPO_PUBLIC_HAPPY_SERVER_URL`.
-  const stacksServerUrl =
-    process.env.HAPPY_STACKS_SERVER_URL?.trim() || process.env.HAPPY_LOCAL_SERVER_URL?.trim() || '';
-  if (stacksServerUrl && !env.EXPO_PUBLIC_HAPPY_SERVER_URL) {
-    env.EXPO_PUBLIC_HAPPY_SERVER_URL = stacksServerUrl;
+  const serverPort = resolveServerPortFromEnv({ env: process.env, defaultPort: 3005 });
+  const { envPublicUrl } = getPublicServerUrlEnvOverride({ env: process.env, serverPort });
+  if (envPublicUrl && !env.EXPO_PUBLIC_HAPPY_SERVER_URL) {
+    env.EXPO_PUBLIC_HAPPY_SERVER_URL = envPublicUrl;
   }
 
   if (json) {
@@ -306,11 +308,16 @@ async function main() {
   }
   if (restart && running.state?.pid) {
     const prevPid = Number(running.state.pid);
-    const prevPort = Number(running.state.port);
-    if (Number.isFinite(prevPort) && prevPort > 0) {
-      await killPortListeners(prevPort, { label: 'expo' });
+    const stackName = (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').trim() || autostart.stackName;
+    const envPath = (process.env.HAPPY_STACKS_ENV_FILE ?? process.env.HAPPY_LOCAL_ENV_FILE ?? '').toString();
+    const res = await killProcessGroupOwnedByStack(prevPid, { stackName, envPath, label: 'expo-mobile', json: true });
+    if (!res.killed) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[mobile] not stopping existing Metro pid=${prevPid} because it does not look stack-owned.\n` +
+          `[mobile] continuing by starting a new Metro on a free port.`
+      );
     }
-    await killPid(prevPid);
   }
 
   const requestedPort = Number.parseInt(String(portRaw), 10);

package/scripts/run.mjs

@@ -1,19 +1,25 @@
-import './utils/env.mjs';
-import { parseArgs } from './utils/args.mjs';
-import { pathExists } from './utils/fs.mjs';
-import { killProcessTree, runCapture, spawnProc } from './utils/proc.mjs';
-import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths.mjs';
-import { killPortListeners } from './utils/ports.mjs';
-import { getServerComponentName, isHappyServerRunning, waitForServerReady } from './utils/server.mjs';
-import { ensureDepsInstalled, pmExecBin, pmSpawnScript, requireDir } from './utils/pm.mjs';
+import './utils/env/env.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { pathExists } from './utils/fs/fs.mjs';
+import { killProcessTree, runCapture, spawnProc } from './utils/proc/proc.mjs';
+import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths/paths.mjs';
+import { killPortListeners } from './utils/net/ports.mjs';
+import { getServerComponentName, isHappyServerRunning, waitForServerReady } from './utils/server/server.mjs';
+import { ensureCliBuilt, ensureDepsInstalled, pmExecBin, pmSpawnScript, requireDir } from './utils/proc/pm.mjs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
-import { maybeResetTailscaleServe, resolvePublicServerUrl } from './tailscale.mjs';
+import { maybeResetTailscaleServe } from './tailscale.mjs';
 import { isDaemonRunning, startLocalDaemonWithAuth, stopLocalDaemon } from './daemon.mjs';
-import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
-import { assertServerComponentDirMatches, assertServerPrismaProviderMatches } from './utils/validate.mjs';
-import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from './utils/happy_server_infra.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { assertServerComponentDirMatches, assertServerPrismaProviderMatches } from './utils/server/validate.mjs';
+import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from './utils/server/infra/happy_server_infra.mjs';
+import { getAccountCountForServerComponent, prepareDaemonAuthSeedIfNeeded } from './utils/stack/startup.mjs';
+import { recordStackRuntimeStart, recordStackRuntimeUpdate } from './utils/stack/runtime_state.mjs';
+import { resolveStackContext } from './utils/stack/context.mjs';
+import { getPublicServerUrlEnvOverride, resolveServerPortFromEnv, resolveServerUrls } from './utils/server/urls.mjs';
+import { resolveLocalhostHost } from './utils/paths/localhost_host.mjs';
+import { openUrlInBrowser } from './utils/ui/browser.mjs';
 
 /**
  * Run the local stack in "production-like" mode:
@@ -31,7 +37,7 @@ async function main() {
   if (wantsHelp(argv, { flags })) {
     printResult({
       json,
-      data: { flags: ['--server=happy-server|happy-server-light', '--no-ui', '--no-daemon', '--restart'], json: true },
+      data: { flags: ['--server=happy-server|happy-server-light', '--no-ui', '--no-daemon', '--restart', '--no-browser'], json: true },
       text: [
         '[start] usage:',
         '  happys start [--server=happy-server|happy-server-light] [--restart] [--json]',
@@ -44,17 +50,14 @@ async function main() {
 
   const rootDir = getRootDir(import.meta.url);
 
-  const serverPort = process.env.HAPPY_LOCAL_SERVER_PORT
-    ? parseInt(process.env.HAPPY_LOCAL_SERVER_PORT, 10)
-    : 3005;
+  const serverPort = resolveServerPortFromEnv({ defaultPort: 3005 });
 
   // Internal URL used by local processes on this machine.
   const internalServerUrl = `http://127.0.0.1:${serverPort}`;
   // Public URL is what you might share/open (e.g. https://<machine>.<tailnet>.ts.net).
   // We auto-prefer the Tailscale HTTPS URL when available, unless explicitly overridden.
-  const defaultPublicUrl = `http://localhost:${serverPort}`;
-  const envPublicUrl = process.env.HAPPY_LOCAL_SERVER_URL?.trim() ? process.env.HAPPY_LOCAL_SERVER_URL.trim() : '';
-  let publicServerUrl = envPublicUrl || defaultPublicUrl;
+  const { defaultPublicUrl, envPublicUrl, publicServerUrl: publicServerUrlPreview } = getPublicServerUrlEnvOverride({ serverPort });
+  let publicServerUrl = publicServerUrlPreview;
 
   const serverComponentName = getServerComponentName({ kv });
   if (serverComponentName === 'both') {
@@ -64,6 +67,7 @@ async function main() {
   const startDaemon = !flags.has('--no-daemon') && (process.env.HAPPY_LOCAL_DAEMON ?? '1') !== '0';
   const serveUiWanted = !flags.has('--no-ui') && (process.env.HAPPY_LOCAL_SERVE_UI ?? '1') !== '0';
   const serveUi = serveUiWanted;
+  const noBrowser = flags.has('--no-browser') || (process.env.HAPPY_STACKS_NO_BROWSER ?? process.env.HAPPY_LOCAL_NO_BROWSER ?? '').toString().trim() === '1';
   const uiPrefix = process.env.HAPPY_LOCAL_UI_PREFIX?.trim() ? process.env.HAPPY_LOCAL_UI_PREFIX.trim() : '/';
   const autostart = getDefaultAutostartPaths();
   const uiBuildDir = process.env.HAPPY_LOCAL_UI_BUILD_DIR?.trim()
@@ -120,18 +124,29 @@ async function main() {
   const children = [];
   let shuttingDown = false;
   const baseEnv = { ...process.env };
+  const stackCtx = resolveStackContext({ env: baseEnv, autostart });
+  const { stackMode, runtimeStatePath, stackName, ephemeral } = stackCtx;
+
+  // Ensure happy-cli is install+build ready before starting the daemon.
+  const buildCli = (baseEnv.HAPPY_STACKS_CLI_BUILD ?? baseEnv.HAPPY_LOCAL_CLI_BUILD ?? '1').toString().trim() !== '0';
+  await ensureCliBuilt(cliDir, { buildCli });
 
   // Ensure server deps exist before any Prisma/docker work.
   await ensureDepsInstalled(serverDir, serverComponentName);
 
-  // Public URL automation: auto-prefer https://*.ts.net on every start.
-  const resolved = await resolvePublicServerUrl({
-    internalServerUrl,
-    defaultPublicUrl,
-    envPublicUrl,
-    allowEnable: true,
-  });
-  publicServerUrl = resolved.publicServerUrl;
+  // Public URL automation:
+  // - Only the main stack should ever auto-enable Tailscale Serve by default.
+  // - Non-main stacks default to localhost unless the user explicitly configured a public URL
+  //   OR Tailscale Serve is already configured for this stack's internal URL (status matches).
+  const allowEnableTailscale = !stackMode || stackName === 'main';
+  const resolvedUrls = await resolveServerUrls({ env: baseEnv, serverPort, allowEnable: allowEnableTailscale });
+  if (stackMode && stackName !== 'main' && !resolvedUrls.envPublicUrl) {
+    const src = String(resolvedUrls.publicServerUrlSource ?? '');
+    const hasStackScopedTailscale = src.startsWith('tailscale-');
+    publicServerUrl = hasStackScopedTailscale ? resolvedUrls.publicServerUrl : resolvedUrls.defaultPublicUrl;
+  } else {
+    publicServerUrl = resolvedUrls.publicServerUrl;
+  }
 
   const serverAlreadyRunning = await isHappyServerRunning(internalServerUrl);
   const daemonAlreadyRunning = startDaemon ? isDaemonRunning(cliHomeDir) : false;
@@ -140,9 +155,21 @@ async function main() {
     return;
   }
 
+  // Stack runtime state (stack-scoped commands only): record the runner PID + chosen ports so stop/restart never kills other stacks.
+  if (stackMode && runtimeStatePath) {
+    await recordStackRuntimeStart(runtimeStatePath, {
+      stackName,
+      script: 'run.mjs',
+      ephemeral,
+      ownerPid: process.pid,
+      ports: { server: serverPort },
+    }).catch(() => {});
+  }
+
   // Server
   // If a previous run left a server behind, free the port first (prevents false "ready" checks).
-  if (!serverAlreadyRunning || restart) {
+  // NOTE: In stack mode we avoid killing arbitrary port listeners (fail-closed instead).
+  if ((!serverAlreadyRunning || restart) && !stackMode) {
     await killPortListeners(serverPort, { label: 'server' });
   }
 
@@ -161,6 +188,8 @@ async function main() {
         }
       : {}),
   };
+  let serverLightAccountCount = null;
+  let happyServerAccountCount = null;
   if (serverComponentName === 'happy-server-light') {
     const dataDir = baseEnv.HAPPY_SERVER_LIGHT_DATA_DIR?.trim()
       ? baseEnv.HAPPY_SERVER_LIGHT_DATA_DIR.trim()
@@ -173,12 +202,14 @@ async function main() {
       ? baseEnv.DATABASE_URL.trim()
       : `file:${join(dataDir, 'happy-server-light.sqlite')}`;
 
-    // Optional: update SQLite schema on interactive start only.
-    // We intentionally do NOT run this under launchd KeepAlive (no TTY) to avoid restart loops.
-    const prismaPushOnStart = (baseEnv.HAPPY_STACKS_PRISMA_PUSH ?? baseEnv.HAPPY_LOCAL_PRISMA_PUSH ?? '').trim() === '1';
-    if (prismaPushOnStart && process.stdout.isTTY) {
-      await pmExecBin({ dir: serverDir, bin: 'prisma', args: ['db', 'push'], env: serverEnv });
-    }
+    // Reliability: ensure DB schema exists before daemon hits /v1/machines (health checks don't cover DB readiness).
+    const acct = await getAccountCountForServerComponent({
+      serverComponentName,
+      serverDir,
+      env: serverEnv,
+      bestEffort: false,
+    });
+    serverLightAccountCount = typeof acct.accountCount === 'number' ? acct.accountCount : null;
   }
   let effectiveInternalServerUrl = internalServerUrl;
   if (serverComponentName === 'happy-server') {
@@ -198,16 +229,32 @@ async function main() {
       const backendPortRaw = (baseEnv.HAPPY_STACKS_HAPPY_SERVER_BACKEND_PORT ?? baseEnv.HAPPY_LOCAL_HAPPY_SERVER_BACKEND_PORT ?? '').trim();
       const backendPort = backendPortRaw ? Number(backendPortRaw) : serverPort + 10;
       const backendUrl = `http://127.0.0.1:${backendPort}`;
-      await killPortListeners(backendPort, { label: 'happy-server-backend' });
+      if (!stackMode) {
+        await killPortListeners(backendPort, { label: 'happy-server-backend' });
+      }
 
       const backendEnv = { ...serverEnv, ...infra.env, PORT: String(backendPort) };
       const autoMigrate = (baseEnv.HAPPY_STACKS_PRISMA_MIGRATE ?? baseEnv.HAPPY_LOCAL_PRISMA_MIGRATE ?? '1') !== '0';
       if (autoMigrate) {
         await applyHappyServerMigrations({ serverDir, env: backendEnv });
       }
+      // Account probe should use the *actual* DATABASE_URL/infra env (ephemeral stacks do not persist it in env files).
+      const acct = await getAccountCountForServerComponent({
+        serverComponentName,
+        serverDir,
+        env: backendEnv,
+        bestEffort: true,
+      });
+      happyServerAccountCount = typeof acct.accountCount === 'number' ? acct.accountCount : null;
 
       const backend = await pmSpawnScript({ label: 'server', dir: serverDir, script: 'start', env: backendEnv });
       children.push(backend);
+      if (stackMode && runtimeStatePath) {
+        await recordStackRuntimeUpdate(runtimeStatePath, {
+          ports: { server: serverPort, backend: backendPort },
+          processes: { happyServerBackendPid: backend.pid },
+        }).catch(() => {});
+      }
       await waitForServerReady(backendUrl);
 
       const gatewayArgs = [
@@ -225,6 +272,9 @@ async function main() {
 
       const gateway = spawnProc('ui', process.execPath, gatewayArgs, { ...backendEnv, PORT: String(serverPort) }, { cwd: rootDir });
       children.push(gateway);
+      if (stackMode && runtimeStatePath) {
+        await recordStackRuntimeUpdate(runtimeStatePath, { processes: { uiGatewayPid: gateway.pid } }).catch(() => {});
+      }
       await waitForServerReady(internalServerUrl);
       effectiveInternalServerUrl = internalServerUrl;
 
@@ -237,6 +287,9 @@ async function main() {
     if (!serverAlreadyRunning || restart) {
       const server = await pmSpawnScript({ label: 'server', dir: serverDir, script: 'start', env: serverEnv });
       children.push(server);
+      if (stackMode && runtimeStatePath) {
+        await recordStackRuntimeUpdate(runtimeStatePath, { processes: { serverPid: server.pid } }).catch(() => {});
+      }
       await waitForServerReady(internalServerUrl);
     } else {
       console.log(`[local] server already running at ${internalServerUrl}`);
@@ -274,10 +327,44 @@ async function main() {
       `export HAPPY_HOME_DIR=\"${cliHomeDir}\"\n` +
       `export HAPPY_WEBAPP_URL=\"${publicServerUrl}\"\n`
     );
+
+    // Auto-open UI (interactive only) using the stack-scoped hostname when applicable.
+    const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    if (isInteractive && !noBrowser) {
+      const host = resolveLocalhostHost({ stackMode, stackName: autostart.stackName });
+      const prefix = uiPrefix.startsWith('/') ? uiPrefix : `/${uiPrefix}`;
+      const openUrl = `http://${host}:${serverPort}${prefix}`;
+      const res = await openUrlInBrowser(openUrl);
+      if (!res.ok) {
+        console.warn(`[local] ui: failed to open browser automatically (${res.error}).`);
+      }
+    }
   }
 
   // Daemon
   if (startDaemon) {
+    const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    if (serverComponentName === 'happy-server' && happyServerAccountCount == null) {
+      const acct = await getAccountCountForServerComponent({
+        serverComponentName,
+        serverDir,
+        env: serverEnv,
+        bestEffort: true,
+      });
+      happyServerAccountCount = typeof acct.accountCount === 'number' ? acct.accountCount : null;
+    }
+    const accountCount =
+      serverComponentName === 'happy-server-light' ? serverLightAccountCount : happyServerAccountCount;
+    await prepareDaemonAuthSeedIfNeeded({
+      rootDir,
+      env: baseEnv,
+      stackName: autostart.stackName,
+      cliHomeDir,
+      startDaemon,
+      isInteractive,
+      accountCount,
+      quiet: false,
+    });
     await startLocalDaemonWithAuth({
       cliBin,
       cliHomeDir,

package/scripts/self.mjs

@@ -1,20 +1,18 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-import { parseArgs } from './utils/args.mjs';
-import { pathExists } from './utils/fs.mjs';
-import { run, runCapture } from './utils/proc.mjs';
-import { getHappyStacksHomeDir, getRootDir } from './utils/paths.mjs';
-import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
-import { getRuntimeDir } from './utils/runtime.mjs';
-
-function expandHome(p) {
-  return p.replace(/^~(?=\/)/, homedir());
-}
+import { parseArgs } from './utils/cli/args.mjs';
+import { pathExists } from './utils/fs/fs.mjs';
+import { run, runCapture } from './utils/proc/proc.mjs';
+import { expandHome } from './utils/paths/canonical_home.mjs';
+import { getHappyStacksHomeDir, getRootDir } from './utils/paths/paths.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { getRuntimeDir } from './utils/paths/runtime.mjs';
+import { readJsonIfExists } from './utils/fs/json.mjs';
+import { readPackageJsonVersion } from './utils/fs/package_json.mjs';
 
 function cachePaths() {
   const home = getHappyStacksHomeDir();
@@ -25,15 +23,6 @@ function cachePaths() {
   };
 }
 
-async function readJsonSafe(path) {
-  try {
-    const raw = await readFile(path, 'utf-8');
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
 async function writeJsonSafe(path, obj) {
   try {
     await mkdir(join(path, '..'), { recursive: true });
@@ -47,25 +36,14 @@ async function writeJsonSafe(path, obj) {
   }
 }
 
-async function readPkgVersion(pkgJsonPath) {
-  try {
-    const raw = await readFile(pkgJsonPath, 'utf-8');
-    const pkg = JSON.parse(raw);
-    const v = String(pkg.version ?? '').trim();
-    return v || null;
-  } catch {
-    return null;
-  }
-}
-
 async function getRuntimeInstalledVersion() {
   const runtimeDir = getRuntimeDir();
   const pkgJson = join(runtimeDir, 'node_modules', 'happy-stacks', 'package.json');
-  return await readPkgVersion(pkgJson);
+  return await readPackageJsonVersion(pkgJson);
 }
 
 async function getInvokerVersion({ rootDir }) {
-  return await readPkgVersion(join(rootDir, 'package.json'));
+  return await readPackageJsonVersion(join(rootDir, 'package.json'));
 }
 
 async function fetchLatestVersion() {
@@ -106,7 +84,7 @@ async function cmdStatus({ rootDir, argv }) {
   const runtimeDir = getRuntimeDir();
   const runtimeVersion = await getRuntimeInstalledVersion();
 
-  const cached = await readJsonSafe(updateJson);
+  const cached = await readJsonIfExists(updateJson, { defaultValue: null });
 
   let latest = cached?.latest ?? null;
   let checkedAt = cached?.checkedAt ?? null;

package/scripts/server_flavor.mjs

@@ -1,10 +1,10 @@
-import './utils/env.mjs';
-import { parseArgs } from './utils/args.mjs';
-import { getRootDir } from './utils/paths.mjs';
-import { ensureEnvFileUpdated } from './utils/env_file.mjs';
-import { resolveUserConfigEnvPath } from './utils/config.mjs';
-import { isTty, promptSelect, withRl } from './utils/wizard.mjs';
-import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
+import './utils/env/env.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { getRootDir } from './utils/paths/paths.mjs';
+import { ensureEnvFileUpdated } from './utils/env/env_file.mjs';
+import { resolveUserConfigEnvPath } from './utils/env/config.mjs';
+import { isTty, promptSelect, withRl } from './utils/cli/wizard.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 
 const FLAVORS = [
   { label: 'happy-server-light (recommended default, serves UI)', value: 'happy-server-light' },

package/scripts/service.mjs

@@ -1,15 +1,19 @@
-import './utils/env.mjs';
-import { run, runCapture } from './utils/proc.mjs';
-import { getDefaultAutostartPaths, getRootDir, resolveStackEnvPath } from './utils/paths.mjs';
-import { ensureMacAutostartDisabled, ensureMacAutostartEnabled } from './utils/pm.mjs';
+import './utils/env/env.mjs';
+import { run, runCapture } from './utils/proc/proc.mjs';
+import { getDefaultAutostartPaths, getRootDir, resolveStackEnvPath } from './utils/paths/paths.mjs';
+import { getInternalServerUrl, getPublicServerUrlEnvOverride } from './utils/server/urls.mjs';
+import { ensureMacAutostartDisabled, ensureMacAutostartEnabled } from './utils/service/autostart_darwin.mjs';
+import { getCanonicalHomeDir } from './utils/env/config.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
 import { spawn } from 'node:child_process';
 import { homedir } from 'node:os';
 import { existsSync } from 'node:fs';
 import { rm } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { readLastLines } from './utils/fs/tail.mjs';
 
 /**
  * Manage the autostart service installed by `happys bootstrap -- --autostart`.
@@ -33,11 +37,6 @@ function getUid() {
   return Number.isFinite(n) ? n : null;
 }
 
-function getInternalUrl() {
-  const port = process.env.HAPPY_LOCAL_SERVER_PORT?.trim() ? Number(process.env.HAPPY_LOCAL_SERVER_PORT) : 3005;
-  return `http://127.0.0.1:${port}`;
-}
-
 function getAutostartEnv({ rootDir }) {
   // IMPORTANT:
   // LaunchAgents should NOT bake the entire config into the plist, because that would require
@@ -63,6 +62,13 @@ function getAutostartEnv({ rootDir }) {
 }
 
 export async function installService() {
+  if (isSandboxed() && !sandboxAllowsGlobalSideEffects()) {
+    throw new Error(
+      '[local] service install is disabled in sandbox mode.\n' +
+        'Reason: services are global OS state (launchd/systemd) and can affect your real installation.\n' +
+        'If you really want this, set: HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1'
+    );
+  }
   if (process.platform !== 'darwin' && process.platform !== 'linux') {
     throw new Error('[local] service install is only supported on macOS (launchd) and Linux (systemd user).');
   }
@@ -89,6 +95,10 @@ export async function installService() {
 }
 
 export async function uninstallService() {
+  if (isSandboxed() && !sandboxAllowsGlobalSideEffects()) {
+    // Sandbox cleanups should be safe and should not touch global services by default.
+    return;
+  }
   if (process.platform !== 'darwin' && process.platform !== 'linux') return;
 
   if (process.platform === 'linux') {
@@ -132,7 +142,7 @@ function systemdEnvLines(env) {
 async function ensureSystemdUserServiceEnabled({ rootDir, label, env }) {
   const unitPath = systemdUnitPath();
   await mkdir(dirname(unitPath), { recursive: true });
-  const happysShim = join(homedir(), '.happy-stacks', 'bin', 'happys');
+  const happysShim = join(getCanonicalHomeDir(), 'bin', 'happys');
   const entry = existsSync(happysShim) ? happysShim : join(rootDir, 'bin', 'happys.mjs');
   const exec = existsSync(happysShim) ? entry : `${process.execPath} ${entry}`;
 
@@ -254,16 +264,19 @@ async function startLaunchAgent({ persistent }) {
 
 async function postStartDiagnostics() {
   const rootDir = getRootDir(import.meta.url);
-  const internalUrl = getInternalUrl();
+  const internalUrl = getInternalServerUrl({ env: process.env, defaultPort: 3005 }).internalServerUrl;
 
   const cliHomeDir = process.env.HAPPY_LOCAL_CLI_HOME_DIR?.trim()
     ? process.env.HAPPY_LOCAL_CLI_HOME_DIR.trim().replace(/^~(?=\/)/, homedir())
     : join(getDefaultAutostartPaths().baseDir, 'cli');
 
-  const publicUrl =
-    process.env.HAPPY_LOCAL_SERVER_URL?.trim()
-      ? process.env.HAPPY_LOCAL_SERVER_URL.trim()
-      : internalUrl.replace('127.0.0.1', 'localhost');
+  let port = 3005;
+  try {
+    port = Number(new URL(internalUrl).port || 0) || 3005;
+  } catch {
+    port = 3005;
+  }
+  const { publicServerUrl: publicUrl } = getPublicServerUrlEnvOverride({ env: process.env, serverPort: port });
 
   const cliDir = join(rootDir, 'components', 'happy-cli');
   const cliBin = join(cliDir, 'bin', 'happy.mjs');
@@ -273,16 +286,6 @@ async function postStartDiagnostics() {
   const lockFile = join(cliHomeDir, 'daemon.state.json.lock');
   const logsDir = join(cliHomeDir, 'logs');
 
-  const readLastLines = async (path, lines = 60) => {
-    try {
-      const raw = await readFile(path, 'utf-8');
-      const parts = raw.split('\n');
-      return parts.slice(Math.max(0, parts.length - lines)).join('\n');
-    } catch {
-      return null;
-    }
-  };
-
   const latestDaemonLog = async () => {
     try {
       const ls = await runCapture('bash', ['-lc', `ls -1t "${logsDir}"/*-daemon.log 2>/dev/null | head -1 || true`]);
@@ -448,7 +451,7 @@ async function waitForLaunchAgentStopped({ timeoutMs = 8000 } = {}) {
 
 async function showStatus() {
   const { plistPath, stdoutPath, stderrPath, label } = getDefaultAutostartPaths();
-  const internalUrl = getInternalUrl();
+  const internalUrl = getInternalServerUrl({ env: process.env, defaultPort: 3005 }).internalServerUrl;
 
   console.log(`label: ${label}`);
   console.log(`plist: ${plistPath} ${existsSync(plistPath) ? '(present)' : '(missing)'}`);
@@ -537,7 +540,7 @@ async function main() {
       return;
     case 'status':
       if (json) {
-        const internalUrl = getInternalUrl();
+        const internalUrl = getInternalServerUrl({ env: process.env, defaultPort: 3005 }).internalServerUrl;
         let health = null;
         try {
           const res = await fetch(`${internalUrl}/health`, { method: 'GET' });