happy-stacks 0.2.0 → 0.3.0

package/scripts/doctor.mjs

@@ -1,21 +1,24 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/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 { 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 } 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/cli.mjs';
-import { getRuntimeDir } from './utils/runtime.mjs';
-import { assertServerComponentDirMatches } from './utils/validate.mjs';
-import { resolveServerPortFromEnv, resolveServerUrls } from './utils/server_urls.mjs';
-import { resolveStackContext } from './utils/stack_context.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.
@@ -43,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;
   }
@@ -54,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;
@@ -114,8 +98,8 @@ 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 autostart = getDefaultAutostartPaths();
   const stackCtx = resolveStackContext({ env: process.env, autostart });
@@ -302,7 +286,7 @@ 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}`);
@@ -314,7 +298,7 @@ async function main() {
 
   // 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}`);

package/scripts/edison.mjs

@@ -1,14 +1,17 @@
-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 { resolveStackEnvPath, getComponentDir, getRootDir } from './utils/paths.mjs';
-import { parseDotenv } from './utils/dotenv.mjs';
-import { pathExists } from './utils/fs.mjs';
-import { run, runCapture } from './utils/proc.mjs';
-import { resolveLocalhostHost } from './utils/localhost_host.mjs';
+import { resolveStackEnvPath, getComponentDir, getRootDir } from './utils/paths/paths.mjs';
+import { parseEnvToObject } from './utils/env/dotenv.mjs';
+import { pathExists } from './utils/fs/fs.mjs';
+import { readTextOrEmpty } from './utils/fs/ops.mjs';
+import { readJsonIfExists } from './utils/fs/json.mjs';
+import { isPidAlive } from './utils/proc/pids.mjs';
+import { run, runCapture } from './utils/proc/proc.mjs';
+import { resolveLocalhostHost } from './utils/paths/localhost_host.mjs';
+import { sanitizeStackName } from './utils/stack/names.mjs';
 import { join } from 'node:path';
 import { spawn } from 'node:child_process';
-import { readFile } from 'node:fs/promises';
 import { mkdir, lstat, rename, symlink, writeFile, readdir, chmod } from 'node:fs/promises';
 import os from 'node:os';
 
@@ -26,25 +29,7 @@ function cleanHappyStacksEnv(baseEnv) {
   return cleaned;
 }
 
-async function readExistingEnv(path) {
-  try {
-    const raw = await readFile(path, 'utf-8');
-    return raw;
-  } catch {
-    return '';
-  }
-}
-
-async function readJsonIfExists(path) {
-  try {
-    if (!path || !(await pathExists(path))) return null;
-    const raw = await readFile(path, 'utf-8');
-    const parsed = JSON.parse(raw);
-    return parsed && typeof parsed === 'object' ? parsed : null;
-  } catch {
-    return null;
-  }
-}
+const readExistingEnv = readTextOrEmpty;
 
 function inferServerPortFromRuntimeState(runtimeState) {
   try {
@@ -56,17 +41,6 @@ function inferServerPortFromRuntimeState(runtimeState) {
   }
 }
 
-function isPidAlive(pid) {
-  const n = Number(pid);
-  if (!Number.isFinite(n) || n <= 1) return false;
-  try {
-    process.kill(n, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 function isRuntimeStateAlive(runtimeState) {
   try {
     const ownerPid = runtimeState?.ownerPid;
@@ -376,11 +350,6 @@ async function inferTaskIdFromArgs({ rootDir, edisonArgs }) {
   return '';
 }
 
-function parseEnvToObject(raw) {
-  const parsed = parseDotenv(raw);
-  return Object.fromEntries(parsed.entries());
-}
-
 function resolveComponentDirsFromStackEnv({ rootDir, stackEnv }) {
   const out = [];
 
@@ -452,17 +421,6 @@ function resolveComponentsFromFrontmatter(fm) {
   return [];
 }
 
-function sanitizeStackName(raw) {
-  return String(raw ?? '')
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9-]+/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^-+/, '')
-    .replace(/-+$/, '')
-    .slice(0, 64);
-}
-
 function yamlQuote(v) {
   const s = String(v ?? '');
   return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
@@ -608,12 +566,13 @@ async function cmdTaskScaffold({ rootDir, argv, json }) {
   const taskId = positionals[1]?.trim?.() ? positionals[1].trim() : '';
   if (!taskId) {
     throw new Error(
-      '[edison] usage: happys edison task:scaffold <task-id> [--mode=upstream|fork|both] [--tracks=upstream,fork] [--yes] [--json]'
+      '[edison] usage: happys edison task:scaffold <task-id> [--mode=upstream|fork|both] [--tracks=upstream,fork] [--yes] [--reuse-only] [--json]'
     );
   }
 
   const mode = (kv.get('--mode') ?? '').trim().toLowerCase() || 'upstream';
   const yes = flags.has('--yes');
+  const reuseOnly = flags.has('--reuse-only') || (kv.get('--reuse-only') ?? '').trim() === '1';
 
   const taskPath = join(rootDir, '.project', 'tasks');
   const taskGlobRoots = ['todo', 'wip', 'done', 'validated', 'blocked'];
@@ -722,12 +681,32 @@ async function cmdTaskScaffold({ rootDir, argv, json }) {
       createdTasks.push({ id: trackTaskId, kind: 'track', stack, path: trackRes.path, created: trackRes.created });
 
       const stackExists = Array.isArray(stacks) && stacks.some((s) => String(s?.name ?? '') === stack);
+      const expectedStackRemote = track === 'fork' || track === 'integration' ? 'origin' : 'upstream';
       if (!stackExists) {
-        await run('node', ['./bin/happys.mjs', 'stack', 'new', stack, '--json'], { cwd: rootDir });
+        await run('node', ['./bin/happys.mjs', 'stack', 'new', stack, `--remote=${expectedStackRemote}`, '--json'], { cwd: rootDir });
         createdStacks.push({ stack });
         stacks.push({ name: stack });
       }
 
+      // If the stack already exists, reuse pinned worktrees when possible.
+      let stackInfo = null;
+      if (stackExists) {
+        const raw = await runCapture('node', ['./bin/happys.mjs', 'stack', 'info', stack, '--json'], { cwd: rootDir });
+        stackInfo = JSON.parse(raw);
+        const actualRemote = String(stackInfo?.stackRemote ?? '').trim() || 'upstream';
+        if (actualRemote !== expectedStackRemote) {
+          throw new Error(
+            `[edison] stack remote mismatch for track "${track}".\n` +
+              `- stack: ${stack}\n` +
+              `- expected: ${expectedStackRemote}\n` +
+              `- actual: ${actualRemote}\n\n` +
+              `Fix:\n` +
+              `- run: happys stack edit ${stack} --interactive\n` +
+              `- set: Git remote for creating new worktrees = ${expectedStackRemote}\n`
+          );
+        }
+      }
+
       const qaRes = await ensureQaFile({
         rootDir,
         taskId: trackTaskId,
@@ -750,7 +729,11 @@ async function cmdTaskScaffold({ rootDir, argv, json }) {
         const compTaskId = existingComp?.id || nextChildId(trackTaskId, existingIds);
         existingIds.add(compTaskId);
         const compTitle = `Component: ${c} (${track})`;
-        const baseWorktree = String(existingComp?.fm?.base_worktree ?? '').trim() || `edison/${compTaskId}`;
+        const pinnedSpec =
+          stackInfo && Array.isArray(stackInfo.components)
+            ? String(stackInfo.components.find((x) => x?.component === c)?.worktreeSpec ?? '').trim()
+            : '';
+        const baseWorktree = String(existingComp?.fm?.base_worktree ?? '').trim() || pinnedSpec || `edison/${compTaskId}`;
         const compFm = {
           id: compTaskId,
           title: compTitle,
@@ -785,16 +768,32 @@ async function cmdTaskScaffold({ rootDir, argv, json }) {
         });
         createdQas.push({ id: `${compTaskId}-qa`, path: qa2.path, created: qa2.created });
 
-        const from = track === 'fork' ? 'origin' : 'upstream';
-        const stdout = await runCapture(
-          'node',
-          ['./bin/happys.mjs', 'wt', 'new', c, baseWorktree, `--from=${from}`, '--json'],
-          { cwd: rootDir }
-        );
-        const res = JSON.parse(stdout);
-        createdWorktrees.push({ component: c, variant: from, taskId: compTaskId, path: res.path, branch: res.branch });
-        await run('node', ['./bin/happys.mjs', 'stack', 'wt', stack, '--', 'use', c, res.path, '--json'], { cwd: rootDir });
-        pinned.push({ stack, component: c, taskId: compTaskId, path: res.path });
+        if (pinnedSpec) {
+          // Stack already pins an existing worktree; reuse it rather than creating a new one.
+          const pinnedDir = String(stackInfo.components.find((x) => x?.component === c)?.dir ?? '').trim();
+          createdWorktrees.push({ component: c, variant: 'reuse', taskId: compTaskId, path: pinnedDir, branch: null, worktreeSpec: pinnedSpec });
+          pinned.push({ stack, component: c, taskId: compTaskId, path: pinnedDir });
+        } else if (reuseOnly && stackExists) {
+          throw new Error(
+            `[edison] --reuse-only: stack "${stack}" is not pinned to a worktree for component "${c}".\n` +
+              `Fix:\n` +
+              `- pin an existing worktree to the stack:\n` +
+              `  happys stack wt ${stack} -- use ${c} <owner/branch|/abs/path>\n` +
+              `- then re-run:\n` +
+              `  happys edison task:scaffold ${taskId} --yes --reuse-only\n`
+          );
+        } else {
+          const from = track === 'fork' ? 'origin' : 'upstream';
+          const stdout = await runCapture(
+            'node',
+            ['./bin/happys.mjs', 'wt', 'new', c, baseWorktree, `--from=${from}`, '--json'],
+            { cwd: rootDir }
+          );
+          const res = JSON.parse(stdout);
+          createdWorktrees.push({ component: c, variant: from, taskId: compTaskId, path: res.path, branch: res.branch });
+          await run('node', ['./bin/happys.mjs', 'stack', 'wt', stack, '--', 'use', c, res.path, '--json'], { cwd: rootDir });
+          pinned.push({ stack, component: c, taskId: compTaskId, path: res.path });
+        }
       }
     }
   } else {
@@ -817,22 +816,48 @@ async function cmdTaskScaffold({ rootDir, argv, json }) {
             `  happys edison task:scaffold ${taskId} --yes\n`
         );
       }
-      await run('node', ['./bin/happys.mjs', 'stack', 'new', stack, '--json'], { cwd: rootDir });
+      const stackRemote = mode === 'fork' ? 'origin' : 'upstream';
+      await run('node', ['./bin/happys.mjs', 'stack', 'new', stack, `--remote=${stackRemote}`, '--json'], { cwd: rootDir });
       createdStacks.push({ stack });
     }
 
+    let stackInfo = null;
+    if (stackExists) {
+      const raw = await runCapture('node', ['./bin/happys.mjs', 'stack', 'info', stack, '--json'], { cwd: rootDir });
+      stackInfo = JSON.parse(raw);
+    }
+
     for (const c of components) {
-      const baseWorktree = `edison/${taskId}`;
+      const pinnedSpec =
+        stackInfo && Array.isArray(stackInfo.components)
+          ? String(stackInfo.components.find((x) => x?.component === c)?.worktreeSpec ?? '').trim()
+          : '';
+      const baseWorktree = pinnedSpec || `edison/${taskId}`;
       const from = mode === 'fork' ? 'origin' : 'upstream';
-      const stdout = await runCapture(
-        'node',
-        ['./bin/happys.mjs', 'wt', 'new', c, baseWorktree, `--from=${from}`, '--json'],
-        { cwd: rootDir }
-      );
-      const res = JSON.parse(stdout);
-      createdWorktrees.push({ component: c, variant: from, taskId, path: res.path, branch: res.branch });
-      await run('node', ['./bin/happys.mjs', 'stack', 'wt', stack, '--', 'use', c, res.path, '--json'], { cwd: rootDir });
-      pinned.push({ stack, component: c, taskId, path: res.path });
+      if (pinnedSpec) {
+        const pinnedDir = String(stackInfo.components.find((x) => x?.component === c)?.dir ?? '').trim();
+        createdWorktrees.push({ component: c, variant: 'reuse', taskId, path: pinnedDir, branch: null, worktreeSpec: pinnedSpec });
+        pinned.push({ stack, component: c, taskId, path: pinnedDir });
+      } else if (reuseOnly && stackExists) {
+        throw new Error(
+          `[edison] --reuse-only: stack "${stack}" is not pinned to a worktree for component "${c}".\n` +
+            `Fix:\n` +
+            `- pin an existing worktree to the stack:\n` +
+            `  happys stack wt ${stack} -- use ${c} <owner/branch|/abs/path>\n` +
+            `- then re-run:\n` +
+            `  happys edison task:scaffold ${taskId} --yes --reuse-only\n`
+        );
+      } else {
+        const stdout = await runCapture(
+          'node',
+          ['./bin/happys.mjs', 'wt', 'new', c, baseWorktree, `--from=${from}`, '--json'],
+          { cwd: rootDir }
+        );
+        const res = JSON.parse(stdout);
+        createdWorktrees.push({ component: c, variant: from, taskId, path: res.path, branch: res.branch });
+        await run('node', ['./bin/happys.mjs', 'stack', 'wt', stack, '--', 'use', c, res.path, '--json'], { cwd: rootDir });
+        pinned.push({ stack, component: c, taskId, path: res.path });
+      }
     }
   }
 

package/scripts/happy.mjs

@@ -1,23 +1,12 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { expandHome } from './utils/canonical_home.mjs';
-import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths.mjs';
-
-function resolveCliHomeDir() {
-  const fromExplicit = (process.env.HAPPY_HOME_DIR ?? '').trim();
-  if (fromExplicit) {
-    return expandHome(fromExplicit);
-  }
-  const fromStacks = (process.env.HAPPY_STACKS_CLI_HOME_DIR ?? process.env.HAPPY_LOCAL_CLI_HOME_DIR ?? '').trim();
-  if (fromStacks) {
-    return expandHome(fromStacks);
-  }
-  return join(getDefaultAutostartPaths().baseDir, 'cli');
-}
+import { getComponentDir, getRootDir, getStackName } from './utils/paths/paths.mjs';
+import { resolveCliHomeDir } from './utils/stack/dirs.mjs';
+import { getPublicServerUrlEnvOverride, resolveServerPortFromEnv } from './utils/server/urls.mjs';
 
 async function main() {
   const argv = process.argv.slice(2);
@@ -42,12 +31,12 @@ async function main() {
 
   const rootDir = getRootDir(import.meta.url);
 
-  const portRaw = (process.env.HAPPY_STACKS_SERVER_PORT ?? process.env.HAPPY_LOCAL_SERVER_PORT ?? '').trim();
-  const port = portRaw ? Number(portRaw) : 3005;
-  const serverPort = Number.isFinite(port) ? port : 3005;
+  const stackName =
+    (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').toString().trim() || getStackName();
+  const serverPort = resolveServerPortFromEnv({ env: process.env, defaultPort: 3005 });
 
   const internalServerUrl = `http://127.0.0.1:${serverPort}`;
-  const publicServerUrl = (process.env.HAPPY_STACKS_SERVER_URL ?? process.env.HAPPY_LOCAL_SERVER_URL ?? '').trim() || `http://localhost:${serverPort}`;
+  const { publicServerUrl } = getPublicServerUrlEnvOverride({ env: process.env, serverPort, stackName });
 
   const cliHomeDir = resolveCliHomeDir();
 

package/scripts/init.mjs

@@ -4,19 +4,11 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
-import { ensureCanonicalHomeEnvUpdated, ensureHomeEnvUpdated } from './utils/config.mjs';
-import { parseDotenv } from './utils/dotenv.mjs';
-import { expandHome } from './utils/canonical_home.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
-
-async function readJsonIfExists(path) {
-  try {
-    const raw = await readFile(path, 'utf-8');
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
+import { ensureCanonicalHomeEnvUpdated, ensureHomeEnvUpdated } from './utils/env/config.mjs';
+import { parseDotenv } from './utils/env/dotenv.mjs';
+import { expandHome } from './utils/paths/canonical_home.mjs';
+import { readJsonIfExists } from './utils/fs/json.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
 
 function getCliRootDir() {
   return dirname(dirname(fileURLToPath(import.meta.url)));

package/scripts/install.mjs

@@ -1,17 +1,17 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
-import { pathExists } from './utils/fs.mjs';
-import { run } from './utils/proc.mjs';
-import { getComponentDir, getRootDir } from './utils/paths.mjs';
-import { getServerComponentName } from './utils/server.mjs';
-import { ensureCliBuilt, ensureDepsInstalled, ensureHappyCliLocalNpmLinked } from './utils/pm.mjs';
+import { pathExists } from './utils/fs/fs.mjs';
+import { run } from './utils/proc/proc.mjs';
+import { getComponentDir, getRootDir } from './utils/paths/paths.mjs';
+import { getServerComponentName } from './utils/server/server.mjs';
+import { ensureCliBuilt, ensureDepsInstalled, ensureHappyCliLocalNpmLinked } from './utils/proc/pm.mjs';
 import { dirname, join } from 'node:path';
 import { mkdir } from 'node:fs/promises';
 import { installService, uninstallService } from './service.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { ensureEnvLocalUpdated } from './utils/env_local.mjs';
+import { ensureEnvLocalUpdated } from './utils/env/env_local.mjs';
 import { isTty, prompt, promptSelect, withRl } from './utils/cli/wizard.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
 
 /**
  * Install/setup the local stack:

package/scripts/lint.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 pickLintScript(scripts) {
-  if (!scripts) return null;
   const candidates = [
     'lint',
     'lint:ci',
@@ -39,7 +18,7 @@ function pickLintScript(scripts) {
     'eslint',
     'eslint:check',
   ];
-  return candidates.find((k) => typeof scripts[k] === 'string' && scripts[k].trim()) ?? null;
+  return pickFirstScript(scripts, candidates);
 }
 
 async function main() {
@@ -86,7 +65,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/menubar.mjs

@@ -1,14 +1,15 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { cp, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { getHappyStacksHomeDir, getRootDir } from './utils/paths.mjs';
+import { getHappyStacksHomeDir, getRootDir } from './utils/paths/paths.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { ensureEnvLocalUpdated } from './utils/env_local.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
+import { ensureEnvLocalUpdated } from './utils/env/env_local.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
+import { normalizeProfile } from './utils/cli/normalize.mjs';
 
 async function ensureSwiftbarAssets({ cliRootDir }) {
   const homeDir = getHappyStacksHomeDir();
@@ -59,14 +60,6 @@ function removeSwiftbarPlugins({ patterns }) {
   return out || null;
 }
 
-function normalizeMenubarMode(raw) {
-  const v = String(raw ?? '').trim().toLowerCase();
-  if (!v) return '';
-  if (v === 'selfhost' || v === 'self-host' || v === 'self_host' || v === 'host') return 'selfhost';
-  if (v === 'dev' || v === 'developer') return 'dev';
-  return '';
-}
-
 async function main() {
   const rawArgv = process.argv.slice(2);
   const argv = rawArgv[0] === 'menubar' ? rawArgv.slice(1) : rawArgv;
@@ -128,7 +121,7 @@ async function main() {
   if (cmd === 'mode') {
     const positionals = argv.filter((a) => !a.startsWith('--'));
     const raw = positionals[1] ?? '';
-    const mode = normalizeMenubarMode(raw);
+    const mode = normalizeProfile(raw);
     if (!mode) {
       throw new Error('[menubar] usage: happys menubar mode <selfhost|dev> [--json]');
     }

package/scripts/migrate.mjs

@@ -1,17 +1,18 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { copyFile, mkdir, readFile } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { createRequire } from 'node:module';
 
 import { parseArgs } from './utils/cli/args.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { parseDotenv } from './utils/dotenv.mjs';
-import { ensureEnvFileUpdated } from './utils/env_file.mjs';
-import { resolveStackEnvPath } from './utils/paths.mjs';
-import { ensureDepsInstalled } from './utils/pm.mjs';
-import { ensureHappyServerManagedInfra, applyHappyServerMigrations } from './utils/happy_server_infra.mjs';
-import { runCapture } from './utils/proc.mjs';
-import { pickNextFreeTcpPort } from './utils/ports.mjs';
+import { ensureEnvFileUpdated } from './utils/env/env_file.mjs';
+import { readEnvObjectFromFile } from './utils/env/read.mjs';
+import { resolveStackEnvPath } from './utils/paths/paths.mjs';
+import { ensureDepsInstalled } from './utils/proc/pm.mjs';
+import { ensureHappyServerManagedInfra, applyHappyServerMigrations } from './utils/server/infra/happy_server_infra.mjs';
+import { runCapture } from './utils/proc/proc.mjs';
+import { pickNextFreeTcpPort } from './utils/net/ports.mjs';
+import { getEnvValue } from './utils/env/values.mjs';
 
 function usage() {
   return [
@@ -25,18 +26,7 @@ function usage() {
   ].join('\n');
 }
 
-async function readEnvObject(envPath) {
-  try {
-    const raw = await readFile(envPath, 'utf-8');
-    return Object.fromEntries(parseDotenv(raw).entries());
-  } catch {
-    return {};
-  }
-}
-
-function getEnvValue(env, key) {
-  return (env?.[key] ?? '').toString().trim();
-}
+const readEnvObject = readEnvObjectFromFile;
 
 function parseFileDatabaseUrl(url) {
   const raw = String(url ?? '').trim();
@@ -290,7 +280,7 @@ async function main() {
     throw new Error('[migrate] --to-stack is required');
   }
 
-  const rootDir = (await import('./utils/paths.mjs')).getRootDir(import.meta.url);
+  const rootDir = (await import('./utils/paths/paths.mjs')).getRootDir(import.meta.url);
   await migrateLightToServer({ rootDir, fromStack, toStack, includeFiles, force, json });
 }