happy-stacks 0.2.0 → 0.3.0

package/README.md

@@ -23,13 +23,6 @@ Recommended:
 npx happy-stacks setup --profile=selfhost
 ```
 
-Alternative (global install):
-
-```bash
-npm install -g happy-stacks
-happys setup --profile=selfhost
-```
-
 `setup` can optionally start Happy and guide you through authentication.
 
 ### Step 2: Start Happy
@@ -192,7 +185,10 @@ happys wt pr happy https://github.com/slopus/happy/pull/123 --use
 happys wt pr happy 123 --update --stash
 ```
 
-Create a fully isolated PR stack (creates stack + PR worktrees + optional auth seeding + starts dev):
+##### Developer quickstart: create a PR stack (isolated ports/dirs; idempotent updates)
+
+This creates (or reuses) a named stack, checks out PR worktrees for the selected components, optionally seeds auth, and starts the stack.
+Re-run with `--reuse` to update the existing worktrees when the PR changes.
 
 ```bash
 happys stack pr pr123 \
@@ -202,15 +198,27 @@ happys stack pr pr123 \
   --dev
 ```
 
-One-shot “install + run PR stack” (best for maintainers who don’t have Happy Stacks set up yet):
+Optional: run it in a self-contained sandbox folder (delete it to uninstall completely):
 
 ```bash
-npx happy-stacks setup pr \
-  --happy=https://github.com/slopus/happy/pull/123 \
-  --happy-cli=https://github.com/slopus/happy-cli/pull/456
+SANDBOX="$(mktemp -d /tmp/happy-stacks-sandbox.XXXXXX)"
+happys --sandbox-dir "$SANDBOX" stack pr pr123 --happy=123 --happy-cli=456 --dev
+rm -rf "$SANDBOX"
 ```
 
-You can also run it as:
+Update when the PR changes:
+
+- Re-run with `--reuse` to fast-forward worktrees when possible.
+- If the PR was force-pushed, add `--force`.
+
+```bash
+happys stack pr pr123 --happy=123 --happy-cli=456 --reuse
+happys stack pr pr123 --happy=123 --happy-cli=456 --reuse --force
+```
+
+##### Maintainer quickstart: one-shot “install + run PR stack” (idempotent)
+
+This is the maintainer-friendly entrypoint. It is safe to re-run and will keep the PR stack wiring intact.
 
 ```bash
 npx happy-stacks setup-pr \
@@ -218,11 +226,36 @@ npx happy-stacks setup-pr \
   --happy-cli=https://github.com/slopus/happy-cli/pull/456
 ```
 
-Updating when the PR changes:
+Optional: run it in a self-contained sandbox folder (delete it to uninstall completely):
+
+```bash
+SANDBOX="$(mktemp -d /tmp/happy-stacks-sandbox.XXXXXX)"
+npx happy-stacks --sandbox-dir "$SANDBOX" setup-pr --happy=123 --happy-cli=456
+rm -rf "$SANDBOX"
+```
+
+Short form (PR numbers):
+
+```bash
+npx happy-stacks setup-pr --happy=123 --happy-cli=456
+```
+
+Override stack name (optional):
+
+```bash
+npx happy-stacks setup-pr --name=pr123 --happy=123 --happy-cli=456
+```
+
+Update when the PR changes:
 
 - Re-run the same command to fast-forward the PR worktrees.
 - If the PR was force-pushed, add `--force`.
 
+```bash
+npx happy-stacks setup-pr --happy=123 --happy-cli=456
+npx happy-stacks setup-pr --happy=123 --happy-cli=456 --force
+```
+
 Details: `[docs/worktrees-and-forks.md](docs/worktrees-and-forks.md)`.
 
 #### Server flavor (server-light vs full server)
@@ -352,19 +385,23 @@ Notes:
 
 ### Sandbox / test installs (fully isolated)
 
-If you want to test the full setup flow (including PR stacks) without impacting your “real” install, run with:
+If you want to test the full setup flow (including PR stacks) without impacting your “real” install, run everything with `--sandbox-dir`.
+To fully uninstall the test run, stop the sandbox stacks and delete the sandbox folder.
 
 ```bash
-npx happy-stacks --sandbox-dir /tmp/happy-stacks-sandbox setup pr --happy=123 --happy-cli=456
-```
+SANDBOX="$(mktemp -d /tmp/happy-stacks-sandbox.XXXXXX)"
 
-To reset completely, just delete the sandbox folder:
+# Run a PR stack (fully isolated install)
+npx happy-stacks --sandbox-dir "$SANDBOX" setup-pr --happy=123 --happy-cli=456
 
-```bash
-rm -rf /tmp/happy-stacks-sandbox
+# Tear down + uninstall
+npx happy-stacks --sandbox-dir "$SANDBOX" stop --yes --no-service
+rm -rf "$SANDBOX"
 ```
 
-Sandbox mode disables global OS side effects (PATH edits, SwiftBar plugin install, LaunchAgents/systemd services) by default.
-To explicitly allow them for testing, set `HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1`.
+Notes:
+
+- Sandbox mode disables global OS side effects (**PATH edits**, **SwiftBar plugin install**, **LaunchAgents/systemd services**, **Tailscale Serve enable/disable**) by default.
+- To explicitly allow those for testing, set `HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1` (still recommended to clean up after).
 
 For contributor/LLM workflow expectations: `[AGENTS.md](AGENTS.md)`.

package/bin/happys.mjs

@@ -8,13 +8,13 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { commandHelpArgs, renderHappysRootHelp, resolveHappysCommand } from '../scripts/utils/cli/cli_registry.mjs';
-import { expandHome, getCanonicalHomeEnvPathFromEnv } from '../scripts/utils/canonical_home.mjs';
+import { expandHome, getCanonicalHomeEnvPathFromEnv } from '../scripts/utils/paths/canonical_home.mjs';
 
 function getCliRootDir() {
   return dirname(dirname(fileURLToPath(import.meta.url)));
 }
 
-// expandHome is imported from scripts/utils/canonical_home.mjs
+// expandHome is imported from scripts/utils/paths/canonical_home.mjs
 
 function dotenvGetQuick(envPath, key) {
   try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "happy-stacks",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "packageManager": "pnpm@10.18.3",
   "bin": {
     "happys": "./bin/happys.mjs",

package/scripts/auth.mjs

@@ -1,99 +1,47 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { getComponentDir, getDefaultAutostartPaths, getRootDir, getStackName, resolveStackEnvPath } from './utils/paths.mjs';
-import { listAllStackNames } from './utils/stacks.mjs';
+import { getComponentDir, getDefaultAutostartPaths, getRootDir, getStackName, resolveStackEnvPath } from './utils/paths/paths.mjs';
+import { listAllStackNames } from './utils/stack/stacks.mjs';
 import { resolvePublicServerUrl } from './tailscale.mjs';
-import { resolveServerPortFromEnv } from './utils/server_urls.mjs';
+import { getInternalServerUrl, getPublicServerUrlEnvOverride, getWebappUrlEnvOverride } from './utils/server/urls.mjs';
+import { fetchHappyHealth } from './utils/server/server.mjs';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { spawn } from 'node:child_process';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 
-import { parseDotenv } from './utils/dotenv.mjs';
-import { ensureDepsInstalled, pmExecBin } from './utils/pm.mjs';
-import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from './utils/happy_server_infra.mjs';
-import { clearDevAuthKey, readDevAuthKey, writeDevAuthKey } from './utils/dev_auth_key.mjs';
-import { getExpoStatePaths, isStateProcessRunning } from './utils/expo.mjs';
-import { resolveAuthSeedFromEnv } from './utils/stack_startup.mjs';
-import { printAuthLoginInstructions } from './utils/auth_login_ux.mjs';
-import { copyFileIfMissing, linkFileIfMissing, removeFileOrSymlinkIfExists, writeSecretFileIfMissing } from './utils/auth_files.mjs';
-import { getLegacyHappyBaseDir, isLegacyAuthSourceName } from './utils/auth_sources.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
-import { resolveHandyMasterSecretFromStack } from './utils/handy_master_secret.mjs';
-
-function getInternalServerUrl() {
-  const n = resolveServerPortFromEnv({ env: process.env, defaultPort: 3005 });
-  return { port: n, url: `http://127.0.0.1:${n}` };
-}
-
-function resolveEnvPublicUrlForStack({ stackName }) {
-  const candidate = (process.env.HAPPY_LOCAL_SERVER_URL ?? process.env.HAPPY_STACKS_SERVER_URL ?? '').trim();
-
-  // For main, allow the user's global/public URL override (commonly a Tailscale Serve URL).
-  if (stackName === 'main') {
-    return candidate;
-  }
-
-  // For non-main stacks, do NOT inherit a global/server URL override from ~/.happy-stacks/env.local
-  // (which often points at main). Only use a public URL override if it is explicitly present in the
-  // stack env file itself.
-  const envPath =
-    (process.env.HAPPY_STACKS_ENV_FILE ?? '').trim() ||
-    (process.env.HAPPY_LOCAL_ENV_FILE ?? '').trim() ||
-    getStackEnvPath(stackName);
-  try {
-    if (!envPath || !existsSync(envPath)) return '';
-    const raw = readFileSync(envPath, 'utf-8');
-    const env = raw ? parseEnvToObject(raw) : {};
-    return (env.HAPPY_LOCAL_SERVER_URL ?? env.HAPPY_STACKS_SERVER_URL ?? '').toString().trim();
-  } catch {
-    return '';
-  }
-}
-
-function expandTilde(p) {
-  return p.replace(/^~(?=\/)/, homedir());
-}
-
-function resolveEnvWebappUrlForStack({ stackName }) {
-  const candidate = (process.env.HAPPY_WEBAPP_URL ?? '').trim();
-
-  // For main, allow the user's global override.
-  if (stackName === 'main') {
-    return candidate;
-  }
-
-  // For non-main stacks, only respect HAPPY_WEBAPP_URL if it is explicitly present in the stack env file.
-  const envPath =
-    (process.env.HAPPY_STACKS_ENV_FILE ?? '').trim() ||
-    (process.env.HAPPY_LOCAL_ENV_FILE ?? '').trim() ||
-    getStackEnvPath(stackName);
-  try {
-    if (!envPath || !existsSync(envPath)) return '';
-    const raw = readFileSync(envPath, 'utf-8');
-    const env = raw ? parseEnvToObject(raw) : {};
-    return (env.HAPPY_WEBAPP_URL ?? '').toString().trim();
-  } catch {
-    return '';
-  }
-}
-
-function sanitizeDnsLabel(raw, { fallback = 'stack' } = {}) {
-  const s = String(raw ?? '')
-    .toLowerCase()
-    .replace(/[^a-z0-9-]+/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^-+/, '')
-    .replace(/-+$/, '');
-  return s || fallback;
+import { parseEnvToObject } from './utils/env/dotenv.mjs';
+import { ensureDepsInstalled, pmExecBin } from './utils/proc/pm.mjs';
+import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from './utils/server/infra/happy_server_infra.mjs';
+import { clearDevAuthKey, readDevAuthKey, writeDevAuthKey } from './utils/auth/dev_key.mjs';
+import { getExpoStatePaths, isStateProcessRunning } from './utils/expo/expo.mjs';
+import { resolveAuthSeedFromEnv } from './utils/stack/startup.mjs';
+import { printAuthLoginInstructions } from './utils/auth/login_ux.mjs';
+import { copyFileIfMissing, linkFileIfMissing, removeFileOrSymlinkIfExists, writeSecretFileIfMissing } from './utils/auth/files.mjs';
+import { getLegacyHappyBaseDir, isLegacyAuthSourceName } from './utils/auth/sources.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
+import { resolveHandyMasterSecretFromStack } from './utils/auth/handy_master_secret.mjs';
+import { ensureDir, readTextIfExists } from './utils/fs/ops.mjs';
+import { stackExistsSync } from './utils/stack/stacks.mjs';
+import { checkDaemonState } from './daemon.mjs';
+import {
+  getCliHomeDirFromEnvOrDefault,
+  getServerLightDataDirFromEnvOrDefault,
+  resolveCliHomeDir,
+} from './utils/stack/dirs.mjs';
+import { resolveLocalhostHost } from './utils/paths/localhost_host.mjs';
+
+function getInternalServerUrlCompat() {
+  const { port, internalServerUrl } = getInternalServerUrl({ env: process.env, defaultPort: 3005 });
+  return { port, url: internalServerUrl };
 }
 
 async function resolveWebappUrlFromRunningExpo({ rootDir, stackName }) {
   try {
-    const baseDir = getStackDir(stackName);
+    const baseDir = resolveStackEnvPath(stackName).baseDir;
     const uiDir = getComponentDir(rootDir, 'happy');
     const uiPaths = getExpoStatePaths({
       baseDir,
@@ -105,66 +53,16 @@ async function resolveWebappUrlFromRunningExpo({ rootDir, stackName }) {
     if (!uiRunning.running) return null;
     const port = Number(uiRunning.state?.port);
     if (!Number.isFinite(port) || port <= 0) return null;
-    const host = stackName && stackName !== 'main' ? `happy-${sanitizeDnsLabel(stackName)}.localhost` : 'localhost';
+    const host = resolveLocalhostHost({ stackMode: stackName !== 'main', stackName });
     return `http://${host}:${port}`;
   } catch {
     return null;
   }
 }
 
-async function ensureDir(p) {
-  await mkdir(p, { recursive: true });
-}
-
-async function readTextIfExists(path) {
-  try {
-    if (!existsSync(path)) return null;
-    const raw = await readFile(path, 'utf-8');
-    const t = raw.trim();
-    return t ? t : null;
-  } catch {
-    return null;
-  }
-}
+// NOTE: common fs helpers live in scripts/utils/fs/ops.mjs
 
-// (auth file copy/link helpers live in scripts/utils/auth_files.mjs)
-
-function parseEnvToObject(raw) {
-  const parsed = parseDotenv(raw);
-  return Object.fromEntries(parsed.entries());
-}
-
-function getStackDir(stackName) {
-  return resolveStackEnvPath(stackName).baseDir;
-}
-
-function getStackEnvPath(stackName) {
-  return resolveStackEnvPath(stackName).envPath;
-}
-
-function stackExistsSync(stackName) {
-  if (stackName === 'main') return true;
-  const envPath = getStackEnvPath(stackName);
-  return existsSync(envPath);
-}
-
-function getCliHomeDirFromEnvOrDefault({ stackBaseDir, env }) {
-  const fromEnv = (env.HAPPY_STACKS_CLI_HOME_DIR ?? env.HAPPY_LOCAL_CLI_HOME_DIR ?? '').trim();
-  return fromEnv || join(stackBaseDir, 'cli');
-}
-
-function getServerLightDataDirFromEnvOrDefault({ stackBaseDir, env }) {
-  const fromEnv = (env.HAPPY_SERVER_LIGHT_DATA_DIR ?? '').trim();
-  return fromEnv || join(stackBaseDir, 'server-light');
-}
-
-function resolveCliHomeDir() {
-  const fromEnv = (process.env.HAPPY_LOCAL_CLI_HOME_DIR ?? process.env.HAPPY_STACKS_CLI_HOME_DIR ?? '').trim();
-  if (fromEnv) {
-    return expandTilde(fromEnv);
-  }
-  return join(getDefaultAutostartPaths().baseDir, 'cli');
-}
+// (auth file copy/link helpers live in scripts/utils/auth/files.mjs)
 
 function fileHasContent(path) {
   try {
@@ -175,60 +73,6 @@ function fileHasContent(path) {
   }
 }
 
-function checkDaemonState(cliHomeDir) {
-  const statePath = join(cliHomeDir, 'daemon.state.json');
-  const lockPath = join(cliHomeDir, 'daemon.state.json.lock');
-
-  const alive = (pid) => {
-    try {
-      process.kill(pid, 0);
-      return true;
-    } catch {
-      return false;
-    }
-  };
-
-  if (existsSync(statePath)) {
-    try {
-      const state = JSON.parse(readFileSync(statePath, 'utf-8'));
-      const pid = Number(state?.pid);
-      if (Number.isFinite(pid) && pid > 0) {
-        return alive(pid) ? { status: 'running', pid } : { status: 'stale_state', pid };
-      }
-      return { status: 'bad_state' };
-    } catch {
-      return { status: 'bad_state' };
-    }
-  }
-
-  if (existsSync(lockPath)) {
-    try {
-      const pid = Number(readFileSync(lockPath, 'utf-8').trim());
-      if (Number.isFinite(pid) && pid > 0) {
-        return alive(pid) ? { status: 'starting', pid } : { status: 'stale_lock', pid };
-      }
-    } catch {
-      // ignore
-    }
-  }
-
-  return { status: 'stopped' };
-}
-
-async function fetchHealth(internalServerUrl) {
-  const ctl = new AbortController();
-  const t = setTimeout(() => ctl.abort(), 1500);
-  try {
-    const res = await fetch(`${internalServerUrl}/health`, { method: 'GET', signal: ctl.signal });
-    const body = (await res.text()).trim();
-    return { ok: res.ok, status: res.status, body };
-  } catch {
-    return { ok: false, status: null, body: null };
-  } finally {
-    clearTimeout(t);
-  }
-}
-
 function authLoginSuggestion(stackName) {
   return stackName === 'main' ? 'happys auth login' : `happys stack auth ${stackName} login`;
 }
@@ -678,8 +522,8 @@ async function cmdCopyFrom({ argv, json }) {
     }
   }
 
-  const sourceBaseDir = isLegacySource ? getLegacyHappyBaseDir() : getStackDir(fromStackName);
-  const sourceEnvRaw = isLegacySource ? '' : await readTextIfExists(getStackEnvPath(fromStackName));
+  const sourceBaseDir = isLegacySource ? getLegacyHappyBaseDir() : resolveStackEnvPath(fromStackName).baseDir;
+  const sourceEnvRaw = isLegacySource ? '' : await readTextIfExists(resolveStackEnvPath(fromStackName).envPath);
   const sourceEnv = sourceEnvRaw ? parseEnvToObject(sourceEnvRaw) : {};
   const sourceCli = isLegacySource
     ? join(sourceBaseDir, 'cli')
@@ -735,9 +579,9 @@ async function cmdCopyFrom({ argv, json }) {
       // so we can seed DB accounts reliably.
       const managed = (targetEnv.HAPPY_STACKS_MANAGED_INFRA ?? targetEnv.HAPPY_LOCAL_MANAGED_INFRA ?? '1').toString().trim() !== '0';
       if (targetServerComponent === 'happy-server' && withInfra && managed) {
-        const { port } = getInternalServerUrl();
+        const { port } = getInternalServerUrlCompat();
         const publicServerUrl = `http://localhost:${port}`;
-        const envPath = getStackEnvPath(stackName);
+        const envPath = resolveStackEnvPath(stackName).envPath;
         const infra = await ensureHappyServerManagedInfra({
           stackName,
           baseDir: targetBaseDir,
@@ -838,9 +682,8 @@ async function cmdStatus({ json }) {
   const rootDir = getRootDir(import.meta.url);
   const stackName = getStackName();
 
-  const { port, url: internalServerUrl } = getInternalServerUrl();
-  const defaultPublicUrl = `http://localhost:${port}`;
-  const envPublicUrl = resolveEnvPublicUrlForStack({ stackName });
+  const { port, url: internalServerUrl } = getInternalServerUrlCompat();
+  const { defaultPublicUrl, envPublicUrl } = getPublicServerUrlEnvOverride({ env: process.env, serverPort: port, stackName });
   const { publicServerUrl } = await resolvePublicServerUrl({
     internalServerUrl,
     defaultPublicUrl,
@@ -861,7 +704,12 @@ async function cmdStatus({ json }) {
   };
 
   const daemon = checkDaemonState(cliHomeDir);
-  const health = await fetchHealth(internalServerUrl);
+  const healthRaw = await fetchHappyHealth(internalServerUrl);
+  const health = {
+    ok: Boolean(healthRaw.ok),
+    status: healthRaw.status,
+    body: healthRaw.text ? healthRaw.text.trim() : null,
+  };
 
   const out = {
     stackName,
@@ -924,16 +772,15 @@ async function cmdLogin({ argv, json }) {
   const stackName = getStackName();
   const { kv } = parseArgs(argv);
 
-  const { port, url: internalServerUrl } = getInternalServerUrl();
-  const defaultPublicUrl = `http://localhost:${port}`;
-  const envPublicUrl = resolveEnvPublicUrlForStack({ stackName });
+  const { port, url: internalServerUrl } = getInternalServerUrlCompat();
+  const { defaultPublicUrl, envPublicUrl } = getPublicServerUrlEnvOverride({ env: process.env, serverPort: port, stackName });
   const { publicServerUrl } = await resolvePublicServerUrl({
     internalServerUrl,
     defaultPublicUrl,
     envPublicUrl,
     allowEnable: false,
   });
-  const envWebappUrl = resolveEnvWebappUrlForStack({ stackName });
+  const { envWebappUrl } = getWebappUrlEnvOverride({ env: process.env, stackName });
   const expoWebappUrl = await resolveWebappUrlFromRunningExpo({ rootDir, stackName });
   const webappUrl = envWebappUrl || expoWebappUrl || publicServerUrl;
   const webappUrlSource = expoWebappUrl ? 'expo' : envWebappUrl ? 'stack env override' : 'server';

package/scripts/build.mjs

@@ -1,7 +1,8 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
-import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths.mjs';
-import { ensureDepsInstalled, pmExecBin, requireDir } from './utils/pm.mjs';
+import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths/paths.mjs';
+import { ensureDepsInstalled, pmExecBin, requireDir } from './utils/proc/pm.mjs';
+import { resolveServerPortFromEnv } from './utils/server/urls.mjs';
 import { dirname, join } from 'node:path';
 import { readFile, rm, mkdir, writeFile } from 'node:fs/promises';
 import { tailscaleServeHttpsUrl } from './tailscale.mjs';
@@ -43,9 +44,7 @@ async function main() {
   const uiDir = getComponentDir(rootDir, 'happy');
   await requireDir('happy', uiDir);
 
-  const serverPort = process.env.HAPPY_LOCAL_SERVER_PORT
-    ? parseInt(process.env.HAPPY_LOCAL_SERVER_PORT, 10)
-    : 3005;
+  const serverPort = resolveServerPortFromEnv({ env: process.env, defaultPort: 3005 });
 
   // For Tauri builds we embed an explicit API base URL (tauri:// origins cannot use window.location.origin).
   const internalServerUrl = `http://127.0.0.1:${serverPort}`;

package/scripts/cli-link.mjs

@@ -1,7 +1,7 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
-import { getComponentDir, getRootDir } from './utils/paths.mjs';
-import { ensureCliBuilt, ensureHappyCliLocalNpmLinked } from './utils/pm.mjs';
+import { getComponentDir, getRootDir } from './utils/paths/paths.mjs';
+import { ensureCliBuilt, ensureHappyCliLocalNpmLinked } from './utils/proc/pm.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 
 /**

package/scripts/completion.mjs

@@ -1,4 +1,4 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
@@ -7,11 +7,11 @@ import { join } from 'node:path';
 
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { runCapture } from './utils/proc.mjs';
+import { runCapture } from './utils/proc/proc.mjs';
 import { getHappysRegistry } from './utils/cli/cli_registry.mjs';
-import { expandHome } from './utils/canonical_home.mjs';
-import { getHappyStacksHomeDir, getRootDir } from './utils/paths.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
+import { expandHome } from './utils/paths/canonical_home.mjs';
+import { getHappyStacksHomeDir, getRootDir } from './utils/paths/paths.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
 
 function detectShell() {
   const raw = (process.env.SHELL ?? '').toLowerCase();

package/scripts/daemon.mjs

@@ -1,7 +1,9 @@
-import { spawnProc, run, runCapture } from './utils/proc.mjs';
-import { resolveAuthSeedFromEnv } from './utils/stack_startup.mjs';
-import { getStacksStorageRoot } from './utils/paths.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
+import { spawnProc, run, runCapture } from './utils/proc/proc.mjs';
+import { resolveAuthSeedFromEnv } from './utils/stack/startup.mjs';
+import { getStacksStorageRoot } from './utils/paths/paths.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
+import { runCaptureIfCommandExists } from './utils/proc/commands.mjs';
+import { readLastLines } from './utils/fs/tail.mjs';
 import { existsSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
 import { chmod, copyFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -28,7 +30,7 @@ export async function cleanupStaleDaemonState(homeDir) {
 
   const lsofHasPath = async (pid, pathNeedle) => {
     try {
-      const out = await runCapture('sh', ['-lc', `command -v lsof >/dev/null 2>&1 && lsof -nP -p ${pid} 2>/dev/null || true`]);
+      const out = await runCaptureIfCommandExists('lsof', ['-nP', '-p', String(pid)]);
       return out.includes(pathNeedle);
     } catch {
       return false;
@@ -173,16 +175,6 @@ function getLatestDaemonLogPath(homeDir) {
   }
 }
 
-function readLastLines(path, lines = 60) {
-  try {
-    const content = readFileSync(path, 'utf-8');
-    const parts = content.split('\n');
-    return parts.slice(Math.max(0, parts.length - lines)).join('\n');
-  } catch {
-    return null;
-  }
-}
-
 function excerptIndicatesMissingAuth(excerpt) {
   if (!excerpt) return false;
   return (
@@ -297,7 +289,7 @@ async function killDaemonFromLockFile({ cliHomeDir }) {
   // We do this by checking that `lsof -p <pid>` includes the lock path (or state file path).
   let ownsLock = false;
   try {
-    const out = await runCapture('sh', ['-lc', `command -v lsof >/dev/null 2>&1 && lsof -nP -p ${pid} 2>/dev/null || true`]);
+    const out = await runCaptureIfCommandExists('lsof', ['-nP', '-p', String(pid)]);
     ownsLock = out.includes(lockPath) || out.includes(join(cliHomeDir, 'daemon.state.json')) || out.includes(join(cliHomeDir, 'logs'));
   } catch {
     ownsLock = false;
@@ -463,7 +455,7 @@ export async function startLocalDaemonWithAuth({
     const logPath =
       getLatestDaemonLogPath(cliHomeDir) ||
       ((!isSandboxed() || sandboxAllowsGlobalSideEffects()) ? getLatestDaemonLogPath(join(homedir(), '.happy')) : null);
-    const excerpt = logPath ? readLastLines(logPath, 120) : null;
+    const excerpt = logPath ? await readLastLines(logPath, 120) : null;
     return { ok: false, exitCode, excerpt, logPath };
   };
 

package/scripts/dev.mjs

@@ -1,36 +1,27 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
-import { killProcessTree } from './utils/proc.mjs';
-import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths.mjs';
-import { killPortListeners } from './utils/ports.mjs';
-import { getServerComponentName, isHappyServerRunning } from './utils/server.mjs';
-import { requireDir } from './utils/pm.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, stopLocalDaemon } from './daemon.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { assertServerComponentDirMatches, assertServerPrismaProviderMatches } from './utils/validate.mjs';
-import { getExpoStatePaths, isStateProcessRunning } from './utils/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/localhost_host.mjs';
-import { openUrlInBrowser } from './utils/browser.mjs';
-import { waitForHttpOk } from './utils/server.mjs';
-
-function sanitizeDnsLabel(raw, { fallback = 'stack' } = {}) {
-  const s = String(raw ?? '')
-    .toLowerCase()
-    .replace(/[^a-z0-9-]+/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^-+/, '')
-    .replace(/-+$/, '');
-  return s || fallback;
-}
+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: