@pugi/cli 0.1.0-alpha.9 → 0.1.0-beta.2

package/dist/core/edits/worktree.js

@@ -0,0 +1,229 @@
+/**
+ * Worktree isolation — α7.7 Phase 1.
+ *
+ * Wraps `git worktree add` so a long agent loop (build / consensus
+ * review / multi-file refactor) can land its edits into a scratch
+ * workspace, run the validators against THAT path, and only then promote
+ * the resulting diff back to the operator's main working tree. The
+ * primary win is safety: a half-applied refactor never corrupts the
+ * operator's branch.
+ *
+ * Three operations:
+ *
+ *   - `createWorktree(branch)` — spawns `git worktree add --detach`
+ *     under `.pugi/worktrees/<uuid>` based on the supplied branch (or
+ *     HEAD when omitted). Returns the absolute path + a `cleanup()`
+ *     callback. The dir lives under `.pugi/` so the existing `.gitignore`
+ *     for that subtree applies (no accidental commits of the scratch
+ *     state to the main repo).
+ *
+ *   - `promoteWorktree(worktreePath, cwd)` — diffs the worktree against
+ *     its base commit and applies the diff to the main `cwd` via
+ *     `git apply`. Refuses if the main cwd has staged changes that
+ *     would conflict; the operator must commit or stash first.
+ *
+ *   - `dropWorktree(worktreePath)` — removes the worktree both from
+ *     git's bookkeeping (`git worktree remove --force`) and from disk.
+ *     Idempotent; a partially-removed worktree (`git` already cleaned
+ *     up but dir survived) is handled.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { resolve, sep } from 'node:path';
+import { OperatorAbortedError } from '../../tools/file-tools.js';
+/**
+ * Create a scratch worktree under `.pugi/worktrees/<uuid>`. The path is
+ * guaranteed unique (uuid) so multiple agent loops can run in parallel
+ * without collision.
+ */
+export function createWorktree(opts) {
+    if (opts.cancellation && opts.cancellation.isAborted) {
+        return { ok: false, reason: 'operator_aborted', detail: 'createWorktree aborted' };
+    }
+    // Confirm we're inside a git repo. `git rev-parse --git-dir` is the
+    // canonical check and avoids a misleading error message later when
+    // `git worktree add` runs in a non-repo.
+    const gitDir = runGit(['rev-parse', '--git-dir'], opts.cwd);
+    if (gitDir.status !== 0) {
+        return {
+            ok: false,
+            reason: 'not_a_git_repo',
+            detail: `not a git repo: ${opts.cwd}`,
+        };
+    }
+    // Resolve base SHA. When the operator named a branch we honor it; the
+    // default is HEAD. We capture the SHA up-front so `promoteWorktree`
+    // can `git diff <baseSha>..HEAD` deterministically even if the main
+    // working tree has moved forward since.
+    const baseRef = opts.branch ?? 'HEAD';
+    const baseShaResult = runGit(['rev-parse', baseRef], opts.cwd);
+    if (baseShaResult.status !== 0) {
+        return {
+            ok: false,
+            reason: 'git_command_failed',
+            detail: `cannot resolve base ref ${baseRef}: ${baseShaResult.stderr}`,
+        };
+    }
+    const baseSha = baseShaResult.stdout.trim();
+    const worktreeRoot = resolve(opts.cwd, '.pugi', 'worktrees');
+    mkdirSync(worktreeRoot, { recursive: true });
+    const worktreePath = resolve(worktreeRoot, randomUUID());
+    // `--detach` keeps the worktree on a detached HEAD so we don't
+    // collide with branch checkouts on the main tree. The worktree is
+    // throwaway — there is no branch name to track.
+    const create = runGit(['worktree', 'add', '--detach', worktreePath, baseSha], opts.cwd);
+    if (create.status !== 0) {
+        return {
+            ok: false,
+            reason: 'git_command_failed',
+            detail: `git worktree add failed: ${create.stderr}`,
+        };
+    }
+    const handle = {
+        path: worktreePath,
+        baseSha,
+        cleanup: () => {
+            const r = dropWorktree(worktreePath, opts.cwd);
+            if (!r.ok && r.reason !== 'worktree_missing') {
+                // Swallow non-fatal cleanup failures so the agent loop doesn't
+                // hard-crash on the happy path. The diagnostic still surfaces
+                // via the JSON output on the `pugi worktree drop` command.
+            }
+        },
+    };
+    return { ok: true, value: handle };
+}
+/**
+ * Diff the worktree against its base and apply the diff to the main cwd.
+ *
+ * Implementation notes:
+ *
+ *   - We run `git diff --binary <baseSha>` inside the worktree (NOT
+ *     `git diff <worktree>..HEAD` from the main tree — the worktree's
+ *     HEAD is detached at `baseSha`, so the meaningful diff is the
+ *     UNCOMMITTED changes the agent wrote into it).
+ *   - `--binary` ensures non-text files (assets, images) survive the
+ *     round-trip; without it `git apply` fails on any binary delta.
+ *   - We always run `git apply --check` first so a refusal does not
+ *     leave the main tree half-modified.
+ */
+export function promoteWorktree(opts) {
+    if (opts.cancellation && opts.cancellation.isAborted) {
+        return { ok: false, reason: 'operator_aborted', detail: 'promoteWorktree aborted' };
+    }
+    if (!existsSync(opts.worktreePath)) {
+        return {
+            ok: false,
+            reason: 'worktree_missing',
+            detail: `worktree path does not exist: ${opts.worktreePath}`,
+        };
+    }
+    // Capture the diff. Include both unstaged AND staged changes — the
+    // agent loop typically stages nothing (it just writes files), but
+    // honoring both is forward-compatible with hand-edits inside the
+    // worktree.
+    const diff = runGit(['diff', '--binary', opts.baseSha], opts.worktreePath);
+    if (diff.status !== 0) {
+        return {
+            ok: false,
+            reason: 'git_command_failed',
+            detail: `git diff failed: ${diff.stderr}`,
+        };
+    }
+    if (diff.stdout.trim().length === 0) {
+        return { ok: true, value: { filesChanged: 0 } };
+    }
+    // `git apply --check` validates the diff against the main tree first.
+    // Refuse early on conflict so the operator can resolve before we
+    // touch any file.
+    const check = runGit(['apply', '--check', '-'], opts.cwd, diff.stdout);
+    if (check.status !== 0) {
+        return {
+            ok: false,
+            reason: 'apply_conflict',
+            detail: `git apply --check rejected: ${check.stderr}`,
+        };
+    }
+    if (opts.dryRun) {
+        return { ok: true, value: { filesChanged: countDiffFiles(diff.stdout) } };
+    }
+    const apply = runGit(['apply', '-'], opts.cwd, diff.stdout);
+    if (apply.status !== 0) {
+        return {
+            ok: false,
+            reason: 'apply_failed',
+            detail: `git apply failed: ${apply.stderr}`,
+        };
+    }
+    return { ok: true, value: { filesChanged: countDiffFiles(diff.stdout) } };
+}
+/**
+ * Drop a worktree both from git's bookkeeping and from disk. Idempotent —
+ * a missing path returns `worktree_missing` which the caller can ignore
+ * on the cleanup-after-error path.
+ */
+export function dropWorktree(worktreePath, cwd) {
+    // `git worktree remove --force` cleans the metadata in `.git/worktrees`.
+    // If the worktree was created by another process and already pruned,
+    // git returns non-zero — we still try to `rmSync` the dir to leave the
+    // filesystem consistent.
+    const remove = runGit(['worktree', 'remove', '--force', worktreePath], cwd);
+    const gitCleanFailed = remove.status !== 0;
+    if (existsSync(worktreePath)) {
+        try {
+            rmSync(worktreePath, { recursive: true, force: true });
+        }
+        catch (error) {
+            if (gitCleanFailed) {
+                return {
+                    ok: false,
+                    reason: 'git_command_failed',
+                    detail: `git worktree remove failed AND rmSync failed: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        }
+    }
+    if (gitCleanFailed && !worktreePath.includes(`${sep}.pugi${sep}worktrees${sep}`)) {
+        // A worktree that wasn't created by us (path is outside our naming
+        // convention) is suspicious — surface the failure so the operator
+        // can diagnose.
+        return {
+            ok: false,
+            reason: 'git_command_failed',
+            detail: `git worktree remove failed: ${remove.stderr}`,
+        };
+    }
+    return { ok: true, value: undefined };
+}
+function countDiffFiles(diff) {
+    // Count `diff --git a/... b/...` headers. Cheap and unambiguous.
+    let count = 0;
+    for (const line of diff.split('\n')) {
+        if (line.startsWith('diff --git '))
+            count += 1;
+    }
+    return count;
+}
+function runGit(args, cwd, stdin) {
+    return spawnSync('git', args, {
+        cwd,
+        input: stdin,
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+}
+/**
+ * Test-only helper exporting the internal git runner so specs can stub
+ * the spawn surface when running on a CI host without a global git.
+ */
+export const __test__ = { runGit, countDiffFiles };
+/**
+ * Re-export the abort marker so the worktree CLI surface can fold the
+ * exception into a clean exit code without needing to import from the
+ * tools layer.
+ */
+export { OperatorAbortedError };
+//# sourceMappingURL=worktree.js.map

package/dist/core/engine/native-pugi.js

@@ -241,6 +241,9 @@ export class NativePugiEngineAdapter {
         for (const event of buffer)
             yield event;
         // Translate the loop outcome into an EngineResult.
+        // `aborted` (α6.9: operator cancelled mid-tool) maps to `blocked`
+        // because the operator chose the outcome, same shape as
+        // budget_exhausted / tool_refused.
         const status = outcome.status === 'completed'
             ? 'done'
             : outcome.status === 'failed'
@@ -252,7 +255,9 @@ export class NativePugiEngineAdapter {
                 ? '[budget_exhausted] '
                 : outcome.status === 'tool_refused'
                     ? '[plan_mode_refused] '
-                    : '[failed] ';
+                    : outcome.status === 'aborted'
+                        ? '[operator_aborted] '
+                        : '[failed] ';
         const filesChangedList = Array.from(filesChanged).sort();
         appendSessionMirror(sessionEventsPath, {
             type: 'outcome',

package/dist/core/engine/prompts.js

@@ -22,7 +22,10 @@ import { getJobRegistry, summarizeJobsForPrompt, } from '../jobs/registry.js';
 const COMMON_LOCAL_FIRST_PREAMBLE = [
     'You are the Pugi CLI agent running locally inside the operator\'s repository.',
     'The local filesystem is the source of truth. Every change you make is committed locally; nothing is uploaded by default (ADR-0037 local-first).',
-    'You have a tool registry: read, write, edit, grep, glob, bash. Call tools to inspect and modify the workspace.',
+    'You have a tool registry: read, write, edit, grep, glob, bash, apply_patch, lsp_hover, lsp_definition, lsp_references, lsp_diagnostics, worktree_create, worktree_promote, worktree_drop. Call tools to inspect and modify the workspace.',
+    'Use lsp_hover / lsp_definition / lsp_references when you need precise symbol intel — they are faster and more reliable than grep for typed languages (TS/JS/Python/Go/Rust). Fall back to grep when the LSP server is unavailable.',
+    'Use apply_patch when you have a complete unified diff in hand (e.g. forwarded from an external review). For incremental edits, prefer edit/write over apply_patch — the failure modes are clearer.',
+    'Use worktree_create + worktree_promote when a multi-file change needs validation before landing on the operator\'s working tree. Drop the worktree with worktree_drop when done; never leave scratch worktrees around.',
     'Cite file paths relative to the workspace root. Keep edits minimal and reversible.',
     'When you are done, return a single final text answer that the operator can read on the CLI.',
 ].join(' ');

package/dist/core/engine/tool-bridge.js

@@ -1,4 +1,4 @@
-import { editTool, globTool, grepTool, readTool, writeTool, } from '../../tools/file-tools.js';
+import { editTool, globTool, grepTool, OperatorAbortedError, readTool, writeTool, } from '../../tools/file-tools.js';
 import { bashToolSync } from '../../tools/bash.js';
 /**
  * Tool-bridge: turns the abstract tool registry into:
@@ -147,6 +147,14 @@ export function buildExecutor(input) {
             // outcome, not a failure, because plan mode is doing its job.
             throw new Error(`PLAN_MODE_REFUSED: ${name} is not allowed in plan mode`);
         }
+        // α6.9: refuse cancelled-token tool dispatch BEFORE PreToolUse
+        // hooks fire so a cancelled brief never reaches user-defined
+        // hook scripts. Sentinel `OPERATOR_ABORTED:<tool>` is recognised
+        // by `runEngineLoop` as a terminal-cancel signal so the loop
+        // returns control to the caller rather than retrying the model.
+        if (ctx.cancellation && ctx.cancellation.isAborted) {
+            throw new Error(`OPERATOR_ABORTED: ${name} refused — operator cancelled the dispatch.`);
+        }
         // Fire PreToolUse hooks. The match grammar takes the tool name and
         // (when extractable) the target path. Each new tool dispatch starts a
         // fresh dedup batch so a hook fires once per dispatch, not once per
@@ -194,6 +202,30 @@ export function buildExecutor(input) {
             return result;
         }
         catch (error) {
+            // α6.9: re-shape OperatorAbortedError throws from the
+            // file-tools layer into the same `OPERATOR_ABORTED:` sentinel
+            // the upstream cancellation gate uses so `runEngineLoop` sees
+            // a consistent terminal-cancel signal regardless of whether
+            // the abort landed pre-dispatch or mid-tool (e.g. inside the
+            // grep file-loop).
+            if (error instanceof OperatorAbortedError) {
+                if (hooks && sessionId) {
+                    const path = extractToolPath(name, argsRaw);
+                    await hooks.fire({
+                        sessionId,
+                        event: 'PostToolUseFailure',
+                        tool: name,
+                        path,
+                        payload: {
+                            tool: name,
+                            arguments: argsRaw,
+                            ok: false,
+                            error: `OPERATOR_ABORTED: ${name}`,
+                        },
+                    });
+                }
+                throw new Error(`OPERATOR_ABORTED: ${name} aborted mid-execution.`);
+            }
             if (hooks && sessionId) {
                 const path = extractToolPath(name, argsRaw);
                 await hooks.fire({