happy-stacks 0.1.2 → 0.3.0

package/scripts/utils/{stack_stop.mjs → stack/stop.mjs}

@@ -2,18 +2,13 @@ import { existsSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
-import { getComponentDir } from './paths.mjs';
-import { killPortListeners } from './ports.mjs';
-import { isPidAlive, killPid, readPidState } from './expo.mjs';
-import { stopLocalDaemon } from '../daemon.mjs';
-import { stopHappyServerManagedInfra } from './happy_server_infra.mjs';
-
-function parseIntOrNull(raw) {
-  const s = String(raw ?? '').trim();
-  if (!s) return null;
-  const n = Number(s);
-  return Number.isFinite(n) && n > 0 ? n : null;
-}
+import { getComponentDir } from '../paths/paths.mjs';
+import { isPidAlive, readPidState } from '../expo/expo.mjs';
+import { stopLocalDaemon } from '../../daemon.mjs';
+import { stopHappyServerManagedInfra } from '../server/infra/happy_server_infra.mjs';
+import { deleteStackRuntimeStateFile, getStackRuntimeStatePath, readStackRuntimeStateFile } from './runtime_state.mjs';
+import { killPidOwnedByStack, killProcessGroupOwnedByStack, listPidsWithEnvNeedle } from '../proc/ownership.mjs';
+import { coercePort } from '../server/port.mjs';
 
 function resolveServerComponentFromStackEnv(env) {
   const v =
@@ -89,7 +84,7 @@ async function stopDaemonTrackedSessions({ cliHomeDir, json }) {
   return { ok: true, skipped: false, stoppedSessionIds };
 }
 
-async function stopExpoStateDir({ stackName, baseDir, kind, stateFileName, json }) {
+async function stopExpoStateDir({ stackName, baseDir, kind, stateFileName, envPath, json }) {
   const root = join(baseDir, kind);
   let entries = [];
   try {
@@ -106,31 +101,28 @@ async function stopExpoStateDir({ stackName, baseDir, kind, stateFileName, json
     const state = await readPidState(statePath);
     if (!state) continue;
     const pid = Number(state.pid);
-    const port = parseIntOrNull(state.port);
 
     if (!Number.isFinite(pid) || pid <= 1) continue;
     if (!isPidAlive(pid)) continue;
 
     if (!json) {
       // eslint-disable-next-line no-console
-      console.log(`[stack] stopping ${kind} (pid=${pid}${port ? ` port=${port}` : ''}) for ${stackName}`);
-    }
-    if (port) {
-      // eslint-disable-next-line no-await-in-loop
-      await killPortListeners(port, { label: `${stackName} ${kind}` });
+      console.log(`[stack] stopping ${kind} (pid=${pid}) for ${stackName}`);
     }
     // eslint-disable-next-line no-await-in-loop
-    await killPid(pid);
-    killed.push({ pid, port, statePath });
+    await killProcessGroupOwnedByStack(pid, { stackName, envPath, label: kind, json });
+    killed.push({ pid, port: null, statePath });
   }
   return killed;
 }
 
-export async function stopStackWithEnv({ rootDir, stackName, baseDir, env, json, noDocker = false, aggressive = false }) {
+export async function stopStackWithEnv({ rootDir, stackName, baseDir, env, json, noDocker = false, aggressive = false, sweepOwned = false }) {
   const actions = {
     stackName,
     baseDir,
     aggressive,
+    sweepOwned,
+    runner: null,
     daemonSessionsStopped: null,
     daemonStopped: false,
     killedPorts: [],
@@ -141,10 +133,34 @@ export async function stopStackWithEnv({ rootDir, stackName, baseDir, env, json,
   };
 
   const serverComponent = resolveServerComponentFromStackEnv(env);
-  const port = parseIntOrNull(env.HAPPY_STACKS_SERVER_PORT ?? env.HAPPY_LOCAL_SERVER_PORT);
-  const backendPort = parseIntOrNull(env.HAPPY_STACKS_HAPPY_SERVER_BACKEND_PORT ?? env.HAPPY_LOCAL_HAPPY_SERVER_BACKEND_PORT);
+  const port = coercePort(env.HAPPY_STACKS_SERVER_PORT ?? env.HAPPY_LOCAL_SERVER_PORT);
+  const backendPort = coercePort(env.HAPPY_STACKS_HAPPY_SERVER_BACKEND_PORT ?? env.HAPPY_LOCAL_HAPPY_SERVER_BACKEND_PORT);
   const cliHomeDir = (env.HAPPY_STACKS_CLI_HOME_DIR ?? env.HAPPY_LOCAL_CLI_HOME_DIR ?? join(baseDir, 'cli')).toString();
   const cliBin = join(getComponentDir(rootDir, 'happy-cli'), 'bin', 'happy.mjs');
+  const envPath = (env.HAPPY_STACKS_ENV_FILE ?? env.HAPPY_LOCAL_ENV_FILE ?? '').toString();
+
+  // Preferred: stop stack-started processes (by PID) recorded in stack.runtime.json.
+  // This is safer than killing whatever happens to listen on a port, and doesn't rely on the runner's shutdown handler.
+  const runtimeStatePath = getStackRuntimeStatePath(stackName);
+  const runtimeState = await readStackRuntimeStateFile(runtimeStatePath);
+  const runnerPid = Number(runtimeState?.ownerPid);
+  const processes = runtimeState?.processes && typeof runtimeState.processes === 'object' ? runtimeState.processes : {};
+
+  // Kill known child processes first (process groups), then stop daemon, then stop runner.
+  const killedProcessPids = [];
+  for (const [key, rawPid] of Object.entries(processes)) {
+    const pid = Number(rawPid);
+    if (!Number.isFinite(pid) || pid <= 1) continue;
+    if (!isPidAlive(pid)) continue;
+    // eslint-disable-next-line no-await-in-loop
+    const res = await killProcessGroupOwnedByStack(pid, { stackName, envPath, cliHomeDir, label: key, json });
+    if (res.killed) {
+      killedProcessPids.push({ key, pid, reason: res.reason, pgid: res.pgid ?? null });
+    }
+  }
+  actions.runner = { stopped: false, pid: Number.isFinite(runnerPid) ? runnerPid : null, reason: runtimeState ? 'not_running_or_not_owned' : 'missing_state' };
+  actions.killedPorts = actions.killedPorts ?? [];
+  actions.processes = { killed: killedProcessPids };
 
   if (aggressive) {
     try {
@@ -162,33 +178,36 @@ export async function stopStackWithEnv({ rootDir, stackName, baseDir, env, json,
     actions.errors.push({ step: 'daemon', error: e instanceof Error ? e.message : String(e) });
   }
 
+  // Now stop the runner PID last (if it exists). This should clean up any remaining state files it owns.
+  if (Number.isFinite(runnerPid) && runnerPid > 1 && isPidAlive(runnerPid)) {
+    if (!json) {
+      // eslint-disable-next-line no-console
+      console.log(`[stack] stopping runner (pid=${runnerPid}) for ${stackName}`);
+    }
+    const res = await killPidOwnedByStack(runnerPid, { stackName, envPath, cliHomeDir, label: 'runner', json });
+    actions.runner = { stopped: res.killed, pid: runnerPid, reason: res.reason };
+  }
+
+  // Only delete runtime state if the runner is confirmed stopped (or not running).
+  if (!isPidAlive(runnerPid)) {
+    await deleteStackRuntimeStateFile(runtimeStatePath);
+  }
+
   try {
-    actions.uiDev = await stopExpoStateDir({ stackName, baseDir, kind: 'ui-dev', stateFileName: 'ui.state.json', json });
+    actions.uiDev = await stopExpoStateDir({ stackName, baseDir, kind: 'ui-dev', stateFileName: 'ui.state.json', envPath, json });
   } catch (e) {
     actions.errors.push({ step: 'expo-ui', error: e instanceof Error ? e.message : String(e) });
   }
   try {
-    actions.mobile = await stopExpoStateDir({ stackName, baseDir, kind: 'mobile', stateFileName: 'expo.state.json', json });
+    actions.mobile = await stopExpoStateDir({ stackName, baseDir, kind: 'mobile', stateFileName: 'expo.state.json', envPath, json });
   } catch (e) {
     actions.errors.push({ step: 'expo-mobile', error: e instanceof Error ? e.message : String(e) });
   }
 
-  if (backendPort) {
-    try {
-      const pids = await killPortListeners(backendPort, { label: `${stackName} happy-server-backend` });
-      actions.killedPorts.push({ port: backendPort, pids, label: 'happy-server-backend' });
-    } catch (e) {
-      actions.errors.push({ step: 'backend-port', error: e instanceof Error ? e.message : String(e) });
-    }
-  }
-  if (port) {
-    try {
-      const pids = await killPortListeners(port, { label: `${stackName} server` });
-      actions.killedPorts.push({ port, pids, label: 'server' });
-    } catch (e) {
-      actions.errors.push({ step: 'server-port', error: e instanceof Error ? e.message : String(e) });
-    }
-  }
+  // IMPORTANT:
+  // Never kill "whatever is listening on a port" in stack mode.
+  void backendPort;
+  void port;
 
   const managed = (env.HAPPY_STACKS_MANAGED_INFRA ?? env.HAPPY_LOCAL_MANAGED_INFRA ?? '1').toString().trim() !== '0';
   if (!noDocker && serverComponent === 'happy-server' && managed) {
@@ -201,6 +220,30 @@ export async function stopStackWithEnv({ rootDir, stackName, baseDir, env, json,
     actions.infra = { ok: true, skipped: true, reason: noDocker ? 'no_docker' : 'not_managed_or_not_happy_server' };
   }
 
+  // Last resort: sweep any remaining processes that still carry this stack env file in their environment.
+  // This is still safe because envPath is unique per stack; we also exclude our own PID.
+  if (sweepOwned && envPath) {
+    const needle1 = `HAPPY_STACKS_ENV_FILE=${envPath}`;
+    const needle2 = `HAPPY_LOCAL_ENV_FILE=${envPath}`;
+    const pids = [
+      ...(await listPidsWithEnvNeedle(needle1)),
+      ...(await listPidsWithEnvNeedle(needle2)),
+    ]
+      .filter((pid) => pid !== process.pid)
+      .filter((pid) => Number.isFinite(pid) && pid > 1);
+
+    const swept = [];
+    for (const pid of Array.from(new Set(pids))) {
+      if (!isPidAlive(pid)) continue;
+      // eslint-disable-next-line no-await-in-loop
+      const res = await killProcessGroupOwnedByStack(pid, { stackName, envPath, cliHomeDir, label: 'sweep', json });
+      if (res.killed) {
+        swept.push({ pid, reason: res.reason, pgid: res.pgid ?? null });
+      }
+    }
+    actions.sweep = { pids: swept };
+  }
+
   return actions;
 }
 

package/scripts/utils/ui/browser.mjs

@@ -0,0 +1,22 @@
+import { runCapture } from '../proc/proc.mjs';
+
+export async function openUrlInBrowser(url, { timeoutMs = 5_000 } = {}) {
+  const u = String(url ?? '').trim();
+  if (!u) return { ok: false, error: 'missing_url' };
+
+  try {
+    if (process.platform === 'darwin') {
+      await runCapture('open', [u], { timeoutMs });
+      return { ok: true, method: 'open' };
+    }
+    if (process.platform === 'win32') {
+      // `start` is a cmd built-in; the empty title ("") is required so URLs with :// don't get treated as a title.
+      await runCapture('cmd', ['/c', 'start', '""', u], { timeoutMs });
+      return { ok: true, method: 'cmd-start' };
+    }
+    await runCapture('xdg-open', [u], { timeoutMs });
+    return { ok: true, method: 'xdg-open' };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}

package/scripts/utils/ui/text.mjs

@@ -0,0 +1,16 @@
+export function stripAnsi(s) {
+  // eslint-disable-next-line no-control-regex
+  return String(s ?? '').replace(/\x1b\[[0-9;]*[A-Za-z]/g, '');
+}
+
+export function padRight(s, n) {
+  const str = String(s ?? '');
+  if (str.length >= n) return str.slice(0, n);
+  return str + ' '.repeat(n - str.length);
+}
+
+export function parsePrefixedLabel(line) {
+  const m = String(line ?? '').match(/^\[([^\]]+)\]\s*/);
+  return m ? m[1] : null;
+}
+

package/scripts/where.mjs

@@ -1,17 +1,15 @@
-import './utils/env.mjs';
+import './utils/env/env.mjs';
 
 import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-import { parseArgs } from './utils/args.mjs';
-import { getComponentsDir, getComponentDir, getHappyStacksHomeDir, getRootDir, getStackLabel, getStackName, getWorkspaceDir, resolveStackEnvPath } from './utils/paths.mjs';
-import { printResult, wantsHelp, wantsJson } from './utils/cli.mjs';
-import { getRuntimeDir } from './utils/runtime.mjs';
-
-function expandHome(p) {
-  return p.replace(/^~(?=\/)/, homedir());
-}
+import { parseArgs } from './utils/cli/args.mjs';
+import { expandHome } from './utils/paths/canonical_home.mjs';
+import { getComponentsDir, getComponentDir, getHappyStacksHomeDir, getRootDir, getStackLabel, getStackName, getWorkspaceDir, resolveStackEnvPath } from './utils/paths/paths.mjs';
+import { printResult, wantsHelp, wantsJson } from './utils/cli/cli.mjs';
+import { getRuntimeDir } from './utils/paths/runtime.mjs';
+import { getCanonicalHomeDir, getCanonicalHomeEnvPath } from './utils/env/config.mjs';
+import { getSandboxDir } from './utils/env/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,18 +1,22 @@
-import './utils/env.mjs';
+import './utils/env/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 { 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 { ensureEnvLocalUpdated } from './utils/env_local.mjs';
-import { ensureEnvFileUpdated } from './utils/env_file.mjs';
+import { parseArgs } from './utils/cli/args.mjs';
+import { pathExists } from './utils/fs/fs.mjs';
+import { run, runCapture } from './utils/proc/proc.mjs';
+import { commandExists, resolveCommandPath } from './utils/proc/commands.mjs';
+import { componentDirEnvKey, getComponentDir, getComponentsDir, getHappyStacksHomeDir, getRootDir, getWorkspaceDir } from './utils/paths/paths.mjs';
+import { inferRemoteNameForOwner, parseGithubOwner } from './utils/git/worktrees.mjs';
+import { getWorktreesRoot } from './utils/git/worktrees.mjs';
+import { parseGithubPullRequest, sanitizeSlugPart } from './utils/git/refs.mjs';
+import { readTextIfExists } from './utils/fs/ops.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/env_local.mjs';
+import { ensureEnvFileUpdated } from './utils/env/env_file.mjs';
 import { existsSync } from 'node:fs';
-import { getHomeEnvLocalPath, getHomeEnvPath, resolveUserConfigEnvPath } from './utils/config.mjs';
-import { detectServerComponentDirMismatch } from './utils/validate.mjs';
+import { getHomeEnvLocalPath, getHomeEnvPath, resolveUserConfigEnvPath } from './utils/env/config.mjs';
+import { detectServerComponentDirMismatch } from './utils/server/validate.mjs';
 
 function getActiveStackName() {
   return (process.env.HAPPY_STACKS_STACK ?? process.env.HAPPY_LOCAL_STACK ?? '').trim() || 'main';
@@ -22,10 +26,6 @@ function isMainStack() {
   return getActiveStackName() === 'main';
 }
 
-function getWorktreesRoot(rootDir) {
-  return join(getComponentsDir(rootDir), '.worktrees');
-}
-
 function resolveComponentWorktreeDir({ rootDir, component, spec }) {
   const worktreesRoot = getWorktreesRoot(rootDir);
   const raw = (spec ?? '').trim();
@@ -51,32 +51,6 @@ function resolveComponentWorktreeDir({ rootDir, component, spec }) {
   return join(worktreesRoot, component, ...raw.split('/'));
 }
 
-function parseGithubPullRequest(input) {
-  const raw = (input ?? '').trim();
-  if (!raw) return null;
-  if (/^\d+$/.test(raw)) {
-    return { number: Number(raw), owner: null, repo: null };
-  }
-  // https://github.com/<owner>/<repo>/pull/<num>
-  const m = raw.match(/github\.com\/(?<owner>[^/]+)\/(?<repo>[^/]+)\/pull\/(?<num>\d+)/);
-  if (!m?.groups?.num) return null;
-  return {
-    number: Number(m.groups.num),
-    owner: m.groups.owner ?? null,
-    repo: m.groups.repo ?? null,
-  };
-}
-
-function sanitizeSlugPart(s) {
-  return (s ?? '')
-    .toString()
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9._/-]+/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^-+|-+$/g, '');
-}
-
 async function isWorktreeClean(dir) {
   const dirty = (await git(dir, ['status', '--porcelain'])).trim();
   return !dirty;
@@ -369,6 +343,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;
@@ -381,8 +370,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;
     }
 
@@ -448,13 +443,13 @@ async function cmdMigrate({ rootDir }) {
   // If the persisted config pins any component dir to a legacy location, attempt to rewrite it.
   const envUpdates = [];
 
-  // Keep in sync with scripts/utils/env_local.mjs selection logic.
+  // Keep in sync with scripts/utils/env/env_local.mjs selection logic.
   const explicitEnv = (process.env.HAPPY_STACKS_ENV_FILE ?? process.env.HAPPY_LOCAL_ENV_FILE ?? '').trim();
   const hasHomeConfig = existsSync(getHomeEnvPath()) || existsSync(getHomeEnvLocalPath());
   const envPath = explicitEnv ? explicitEnv : hasHomeConfig ? resolveUserConfigEnvPath({ cliRootDir: rootDir }) : join(rootDir, 'env.local');
 
   if (await pathExists(envPath)) {
-    const raw = await readFile(envPath, 'utf-8');
+    const raw = (await readTextIfExists(envPath)) ?? '';
     const rewrite = (v) => {
       if (!v.includes('/components/')) {
         return v;
@@ -675,7 +670,13 @@ 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 });
@@ -705,6 +706,43 @@ async function cmdNew({ rootDir, argv }) {
   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 });
@@ -1181,15 +1219,6 @@ async function cmdSync({ rootDir, argv }) {
   return { component, remote: remoteName, mirrorBranch, upstreamRef: `${remoteName}/${defaultBranch}` };
 }
 
-async function commandExists(cmd) {
-  try {
-    const out = (await runCapture('sh', ['-lc', `command -v ${cmd} >/dev/null 2>&1 && echo yes || echo no`])).trim();
-    return out === 'yes';
-  } catch {
-    return false;
-  }
-}
-
 async function fileExists(path) {
   try {
     return await pathExists(path);
@@ -1344,14 +1373,15 @@ async function cmdCode({ rootDir, argv }) {
   if (!(await pathExists(dir))) {
     throw new Error(`[wt] target does not exist: ${dir}`);
   }
-  if (!(await commandExists('code'))) {
+  const codePath = await resolveCommandPath('code', { cwd: rootDir, env: process.env });
+  if (!codePath) {
     throw new Error("[wt] VS Code CLI 'code' not found on PATH. In VS Code: Cmd+Shift+P → 'Shell Command: Install code command in PATH'.");
   }
   if (json) {
-    return { component, dir, cmd: 'code' };
+    return { component, dir, cmd: 'code', resolvedCmd: codePath };
   }
-  await run('code', [dir], { cwd: rootDir, env: process.env, stdio: 'inherit' });
-  return { component, dir, cmd: 'code' };
+  await run(codePath, [dir], { cwd: rootDir, env: process.env, stdio: 'inherit' });
+  return { component, dir, cmd: 'code', resolvedCmd: codePath };
 }
 
 async function cmdCursor({ rootDir, argv }) {
@@ -1368,14 +1398,20 @@ async function cmdCursor({ rootDir, argv }) {
     throw new Error(`[wt] target does not exist: ${dir}`);
   }
 
-  const hasCursorCli = await commandExists('cursor');
+  const cursorPath = await resolveCommandPath('cursor', { cwd: rootDir, env: process.env });
+  const hasCursorCli = Boolean(cursorPath);
   if (json) {
-    return { component, dir, cmd: hasCursorCli ? 'cursor' : process.platform === 'darwin' ? 'open -a Cursor' : null };
+    return {
+      component,
+      dir,
+      cmd: hasCursorCli ? 'cursor' : process.platform === 'darwin' ? 'open -a Cursor' : null,
+      resolvedCmd: cursorPath || null,
+    };
   }
 
   if (hasCursorCli) {
-    await run('cursor', [dir], { cwd: rootDir, env: process.env, stdio: 'inherit' });
-    return { component, dir, cmd: 'cursor' };
+    await run(cursorPath, [dir], { cwd: rootDir, env: process.env, stdio: 'inherit' });
+    return { component, dir, cmd: 'cursor', resolvedCmd: cursorPath };
   }
 
   if (process.platform === 'darwin') {
@@ -1582,6 +1618,7 @@ async function main() {
         '  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] [--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> [--force] [--interactive|-i] [--json]',
         '  happys wt status <component> [worktreeSpec|default|path] [--json]',
@@ -1633,6 +1670,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({