@pugi/cli 0.1.0-beta.4 → 0.1.0-beta.41

package/dist/core/prd-check/verifiers.js

@@ -0,0 +1,223 @@
+/**
+ * PRD criterion verifiers — Pugi α7 Wave 6 (`/prd-check`, 2026-05-27).
+ *
+ * Given a `ParsedCriterion` from `parser.ts`, run a set of built-in
+ * checks against the repository workspace and return a
+ * `VerifiedCriterion` with a per-criterion verdict + per-mention
+ * evidence trail. The module owns the file-system + grep surface
+ * the parser deliberately avoided.
+ *
+ * Verdict semantics (mirror the doctor probe contract so the
+ * reporter can render both with the same column layout):
+ *
+ *   - PASS    : at least one mention verified AND every attempted
+ *               verifier passed
+ *   - FAIL    : at least one verifier failed (missing file, empty
+ *               doc, command not in registry, etc.)
+ *   - SKIPPED : no verifiable mentions in the criterion. The
+ *               criterion is preserved in the report so the
+ *               operator sees it, but it does not gate the verdict.
+ *
+ * Each `MentionResult` carries an evidence string the reporter
+ * shows next to the criterion. For PASS we render the resolved
+ * absolute path or matched line; for FAIL we render the missing
+ * artifact identifier so the operator can fix it directly.
+ *
+ * The verifier deps are injected (existsSync, readFileSync, …) so
+ * the spec can drive every branch without touching the real disk.
+ * The default-bound variant `runDefaultVerifiers` plugs the real
+ * Node fs helpers in for the CLI handler.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+/**
+ * Top-level verify-one-criterion entry. Walks the mention list,
+ * dispatches each to the right verifier, then computes the
+ * roll-up. Pure with respect to `deps` — no globals touched.
+ */
+export function verifyCriterion(criterion, deps) {
+    if (criterion.mentions.length === 0) {
+        return {
+            criterion,
+            status: 'skipped',
+            results: [],
+        };
+    }
+    const results = [];
+    for (const mention of criterion.mentions) {
+        results.push(verifyMention(mention, deps));
+    }
+    const status = rollUp(results);
+    return { criterion, status, results };
+}
+/** Verify a whole PRD's worth of criteria. */
+export function verifyAll(criteria, deps) {
+    return criteria.map((c) => verifyCriterion(c, deps));
+}
+function verifyMention(mention, deps) {
+    switch (mention.kind) {
+        case 'file':
+            return verifyFile(mention, deps);
+        case 'test':
+            return verifyTest(mention, deps);
+        case 'doc':
+            return verifyDoc(mention, deps);
+        case 'command':
+            return verifyCommand(mention, deps);
+        case 'route':
+            return verifyRoute(mention, deps);
+    }
+}
+function verifyFile(mention, deps) {
+    const absolute = deps.resolveWorkspacePath(mention.path);
+    if (deps.existsSync(absolute)) {
+        return {
+            mention,
+            status: 'pass',
+            evidence: `file present (${mention.path})`,
+        };
+    }
+    return {
+        mention,
+        status: 'fail',
+        evidence: `file missing (${mention.path})`,
+    };
+}
+function verifyTest(mention, deps) {
+    const absolute = deps.resolveWorkspacePath(mention.path);
+    if (!deps.existsSync(absolute)) {
+        return {
+            mention,
+            status: 'fail',
+            evidence: `spec missing (${mention.path})`,
+        };
+    }
+    let body;
+    try {
+        body = deps.readFileSync(absolute);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            mention,
+            status: 'fail',
+            evidence: `spec unreadable: ${message}`,
+        };
+    }
+    // Count `test(`, `it(`, and `describe(...).it(` blocks. The
+    // matcher is permissive — any of the three counts because the
+    // PRD only cares whether the spec asserts anything at all.
+    const matches = body.match(/\b(it|test)\s*\(/g);
+    if (!matches || matches.length === 0) {
+        return {
+            mention,
+            status: 'fail',
+            evidence: `spec present but has 0 test()/it() blocks`,
+        };
+    }
+    return {
+        mention,
+        status: 'pass',
+        evidence: `spec present with ${matches.length} block(s)`,
+    };
+}
+function verifyDoc(mention, deps) {
+    const absolute = deps.resolveWorkspacePath(mention.path);
+    if (!deps.existsSync(absolute)) {
+        return {
+            mention,
+            status: 'fail',
+            evidence: `doc missing (${mention.path})`,
+        };
+    }
+    let body;
+    try {
+        body = deps.readFileSync(absolute);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            mention,
+            status: 'fail',
+            evidence: `doc unreadable: ${message}`,
+        };
+    }
+    const trimmed = body.trim();
+    if (trimmed.length < 100) {
+        return {
+            mention,
+            status: 'fail',
+            evidence: `doc present but too short (${trimmed.length} chars, < 100)`,
+        };
+    }
+    return {
+        mention,
+        status: 'pass',
+        evidence: `doc present (${trimmed.length} chars)`,
+    };
+}
+function verifyCommand(mention, deps) {
+    if (deps.isKnownCommand(mention.name)) {
+        return {
+            mention,
+            status: 'pass',
+            evidence: `command \`${mention.name}\` registered`,
+        };
+    }
+    return {
+        mention,
+        status: 'fail',
+        evidence: `command \`${mention.name}\` not found in CLI registry`,
+    };
+}
+function verifyRoute(mention, deps) {
+    if (deps.hasRoute(mention.method, mention.path)) {
+        return {
+            mention,
+            status: 'pass',
+            evidence: `route ${mention.method} ${mention.path} registered`,
+        };
+    }
+    return {
+        mention,
+        status: 'fail',
+        evidence: `route ${mention.method} ${mention.path} not found`,
+    };
+}
+function rollUp(results) {
+    if (results.length === 0)
+        return 'skipped';
+    const anyFail = results.some((r) => r.status === 'fail');
+    if (anyFail)
+        return 'fail';
+    const anyPass = results.some((r) => r.status === 'pass');
+    return anyPass ? 'pass' : 'skipped';
+}
+/**
+ * Default verifier deps bound to real fs + a CLI-command predicate
+ * + a grep-based route locator. The CLI handler passes the
+ * workspace root + the known-command list at call time.
+ */
+export function createDefaultDeps(options) {
+    return {
+        resolveWorkspacePath: (relative) => {
+            if (isAbsolute(relative))
+                return relative;
+            return resolve(options.workspaceRoot, relative);
+        },
+        existsSync: (path) => existsSync(path),
+        readFileSync: (path) => readFileSync(path, 'utf8'),
+        isKnownCommand: (name) => options.knownCommands.has(name),
+        hasRoute: () => {
+            // Best-effort default: the wave-6 PRD says the route verifier
+            // is "best-effort grep of controllers". Since the workspace
+            // layout varies per repo, the CLI handler injects a project
+            // -aware implementation when one is available; the default
+            // stays conservative and reports `fail` so the reporter
+            // surfaces the missing-verifier signal instead of silently
+            // passing.
+            return false;
+        },
+    };
+}
+//# sourceMappingURL=verifiers.js.map

package/dist/core/pugi-md/context-injector.js

@@ -0,0 +1,76 @@
+/**
+ * Aggregate byte cap on the full rendered block. 96 KB = 3 files at
+ * the per-file cap, which is enough for cwd + parent + homedir while
+ * leaving plenty of prompt budget for the rest of the system prompt.
+ * Anything beyond is replaced with a truncation marker.
+ */
+export const MAX_INJECT_BYTES = 96 * 1024;
+/**
+ * Marker line emitted when the aggregate cap is hit. Visible to the
+ * model so it knows ambient context was clipped; visible to the
+ * operator via the doctor probe so they can decide whether to trim
+ * their `PUGI.md` hierarchy.
+ */
+export const TRUNCATION_MARKER = '<ambient-context-truncated reason="aggregate-cap" />';
+/**
+ * Render a HierarchyFile array into the system-prompt block. Returns
+ * `''` when `files` is empty. Each file becomes one
+ * `<ambient-context source="..." level="...">...</ambient-context>`
+ * stanza separated by a single newline.
+ *
+ * Determinism: same input always produces byte-identical output.
+ */
+export function renderAmbientContext(files) {
+    if (files.length === 0)
+        return '';
+    const stanzas = [];
+    let bytes = 0;
+    let truncated = false;
+    for (const file of files) {
+        const stanza = renderStanza(file);
+        const stanzaBytes = Buffer.byteLength(stanza, 'utf8') + 1; // newline join cost
+        if (bytes + stanzaBytes > MAX_INJECT_BYTES) {
+            truncated = true;
+            break;
+        }
+        stanzas.push(stanza);
+        bytes += stanzaBytes;
+    }
+    if (truncated)
+        stanzas.push(TRUNCATION_MARKER);
+    return stanzas.join('\n');
+}
+/**
+ * Build a single `<ambient-context>` stanza for one HierarchyFile.
+ * The `source` attribute carries the absolute path (after realpath)
+ * so the model can cite which file a piece of guidance came from
+ * when it explains its decisions to the operator.
+ */
+function renderStanza(file) {
+    const sourceAttr = escapeAttr(file.path);
+    const levelAttr = String(file.level);
+    // No trailing newline inside `content` — the join adds one between
+    // stanzas. Trimming the file's trailing whitespace keeps the tag
+    // close to the content for readability when an engineer dumps the
+    // assembled prompt for debugging.
+    const trimmed = file.content.replace(/\s+$/g, '');
+    return [
+        `<ambient-context source="${sourceAttr}" level="${levelAttr}">`,
+        trimmed,
+        `</ambient-context>`,
+    ].join('\n');
+}
+/**
+ * Escape an XML attribute value. We expect operator-controlled paths
+ * (not adversarial input) but `&`, `"` and `<` are still possible in
+ * symlinked / unicode paths so we escape them defensively. The model
+ * has been trained to read this attribute as opaque metadata.
+ */
+function escapeAttr(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+//# sourceMappingURL=context-injector.js.map

package/dist/core/pugi-md/walk-up.js

@@ -0,0 +1,207 @@
+/**
+ * Leak L32 (2026-05-27) — `PUGI.md` hierarchy walk-up to `$HOME`.
+ *
+ * Claude Code walks from `cwd` upward toward the user's homedir and
+ * concatenates every `CLAUDE.md` it finds at each intermediate level
+ * (deepest overrides shallowest). Pugi parity: same walk, looking for
+ * `PUGI.md` first at each level and accepting `CLAUDE.md` as a fallback
+ * — operators often have a leftover `~/CLAUDE.md` or a parent-dir
+ * `CLAUDE.md` from a previous Claude Code session and we want their
+ * ambient guidance picked up automatically without a migration step.
+ *
+ * Why this is a separate module from `core/context/markdown-traverse.ts`:
+ *
+ *   - `markdown-traverse.ts` is the *workspace-bounded* walk (cwd → up
+ *     to but NOT including `workspaceRoot`). It guards every read by
+ *     `realpathSync` containment against the workspace root and
+ *     refuses to escape — by design, because the per-dir markdown is
+ *     part of the project's first-party context.
+ *
+ *   - This module is the *home-bounded* walk (cwd → up to `homedir()`,
+ *     OR until depth limit). It picks up the operator's personal /
+ *     global guidance that lives ABOVE the workspace root. The two
+ *     surfaces are complementary: workspace markdown encodes project
+ *     conventions; this hierarchy walk encodes operator-level taste
+ *     (preferred libraries, "always run prettier", style guides).
+ *
+ * Contract:
+ *
+ *   - Walks from `cwd` upward. At each directory checks `PUGI.md`
+ *     (preferred); when absent falls back to `CLAUDE.md`. Only ONE
+ *     file per level is loaded — preferred wins.
+ *   - Stops at `homedir()` INCLUSIVE — the file at `~/PUGI.md` or
+ *     `~/CLAUDE.md` IS loaded (Claude Code parity: a `~/CLAUDE.md`
+ *     applies to every project the operator opens).
+ *   - Hard depth cap of `MAX_WALK_DEPTH` (20) directories regardless
+ *     of how far cwd is from homedir; defense against symlinked or
+ *     malicious cwd values.
+ *   - Per-file byte cap `MAX_FILE_BYTES` (32 KB); over-cap files are
+ *     truncated, not rejected, so a runaway `PUGI.md` does not break
+ *     the prompt budget.
+ *   - Returns shallow-to-deep order (cwd FIRST, homedir LAST). The
+ *     caller is responsible for rendering precedence — Claude Code's
+ *     rule is "deeper overrides shallower", which means the LAST
+ *     entry in the rendered system prompt wins. Our order matches
+ *     that convention so the context injector can splice directly.
+ *
+ * Safety:
+ *
+ *   - No `realpath` on the directories themselves: the operator's
+ *     cwd may live under a workspace symlink (common with macOS
+ *     `/private/var/...`) and we want to honor what the operator
+ *     sees in their shell. We DO resolve the candidate file via
+ *     `realpathSync` before reading, but only to defeat
+ *     symlinks-pointing-outside-homedir attacks; an off-tree symlink
+ *     is skipped silently.
+ *   - Catch + skip every fs error per file. The walk-up surface MUST
+ *     NEVER break engine boot — missing read perms on a parent dir
+ *     is the common case (e.g. `/etc` on a corp laptop) and the
+ *     fallback is "no ambient context", not a crash.
+ *
+ * Pure module: no logging, no network, no fs writes.
+ */
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+/**
+ * Hard ceiling on parent-dir traversal depth. 20 is generous — even
+ * deep monorepo layouts rarely sit more than 8-10 levels below the
+ * homedir on a developer's laptop. The cap exists so a misconfigured
+ * cwd (e.g. cwd outside the user's home filesystem entirely) cannot
+ * cause a multi-second fs scan of unrelated directories.
+ */
+export const MAX_WALK_DEPTH = 20;
+/**
+ * Per-file byte cap. 32 KB matches the per-dir markdown traverse
+ * aggregate budget — generous enough for a fully written-out
+ * project / personal `PUGI.md` (~8000 words) while keeping any one
+ * file from blowing the prompt budget on its own.
+ */
+export const MAX_FILE_BYTES = 32 * 1024;
+/**
+ * Filenames consulted at each level, in lookup order. `PUGI.md` is
+ * preferred — when both files coexist in a directory the Pugi-native
+ * file wins and the Claude Code shim is ignored. This is the same
+ * precedence used by `markdown-traverse.ts` for workspace-bounded
+ * walks; keeping the two surfaces consistent removes the "why does
+ * Pugi sometimes read CLAUDE.md and sometimes PUGI.md?" foot-gun.
+ */
+export const HIERARCHY_SOURCES = ['PUGI.md', 'CLAUDE.md'];
+/**
+ * Walk from `cwd` upward, collecting ambient `PUGI.md` / `CLAUDE.md`
+ * files at each level until we reach the homedir (inclusive) or the
+ * depth cap.
+ *
+ * Returns an array ordered shallowest-first (cwd → homedir). When no
+ * files are found, returns `[]`. When `cwd` is OUTSIDE the homedir
+ * tree (e.g. the operator runs `pugi` from `/tmp`), the walk still
+ * proceeds upward but stops the moment we reach a filesystem root
+ * without ever entering the homedir — useful for ops/admin invocations
+ * where there is genuinely no personal context to load.
+ */
+export function walkUpPugiMd(cwd, opts = {}) {
+    const limit = clampLimit(opts.limit);
+    const home = opts.homedir;
+    let absCwd;
+    try {
+        absCwd = resolve(cwd);
+    }
+    catch {
+        return [];
+    }
+    const absHome = home ? resolve(home) : undefined;
+    const results = [];
+    let current = absCwd;
+    let level = 0;
+    const visited = new Set();
+    while (level <= limit) {
+        if (visited.has(current))
+            break; // pathological symlink loop guard
+        visited.add(current);
+        const found = tryLoadDirectory(current, level);
+        if (found)
+            results.push(found);
+        // Inclusive home boundary: load home if we are here, then stop.
+        if (absHome && current === absHome)
+            break;
+        const parent = dirname(current);
+        if (parent === current)
+            break; // hit filesystem root before homedir
+        current = parent;
+        level += 1;
+    }
+    return results;
+}
+/**
+ * Pick the first matching file in `dir`, read + cap it, and produce
+ * a HierarchyFile row. Returns `undefined` when no file in
+ * `HIERARCHY_SOURCES` exists or all reads error out (perms, symlink
+ * escape, etc.). NEVER throws — fs errors degrade to "no file at
+ * this level".
+ */
+function tryLoadDirectory(dir, level) {
+    for (const source of HIERARCHY_SOURCES) {
+        const candidate = resolve(dir, source);
+        if (!existsSync(candidate))
+            continue;
+        // Realpath the FILE to defeat symlink-points-elsewhere attacks.
+        // We do not realpath the directory itself — operators often run
+        // pugi from inside a workspace symlink and the walk should honor
+        // the path they see.
+        let realPath;
+        try {
+            realPath = realpathSync(candidate);
+        }
+        catch {
+            // Broken symlink or perms issue on the link itself. Skip this
+            // file and try the next source in the same directory.
+            continue;
+        }
+        let rawBytes;
+        try {
+            rawBytes = statSync(realPath).size;
+        }
+        catch {
+            continue;
+        }
+        let content;
+        try {
+            content = readFileSync(realPath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        let truncated = false;
+        if (Buffer.byteLength(content, 'utf8') > MAX_FILE_BYTES) {
+            // Trim by character index sized to the byte cap. Mild over-trim
+            // on multi-byte boundaries is acceptable — we never under-trim
+            // (we'd exceed the cap) and the truncation is operator-visible
+            // via the `truncated` flag.
+            content = content.slice(0, MAX_FILE_BYTES);
+            truncated = true;
+        }
+        return {
+            path: realPath,
+            content,
+            level,
+            source,
+            truncated,
+            rawBytes,
+        };
+    }
+    return undefined;
+}
+/**
+ * Bound the limit to `[0, MAX_WALK_DEPTH]`. A negative or zero value
+ * still permits the cwd-level file to load (level 0 is always
+ * considered) — passing `limit: 0` means "current directory only".
+ */
+function clampLimit(limit) {
+    if (typeof limit !== 'number' || !Number.isFinite(limit))
+        return MAX_WALK_DEPTH;
+    if (limit < 0)
+        return 0;
+    if (limit > MAX_WALK_DEPTH)
+        return MAX_WALK_DEPTH;
+    return Math.floor(limit);
+}
+//# sourceMappingURL=walk-up.js.map