happy-stacks 0.4.0 → 0.5.0

package/scripts/stack.mjs

@@ -1,7 +1,7 @@
 import './utils/env/env.mjs';
 import { spawn } from 'node:child_process';
-import { chmod, copyFile, mkdir, open, readFile, readdir, writeFile } from 'node:fs/promises';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { chmod, copyFile, mkdir, open, readFile, readdir, rename, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { existsSync } from 'node:fs';
 // NOTE: random bytes usage centralized in scripts/utils/crypto/tokens.mjs
 import { homedir } from 'node:os';
@@ -11,12 +11,14 @@ import { parseArgs } from './utils/cli/args.mjs';
 import { killProcessTree, run, runCapture } from './utils/proc/proc.mjs';
 import {
   componentDirEnvKey,
+  coerceHappyMonorepoRootFromPath,
   getComponentDir,
   getComponentsDir,
   getHappyStacksHomeDir,
   getLegacyStorageRoot,
   getRootDir,
   getStacksStorageRoot,
+  happyMonorepoSubdirForComponent,
   resolveStackEnvPath,
 } from './utils/paths/paths.mjs';
 import { isTcpPortFree, listListenPids, pickNextFreeTcpPort } from './utils/net/ports.mjs';
@@ -28,7 +30,7 @@ import {
   resolveComponentSpecToDir,
   worktreeSpecFromDir,
 } from './utils/git/worktrees.mjs';
-import { isTty, prompt, promptWorktreeSource, withRl } from './utils/cli/wizard.mjs';
+import { isTty, prompt, promptSelect, withRl } from './utils/cli/wizard.mjs';
 import { parseEnvToObject } from './utils/env/dotenv.mjs';
 import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 import { ensureEnvFilePruned, ensureEnvFileUpdated } from './utils/env/env_file.mjs';
@@ -66,6 +68,7 @@ import { sanitizeSlugPart } from './utils/git/refs.mjs';
 import { isCursorInstalled, openWorkspaceInEditor, writeStackCodeWorkspace } from './utils/stack/editor_workspace.mjs';
 import { readLastLines } from './utils/fs/tail.mjs';
 import { defaultStackReleaseIdentity } from './utils/mobile/identifiers.mjs';
+import { interactiveEdit, interactiveNew } from './utils/stack/interactive_stack_config.mjs';
 
 function stackNameFromArg(positionals, idx) {
   const name = positionals[idx]?.trim() ? positionals[idx].trim() : '';
@@ -242,18 +245,48 @@ function stringifyEnv(env) {
 const readExistingEnv = readTextOrEmpty;
 
 function resolveDefaultComponentDirs({ rootDir }) {
-  const componentNames = ['happy', 'happy-cli', 'happy-server-light', 'happy-server'];
-  const out = {};
-  for (const name of componentNames) {
+  function hasUnifiedLightSchema(serverDir) {
+    return (
+      existsSync(join(serverDir, 'prisma', 'schema.sqlite.prisma')) ||
+      existsSync(join(serverDir, 'prisma', 'sqlite', 'schema.prisma'))
+    );
+  }
+
+  function pickDefaultDir(name) {
     const embedded = join(rootDir, 'components', name);
     const workspace = join(getComponentsDir(rootDir), name);
     // CRITICAL:
     // In sandbox mode, never point stacks at the repo's embedded `components/*` checkouts.
     // Sandboxes must use the sandbox workspace clones (HAPPY_STACKS_WORKSPACE_DIR/components/*),
     // otherwise worktrees/branches collide with the user's real machine state.
-    const dir = !isSandboxed() && existsSync(embedded) ? embedded : workspace;
-    out[`HAPPY_STACKS_COMPONENT_DIR_${name.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`] = dir;
+    return !isSandboxed() && existsSync(embedded) ? embedded : workspace;
   }
+
+  const out = {};
+
+  const happyRoot = pickDefaultDir('happy');
+  const monoRoot = existsSync(happyRoot) ? coerceHappyMonorepoRootFromPath(happyRoot) : null;
+
+  if (monoRoot) {
+    const subdir = (component) => happyMonorepoSubdirForComponent(component);
+    out.HAPPY_STACKS_COMPONENT_DIR_HAPPY = join(monoRoot, subdir('happy'));
+    out.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = join(monoRoot, subdir('happy-cli'));
+    const serverDir = join(monoRoot, subdir('happy-server'));
+    out.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = serverDir;
+    out.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT = hasUnifiedLightSchema(serverDir)
+      ? serverDir
+      : pickDefaultDir('happy-server-light');
+    return out;
+  }
+
+  // Prefer a single unified happy-server checkout for both flavors when it includes sqlite support.
+  const fullServerDir = pickDefaultDir('happy-server');
+  const hasUnifiedLight = hasUnifiedLightSchema(fullServerDir);
+
+  out.HAPPY_STACKS_COMPONENT_DIR_HAPPY = pickDefaultDir('happy');
+  out.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = pickDefaultDir('happy-cli');
+  out.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = fullServerDir;
+  out.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT = hasUnifiedLight ? fullServerDir : pickDefaultDir('happy-server-light');
   return out;
 }
 
@@ -401,110 +434,6 @@ async function withStackEnv({ stackName, fn, extraEnv = {} }) {
   return await fn({ env, envPath, stackEnv, runtimeStatePath, runtimeState });
 }
 
-async function interactiveNew({ rootDir, rl, defaults }) {
-  const out = { ...defaults };
-
-  if (!out.stackName) {
-    out.stackName = (await rl.question('Stack name: ')).trim();
-  }
-  if (!out.stackName) {
-    throw new Error('[stack] stack name is required');
-  }
-  if (out.stackName === 'main') {
-    throw new Error('[stack] stack name \"main\" is reserved (use the default stack without creating it)');
-  }
-
-  // Server component selection
-  if (!out.serverComponent) {
-    const server = (await rl.question('Server component [happy-server-light|happy-server] (default: happy-server-light): ')).trim();
-    out.serverComponent = server || 'happy-server-light';
-  }
-
-  // Port
-  if (!out.port) {
-    const want = (await rl.question('Port (empty = ephemeral): ')).trim();
-    out.port = want ? Number(want) : null;
-  }
-
-  // Remote for creating new worktrees (used by all "create new worktree" choices)
-  if (!out.createRemote) {
-    out.createRemote = await prompt(rl, 'Git remote for creating new worktrees (default: upstream): ', { defaultValue: 'upstream' });
-  }
-
-  // Component selections
-  for (const c of ['happy', 'happy-cli']) {
-    if (out.components[c] != null) continue;
-    out.components[c] = await promptWorktreeSource({
-      rl,
-      rootDir,
-      component: c,
-      stackName: out.stackName,
-      createRemote: out.createRemote,
-    });
-  }
-
-  // Server worktree selection (optional; only for the chosen server component)
-  const serverComponent = out.serverComponent === 'happy-server' ? 'happy-server' : 'happy-server-light';
-  if (out.components[serverComponent] == null) {
-    out.components[serverComponent] = await promptWorktreeSource({
-      rl,
-      rootDir,
-      component: serverComponent,
-      stackName: out.stackName,
-      createRemote: out.createRemote,
-    });
-  }
-
-  return out;
-}
-
-async function interactiveEdit({ rootDir, rl, stackName, existingEnv, defaults }) {
-  const out = { ...defaults, stackName };
-
-  // Server component selection
-  const currentServer = existingEnv.HAPPY_STACKS_SERVER_COMPONENT ?? existingEnv.HAPPY_LOCAL_SERVER_COMPONENT ?? '';
-  const server = await prompt(
-    rl,
-    `Server component [happy-server-light|happy-server] (default: ${currentServer || 'happy-server-light'}): `,
-    { defaultValue: currentServer || 'happy-server-light' }
-  );
-  out.serverComponent = server || 'happy-server-light';
-
-  // Port
-  const currentPort = existingEnv.HAPPY_STACKS_SERVER_PORT ?? existingEnv.HAPPY_LOCAL_SERVER_PORT ?? '';
-  const wantPort = await prompt(rl, `Port (empty = keep ${currentPort || 'ephemeral'}; type 'ephemeral' to unpin): `, { defaultValue: '' });
-  const wantTrimmed = wantPort.trim().toLowerCase();
-  out.port = wantTrimmed === 'ephemeral' ? null : wantPort ? Number(wantPort) : (currentPort ? Number(currentPort) : null);
-
-  // Remote for creating new worktrees
-  const currentRemote = existingEnv.HAPPY_STACKS_STACK_REMOTE ?? existingEnv.HAPPY_LOCAL_STACK_REMOTE ?? '';
-  out.createRemote = await prompt(rl, `Git remote for creating new worktrees (default: ${currentRemote || 'upstream'}): `, {
-    defaultValue: currentRemote || 'upstream',
-  });
-
-  // Worktree selections
-  for (const c of ['happy', 'happy-cli']) {
-    out.components[c] = await promptWorktreeSource({
-      rl,
-      rootDir,
-      component: c,
-      stackName,
-      createRemote: out.createRemote,
-    });
-  }
-
-  const serverComponent = out.serverComponent === 'happy-server' ? 'happy-server' : 'happy-server-light';
-  out.components[serverComponent] = await promptWorktreeSource({
-    rl,
-    rootDir,
-    component: serverComponent,
-    stackName,
-    createRemote: out.createRemote,
-  });
-
-  return out;
-}
-
 async function cmdNew({ rootDir, argv, emit = true }) {
   const { flags, kv } = parseArgs(argv);
   const positionals = argv.filter((a) => !a.startsWith('--'));
@@ -551,7 +480,7 @@ async function cmdNew({ rootDir, argv, emit = true }) {
   if (!stackName) {
     throw new Error(
       '[stack] usage: happys stack new <name> [--port=NNN] [--server=happy-server|happy-server-light] ' +
-        '[--happy=default|<owner/...>|<path>] [--happy-cli=...] [--happy-server=...] [--happy-server-light=...] ' +
+        '[--happy=default|<owner/...>|<path>] [--happy-server-light=...] ' +
         '[--copy-auth-from=<stack|legacy>] [--link-auth] [--no-copy-auth] [--interactive] [--force-port]'
     );
   }
@@ -672,24 +601,88 @@ async function cmdNew({ rootDir, argv, emit = true }) {
     }
   }
 
-  // happy
-  const happySpec = config.components.happy;
-  if (happySpec && typeof happySpec === 'object' && happySpec.create) {
-    const dir = await createWorktree({ rootDir, component: 'happy', slug: happySpec.slug, remoteName: happySpec.remote || 'upstream' });
-    stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY = dir;
-  } else {
-    const dir = resolveComponentSpecToDir({ rootDir, component: 'happy', spec: happySpec });
-    if (dir) stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY = resolve(rootDir, dir);
+  let monorepoPinned = false;
+
+  // happy / happy-cli / happy-server can be a single monorepo (slopus/happy).
+  // Detect monorepo pinning by resolving the provided spec(s), rather than relying on the local default checkout.
+  const monoSpecs = [
+    { component: 'happy', spec: config.components.happy },
+    { component: 'happy-cli', spec: config.components['happy-cli'] },
+    { component: 'happy-server', spec: config.components['happy-server'] },
+  ].filter((x) => x.spec);
+
+  if (monoSpecs.length) {
+    const primary = monoSpecs[0];
+    const canon = (spec) => {
+      if (spec && typeof spec === 'object' && spec.create) {
+        const remote = String(spec.remote || 'upstream');
+        return `create:${String(spec.slug)}@${remote}`;
+      }
+      return String(spec);
+    };
+
+    let resolvedDir = '';
+    if (primary.spec && typeof primary.spec === 'object' && primary.spec.create) {
+      resolvedDir = await createWorktree({
+        rootDir,
+        component: primary.component,
+        slug: primary.spec.slug,
+        remoteName: primary.spec.remote || 'upstream',
+      });
+    } else {
+      const dir = resolveComponentSpecToDir({ rootDir, component: primary.component, spec: primary.spec });
+      if (dir) resolvedDir = resolve(rootDir, dir);
+    }
+
+    const monoRoot = resolvedDir ? coerceHappyMonorepoRootFromPath(resolvedDir) : null;
+    if (monoRoot) {
+      for (const s of monoSpecs.slice(1)) {
+        if (canon(s.spec) !== canon(primary.spec)) {
+          throw new Error(
+            `[stack] conflicting monorepo component specs.\n` +
+              `- happy: ${canon(config.components.happy)}\n` +
+              `- happy-cli: ${canon(config.components['happy-cli'])}\n` +
+              `- happy-server: ${canon(config.components['happy-server'])}\n` +
+              `Fix: in monorepo mode, pass only one of --happy/--happy-cli/--happy-server (or pass the same value for all).`
+          );
+        }
+      }
+
+      const subdir = (c) => happyMonorepoSubdirForComponent(c);
+      stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY = join(monoRoot, subdir('happy'));
+      stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = join(monoRoot, subdir('happy-cli'));
+      const serverDir = join(monoRoot, subdir('happy-server'));
+      stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = serverDir;
+      if (
+        existsSync(join(serverDir, 'prisma', 'schema.sqlite.prisma')) ||
+        existsSync(join(serverDir, 'prisma', 'sqlite', 'schema.prisma'))
+      ) {
+        stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT = serverDir;
+      }
+      monorepoPinned = true;
+    }
   }
 
-  // happy-cli
-  const cliSpec = config.components['happy-cli'];
-  if (cliSpec && typeof cliSpec === 'object' && cliSpec.create) {
-    const dir = await createWorktree({ rootDir, component: 'happy-cli', slug: cliSpec.slug, remoteName: cliSpec.remote || 'upstream' });
-    stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = dir;
-  } else {
-    const dir = resolveComponentSpecToDir({ rootDir, component: 'happy-cli', spec: cliSpec });
-    if (dir) stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = resolve(rootDir, dir);
+  if (!monorepoPinned) {
+    // happy
+    const happySpec = config.components.happy;
+    if (happySpec && typeof happySpec === 'object' && happySpec.create) {
+      const dir = await createWorktree({ rootDir, component: 'happy', slug: happySpec.slug, remoteName: happySpec.remote || 'upstream' });
+      stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY = dir;
+    } else {
+      const dir = resolveComponentSpecToDir({ rootDir, component: 'happy', spec: happySpec });
+      if (dir) stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY = resolve(rootDir, dir);
+    }
+
+    // happy-cli
+    const cliSpec = config.components['happy-cli'];
+    if (cliSpec && typeof cliSpec === 'object' && cliSpec.create) {
+      const dir = await createWorktree({ rootDir, component: 'happy-cli', slug: cliSpec.slug, remoteName: cliSpec.remote || 'upstream' });
+      stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = dir;
+    } else {
+      const dir = resolveComponentSpecToDir({ rootDir, component: 'happy-cli', spec: cliSpec });
+      if (dir) stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = resolve(rootDir, dir);
+    }
   }
 
   // Server component directory override (optional)
@@ -708,13 +701,15 @@ async function cmdNew({ rootDir, argv, emit = true }) {
       if (dir) stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT = resolve(rootDir, dir);
     }
   } else if (serverComponent === 'happy-server') {
-    const spec = config.components['happy-server'];
-    if (spec && typeof spec === 'object' && spec.create) {
-      const dir = await createWorktree({ rootDir, component: 'happy-server', slug: spec.slug, remoteName: spec.remote || 'upstream' });
-      stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = dir;
-    } else {
-      const dir = resolveComponentSpecToDir({ rootDir, component: 'happy-server', spec });
-      if (dir) stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = resolve(rootDir, dir);
+    if (!monorepoPinned) {
+      const spec = config.components['happy-server'];
+      if (spec && typeof spec === 'object' && spec.create) {
+        const dir = await createWorktree({ rootDir, component: 'happy-server', slug: spec.slug, remoteName: spec.remote || 'upstream' });
+        stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = dir;
+      } else {
+        const dir = resolveComponentSpecToDir({ rootDir, component: 'happy-server', spec });
+        if (dir) stackEnv.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = resolve(rootDir, dir);
+      }
     }
   }
 
@@ -896,11 +891,83 @@ async function cmdEdit({ rootDir, argv }) {
     }
   };
 
-  await applyComponent('happy', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY', config.components.happy);
-  await applyComponent('happy-cli', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI', config.components['happy-cli']);
-  if (serverComponent === 'happy-server') {
-    await applyComponent('happy-server', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER', config.components['happy-server']);
+  const existingHappy = String(next.HAPPY_STACKS_COMPONENT_DIR_HAPPY ?? '').trim();
+  const happyMonorepo = Boolean(coerceHappyMonorepoRootFromPath(existingHappy)) || Boolean(coerceHappyMonorepoRootFromPath(getComponentDir(rootDir, 'happy', process.env)));
+
+  if (happyMonorepo) {
+    const monoSpecs = [
+      { component: 'happy', spec: config.components.happy },
+      { component: 'happy-cli', spec: config.components['happy-cli'] },
+      { component: 'happy-server', spec: config.components['happy-server'] },
+    ].filter((x) => x.spec);
+
+    if (monoSpecs.length) {
+      const primary = monoSpecs[0];
+      const canon = (spec) => {
+        if (spec && typeof spec === 'object' && spec.create) {
+          const remote = String(spec.remote || 'upstream');
+          return `create:${String(spec.slug)}@${remote}`;
+        }
+        return String(spec);
+      };
+
+      let resolvedDir = '';
+      if (primary.spec && typeof primary.spec === 'object' && primary.spec.create) {
+        resolvedDir = await createWorktree({
+          rootDir,
+          component: primary.component,
+          slug: primary.spec.slug,
+          remoteName: primary.spec.remote || next.HAPPY_STACKS_STACK_REMOTE,
+        });
+      } else {
+        const dir = resolveComponentSpecToDir({ rootDir, component: primary.component, spec: primary.spec });
+        if (dir) resolvedDir = resolve(rootDir, dir);
+      }
+
+      const monoRoot = resolvedDir ? coerceHappyMonorepoRootFromPath(resolvedDir) : null;
+      if (monoRoot) {
+        for (const s of monoSpecs.slice(1)) {
+          if (canon(s.spec) !== canon(primary.spec)) {
+            throw new Error(
+              `[stack] edit: conflicting monorepo component specs.\n` +
+                `- happy: ${canon(config.components.happy)}\n` +
+                `- happy-cli: ${canon(config.components['happy-cli'])}\n` +
+                `- happy-server: ${canon(config.components['happy-server'])}\n` +
+                `Fix: in monorepo mode, pass only one of --happy/--happy-cli/--happy-server (or pass the same value for all).`
+            );
+          }
+        }
+
+        const subdir = (c) => happyMonorepoSubdirForComponent(c);
+        next.HAPPY_STACKS_COMPONENT_DIR_HAPPY = join(monoRoot, subdir('happy'));
+        next.HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI = join(monoRoot, subdir('happy-cli'));
+        const serverDir = join(monoRoot, subdir('happy-server'));
+        next.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER = serverDir;
+        if (
+          existsSync(join(serverDir, 'prisma', 'schema.sqlite.prisma')) ||
+          existsSync(join(serverDir, 'prisma', 'sqlite', 'schema.prisma'))
+        ) {
+          next.HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT = serverDir;
+        }
+      } else {
+        await applyComponent('happy', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY', config.components.happy);
+        await applyComponent('happy-cli', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI', config.components['happy-cli']);
+        await applyComponent('happy-server', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER', config.components['happy-server']);
+      }
+    } else {
+      await applyComponent('happy', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY', config.components.happy);
+      await applyComponent('happy-cli', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI', config.components['happy-cli']);
+      await applyComponent('happy-server', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER', config.components['happy-server']);
+    }
   } else {
+    await applyComponent('happy', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY', config.components.happy);
+    await applyComponent('happy-cli', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI', config.components['happy-cli']);
+    if (serverComponent === 'happy-server') {
+      await applyComponent('happy-server', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER', config.components['happy-server']);
+    }
+  }
+
+  if (serverComponent === 'happy-server-light') {
     await applyComponent('happy-server-light', 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT', config.components['happy-server-light']);
   }
 
@@ -1448,7 +1515,21 @@ async function cmdWt({ rootDir, stackName, args }) {
   // Forward to scripts/worktrees.mjs under the stack env.
   // This makes `happys stack wt <name> -- ...` behave exactly like `happys wt ...`,
   // but read/write the stack env file (HAPPY_STACKS_ENV_FILE / legacy: HAPPY_LOCAL_ENV_FILE) instead of repo env.local.
-  const forwarded = args[0] === '--' ? args.slice(1) : args;
+  let forwarded = args[0] === '--' ? args.slice(1) : args;
+
+  // Stack users usually want to see what *this stack* is using (active checkout),
+  // not an exhaustive enumeration of every worktree on disk.
+  //
+  // `happys wt list` defaults to showing all worktrees. In stack mode, default to
+  // an active-only view unless the caller opts into `--all`.
+  if (forwarded[0] === 'list') {
+    const wantsAll = forwarded.includes('--all') || forwarded.includes('--all-worktrees');
+    const wantsActive = forwarded.includes('--active') || forwarded.includes('--active-only');
+    if (!wantsAll && !wantsActive) {
+      forwarded = [...forwarded, '--active'];
+    }
+  }
+
   await withStackEnv({
     stackName,
     fn: async ({ env }) => {
@@ -2310,6 +2391,150 @@ async function readStackEnvObject(stackName) {
   return { envPath, env };
 }
 
+function getTodayYmd() {
+  const now = new Date();
+  const y = String(now.getFullYear());
+  const m = String(now.getMonth() + 1).padStart(2, '0');
+  const d = String(now.getDate()).padStart(2, '0');
+  return `${y}-${m}-${d}`;
+}
+
+async function cmdArchiveStack({ rootDir, argv, stackName }) {
+  const { flags, kv } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+  const dryRun = flags.has('--dry-run');
+  const date = (kv.get('--date') ?? '').toString().trim() || getTodayYmd();
+
+  if (!stackExistsSync(stackName)) {
+    throw new Error(`[stack] archive: stack does not exist: ${stackName}`);
+  }
+
+  const { env } = await readStackEnvObject(stackName);
+  const serverComponent = parseServerComponentFromEnv(env);
+  const components = ['happy', 'happy-cli', 'happy-server-light', 'happy-server'];
+
+  const componentsDir = getComponentsDir(rootDir);
+  const workspaceDir = dirname(componentsDir);
+  const worktreesRoot = join(componentsDir, '.worktrees');
+
+  // Collect unique git worktree roots referenced by this stack.
+  const byRoot = new Map();
+  for (const component of components) {
+    const key = envKeyForComponentDir({ serverComponent, component });
+    const legacyKey = key.replace('HAPPY_STACKS_', 'HAPPY_LOCAL_');
+    const raw = (env[key] ?? env[legacyKey] ?? '').toString().trim();
+    if (!raw) continue;
+    const abs = isAbsolute(raw) ? raw : resolve(workspaceDir, raw);
+    // Only archive paths that live under components/.worktrees/.
+    const rel = relative(worktreesRoot, abs);
+    if (!rel || rel.startsWith('..') || isAbsolute(rel)) continue;
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const top = (await runCapture('git', ['rev-parse', '--show-toplevel'], { cwd: abs })).trim();
+      if (!top) continue;
+      if (!byRoot.has(top)) {
+        byRoot.set(top, { component, dir: top });
+      }
+    } catch {
+      // ignore invalid git dirs
+    }
+  }
+
+  const { baseDir } = resolveStackEnvPath(stackName);
+  const destStackDir = join(dirname(baseDir), '.archived', date, stackName);
+
+  // Safety: avoid archiving a worktree that is still actively referenced by other stacks.
+  // If we did, we'd break those stacks by moving their active checkout.
+  if (!dryRun && byRoot.size) {
+    const otherStacks = new Map(); // envPath -> Set(keys)
+    const otherNames = new Set();
+
+    for (const wt of byRoot.values()) {
+      // eslint-disable-next-line no-await-in-loop
+      const out = await runCapture(
+        process.execPath,
+        [join(rootDir, 'scripts', 'worktrees.mjs'), 'archive', wt.component, wt.dir, '--dry-run', `--date=${date}`, '--json'],
+        { cwd: rootDir, env: process.env }
+      );
+      const info = JSON.parse(out);
+      const linked = Array.isArray(info.linkedStacks) ? info.linkedStacks : [];
+      for (const s of linked) {
+        if (!s?.name || s.name === stackName) continue;
+        otherNames.add(s.name);
+        const envPath = String(s.envPath ?? '').trim();
+        if (!envPath) continue;
+        const set = otherStacks.get(envPath) ?? new Set();
+        for (const k of Array.isArray(s.keys) ? s.keys : []) {
+          if (k) set.add(String(k));
+        }
+        otherStacks.set(envPath, set);
+      }
+    }
+
+    if (otherNames.size) {
+      const names = Array.from(otherNames).sort().join(', ');
+      if (json || !isTty()) {
+        throw new Error(`[stack] archive: worktree(s) are still referenced by other stacks: ${names}. Resolve first (detach or archive those stacks).`);
+      }
+
+      const action = await withRl(async (rl) => {
+        return await promptSelect(rl, {
+          title: `Worktree(s) referenced by "${stackName}" are still in use by other stacks: ${names}`,
+          options: [
+            { label: 'abort (recommended)', value: 'abort' },
+            { label: 'detach those stacks from the shared worktree(s)', value: 'detach' },
+            { label: 'archive the linked stacks as well', value: 'archive-stacks' },
+          ],
+          defaultIndex: 0,
+        });
+      });
+
+      if (action === 'abort') {
+        throw new Error('[stack] archive aborted');
+      }
+      if (action === 'archive-stacks') {
+        for (const name of Array.from(otherNames).sort()) {
+          // eslint-disable-next-line no-await-in-loop
+          await run(process.execPath, [join(rootDir, 'scripts', 'stack.mjs'), 'archive', name, `--date=${date}`], { cwd: rootDir, env: process.env });
+        }
+      } else {
+        for (const [envPath, keys] of otherStacks.entries()) {
+          // eslint-disable-next-line no-await-in-loop
+          await ensureEnvFilePruned({ envPath, removeKeys: Array.from(keys) });
+        }
+      }
+    }
+  }
+
+  if (dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      stackName,
+      date,
+      stackBaseDir: baseDir,
+      archivedStackDir: destStackDir,
+      worktrees: Array.from(byRoot.values()),
+    };
+  }
+
+  await mkdir(dirname(destStackDir), { recursive: true });
+  await rename(baseDir, destStackDir);
+
+  const archivedWorktrees = [];
+  for (const wt of byRoot.values()) {
+    if (!existsSync(wt.dir)) continue;
+    // eslint-disable-next-line no-await-in-loop
+    const out = await runCapture(process.execPath, [join(rootDir, 'scripts', 'worktrees.mjs'), 'archive', wt.component, wt.dir, `--date=${date}`, '--json'], {
+      cwd: rootDir,
+      env: process.env,
+    });
+    archivedWorktrees.push(JSON.parse(out));
+  }
+
+  return { ok: true, dryRun: false, stackName, date, archivedStackDir: destStackDir, archivedWorktrees };
+}
+
 function envKeyForComponentDir({ serverComponent, component }) {
   if (component === 'happy') return 'HAPPY_STACKS_COMPONENT_DIR_HAPPY';
   if (component === 'happy-cli') return 'HAPPY_STACKS_COMPONENT_DIR_HAPPY_CLI';
@@ -2470,26 +2695,26 @@ async function cmdPrStack({ rootDir, argv }) {
       json,
       data: {
         usage:
-          'happys stack pr <name> --happy=<pr-url|number> [--happy-cli=<pr-url|number>] [--happy-server=<pr-url|number>|--happy-server-light=<pr-url|number>] [--server=happy-server|happy-server-light] [--remote=upstream] [--deps=none|link|install|link-or-install] [--seed-auth] [--copy-auth-from=<stack>] [--with-infra] [--auth-force] [--dev|--start] [--background] [--mobile] [--json] [-- <stack dev/start args...>]',
+          'happys stack pr <name> --happy=<pr-url|number> [--happy-server-light=<pr-url|number>] [--server=happy-server|happy-server-light] [--remote=upstream] [--deps=none|link|install|link-or-install] [--seed-auth] [--copy-auth-from=<stack>] [--with-infra] [--auth-force] [--dev|--start] [--background] [--mobile] [--expo-tailscale] [--json] [-- <stack dev/start args...>]',
       },
       text: [
         '[stack] usage:',
-        '  happys stack pr <name> --happy=<pr-url|number> [--happy-cli=<pr-url|number>] [--dev|--start]',
+        '  happys stack pr <name> --happy=<pr-url|number> [--happy-server-light=<pr-url|number>] [--dev|--start]',
         '    [--seed-auth] [--copy-auth-from=<stack>] [--link-auth] [--with-infra] [--auth-force]',
         '    [--remote=upstream] [--deps=none|link|install|link-or-install] [--update] [--force] [--background]',
-        '    [--mobile]   # also start Expo dev-client Metro for mobile',
+        '    [--mobile]         # also start Expo dev-client Metro for mobile',
+        '    [--expo-tailscale] # forward Expo to Tailscale interface for remote access',
         '    [--json] [-- <stack dev/start args...>]',
         '',
         'examples:',
         '  # Create stack + check out PRs + start dev UI',
         '  happys stack pr pr123 \\',
         '    --happy=https://github.com/slopus/happy/pull/123 \\',
-        '    --happy-cli=https://github.com/slopus/happy-cli/pull/456 \\',
         '    --seed-auth --copy-auth-from=dev-auth \\',
         '    --dev',
         '',
         '  # Use numeric PR refs (remote defaults to upstream)',
-        '  happys stack pr pr123 --happy=123 --happy-cli=456 --seed-auth --copy-auth-from=dev-auth --dev',
+        '  happys stack pr pr123 --happy=123 --seed-auth --copy-auth-from=dev-auth --dev',
         '',
         '  # Reuse an existing non-stacks Happy install for auth seeding',
         '  (deprecated) legacy ~/.happy is not supported for reliable seeding',
@@ -2537,6 +2762,22 @@ async function cmdPrStack({ rootDir, argv }) {
     throw new Error('[stack] pr: cannot specify both --happy-server and --happy-server-light');
   }
 
+  const happyMonorepoActive = Boolean(coerceHappyMonorepoRootFromPath(getComponentDir(rootDir, 'happy', process.env)));
+  if (happyMonorepoActive) {
+    if (prCli) {
+      throw new Error(
+        '[stack] pr: --happy-cli is not supported when using the slopus/happy monorepo.\n' +
+          'Fix: use --happy=<pr> to pin the monorepo (UI + CLI + server) in one worktree.'
+      );
+    }
+    if (prServer) {
+      throw new Error(
+        '[stack] pr: --happy-server is not supported when using the slopus/happy monorepo.\n' +
+          'Fix: use --happy=<pr> to pin the monorepo (UI + CLI + server) in one worktree.'
+      );
+    }
+  }
+
   const serverFromArg = (kv.get('--server') ?? '').trim();
   const inferredServer = prServer ? 'happy-server' : prServerLight ? 'happy-server-light' : '';
   const serverComponent = (serverFromArg || inferredServer || 'happy-server-light').trim();
@@ -2551,6 +2792,7 @@ async function cmdPrStack({ rootDir, argv }) {
   }
 
   const wantsMobile = flags.has('--mobile') || flags.has('--with-mobile');
+  const wantsExpoTailscale = flags.has('--expo-tailscale');
   const background = flags.has('--background') || flags.has('--bg') || (kv.get('--background') ?? '').trim() === '1';
 
   const seedAuthFlag = flags.has('--seed-auth') ? true : flags.has('--no-seed-auth') ? false : null;
@@ -2681,12 +2923,19 @@ async function cmdPrStack({ rootDir, argv }) {
   }
 
   // 2) Checkout PR worktrees and pin them to the stack env file.
-  const prSpecs = [
-    { component: 'happy', pr: prHappy },
-    { component: 'happy-cli', pr: prCli },
-    ...(serverComponent === 'happy-server' ? [{ component: 'happy-server', pr: prServer }] : []),
-    ...(serverComponent === 'happy-server-light' ? [{ component: 'happy-server-light', pr: prServerLight }] : []),
-  ].filter((x) => x.pr);
+  const prSpecs = (
+    happyMonorepoActive
+      ? [
+          ...(prHappy ? [{ component: 'happy', pr: prHappy }] : []),
+          ...(serverComponent === 'happy-server-light' && prServerLight ? [{ component: 'happy-server-light', pr: prServerLight }] : []),
+        ]
+      : [
+          ...(prHappy ? [{ component: 'happy', pr: prHappy }] : []),
+          ...(prCli ? [{ component: 'happy-cli', pr: prCli }] : []),
+          ...(serverComponent === 'happy-server' && prServer ? [{ component: 'happy-server', pr: prServer }] : []),
+          ...(serverComponent === 'happy-server-light' && prServerLight ? [{ component: 'happy-server-light', pr: prServerLight }] : []),
+        ]
+  ).filter((x) => x.pr);
 
   const worktrees = [];
   const stackEnvPath = resolveStackEnvPath(stackName).envPath;
@@ -2714,9 +2963,10 @@ async function cmdPrStack({ rootDir, argv }) {
         // If you asked to pin a component to a PR checkout, it MUST be a worktree path under
         // the active workspace components dir (including sandbox workspace).
         if (parsed?.path && !isComponentWorktreePath({ rootDir, component, dir: parsed.path, env })) {
+          const expectedRepoKey = parsed?.repoKey ? String(parsed.repoKey) : component;
           throw new Error(
             `[stack] pr: refusing to pin ${component} because the checked out path is not a worktree.\n` +
-              `- expected under: ${join(getComponentsDir(rootDir, env), '.worktrees', component)}/...\n` +
+              `- expected under: ${join(getComponentsDir(rootDir, env), '.worktrees', expectedRepoKey)}/...\n` +
               `- actual: ${String(parsed.path ?? '').trim()}\n` +
               `Fix: this is a bug. Please re-run with --force, or delete/recreate the stack (${stackName}).`
           );
@@ -2753,6 +3003,40 @@ async function cmdPrStack({ rootDir, argv }) {
     }
   }
 
+  // Monorepo shortcut:
+  // If `--happy=<pr>` was provided and the local checkout is the slopus/happy monorepo, pin
+  // happy-cli and (optionally) happy-server to that same worktree without fetching separate PRs.
+  if (happyMonorepoActive && prHappy) {
+    const happyWt = worktrees.find((w) => w?.component === 'happy');
+    const happyPath = String(happyWt?.path ?? '').trim();
+    const happyRoot = happyWt?.worktreeRoot ? resolve(String(happyWt.worktreeRoot)) : happyPath ? coerceHappyMonorepoRootFromPath(happyPath) : null;
+    if (!happyRoot) {
+      throw new Error('[stack] pr: expected happy monorepo worktree root but could not resolve it from the checked out path.');
+    }
+
+    const derive = (component) => {
+      const sub = happyMonorepoSubdirForComponent(component);
+      if (!sub) return null;
+      return join(happyRoot, sub);
+    };
+
+    const derivedComponents = [
+      'happy-cli',
+      ...(serverComponent === 'happy-server' ? ['happy-server'] : []),
+    ];
+
+    for (const c of derivedComponents) {
+      const p = derive(c);
+      if (!p) continue;
+      if (!isComponentWorktreePath({ rootDir, component: c, dir: p, env: process.env })) {
+        throw new Error(`[stack] pr: refusing to pin ${c} because the derived path is not a worktree: ${p}`);
+      }
+      const key = componentDirEnvKey(c);
+      await ensureEnvFileUpdated({ envPath: stackEnvPath, updates: [{ key, value: p }] });
+      worktrees.push({ component: c, path: p });
+    }
+  }
+
   // Validate that all PR components are pinned correctly before starting.
   // This prevents "wrong daemon" / "wrong UI" errors that are otherwise extremely confusing in review-pr.
   if (prSpecs.length) {
@@ -2815,6 +3099,7 @@ async function cmdPrStack({ rootDir, argv }) {
     progress(`[stack] pr: ${stackName}: starting dev...`);
     const args = [
       ...(wantsMobile ? ['--mobile'] : []),
+      ...(wantsExpoTailscale ? ['--expo-tailscale'] : []),
       ...(passthrough.length ? ['--', ...passthrough] : []),
     ];
     await cmdRunScript({ rootDir, stackName, scriptPath: 'dev.mjs', args, background });
@@ -2822,6 +3107,7 @@ async function cmdPrStack({ rootDir, argv }) {
     progress(`[stack] pr: ${stackName}: starting...`);
     const args = [
       ...(wantsMobile ? ['--mobile'] : []),
+      ...(wantsExpoTailscale ? ['--expo-tailscale'] : []),
       ...(passthrough.length ? ['--', ...passthrough] : []),
     ];
     await cmdRunScript({ rootDir, stackName, scriptPath: 'run.mjs', args, background });
@@ -2993,10 +3279,13 @@ async function main() {
           'list',
           'migrate',
           'audit',
-        'duplicate',
+          'archive',
+          'duplicate',
           'info',
           'pr',
           'create-dev-auth-seed',
+          'happy',
+          'env',
           'auth',
           'dev',
           'start',
@@ -3022,20 +3311,23 @@ async function main() {
       },
       text: [
         '[stack] usage:',
-        '  happys stack new <name> [--port=NNN] [--server=happy-server|happy-server-light] [--happy=default|<owner/...>|<path>] [--happy-cli=...] [--interactive] [--copy-auth-from=<stack>] [--no-copy-auth] [--force-port] [--json]',
+        '  happys stack new <name> [--port=NNN] [--server=happy-server|happy-server-light] [--happy=default|<owner/...>|<path>] [--interactive] [--copy-auth-from=<stack>] [--no-copy-auth] [--force-port] [--json]',
         '  happys stack edit <name> --interactive [--json]',
         '  happys stack list [--json]',
         '  happys stack migrate [--json]   # copy legacy env files from ~/.happy/local/stacks/* -> ~/.happy/stacks/*',
         '  happys stack audit [--fix] [--fix-main] [--fix-ports] [--fix-workspace] [--fix-paths] [--unpin-ports] [--unpin-ports-except=stack1,stack2] [--json]',
+        '  happys stack archive <name> [--dry-run] [--date=YYYY-MM-DD] [--json]',
         '  happys stack duplicate <from> <to> [--duplicate-worktrees] [--deps=none|link|install|link-or-install] [--json]',
         '  happys stack info <name> [--json]',
-        '  happys stack pr <name> --happy=<pr-url|number> [--happy-cli=<pr-url|number>] [--dev|--start] [--json] [-- ...]',
+        '  happys stack pr <name> --happy=<pr-url|number> [--happy-server-light=<pr-url|number>] [--dev|--start] [--json] [-- ...]',
         '  happys stack create-dev-auth-seed [name] [--server=happy-server|happy-server-light] [--non-interactive] [--json]',
+        '  happys stack happy <name> [-- ...]',
+        '  happys stack env <name> set KEY=VALUE [KEY2=VALUE2...] | unset KEY [KEY2...] | get KEY | list | path [--json]',
         '  happys stack auth <name> status|login|copy-from [--json]',
         '  happys stack dev <name> [-- ...]',
         '  happys stack start <name> [-- ...]',
         '  happys stack build <name> [-- ...]',
-        '  happys stack review <name> [component...] [--reviewers=coderabbit,codex] [--base-remote=<remote>] [--base-branch=<branch>] [--base-ref=<ref>] [--json]',
+        '  happys stack review <name> [component...] [--reviewers=coderabbit,codex] [--base-remote=<remote>] [--base-branch=<branch>] [--base-ref=<ref>] [--chunks|--no-chunks] [--chunking=auto|head-slice|commit-window] [--chunk-max-files=N] [--json]',
         '  happys stack typecheck <name> [component...] [--json]',
         '  happys stack lint <name> [component...] [--json]',
         '  happys stack test <name> [component...] [--json]',
@@ -3155,6 +3447,15 @@ async function main() {
                 'example:',
                 '  happys stack srv exp1 -- status',
               ]
+          : cmd === 'env'
+            ? [
+                '[stack] usage:',
+                '  happys stack env <name> set KEY=VALUE [KEY2=VALUE2...]',
+                '  happys stack env <name> unset KEY [KEY2...]',
+                '  happys stack env <name> get KEY',
+                '  happys stack env <name> list',
+                '  happys stack env <name> path',
+              ]
             : cmd.startsWith('tailscale:')
               ? [
                   '[stack] usage:',
@@ -3175,6 +3476,41 @@ async function main() {
   // Remaining args after "<cmd> <name>"
   const passthrough = argv.slice(2);
 
+  if (cmd === 'archive') {
+    const res = await cmdArchiveStack({ rootDir, argv, stackName });
+    if (json) {
+      printResult({ json, data: res });
+    } else if (res.dryRun) {
+      console.log(`[stack] would archive "${stackName}" -> ${res.archivedStackDir} (dry-run)`);
+    } else {
+      console.log(`[stack] archived "${stackName}" -> ${res.archivedStackDir}`);
+    }
+    return;
+  }
+
+  if (cmd === 'env') {
+    const hasPositional = passthrough.some((a) => !a.startsWith('-'));
+    const envArgv = hasPositional ? passthrough : ['list', ...passthrough];
+    // Forward to scripts/env.mjs under the stack env.
+    // This keeps stack env editing behavior unified with `happys env ...`.
+    await withStackEnv({
+      stackName,
+      fn: async ({ env }) => {
+        await run(process.execPath, [join(rootDir, 'scripts', 'env.mjs'), ...envArgv], { cwd: rootDir, env });
+      },
+    });
+    return;
+  }
+  if (cmd === 'happy') {
+    const args = passthrough[0] === '--' ? passthrough.slice(1) : passthrough;
+    await withStackEnv({
+      stackName,
+      fn: async ({ env }) => {
+        await run(process.execPath, [join(rootDir, 'scripts', 'happy.mjs'), ...args], { cwd: rootDir, env });
+      },
+    });
+    return;
+  }
   if (cmd === 'dev') {
     const background = passthrough.includes('--background') || passthrough.includes('--bg');
     const args = background ? passthrough.filter((a) => a !== '--background' && a !== '--bg') : passthrough;