happy-stacks 0.2.0 → 0.4.0

package/scripts/edison.mjs

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

package/scripts/happy.mjs

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

package/scripts/init.mjs

@@ -4,19 +4,11 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
-import { ensureCanonicalHomeEnvUpdated, ensureHomeEnvUpdated } from './utils/config.mjs';
-import { parseDotenv } from './utils/dotenv.mjs';
-import { expandHome } from './utils/canonical_home.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
-
-async function readJsonIfExists(path) {
-  try {
-    const raw = await readFile(path, 'utf-8');
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
+import { ensureCanonicalHomeEnvUpdated, ensureHomeEnvUpdated } from './utils/env/config.mjs';
+import { parseDotenv } from './utils/env/dotenv.mjs';
+import { expandHome } from './utils/paths/canonical_home.mjs';
+import { readJsonIfExists } from './utils/fs/json.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
 
 function getCliRootDir() {
   return dirname(dirname(fileURLToPath(import.meta.url)));
@@ -207,7 +199,9 @@ async function main() {
   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;
+    // In sandbox mode, storage dir MUST be isolated and must override any pre-existing env.
+    process.env.HAPPY_STACKS_STORAGE_DIR = isSandboxed() ? storageDirOverride : (process.env.HAPPY_STACKS_STORAGE_DIR ?? storageDirOverride);
+    process.env.HAPPY_LOCAL_STORAGE_DIR = process.env.HAPPY_LOCAL_STORAGE_DIR ?? process.env.HAPPY_STACKS_STORAGE_DIR;
   }
 
   const cliRootDirRaw = parseArgValue(argv, 'cli-root-dir');

package/scripts/install.mjs

@@ -1,17 +1,17 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 import { parseArgs } from './utils/cli/args.mjs';
-import { pathExists } from './utils/fs.mjs';
-import { run } from './utils/proc.mjs';
-import { getComponentDir, getRootDir } from './utils/paths.mjs';
-import { getServerComponentName } from './utils/server.mjs';
-import { ensureCliBuilt, ensureDepsInstalled, ensureHappyCliLocalNpmLinked } from './utils/pm.mjs';
+import { pathExists } from './utils/fs/fs.mjs';
+import { run, runCapture } from './utils/proc/proc.mjs';
+import { getComponentDir, getRootDir } from './utils/paths/paths.mjs';
+import { getServerComponentName } from './utils/server/server.mjs';
+import { ensureCliBuilt, ensureDepsInstalled, ensureHappyCliLocalNpmLinked } from './utils/proc/pm.mjs';
 import { dirname, join } from 'node:path';
 import { mkdir } from 'node:fs/promises';
 import { installService, uninstallService } from './service.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
-import { ensureEnvLocalUpdated } from './utils/env_local.mjs';
+import { ensureEnvLocalUpdated } from './utils/env/env_local.mjs';
 import { isTty, prompt, promptSelect, withRl } from './utils/cli/wizard.mjs';
-import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs';
+import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/env/sandbox.mjs';
 
 /**
  * Install/setup the local stack:
@@ -24,8 +24,10 @@ import { isSandboxed, sandboxAllowsGlobalSideEffects } from './utils/sandbox.mjs
 
 const DEFAULT_FORK_REPOS = {
   serverLight: 'https://github.com/leeroybrun/happy-server-light.git',
-  // We don't currently maintain a separate fork for full happy-server; default to upstream.
-  serverFull: 'https://github.com/slopus/happy-server.git',
+  // Both server flavors live as branches in the same fork repo:
+  // - happy-server-light (sqlite)
+  // - happy-server (full)
+  serverFull: 'https://github.com/leeroybrun/happy-server-light.git',
   cli: 'https://github.com/leeroybrun/happy-cli.git',
   ui: 'https://github.com/leeroybrun/happy.git',
 };
@@ -44,7 +46,8 @@ function repoUrlsFromOwners({ forkOwner, upstreamOwner }) {
   return {
     forks: {
       serverLight: fork('happy-server-light'),
-      serverFull: fork('happy-server') /* best-effort; user can override */,
+      // Fork convention: server full is a branch in happy-server-light repo (not a separate repo).
+      serverFull: fork('happy-server-light'),
       cli: fork('happy-cli'),
       ui: fork('happy'),
     },
@@ -86,6 +89,51 @@ function getRepoUrls({ repoSource }) {
   };
 }
 
+async function ensureGitBranchCheckedOut({ repoDir, branch, label }) {
+  if (!(await pathExists(join(repoDir, '.git')))) return;
+  const b = String(branch ?? '').trim();
+  if (!b) return;
+
+  try {
+    const head = (await runCapture('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: repoDir })).trim();
+    if (head && head === b) return;
+  } catch {
+    // ignore
+  }
+
+  // Ensure branch exists locally, otherwise fetch it from origin.
+  let hasLocal = true;
+  try {
+    await run('git', ['show-ref', '--verify', '--quiet', `refs/heads/${b}`], { cwd: repoDir });
+  } catch {
+    hasLocal = false;
+  }
+  if (!hasLocal) {
+    try {
+      await run('git', ['fetch', '--quiet', 'origin', b], { cwd: repoDir });
+    } catch {
+      throw new Error(
+        `[local] ${label}: expected branch "${b}" to exist in ${repoDir}.\n` +
+          `[local] Fix: use --forks for happy-server-light (sqlite), or use --server=happy-server with --upstream.`
+      );
+    }
+  }
+
+  try {
+    await run('git', ['checkout', '-q', b], { cwd: repoDir });
+  } catch {
+    // If remote-tracking branch exists but local doesn't, create it.
+    try {
+      await run('git', ['checkout', '-q', '-B', b, `origin/${b}`], { cwd: repoDir });
+    } catch {
+      throw new Error(
+        `[local] ${label}: failed to checkout branch "${b}" in ${repoDir}.\n` +
+          `[local] Fix: re-run with --force in worktree flows, or delete the checkout and re-run install/bootstrap.`
+      );
+    }
+  }
+}
+
 async function ensureComponentPresent({ dir, label, repoUrl, allowClone }) {
   if (await pathExists(dir)) {
     return;
@@ -201,7 +249,22 @@ async function main() {
   if (wantsHelp(argv, { flags })) {
     printResult({
       json,
-      data: { flags: ['--forks', '--upstream', '--clone', '--no-clone', '--autostart', '--no-autostart', '--server=...'], json: true },
+      data: {
+        flags: [
+          '--forks',
+          '--upstream',
+          '--clone',
+          '--no-clone',
+          '--autostart',
+          '--no-autostart',
+          '--server=...',
+          '--no-ui-build',
+          '--no-ui-deps',
+          '--no-cli-deps',
+          '--no-cli-build',
+        ],
+        json: true,
+      },
       text: [
         '[bootstrap] usage:',
         '  happys bootstrap [--forks|--upstream] [--server=happy-server|happy-server-light|both] [--json]',
@@ -270,6 +333,17 @@ async function main() {
   const disableAutostart = flags.has('--no-autostart');
 
   const serverComponentName = (wizard?.serverComponentName ?? getServerComponentName({ kv })).trim();
+  // Safety: upstream server-light is not a separate upstream repo/branch today.
+  // Upstream slopus/happy-server is Postgres-only, while happy-server-light requires sqlite.
+  if (repoSource === 'upstream' && (serverComponentName === 'happy-server-light' || serverComponentName === 'both')) {
+    throw new Error(
+      `[bootstrap] --upstream is not supported for happy-server-light (sqlite).\n` +
+        `Reason: upstream ${DEFAULT_UPSTREAM_REPOS.serverLight} does not provide a happy-server-light branch.\n` +
+        `Fix:\n` +
+        `- use --forks (recommended), OR\n` +
+        `- use --server=happy-server with --upstream`
+    );
+  }
   const serverLightDir = getComponentDir(rootDir, 'happy-server-light');
   const serverFullDir = getComponentDir(rootDir, 'happy-server');
   const cliDir = getComponentDir(rootDir, 'happy-cli');
@@ -305,35 +379,57 @@ async function main() {
     allowClone,
   });
 
+  // Ensure expected branches are checked out for server flavors (avoids "server-light directory contains full server" mistakes).
+  if (serverComponentName === 'both' || serverComponentName === 'happy-server-light') {
+    await ensureGitBranchCheckedOut({ repoDir: serverLightDir, branch: 'happy-server-light', label: 'SERVER' });
+  }
+  if (serverComponentName === 'both' || serverComponentName === 'happy-server') {
+    // In fork mode, full server is a branch in the fork server repo. In upstream mode, use upstream main.
+    const serverFullBranch = repoSource === 'upstream' ? 'main' : 'happy-server';
+    await ensureGitBranchCheckedOut({ repoDir: serverFullDir, branch: serverFullBranch, label: 'SERVER_FULL' });
+  }
+
   const cliDirFinal = cliDir;
   const uiDirFinal = uiDir;
 
   // Install deps
+  const skipUiDeps = flags.has('--no-ui-deps') || (process.env.HAPPY_STACKS_INSTALL_NO_UI_DEPS ?? '').trim() === '1';
+  const skipCliDeps = flags.has('--no-cli-deps') || (process.env.HAPPY_STACKS_INSTALL_NO_CLI_DEPS ?? '').trim() === '1';
   if (serverComponentName === 'both' || serverComponentName === 'happy-server-light') {
     await ensureDepsInstalled(serverLightDir, 'happy-server-light');
   }
   if (serverComponentName === 'both' || serverComponentName === 'happy-server') {
     await ensureDepsInstalled(serverFullDir, 'happy-server');
   }
-  await ensureDepsInstalled(uiDirFinal, 'happy');
-  await ensureDepsInstalled(cliDirFinal, 'happy-cli');
+  if (!skipUiDeps) {
+    await ensureDepsInstalled(uiDirFinal, 'happy');
+  }
+  if (!skipCliDeps) {
+    await ensureDepsInstalled(cliDirFinal, 'happy-cli');
+  }
 
   // CLI build + link
-  const buildCli = (process.env.HAPPY_LOCAL_CLI_BUILD ?? '1') !== '0';
-  const npmLinkCli = (process.env.HAPPY_LOCAL_NPM_LINK ?? '1') !== '0';
-  await ensureCliBuilt(cliDirFinal, { buildCli });
-  await ensureHappyCliLocalNpmLinked(rootDir, { npmLinkCli });
+  const skipCliBuild = flags.has('--no-cli-build') || (process.env.HAPPY_STACKS_INSTALL_NO_CLI_BUILD ?? '').trim() === '1';
+  if (!skipCliBuild) {
+    const buildCli = (process.env.HAPPY_LOCAL_CLI_BUILD ?? '1') !== '0';
+    const npmLinkCli = (process.env.HAPPY_LOCAL_NPM_LINK ?? '1') !== '0';
+    await ensureCliBuilt(cliDirFinal, { buildCli });
+    await ensureHappyCliLocalNpmLinked(rootDir, { npmLinkCli });
+  }
 
   // Build UI (so run works without expo dev server)
+  const skipUiBuild = flags.has('--no-ui-build') || (process.env.HAPPY_STACKS_INSTALL_NO_UI_BUILD ?? '').trim() === '1';
   const buildArgs = [join(rootDir, 'scripts', 'build.mjs')];
   // Tauri builds are opt-in (slow + requires additional toolchain).
   const buildTauri = wizard?.buildTauri ?? (flags.has('--tauri') && !flags.has('--no-tauri'));
-  if (buildTauri) {
-    buildArgs.push('--tauri');
-  } else if (flags.has('--no-tauri')) {
-    buildArgs.push('--no-tauri');
+  if (!skipUiBuild) {
+    if (buildTauri) {
+      buildArgs.push('--tauri');
+    } else if (flags.has('--no-tauri')) {
+      buildArgs.push('--no-tauri');
+    }
+    await run(process.execPath, buildArgs, { cwd: rootDir });
   }
-  await run(process.execPath, buildArgs, { cwd: rootDir });
 
   // Optional autostart (macOS)
   if (disableAutostart) {