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

package/dist/tools/enter-worktree.js

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

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