happy-stacks 0.1.0 → 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

@@ -1,12 +1,21 @@
+import { existsSync } from 'node:fs';
 import { mkdir, writeFile, readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
-import { ensureHomeEnvUpdated } from './utils/config.mjs';
-
-function expandHome(p) {
-  return p.replace(/^~(?=\/)/, homedir());
+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;
+  }
 }
 
 function getCliRootDir() {
@@ -22,6 +31,47 @@ function parseArgValue(argv, key) {
   return null;
 }
 
+function firstNonEmpty(...values) {
+  for (const v of values) {
+    const s = (v ?? '').trim();
+    if (s) return s;
+  }
+  return '';
+}
+
+async function loadEnvFile(path, { override = false, overridePrefix = null } = {}) {
+  try {
+    const contents = await readFile(path, 'utf-8');
+    const parsed = parseDotenv(contents);
+    for (const [k, v] of parsed.entries()) {
+      const allowOverride = override && (!overridePrefix || k.startsWith(overridePrefix));
+      if (allowOverride || process.env[k] == null || process.env[k] === '') {
+        process.env[k] = v;
+      }
+    }
+  } catch {
+    // ignore missing/invalid env file
+  }
+}
+
+function isWorkspaceBootstrapped(workspaceDir) {
+  // Heuristic: if the expected component repos exist in the workspace, we consider bootstrap "already done"
+  // and avoid re-running the interactive bootstrap wizard from `happys init`.
+  //
+  // Users can always re-run bootstrap explicitly:
+  //   happys bootstrap --interactive
+  try {
+    const componentsDir = join(workspaceDir, 'components');
+    const ui = join(componentsDir, 'happy', 'package.json');
+    const cli = join(componentsDir, 'happy-cli', 'package.json');
+    const serverLight = join(componentsDir, 'happy-server-light', 'package.json');
+    const serverFull = join(componentsDir, 'happy-server', 'package.json');
+    return existsSync(ui) && existsSync(cli) && (existsSync(serverLight) || existsSync(serverFull));
+  } catch {
+    return false;
+  }
+}
+
 async function writeExecutable(path, contents) {
   await writeFile(path, contents, { mode: 0o755 });
 }
@@ -87,64 +137,175 @@ 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] [--install-path] [--no-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)',
-      '  - optional: --install-path adds ~/.happy-stacks/bin to your shell PATH (idempotent)',
-      '  - by default, runs `happys bootstrap --interactive` at the end (TTY only)',
+      '  - 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 <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;
   }
 
   const cliRootDir = getCliRootDir();
 
+  // Important: `happys init` must be idempotent and must not "forget" custom dirs from a prior install.
+  //
+  // 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 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_' });
+    await loadEnvFile(canonicalEnvPath, { override: true, overridePrefix: 'HAPPY_LOCAL_' });
+  }
+
   const homeDirRaw = parseArgValue(argv, 'home-dir');
-  const homeDir = expandHome((homeDirRaw ?? '').trim() || (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim() || join(homedir(), '.happy-stacks'));
+  const homeDir = expandHome(firstNonEmpty(
+    homeDirRaw,
+    process.env.HAPPY_STACKS_HOME_DIR,
+    process.env.HAPPY_LOCAL_HOME_DIR,
+    join(homedir(), '.happy-stacks'),
+  ));
   process.env.HAPPY_STACKS_HOME_DIR = homeDir;
+  process.env.HAPPY_LOCAL_HOME_DIR = process.env.HAPPY_LOCAL_HOME_DIR ?? homeDir;
 
   const workspaceDirRaw = parseArgValue(argv, 'workspace-dir');
-  const workspaceDir = expandHome((workspaceDirRaw ?? '').trim() || join(homeDir, 'workspace'));
-  process.env.HAPPY_STACKS_WORKSPACE_DIR = process.env.HAPPY_STACKS_WORKSPACE_DIR ?? workspaceDir;
+  const workspaceDir = expandHome(firstNonEmpty(
+    workspaceDirRaw,
+    process.env.HAPPY_STACKS_WORKSPACE_DIR,
+    process.env.HAPPY_LOCAL_WORKSPACE_DIR,
+    join(homeDir, 'workspace'),
+  ));
+  process.env.HAPPY_STACKS_WORKSPACE_DIR = workspaceDir;
+  process.env.HAPPY_LOCAL_WORKSPACE_DIR = process.env.HAPPY_LOCAL_WORKSPACE_DIR ?? workspaceDir;
 
   const runtimeDirRaw = parseArgValue(argv, 'runtime-dir');
-  const runtimeDir = expandHome((runtimeDirRaw ?? '').trim() || (process.env.HAPPY_STACKS_RUNTIME_DIR ?? '').trim() || join(homeDir, 'runtime'));
-  process.env.HAPPY_STACKS_RUNTIME_DIR = process.env.HAPPY_STACKS_RUNTIME_DIR ?? runtimeDir;
+  const runtimeDir = expandHome(firstNonEmpty(
+    runtimeDirRaw,
+    process.env.HAPPY_STACKS_RUNTIME_DIR,
+    process.env.HAPPY_LOCAL_RUNTIME_DIR,
+    join(homeDir, 'runtime'),
+  ));
+  process.env.HAPPY_STACKS_RUNTIME_DIR = runtimeDir;
+  process.env.HAPPY_LOCAL_RUNTIME_DIR = process.env.HAPPY_LOCAL_RUNTIME_DIR ?? runtimeDir;
+
+  const storageDirRaw = parseArgValue(argv, 'storage-dir');
+  const storageDirOverride = expandHome((storageDirRaw ?? '').trim());
+  if (storageDirOverride) {
+    process.env.HAPPY_STACKS_STORAGE_DIR = process.env.HAPPY_STACKS_STORAGE_DIR ?? storageDirOverride;
+  }
+
+  const cliRootDirRaw = parseArgValue(argv, 'cli-root-dir');
+  const cliRootDirOverride = expandHome((cliRootDirRaw ?? '').trim());
+  if (cliRootDirOverride) {
+    process.env.HAPPY_STACKS_CLI_ROOT_DIR = process.env.HAPPY_STACKS_CLI_ROOT_DIR ?? cliRootDirOverride;
+  }
+
+  const tailscaleBinRaw = parseArgValue(argv, 'tailscale-bin');
+  const tailscaleBinOverride = expandHome((tailscaleBinRaw ?? '').trim());
+  if (tailscaleBinOverride) {
+    process.env.HAPPY_STACKS_TAILSCALE_BIN = process.env.HAPPY_STACKS_TAILSCALE_BIN ?? tailscaleBinOverride;
+  }
+
+  const tailscaleCmdTimeoutMsRaw = parseArgValue(argv, 'tailscale-cmd-timeout-ms');
+  const tailscaleCmdTimeoutMsOverride = (tailscaleCmdTimeoutMsRaw ?? '').trim();
+  if (tailscaleCmdTimeoutMsOverride) {
+    process.env.HAPPY_STACKS_TAILSCALE_CMD_TIMEOUT_MS =
+      process.env.HAPPY_STACKS_TAILSCALE_CMD_TIMEOUT_MS ?? tailscaleCmdTimeoutMsOverride;
+  }
+
+  const tailscaleEnableTimeoutMsRaw = parseArgValue(argv, 'tailscale-enable-timeout-ms');
+  const tailscaleEnableTimeoutMsOverride = (tailscaleEnableTimeoutMsRaw ?? '').trim();
+  if (tailscaleEnableTimeoutMsOverride) {
+    process.env.HAPPY_STACKS_TAILSCALE_ENABLE_TIMEOUT_MS =
+      process.env.HAPPY_STACKS_TAILSCALE_ENABLE_TIMEOUT_MS ?? tailscaleEnableTimeoutMsOverride;
+  }
+
+  const tailscaleEnableTimeoutMsAutoRaw = parseArgValue(argv, 'tailscale-enable-timeout-ms-auto');
+  const tailscaleEnableTimeoutMsAutoOverride = (tailscaleEnableTimeoutMsAutoRaw ?? '').trim();
+  if (tailscaleEnableTimeoutMsAutoOverride) {
+    process.env.HAPPY_STACKS_TAILSCALE_ENABLE_TIMEOUT_MS_AUTO =
+      process.env.HAPPY_STACKS_TAILSCALE_ENABLE_TIMEOUT_MS_AUTO ?? tailscaleEnableTimeoutMsAutoOverride;
+  }
+
+  const tailscaleResetTimeoutMsRaw = parseArgValue(argv, 'tailscale-reset-timeout-ms');
+  const tailscaleResetTimeoutMsOverride = (tailscaleResetTimeoutMsRaw ?? '').trim();
+  if (tailscaleResetTimeoutMsOverride) {
+    process.env.HAPPY_STACKS_TAILSCALE_RESET_TIMEOUT_MS =
+      process.env.HAPPY_STACKS_TAILSCALE_RESET_TIMEOUT_MS ?? tailscaleResetTimeoutMsOverride;
+  }
 
   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 });
   await mkdir(join(homeDir, 'bin'), { recursive: true });
 
-  await ensureHomeEnvUpdated({
-    updates: [
-      { key: 'HAPPY_STACKS_HOME_DIR', value: homeDir },
-      { key: 'HAPPY_STACKS_WORKSPACE_DIR', value: workspaceDir },
-      { key: 'HAPPY_STACKS_RUNTIME_DIR', value: runtimeDir },
-      { key: 'HAPPY_STACKS_NODE', value: nodePath },
-    ],
-  });
+  const pointerUpdates = [
+    { key: 'HAPPY_STACKS_HOME_DIR', value: homeDir },
+    { key: 'HAPPY_STACKS_WORKSPACE_DIR', value: workspaceDir },
+    { key: 'HAPPY_STACKS_RUNTIME_DIR', value: runtimeDir },
+    { key: 'HAPPY_STACKS_NODE', value: nodePath },
+  ];
+  if (storageDirOverride) {
+    pointerUpdates.push({ key: 'HAPPY_STACKS_STORAGE_DIR', value: storageDirOverride });
+  }
+  if (cliRootDirOverride) {
+    pointerUpdates.push({ key: 'HAPPY_STACKS_CLI_ROOT_DIR', value: cliRootDirOverride });
+  }
 
-  const installRuntime = !argv.includes('--no-runtime');
+  // Write the "real" home env (used by runtime + scripts), AND a stable pointer at ~/.happy-stacks/.env.
+  // The pointer file allows launchd/SwiftBar/minimal shells to discover the actual install location
+  // even when no env vars are exported.
+  await ensureHomeEnvUpdated({ updates: pointerUpdates });
+  await ensureCanonicalHomeEnvUpdated({ updates: pointerUpdates });
+
+  const initNoRuntimeRaw = (process.env.HAPPY_STACKS_INIT_NO_RUNTIME ?? process.env.HAPPY_LOCAL_INIT_NO_RUNTIME ?? '').trim();
+  const initNoRuntime = initNoRuntimeRaw === '1' || initNoRuntimeRaw.toLowerCase() === 'true' || initNoRuntimeRaw.toLowerCase() === 'yes';
+  const forceRuntime = argv.includes('--force-runtime');
+  const skipRuntime = argv.includes('--no-runtime') || (initNoRuntime && !forceRuntime);
+  const installRuntime = !skipRuntime;
   if (installRuntime) {
-    const pkg = JSON.parse(await readFile(join(cliRootDir, 'package.json'), 'utf-8'));
-    const version = String(pkg.version ?? '').trim() || 'latest';
-    const spec = version === '0.0.0' ? 'happy-stacks@latest' : `happy-stacks@${version}`;
+    const cliPkg = await readJsonIfExists(join(cliRootDir, 'package.json'));
+    const cliVersion = String(cliPkg?.version ?? '').trim() || 'latest';
+    const spec = cliVersion === '0.0.0' ? 'happy-stacks@latest' : `happy-stacks@${cliVersion}`;
 
-    console.log(`[init] installing runtime into ${runtimeDir} (${spec})...`);
-    let res = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--silent', '--prefix', runtimeDir, spec], { stdio: 'inherit' });
-    if (res.status !== 0) {
-      // Pre-publish developer experience: if the package isn't on npm yet (E404),
-      // fall back to installing the local checkout into the runtime prefix.
-      console.log(`[init] runtime install failed; attempting local install from ${cliRootDir}...`);
-      res = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--silent', '--prefix', runtimeDir, cliRootDir], { stdio: 'inherit' });
+    const runtimePkgPath = join(runtimeDir, 'node_modules', 'happy-stacks', 'package.json');
+    const runtimePkg = await readJsonIfExists(runtimePkgPath);
+    const runtimeVersion = String(runtimePkg?.version ?? '').trim();
+    const sameVersionInstalled = Boolean(cliVersion && cliVersion !== '0.0.0' && runtimeVersion && runtimeVersion === cliVersion);
+
+    if (!forceRuntime && sameVersionInstalled) {
+      console.log(`[init] runtime already installed in ${runtimeDir} (happy-stacks@${runtimeVersion})`);
+    } else {
+      console.log(`[init] installing runtime into ${runtimeDir} (${spec})...`);
+      let res = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--silent', '--prefix', runtimeDir, spec], { stdio: 'inherit' });
       if (res.status !== 0) {
-        process.exit(res.status ?? 1);
+        // Pre-publish developer experience: if the package isn't on npm yet (E404),
+        // fall back to installing the local checkout into the runtime prefix.
+        console.log(`[init] runtime install failed; attempting local install from ${cliRootDir}...`);
+        res = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--silent', '--prefix', runtimeDir, cliRootDir], { stdio: 'inherit' });
+        if (res.status !== 0) {
+          process.exit(res.status ?? 1);
+        }
       }
     }
   }
@@ -154,15 +315,58 @@ async function main() {
   const shim = [
     '#!/bin/bash',
     'set -euo pipefail',
-    'HOME_DIR="${HAPPY_STACKS_HOME_DIR:-$HOME/.happy-stacks}"',
+    `CANONICAL_ENV="${canonicalEnvPath}"`,
+    '',
+    '# Best-effort: if env vars are not exported (common under launchd/SwiftBar),',
+    '# 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',
+    '    export HAPPY_STACKS_HOME_DIR',
+    '  fi',
+    '  if [[ -z "${HAPPY_STACKS_WORKSPACE_DIR:-}" ]]; then',
+    '    HAPPY_STACKS_WORKSPACE_DIR="$(grep -E \'^HAPPY_STACKS_WORKSPACE_DIR=\' "$CANONICAL_ENV" | head -n 1 | sed \'s/^HAPPY_STACKS_WORKSPACE_DIR=//\')" || true',
+    '    export HAPPY_STACKS_WORKSPACE_DIR',
+    '  fi',
+    '  if [[ -z "${HAPPY_STACKS_RUNTIME_DIR:-}" ]]; then',
+    '    HAPPY_STACKS_RUNTIME_DIR="$(grep -E \'^HAPPY_STACKS_RUNTIME_DIR=\' "$CANONICAL_ENV" | head -n 1 | sed \'s/^HAPPY_STACKS_RUNTIME_DIR=//\')" || true',
+    '    export HAPPY_STACKS_RUNTIME_DIR',
+    '  fi',
+    '  if [[ -z "${HAPPY_STACKS_NODE:-}" ]]; then',
+    '    HAPPY_STACKS_NODE="$(grep -E \'^HAPPY_STACKS_NODE=\' "$CANONICAL_ENV" | head -n 1 | sed \'s/^HAPPY_STACKS_NODE=//\')" || true',
+    '    export HAPPY_STACKS_NODE',
+    '  fi',
+    '  if [[ -z "${HAPPY_STACKS_CLI_ROOT_DIR:-}" ]]; then',
+    '    HAPPY_STACKS_CLI_ROOT_DIR="$(grep -E \'^HAPPY_STACKS_CLI_ROOT_DIR=\' "$CANONICAL_ENV" | head -n 1 | sed \'s/^HAPPY_STACKS_CLI_ROOT_DIR=//\')" || true',
+    '    export HAPPY_STACKS_CLI_ROOT_DIR',
+    '  fi',
+    'fi',
+    '',
+    `HOME_DIR="\${HAPPY_STACKS_HOME_DIR:-${canonicalHomeDir}}"`,
     'ENV_FILE="$HOME_DIR/.env"',
-    'NODE_BIN=""',
-    'if [[ -f "$ENV_FILE" ]]; then',
+    'WORKDIR="${HAPPY_STACKS_WORKSPACE_DIR:-$HOME_DIR/workspace}"',
+    'if [[ -d "$WORKDIR" ]]; then',
+    '  cd "$WORKDIR"',
+    'else',
+    '  cd "$HOME"',
+    'fi',
+    'NODE_BIN="${HAPPY_STACKS_NODE:-}"',
+    'if [[ -z "$NODE_BIN" && -f "$ENV_FILE" ]]; then',
     '  NODE_BIN="$(grep -E \'^HAPPY_STACKS_NODE=\' "$ENV_FILE" | head -n 1 | sed \'s/^HAPPY_STACKS_NODE=//\')"',
     'fi',
     'if [[ -z "$NODE_BIN" ]]; then',
     '  NODE_BIN="$(command -v node 2>/dev/null || true)"',
     'fi',
+    'CLI_ROOT_DIR="${HAPPY_STACKS_CLI_ROOT_DIR:-}"',
+    'if [[ -z "$CLI_ROOT_DIR" && -f "$ENV_FILE" ]]; then',
+    '  CLI_ROOT_DIR="$(grep -E \'^HAPPY_STACKS_CLI_ROOT_DIR=\' "$ENV_FILE" | head -n 1 | sed \'s/^HAPPY_STACKS_CLI_ROOT_DIR=//\')" || true',
+    'fi',
+    'if [[ -n "$CLI_ROOT_DIR" ]]; then',
+    '  CLI_ENTRY="$CLI_ROOT_DIR/bin/happys.mjs"',
+    '  if [[ -f "$CLI_ENTRY" ]]; then',
+    '    exec "$NODE_BIN" "$CLI_ENTRY" "$@"',
+    '  fi',
+    'fi',
     'RUNTIME_DIR="${HAPPY_STACKS_RUNTIME_DIR:-$HOME_DIR/runtime}"',
     'ENTRY="$RUNTIME_DIR/node_modules/happy-stacks/bin/happys.mjs"',
     'if [[ -f "$ENTRY" ]]; then',
@@ -175,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)');
@@ -202,11 +415,15 @@ async function main() {
 
   const wantBootstrap = !argv.includes('--no-bootstrap');
   const isTty = process.stdout.isTTY && process.stdin.isTTY;
-  const shouldBootstrap = wantBootstrap;
+  const alreadyBootstrapped = isWorkspaceBootstrapped(workspaceDir);
+  const bootstrapExplicit = bootstrapArgs.length > 0;
+  const shouldBootstrap = wantBootstrap && (bootstrapExplicit || !alreadyBootstrapped);
 
   if (shouldBootstrap) {
     const nextArgs = [...bootstrapArgs];
-    if (isTty && !nextArgs.includes('--interactive') && !nextArgs.includes('-i')) {
+    // Only auto-enable the interactive wizard when init is driving bootstrap with no explicit args.
+    // If users pass args after `--`, we assume they know what they want and avoid injecting prompts.
+    if (!bootstrapExplicit && isTty && !nextArgs.includes('--interactive') && !nextArgs.includes('-i')) {
       nextArgs.unshift('--interactive');
     }
     console.log('[init] running bootstrap...');
@@ -221,12 +438,24 @@ async function main() {
     return;
   }
 
+  if (wantBootstrap && alreadyBootstrapped && !bootstrapExplicit) {
+    console.log('[init] bootstrap: already set up; skipping');
+    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) => {
   console.error('[init] failed:', err);
   process.exit(1);
 });
+

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);
+});
+