@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.90

package/dist/runtime/worktree-bootstrap.js

@@ -0,0 +1,579 @@
+/**
+ * `pugi --worktree` bootstrap - PUGI-487.
+ *
+ * User-facing parity surface for parallel-agent isolation patterns
+ * seen across competitor AI coding CLIs. The flag creates an isolated
+ * git worktree at `.claude/worktrees/<name>/` on a new branch
+ * `worktree-<name>` and starts the REPL inside it. Operators can run
+ * several Pugi sessions in parallel without their filesystems
+ * colliding.
+ *
+ * Distinct namespace from the existing dispatcher worktree manager:
+ *
+ *  - This module owns `.claude/worktrees/<name>/` (USER-facing,
+ *    short kebab names like `feat-x` or auto-generated `bright-fox`).
+ *  - `core/worktree-manager/` owns `.pugi/worktrees/<agent-id>/`
+ *    (DISPATCHER-facing, agent-id keyed).
+ *
+ * Public surface:
+ *
+ *  - `bootstrapWorktree(options)` - validate inputs, run hooks,
+ *    create the worktree, copy `.worktreeinclude` matches, return
+ *    a typed envelope ready for the CLI to chdir + REPL.
+ *  - `generateWhimsicalName()` - adjective + animal pair for the
+ *    auto-named case (`pugi --worktree` with no name).
+ *  - `runUserWorktreeCleanup(options)` - the daily sweep that removes
+ *    user-facing worktrees > N days old with no uncommitted state.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync, } from 'node:fs';
+import { dirname, isAbsolute, posix, resolve, sep } from 'node:path';
+import { loadHooksConfig } from '../core/hooks/registry.js';
+import { fireWorktreeHooks, } from '../core/hooks/worktree-events.js';
+import { collectWorktreeIncludeFiles, loadWorktreeInclude, } from '../core/worktree/include-parser.js';
+import { isTrustedWorkspace } from '../core/trust.js';
+/** Canonical directory prefix for user-facing worktrees. */
+export const USER_WORKTREES_PREFIX = '.claude/worktrees';
+/**
+ * Branch prefix for user-facing worktree branches. The full name is
+ * `worktree-<name>` so the operator can quickly see which branches in
+ * `git branch` came from `pugi --worktree`.
+ */
+export const USER_WORKTREE_BRANCH_PREFIX = 'worktree-';
+/** Strict slug regex for the operator-supplied name. */
+export const WORKTREE_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/** Strict regex for the PR-shorthand sugar. */
+export const PR_SHORTHAND_PATTERN = /^#(\d{1,8})$/;
+/**
+ * The main entry point invoked by `runtime/cli.ts` when `--worktree`
+ * is set on the bare invocation. Returns the typed envelope so the
+ * CLI layer can decide whether to chdir + mount the REPL or surface
+ * an error.
+ */
+export async function bootstrapWorktree(options) {
+    const runGit = options.runGit ?? defaultGitRunner;
+    const repoRoot = resolve(options.repoRoot);
+    // Step 1: confirm we are actually in a git repo. The standard
+    // `rev-parse --git-dir` probe surfaces the most useful error when
+    // the operator runs `pugi --worktree` in `$HOME` by mistake.
+    const probe = runGit(['rev-parse', '--git-dir'], repoRoot);
+    if (probe.status !== 0) {
+        return failure({
+            name: '',
+            branch: '',
+            directory: '',
+            baseRef: options.baseRef ?? 'fresh',
+            resolvedBase: '',
+            reason: 'not_a_git_repo',
+            message: `not a git repository: ${repoRoot}`,
+        });
+    }
+    // Step 2: trust gate. The default-restricted policy (see
+    // `core/trust.ts`) refuses to load workspace-scoped hooks unless the
+    // operator has explicitly trusted the directory. Worktrees inherit
+    // their parent's trust state so a `pugi init`-trusted root carries
+    // through to every child created via this flag.
+    const trustGate = options.isTrusted ?? isTrustedWorkspace;
+    const skipTrust = options.skipTrustGate === true ||
+        process.env.PUGI_SKIP_WORKTREE_TRUST === '1';
+    if (!skipTrust) {
+        const trusted = await trustGate(repoRoot);
+        if (!trusted) {
+            return failure({
+                name: '',
+                branch: '',
+                directory: '',
+                baseRef: options.baseRef ?? 'fresh',
+                resolvedBase: '',
+                reason: 'untrusted_workspace',
+                message: `workspace ${repoRoot} is not trusted. Run \`pugi init\` or \`pugi config trust .\` first.`,
+            });
+        }
+    }
+    // Step 3: resolve the requested name. Three shapes:
+    //   - PR shorthand `#1234`
+    //   - operator-supplied slug
+    //   - undefined => auto-generate
+    const nameResolution = resolveName(options.nameArg, options.generateName);
+    if (typeof nameResolution === 'string') {
+        return failure({
+            name: typeof options.nameArg === 'string' ? options.nameArg : '',
+            branch: '',
+            directory: '',
+            baseRef: options.baseRef ?? 'fresh',
+            resolvedBase: '',
+            reason: 'invalid_name',
+            message: nameResolution,
+        });
+    }
+    const { name, branch, prNumber } = nameResolution;
+    const baseRefMode = options.baseRef ?? 'fresh';
+    // Step 4: compute the target directory + resolved base ref.
+    const defaultDirectory = resolve(repoRoot, USER_WORKTREES_PREFIX, name);
+    if (existsSync(defaultDirectory)) {
+        return failure({
+            name,
+            branch,
+            directory: defaultDirectory,
+            baseRef: baseRefMode,
+            resolvedBase: '',
+            reason: 'directory_exists',
+            message: `worktree already exists at ${defaultDirectory}`,
+        });
+    }
+    const baseSha = resolveBaseSha(runGit, repoRoot, baseRefMode, prNumber);
+    if (typeof baseSha === 'string' && baseSha.startsWith('ERR:')) {
+        return failure({
+            name,
+            branch,
+            directory: defaultDirectory,
+            baseRef: baseRefMode,
+            resolvedBase: '',
+            reason: prNumber !== undefined ? 'pr_fetch_failed' : 'git_command_failed',
+            message: baseSha.slice('ERR:'.length),
+        });
+    }
+    // Step 5: fire the WorktreeCreate hook. Hooks may veto via non-zero
+    // exit (with `blocking: true`) or override the directory location.
+    const hooks = (options.loadHooks ?? loadHooksConfig)();
+    const createPayload = {
+        event: 'WorktreeCreate',
+        name,
+        defaultDirectory,
+        baseRef: typeof baseSha === 'string' ? baseSha : '',
+        repoRoot,
+    };
+    const createOutcome = fireWorktreeHooks(hooks, 'WorktreeCreate', createPayload);
+    if (createOutcome.anyBlocked) {
+        return failure({
+            name,
+            branch,
+            directory: defaultDirectory,
+            baseRef: baseRefMode,
+            resolvedBase: typeof baseSha === 'string' ? baseSha : '',
+            reason: 'hook_blocked',
+            message: `WorktreeCreate hook blocked the operation`,
+        });
+    }
+    // Override resolution: a hook stdout `{ "directory": "<abs-path>" }`
+    // wins ONLY when the path is inside the repo root. We refuse
+    // out-of-repo overrides defensively because the cleanup sweep would
+    // never reach them.
+    let directory = defaultDirectory;
+    if (createOutcome.directoryOverride) {
+        const override = resolve(repoRoot, createOutcome.directoryOverride);
+        if (override.startsWith(repoRoot + sep)) {
+            directory = override;
+        }
+    }
+    // Step 6: git worktree add. We resolve the base SHA above so the
+    // branch ref does not depend on a runtime-mutable `origin/HEAD` at
+    // creation time.
+    mkdirSync(dirname(directory), { recursive: true });
+    const addArgs = [
+        'worktree',
+        'add',
+        '-b',
+        branch,
+        '--',
+        directory,
+        typeof baseSha === 'string' ? baseSha : 'HEAD',
+    ];
+    const add = runGit(addArgs, repoRoot);
+    if (add.status !== 0) {
+        return failure({
+            name,
+            branch,
+            directory,
+            baseRef: baseRefMode,
+            resolvedBase: typeof baseSha === 'string' ? baseSha : '',
+            reason: 'git_command_failed',
+            message: (add.stderr || add.stdout || `exit=${add.status}`).trim(),
+        });
+    }
+    // Step 7: copy `.worktreeinclude` matches (e.g. .env). Tracked files
+    // are never duplicated - see the include-parser doc-block.
+    const includeResult = loadWorktreeInclude(repoRoot);
+    const collector = options.collectIncludes ?? collectWorktreeIncludeFiles;
+    const copyFile = options.copyFile ?? defaultCopyFile;
+    const copyOpts = {};
+    const matches = collector(repoRoot, includeResult.rules, copyOpts);
+    const copiedFiles = [];
+    for (const rel of matches) {
+        const src = resolve(repoRoot, rel);
+        const dest = resolve(directory, rel);
+        try {
+            mkdirSync(dirname(dest), { recursive: true });
+            copyFile(src, dest);
+            copiedFiles.push(rel);
+        }
+        catch {
+            // Best-effort copy. A single failure (e.g. permission denied on
+            // one entry) should not abort the bootstrap - surface via the
+            // envelope and let the operator decide.
+        }
+    }
+    return {
+        ok: true,
+        name,
+        branch,
+        directory,
+        baseRef: baseRefMode,
+        resolvedBase: typeof baseSha === 'string' ? baseSha : '',
+        copiedFiles,
+    };
+}
+/**
+ * Parse the operator-supplied name argument. Returns a `ResolvedName`
+ * on success or a human-readable error string on rejection. Exposed
+ * for spec coverage.
+ */
+export function resolveName(nameArg, generator) {
+    if (nameArg === undefined || nameArg.trim().length === 0) {
+        const generated = (generator ?? generateWhimsicalName)();
+        if (!WORKTREE_NAME_PATTERN.test(generated)) {
+            return `auto-generated name "${generated}" failed validation`;
+        }
+        return {
+            name: generated,
+            branch: `${USER_WORKTREE_BRANCH_PREFIX}${generated}`,
+        };
+    }
+    const trimmed = nameArg.trim();
+    const prMatch = PR_SHORTHAND_PATTERN.exec(trimmed);
+    if (prMatch && typeof prMatch[1] === 'string') {
+        const n = Number(prMatch[1]);
+        if (!Number.isInteger(n) || n <= 0) {
+            return `invalid PR number: ${trimmed}`;
+        }
+        return {
+            name: `pr-${n}`,
+            branch: `${USER_WORKTREE_BRANCH_PREFIX}pr-${n}`,
+            prNumber: n,
+        };
+    }
+    if (!WORKTREE_NAME_PATTERN.test(trimmed)) {
+        return `name must match ${WORKTREE_NAME_PATTERN}`;
+    }
+    return {
+        name: trimmed,
+        branch: `${USER_WORKTREE_BRANCH_PREFIX}${trimmed}`,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Base ref resolution                                                */
+/* ------------------------------------------------------------------ */
+/**
+ * Resolve the SHA the new branch should point at. PR-shorthand wins
+ * regardless of `baseRef` mode (the operator's clear intent). For the
+ * `fresh` mode we resolve `origin/<default-branch>` and fall back to
+ * local HEAD when no remote is configured. The `head` mode always
+ * carries local HEAD.
+ *
+ * Returns the resolved SHA on success or an `ERR:<detail>` string on
+ * failure so the caller can decide whether to surface
+ * `git_command_failed` or `pr_fetch_failed`.
+ */
+function resolveBaseSha(runGit, repoRoot, baseRef, prNumber) {
+    if (prNumber !== undefined) {
+        // `pull/N/head` is the GitHub convention. Fetch the PR head into
+        // the local refs cache before resolving so the worktree-add can
+        // find it.
+        const ref = `pull/${prNumber}/head`;
+        const fetch = runGit(['fetch', 'origin', ref], repoRoot);
+        if (fetch.status !== 0) {
+            return `ERR:failed to fetch ${ref} from origin: ${(fetch.stderr || fetch.stdout).trim()}`;
+        }
+        const sha = runGit(['rev-parse', 'FETCH_HEAD'], repoRoot);
+        if (sha.status !== 0) {
+            return `ERR:failed to resolve FETCH_HEAD after fetching ${ref}`;
+        }
+        return sha.stdout.trim();
+    }
+    if (baseRef === 'head') {
+        const sha = runGit(['rev-parse', 'HEAD'], repoRoot);
+        if (sha.status !== 0) {
+            return `ERR:failed to resolve HEAD: ${(sha.stderr || sha.stdout).trim()}`;
+        }
+        return sha.stdout.trim();
+    }
+    // baseRef === 'fresh': try origin/<default-branch>, fall back to HEAD.
+    const remoteBranch = detectOriginHead(runGit, repoRoot);
+    if (remoteBranch) {
+        const sha = runGit(['rev-parse', remoteBranch], repoRoot);
+        if (sha.status === 0) {
+            return sha.stdout.trim();
+        }
+    }
+    const headSha = runGit(['rev-parse', 'HEAD'], repoRoot);
+    if (headSha.status !== 0) {
+        return `ERR:failed to resolve any base ref (no origin/HEAD and no local HEAD)`;
+    }
+    return headSha.stdout.trim();
+}
+function detectOriginHead(runGit, repoRoot) {
+    const symRef = runGit(['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], repoRoot);
+    if (symRef.status === 0) {
+        const value = symRef.stdout.trim();
+        if (value.length > 0)
+            return value;
+    }
+    // Common default fallbacks. Try `origin/main`, then `origin/master`.
+    for (const candidate of ['origin/main', 'origin/master']) {
+        const verify = runGit(['rev-parse', '--verify', candidate], repoRoot);
+        if (verify.status === 0)
+            return candidate;
+    }
+    return undefined;
+}
+/* ------------------------------------------------------------------ */
+/* Whimsical name generator                                           */
+/* ------------------------------------------------------------------ */
+const WHIMSICAL_ADJECTIVES = [
+    'bright',
+    'brave',
+    'calm',
+    'clever',
+    'eager',
+    'fancy',
+    'gentle',
+    'happy',
+    'jolly',
+    'keen',
+    'lucky',
+    'mighty',
+    'noble',
+    'quick',
+    'royal',
+    'silent',
+    'swift',
+    'tidy',
+    'vivid',
+    'witty',
+];
+const WHIMSICAL_VERBS = [
+    'running',
+    'sleeping',
+    'flying',
+    'leaping',
+    'roaring',
+    'singing',
+    'climbing',
+    'gliding',
+    'dancing',
+    'soaring',
+];
+const WHIMSICAL_ANIMALS = [
+    'fox',
+    'otter',
+    'lynx',
+    'puma',
+    'eagle',
+    'hawk',
+    'whale',
+    'dolphin',
+    'badger',
+    'panda',
+    'tiger',
+    'wolf',
+    'bear',
+    'koala',
+    'raven',
+    'falcon',
+    'crow',
+    'sparrow',
+];
+/**
+ * Three-word adjective-verb-animal slug for the auto-name case.
+ * Uses `Math.random` because there is no security boundary at the
+ * naming layer - the WORKTREE_NAME_PATTERN regex below validates the
+ * shape after generation.
+ */
+export function generateWhimsicalName() {
+    const adj = pick(WHIMSICAL_ADJECTIVES);
+    const verb = pick(WHIMSICAL_VERBS);
+    const animal = pick(WHIMSICAL_ANIMALS);
+    return `${adj}-${verb}-${animal}`;
+}
+function pick(items) {
+    if (items.length === 0) {
+        throw new Error('cannot pick from empty list');
+    }
+    const idx = Math.floor(Math.random() * items.length);
+    // Bounded by the modulo above so the result is always defined.
+    return items[idx];
+}
+/* ------------------------------------------------------------------ */
+/* Helpers                                                            */
+/* ------------------------------------------------------------------ */
+function defaultGitRunner(argv, cwd) {
+    const result = spawnSync('git', [...argv], {
+        cwd,
+        encoding: 'utf8',
+        shell: false,
+        timeout: 60_000,
+        maxBuffer: 16 * 1024 * 1024,
+    });
+    return {
+        status: result.status,
+        stdout: typeof result.stdout === 'string' ? result.stdout : '',
+        stderr: typeof result.stderr === 'string' ? result.stderr : '',
+    };
+}
+function defaultCopyFile(src, dest) {
+    copyFileSync(src, dest);
+}
+function failure(args) {
+    return {
+        ok: false,
+        name: args.name,
+        branch: args.branch,
+        directory: args.directory,
+        baseRef: args.baseRef,
+        resolvedBase: args.resolvedBase,
+        copiedFiles: [],
+        reason: args.reason,
+        message: args.message,
+    };
+}
+/**
+ * The daily cleanup sweep. Walks `.claude/worktrees/`, computes each
+ * entry's age (mtime), and removes ones older than `periodDays` that
+ * have no uncommitted/untracked/unpushed state. Crashed-looking trees
+ * with local work are preserved by design.
+ */
+export function runUserWorktreeCleanup(options) {
+    const repoRoot = resolve(options.repoRoot);
+    const now = options.now ?? Date.now;
+    const runGit = options.runGit ?? defaultGitRunner;
+    const root = resolve(repoRoot, USER_WORKTREES_PREFIX);
+    const lister = options.listWorktreeDir ?? defaultListWorktreeDir;
+    const remover = options.removeWorktree ?? defaultRemoveWorktree;
+    const hooks = (options.loadHooks ?? loadHooksConfig)();
+    if (!existsSync(root)) {
+        return { scanned: 0, removed: [], preserved: [] };
+    }
+    const entries = lister(root);
+    const removed = [];
+    const preserved = [];
+    const periodMs = options.periodDays * 24 * 60 * 60 * 1000;
+    for (const name of entries) {
+        if (!WORKTREE_NAME_PATTERN.test(name))
+            continue;
+        const dir = resolve(root, name);
+        let mtimeMs;
+        try {
+            mtimeMs = statSync(dir).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        const ageMs = now() - mtimeMs;
+        const ageDays = Math.floor(ageMs / (24 * 60 * 60 * 1000));
+        if (ageMs < periodMs) {
+            preserved.push({ name, directory: dir, ageDays, removed: false, preservedReason: 'too-young' });
+            continue;
+        }
+        if (hasUncommittedChanges(runGit, dir)) {
+            preserved.push({
+                name,
+                directory: dir,
+                ageDays,
+                removed: false,
+                preservedReason: 'has-uncommitted-changes',
+            });
+            continue;
+        }
+        if (hasUntrackedFiles(runGit, dir)) {
+            preserved.push({
+                name,
+                directory: dir,
+                ageDays,
+                removed: false,
+                preservedReason: 'has-untracked-files',
+            });
+            continue;
+        }
+        if (hasUnpushedCommits(runGit, dir)) {
+            preserved.push({
+                name,
+                directory: dir,
+                ageDays,
+                removed: false,
+                preservedReason: 'has-unpushed-commits',
+            });
+            continue;
+        }
+        // Fire WorktreeRemove hook before pulling the trigger.
+        const removePayload = {
+            event: 'WorktreeRemove',
+            name,
+            directory: dir,
+            reason: 'auto-cleanup',
+            repoRoot,
+        };
+        const outcome = fireWorktreeHooks(hooks, 'WorktreeRemove', removePayload);
+        if (outcome.anyBlocked) {
+            preserved.push({
+                name,
+                directory: dir,
+                ageDays,
+                removed: false,
+                preservedReason: 'hook-blocked',
+            });
+            continue;
+        }
+        if (options.dryRun) {
+            removed.push({ name, directory: dir, ageDays, removed: false });
+            continue;
+        }
+        const ok = remover(dir, runGit, repoRoot);
+        removed.push({ name, directory: dir, ageDays, removed: ok });
+    }
+    return {
+        scanned: entries.length,
+        removed,
+        preserved,
+    };
+}
+function defaultListWorktreeDir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function defaultRemoveWorktree(path, runGit, repoRoot) {
+    const result = runGit(['worktree', 'remove', '--force', path], repoRoot);
+    return result.status === 0;
+}
+function hasUncommittedChanges(runGit, dir) {
+    // `git diff --quiet` only inspects the working tree against the
+    // index, so a `git add`-staged but uncommitted hunk passes that
+    // check. Catch the staged case explicitly via `--cached` so the
+    // cleanup sweep never drops a worktree with staged work.
+    const unstaged = runGit(['diff', '--quiet'], dir);
+    if (unstaged.status !== 0)
+        return true;
+    const staged = runGit(['diff', '--cached', '--quiet'], dir);
+    return staged.status !== 0;
+}
+function hasUntrackedFiles(runGit, dir) {
+    const r = runGit(['ls-files', '--others', '--exclude-standard'], dir);
+    return r.status === 0 && r.stdout.trim().length > 0;
+}
+function hasUnpushedCommits(runGit, dir) {
+    const r = runGit(['log', '--branches', '--not', '--remotes', '--oneline'], dir);
+    return r.status === 0 && r.stdout.trim().length > 0;
+}
+/** Re-export for symmetry with the dispatcher manager. */
+export function userWorktreePathFor(repoRoot, name) {
+    // Posix-join the prefix so the slash separators stay correct on
+    // every host, then resolve to absolute on the local FS.
+    const rel = posix.join(USER_WORKTREES_PREFIX, name);
+    return isAbsolute(rel) ? rel : resolve(repoRoot, rel);
+}
+//# sourceMappingURL=worktree-bootstrap.js.map