happy-stacks 0.1.2 → 0.2.0

package/scripts/happy.mjs

@@ -1,16 +1,12 @@
 import './utils/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 { 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 expandHome(p) {
-  return p.replace(/^~(?=\/)/, homedir());
-}
-
 function resolveCliHomeDir() {
   const fromExplicit = (process.env.HAPPY_HOME_DIR ?? '').trim();
   if (fromExplicit) {

package/scripts/init.mjs

@@ -6,10 +6,8 @@ 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());
-}
+import { expandHome } from './utils/canonical_home.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
 
 async function readJsonIfExists(path) {
   try {
@@ -139,15 +137,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 +157,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 +253,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 +315,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 +342,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 +379,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 +440,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,5 +1,5 @@
 import './utils/env.mjs';
-import { parseArgs } from './utils/args.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';
@@ -8,15 +8,16 @@ import { ensureCliBuilt, ensureDepsInstalled, ensureHappyCliLocalNpmLinked } fro
 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 { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 import { ensureEnvLocalUpdated } from './utils/env_local.mjs';
-import { isTty, prompt, promptSelect, withRl } from './utils/wizard.mjs';
+import { isTty, prompt, promptSelect, withRl } from './utils/cli/wizard.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/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,145 @@
+import './utils/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';
+
+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',
+    'check',
+    'check:lint',
+    'eslint',
+    'eslint:check',
+  ];
+  return candidates.find((k) => typeof scripts[k] === 'string' && scripts[k].trim()) ?? null;
+}
+
+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 readScripts(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

@@ -3,9 +3,12 @@ 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 { parseArgs } from './utils/args.mjs';
-import { printResult, wantsHelp, wantsJson } from './utils/cli.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';
 
 async function ensureSwiftbarAssets({ cliRootDir }) {
   const homeDir = getHappyStacksHomeDir();
@@ -34,9 +37,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;
@@ -45,6 +59,14 @@ function removeSwiftbarPlugins() {
   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;
@@ -55,16 +77,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 +107,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 = normalizeMenubarMode(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

@@ -3,14 +3,15 @@ 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 { 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';
 
 function usage() {
   return [
@@ -97,9 +98,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 +118,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 +128,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 });

package/scripts/mobile.mjs

@@ -1,11 +1,12 @@
 import './utils/env.mjs';
-import { parseArgs } from './utils/args.mjs';
-import { killPortListeners, pickNextFreeTcpPort } from './utils/ports.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { pickNextFreeTcpPort } from './utils/ports.mjs';
 import { run, runCapture, spawnProc } from './utils/proc.mjs';
 import { getComponentDir, getDefaultAutostartPaths, getRootDir } from './utils/paths.mjs';
 import { ensureDepsInstalled, pmExecBin, pmSpawnBin, requireDir } from './utils/pm.mjs';
-import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 import { ensureExpoIsolationEnv, getExpoStatePaths, isStateProcessRunning, killPid, wantsExpoClearCache, writePidState } from './utils/expo.mjs';
+import { killProcessGroupOwnedByStack } from './utils/ownership.mjs';
 
 /**
  * Mobile dev helper for the embedded `components/happy` Expo app.
@@ -306,11 +307,16 @@ async function main() {
   }
   if (restart && running.state?.pid) {
     const prevPid = Number(running.state.pid);
-    const prevPort = Number(running.state.port);
-    if (Number.isFinite(prevPort) && prevPort > 0) {
-      await killPortListeners(prevPort, { label: 'expo' });
+    const stackName = (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').trim() || autostart.stackName;
+    const envPath = (process.env.HAPPY_STACKS_ENV_FILE ?? process.env.HAPPY_LOCAL_ENV_FILE ?? '').toString();
+    const res = await killProcessGroupOwnedByStack(prevPid, { stackName, envPath, label: 'expo-mobile', json: true });
+    if (!res.killed) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[mobile] not stopping existing Metro pid=${prevPid} because it does not look stack-owned.\n` +
+          `[mobile] continuing by starting a new Metro on a free port.`
+      );
     }
-    await killPid(prevPid);
   }
 
   const requestedPort = Number.parseInt(String(portRaw), 10);