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

package/dist/tools/enter-worktree.js

@@ -0,0 +1,250 @@
+/**
+ * enter_worktree tool — scratch git worktree primitive (tool gap pack
+ *).
+ *
+ * Spawns `git worktree add <path> [<baseRef>]` at
+ * `.pugi/worktrees/<taskId>/` so a long-running agent task can land
+ * its edits into an isolated scratch tree. The matching `exit_worktree`
+ * tool is the cleanup primitive. The actual fan-out (one worktree per
+ * task in a backlog batch) lives behind a separate task — this tool is
+ * the primitive both call paths share.
+ *
+ * Wire shape:
+ *  args:  { taskId: string, baseRef?: string }
+ *          - taskId: lowercase slug, `[a-z0-9][a-z0-9-]{0,63}`. The
+ *            pattern bans path-traversal segments (`..`, `/`, `\\`) so
+ *            the basename cannot escape `.pugi/worktrees/`.
+ *          - baseRef: optional git ref (branch / tag / SHA). Defaults
+ *            to `main` so the standard case is "fork from main and go".
+ *            The CLI validates the ref shape only loosely — git
+ *            rejects unknown refs upstream and that error message is
+ *            surfaced verbatim.
+ *  return: { ok: true, worktreePath, branchName } serialised JSON.
+ *
+ * Spawn discipline: every git invocation uses `spawnSync` with
+ * `shell: false` and a string-array argv so an unsanitised character
+ * inside a ref name cannot inject shell metacharacters. The taskId is
+ * gated by a strict regex BEFORE the spawn so the path argument is
+ * trusted.
+ *
+ * Path discipline: the worktree path is computed locally
+ * (`path.resolve(workspaceRoot, '.pugi/worktrees', taskId)`) and then
+ * containment-checked against the workspace root and the
+ * `.pugi/worktrees` subtree. Anything else throws — a deformed taskId
+ * that survived the regex (it should not) cannot pull the basename
+ * outside the expected subtree.
+ *
+ * Brand voice: English only, no emoji, no banned words.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+/** Strict taskId pattern. Lowercase alphanumeric + hyphen, must start
+ * with a lowercase letter or digit, length 1..64. The first-character
+ * constraint stops a leading hyphen from being interpreted as a flag
+ * by `git worktree add` (defense in depth — argv form already protects
+ * us, but a leading hyphen is still a smell). */
+export const TASK_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** Default base ref when the caller does not supply one. */
+export const DEFAULT_BASE_REF = 'main';
+/** Sentinels. Distinct prefixes so the model / dispatcher can
+ * pattern-match without parsing the trailing message. */
+export const ENTER_WORKTREE_INVALID_ARGS = 'ENTER_WORKTREE_INVALID_ARGS';
+export const ENTER_WORKTREE_GIT_FAILED = 'ENTER_WORKTREE_GIT_FAILED';
+export const ENTER_WORKTREE_ALREADY_EXISTS = 'ENTER_WORKTREE_ALREADY_EXISTS';
+export const ENTER_WORKTREE_PATH_ESCAPED = 'ENTER_WORKTREE_PATH_ESCAPED';
+/**
+ * Validate the raw arguments. Returns the typed value on success or a
+ * `ENTER_WORKTREE_INVALID_ARGS: ...` sentinel string.
+ */
+/**
+ * Permissive git ref-name validation. We do not aim to fully implement
+ * `git check-ref-format` — instead reject anything outside a safe
+ * character class plus a leading-dash check. The leading-dash rule is
+ * the real defense: it stops an operator-controlled `baseRef` from
+ * being reinterpreted as a CLI flag (e.g. `--detach`, `--force`).
+ */
+function isValidGitRef(s) {
+    if (s.startsWith('-'))
+        return false;
+    return /^[A-Za-z0-9._/-]+$/.test(s);
+}
+export function parseEnterWorktreeArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${ENTER_WORKTREE_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const issues = [];
+    const taskId = obj['taskId'];
+    if (typeof taskId !== 'string') {
+        issues.push('taskId: must be a string');
+    }
+    else if (!TASK_ID_PATTERN.test(taskId)) {
+        issues.push(`taskId: must match ${TASK_ID_PATTERN}`);
+    }
+    let baseRef;
+    if (obj['baseRef'] !== undefined && obj['baseRef'] !== null) {
+        if (typeof obj['baseRef'] !== 'string') {
+            issues.push('baseRef: must be a string when present');
+        }
+        else if (obj['baseRef'].length === 0) {
+            issues.push('baseRef: must be non-empty when present');
+        }
+        else if (obj['baseRef'].length > 250) {
+            // Git imposes its own limits; we cut off well below them to keep
+            // error messages and audit lines bounded.
+            issues.push('baseRef: must be <= 250 chars when present');
+        }
+        else if (!isValidGitRef(obj['baseRef'])) {
+            // Permissive ref-chars regex that also rejects leading `-` so
+            // an operator-controlled `baseRef` cannot be reinterpreted as
+            // a git flag (e.g. `--detach`, `--force`). Combined with the
+            // `--` separator in argv this is belt-and-suspenders against
+            // arg-injection. Triple-review Claude P2,.
+            issues.push('baseRef: must match [A-Za-z0-9._/-] and not start with `-`');
+        }
+        else {
+            baseRef = obj['baseRef'];
+        }
+    }
+    if (issues.length > 0) {
+        return `${ENTER_WORKTREE_INVALID_ARGS}: ${issues.join('; ')}`;
+    }
+    const out = baseRef !== undefined
+        ? { taskId: taskId, baseRef }
+        : { taskId: taskId };
+    return out;
+}
+/**
+ * Compute the absolute on-disk path for a task's worktree. Public so
+ * `exit_worktree` and any future TUI surface can share the layout.
+ */
+export function worktreePathFor(workspaceRoot, taskId) {
+    return join(resolve(workspaceRoot), '.pugi', 'worktrees', taskId);
+}
+/**
+ * Compute the canonical worktree root (`<workspaceRoot>/.pugi/worktrees`).
+ * Used by `exit_worktree` for the containment check.
+ */
+export function worktreesRoot(workspaceRoot) {
+    return join(resolve(workspaceRoot), '.pugi', 'worktrees');
+}
+/**
+ * Dispatch entry point. Validates input, ensures the parent directory
+ * exists, then spawns `git worktree add` with the strict argv form.
+ * Returns the structured result envelope as JSON, or a sentinel string
+ * on a recoverable failure.
+ */
+export function dispatchEnterWorktree(ctx, raw) {
+    const parsed = parseEnterWorktreeArgs(raw);
+    if (typeof parsed === 'string') {
+        return parsed;
+    }
+    const baseRef = parsed.baseRef ?? DEFAULT_BASE_REF;
+    const root = resolve(ctx.workspaceRoot);
+    const targetPath = worktreePathFor(root, parsed.taskId);
+    const subtreeRoot = worktreesRoot(root);
+    // Defense in depth: re-check that the resolved target stays inside
+    // `<workspaceRoot>/.pugi/worktrees/`. The regex on taskId already
+    // bans `..` and `/`, so a successful escape here would indicate a
+    // catastrophic node:path regression — we still treat it as a fatal
+    // refusal rather than trusting the upstream gate alone.
+    if (!isContainedIn(targetPath, subtreeRoot)) {
+        return `${ENTER_WORKTREE_PATH_ESCAPED}: ${targetPath} is not under ${subtreeRoot}`;
+    }
+    if (existsSync(targetPath)) {
+        return `${ENTER_WORKTREE_ALREADY_EXISTS}: ${targetPath}`;
+    }
+    // Ensure `.pugi/worktrees/` exists; git worktree add will not create
+    // the parent for us.
+    if (!existsSync(subtreeRoot)) {
+        mkdirSync(subtreeRoot, { recursive: true });
+    }
+    // Compose the branch name we hand to git. The convention pairs
+    // 1:1 with taskId so `exit_worktree` does not need a separate
+    // lookup. `-b <branch>` creates the branch as a side effect of the
+    // worktree-add; without it git would refuse a worktree that points
+    // to an existing branch already checked out elsewhere.
+    const branchName = `pugi/worktree/${parsed.taskId}`;
+    // `--` separator forces git to treat everything after it as strict
+    // positionals. Belt-and-suspenders against arg-injection via
+    // `baseRef` (the regex above already rejects leading `-`).
+    const argv = [
+        'worktree',
+        'add',
+        '-b',
+        branchName,
+        '--',
+        targetPath,
+        baseRef,
+    ];
+    const runner = ctx.runGit ?? defaultGitRunner;
+    const result = runner(argv, root);
+    if (result.status !== 0) {
+        const detail = (result.stderr || result.stdout || `exit=${result.status}`).trim();
+        return `${ENTER_WORKTREE_GIT_FAILED}: ${detail}`;
+    }
+    const out = {
+        ok: true,
+        worktreePath: targetPath,
+        branchName,
+        baseRef,
+    };
+    return JSON.stringify(out);
+}
+/**
+ * Default spawnSync wrapper. `shell: false` is non-negotiable — every
+ * argv element is forwarded verbatim к the child without shell
+ * interpretation. The stdout/stderr captures are forced to utf-8 so the
+ * caller works with strings without manual decoding.
+ */
+function defaultGitRunner(argv, cwd) {
+    const result = spawnSync('git', [...argv], {
+        cwd,
+        shell: false,
+        encoding: 'utf8',
+        timeout: 30_000,
+    });
+    return {
+        status: result.status,
+        stdout: typeof result.stdout === 'string' ? result.stdout : '',
+        stderr: typeof result.stderr === 'string' ? result.stderr : '',
+    };
+}
+/**
+ * Containment check. Resolves both paths and asserts the target lives
+ * under the root via a separator-aware prefix match. The separator
+ * append on the root protects against the `/foo/bar2` vs `/foo/bar`
+ * partial-prefix bug.
+ */
+function isContainedIn(target, root) {
+    const rResolved = resolve(root);
+    const tResolved = resolve(target);
+    if (tResolved === rResolved)
+        return false;
+    const rootWithSep = rResolved.endsWith(sep) ? rResolved : `${rResolved}${sep}`;
+    return tResolved.startsWith(rootWithSep);
+}
+/**
+ * JSON-Schema fragment the schema builder advertises to the model.
+ */
+export const enterWorktreeJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['taskId'],
+    properties: {
+        taskId: {
+            type: 'string',
+            pattern: '^[a-z0-9][a-z0-9-]{0,63}$',
+            description: 'Slug used as the worktree basename. ' +
+                'Lowercase alphanumeric + hyphen, must start with letter/digit, 1..64 chars.',
+        },
+        baseRef: {
+            type: 'string',
+            minLength: 1,
+            maxLength: 250,
+            description: `Optional git base ref (branch / tag / SHA). Defaults to "${DEFAULT_BASE_REF}".`,
+        },
+    },
+};
+//# sourceMappingURL=enter-worktree.js.map

package/dist/tools/exit-worktree.js

@@ -0,0 +1,147 @@
+/**
+ * exit_worktree tool — opposite of `enter_worktree` (tool gap pack
+ *).
+ *
+ * Tears down a scratch git worktree at the supplied path. The path is
+ * STRICTLY validated к live under `<workspaceRoot>/.pugi/worktrees/`
+ * — anything outside that subtree refuses with a sentinel and zero
+ * filesystem mutation. This is a destructive primitive, so the
+ * containment check is the load-bearing safety boundary.
+ *
+ * Procedure:
+ *  1. Validate the argument shape.
+ *  2. Resolve the input path and assert it lives under
+ *     `<workspaceRoot>/.pugi/worktrees/`. Refuse otherwise.
+ *  3. Run `git worktree remove --force <path>` so git's bookkeeping
+ *     drops the worktree. `--force` is required because the model may
+ *     have left dirty edits inside the scratch tree — that is the
+ *     normal case for a refactor that the operator is about to merge
+ *     via a different tool. Best-effort: a non-zero exit from git is
+ *     logged in the return envelope but does NOT abort the disk
+ *     cleanup. Git may have already cleaned the entry when the dir
+ *     itself was removed manually.
+ *  4. `rmSync(path, { recursive: true, force: true })` for any
+ *     leftover files.
+ *
+ * Wire shape:
+ *  args:  { worktreePath: string }
+ *  return: { ok: true, removed: boolean, gitStatus: number|null,
+ *            gitDetail?: string } serialised JSON.
+ *
+ * Idempotent: calling on a path that no longer exists returns
+ * `{ ok: true, removed: false }` with no error. This matches the
+ * semantics agent-progress / cleanup operations already follow elsewhere
+ * in the CLI.
+ *
+ * Brand voice: English only, no emoji, no banned words.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, rmSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { worktreesRoot } from './enter-worktree.js';
+/** Sentinels. Distinct prefixes so the model / dispatcher can
+ * pattern-match. */
+export const EXIT_WORKTREE_INVALID_ARGS = 'EXIT_WORKTREE_INVALID_ARGS';
+export const EXIT_WORKTREE_PATH_ESCAPED = 'EXIT_WORKTREE_PATH_ESCAPED';
+/**
+ * Validate the raw arguments. Returns the typed value on success or a
+ * `EXIT_WORKTREE_INVALID_ARGS: ...` sentinel string.
+ */
+export function parseExitWorktreeArgs(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return `${EXIT_WORKTREE_INVALID_ARGS}: arguments must be a JSON object`;
+    }
+    const obj = raw;
+    const worktreePath = obj['worktreePath'];
+    if (typeof worktreePath !== 'string') {
+        return `${EXIT_WORKTREE_INVALID_ARGS}: worktreePath: must be a string`;
+    }
+    if (worktreePath.length === 0) {
+        return `${EXIT_WORKTREE_INVALID_ARGS}: worktreePath: must be non-empty`;
+    }
+    return { worktreePath };
+}
+/**
+ * Dispatch entry point. Validates input, asserts the path lives under
+ * the allowed root, then runs `git worktree remove --force` followed
+ * by a filesystem removal for any leftovers. Returns the structured
+ * envelope as JSON.
+ *
+ * Returns sentinel strings on validation failures or a containment
+ * refusal — no throw — so the engine adapter surfaces a recoverable
+ * tool result and the model can adapt.
+ */
+export function dispatchExitWorktree(ctx, raw) {
+    const parsed = parseExitWorktreeArgs(raw);
+    if (typeof parsed === 'string') {
+        return parsed;
+    }
+    const root = resolve(ctx.workspaceRoot);
+    const subtreeRoot = worktreesRoot(root);
+    const target = resolve(parsed.worktreePath);
+    if (!isContainedIn(target, subtreeRoot)) {
+        return `${EXIT_WORKTREE_PATH_ESCAPED}: ${target} is not under ${subtreeRoot}`;
+    }
+    // git worktree remove. Best-effort. Non-zero exit is captured in the
+    // return envelope but does not block the rmTree step — a half-cleaned
+    // worktree (entry gone but dir survived) is a common operator-side
+    // mistake we want to recover from.
+    const runner = ctx.runGit ?? defaultGitRunner;
+    const gitResult = runner(['worktree', 'remove', '--force', target], root);
+    const existedBefore = existsSync(target);
+    const rmTree = ctx.rmTree ?? defaultRmTree;
+    if (existedBefore) {
+        rmTree(target);
+    }
+    const removed = existedBefore && !existsSync(target);
+    const envelope = gitResult.status === 0
+        ? { ok: true, removed, gitStatus: gitResult.status }
+        : {
+            ok: true,
+            removed,
+            gitStatus: gitResult.status,
+            gitDetail: (gitResult.stderr || gitResult.stdout || '').trim(),
+        };
+    return JSON.stringify(envelope);
+}
+function defaultGitRunner(argv, cwd) {
+    const result = spawnSync('git', [...argv], {
+        cwd,
+        shell: false,
+        encoding: 'utf8',
+        timeout: 30_000,
+    });
+    return {
+        status: result.status,
+        stdout: typeof result.stdout === 'string' ? result.stdout : '',
+        stderr: typeof result.stderr === 'string' ? result.stderr : '',
+    };
+}
+function defaultRmTree(path) {
+    rmSync(path, { recursive: true, force: true });
+}
+function isContainedIn(target, root) {
+    const rResolved = resolve(root);
+    const tResolved = resolve(target);
+    if (tResolved === rResolved)
+        return false;
+    const rootWithSep = rResolved.endsWith(sep) ? rResolved : `${rResolved}${sep}`;
+    return tResolved.startsWith(rootWithSep);
+}
+/**
+ * JSON-Schema fragment the schema builder advertises to the model.
+ */
+export const exitWorktreeJsonSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['worktreePath'],
+    properties: {
+        worktreePath: {
+            type: 'string',
+            minLength: 1,
+            description: 'Absolute path to the worktree to tear down. Must live under ' +
+                '<workspaceRoot>/.pugi/worktrees/ — anything else refuses.',
+        },
+    },
+};
+//# sourceMappingURL=exit-worktree.js.map