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

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

@@ -0,0 +1,223 @@
+/**
+ * PRD criterion verifiers — Pugi  (`/prd-check`).
+ *
+ * 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/prompt-cache/client-cache.js

@@ -0,0 +1,99 @@
+/**
+ * Client-side prompt cache .
+ *
+ * Wraps `lru-cache` (isaacs, MIT, used by npm itself) for in-memory
+ * LRU with TTL. Cached entries survive the entire process lifetime
+ * but are intentionally NOT persisted к disk — that's a follow-up
+ * (see PUGI_CLIENT_PROMPT_CACHE_PERSIST in the spec).
+ *
+ * Anthropic's server-side prompt cache uses a 5-minute TTL. We mirror
+ * that default here so a repeated turn within a single user session
+ * benefits even when the server cache expired (e.g. across a brief
+ * network drop or a model retry to a different upstream replica).
+ *
+ * Pure wrapper — no I/O, no globals. Caller hashes the prompt itself
+ * (this keeps the cache key implementation orthogonal to whichever
+ * digest algorithm the engine prefers). The key must already include
+ * the model slug + system prompt + dialog tail digest.
+ */
+import { LRUCache } from 'lru-cache';
+const DEFAULT_MAX_ENTRIES = 256;
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+export class ClientPromptCache {
+    store;
+    hits = 0;
+    misses = 0;
+    tokensSaved = 0;
+    constructor(options = {}) {
+        const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        if (maxEntries < 1) {
+            throw new RangeError(`maxEntries must be >= 1, got ${maxEntries}`);
+        }
+        if (ttlMs <= 0) {
+            throw new RangeError(`ttlMs must be > 0, got ${ttlMs}`);
+        }
+        this.store = new LRUCache({
+            max: maxEntries,
+            ttl: ttlMs,
+            // updateAgeOnGet=false: a cache hit does NOT refresh the TTL —
+            // we want stale-after-5min semantics matching Anthropic's server
+            // cache, not "as long as someone keeps asking, keep it forever".
+            updateAgeOnGet: false,
+        });
+    }
+    /**
+     * Look up an entry. Returns null on miss or на TTL expiry.
+     * Increments hit/miss counters as a side effect.
+     */
+    tryGet(key) {
+        const entry = this.store.get(key);
+        if (entry === undefined) {
+            this.misses += 1;
+            return null;
+        }
+        this.hits += 1;
+        this.tokensSaved += entry.avoidedInputTokens + entry.outputTokens;
+        return entry;
+    }
+    /**
+     * Store a response для future hits. Overwrites prior entry at the
+     * same key, resetting its TTL.
+     */
+    set(key, entry) {
+        this.store.set(key, entry);
+    }
+    /**
+     * Drop a single key. No-op if absent. Returns true when removed.
+     */
+    invalidate(key) {
+        return this.store.delete(key);
+    }
+    /** Clear all entries и reset hit/miss/tokensSaved counters. */
+    clear() {
+        this.store.clear();
+        this.hits = 0;
+        this.misses = 0;
+        this.tokensSaved = 0;
+    }
+    /** Snapshot of cache stats — caller-safe read. */
+    stats() {
+        return {
+            hits: this.hits,
+            misses: this.misses,
+            size: this.store.size,
+            tokensSaved: this.tokensSaved,
+        };
+    }
+    /**
+     * Hit rate в [0, 1]. Returns 0 when no lookups have happened yet
+     * (instead of NaN), so callers can render without guard.
+     */
+    hitRate() {
+        const total = this.hits + this.misses;
+        if (total === 0)
+            return 0;
+        return this.hits / total;
+    }
+}
+//# sourceMappingURL=client-cache.js.map

package/dist/core/prompts/assembly.js

@@ -0,0 +1,29 @@
+const SECTION_SEPARATOR = '\n\n---\n\n';
+export function registerModule(registry, mod) {
+    registry.set(mod.key, mod);
+}
+export function assemblePrompt(modules, context) {
+    const registry = new Map();
+    for (const mod of modules) {
+        registerModule(registry, mod);
+    }
+    const orderedModules = [...registry.values()].sort((a, b) => b.priority - a.priority);
+    const producedSections = [];
+    const sections = [];
+    const skipped = [];
+    for (const mod of orderedModules) {
+        const produced = mod.produce(context);
+        if (produced === null || produced.length === 0) {
+            skipped.push(mod.key);
+            continue;
+        }
+        producedSections.push(produced);
+        sections.push({ key: mod.key, size: produced.length });
+    }
+    return {
+        text: producedSections.join(SECTION_SEPARATOR),
+        sections,
+        skipped,
+    };
+}
+//# sourceMappingURL=assembly.js.map