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

package/dist/core/edits/security-gate.js

@@ -1,8 +1,8 @@
 /**
- * Shared security gate for the α6.6 diff escalation Layer A/B/C
+ * Shared security gate for the diff escalation Layer A/B/C
  * applicators.
  *
- * Before α6.6.1 (triple-review remediation 2026-05-25) every layer
+ * Before (triple-review remediation) every layer
  * built its own path resolver via `isAbsolute(file) ? file : resolve(cwd, file)`.
  * That bypassed the workspace-scoped resolver + protected-basename
  * gate + symlink-escape check used by the `edit`/`write` tools in
@@ -14,34 +14,34 @@
  * This module is the single chokepoint every layer goes through.
  * Centralised here so:
  *
- *   1. Future layers (D = AST, planned β-tier) inherit the gate for
- *      free instead of re-implementing it.
- *   2. New protected-file rules added to `decidePermission` propagate
- *      to dispatcher writes uniformly.
- *   3. A single spec surface covers every layer's path-handling
- *      contract (`apps/pugi-cli/test/edits-security-gate.spec.ts`).
+ *  1. Future layers (D = AST, planned β-tier) inherit the gate for
+ *     free instead of re-implementing it.
+ *  2. New protected-file rules added to `decidePermission` propagate
+ *     to dispatcher writes uniformly.
+ *  3. A single spec surface covers every layer's path-handling
+ *     contract (`apps/pugi-cli/test/edits-security-gate.spec.ts`).
  *
  * Defense layers, in order (fail-fast — first reject wins):
  *
- *   a. `resolveWorkspacePath` — workspace-scoped resolver with URL-decode
- *      and realpath gate at the target. Throws on traversal; we
- *      translate the throw into `path_outside_workspace`.
- *   b. `decidePermission` (kind: 'edit') — protected basename / suffix /
- *      credential-path check (`.env`, `*.pem`, `id_rsa`, `~/.ssh/**`,
- *      etc.). Mirrors what `writeTool` / `editTool` already enforce.
- *   c. Explicit `realpathSync.native` re-check on the target (or
- *      target's parent when the target does not yet exist) to defend
- *      against TOCTOU symlink swap between `resolveWorkspacePath` and
- *      the apply-time write.
- *   d. Re-run `decidePermission` on the REAL target's workspace-relative
- *      form. R2 triple-review (2026-05-25, Codex P1) caught the
- *      symlink → protected-file bypass: a workspace-local symlink
- *      `alias -> .env` passes step (b) because `alias` is not a
- *      protected basename, and passes step (c) because `.env`
- *      legitimately lives inside the workspace realpath. Without step
- *      (d) the gate would allow the atomic write to land on `.env`
- *      via the symlink's resolved target. Re-running the protected-file
- *      check against the resolved name closes that loop.
+ *  a. `resolveWorkspacePath` — workspace-scoped resolver with URL-decode
+ *     and realpath gate at the target. Throws on traversal; we
+ *     translate the throw into `path_outside_workspace`.
+ *  b. `decidePermission` (kind: 'edit') — protected basename / suffix /
+ *     credential-path check (`.env`, `*.pem`, `id_rsa`, `~/.ssh/**`,
+ *     etc.). Mirrors what `writeTool` / `editTool` already enforce.
+ *  c. Explicit `realpathSync.native` re-check on the target (or
+ *     target's parent when the target does not yet exist) to defend
+ *     against TOCTOU symlink swap between `resolveWorkspacePath` and
+ *     the apply-time write.
+ *  d. Re-run `decidePermission` on the REAL target's workspace-relative
+ *     form. R2 triple-review (2026-05-25, Codex P1) caught the
+ *     symlink → protected-file bypass: a workspace-local symlink
+ *     `alias -> .env` passes step (b) because `alias` is not a
+ *     protected basename, and passes step (c) because `.env`
+ *     legitimately lives inside the workspace realpath. Without step
+ *     (d) the gate would allow the atomic write to land on `.env`
+ *     via the symlink's resolved target. Re-running the protected-file
+ *     check against the resolved name closes that loop.
  */
 import { realpathSync } from 'node:fs';
 import { basename, resolve, sep, relative } from 'node:path';

package/dist/core/edits/verify-hook.js

@@ -0,0 +1,273 @@
+/**
+ * Verify hook — β1b Pl10 .
+ *
+ * After the edit-dispatcher writes a multi-file change to the
+ * workspace, this hook fires three lightweight checks against the
+ * post-state and reports each result back to the engine loop as a
+ * status event:
+ *
+ *  1. tsc — if `tsconfig.json` is present in the workspace root, run
+ *     `tsc --noEmit` to catch compile-time breakage. Pass/fail tracked
+ *     per file is overkill at this stage; we surface the exit code +
+ *     first ~40 lines of stderr.
+ *  2. tests — if package.json has a `test` script AND a test runner
+ *     is available (jest / vitest / node --test), run `pnpm test
+ *     --bail` (or `npm test --bail`). Same exit-code + tail of output
+ *     contract.
+ *  3. URL probes — extract every `https?://...` literal from the diff
+ *     (README + code) and HEAD-probe each. A response < 400 counts as
+ *     live; >=400 surfaces as a warning. Capped at 8 unique URLs per
+ *     hook to avoid spending the budget on doc rot.
+ *
+ * Retry contract (β1b r1 rescope): the hook itself is stateless and
+ * runs ONCE per invocation, returning a structured report. The
+ * "feedback → model → re-edit" retry orchestrator does NOT exist yet
+ * in the engine loop — it was promised as part of β1b Pl10 but never
+ * shipped because the engine refactor that hosts it is bigger than
+ * the verify-hook itself can absorb. Retry orchestration is deferred
+ * to β6 plan-mode integration where the loop already needs a
+ * model→hook feedback channel for plan replay. Today the operator
+ * re-runs `pugi code` to re-drive verification after a fail. The
+ * stateless hook ships unchanged so the β6 driver can wrap it.
+ *
+ * Why HEAD and not GET for URL probes:
+ *  - HEAD avoids the body fetch; cheaper + faster.
+ *  - SSRF guard from `web-fetch.ts::validateHostnameForFetch` runs
+ *    before every probe so private IPs / localhost cannot ride.
+ *  - Some servers reject HEAD (rare but real); on 4xx-from-HEAD we
+ *    do NOT escalate to GET — that would burn the budget. We surface
+ *    a `head_rejected` warning so the operator decides.
+ *
+ * Skip cases (return early with `skipped: true` on the relevant
+ * check):
+ *  - tsc: no `tsconfig.json` at workspace root.
+ *  - tests: no `package.json` OR no `test` script.
+ *  - urls: no `https?://...` literals in the diff.
+ *
+ * Best-effort: every failure mode degrades to a structured report; the
+ * hook itself NEVER throws. The engine loop decides whether to
+ * surface as a hard fail vs a model-correctable warning.
+ *
+ * Brand voice: ASCII only, no banned words.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { validateHostnameForFetch } from '../../tools/web-fetch.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_URL_PROBES = 8;
+const URL_LITERAL_RE = /(https?:\/\/[^\s"'<>()`\\\]]+)/g;
+/**
+ * Drive one verify pass. Synchronous tsc + test child processes,
+ * concurrent URL probes (up to `maxUrlProbes`). Returns once every
+ * check has completed (no streaming events — the caller wraps the
+ * report into its own status event format).
+ */
+export async function runVerifyHook(input) {
+    const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const runProc = input.runProc ?? defaultRunProc;
+    return {
+        tsc: runTscCheck(input.workspaceRoot, runProc, timeoutMs),
+        tests: runTestsCheck(input.workspaceRoot, runProc, timeoutMs),
+        urls: await runUrlChecks(input),
+    };
+}
+/* ----------------------- tsc check ---------------------- */
+function runTscCheck(workspaceRoot, runProc, timeoutMs) {
+    const tsconfig = resolve(workspaceRoot, 'tsconfig.json');
+    if (!existsSync(tsconfig)) {
+        return { ok: true, skipped: true, reason: 'no_tsconfig' };
+    }
+    // Prefer `pnpm exec tsc` because pnpm-aware monorepos hoist tsc into
+    // `node_modules/.bin`; fallback to bare `tsc` for global installs.
+    // We try `pnpm exec tsc` first only if a `pnpm-lock.yaml` is at the
+    // workspace root; otherwise we go straight to `tsc`.
+    const pnpmLock = existsSync(resolve(workspaceRoot, 'pnpm-lock.yaml'));
+    const cmd = pnpmLock ? 'pnpm' : 'tsc';
+    const args = pnpmLock ? ['exec', 'tsc', '--noEmit'] : ['--noEmit'];
+    const result = runProc(cmd, args, workspaceRoot, timeoutMs);
+    if (result.exitCode === 0)
+        return { ok: true };
+    return {
+        ok: false,
+        reason: `tsc_exit_${result.exitCode}`,
+        detail: tailOutput(result.stdout, result.stderr, 40),
+    };
+}
+/* ----------------------- tests check ---------------------- */
+function runTestsCheck(workspaceRoot, runProc, timeoutMs) {
+    const pkgPath = resolve(workspaceRoot, 'package.json');
+    if (!existsSync(pkgPath)) {
+        return { ok: true, skipped: true, reason: 'no_package_json' };
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    }
+    catch {
+        return { ok: true, skipped: true, reason: 'malformed_package_json' };
+    }
+    if (!pkg.scripts || typeof pkg.scripts.test !== 'string') {
+        return { ok: true, skipped: true, reason: 'no_test_script' };
+    }
+    const pnpmLock = existsSync(resolve(workspaceRoot, 'pnpm-lock.yaml'));
+    // Prefer pnpm test --bail; some test runners reject the flag (node
+    // --test ignores it), so we surface non-zero exits clearly but do
+    // not retry without --bail.
+    // Both pnpm + npm accept `<cmd> test -- --bail`; the runner-side
+    // flag-forwarding contract is identical, so the ternary collapses to
+    // a single args literal.
+    const cmd = pnpmLock ? 'pnpm' : 'npm';
+    const args = ['test', '--', '--bail'];
+    const result = runProc(cmd, args, workspaceRoot, timeoutMs);
+    if (result.exitCode === 0)
+        return { ok: true };
+    return {
+        ok: false,
+        reason: `tests_exit_${result.exitCode}`,
+        detail: tailOutput(result.stdout, result.stderr, 60),
+    };
+}
+/* ----------------------- url probes ---------------------- */
+async function runUrlChecks(input) {
+    const diffText = input.diffText ?? '';
+    if (diffText.length === 0) {
+        return { ok: true, skipped: true, reason: 'no_diff_text' };
+    }
+    const urls = extractUrls(diffText);
+    if (urls.length === 0) {
+        return { ok: true, skipped: true, reason: 'no_urls' };
+    }
+    const cap = input.maxUrlProbes ?? DEFAULT_MAX_URL_PROBES;
+    const probed = urls.slice(0, cap);
+    const probeFn = input.probeFn ?? defaultProbeFn;
+    const failures = [];
+    for (const url of probed) {
+        // Hostname SSRF guard — never probe a localhost / private IP even
+        // when a literal in the diff points there.
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            failures.push({ url, error: 'invalid_url' });
+            continue;
+        }
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            failures.push({ url, error: `unsupported_scheme_${parsed.protocol}` });
+            continue;
+        }
+        const hostname = parsed.hostname.replace(/^\[|\]$/g, '');
+        const guard = await validateHostnameForFetch(hostname);
+        if (guard) {
+            failures.push({ url, error: `ssrf_refused: ${guard}` });
+            continue;
+        }
+        try {
+            const r = await probeFn(url);
+            if ('error' in r) {
+                failures.push({ url, error: r.error });
+                continue;
+            }
+            if (r.status >= 400) {
+                failures.push({ url, error: `http_${r.status}` });
+            }
+        }
+        catch (error) {
+            failures.push({
+                url,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    if (failures.length === 0) {
+        return { ok: true, probedCount: probed.length };
+    }
+    return {
+        ok: false,
+        reason: `url_probe_failed`,
+        probedCount: probed.length,
+        failures,
+        detail: failures.map((f) => `${f.url} → ${f.error}`).join('; '),
+    };
+}
+/**
+ * Extract unique http(s) URLs from a diff/text blob. Order preserved
+ * (first-seen) so the cap picks the earliest-mentioned ones, which
+ * intuitively matches the operator's expectation.
+ */
+export function extractUrls(text) {
+    const seen = new Set();
+    const out = [];
+    let match;
+    // Reset the regex's lastIndex; URL_LITERAL_RE is module-scoped and
+    // /g means stateful exec calls.
+    URL_LITERAL_RE.lastIndex = 0;
+    while ((match = URL_LITERAL_RE.exec(text)) !== null) {
+        const raw = match[1];
+        if (!raw)
+            continue;
+        // Strip a trailing punctuation that the regex tolerates inside
+        // the match (sentences in Markdown often end `... https://x).`).
+        // We also strip `!` and `?` so prose like "see https://x!" lands
+        // as `https://x`.
+        const cleaned = raw.replace(/[.,;:!?)\]>]+$/, '');
+        if (cleaned.length === 0)
+            continue;
+        if (seen.has(cleaned))
+            continue;
+        seen.add(cleaned);
+        out.push(cleaned);
+    }
+    return out;
+}
+/* ----------------------- defaults ---------------------- */
+function defaultRunProc(cmd, args, cwd, timeoutMs) {
+    const result = spawnSync(cmd, [...args], {
+        cwd,
+        encoding: 'utf8',
+        timeout: timeoutMs,
+        // Inherit a minimal env — every check is read-only against the
+        // workspace and we do not want to leak PUGI_API_KEY into a
+        // sub-process accidentally.
+        env: { ...process.env, PUGI_API_KEY: undefined, PUGI_LOGIN_TOKEN: undefined },
+    });
+    return {
+        exitCode: typeof result.status === 'number' ? result.status : -1,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+    };
+}
+async function defaultProbeFn(url) {
+    // Lazy-import undici so the verify-hook module stays cheap when
+    // url probes are skipped.
+    const { request } = await import('undici');
+    try {
+        const response = await request(url, {
+            method: 'HEAD',
+            bodyTimeout: 5_000,
+            headersTimeout: 5_000,
+        });
+        // Drain so the connection releases promptly.
+        try {
+            await response.body.dump();
+        }
+        catch {
+            /* swallow */
+        }
+        return { status: response.statusCode };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+function tailOutput(stdout, stderr, maxLines) {
+    const merged = `${stdout}\n${stderr}`.trim();
+    if (merged.length === 0)
+        return '';
+    const lines = merged.split('\n');
+    if (lines.length <= maxLines)
+        return merged;
+    return `... (${lines.length - maxLines} earlier lines elided)\n${lines.slice(-maxLines).join('\n')}`;
+}
+//# sourceMappingURL=verify-hook.js.map

package/dist/core/edits/worktree.js

@@ -1,5 +1,5 @@
 /**
- * Worktree isolation — α7.7 Phase 1.
+ * Worktree isolation — Phase 1.
  *
  * Wraps `git worktree add` so a long agent loop (build / consensus
  * review / multi-file refactor) can land its edits into a scratch
@@ -10,22 +10,22 @@
  *
  * 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).
+ *  - `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.
+ *  - `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.
+ *  - `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.
  */
@@ -103,14 +103,14 @@ export function createWorktree(opts) {
  *
  * 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.
+ *  - 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) {
@@ -147,7 +147,7 @@ export function promoteWorktree(opts) {
     if (diffText.trim().length === 0) {
         return { ok: true, value: { filesChanged: 0 } };
     }
-    // SECURITY GATE (R1 fix 2026-05-26, PR #413 r1) — every path mentioned
+    // SECURITY GATE (R1 fix, PR r1) — every path mentioned
     // in the worktree's diff goes through the same `applySecurityGate`
     // chokepoint as the apply_patch + Layer A/B/C applicators. A staged
     // `.env` (or `../../etc/passwd`, or a symlink into a protected target)
@@ -200,7 +200,7 @@ export function promoteWorktree(opts) {
  * a missing path returns `worktree_missing` which the caller can ignore
  * on the cleanup-after-error path.
  *
- * Security (R1 fix 2026-05-26, PR #413 r1): we MUST validate the path is
+ * Security (R1 fix, PR r1): we MUST validate the path is
  * a real subdirectory of `<cwd>/.pugi/worktrees/` BEFORE running either
  * `git worktree remove --force` or `rmSync`. Without this gate, a
  * typo like `pugi worktree drop ../some-dir` recursively deleted an
@@ -218,10 +218,10 @@ export function promoteWorktree(opts) {
 export function dropWorktree(worktreePath, cwd) {
     // SECURITY GATE — validate containment under `<cwd>/.pugi/worktrees/`
     // BEFORE any destructive call. Two-tier check:
-    //   1. lexical containment using resolved (but not realpath'd) paths,
-    //      catches the operator-typo + missing-worktree cases.
-    //   2. realpath containment when the path exists, catches symlink
-    //      shenanigans.
+    //  1. lexical containment using resolved (but not realpath'd) paths,
+    //     catches the operator-typo + missing-worktree cases.
+    //  2. realpath containment when the path exists, catches symlink
+    //     shenanigans.
     const scratchRootLexical = resolve(cwd, '.pugi', 'worktrees');
     const worktreeLexical = resolve(cwd, worktreePath);
     const insideLexical = worktreeLexical.startsWith(scratchRootLexical + sep) &&