@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.1

package/dist/runtime/worktree-bootstrap.js

@@ -1,579 +0,0 @@
-/**
- * `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