happy-stacks 0.2.0 → 0.3.0

package/scripts/stack.mjs

@@ -1,15 +1,16 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { spawn } from 'node:child_process';
 import { chmod, copyFile, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { existsSync } from 'node:fs';
-import { randomBytes } from 'node:crypto';
+// NOTE: random bytes usage centralized in scripts/utils/crypto/tokens.mjs
 import { homedir } from 'node:os';
+import { ensureDir, readTextIfExists, readTextOrEmpty } from './utils/fs/ops.mjs';
 
 import { parseArgs } from './utils/cli/args.mjs';
-import { killProcessTree, run, runCapture } from './utils/proc.mjs';
-import { getComponentDir, getComponentsDir, getHappyStacksHomeDir, getLegacyStorageRoot, getRootDir, getStacksStorageRoot, resolveStackEnvPath } from './utils/paths.mjs';
-import { isTcpPortFree, pickNextFreeTcpPort } from './utils/ports.mjs';
+import { killProcessTree, run, runCapture } from './utils/proc/proc.mjs';
+import { getComponentDir, getComponentsDir, getHappyStacksHomeDir, getLegacyStorageRoot, getRootDir, getStacksStorageRoot, resolveStackEnvPath } from './utils/paths/paths.mjs';
+import { isTcpPortFree, pickNextFreeTcpPort } from './utils/net/ports.mjs';
 import {
   createWorktree,
   createWorktreeFromBaseWorktree,
@@ -17,62 +18,49 @@ import {
   isComponentWorktreePath,
   resolveComponentSpecToDir,
   worktreeSpecFromDir,
-} from './utils/worktrees.mjs';
+} from './utils/git/worktrees.mjs';
 import { isTty, prompt, promptWorktreeSource, withRl } from './utils/cli/wizard.mjs';
-import { parseDotenv } from './utils/dotenv.mjs';
+import { parseEnvToObject } from './utils/env/dotenv.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { ensureEnvFilePruned, ensureEnvFileUpdated } from './utils/env_file.mjs';
-import { listAllStackNames } from './utils/stacks.mjs';
-import { stopStackWithEnv } from './utils/stack_stop.mjs';
-import { writeDevAuthKey } from './utils/dev_auth_key.mjs';
-import { startDevServer } from './utils/dev_server.mjs';
-import { startDevExpoWebUi } from './utils/dev_expo_web.mjs';
-import { requireDir } from './utils/pm.mjs';
-import { waitForHttpOk } from './utils/server.mjs';
-import { resolveLocalhostHost } from './utils/localhost_host.mjs';
-import { openUrlInBrowser } from './utils/browser.mjs';
-import { copyFileIfMissing, linkFileIfMissing, writeSecretFileIfMissing } from './utils/auth_files.mjs';
-import { getLegacyHappyBaseDir, isLegacyAuthSourceName } from './utils/auth_sources.mjs';
-import { resolveAuthSeedFromEnv } from './utils/stack_startup.mjs';
-import { getHomeEnvLocalPath } from './utils/config.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
-import { resolveHandyMasterSecretFromStack } from './utils/handy_master_secret.mjs';
+import { ensureEnvFilePruned, ensureEnvFileUpdated } from './utils/env/env_file.mjs';
+import { listAllStackNames, stackExistsSync } from './utils/stack/stacks.mjs';
+import { stopStackWithEnv } from './utils/stack/stop.mjs';
+import { writeDevAuthKey } from './utils/auth/dev_key.mjs';
+import { startDevServer } from './utils/dev/server.mjs';
+import { startDevExpoWebUi } from './utils/dev/expo_web.mjs';
+import { requireDir } from './utils/proc/pm.mjs';
+import { waitForHttpOk } from './utils/server/server.mjs';
+import { resolveLocalhostHost } from './utils/paths/localhost_host.mjs';
+import { openUrlInBrowser } from './utils/ui/browser.mjs';
+import { copyFileIfMissing, linkFileIfMissing, writeSecretFileIfMissing } from './utils/auth/files.mjs';
+import { getLegacyHappyBaseDir, isLegacyAuthSourceName } from './utils/auth/sources.mjs';
+import { resolveAuthSeedFromEnv } from './utils/stack/startup.mjs';
+import { getHomeEnvLocalPath } from './utils/env/config.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
+import { resolveHandyMasterSecretFromStack } from './utils/auth/handy_master_secret.mjs';
+import { readPinnedServerPortFromEnvFile } from './utils/server/port.mjs';
+import { getEnvValue, getEnvValueAny } from './utils/env/values.mjs';
+import { sanitizeDnsLabel } from './utils/net/dns.mjs';
+import { coercePort, listPortsFromEnvObject, STACK_RESERVED_PORT_KEYS } from './utils/server/port.mjs';
 import {
   deleteStackRuntimeStateFile,
   getStackRuntimeStatePath,
   isPidAlive,
   recordStackRuntimeStart,
   readStackRuntimeStateFile,
-} from './utils/stack_runtime_state.mjs';
-import { killPid } from './utils/expo.mjs';
-import { killPidOwnedByStack } from './utils/ownership.mjs';
-
-function getEnvValue(obj, key) {
-  const v = (obj?.[key] ?? '').toString().trim();
-  return v || '';
-}
-
-function getEnvValueAny(obj, keys) {
-  for (const k of keys) {
-    const v = getEnvValue(obj, k);
-    if (v) return v;
-  }
-  return '';
-}
+} from './utils/stack/runtime_state.mjs';
+import { killPid } from './utils/expo/expo.mjs';
+import { getCliHomeDirFromEnvOrDefault, getServerLightDataDirFromEnvOrDefault } from './utils/stack/dirs.mjs';
+import { randomToken } from './utils/crypto/tokens.mjs';
+import { killPidOwnedByStack } from './utils/proc/ownership.mjs';
+import { sanitizeSlugPart } from './utils/git/refs.mjs';
+import { isCursorInstalled, openWorkspaceInEditor, writeStackCodeWorkspace } from './utils/stack/editor_workspace.mjs';
 
 function stackNameFromArg(positionals, idx) {
   const name = positionals[idx]?.trim() ? positionals[idx].trim() : '';
   return name;
 }
 
-function getStackDir(stackName) {
-  return resolveStackEnvPath(stackName).baseDir;
-}
-
-function getStackEnvPath(stackName) {
-  return resolveStackEnvPath(stackName).envPath;
-}
-
 function getDefaultPortStart() {
   const raw = process.env.HAPPY_STACKS_STACK_PORT_START?.trim()
     ? process.env.HAPPY_STACKS_STACK_PORT_START.trim()
@@ -97,34 +85,14 @@ async function pickNextFreePort(startPort, { reservedPorts = new Set() } = {}) {
 }
 
 async function readPortFromEnvFile(envPath) {
-  const raw = await readExistingEnv(envPath);
-  if (!raw.trim()) return null;
-  const parsed = parseEnvToObject(raw);
-  const portRaw = (parsed.HAPPY_STACKS_SERVER_PORT ?? parsed.HAPPY_LOCAL_SERVER_PORT ?? '').toString().trim();
-  const n = portRaw ? Number(portRaw) : NaN;
-  return Number.isFinite(n) && n > 0 ? n : null;
+  return await readPinnedServerPortFromEnvFile(envPath);
 }
 
 async function readPortsFromEnvFile(envPath) {
   const raw = await readExistingEnv(envPath);
   if (!raw.trim()) return [];
   const parsed = parseEnvToObject(raw);
-  const keys = [
-    'HAPPY_STACKS_SERVER_PORT',
-    'HAPPY_LOCAL_SERVER_PORT',
-    'HAPPY_STACKS_HAPPY_SERVER_BACKEND_PORT',
-    'HAPPY_STACKS_PG_PORT',
-    'HAPPY_STACKS_REDIS_PORT',
-    'HAPPY_STACKS_MINIO_PORT',
-    'HAPPY_STACKS_MINIO_CONSOLE_PORT',
-  ];
-  const ports = [];
-  for (const k of keys) {
-    const rawV = (parsed[k] ?? '').toString().trim();
-    const n = rawV ? Number(rawV) : NaN;
-    if (Number.isFinite(n) && n > 0) ports.push(n);
-  }
-  return ports;
+  return listPortsFromEnvObject(parsed, STACK_RESERVED_PORT_KEYS);
 }
 
 async function collectReservedStackPorts({ excludeStackName = null } = {}) {
@@ -159,54 +127,7 @@ async function collectReservedStackPorts({ excludeStackName = null } = {}) {
   return reserved;
 }
 
-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;
-}
-
-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;
-  }
-}
-
-// auth file copy/link helpers live in scripts/utils/auth_files.mjs
-
-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');
-}
+// auth file copy/link helpers live in scripts/utils/auth/files.mjs
 
 async function copyAuthFromStackIntoNewStack({
   fromStackName,
@@ -255,8 +176,8 @@ async function copyAuthFromStackIntoNewStack({
         'If you really want this, set: HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1'
     );
   }
-  const sourceBaseDir = legacy ? getLegacyHappyBaseDir() : getStackDir(fromStackName);
-  const sourceEnvRaw = legacy ? '' : await readExistingEnv(getStackEnvPath(fromStackName));
+  const sourceBaseDir = legacy ? getLegacyHappyBaseDir() : resolveStackEnvPath(fromStackName).baseDir;
+  const sourceEnvRaw = legacy ? '' : await readExistingEnv(resolveStackEnvPath(fromStackName).envPath);
   const sourceEnv = parseEnvToObject(sourceEnvRaw);
   const sourceCli = legacy ? join(sourceBaseDir, 'cli') : getCliHomeDirFromEnvOrDefault({ stackBaseDir: sourceBaseDir, env: sourceEnv });
   const targetCli = stackEnv.HAPPY_STACKS_CLI_HOME_DIR;
@@ -302,25 +223,7 @@ function stringifyEnv(env) {
   return lines.join('\n') + '\n';
 }
 
-async function readExistingEnv(path) {
-  try {
-    const raw = await readFile(path, 'utf-8');
-    return raw;
-  } catch {
-    return '';
-  }
-}
-
-function parseEnvToObject(raw) {
-  const parsed = parseDotenv(raw);
-  return Object.fromEntries(parsed.entries());
-}
-
-function stackExistsSync(stackName) {
-  if (stackName === 'main') return true;
-  const envPath = getStackEnvPath(stackName);
-  return existsSync(envPath);
-}
+const readExistingEnv = readTextOrEmpty;
 
 function resolveDefaultComponentDirs({ rootDir }) {
   const componentNames = ['happy', 'happy-cli', 'happy-server-light', 'happy-server'];
@@ -335,9 +238,9 @@ function resolveDefaultComponentDirs({ rootDir }) {
 }
 
 async function writeStackEnv({ stackName, env }) {
-  const stackDir = getStackDir(stackName);
+  const stackDir = resolveStackEnvPath(stackName).baseDir;
   await ensureDir(stackDir);
-  const envPath = getStackEnvPath(stackName);
+  const envPath = resolveStackEnvPath(stackName).envPath;
   const next = stringifyEnv(env);
   const existing = await readExistingEnv(envPath);
   if (existing !== next) {
@@ -347,7 +250,7 @@ async function writeStackEnv({ stackName, env }) {
 }
 
 async function withStackEnv({ stackName, fn, extraEnv = {} }) {
-  const envPath = getStackEnvPath(stackName);
+  const envPath = resolveStackEnvPath(stackName).envPath;
   if (!stackExistsSync(stackName)) {
     throw new Error(
       `[stack] stack "${stackName}" does not exist yet.\n` +
@@ -604,7 +507,7 @@ async function cmdNew({ rootDir, argv, emit = true }) {
     throw new Error(`[stack] invalid server component: ${serverComponent}`);
   }
 
-  const baseDir = getStackDir(stackName);
+  const baseDir = resolveStackEnvPath(stackName).baseDir;
   const uiBuildDir = join(baseDir, 'ui');
   const cliHomeDir = join(baseDir, 'cli');
 
@@ -804,7 +707,7 @@ async function cmdEdit({ rootDir, argv }) {
     throw new Error('[stack] usage: happys stack edit <name> [--interactive]');
   }
 
-  const envPath = getStackEnvPath(stackName);
+  const envPath = resolveStackEnvPath(stackName).envPath;
   const raw = await readExistingEnv(envPath);
   const existingEnv = parseEnvToObject(raw);
 
@@ -829,7 +732,7 @@ async function cmdEdit({ rootDir, argv }) {
   const config = await withRl((rl) => interactiveEdit({ rootDir, rl, stackName, existingEnv, defaults }));
 
   // Build next env, starting from existing env but enforcing stack-scoped invariants.
-  const baseDir = getStackDir(stackName);
+  const baseDir = resolveStackEnvPath(stackName).baseDir;
   const uiBuildDir = join(baseDir, 'ui');
   const cliHomeDir = join(baseDir, 'cli');
 
@@ -1894,7 +1797,7 @@ async function cmdCreateDevAuthSeed({ rootDir, argv }) {
         const internalServerUrl = `http://127.0.0.1:${serverPort}`;
         const publicServerUrl = `http://localhost:${serverPort}`;
 
-        const autostart = { stackName: name, baseDir: getStackDir(name) };
+        const autostart = { stackName: name, baseDir: resolveStackEnvPath(name).baseDir };
         const children = [];
 
         await withStackEnv({
@@ -1962,7 +1865,7 @@ async function cmdCreateDevAuthSeed({ rootDir, argv }) {
               }
 
               console.log('');
-              const uiHost = `happy-${sanitizeDnsLabel(name)}.localhost`;
+              const uiHost = resolveLocalhostHost({ stackMode: true, stackName: name });
               const uiPort = uiRes?.port;
               const uiRoot = Number.isFinite(uiPort) && uiPort > 0 ? `http://${uiHost}:${uiPort}` : null;
               const uiRootLocalhost = Number.isFinite(uiPort) && uiPort > 0 ? `http://localhost:${uiPort}` : null;
@@ -2092,7 +1995,7 @@ function parseServerComponentFromEnv(env) {
 }
 
 async function readStackEnvObject(stackName) {
-  const envPath = getStackEnvPath(stackName);
+  const envPath = resolveStackEnvPath(stackName).envPath;
   const raw = await readExistingEnv(envPath);
   const env = raw ? parseEnvToObject(raw) : {};
   return { envPath, env };
@@ -2107,16 +2010,6 @@ function envKeyForComponentDir({ serverComponent, component }) {
   return `HAPPY_STACKS_COMPONENT_DIR_${component.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`;
 }
 
-function sanitizeSlugPart(s) {
-  return String(s ?? '')
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9._/-]+/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^-+/, '')
-    .replace(/-+$/, '');
-}
-
 async function cmdDuplicate({ rootDir, argv }) {
   const { flags, kv } = parseArgs(argv);
   const json = wantsJson(argv, { flags });
@@ -2190,7 +2083,7 @@ async function cmdDuplicate({ rootDir, argv }) {
   }
 
   // Apply component dir overrides to the destination stack env file.
-  const toEnvPath = getStackEnvPath(toStack);
+  const toEnvPath = resolveStackEnvPath(toStack).envPath;
   if (updates.length) {
     await ensureEnvFileUpdated({ envPath: toEnvPath, updates });
   }
@@ -2577,8 +2470,8 @@ async function cmdPrStack({ rootDir, argv }) {
 
 async function cmdInfoInternal({ rootDir, stackName }) {
   // Minimal extraction from cmdInfo to avoid re-parsing argv/printing. Used by cmdPrStack.
-  const baseDir = getStackDir(stackName);
-  const envPath = getStackEnvPath(stackName);
+  const baseDir = resolveStackEnvPath(stackName).baseDir;
+  const envPath = resolveStackEnvPath(stackName).envPath;
   const envRaw = await readExistingEnv(envPath);
   const stackEnv = envRaw ? parseEnvToObject(envRaw) : {};
   const runtimeStatePath = getStackRuntimeStatePath(stackName);
@@ -2587,6 +2480,9 @@ async function cmdInfoInternal({ rootDir, stackName }) {
   const serverComponent =
     getEnvValueAny(stackEnv, ['HAPPY_STACKS_SERVER_COMPONENT', 'HAPPY_LOCAL_SERVER_COMPONENT']) || 'happy-server-light';
 
+  const stackRemote =
+    getEnvValueAny(stackEnv, ['HAPPY_STACKS_STACK_REMOTE', 'HAPPY_LOCAL_STACK_REMOTE']) || 'upstream';
+
   const pinnedServerPortRaw = getEnvValueAny(stackEnv, ['HAPPY_STACKS_SERVER_PORT', 'HAPPY_LOCAL_SERVER_PORT']);
   const pinnedServerPort = pinnedServerPortRaw ? Number(pinnedServerPortRaw) : null;
 
@@ -2632,6 +2528,7 @@ async function cmdInfoInternal({ rootDir, stackName }) {
     envPath,
     runtimeStatePath,
     serverComponent,
+    stackRemote,
     pinned: {
       serverPort: Number.isFinite(pinnedServerPort) && pinnedServerPort > 0 ? pinnedServerPort : null,
     },
@@ -2659,6 +2556,31 @@ async function cmdInfoInternal({ rootDir, stackName }) {
   };
 }
 
+async function cmdStackCodeOrCursor({ rootDir, stackName, json, editor, includeStackDir, includeAllComponents, includeCliHome }) {
+  const ws = await writeStackCodeWorkspace({ rootDir, stackName, includeStackDir, includeAllComponents, includeCliHome });
+
+  if (json) {
+    printResult({
+      json,
+      data: {
+        ok: true,
+        stackName,
+        editor,
+        ...ws,
+      },
+    });
+    return;
+  }
+
+  await openWorkspaceInEditor({ rootDir, editor, workspacePath: ws.workspacePath });
+  console.log(`[stack] opened ${editor === 'code' ? 'VS Code' : 'Cursor'} workspace for "${stackName}": ${ws.workspacePath}`);
+}
+
+async function cmdStackOpen({ rootDir, stackName, json, includeStackDir, includeAllComponents, includeCliHome }) {
+  const editor = (await isCursorInstalled({ cwd: rootDir, env: process.env })) ? 'cursor' : 'code';
+  await cmdStackCodeOrCursor({ rootDir, stackName, json, editor, includeStackDir, includeAllComponents, includeCliHome });
+}
+
 async function main() {
   const rootDir = getRootDir(import.meta.url);
   // pnpm (legacy) passes an extra leading `--` when forwarding args into scripts. Normalize it away so
@@ -2702,6 +2624,9 @@ async function main() {
           'mobile',
           'resume',
           'stop',
+          'code',
+          'cursor',
+          'open',
           'srv',
           'wt',
           'tailscale:*',
@@ -2730,6 +2655,9 @@ async function main() {
         '  happys stack mobile <name> [-- ...]',
         '  happys stack resume <name> <sessionId...> [--json]',
         '  happys stack stop <name> [--aggressive] [--sweep-owned] [--no-docker] [--json]',
+        '  happys stack code <name> [--no-stack-dir] [--include-all-components] [--include-cli-home] [--json]',
+        '  happys stack cursor <name> [--no-stack-dir] [--include-all-components] [--include-cli-home] [--json]',
+        '  happys stack open <name> [--no-stack-dir] [--include-all-components] [--include-cli-home] [--json]   # prefer Cursor, else VS Code',
         '  happys stack srv <name> -- status|use ...',
         '  happys stack wt <name> -- <wt args...>',
         '  happys stack tailscale:status|enable|disable|url <name> [-- ...]',
@@ -2928,7 +2856,7 @@ async function main() {
     const noDocker = stopFlags.has('--no-docker');
     const aggressive = stopFlags.has('--aggressive');
     const sweepOwned = stopFlags.has('--sweep-owned');
-    const baseDir = getStackDir(stackName);
+    const baseDir = resolveStackEnvPath(stackName).baseDir;
     const out = await withStackEnv({
       stackName,
       fn: async ({ env }) => {
@@ -2939,6 +2867,28 @@ async function main() {
     return;
   }
 
+  if (cmd === 'code') {
+    const includeStackDir = !flags.has('--no-stack-dir');
+    const includeAllComponents = flags.has('--include-all-components');
+    const includeCliHome = flags.has('--include-cli-home');
+    await cmdStackCodeOrCursor({ rootDir, stackName, json, editor: 'code', includeStackDir, includeAllComponents, includeCliHome });
+    return;
+  }
+  if (cmd === 'cursor') {
+    const includeStackDir = !flags.has('--no-stack-dir');
+    const includeAllComponents = flags.has('--include-all-components');
+    const includeCliHome = flags.has('--include-cli-home');
+    await cmdStackCodeOrCursor({ rootDir, stackName, json, editor: 'cursor', includeStackDir, includeAllComponents, includeCliHome });
+    return;
+  }
+  if (cmd === 'open') {
+    const includeStackDir = !flags.has('--no-stack-dir');
+    const includeAllComponents = flags.has('--include-all-components');
+    const includeCliHome = flags.has('--include-cli-home');
+    await cmdStackOpen({ rootDir, stackName, json, includeStackDir, includeAllComponents, includeCliHome });
+    return;
+  }
+
   if (cmd === 'srv') {
     await cmdSrv({ rootDir, stackName, args: passthrough });
     return;

package/scripts/stop.mjs

@@ -1,11 +1,11 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { run, runCapture } from './utils/proc.mjs';
-import { getRootDir, resolveStackEnvPath } from './utils/paths.mjs';
+import { run, runCapture } from './utils/proc/proc.mjs';
+import { getRootDir, resolveStackEnvPath } from './utils/paths/paths.mjs';
 
 function usage() {
   return [

package/scripts/tailscale.mjs

@@ -1,8 +1,10 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
-import { run, runCapture } from './utils/proc.mjs';
+import { run, runCapture } from './utils/proc/proc.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
+import { getInternalServerUrl } from './utils/server/urls.mjs';
+import { resolveCommandPath } from './utils/proc/commands.mjs';
 import { constants } from 'node:fs';
 import { access } from 'node:fs/promises';
 
@@ -21,11 +23,6 @@ import { access } from 'node:fs/promises';
  * - url (print the first https:// URL from status output)
  */
 
-function getInternalServerUrl() {
-  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 getServeConfig(internalServerUrl) {
   const upstream = process.env.HAPPY_LOCAL_TAILSCALE_UPSTREAM?.trim()
     ? process.env.HAPPY_LOCAL_TAILSCALE_UPSTREAM.trim()
@@ -134,7 +131,7 @@ async function resolveTailscaleCmd() {
 
   // Try PATH first (without executing `tailscale`, which can hang in some environments).
   try {
-    const found = (await runCapture('sh', ['-lc', 'command -v tailscale 2>/dev/null || true'], { env: tailscaleEnv(), timeoutMs: tailscaleProbeTimeoutMs() })).trim();
+    const found = await resolveCommandPath('tailscale', { env: tailscaleEnv(), timeoutMs: tailscaleProbeTimeoutMs() });
     if (found) {
       return found;
     }
@@ -342,7 +339,7 @@ async function main() {
     return;
   }
 
-  const internalServerUrl = getInternalServerUrl();
+  const internalServerUrl = getInternalServerUrl({ env: process.env, defaultPort: 3005 }).internalServerUrl;
   if (flags.has('--upstream') || kv.get('--upstream')) {
     process.env.HAPPY_LOCAL_TAILSCALE_UPSTREAM = kv.get('--upstream') ?? internalServerUrl;
   }

package/scripts/test.mjs

@@ -1,36 +1,15 @@
-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, getRootDir } from './utils/paths.mjs';
-import { ensureDepsInstalled, requirePnpm } from './utils/pm.mjs';
-import { pathExists } from './utils/fs.mjs';
-import { run } from './utils/proc.mjs';
-import { join } from 'node:path';
-import { readFile } from 'node:fs/promises';
+import { getComponentDir, getRootDir } from './utils/paths/paths.mjs';
+import { ensureDepsInstalled } from './utils/proc/pm.mjs';
+import { pathExists } from './utils/fs/fs.mjs';
+import { run } from './utils/proc/proc.mjs';
+import { detectPackageManagerCmd, pickFirstScript, readPackageJsonScripts } from './utils/proc/package_scripts.mjs';
 
 const DEFAULT_COMPONENTS = ['happy', 'happy-cli', 'happy-server-light', 'happy-server'];
 
-async function detectPackageManagerCmd(dir) {
-  if (await pathExists(join(dir, 'yarn.lock'))) {
-    return { name: 'yarn', cmd: 'yarn', argsForScript: (script) => ['-s', script] };
-  }
-  await requirePnpm();
-  return { name: 'pnpm', cmd: 'pnpm', argsForScript: (script) => ['--silent', script] };
-}
-
-async function readScripts(dir) {
-  try {
-    const raw = await readFile(join(dir, 'package.json'), 'utf-8');
-    const pkg = JSON.parse(raw);
-    const scripts = pkg?.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
-    return scripts;
-  } catch {
-    return null;
-  }
-}
-
 function pickTestScript(scripts) {
-  if (!scripts) return null;
   const candidates = [
     'test',
     'tst',
@@ -38,7 +17,7 @@ function pickTestScript(scripts) {
     'test:unit',
     'check:test',
   ];
-  return candidates.find((k) => typeof scripts[k] === 'string' && scripts[k].trim()) ?? null;
+  return pickFirstScript(scripts, candidates);
 }
 
 async function main() {
@@ -85,7 +64,7 @@ async function main() {
       continue;
     }
 
-    const scripts = await readScripts(dir);
+    const scripts = await readPackageJsonScripts(dir);
     if (!scripts) {
       results.push({ component, ok: true, skipped: true, dir, reason: 'no package.json' });
       continue;

package/scripts/tui.mjs

@@ -1,29 +1,13 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
 import { join, resolve, sep } from 'node:path';
 
-import { parseDotenv } from './utils/dotenv.mjs';
 import { printResult } from './utils/cli/cli.mjs';
-import { getRootDir, resolveStackEnvPath } from './utils/paths.mjs';
-import { getStackRuntimeStatePath, readStackRuntimeStateFile } from './utils/stack_runtime_state.mjs';
-
-function stripAnsi(s) {
-  // eslint-disable-next-line no-control-regex
-  return String(s ?? '').replace(/\x1b\[[0-9;]*[A-Za-z]/g, '');
-}
-
-function padRight(s, n) {
-  const str = String(s ?? '');
-  if (str.length >= n) return str.slice(0, n);
-  return str + ' '.repeat(n - str.length);
-}
-
-function parsePrefixedLabel(line) {
-  const m = String(line ?? '').match(/^\[([^\]]+)\]\s*/);
-  return m ? m[1] : null;
-}
+import { readEnvObjectFromFile } from './utils/env/read.mjs';
+import { getRootDir, resolveStackEnvPath } from './utils/paths/paths.mjs';
+import { getStackRuntimeStatePath, readStackRuntimeStateFile } from './utils/stack/runtime_state.mjs';
+import { getEnvValueAny } from './utils/env/values.mjs';
+import { padRight, parsePrefixedLabel, stripAnsi } from './utils/ui/text.mjs';
 
 function nowTs() {
   const d = new Date();
@@ -107,15 +91,7 @@ function inferStackNameFromForwardedArgs(args) {
   return (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').trim() || 'main';
 }
 
-async function readEnvObject(path) {
-  try {
-    if (!path || !existsSync(path)) return {};
-    const raw = await readFile(path, 'utf-8');
-    return Object.fromEntries(parseDotenv(raw).entries());
-  } catch {
-    return {};
-  }
-}
+const readEnvObject = readEnvObjectFromFile;
 
 function formatComponentRef({ rootDir, component, dir }) {
   const raw = String(dir ?? '').trim();
@@ -132,12 +108,6 @@ function formatComponentRef({ rootDir, component, dir }) {
   return abs;
 }
 
-function getEnvVal(env, k1, k2) {
-  const a = String(env?.[k1] ?? '').trim();
-  if (a) return a;
-  return String(env?.[k2] ?? '').trim();
-}
-
 async function buildStackSummaryLines({ rootDir, stackName }) {
   const { envPath, baseDir } = resolveStackEnvPath(stackName);
   const env = await readEnvObject(envPath);
@@ -145,7 +115,7 @@ async function buildStackSummaryLines({ rootDir, stackName }) {
   const runtime = await readStackRuntimeStateFile(runtimePath);
 
   const serverComponent =
-    getEnvVal(env, 'HAPPY_STACKS_SERVER_COMPONENT', 'HAPPY_LOCAL_SERVER_COMPONENT') || 'happy-server-light';
+    getEnvValueAny(env, ['HAPPY_STACKS_SERVER_COMPONENT', 'HAPPY_LOCAL_SERVER_COMPONENT']) || 'happy-server-light';
 
   const ports = runtime?.ports && typeof runtime.ports === 'object' ? runtime.ports : {};
   const expoWebPort = runtime?.expo && typeof runtime.expo === 'object' ? runtime.expo.webPort : null;