happy-stacks 0.1.2 → 0.3.0

package/scripts/happy.mjs

@@ -1,27 +1,12 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { parseArgs } from './utils/args.mjs';
-import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
-import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths.mjs';
-
-function expandHome(p) {
-  return p.replace(/^~(?=\/)/, homedir());
-}
-
-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 { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+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);
@@ -46,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,21 +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';
-
-function expandHome(p) {
-  return p.replace(/^~(?=\/)/, homedir());
-}
-
-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)));
@@ -139,15 +129,15 @@ async function main() {
   if (argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') {
     console.log([
       '[init] usage:',
-      '  happys init [--home-dir=/path] [--workspace-dir=/path] [--runtime-dir=/path] [--storage-dir=/path] [--cli-root-dir=/path] [--tailscale-bin=/path] [--tailscale-cmd-timeout-ms=MS] [--tailscale-enable-timeout-ms=MS] [--tailscale-enable-timeout-ms-auto=MS] [--tailscale-reset-timeout-ms=MS] [--install-path] [--no-runtime] [--force-runtime] [--no-bootstrap] [--] [bootstrap args...]',
+      '  happys init [--canonical-home-dir=/path] [--home-dir=/path] [--workspace-dir=/path] [--runtime-dir=/path] [--storage-dir=/path] [--cli-root-dir=/path] [--tailscale-bin=/path] [--tailscale-cmd-timeout-ms=MS] [--tailscale-enable-timeout-ms=MS] [--tailscale-enable-timeout-ms-auto=MS] [--tailscale-reset-timeout-ms=MS] [--install-path] [--no-runtime] [--force-runtime] [--no-bootstrap] [--] [bootstrap args...]',
       '',
       'notes:',
-      '  - writes ~/.happy-stacks/.env (stable pointer file)',
-      '  - default workspace: ~/.happy-stacks/workspace',
-      '  - default runtime: ~/.happy-stacks/runtime (recommended for services/SwiftBar)',
+      '  - writes <canonicalHomeDir>/.env (stable pointer file; default: ~/.happy-stacks/.env)',
+      '  - default workspace: <homeDir>/workspace',
+      '  - default runtime: <homeDir>/runtime (recommended for services/SwiftBar)',
       '  - runtime install is skipped if the same version is already installed (use --force-runtime to reinstall)',
       '  - set HAPPY_STACKS_INIT_NO_RUNTIME=1 to persist skipping runtime installs on this machine',
-      '  - optional: --install-path adds ~/.happy-stacks/bin to your shell PATH (idempotent)',
+      '  - optional: --install-path adds <homeDir>/bin to your shell PATH (idempotent)',
       '  - by default, runs `happys bootstrap --interactive` at the end (TTY only) IF components are not already present',
     ].join('\n'));
     return;
@@ -159,7 +149,17 @@ async function main() {
   //
   // Other scripts load this pointer via `scripts/utils/env.mjs`, but `init.mjs` is often run before
   // anything else (or directly from a repo checkout). So we load it here too.
-  const canonicalEnvPath = join(homedir(), '.happy-stacks', '.env');
+  const canonicalHomeDirRaw = parseArgValue(argv, 'canonical-home-dir');
+  const canonicalHomeDir = expandHome(firstNonEmpty(
+    canonicalHomeDirRaw,
+    process.env.HAPPY_STACKS_CANONICAL_HOME_DIR,
+    process.env.HAPPY_LOCAL_CANONICAL_HOME_DIR,
+    join(homedir(), '.happy-stacks'),
+  ));
+  process.env.HAPPY_STACKS_CANONICAL_HOME_DIR = canonicalHomeDir;
+  process.env.HAPPY_LOCAL_CANONICAL_HOME_DIR = process.env.HAPPY_LOCAL_CANONICAL_HOME_DIR ?? canonicalHomeDir;
+
+  const canonicalEnvPath = join(canonicalHomeDir, '.env');
   if (existsSync(canonicalEnvPath)) {
     await loadEnvFile(canonicalEnvPath, { override: false });
     await loadEnvFile(canonicalEnvPath, { override: true, overridePrefix: 'HAPPY_STACKS_' });
@@ -245,6 +245,7 @@ async function main() {
   const nodePath = process.execPath;
 
   await mkdir(homeDir, { recursive: true });
+  await mkdir(canonicalHomeDir, { recursive: true });
   await mkdir(workspaceDir, { recursive: true });
   await mkdir(join(workspaceDir, 'components'), { recursive: true });
   await mkdir(runtimeDir, { recursive: true });
@@ -306,10 +307,10 @@ async function main() {
   const shim = [
     '#!/bin/bash',
     'set -euo pipefail',
-    'CANONICAL_ENV="$HOME/.happy-stacks/.env"',
+    `CANONICAL_ENV="${canonicalEnvPath}"`,
     '',
     '# Best-effort: if env vars are not exported (common under launchd/SwiftBar),',
-    '# read the stable pointer file at ~/.happy-stacks/.env to discover the real dirs.',
+    '# read the stable pointer file at CANONICAL_ENV to discover the real dirs.',
     'if [[ -f "$CANONICAL_ENV" ]]; then',
     '  if [[ -z "${HAPPY_STACKS_HOME_DIR:-}" ]]; then',
     '    HAPPY_STACKS_HOME_DIR="$(grep -E \'^HAPPY_STACKS_HOME_DIR=\' "$CANONICAL_ENV" | head -n 1 | sed \'s/^HAPPY_STACKS_HOME_DIR=//\')" || true',
@@ -333,7 +334,7 @@ async function main() {
     '  fi',
     'fi',
     '',
-    'HOME_DIR="${HAPPY_STACKS_HOME_DIR:-$HOME/.happy-stacks}"',
+    `HOME_DIR="\${HAPPY_STACKS_HOME_DIR:-${canonicalHomeDir}}"`,
     'ENV_FILE="$HOME_DIR/.env"',
     'WORKDIR="${HAPPY_STACKS_WORKSPACE_DIR:-$HOME_DIR/workspace}"',
     'if [[ -d "$WORKDIR" ]]; then',
@@ -370,22 +371,31 @@ async function main() {
   await writeExecutable(happysShimPath, shim);
   await writeExecutable(happyShimPath, `#!/bin/bash\nset -euo pipefail\nexec \"${happysShimPath}\" happy \"$@\"\n`);
 
+  let didInstallPath = false;
   if (argv.includes('--install-path')) {
-    const res = await ensurePathInstalled({ homeDir });
-    if (res.updated) {
-      console.log(`[init] added ${homeDir}/bin to PATH via ${res.path}`);
+    if (isSandboxed() && !sandboxAllowsGlobalSideEffects()) {
+      console.log('[init] sandbox mode: skipping --install-path (would modify your shell config)');
+      console.log('[init] tip: set HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1 if you really want to test PATH modifications');
     } else {
-      console.log(`[init] PATH already configured in ${res.path}`);
+      const res = await ensurePathInstalled({ homeDir });
+      didInstallPath = true;
+      if (res.updated) {
+        console.log(`[init] added ${homeDir}/bin to PATH via ${res.path}`);
+      } else {
+        console.log(`[init] PATH already configured in ${res.path}`);
+      }
     }
   }
 
+  const invokedBySetup = (process.env.HAPPY_STACKS_SETUP_CHILD ?? '').trim() === '1';
+
   console.log('[init] complete');
   console.log(`[init] home:      ${homeDir}`);
   console.log(`[init] workspace:  ${workspaceDir}`);
   console.log(`[init] shims:     ${homeDir}/bin`);
   console.log('');
 
-  if (!argv.includes('--install-path')) {
+  if (!argv.includes('--install-path') || !didInstallPath) {
     console.log('[init] note: to use `happys` / `happy` from any terminal, add shims to PATH:');
     console.log(`  export PATH="${homeDir}/bin:$PATH"`);
     console.log('  (or re-run: happys init --install-path)');
@@ -422,13 +432,18 @@ async function main() {
 
   if (wantBootstrap && alreadyBootstrapped && !bootstrapExplicit) {
     console.log('[init] bootstrap: already set up; skipping');
-    console.log('[init] tip: to re-run setup: happys bootstrap --interactive');
+    console.log('[init] tip: for guided onboarding: happys setup');
     console.log('');
   }
 
+  // When `happys setup` drives init, avoid printing confusing “next steps”.
+  if (invokedBySetup) {
+    return;
+  }
+
   console.log('[init] next steps:');
   console.log(`  export PATH=\"${homeDir}/bin:$PATH\"`);
-  console.log('  happys bootstrap --interactive');
+  console.log('  happys setup');
 }
 
 main().catch((err) => {

package/scripts/install.mjs

@@ -1,22 +1,23 @@
-import './utils/env.mjs';
-import { parseArgs } from './utils/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 './utils/env/env.mjs';
+import { parseArgs } from './utils/cli/args.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.mjs';
-import { ensureEnvLocalUpdated } from './utils/env_local.mjs';
-import { isTty, prompt, promptSelect, withRl } from './utils/wizard.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { ensureEnvLocalUpdated } from './utils/env/env_local.mjs';
+import { isTty, prompt, promptSelect, withRl } from './utils/cli/wizard.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
 
 /**
  * Install/setup the local stack:
  * - ensure components exist (optionally clone if missing)
  * - install dependencies where needed
- * - build happy-cli (optional) and install `happy`/`happys` shims under `~/.happy-stacks/bin`
+ * - build happy-cli (optional) and install `happy`/`happys` shims under `<homeDir>/bin`
  * - build the web UI bundle (so `run` can serve it)
  * - optional macOS autostart (LaunchAgent)
  */
@@ -152,7 +153,9 @@ async function interactiveWizard({ rootDir, defaults }) {
     });
 
     const enableAutostart = await promptSelect(rl, {
-      title: 'Enable macOS autostart (LaunchAgent)?',
+      title: isSandboxed()
+        ? 'Enable macOS autostart (LaunchAgent)? (NOTE: sandbox mode; this is global OS state)'
+        : 'Enable macOS autostart (LaunchAgent)?',
       options: [
         { label: 'no (default)', value: false },
         { label: 'yes', value: true },
@@ -211,6 +214,8 @@ async function main() {
   const rootDir = getRootDir(import.meta.url);
 
   const interactive = flags.has('--interactive') && isTty();
+  const allowGlobal = sandboxAllowsGlobalSideEffects();
+  const sandboxed = isSandboxed();
 
   // Defaults for wizard.
   const defaultRepoSource = resolveRepoSource({ flags });
@@ -220,7 +225,7 @@ async function main() {
     upstreamOwner: 'slopus',
     serverComponentName: getServerComponentName({ kv }),
     allowClone: !flags.has('--no-clone') && ((process.env.HAPPY_LOCAL_CLONE_MISSING ?? '1') !== '0' || flags.has('--clone')),
-    enableAutostart: flags.has('--autostart') || (process.env.HAPPY_LOCAL_AUTOSTART ?? '0') === '1',
+    enableAutostart: (!sandboxed || allowGlobal) && (flags.has('--autostart') || (process.env.HAPPY_LOCAL_AUTOSTART ?? '0') === '1'),
     buildTauri: flags.has('--tauri') && !flags.has('--no-tauri'),
   };
 
@@ -260,7 +265,8 @@ async function main() {
   const cloneMissingDefault = (process.env.HAPPY_LOCAL_CLONE_MISSING ?? '1') !== '0';
   const allowClone =
     wizard?.allowClone ?? (!flags.has('--no-clone') && (flags.has('--clone') || cloneMissingDefault));
-  const enableAutostart = wizard?.enableAutostart ?? (flags.has('--autostart') || (process.env.HAPPY_LOCAL_AUTOSTART ?? '0') === '1');
+  const enableAutostartRaw = wizard?.enableAutostart ?? (flags.has('--autostart') || (process.env.HAPPY_LOCAL_AUTOSTART ?? '0') === '1');
+  const enableAutostart = sandboxed && !allowGlobal ? false : enableAutostartRaw;
   const disableAutostart = flags.has('--no-autostart');
 
   const serverComponentName = (wizard?.serverComponentName ?? getServerComponentName({ kv })).trim();
@@ -366,7 +372,7 @@ async function main() {
       serverComponentName,
       dirs: { serverLightDir, serverFullDir, cliDir: cliDirFinal, uiDir: uiDirFinal },
       cloned: allowClone,
-      autostart: enableAutostart ? 'enabled' : disableAutostart ? 'disabled' : 'unchanged',
+      autostart: enableAutostart ? 'enabled' : sandboxed && enableAutostartRaw && !allowGlobal ? 'skipped (sandbox)' : disableAutostart ? 'disabled' : 'unchanged',
       interactive: Boolean(wizard),
     },
     text: '[local] setup complete',

package/scripts/lint.mjs

@@ -0,0 +1,124 @@
+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/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'];
+
+function pickLintScript(scripts) {
+  const candidates = [
+    'lint',
+    'lint:ci',
+    'check',
+    'check:lint',
+    'eslint',
+    'eslint:check',
+  ];
+  return pickFirstScript(scripts, candidates);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+
+  if (wantsHelp(argv, { flags })) {
+    printResult({
+      json,
+      data: { components: DEFAULT_COMPONENTS, flags: ['--json'] },
+      text: [
+        '[lint] usage:',
+        '  happys lint [component...] [--json]',
+        '',
+        'components:',
+        `  ${DEFAULT_COMPONENTS.join(' | ')}`,
+        '',
+        'examples:',
+        '  happys lint',
+        '  happys lint happy happy-cli',
+      ].join('\n'),
+    });
+    return;
+  }
+
+  const positionals = argv.filter((a) => !a.startsWith('--'));
+  const requested = positionals.length ? positionals : ['all'];
+  const wantAll = requested.includes('all');
+  const components = wantAll ? DEFAULT_COMPONENTS : requested;
+
+  const rootDir = getRootDir(import.meta.url);
+
+  const results = [];
+  for (const component of components) {
+    if (!DEFAULT_COMPONENTS.includes(component)) {
+      results.push({ component, ok: false, skipped: false, error: `unknown component (expected one of: ${DEFAULT_COMPONENTS.join(', ')})` });
+      continue;
+    }
+
+    const dir = getComponentDir(rootDir, component);
+    if (!(await pathExists(dir))) {
+      results.push({ component, ok: false, skipped: false, dir, error: `missing component dir: ${dir}` });
+      continue;
+    }
+
+    const scripts = await readPackageJsonScripts(dir);
+    if (!scripts) {
+      results.push({ component, ok: true, skipped: true, dir, reason: 'no package.json' });
+      continue;
+    }
+
+    const script = pickLintScript(scripts);
+    if (!script) {
+      results.push({ component, ok: true, skipped: true, dir, reason: 'no lint script found in package.json' });
+      continue;
+    }
+
+    await ensureDepsInstalled(dir, component);
+    const pm = await detectPackageManagerCmd(dir);
+
+    try {
+      // eslint-disable-next-line no-console
+      console.log(`[lint] ${component}: running ${pm.name} ${script}`);
+      await run(pm.cmd, pm.argsForScript(script), { cwd: dir, env: process.env });
+      results.push({ component, ok: true, skipped: false, dir, pm: pm.name, script });
+    } catch (e) {
+      results.push({ component, ok: false, skipped: false, dir, pm: pm.name, script, error: String(e?.message ?? e) });
+    }
+  }
+
+  const ok = results.every((r) => r.ok);
+  if (json) {
+    printResult({ json, data: { ok, results } });
+    return;
+  }
+
+  const lines = ['[lint] results:'];
+  for (const r of results) {
+    if (r.ok && r.skipped) {
+      lines.push(`- ↪ ${r.component}: skipped (${r.reason})`);
+    } else if (r.ok) {
+      lines.push(`- ✅ ${r.component}: ok (${r.pm} ${r.script})`);
+    } else {
+      lines.push(`- ❌ ${r.component}: failed (${r.pm ?? 'unknown'} ${r.script ?? ''})`);
+      if (r.error) lines.push(`  - ${r.error}`);
+    }
+  }
+  if (!ok) {
+    lines.push('');
+    lines.push('[lint] failed');
+  }
+  printResult({ json: false, text: lines.join('\n') });
+  if (!ok) {
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('[lint] failed:', err);
+  process.exit(1);
+});
+

package/scripts/menubar.mjs

@@ -1,11 +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 { getHappyStacksHomeDir, getRootDir } from './utils/paths.mjs';
-import { parseArgs } from './utils/args.mjs';
-import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
+import { createHash } from 'node:crypto';
+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/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();
@@ -34,9 +38,20 @@ function openSwiftbarPluginsDir() {
   }
 }
 
-function removeSwiftbarPlugins() {
+function sandboxPluginBasename() {
+  const sandboxDir = (process.env.HAPPY_STACKS_SANDBOX_DIR ?? '').trim();
+  if (!sandboxDir) return '';
+  const hash = createHash('sha256').update(sandboxDir).digest('hex').slice(0, 10);
+  return `happy-stacks.sandbox-${hash}`;
+}
+
+function removeSwiftbarPlugins({ patterns }) {
+  const pats = (patterns ?? []).filter(Boolean);
+  const args = pats.length ? pats.map((p) => `"${p}"`).join(' ') : '"happy-stacks.*.sh" "happy-local.*.sh"';
   const s =
-    'DIR="$(defaults read com.ameba.SwiftBar PluginDirectory 2>/dev/null)"; if [[ -z "$DIR" ]]; then DIR="$HOME/Library/Application Support/SwiftBar/Plugins"; fi; if [[ -d "$DIR" ]]; then rm -f "$DIR"/happy-stacks.*.sh "$DIR"/happy-local.*.sh 2>/dev/null || true; echo "$DIR"; else echo ""; fi';
+    `DIR="$(defaults read com.ameba.SwiftBar PluginDirectory 2>/dev/null)"; ` +
+    `if [[ -z "$DIR" ]]; then DIR="$HOME/Library/Application Support/SwiftBar/Plugins"; fi; ` +
+    `if [[ -d "$DIR" ]]; then rm -f "$DIR"/${args} 2>/dev/null || true; echo "$DIR"; else echo ""; fi`;
   const res = spawnSync('bash', ['-lc', s], { encoding: 'utf-8' });
   if (res.status !== 0) {
     return null;
@@ -55,16 +70,19 @@ async function main() {
   if (wantsHelp(argv, { flags }) || cmd === 'help') {
     printResult({
       json,
-      data: { commands: ['install', 'uninstall', 'open'] },
+      data: { commands: ['install', 'uninstall', 'open', 'mode', 'status'] },
       text: [
         '[menubar] usage:',
         '  happys menubar install [--json]',
         '  happys menubar uninstall [--json]',
         '  happys menubar open [--json]',
+        '  happys menubar mode <selfhost|dev> [--json]',
+        '  happys menubar status [--json]',
         '',
         'notes:',
         '  - installs SwiftBar plugin into the active SwiftBar plugin folder',
-        '  - keeps plugin source under ~/.happy-stacks/extras/swiftbar for stability',
+        '  - keeps plugin source under <homeDir>/extras/swiftbar for stability',
+        '  - sandbox mode: install/uninstall are disabled by default (set HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1 to override)',
       ].join('\n'),
     });
     return;
@@ -82,15 +100,63 @@ async function main() {
   }
 
   if (cmd === 'menubar:uninstall' || cmd === 'uninstall') {
-    const dir = removeSwiftbarPlugins();
+    if (isSandboxed() && !sandboxAllowsGlobalSideEffects()) {
+      printResult({ json, data: { ok: true, skipped: 'sandbox' }, text: '[menubar] uninstall skipped (sandbox mode)' });
+      return;
+    }
+    const patterns = isSandboxed()
+      ? [`${sandboxPluginBasename()}.*.sh`]
+      : ['happy-stacks.*.sh', 'happy-local.*.sh'];
+    const dir = removeSwiftbarPlugins({ patterns });
     printResult({ json, data: { ok: true, pluginsDir: dir }, text: dir ? `[menubar] removed plugins from ${dir}` : '[menubar] no plugins dir found' });
     return;
   }
 
+  if (cmd === 'status') {
+    const mode = (process.env.HAPPY_STACKS_MENUBAR_MODE ?? process.env.HAPPY_LOCAL_MENUBAR_MODE ?? 'dev').trim() || 'dev';
+    printResult({ json, data: { ok: true, mode }, text: `[menubar] mode: ${mode}` });
+    return;
+  }
+
+  if (cmd === 'mode') {
+    const positionals = argv.filter((a) => !a.startsWith('--'));
+    const raw = positionals[1] ?? '';
+    const mode = normalizeProfile(raw);
+    if (!mode) {
+      throw new Error('[menubar] usage: happys menubar mode <selfhost|dev> [--json]');
+    }
+    await ensureEnvLocalUpdated({
+      rootDir: cliRootDir,
+      updates: [
+        { key: 'HAPPY_STACKS_MENUBAR_MODE', value: mode },
+        { key: 'HAPPY_LOCAL_MENUBAR_MODE', value: mode },
+      ],
+    });
+    printResult({ json, data: { ok: true, mode }, text: `[menubar] mode set: ${mode}` });
+    return;
+  }
+
   if (cmd === 'menubar:install' || cmd === 'install') {
+    if (isSandboxed() && !sandboxAllowsGlobalSideEffects()) {
+      throw new Error(
+        '[menubar] install is disabled in sandbox mode.\n' +
+          'Reason: SwiftBar plugin installation writes to a global user folder.\n' +
+          'If you really want this, set: HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1'
+      );
+    }
     const { destDir } = await ensureSwiftbarAssets({ cliRootDir });
     const installer = join(destDir, 'install.sh');
-    const res = spawnSync('bash', [installer, '--force'], { stdio: 'inherit', env: { ...process.env, HAPPY_STACKS_HOME_DIR: getHappyStacksHomeDir() } });
+    const env = {
+      ...process.env,
+      HAPPY_STACKS_HOME_DIR: getHappyStacksHomeDir(),
+      ...(isSandboxed()
+        ? {
+            HAPPY_STACKS_SWIFTBAR_PLUGIN_BASENAME: sandboxPluginBasename(),
+            HAPPY_STACKS_SWIFTBAR_PLUGIN_WRAPPER: '1',
+          }
+        : {}),
+    };
+    const res = spawnSync('bash', [installer, '--force'], { stdio: 'inherit', env });
     if (res.status !== 0) {
       process.exit(res.status ?? 1);
     }

package/scripts/migrate.mjs

@@ -1,16 +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/args.mjs';
-import { printResult, wantsHelp, wantsJson } from './utils/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 { parseArgs } from './utils/cli/args.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.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 [
@@ -24,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();
@@ -97,9 +88,15 @@ async function migrateLightToServer({ rootDir, fromStack, toStack, includeFiles,
   }
 
   const toPortRaw = getEnvValue(toEnv, 'HAPPY_STACKS_SERVER_PORT') || getEnvValue(toEnv, 'HAPPY_LOCAL_SERVER_PORT');
-  const toPort = toPortRaw ? Number(toPortRaw) : NaN;
+  let toPort = toPortRaw ? Number(toPortRaw) : NaN;
+  const toEphemeral = !toPortRaw;
   if (!Number.isFinite(toPort) || toPort <= 0) {
-    throw new Error(`[migrate] to-stack is missing a valid server port (HAPPY_STACKS_SERVER_PORT)`);
+    // Ephemeral-port stacks don't pin ports in env. Pick a free port for this one-off migration run.
+    toPort = await pickNextFreeTcpPort(3005);
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.log(`[migrate] to-stack has no pinned port; using ephemeral port ${toPort} for this migration run`);
+    }
   }
 
   // Ensure target secret is the same as source so auth tokens remain valid after migration.
@@ -111,17 +108,6 @@ async function migrateLightToServer({ rootDir, fromStack, toStack, includeFiles,
     updates: [{ key: 'HAPPY_STACKS_HANDY_MASTER_SECRET_FILE', value: targetSecretPath }],
   });
 
-  // Bring up infra and ensure env vars are present.
-  const infra = await ensureHappyServerManagedInfra({
-    stackName: toStack,
-    baseDir: to.baseDir,
-    serverPort: toPort,
-    publicServerUrl: `http://127.0.0.1:${toPort}`,
-    envPath: to.envPath,
-    env: process.env,
-  });
-  await applyHappyServerMigrations({ serverDir: fullDir, env: { ...process.env, ...infra.env } });
-
   // Resolve component dirs (prefer stack-pinned dirs).
   const lightDir = getEnvValue(fromEnv, 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT') || getEnvValue(fromEnv, 'HAPPY_LOCAL_COMPONENT_DIR_HAPPY_SERVER_LIGHT');
   const fullDir = getEnvValue(toEnv, 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER') || getEnvValue(toEnv, 'HAPPY_LOCAL_COMPONENT_DIR_HAPPY_SERVER');
@@ -132,6 +118,20 @@ async function migrateLightToServer({ rootDir, fromStack, toStack, includeFiles,
   await ensureDepsInstalled(lightDir, 'happy-server-light');
   await ensureDepsInstalled(fullDir, 'happy-server');
 
+  // Bring up infra and ensure env vars are present.
+  const infra = await ensureHappyServerManagedInfra({
+    stackName: toStack,
+    baseDir: to.baseDir,
+    serverPort: toPort,
+    publicServerUrl: `http://127.0.0.1:${toPort}`,
+    envPath: to.envPath,
+    env: {
+      ...process.env,
+      ...(toEphemeral ? { HAPPY_STACKS_EPHEMERAL_PORTS: '1', HAPPY_LOCAL_EPHEMERAL_PORTS: '1' } : {}),
+    },
+  });
+  await applyHappyServerMigrations({ serverDir: fullDir, env: { ...process.env, ...infra.env } });
+
   // Copy sqlite DB to a snapshot so migration is consistent even if the source server is running.
   const snapshotDir = join(to.baseDir, 'migrations');
   await mkdir(snapshotDir, { recursive: true });
@@ -280,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 });
 }