happy-stacks 0.1.0 → 0.2.0

package/scripts/utils/env.mjs

@@ -4,13 +4,32 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseDotenv } from './dotenv.mjs';
+import { expandHome, getCanonicalHomeEnvPathFromEnv } from './canonical_home.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './sandbox.mjs';
 
 async function loadEnvFile(path, { override = false, overridePrefix = null } = {}) {
   try {
     const contents = await readFile(path, 'utf-8');
     const parsed = parseDotenv(contents);
+    const allowTransientComponentDirOverrides =
+      !overridePrefix &&
+      override &&
+      ((process.env.HAPPY_STACKS_TRANSIENT_COMPONENT_OVERRIDES ?? '').trim() === '1' ||
+        (process.env.HAPPY_LOCAL_TRANSIENT_COMPONENT_OVERRIDES ?? '').trim() === '1');
     for (const [k, v] of parsed.entries()) {
       const allowOverride = override && (!overridePrefix || k.startsWith(overridePrefix));
+      // Special-case: allow one-shot CLI overrides (e.g. `happys stack typecheck <stack> --happy-cli=...`)
+      // to win over stack env files for component directories.
+      //
+      // This keeps stack env files authoritative by default (we also scrub HAPPY_STACKS_* from the parent
+      // environment in `withStackEnv()`), but lets the stack wrappers inject a temporary override when explicitly requested.
+      if (
+        allowTransientComponentDirOverrides &&
+        (k.startsWith('HAPPY_STACKS_COMPONENT_DIR_') || k.startsWith('HAPPY_LOCAL_COMPONENT_DIR_')) &&
+        (process.env[k] ?? '').trim()
+      ) {
+        continue;
+      }
       if (allowOverride || process.env[k] == null || process.env[k] === '') {
         process.env[k] = v;
       }
@@ -20,16 +39,29 @@ async function loadEnvFile(path, { override = false, overridePrefix = null } = {
   }
 }
 
+async function loadEnvFileIgnoringPrefixes(path, { ignorePrefixes = [] } = {}) {
+  try {
+    const contents = await readFile(path, 'utf-8');
+    const parsed = parseDotenv(contents);
+    for (const [k, v] of parsed.entries()) {
+      if (ignorePrefixes.some((p) => k.startsWith(p))) {
+        continue;
+      }
+      if (process.env[k] == null || process.env[k] === '') {
+        process.env[k] = v;
+      }
+    }
+  } catch {
+    // ignore missing/invalid env file
+  }
+}
+
 // Load happy-stacks env (optional). This is intentionally lightweight and does not require extra deps.
 // This file lives under scripts/utils/, so repo root is two directories up.
 const __utilsDir = dirname(fileURLToPath(import.meta.url));
 const __scriptsDir = dirname(__utilsDir);
 const __cliRootDir = dirname(__scriptsDir);
 
-function expandHome(p) {
-  return p.replace(/^~(?=\/)/, homedir());
-}
-
 function resolveHomeDir() {
   const fromEnv = (process.env.HAPPY_STACKS_HOME_DIR ?? '').trim();
   if (fromEnv) {
@@ -65,6 +97,17 @@ function applyStacksPrefixMapping() {
   }
 }
 
+// If HAPPY_STACKS_HOME_DIR isn't set, try the canonical pointer file at <canonicalHomeDir>/.env first.
+//
+// This allows installs where the "real" home/workspace/runtime are elsewhere, while still
+// giving us a stable discovery location for launchd/SwiftBar/minimal shells.
+const canonicalEnvPath = getCanonicalHomeEnvPathFromEnv(process.env);
+if (!(process.env.HAPPY_STACKS_HOME_DIR ?? '').trim() && existsSync(canonicalEnvPath)) {
+  await loadEnvFile(canonicalEnvPath, { override: false });
+  await loadEnvFile(canonicalEnvPath, { override: true, overridePrefix: 'HAPPY_STACKS_' });
+  await loadEnvFile(canonicalEnvPath, { override: true, overridePrefix: 'HAPPY_LOCAL_' });
+}
+
 const __homeDir = resolveHomeDir();
 process.env.HAPPY_STACKS_HOME_DIR = process.env.HAPPY_STACKS_HOME_DIR ?? __homeDir;
 
@@ -72,12 +115,15 @@ process.env.HAPPY_STACKS_HOME_DIR = process.env.HAPPY_STACKS_HOME_DIR ?? __homeD
 //   ~/.happy-stacks/.env
 //   ~/.happy-stacks/env.local
 //
-// Backwards compatible fallback for cloned-repo usage (when home config doesn't exist yet):
-//   <repo>/.env
-//   <repo>/env.local
+// Additionally: when running from a cloned repo, load <repo>/.env as a *fallback* even if home config exists.
+// This helps keep repo-local dev settings (e.g. custom Codex binaries) working without requiring users to
+// duplicate them into ~/.happy-stacks/env.local.
 const homeEnv = join(__homeDir, '.env');
 const homeLocal = join(__homeDir, 'env.local');
-const hasHomeConfig = existsSync(homeEnv) || existsSync(homeLocal);
+// In sandbox mode, never load repo env.local (it can contain "real" machine paths/URLs).
+// Treat sandbox runs as having home config even if the sandbox home env files don't exist yet.
+const hasHomeConfig = isSandboxed() || existsSync(homeEnv) || existsSync(homeLocal);
+const repoEnv = join(__cliRootDir, '.env');
 
 // 1) Load defaults first (lowest precedence)
 if (hasHomeConfig) {
@@ -90,6 +136,19 @@ if (hasHomeConfig) {
   await loadEnvFile(join(__cliRootDir, 'env.local'), { override: true, overridePrefix: 'HAPPY_STACKS_' });
 }
 
+// Repo-local fallback (dev convenience):
+// If the repo has a .env, load it without overriding anything already set by the environment or home config.
+// Note: we intentionally do NOT load repo env.local here, because env.local is treated as higher-precedence
+// overrides and could unexpectedly fight with stack/home configuration when present.
+if (hasHomeConfig) {
+  // IMPORTANT:
+  // When home config exists, do not let repo-local .env set HAPPY_STACKS_* / HAPPY_LOCAL_* keys.
+  // Otherwise a cloned repo's .env can accidentally leak global URLs/ports into every stack.
+  await loadEnvFileIgnoringPrefixes(repoEnv, { ignorePrefixes: ['HAPPY_STACKS_', 'HAPPY_LOCAL_'] });
+} else {
+  await loadEnvFile(repoEnv, { override: false });
+}
+
 // If no explicit env file is set, and we're on the default "main" stack, prefer the stack-scoped env file
 // if it exists: ~/.happy/stacks/main/env
 (() => {
@@ -99,22 +158,34 @@ if (hasHomeConfig) {
     return;
   }
   const stackName = (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').trim() || 'main';
-  if (stackName !== 'main') {
-    return;
-  }
-  const mainEnv = join(homedir(), '.happy', 'stacks', 'main', 'env');
-  if (!existsSync(mainEnv)) {
-    return;
-  }
-  process.env.HAPPY_STACKS_ENV_FILE = mainEnv;
-  process.env.HAPPY_LOCAL_ENV_FILE = mainEnv;
+  const stacksStorageRootRaw = (process.env.HAPPY_STACKS_STORAGE_DIR ?? process.env.HAPPY_LOCAL_STORAGE_DIR ?? '').trim();
+  const stacksStorageRoot = stacksStorageRootRaw ? expandHome(stacksStorageRootRaw) : join(homedir(), '.happy', 'stacks');
+  const allowLegacy = !isSandboxed() || sandboxAllowsGlobalSideEffects();
+  const legacyStacksRoot = allowLegacy ? join(homedir(), '.happy', 'local', 'stacks') : join(stacksStorageRoot, '__legacy_disabled__');
+
+  const candidates = [
+    join(stacksStorageRoot, stackName, 'env'),
+    join(legacyStacksRoot, stackName, 'env'),
+  ];
+  const envPath = candidates.find((p) => existsSync(p));
+  if (!envPath) return;
+
+  process.env.HAPPY_STACKS_ENV_FILE = envPath;
+  process.env.HAPPY_LOCAL_ENV_FILE = envPath;
 })();
-// 3) Load explicit env file overlay (stack env, or any caller-provided env file) last (highest precedence)
-if (process.env.HAPPY_STACKS_ENV_FILE?.trim()) {
-  await loadEnvFile(process.env.HAPPY_STACKS_ENV_FILE.trim(), { override: true, overridePrefix: 'HAPPY_STACKS_' });
-}
-if (process.env.HAPPY_LOCAL_ENV_FILE?.trim()) {
-  await loadEnvFile(process.env.HAPPY_LOCAL_ENV_FILE.trim(), { override: true, overridePrefix: 'HAPPY_LOCAL_' });
+// 3) Load explicit env file overlay (stack env, or any caller-provided env file) last (highest precedence).
+//
+// IMPORTANT:
+// Stack env files intentionally include some non-prefixed keys (e.g. DATABASE_URL, HAPPY_SERVER_LIGHT_DATA_DIR)
+// that must apply for true per-stack isolation. Do not filter by prefix here.
+{
+  const stacksEnv = process.env.HAPPY_STACKS_ENV_FILE?.trim() ? process.env.HAPPY_STACKS_ENV_FILE.trim() : '';
+  const localEnv = process.env.HAPPY_LOCAL_ENV_FILE?.trim() ? process.env.HAPPY_LOCAL_ENV_FILE.trim() : '';
+  const unique = Array.from(new Set([stacksEnv, localEnv].filter(Boolean)));
+  for (const p of unique) {
+    // eslint-disable-next-line no-await-in-loop
+    await loadEnvFile(p, { override: true });
+  }
 }
 
 // Make both prefixes available to the rest of the codebase.

package/scripts/utils/env_file.mjs

@@ -10,6 +10,17 @@ export async function ensureEnvFileUpdated({ envPath, updates }) {
   await writeFileIfChanged(envPath, applyEnvUpdates(await readText(envPath), updates), envPath);
 }
 
+export async function ensureEnvFilePruned({ envPath, removeKeys }) {
+  const keys = Array.from(new Set((removeKeys ?? []).map((k) => String(k).trim()).filter(Boolean)));
+  if (!keys.length) {
+    return;
+  }
+  await mkdir(dirname(envPath), { recursive: true });
+  const existing = await readText(envPath);
+  const next = pruneEnvKeys(existing, keys);
+  await writeFileIfChanged(existing, next, envPath);
+}
+
 async function readText(path) {
   try {
     return (await pathExists(path)) ? await readFile(path, 'utf-8') : '';
@@ -42,6 +53,31 @@ function applyEnvUpdates(existing, updates) {
   return next.join('\n');
 }
 
+function pruneEnvKeys(existing, removeKeys) {
+  const keys = new Set(removeKeys);
+  const lines = (existing ?? '').split('\n');
+  const kept = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      kept.push(line);
+      continue;
+    }
+    // Remove any "KEY=..." line for keys in removeKeys.
+    const eq = trimmed.indexOf('=');
+    if (eq <= 0) {
+      kept.push(line);
+      continue;
+    }
+    const key = trimmed.slice(0, eq).trim();
+    if (keys.has(key)) {
+      continue;
+    }
+    kept.push(line);
+  }
+  return kept.join('\n');
+}
+
 async function writeFileIfChanged(existingContent, nextContent, path) {
   const normalizedNext = nextContent.endsWith('\n') ? nextContent : nextContent + '\n';
   const normalizedExisting = existingContent.endsWith('\n') ? existingContent : existingContent + (existingContent ? '\n' : '');

package/scripts/utils/expo.mjs

@@ -0,0 +1,96 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+
+function hashDir(dir) {
+  return createHash('sha1').update(String(dir ?? '')).digest('hex').slice(0, 12);
+}
+
+export function getExpoStatePaths({ baseDir, kind, projectDir, stateFileName = 'expo.state.json' }) {
+  const key = hashDir(projectDir);
+  const stateDir = join(baseDir, kind, key);
+  return {
+    key,
+    stateDir,
+    statePath: join(stateDir, stateFileName),
+    expoHomeDir: join(stateDir, 'expo-home'),
+    tmpDir: join(stateDir, 'tmp'),
+  };
+}
+
+export async function ensureExpoIsolationEnv({ env, stateDir, expoHomeDir, tmpDir }) {
+  await mkdir(stateDir, { recursive: true });
+  await mkdir(expoHomeDir, { recursive: true });
+  await mkdir(tmpDir, { recursive: true });
+
+  // Expo CLI uses this to override ~/.expo.
+  // Always override: stack/worktree isolation must not fall back to the user's global ~/.expo.
+  env.__UNSAFE_EXPO_HOME_DIRECTORY = expoHomeDir;
+
+  // Metro default cache root is `path.join(os.tmpdir(), 'metro-cache')`, so TMPDIR isolates it.
+  // Always override: macOS sets TMPDIR by default, so a "set-if-missing" guard would not isolate Metro.
+  env.TMPDIR = tmpDir;
+}
+
+export function wantsExpoClearCache({ env }) {
+  const raw = (env.HAPPY_STACKS_EXPO_CLEAR_CACHE ?? env.HAPPY_LOCAL_EXPO_CLEAR_CACHE ?? '').trim();
+  if (raw) {
+    return raw !== '0';
+  }
+  // Default: clear cache when non-interactive (LLMs/services), keep fast iteration in TTY shells.
+  return !(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+export async function readPidState(statePath) {
+  try {
+    if (!existsSync(statePath)) return null;
+    const raw = await readFile(statePath, 'utf-8');
+    const state = JSON.parse(raw);
+    const pid = Number(state?.pid);
+    if (!Number.isFinite(pid) || pid <= 0) return null;
+    return state;
+  } catch {
+    return null;
+  }
+}
+
+export function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function isStateProcessRunning(statePath) {
+  const state = await readPidState(statePath);
+  if (!state) return { running: false, state: null };
+  const pid = Number(state.pid);
+  return { running: isPidAlive(pid), state };
+}
+
+export async function writePidState(statePath, state) {
+  await mkdir(dirname(statePath), { recursive: true }).catch(() => {});
+  await writeFile(statePath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+}
+
+export async function killPid(pid) {
+  const n = Number(pid);
+  if (!Number.isFinite(n) || n <= 1) return;
+  try {
+    process.kill(n, 'SIGTERM');
+  } catch {
+    return;
+  }
+  await delay(500);
+  try {
+    process.kill(n, 0);
+    process.kill(n, 'SIGKILL');
+  } catch {
+    // exited
+  }
+}
+

package/scripts/utils/handy_master_secret.mjs

@@ -0,0 +1,94 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { parseDotenv } from './dotenv.mjs';
+import { resolveStackEnvPath } from './paths.mjs';
+import { getLegacyHappyBaseDir, isLegacyAuthSourceName } from './auth_sources.mjs';
+
+async function readTextIfExists(path) {
+  try {
+    if (!path || !existsSync(path)) return null;
+    const raw = await readFile(path, 'utf-8');
+    const t = raw.trim();
+    return t ? t : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseEnvToObject(raw) {
+  const parsed = parseDotenv(raw ?? '');
+  return Object.fromEntries(parsed.entries());
+}
+
+function getEnvValue(env, key) {
+  const v = (env?.[key] ?? '').toString().trim();
+  return v || '';
+}
+
+function stackExistsSync(stackName) {
+  if (stackName === 'main') return true;
+  const envPath = resolveStackEnvPath(stackName).envPath;
+  return existsSync(envPath);
+}
+
+export async function resolveHandyMasterSecretFromStack({
+  stackName,
+  requireStackExists = false,
+  allowLegacyAuthSource = true,
+  allowLegacyMainFallback = true,
+} = {}) {
+  const name = String(stackName ?? '').trim() || 'main';
+
+  if (isLegacyAuthSourceName(name)) {
+    if (!allowLegacyAuthSource) {
+      throw new Error(
+        '[auth] legacy auth source is disabled in sandbox mode.\n' +
+          'Reason: it reads from ~/.happy (global user state).\n' +
+          'If you really want this, set: HAPPY_STACKS_SANDBOX_ALLOW_GLOBAL=1'
+      );
+    }
+    const baseDir = getLegacyHappyBaseDir();
+    const legacySecretPath = join(baseDir, 'server-light', 'handy-master-secret.txt');
+    const secret = await readTextIfExists(legacySecretPath);
+    return secret ? { secret, source: legacySecretPath } : { secret: null, source: null };
+  }
+
+  if (requireStackExists && !stackExistsSync(name)) {
+    throw new Error(`[auth] cannot copy auth: source stack "${name}" does not exist`);
+  }
+
+  const resolved = resolveStackEnvPath(name);
+  const sourceBaseDir = resolved.baseDir;
+  const sourceEnvPath = resolved.envPath;
+  const raw = await readTextIfExists(sourceEnvPath);
+  const env = raw ? parseEnvToObject(raw) : {};
+
+  const inline = getEnvValue(env, 'HANDY_MASTER_SECRET');
+  if (inline) {
+    return { secret: inline, source: `${sourceEnvPath} (HANDY_MASTER_SECRET)` };
+  }
+
+  const secretFile = getEnvValue(env, 'HAPPY_STACKS_HANDY_MASTER_SECRET_FILE');
+  if (secretFile) {
+    const secret = await readTextIfExists(secretFile);
+    if (secret) return { secret, source: secretFile };
+  }
+
+  const dataDir = getEnvValue(env, 'HAPPY_SERVER_LIGHT_DATA_DIR') || join(sourceBaseDir, 'server-light');
+  const secretPath = join(dataDir, 'handy-master-secret.txt');
+  const secret = await readTextIfExists(secretPath);
+  if (secret) return { secret, source: secretPath };
+
+  // Last-resort legacy: if main has never been migrated to stack dirs.
+  if (name === 'main' && allowLegacyMainFallback) {
+    const legacy = join(homedir(), '.happy', 'server-light', 'handy-master-secret.txt');
+    const legacySecret = await readTextIfExists(legacy);
+    if (legacySecret) return { secret: legacySecret, source: legacy };
+  }
+
+  return { secret: null, source: null };
+}
+