happy-stacks 0.1.0 → 0.2.0

package/scripts/utils/watch.mjs

@@ -0,0 +1,63 @@
+import { watch } from 'node:fs';
+
+function safeWatch(path, handler) {
+  try {
+    // Node supports recursive watching on macOS and Windows. On Linux this may throw; we fail closed by returning null.
+    return watch(path, { recursive: true }, handler);
+  } catch {
+    try {
+      return watch(path, {}, handler);
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * Very small, dependency-free debounced watcher.
+ * Intended for dev ergonomics (rebuild/restart), not for correctness-critical logic.
+ */
+export function watchDebounced({ paths, debounceMs = 500, onChange } = {}) {
+  const list = Array.isArray(paths) ? paths.filter(Boolean) : [];
+  if (!list.length) return null;
+  if (typeof onChange !== 'function') return null;
+
+  let closed = false;
+  let t = null;
+  const watchers = [];
+
+  const trigger = (eventType, filename) => {
+    if (closed) return;
+    if (t) clearTimeout(t);
+    t = setTimeout(() => {
+      t = null;
+      try {
+        onChange({ eventType, filename });
+      } catch {
+        // ignore
+      }
+    }, debounceMs);
+  };
+
+  for (const p of list) {
+    const w = safeWatch(p, trigger);
+    if (w) watchers.push(w);
+  }
+
+  if (!watchers.length) return null;
+
+  return {
+    close() {
+      closed = true;
+      if (t) clearTimeout(t);
+      for (const w of watchers) {
+        try {
+          w.close();
+        } catch {
+          // ignore
+        }
+      }
+    },
+  };
+}
+

package/scripts/utils/worktrees.mjs

@@ -1,5 +1,5 @@
 import { readdir } from 'node:fs/promises';
-import { isAbsolute, join } from 'node:path';
+import { isAbsolute, join, resolve } from 'node:path';
 import { getComponentsDir } from './paths.mjs';
 import { pathExists } from './fs.mjs';
 import { run, runCapture } from './proc.mjs';
@@ -23,6 +23,62 @@ export function componentRepoDir(rootDir, component) {
   return join(getComponentsDir(rootDir), component);
 }
 
+export function isComponentWorktreePath({ rootDir, component, dir }) {
+  const raw = String(dir ?? '').trim();
+  if (!raw) return false;
+  const abs = resolve(raw);
+  const root = resolve(join(getWorktreesRoot(rootDir), component)) + '/';
+  return abs.startsWith(root);
+}
+
+export function worktreeSpecFromDir({ rootDir, component, dir }) {
+  const raw = String(dir ?? '').trim();
+  if (!raw) return null;
+  if (!isComponentWorktreePath({ rootDir, component, dir: raw })) return null;
+  const abs = resolve(raw);
+  const root = resolve(join(getWorktreesRoot(rootDir), component)) + '/';
+  const rel = abs.slice(root.length).split('/').filter(Boolean);
+  if (rel.length < 2) return null;
+  // rel = [owner, ...branchParts]
+  return rel.join('/');
+}
+
+export async function inferRemoteNameForOwner({ repoDir, owner }) {
+  const want = String(owner ?? '').trim();
+  if (!want) return 'upstream';
+
+  const candidates = ['upstream', 'origin', 'fork'];
+  for (const remoteName of candidates) {
+    try {
+      const url = (await runCapture('git', ['remote', 'get-url', remoteName], { cwd: repoDir })).trim();
+      const o = parseGithubOwner(url);
+      if (o && o === want) {
+        return remoteName;
+      }
+    } catch {
+      // ignore missing remote
+    }
+  }
+  return 'upstream';
+}
+
+export async function createWorktreeFromBaseWorktree({
+  rootDir,
+  component,
+  slug,
+  baseWorktreeSpec,
+  remoteName = 'upstream',
+  depsMode = '',
+}) {
+  const args = ['wt', 'new', component, slug, `--remote=${remoteName}`, `--base-worktree=${baseWorktreeSpec}`];
+  if (depsMode) args.push(`--deps=${depsMode}`);
+  await run(process.execPath, [join(rootDir, 'bin', 'happys.mjs'), ...args], { cwd: rootDir });
+
+  const repoDir = componentRepoDir(rootDir, component);
+  const owner = await getRemoteOwner({ repoDir, remoteName });
+  return join(getWorktreesRoot(rootDir), component, owner, ...slug.split('/'));
+}
+
 export function resolveComponentSpecToDir({ rootDir, component, spec }) {
   const raw = (spec ?? '').trim();
   if (!raw || raw === 'default') {

package/scripts/where.mjs

@@ -1,17 +1,15 @@
 import './utils/env.mjs';
 
 import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-import { parseArgs } from './utils/args.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { expandHome } from './utils/canonical_home.mjs';
 import { getComponentsDir, getComponentDir, getHappyStacksHomeDir, getRootDir, getStackLabel, getStackName, getWorkspaceDir, resolveStackEnvPath } from './utils/paths.mjs';
-import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 import { getRuntimeDir } from './utils/runtime.mjs';
-
-function expandHome(p) {
-  return p.replace(/^~(?=\/)/, homedir());
-}
+import { getCanonicalHomeDir, getCanonicalHomeEnvPath } from './utils/config.mjs';
+import { getSandboxDir } from './utils/sandbox.mjs';
 
 function getHomeEnvPaths() {
   const homeDir = getHappyStacksHomeDir();
@@ -36,6 +34,9 @@ async function main() {
 
   const rootDir = getRootDir(import.meta.url);
   const homeDir = getHappyStacksHomeDir();
+  const canonicalHomeDir = getCanonicalHomeDir();
+  const canonicalEnv = getCanonicalHomeEnvPath();
+  const sandboxDir = getSandboxDir();
   const runtimeDir = getRuntimeDir();
   const workspaceDir = getWorkspaceDir(rootDir);
   const componentsDir = getComponentsDir(rootDir);
@@ -60,12 +61,15 @@ async function main() {
     data: {
       ok: true,
       rootDir,
+      sandbox: sandboxDir ? { enabled: true, dir: sandboxDir } : { enabled: false },
       homeDir,
+      canonicalHomeDir,
       runtimeDir,
       workspaceDir,
       componentsDir,
       stack: { name: stackName, label: stackLabel },
       envFiles: {
+        canonical: { path: canonicalEnv, exists: existsSync(canonicalEnv) },
         homeEnv: { path: homeEnv, exists: existsSync(homeEnv) },
         homeLocal: { path: homeLocal, exists: existsSync(homeLocal) },
         active: resolvedActiveEnv ? { path: resolvedActiveEnv.envPath, exists: existsSync(resolvedActiveEnv.envPath) } : null,
@@ -80,12 +84,15 @@ async function main() {
     },
     text: [
       `[where] root:      ${rootDir}`,
+      sandboxDir ? `[where] sandbox:   ${sandboxDir}` : null,
+      `[where] canonical: ${canonicalHomeDir}`,
       `[where] home:      ${homeDir}`,
       `[where] runtime:   ${runtimeDir}`,
       `[where] workspace: ${workspaceDir}`,
       `[where] components:${componentsDir}`,
       '',
       `[where] stack:     ${stackName} (${stackLabel})`,
+      `[where] env (canonical pointer): ${existsSync(canonicalEnv) ? canonicalEnv : `${canonicalEnv} (missing)`}`,
       `[where] env (home defaults): ${existsSync(homeEnv) ? homeEnv : `${homeEnv} (missing)`}`,
       `[where] env (home overrides): ${existsSync(homeLocal) ? homeLocal : `${homeLocal} (missing)`}`,
       `[where] env (active): ${resolvedActiveEnv?.envPath ? resolvedActiveEnv.envPath : '(none)'}`,

package/scripts/worktrees.mjs

@@ -1,19 +1,27 @@
 import './utils/env.mjs';
 import { mkdir, readFile, readdir, rm, symlink, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
-import { parseArgs } from './utils/args.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
 import { pathExists } from './utils/fs.mjs';
 import { run, runCapture } from './utils/proc.mjs';
-import { componentDirEnvKey, getComponentDir, getComponentsDir, getRootDir, getWorkspaceDir } from './utils/paths.mjs';
-import { parseGithubOwner } from './utils/worktrees.mjs';
-import { isTty, prompt, promptSelect, withRl } from './utils/wizard.mjs';
-import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
+import { componentDirEnvKey, getComponentDir, getComponentsDir, getHappyStacksHomeDir, getRootDir, getWorkspaceDir } from './utils/paths.mjs';
+import { inferRemoteNameForOwner, parseGithubOwner } from './utils/worktrees.mjs';
+import { isTty, prompt, promptSelect, withRl } from './utils/cli/wizard.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
 import { ensureEnvLocalUpdated } from './utils/env_local.mjs';
 import { ensureEnvFileUpdated } from './utils/env_file.mjs';
 import { existsSync } from 'node:fs';
 import { getHomeEnvLocalPath, getHomeEnvPath, resolveUserConfigEnvPath } from './utils/config.mjs';
 import { detectServerComponentDirMismatch } from './utils/validate.mjs';
 
+function getActiveStackName() {
+  return (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').trim() || 'main';
+}
+
+function isMainStack() {
+  return getActiveStackName() === 'main';
+}
+
 function getWorktreesRoot(rootDir) {
   return join(getComponentsDir(rootDir), '.worktrees');
 }
@@ -142,6 +150,7 @@ async function ensureWorktreeExclude(worktreeDir, patterns) {
   const want = patterns.map((p) => p.trim()).filter(Boolean).filter((p) => !existingLines.has(p));
   if (!want.length) return;
   const next = (existing ? existing.replace(/\s*$/, '') + '\n' : '') + want.join('\n') + '\n';
+  await mkdir(dirname(excludePath), { recursive: true });
   await writeFile(excludePath, next, 'utf-8');
 }
 
@@ -360,6 +369,21 @@ async function migrateComponentWorktrees({ rootDir, component }) {
   let renamed = 0;
 
   const componentsDir = getComponentsDir(rootDir);
+  // NOTE: getWorkspaceDir() is influenced by HAPPY_STACKS_WORKSPACE_DIR, which for this repo
+  // points at the current workspace. For migration we specifically want to consider the
+  // historical home workspace at: <home>/workspace/components
+  const legacyHomeWorkspaceComponentsDir = join(getHappyStacksHomeDir(), 'workspace', 'components');
+  const allowedComponentRoots = [componentsDir];
+  try {
+    if (
+      existsSync(legacyHomeWorkspaceComponentsDir) &&
+      resolve(legacyHomeWorkspaceComponentsDir) !== resolve(componentsDir)
+    ) {
+      allowedComponentRoots.push(legacyHomeWorkspaceComponentsDir);
+    }
+  } catch {
+    // ignore
+  }
 
   for (const wt of worktrees) {
     const wtPath = wt.path;
@@ -372,8 +396,14 @@ async function migrateComponentWorktrees({ rootDir, component }) {
       continue;
     }
 
-    // Only migrate worktrees living under this happy-stacks components folder.
-    if (!resolve(wtPath).startsWith(resolve(componentsDir) + '/')) {
+    // Only migrate worktrees living under either:
+    // - current workspace components folder, or
+    // - legacy home workspace components folder (~/.happy-stacks/workspace/components)
+    // This is necessary when users switch HAPPY_STACKS_WORKSPACE_DIR, otherwise git will keep
+    // worktrees "stuck" in the old workspace and branches can't be re-used in the new workspace.
+    const resolvedWt = resolve(wtPath);
+    const okRoot = allowedComponentRoots.some((d) => resolvedWt.startsWith(resolve(d) + '/'));
+    if (!okRoot) {
       continue;
     }
 
@@ -475,13 +505,33 @@ async function cmdMigrate({ rootDir }) {
   return { moved: totalMoved, branchesRenamed: totalRenamed };
 }
 
-async function cmdUse({ rootDir, args }) {
+async function cmdUse({ rootDir, args, flags }) {
   const component = args[0];
   const spec = args[1];
   if (!component || !spec) {
     throw new Error('[wt] usage: happys wt use <component> <owner/branch|path|default>');
   }
 
+  // Safety: main stack should not be repointed to arbitrary worktrees by default.
+  // This is the most common “oops, the main stack now runs my PR checkout” footgun (especially for agents).
+  const force = Boolean(flags?.has('--force'));
+  if (!force && isMainStack() && spec !== 'default' && spec !== 'main') {
+    throw new Error(
+      `[wt] refusing to change main stack component override by default.\n` +
+        `- stack: main\n` +
+        `- component: ${component}\n` +
+        `- requested: ${spec}\n` +
+        `\n` +
+        `Recommendation:\n` +
+        `- Create a new isolated stack and switch that stack instead:\n` +
+        `  happys stack new exp1 --interactive\n` +
+        `  happys stack wt exp1 -- use ${component} ${spec}\n` +
+        `\n` +
+        `If you really intend to repoint the main stack, re-run with --force:\n` +
+        `  happys wt use ${component} ${spec} --force\n`
+    );
+  }
+
   const key = componentDirEnvKey(component);
   const worktreesRoot = getWorktreesRoot(rootDir);
   const envPath = process.env.HAPPY_STACKS_ENV_FILE?.trim()
@@ -577,10 +627,10 @@ async function cmdUseInteractive({ rootDir }) {
         options: specs.map((s) => ({ label: s, value: s })),
         defaultIndex: 0,
       });
-      await cmdUse({ rootDir, args: [component, picked] });
+      await cmdUse({ rootDir, args: [component, picked], flags: new Set(['--force']) });
       return;
     }
-    await cmdUse({ rootDir, args: [component, 'default'] });
+    await cmdUse({ rootDir, args: [component, 'default'], flags: new Set(['--force']) });
   });
 }
 
@@ -646,19 +696,79 @@ async function cmdNew({ rootDir, argv }) {
     await git(repoRoot, ['branch', '--set-upstream-to', `${remoteName}/${defaultBranch}`, mirrorBranch]).catch(() => {});
   }
 
-  await git(repoRoot, ['worktree', 'add', '-b', branchName, destPath, base]);
+  // If the branch already exists (common when migrating between workspaces),
+  // attach a new worktree to that branch instead of failing.
+  if (await gitOk(repoRoot, ['show-ref', '--verify', `refs/heads/${branchName}`])) {
+    await git(repoRoot, ['worktree', 'add', destPath, branchName]);
+  } else {
+    await git(repoRoot, ['worktree', 'add', '-b', branchName, destPath, base]);
+  }
 
   const depsMode = parseDepsMode(kv.get('--deps'));
   const deps = await maybeSetupDeps({ repoRoot, baseDir: baseWorktreeDir || '', worktreeDir: destPath, depsMode });
 
   const shouldUse = flags.has('--use');
+  const force = flags.has('--force');
   if (shouldUse) {
+    if (isMainStack() && !force) {
+      throw new Error(
+        `[wt] refusing to set main stack component override via --use by default.\n` +
+          `- stack: main\n` +
+          `- component: ${component}\n` +
+          `- new worktree: ${destPath}\n` +
+          `\n` +
+          `Recommendation:\n` +
+          `- Use an isolated stack instead:\n` +
+          `  happys stack new exp1 --interactive\n` +
+          `  happys stack wt exp1 -- use ${component} ${owner}/${slug}\n` +
+          `\n` +
+          `If you really intend to repoint the main stack, re-run with --force:\n` +
+          `  happys wt new ${component} ${slug} --use --force\n`
+      );
+    }
     const key = componentDirEnvKey(component);
     await ensureEnvLocalUpdated({ rootDir, updates: [{ key, value: destPath }] });
   }
   return { component, branch: branchName, path: destPath, base, used: shouldUse, deps };
 }
 
+async function cmdDuplicate({ rootDir, argv }) {
+  const { flags, kv } = parseArgs(argv);
+  const json = wantsJson(argv, { flags });
+
+  const positionals = argv.filter((a) => !a.startsWith('--'));
+  const component = positionals[1];
+  const fromSpec = positionals[2];
+  const slug = positionals[3];
+  if (!component || !fromSpec || !slug) {
+    throw new Error(
+      '[wt] usage: happys wt duplicate <component> <fromWorktreeSpec|path|active|default> <newSlug> [--remote=<name>] [--deps=none|link|install|link-or-install] [--use] [--json]'
+    );
+  }
+
+  // Prefer inferring the remote from the source spec's owner when possible (owner/<branch...>).
+  const remoteOverride = (kv.get('--remote') ?? '').trim();
+  let remoteName = remoteOverride;
+  if (!remoteName && !isAbsolute(fromSpec)) {
+    const owner = String(fromSpec).trim().split('/')[0];
+    if (owner && owner !== 'active' && owner !== 'default' && owner !== 'main') {
+      const repoRoot = getComponentRepoRoot(rootDir, component);
+      remoteName = await normalizeRemoteName(repoRoot, await inferRemoteNameForOwner({ repoDir: repoRoot, owner }));
+    }
+  }
+
+  const depsMode = (kv.get('--deps') ?? '').trim();
+  const forwarded = ['new', component, slug, `--base-worktree=${fromSpec}`];
+  if (remoteName) forwarded.push(`--remote=${remoteName}`);
+  if (depsMode) forwarded.push(`--deps=${depsMode}`);
+  if (flags.has('--use')) forwarded.push('--use');
+  if (flags.has('--force')) forwarded.push('--force');
+  if (json) forwarded.push('--json');
+
+  // Delegate to cmdNew for the actual implementation (single source of truth).
+  return await cmdNew({ rootDir, argv: forwarded });
+}
+
 async function cmdPr({ rootDir, argv }) {
   const { flags, kv } = parseArgs(argv);
   const json = wantsJson(argv, { flags });
@@ -776,7 +886,7 @@ async function cmdPr({ rootDir, argv }) {
   const shouldUse = flags.has('--use');
   if (shouldUse) {
     // Reuse cmdUse so it writes to env.local or stack env file depending on context.
-    await cmdUse({ rootDir, args: [component, destPath] });
+    await cmdUse({ rootDir, args: [component, destPath], flags });
   }
 
   const newHead = (await git(destPath, ['rev-parse', 'HEAD'])).trim();
@@ -1535,9 +1645,10 @@ async function main() {
         '  happys wt sync <component> [--remote=<name>] [--json]',
         '  happys wt sync-all [--remote=<name>] [--json]',
         '  happys wt list <component> [--json]',
-        '  happys wt new <component> <slug> [--from=upstream|origin] [--remote=<name>] [--base=<ref>|--base-worktree=<spec>] [--deps=none|link|install|link-or-install] [--use] [--interactive|-i] [--json]',
+        '  happys wt new <component> <slug> [--from=upstream|origin] [--remote=<name>] [--base=<ref>|--base-worktree=<spec>] [--deps=none|link|install|link-or-install] [--use] [--force] [--interactive|-i] [--json]',
+        '  happys wt duplicate <component> <fromWorktreeSpec|path|active|default> <newSlug> [--remote=<name>] [--deps=none|link|install|link-or-install] [--use] [--json]',
         '  happys wt pr <component> <pr-url|number> [--remote=upstream] [--slug=<name>] [--deps=none|link|install|link-or-install] [--use] [--update] [--stash|--stash-keep] [--force] [--json]',
-        '  happys wt use <component> <owner/branch|path|default|main> [--interactive|-i] [--json]',
+        '  happys wt use <component> <owner/branch|path|default|main> [--force] [--interactive|-i] [--json]',
         '  happys wt status <component> [worktreeSpec|default|path] [--json]',
         '  happys wt update <component> [worktreeSpec|default|path] [--remote=upstream] [--base=<ref>] [--rebase|--merge] [--dry-run] [--stash|--stash-keep] [--force] [--json]',
         '  happys wt update-all [component] [--remote=upstream] [--base=<ref>] [--rebase|--merge] [--dry-run] [--stash|--stash-keep] [--force] [--json]',
@@ -1569,7 +1680,7 @@ async function main() {
     if (interactive && isTty()) {
       await cmdUseInteractive({ rootDir });
     } else {
-      const res = await cmdUse({ rootDir, args: positionals.slice(1) });
+      const res = await cmdUse({ rootDir, args: positionals.slice(1), flags });
       printResult({ json, data: res, text: `[wt] ${res.component}: active dir -> ${res.activeDir}` });
     }
     return;
@@ -1587,6 +1698,15 @@ async function main() {
     }
     return;
   }
+  if (cmd === 'duplicate') {
+    const res = await cmdDuplicate({ rootDir, argv });
+    printResult({
+      json,
+      data: res,
+      text: `[wt] duplicated ${res.component} worktree: ${res.path} (${res.branch} based on ${res.base})`,
+    });
+    return;
+  }
   if (cmd === 'pr') {
     const res = await cmdPr({ rootDir, argv });
     printResult({