@pugi/cli 0.1.0-beta.12 → 0.1.0-beta.13

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

@@ -0,0 +1,273 @@
+/**
+ * Verify hook — β1b Pl10 (2026-05-26).
+ *
+ * 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/engine/anvil-client.js

@@ -1,3 +1,10 @@
+// PR-CLI-SERVER-VERSION-HANDSHAKE (#225). The interceptor stamps the
+// outbound X-Pugi-Cli-Version header, inspects the inbound recommended/
+// server-version headers, and throws PugiCliUpgradeRequiredError on a
+// 426 server response. The top-level catch in `runtime/cli.ts` /
+// `index.ts` renders the upgrade message and exits 1.
+import { assertNotUpgradeRequired, injectClientVersionHeader, inspectVersionResponse, } from '../transport/version-interceptor.js';
+import { PUGI_CLI_VERSION } from '../../runtime/version.js';
 /**
  * Anvil-backed engine loop client.
  *
@@ -54,13 +61,17 @@ export class AnvilEngineLoopClient {
             options.signal.addEventListener('abort', onAbort);
         const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
         try {
+            // PR-CLI-SERVER-VERSION-HANDSHAKE (#225). Stamp the outbound
+            // X-Pugi-Cli-Version header so the admin-api middleware can
+            // decide whether to honour, soft-warn, or 426 this request.
+            const outboundHeaders = injectClientVersionHeader({
+                'content-type': 'application/json',
+                authorization: `Bearer ${this.config.apiKey}`,
+                'user-agent': 'pugi-cli/0.0.1',
+            }, PUGI_CLI_VERSION);
             const res = await fetch(url, {
                 method: 'POST',
-                headers: {
-                    'content-type': 'application/json',
-                    authorization: `Bearer ${this.config.apiKey}`,
-                    'user-agent': 'pugi-cli/0.0.1',
-                },
+                headers: outboundHeaders,
                 body: JSON.stringify({
                     personaSlug: options.personaSlug,
                     messages,
@@ -87,6 +98,40 @@ export class AnvilEngineLoopClient {
                 signal: controller.signal,
             });
             const text = await res.text();
+            // PR-CLI-SERVER-VERSION-HANDSHAKE: cache server-recommended +
+            // server-version headers so UpdateBanner / `pugi doctor` can
+            // surface them, then short-circuit on 426 by throwing
+            // PugiCliUpgradeRequiredError. The throw bubbles to the
+            // top-level catch in index.ts which renders the upgrade banner.
+            // The getter shim handles both real `Response` (`.headers.get`)
+            // and minimal fixture/stub responses (`.headers?.[name]`) so
+            // existing transport tests that mock `fetch` with `{status, text}`
+            // don't need to grow a Headers polyfill just to keep passing.
+            //
+            // Cache poison guard: skip the inspect step on 426. A hostile
+            // upstream (proxy with a compromised cert pin, or a transient MITM
+            // on a coffee-shop network) could otherwise forge an
+            // `X-Pugi-Cli-Upgrade-Recommended` header alongside a 426 status
+            // and poison `cachedServerRecommendation` for the rest of the REPL
+            // session — `UpdateBanner` would then surface attacker-chosen
+            // version strings to the operator. The 426 body still carries the
+            // legitimate `recommendedVersion` field, which assertNotUpgrade-
+            // Required parses + throws with, so the operator-facing banner
+            // remains accurate via the error path.
+            if (res.status !== 426) {
+                inspectVersionResponse((name) => {
+                    const h = res.headers;
+                    if (h && typeof h.get === 'function') {
+                        return h.get(name);
+                    }
+                    if (h && typeof h === 'object') {
+                        const lowered = h[name.toLowerCase()];
+                        return lowered ?? null;
+                    }
+                    return null;
+                });
+            }
+            assertNotUpgradeRequired(res.status, text, PUGI_CLI_VERSION);
             if (res.status === 200) {
                 try {
                     const json = JSON.parse(text);
@@ -135,6 +180,36 @@ export class AnvilEngineLoopClient {
                 };
             }
             if (res.status === 401 || res.status === 403) {
+                // 403 has two distinct causes:
+                //   1. genuinely invalid / expired token (auth_missing) — the
+                //      old default.
+                //   2. tenant authenticated successfully but the privacy mode
+                //      (strict / balanced policy) refused upstream LLM dispatch.
+                //      The admin-api returns
+                //      `{ code: 'privacy_strict_upstream_blocked', mode, model,
+                //         message: '...switch via pugi config set privacy=...' }`.
+                //      Reported as `auth_missing` the user runs `pugi login`
+                //      again, which does nothing — the actual fix is a privacy-
+                //      mode change. Parse the body and route accordingly.
+                // (2026-05-27 P0.3 — dogfood surfaced this on /api/pugi/engine
+                // for a strict-mode tenant; see memory feedback_no_fake_dispatch_promises
+                // for the broader "misleading error" pattern.)
+                try {
+                    const parsed = text ? JSON.parse(text) : null;
+                    if (parsed?.code === 'privacy_strict_upstream_blocked' || parsed?.code === 'privacy_blocked') {
+                        return {
+                            stop: 'error',
+                            code: 'privacy_blocked',
+                            message: parsed.message ?? 'Tenant privacy mode forbids upstream LLM dispatch.',
+                            remediation: 'pugi config set privacy=balanced — OR configure a self-hosted Anvil model.',
+                        };
+                    }
+                }
+                catch {
+                    // Body not JSON — fall through to the generic auth_missing
+                    // branch below; the 200-char text echo on `failed` will at
+                    // least give the operator the raw response to triage.
+                }
                 return {
                     stop: 'error',
                     code: 'auth_missing',

package/dist/core/engine/context-prefix.js

@@ -0,0 +1,155 @@
+/** Hard cap on the rendered `<context>` block, bytes. */
+export const CONTEXT_PREFIX_MAX_BYTES = 5 * 1024;
+/** Hard cap on working-set entries surfaced in the prefix. */
+export const CONTEXT_PREFIX_MAX_WORKING_SET = 50;
+/** Hard cap on per-dir markdown files surfaced inline. */
+export const CONTEXT_PREFIX_MAX_MARKDOWN = 3;
+/** Per-markdown-file inline excerpt cap, bytes. Keeps any one file from dominating. */
+export const CONTEXT_PREFIX_MAX_PER_MARKDOWN_BYTES = 1024;
+/**
+ * Build the `<context>` block. Always returns a result — when there
+ * is nothing to surface (no cwd hint, no working set, no per-dir
+ * files), returns `{ block: '', bytes: 0, truncated: false, counts: ... }`
+ * so the caller can short-circuit the splice cleanly.
+ *
+ * Determinism: same input always produces byte-identical output. The
+ * working-set order comes from the caller's summary; we preserve it
+ * verbatim. Per-dir files are sorted by `distanceFromCwd` ascending
+ * (closest first) so two equal `TraversedMarkdown` arrays produce
+ * identical blocks.
+ */
+export function buildContextPrefix(input) {
+    const lines = [];
+    let bytes = 0;
+    let truncated = false;
+    // Walk a write-then-measure loop so we never overflow the byte cap.
+    // Each push checks budget; when full, set `truncated = true` and
+    // stop. The opener / closer tags always fit (small) — we reserve
+    // their byte cost up-front from the budget.
+    const opener = '<context>';
+    const closer = '</context>';
+    const reservedTagBytes = Buffer.byteLength(opener, 'utf8') + 1 + Buffer.byteLength(closer, 'utf8') + 1;
+    let budget = CONTEXT_PREFIX_MAX_BYTES - reservedTagBytes;
+    if (budget < 0) {
+        return {
+            block: '',
+            bytes: 0,
+            truncated: false,
+            counts: {
+                workingSetIncluded: 0,
+                workingSetTotal: input.workingSet?.length ?? 0,
+                markdownIncluded: 0,
+                markdownTotal: input.traversedMarkdown?.length ?? 0,
+            },
+        };
+    }
+    const pushLine = (line) => {
+        const lineBytes = Buffer.byteLength(line, 'utf8') + 1; // newline
+        if (lineBytes > budget) {
+            truncated = true;
+            return false;
+        }
+        lines.push(line);
+        budget -= lineBytes;
+        bytes += lineBytes;
+        return true;
+    };
+    // cwd — always cheap, always first.
+    pushLine(`cwd: ${input.cwdRelative || '.'}`);
+    // intent hint, if provided.
+    if (input.intentHint) {
+        pushLine(`intent: ${input.intentHint}`);
+    }
+    // Working set — render `open-files:` only when there is at least one entry.
+    const wsTotal = input.workingSet?.length ?? 0;
+    let wsIncluded = 0;
+    if (wsTotal > 0 && input.workingSet) {
+        const wsCap = Math.min(CONTEXT_PREFIX_MAX_WORKING_SET, wsTotal);
+        pushLine('open-files:');
+        for (let i = 0; i < wsCap; i += 1) {
+            const entry = input.workingSet[i];
+            if (!entry)
+                continue;
+            const ok = pushLine(`  - ${entry.absPath}`);
+            if (!ok)
+                break;
+            wsIncluded += 1;
+        }
+        if (wsTotal > wsCap) {
+            pushLine(`  ... (+${wsTotal - wsCap} more)`);
+            truncated = truncated || true;
+        }
+    }
+    // Per-dir markdown — closest-first, max 3, each capped to 1 KB excerpt.
+    const mdTotal = input.traversedMarkdown?.length ?? 0;
+    let mdIncluded = 0;
+    if (mdTotal > 0 && input.traversedMarkdown) {
+        const sorted = [...input.traversedMarkdown].sort((a, b) => a.distanceFromCwd - b.distanceFromCwd);
+        const top = sorted.slice(0, CONTEXT_PREFIX_MAX_MARKDOWN);
+        if (top.length > 0) {
+            pushLine('per-dir-conventions:');
+            for (const md of top) {
+                // Header line names the source file for traceability.
+                const header = `  [${md.resolvedPath}]`;
+                if (!pushLine(header))
+                    break;
+                // Excerpt: cap to 1 KB, single-line collapse (replace newlines
+                // with " | " so the YAML-ish block stays parseable by humans).
+                const excerpt = excerpt1KB(md.content);
+                // Indent two spaces so it nests under the file header.
+                const indented = excerpt.split('\n').map((l) => `    ${l}`).join('\n');
+                if (!pushLine(indented))
+                    break;
+                mdIncluded += 1;
+            }
+            if (mdTotal > top.length) {
+                pushLine(`  ... (+${mdTotal - top.length} more files; closest-3 shown)`);
+                truncated = truncated || true;
+            }
+        }
+    }
+    if (lines.length === 0) {
+        return {
+            block: '',
+            bytes: 0,
+            truncated: false,
+            counts: {
+                workingSetIncluded: 0,
+                workingSetTotal: wsTotal,
+                markdownIncluded: 0,
+                markdownTotal: mdTotal,
+            },
+        };
+    }
+    const block = [opener, ...lines, closer].join('\n');
+    const totalBytes = Buffer.byteLength(block, 'utf8');
+    return {
+        block,
+        bytes: totalBytes,
+        truncated,
+        counts: {
+            workingSetIncluded: wsIncluded,
+            workingSetTotal: wsTotal,
+            markdownIncluded: mdIncluded,
+            markdownTotal: mdTotal,
+        },
+    };
+}
+/**
+ * Splice a built context block onto the front of a user message.
+ * Empty block → message returned verbatim (no leading blank line, no
+ * empty `<context>` tag).
+ */
+export function spliceContextPrefix(block, userMessage) {
+    if (block.length === 0)
+        return userMessage;
+    return `${block}\n\n${userMessage}`;
+}
+function excerpt1KB(content) {
+    const capped = content.length <= CONTEXT_PREFIX_MAX_PER_MARKDOWN_BYTES
+        ? content
+        : content.slice(0, CONTEXT_PREFIX_MAX_PER_MARKDOWN_BYTES);
+    // Trim trailing newlines so the YAML-ish render stays tight.
+    return capped.replace(/\s+$/g, '');
+}
+//# sourceMappingURL=context-prefix.js.map