happy-stacks 0.1.2 → 0.3.0

package/scripts/dev.mjs

@@ -1,19 +1,27 @@
-import './utils/env.mjs';
-import { parseArgs } from './utils/args.mjs';
-import { killProcessTree } from './utils/proc.mjs';
-import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths.mjs';
-import { killPortListeners, pickNextFreeTcpPort } from './utils/ports.mjs';
-import { getServerComponentName, isHappyServerRunning, waitForServerReady } from './utils/server.mjs';
-import { ensureDepsInstalled, pmSpawnBin, pmSpawnScript, requireDir } from './utils/pm.mjs';
+import './utils/env/env.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { killProcessTree } from './utils/proc/proc.mjs';
+import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths/paths.mjs';
+import { killPortListeners } from './utils/net/ports.mjs';
+import { getServerComponentName, isHappyServerRunning } from './utils/server/server.mjs';
+import { requireDir } from './utils/proc/pm.mjs';
 import { join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { homedir } from 'node:os';
-import { isDaemonRunning, startLocalDaemonWithAuth, stopLocalDaemon } from './daemon.mjs';
-import { resolvePublicServerUrl } from './tailscale.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 { ensureExpoIsolationEnv, getExpoStatePaths, isStateProcessRunning, killPid, wantsExpoClearCache, writePidState } from './utils/expo.mjs';
+import { isDaemonRunning, stopLocalDaemon } from './daemon.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { assertServerComponentDirMatches, assertServerPrismaProviderMatches } from './utils/server/validate.mjs';
+import { getExpoStatePaths, isStateProcessRunning } from './utils/expo/expo.mjs';
+import { isPidAlive, readStackRuntimeStateFile, recordStackRuntimeStart } from './utils/stack/runtime_state.mjs';
+import { resolveStackContext } from './utils/stack/context.mjs';
+import { resolveServerPortFromEnv, resolveServerUrls } from './utils/server/urls.mjs';
+import { ensureDevCliReady, prepareDaemonAuthSeed, startDevDaemon, watchHappyCliAndRestartDaemon } from './utils/dev/daemon.mjs';
+import { startDevServer, watchDevServerAndRestart } from './utils/dev/server.mjs';
+import { startDevExpoWebUi } from './utils/dev/expo_web.mjs';
+import { resolveLocalhostHost } from './utils/paths/localhost_host.mjs';
+import { openUrlInBrowser } from './utils/ui/browser.mjs';
+import { waitForHttpOk } from './utils/server/server.mjs';
+import { sanitizeDnsLabel } from './utils/net/dns.mjs';
 
 /**
  * Dev mode stack:
@@ -29,10 +37,13 @@ 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', '--watch', '--no-watch', '--no-browser'], json: true },
       text: [
         '[dev] usage:',
         '  happys dev [--server=happy-server|happy-server-light] [--restart] [--json]',
+        '  happys dev --watch      # rebuild/restart happy-cli daemon on file changes (TTY default)',
+        '  happys dev --no-watch   # disable watch mode (always disabled in non-interactive mode)',
+        '  happys dev --no-browser # do not open the UI in your browser automatically',
         '  note: --json prints the resolved config (dry-run) and exits.',
       ].join('\n'),
     });
@@ -40,21 +51,6 @@ 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 internalServerUrl = `http://127.0.0.1:${serverPort}`;
-  const defaultPublicUrl = `http://localhost:${serverPort}`;
-  const envPublicUrl = process.env.HAPPY_LOCAL_SERVER_URL?.trim() ? process.env.HAPPY_LOCAL_SERVER_URL.trim() : '';
-  const resolved = await resolvePublicServerUrl({
-    internalServerUrl,
-    defaultPublicUrl,
-    envPublicUrl,
-    allowEnable: true,
-  });
-  const publicServerUrl = resolved.publicServerUrl;
-
   const serverComponentName = getServerComponentName({ kv });
   if (serverComponentName === 'both') {
     throw new Error(`[local] --server=both is not supported for dev (pick one: happy-server-light or happy-server)`);
@@ -62,7 +58,7 @@ async function main() {
 
   const startUi = !flags.has('--no-ui') && (process.env.HAPPY_LOCAL_UI ?? '1') !== '0';
   const startDaemon = !flags.has('--no-daemon') && (process.env.HAPPY_LOCAL_DAEMON ?? '1') !== '0';
-  const restart = flags.has('--restart');
+  const noBrowser = flags.has('--no-browser') || (process.env.HAPPY_STACKS_NO_BROWSER ?? process.env.HAPPY_LOCAL_NO_BROWSER ?? '').toString().trim() === '1';
 
   const serverDir = getComponentDir(rootDir, serverComponentName);
   const uiDir = getComponentDir(rootDir, 'happy');
@@ -77,6 +73,28 @@ async function main() {
 
   const cliBin = join(cliDir, 'bin', 'happy.mjs');
   const autostart = getDefaultAutostartPaths();
+  const baseEnv = { ...process.env };
+  const stackCtx = resolveStackContext({ env: baseEnv, autostart });
+  const { stackMode, runtimeStatePath, stackName, envPath, ephemeral } = stackCtx;
+
+  const serverPort = resolveServerPortFromEnv({ env: baseEnv, defaultPort: 3005 });
+  // IMPORTANT:
+  // - Only the main stack should ever auto-enable (or prefer) Tailscale Serve by default.
+  // - Non-main stacks should default to localhost URLs 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 });
+  const internalServerUrl = resolvedUrls.internalServerUrl;
+  let publicServerUrl = resolvedUrls.publicServerUrl;
+  if (stackMode && stackName !== 'main' && !resolvedUrls.envPublicUrl) {
+    const src = String(resolvedUrls.publicServerUrlSource ?? '');
+    const hasStackScopedTailscale = src.startsWith('tailscale-');
+    if (!hasStackScopedTailscale) {
+      publicServerUrl = resolvedUrls.defaultPublicUrl;
+    }
+  }
+  const uiApiUrl = resolvedUrls.defaultPublicUrl;
+  const restart = flags.has('--restart');
   const cliHomeDir = process.env.HAPPY_LOCAL_CLI_HOME_DIR?.trim()
     ? process.env.HAPPY_LOCAL_CLI_HOME_DIR.trim().replace(/^~(?=\/)/, homedir())
     : join(autostart.baseDir, 'cli');
@@ -103,7 +121,16 @@ async function main() {
 
   const children = [];
   let shuttingDown = false;
-  const baseEnv = { ...process.env };
+
+  // Ensure happy-cli is install+build ready before starting the daemon.
+  // Worktrees often don't have dist/ built yet, which causes MODULE_NOT_FOUND on dist/index.mjs.
+  const buildCli = (baseEnv.HAPPY_STACKS_CLI_BUILD ?? baseEnv.HAPPY_LOCAL_CLI_BUILD ?? '1').toString().trim() !== '0';
+  await ensureDevCliReady({ cliDir, buildCli });
+
+  // Watch mode (interactive only by default): rebuild happy-cli and restart daemon when code changes.
+  const watchEnabled =
+    flags.has('--watch') || (!flags.has('--no-watch') && Boolean(process.stdin.isTTY && process.stdout.isTTY));
+  const watchers = [];
 
   const serverAlreadyRunning = await isHappyServerRunning(internalServerUrl);
   const daemonAlreadyRunning = startDaemon ? isDaemonRunning(cliHomeDir) : false;
@@ -118,63 +145,39 @@ async function main() {
     return;
   }
 
+  if (stackMode && runtimeStatePath) {
+    await recordStackRuntimeStart(runtimeStatePath, {
+      stackName,
+      script: 'dev.mjs',
+      ephemeral,
+      ownerPid: process.pid,
+      ports: { server: serverPort },
+    }).catch(() => {});
+  }
+
   // Start server (only if not already healthy)
-  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' });
   }
-  const serverEnv = {
-    ...baseEnv,
-    PORT: String(serverPort),
-    PUBLIC_URL: publicServerUrl,
-    // Avoid noisy failures if a previous run left the metrics port busy.
-    METRICS_ENABLED: baseEnv.METRICS_ENABLED ?? 'false',
-  };
-  if (serverComponentName === 'happy-server-light') {
-    const dataDir = baseEnv.HAPPY_SERVER_LIGHT_DATA_DIR?.trim()
-      ? baseEnv.HAPPY_SERVER_LIGHT_DATA_DIR.trim()
-      : join(autostart.baseDir, 'server-light');
-    serverEnv.HAPPY_SERVER_LIGHT_DATA_DIR = dataDir;
-    serverEnv.HAPPY_SERVER_LIGHT_FILES_DIR = baseEnv.HAPPY_SERVER_LIGHT_FILES_DIR?.trim()
-      ? baseEnv.HAPPY_SERVER_LIGHT_FILES_DIR.trim()
-      : join(dataDir, 'files');
-  }
-  if (serverComponentName === 'happy-server') {
-    const managed = (baseEnv.HAPPY_STACKS_MANAGED_INFRA ?? baseEnv.HAPPY_LOCAL_MANAGED_INFRA ?? '1') !== '0';
-    if (managed) {
-      const envPath = baseEnv.HAPPY_STACKS_ENV_FILE ?? baseEnv.HAPPY_LOCAL_ENV_FILE ?? '';
-      const infra = await ensureHappyServerManagedInfra({
-        stackName: autostart.stackName,
-        baseDir: autostart.baseDir,
-        serverPort,
-        publicServerUrl,
-        envPath,
-        env: baseEnv,
-      });
-      Object.assign(serverEnv, infra.env);
-    }
 
-    const autoMigrate = (baseEnv.HAPPY_STACKS_PRISMA_MIGRATE ?? baseEnv.HAPPY_LOCAL_PRISMA_MIGRATE ?? '1') !== '0';
-    if (autoMigrate) {
-      await applyHappyServerMigrations({ serverDir, env: serverEnv });
-    }
-  }
-  await ensureDepsInstalled(serverDir, serverComponentName);
-  // For happy-server: the upstream `dev` script is not stack-safe (kills fixed ports, reads .env.dev).
-  // Use `start` and rely on stack-scoped env + optional migrations above.
-  //
-  // For happy-server-light: the upstream `dev` script runs `prisma db push` automatically. If you want to skip
-  // it (e.g. big sqlite DB), set HAPPY_STACKS_PRISMA_PUSH=0 to use `start` even in dev mode.
-  const prismaPush = (baseEnv.HAPPY_STACKS_PRISMA_PUSH ?? baseEnv.HAPPY_LOCAL_PRISMA_PUSH ?? '1').trim() !== '0';
-  const serverScript =
-    serverComponentName === 'happy-server'
-      ? 'start'
-      : serverComponentName === 'happy-server-light' && !prismaPush
-        ? 'start'
-        : 'dev';
+  const { serverEnv, serverScript, serverProc } = await startDevServer({
+    serverComponentName,
+    serverDir,
+    autostart,
+    baseEnv,
+    serverPort,
+    internalServerUrl,
+    publicServerUrl,
+    envPath,
+    stackMode,
+    runtimeStatePath,
+    serverAlreadyRunning,
+    restart,
+    children,
+  });
+
   if (!serverAlreadyRunning || restart) {
-    const server = await pmSpawnScript({ label: 'server', dir: serverDir, script: serverScript, env: serverEnv });
-    children.push(server);
-    await waitForServerReady(internalServerUrl);
     console.log(`[local] server ready at ${internalServerUrl}`);
   } else {
     console.log(`[local] server already running at ${internalServerUrl}`);
@@ -186,66 +189,114 @@ async function main() {
     `export HAPPY_WEBAPP_URL=\"${publicServerUrl}\"\n`
   );
 
-  // Start daemon (detached daemon process managed by happy-cli)
-  if (startDaemon) {
-    await startLocalDaemonWithAuth({
-      cliBin,
-      cliHomeDir,
-      internalServerUrl,
-      publicServerUrl,
-      isShuttingDown: () => shuttingDown,
-      forceRestart: restart,
-    });
+  // Reliability before daemon start:
+  // - Ensure schema exists (server-light: db push; happy-server: migrate deploy if tables missing)
+  // - Auto-seed from main only when needed (non-main + non-interactive default, and only if missing creds or 0 accounts)
+  const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  await prepareDaemonAuthSeed({
+    rootDir,
+    env: baseEnv,
+    stackName,
+    cliHomeDir,
+    startDaemon,
+    isInteractive,
+    serverComponentName,
+    serverDir,
+    serverEnv,
+    quiet: false,
+  });
+
+  await startDevDaemon({
+    startDaemon,
+    cliBin,
+    cliHomeDir,
+    internalServerUrl,
+    publicServerUrl,
+    restart,
+    isShuttingDown: () => shuttingDown,
+  });
+
+  const cliWatcher = watchHappyCliAndRestartDaemon({
+    enabled: watchEnabled,
+    startDaemon,
+    buildCli,
+    cliDir,
+    cliBin,
+    cliHomeDir,
+    internalServerUrl,
+    publicServerUrl,
+    isShuttingDown: () => shuttingDown,
+  });
+  if (cliWatcher) watchers.push(cliWatcher);
+
+  const serverProcRef = { current: serverProc };
+  if (stackMode && runtimeStatePath && !serverProcRef.current?.pid) {
+    // If the server was already running when we started dev, `startDevServer` won't spawn a new process
+    // (and therefore we don't have a ChildProcess handle). For safe watch/restart we need a PID.
+    const state = await readStackRuntimeStateFile(runtimeStatePath);
+    const pid = state?.processes?.serverPid;
+    if (isPidAlive(pid)) {
+      serverProcRef.current = { pid: Number(pid), exitCode: null };
+    }
+  }
+  const serverWatcher = watchDevServerAndRestart({
+    enabled: watchEnabled && Boolean(serverProcRef.current?.pid),
+    stackMode,
+    serverComponentName,
+    serverDir,
+    serverPort,
+    internalServerUrl,
+    serverScript,
+    serverEnv,
+    runtimeStatePath,
+    stackName,
+    envPath,
+    children,
+    serverProcRef,
+    isShuttingDown: () => shuttingDown,
+  });
+  if (serverWatcher) watchers.push(serverWatcher);
+  if (watchEnabled && stackMode && serverComponentName === 'happy-server' && !serverWatcher) {
+    console.warn(
+      `[local] watch: server restart is disabled because the running server PID is unknown.\n` +
+        `[local] watch: fix: re-run with --restart so Happy Stacks can (re)spawn the server and track its PID.`
+    );
   }
 
-  // Start UI (Expo web dev server)
+  const uiRes = await startDevExpoWebUi({
+    startUi,
+    uiDir,
+    autostart,
+    baseEnv,
+    apiServerUrl: uiApiUrl,
+    restart,
+    stackMode,
+    runtimeStatePath,
+    stackName,
+    envPath,
+    children,
+  });
   if (startUi) {
-    await ensureDepsInstalled(uiDir, 'happy');
-    const uiEnv = { ...baseEnv };
-    delete uiEnv.CI;
-    uiEnv.EXPO_PUBLIC_HAPPY_SERVER_URL = publicServerUrl;
-    uiEnv.EXPO_PUBLIC_DEBUG = uiEnv.EXPO_PUBLIC_DEBUG ?? '1';
-
-    await ensureExpoIsolationEnv({
-      env: uiEnv,
-      stateDir: uiPaths.stateDir,
-      expoHomeDir: uiPaths.expoHomeDir,
-      tmpDir: uiPaths.tmpDir,
-    });
-
-    // Expo uses Metro (default 8081). If it's already used by another worktree/stack,
-    // Expo prompts to pick another port, which fails in non-interactive mode.
-    // Pick a free port up-front to make LLM/CI/service runs reliable.
-    const defaultMetroPort = 8081;
-    const metroPort = await pickNextFreeTcpPort(defaultMetroPort);
-    uiEnv.RCT_METRO_PORT = String(metroPort);
-    // eslint-disable-next-line no-console
-    console.log(`[local] ui: starting Expo web (metro port=${metroPort})`);
-
-    const uiArgs = ['start', '--web', '--port', String(metroPort)];
-    if (wantsExpoClearCache({ env: baseEnv })) {
-      uiArgs.push('--clear');
+    const host = resolveLocalhostHost({ stackMode, stackName });
+    if (uiRes?.reason === 'already_running' && uiRes.port) {
+      console.log(`[local] ui already running (pid=${uiRes.pid}, port=${uiRes.port})`);
+      console.log(`[local] ui: open http://${host}:${uiRes.port}`);
+    } else if (uiRes?.skipped === false && uiRes.port) {
+      console.log(`[local] ui: open http://${host}:${uiRes.port}`);
+    } else if (uiRes?.skipped && uiRes?.reason === 'already_running') {
+      console.log('[local] ui already running (skipping Expo start)');
     }
 
-    if (!uiAlreadyRunning || restart) {
-      if (restart && uiRunning.state?.pid) {
-        const prevPid = Number(uiRunning.state.pid);
-        const prevPort = Number(uiRunning.state.port);
-        if (Number.isFinite(prevPort) && prevPort > 0) {
-          await killPortListeners(prevPort, { label: 'ui' });
-        }
-        await killPid(prevPid);
-        uiAlreadyRunning = false;
+    const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const shouldOpen = isInteractive && !noBrowser && Boolean(uiRes?.port);
+    if (shouldOpen) {
+      const url = `http://${host}:${uiRes.port}`;
+      // Prefer localhost for readiness checks (faster/more reliable), but open the stack-scoped hostname.
+      await waitForHttpOk(`http://localhost:${uiRes.port}`, { timeoutMs: 30_000 }).catch(() => {});
+      const res = await openUrlInBrowser(url);
+      if (!res.ok) {
+        console.warn(`[local] ui: failed to open browser automatically (${res.error}).`);
       }
-      const ui = await pmSpawnBin({ label: 'ui', dir: uiDir, bin: 'expo', args: uiArgs, env: uiEnv });
-      children.push(ui);
-      try {
-        await writePidState(uiPaths.statePath, { pid: ui.pid, port: metroPort, uiDir, startedAt: new Date().toISOString() });
-      } catch {
-        // ignore
-      }
-    } else {
-      console.log('[local] ui already running (skipping Expo start)');
     }
   }
 
@@ -256,6 +307,14 @@ async function main() {
     shuttingDown = true;
     console.log('\n[local] shutting down...');
 
+    for (const w of watchers) {
+      try {
+        w.close();
+      } catch {
+        // ignore
+      }
+    }
+
     if (startDaemon) {
       await stopLocalDaemon({ cliBin, internalServerUrl, cliHomeDir });
     }

package/scripts/doctor.mjs

@@ -1,19 +1,24 @@
-import './utils/env.mjs';
-import { parseArgs } from './utils/args.mjs';
-import { pathExists } from './utils/fs.mjs';
-import { runCapture } from './utils/proc.mjs';
-import { getComponentDir, getDefaultAutostartPaths, getHappyStacksHomeDir, getRootDir, getWorkspaceDir, resolveStackEnvPath } from './utils/paths.mjs';
-import { killPortListeners } from './utils/ports.mjs';
-import { getServerComponentName } from './utils/server.mjs';
+import './utils/env/env.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { pathExists } from './utils/fs/fs.mjs';
+import { runCapture } from './utils/proc/proc.mjs';
+import { resolveCommandPath } from './utils/proc/commands.mjs';
+import { getComponentDir, getDefaultAutostartPaths, getHappyStacksHomeDir, getRootDir, getWorkspaceDir, resolveStackEnvPath } from './utils/paths/paths.mjs';
+import { killPortListeners } from './utils/net/ports.mjs';
+import { getServerComponentName } from './utils/server/server.mjs';
+import { fetchHappyHealth } from './utils/server/server.mjs';
 import { daemonStatusSummary } from './daemon.mjs';
-import { tailscaleServeStatus, resolvePublicServerUrl } from './tailscale.mjs';
+import { tailscaleServeStatus } from './tailscale.mjs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
-import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
-import { getRuntimeDir } from './utils/runtime.mjs';
-import { assertServerComponentDirMatches } from './utils/validate.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { getRuntimeDir } from './utils/paths/runtime.mjs';
+import { assertServerComponentDirMatches } from './utils/server/validate.mjs';
+import { resolveServerPortFromEnv, resolveServerUrls } from './utils/server/urls.mjs';
+import { resolveStackContext } from './utils/stack/context.mjs';
+import { readJsonIfExists } from './utils/fs/json.mjs';
+import { readPackageJsonVersion } from './utils/fs/package_json.mjs';
 
 /**
  * Doctor script for common happy-stacks failure modes.
@@ -41,7 +46,8 @@ async function fetchHealth(url) {
   };
 
   // Prefer /health when available, but fall back to / (matches waitForServerReady).
-  const health = await tryGet('/health');
+  const healthRaw = await fetchHappyHealth(url);
+  const health = { ok: healthRaw.ok, status: healthRaw.status, body: healthRaw.text ? healthRaw.text.trim() : null };
   if (health.ok) {
     return health;
   }
@@ -52,26 +58,6 @@ async function fetchHealth(url) {
   return health.ok ? health : root;
 }
 
-async function readJsonSafe(path) {
-  try {
-    const raw = await readFile(path, 'utf-8');
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
-async function readPkgVersion(path) {
-  try {
-    const raw = await readFile(path, 'utf-8');
-    const pkg = JSON.parse(raw);
-    const v = String(pkg.version ?? '').trim();
-    return v || null;
-  } catch {
-    return null;
-  }
-}
-
 async function resolveSwiftbarPluginsDir() {
   if (process.platform !== 'darwin') {
     return null;
@@ -112,30 +98,26 @@ async function main() {
   const workspaceDir = getWorkspaceDir(rootDir);
   const updateCachePath = join(homeDir, 'cache', 'update.json');
   const runtimePkgJson = join(runtimeDir, 'node_modules', 'happy-stacks', 'package.json');
-  const runtimeVersion = await readPkgVersion(runtimePkgJson);
-  const updateCache = existsSync(updateCachePath) ? await readJsonSafe(updateCachePath) : null;
+  const runtimeVersion = await readPackageJsonVersion(runtimePkgJson);
+  const updateCache = await readJsonIfExists(updateCachePath, { defaultValue: null });
 
-  const serverPort = process.env.HAPPY_LOCAL_SERVER_PORT?.trim() ? Number(process.env.HAPPY_LOCAL_SERVER_PORT) : 3005;
-  const internalServerUrl = `http://127.0.0.1:${serverPort}`;
+  const autostart = getDefaultAutostartPaths();
+  const stackCtx = resolveStackContext({ env: process.env, autostart });
+  const stackMode = stackCtx.stackMode;
 
-  const defaultPublicUrl = `http://localhost:${serverPort}`;
-  const envPublicUrl = process.env.HAPPY_LOCAL_SERVER_URL?.trim() ? process.env.HAPPY_LOCAL_SERVER_URL.trim() : '';
-  const resolved = await resolvePublicServerUrl({
-    internalServerUrl,
-    defaultPublicUrl,
-    envPublicUrl,
-    allowEnable: false,
-  });
-  const publicServerUrl = resolved.publicServerUrl;
+  const serverPort = resolveServerPortFromEnv({ defaultPort: 3005 });
+  const resolvedUrls = await resolveServerUrls({ serverPort, allowEnable: false });
+  const internalServerUrl = resolvedUrls.internalServerUrl;
+  const publicServerUrl = resolvedUrls.publicServerUrl;
 
   const cliHomeDir = process.env.HAPPY_LOCAL_CLI_HOME_DIR?.trim()
     ? process.env.HAPPY_LOCAL_CLI_HOME_DIR.trim().replace(/^~(?=\/)/, homedir())
-    : join(getDefaultAutostartPaths().baseDir, 'cli');
+    : join(autostart.baseDir, 'cli');
 
   const serveUi = (process.env.HAPPY_LOCAL_SERVE_UI ?? '1') !== '0';
   const uiBuildDir = process.env.HAPPY_LOCAL_UI_BUILD_DIR?.trim()
     ? process.env.HAPPY_LOCAL_UI_BUILD_DIR.trim()
-    : join(getDefaultAutostartPaths().baseDir, 'ui');
+    : join(autostart.baseDir, 'ui');
 
   const serverComponentName = getServerComponentName({ kv });
   if (serverComponentName === 'both') {
@@ -206,8 +188,15 @@ async function main() {
     report.checks.serverHealth = { ok: false };
     if (!json) console.log(`❌ server health: unreachable (${internalServerUrl})`);
     if (fix) {
-      if (!json) console.log(`↪ attempting fix: freeing tcp:${serverPort}`);
-      await killPortListeners(serverPort, { label: 'doctor' });
+      if (stackMode) {
+        if (!json) {
+          console.log(`↪ fix skipped: refusing to kill unknown port listeners in stack mode.`);
+          console.log(`↪ Fix: use stack-safe controls instead: happys stack stop ${process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? 'main'} --aggressive`);
+        }
+      } else {
+        if (!json) console.log(`↪ attempting fix: freeing tcp:${serverPort}`);
+        await killPortListeners(serverPort, { label: 'doctor' });
+      }
     }
   }
 
@@ -297,26 +286,26 @@ async function main() {
 
   // happy wrapper
   try {
-    const happyPath = (await runCapture('sh', ['-lc', 'command -v happy'])).trim();
+    const happyPath = await resolveCommandPath('happy');
     if (happyPath) {
       report.checks.happyOnPath = { ok: true, path: happyPath };
       if (!json) console.log(`✅ happy on PATH: ${happyPath}`);
     }
   } catch {
     report.checks.happyOnPath = { ok: false };
-    if (!json) console.log('ℹ️ happy on PATH: not found (run: happys init --install-path, or add ~/.happy-stacks/bin to PATH)');
+    if (!json) console.log(`ℹ️ happy on PATH: not found (run: happys init --install-path, or add ${join(getHappyStacksHomeDir(), 'bin')} to PATH)`);
   }
 
   // happys on PATH
   try {
-    const happysPath = (await runCapture('sh', ['-lc', 'command -v happys'])).trim();
+    const happysPath = await resolveCommandPath('happys');
     if (happysPath) {
       report.checks.happysOnPath = { ok: true, path: happysPath };
       if (!json) console.log(`✅ happys on PATH: ${happysPath}`);
     }
   } catch {
     report.checks.happysOnPath = { ok: false };
-    if (!json) console.log('ℹ️ happys on PATH: not found (run: happys init --install-path, or add ~/.happy-stacks/bin to PATH)');
+    if (!json) console.log(`ℹ️ happys on PATH: not found (run: happys init --install-path, or add ${join(getHappyStacksHomeDir(), 'bin')} to PATH)`);
   }
 
   if (!json) {
@@ -326,7 +315,7 @@ async function main() {
       console.log('- Install a stable runtime (recommended for SwiftBar/services): happys self update');
     }
     if (!report.checks.happysOnPath?.ok) {
-      console.log('- Add shims to PATH: export PATH="$HOME/.happy-stacks/bin:$PATH" (or: happys init --install-path)');
+      console.log(`- Add shims to PATH: export PATH="${join(getHappyStacksHomeDir(), 'bin')}:$PATH" (or: happys init --install-path)`);
     }
     console.log('');
   }