@pugi/cli 0.1.0-alpha.10

package/dist/core/context/invariants.js

@@ -0,0 +1,250 @@
+/**
+ * Compaction invariants — the safety belt that decides whether a
+ * compaction result is allowed to replace the original transcript.
+ *
+ * Per pattern card §2:
+ *   - principle 4: never summarize secrets into durable memory
+ *   - principle 5: do not erase open decisions
+ *   - principle 6: cache stable prompt parts (static hash must survive
+ *     compaction unchanged)
+ *
+ * Plus our own physical-integrity invariant: artifact refs emitted by
+ * the compaction must point to files that exist on disk and match the
+ * SHA256 stored in the ref.
+ *
+ * Violations fire `compaction.invariant_violated` events upstream; the
+ * engine loop discards the compaction result and tries again on the
+ * next turn.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+/**
+ * Regex sweep for credential-shaped substrings. Errs on the side of
+ * over-reporting; a false positive aborts the compaction (the engine
+ * keeps the original transcript and the operator pays the latency
+ * cost of one extra turn, which is the right trade-off for secrets).
+ *
+ * Coverage spans two shapes:
+ *
+ *   1. Cooperative `keyword = value` / `keyword: value` pairs covering
+ *      api_key, access_token, password, client_secret, private_key,
+ *      .env.* etc.
+ *   2. Provider-specific bare tokens that travel without a keyword:
+ *      Bearer JWTs, AWS access keys, GitHub PATs, Slack tokens, Stripe
+ *      keys, Anthropic/OpenAI keys, and PEM private key blocks.
+ *
+ * High-entropy base64-shaped blobs after a `:` or `=` are also caught
+ * as a defence in depth — operators who exfiltrate keys via raw JSON
+ * blobs (`{"x":"abc...40chars..."}`) are still surfaced.
+ *
+ * Each pattern is tried in turn by `findSecrets`; the first match per
+ * pattern is reported (with redaction) and the compaction is aborted.
+ */
+const SECRET_PATTERNS = [
+    // 1. Keyword=value / keyword: value — the cooperative shape.
+    /(api[_-]?key|access[_-]?token|id[_-]?token|password|passwd|client[_-]?secret|private[_-]?key|\.env\.[A-Z_]+|(?<![a-z])token|(?<![a-z])secret)\s*[:=]\s*\S+/gi,
+    // 2. Authorization: Bearer <jwt-or-opaque-token>. JWTs are eyJ... but
+    //    we accept any non-whitespace token after Bearer so opaque bearer
+    //    tokens are also caught.
+    /Authorization\s*:\s*Bearer\s+\S+/gi,
+    /\bBearer\s+(?:eyJ[A-Za-z0-9_\-.]{16,}|[A-Za-z0-9_\-.]{20,})/g,
+    // 3. AWS access keys. AKIA prefix is the long-lived IAM key shape;
+    //    aws_access_key_id is the typical .aws/credentials shape.
+    /\bAKIA[0-9A-Z]{16}\b/g,
+    /aws_access_key_id\s*[:=]\s*\S+/gi,
+    /aws_secret_access_key\s*[:=]\s*\S+/gi,
+    // 4. GitHub PATs and app tokens.
+    /\bghp_[A-Za-z0-9]{36}\b/g,
+    /\bgho_[A-Za-z0-9]{36}\b/g,
+    /\bghs_[A-Za-z0-9]{36}\b/g,
+    /\bghu_[A-Za-z0-9]{36}\b/g,
+    /\bghr_[A-Za-z0-9]{36}\b/g,
+    /\bgithub_pat_[A-Za-z0-9_]{22,}\b/g,
+    // 5. Slack tokens (xoxa / xoxb / xoxp / xoxr / xoxs / xoxe).
+    /\bxox[abprse]-[A-Za-z0-9-]{10,}/g,
+    // 6. Stripe live/test secret keys.
+    /\bsk_(?:live|test)_[A-Za-z0-9]{24,}\b/g,
+    // 7. Anthropic and OpenAI API keys. Anthropic uses sk-ant-<32+chars>;
+    //    OpenAI legacy keys are sk-<40+chars>. Both share the sk- prefix
+    //    so we keep them in their own patterns to avoid catching every
+    //    Stripe sk_ as well (Stripe uses an underscore, not a dash).
+    /\bsk-ant-[A-Za-z0-9_-]{32,}\b/g,
+    /\bsk-(?!ant-)[A-Za-z0-9]{40,}\b/g,
+    // 8. PEM-encoded private key blocks. Matches RSA / EC / DSA / OPENSSH
+    //    and the bare PRIVATE KEY variant. The body may contain real
+    //    newlines (when scanning raw transcript content) OR literal `\n`
+    //    sequences (when scanning JSON.stringify'd summaries) — both are
+    //    covered by the broad character class.
+    /-----BEGIN (?:RSA |EC |DSA |OPENSSH |ENCRYPTED |)PRIVATE KEY-----[\s\S\\n]*?-----END (?:RSA |EC |DSA |OPENSSH |ENCRYPTED |)PRIVATE KEY-----/g,
+    // 8b. Lone PEM begin/end markers — survive even when the body is too
+    //     long to capture or escaped beyond recognition.
+    /-----BEGIN (?:RSA |EC |DSA |OPENSSH |ENCRYPTED |)PRIVATE KEY-----/g,
+    // 9. High-entropy base64-shaped blobs after a colon or equals. 40+ chars
+    //    of the base64url alphabet is well above the ~6 bytes/char threshold
+    //    where false positives become rare. Word-boundary anchored so prose
+    //    is not swept up.
+    /[:=]\s*"?([A-Za-z0-9_\-+/]{40,}={0,2})"?(?=\s|,|\}|$)/g,
+];
+/**
+ * Decision markers we promise to preserve verbatim across compaction.
+ * Line-anchored so a decision quoted in chat (`> DECISION: ...`)
+ * survives, but a casual mention does not falsely trigger.
+ */
+const DECISION_RX = /^\s*(?:DECISION|OPEN|BLOCKED|REJECTED):/;
+/**
+ * Compare invariant-relevant state before and after compaction. Returns
+ * an empty array when the compaction is safe to commit. Any returned
+ * violation must cause the engine to drop the compaction result.
+ *
+ * Inputs:
+ *   - `before`: the compaction input snapshot the caller computed
+ *   - `after`: the compaction result the tier function produced
+ *   - `summaryText`: the concrete prose / structured summary the
+ *     compaction wrote into the dynamic block (or empty string for
+ *     microcompact tiers that only reshape existing content)
+ *   - `staticHashBefore` / `staticHashAfter`: instructions+toolSchema
+ *     hash from the context builder, captured before and after the
+ *     compaction (compaction must never touch static blocks)
+ */
+export function checkInvariants(args) {
+    const { before, after, summaryText } = args;
+    const violations = [];
+    // 1. secrets-never-summarize — sweep the post-compaction summary text.
+    //    `summaryText` is what gets written to .pugi/session.db / replaces
+    //    the transcript turns. We grep there, not the input, because the
+    //    pre-compaction transcript is the operator's own data; we only
+    //    police what we are about to make durable.
+    if (summaryText.length > 0) {
+        const firstMatch = findFirstSecret(summaryText);
+        if (firstMatch !== null) {
+            violations.push({
+                invariant: 'secrets-never-summarize',
+                evidence: redact(firstMatch),
+            });
+        }
+    }
+    // 2. open-decisions-preserved — every DECISION/OPEN/BLOCKED/REJECTED
+    //    line in the pre-compaction transcript must appear verbatim in
+    //    the post-compaction summary OR remain in the after-state's
+    //    `decisionsPreserved`. The compaction result surfaces the latter
+    //    so we cross-check both.
+    const beforeDecisions = [];
+    for (const turn of before.transcript) {
+        for (const line of turn.content.split('\n')) {
+            if (DECISION_RX.test(line))
+                beforeDecisions.push(line.trim());
+        }
+    }
+    const preservedSet = new Set(after.decisionsPreserved.map((d) => d.trim()));
+    for (const dec of beforeDecisions) {
+        const inSummary = summaryText.includes(dec);
+        const inPreservedList = preservedSet.has(dec);
+        if (!inSummary && !inPreservedList) {
+            violations.push({
+                invariant: 'open-decisions-preserved',
+                evidence: dec,
+            });
+        }
+    }
+    // 3. artifact-refs-resolvable — every artifact ref must point to a
+    //    file under .pugi/artifacts/ that exists and SHA256-matches the
+    //    ref. We compute the hash physically rather than trusting the
+    //    bookkeeping; if the disk write was corrupted, we want to know
+    //    before we promote the compaction.
+    for (const ref of after.artifactsCreated) {
+        const violation = verifyArtifact(ref);
+        if (violation)
+            violations.push(violation);
+    }
+    // 4. static-hash-unchanged — instructions and tool schema hashes
+    //    must be byte-identical before and after compaction.
+    if (args.staticHashBefore.instructionsHash !== args.staticHashAfter.instructionsHash) {
+        violations.push({
+            invariant: 'static-hash-unchanged',
+            evidence: `instructionsHash ${args.staticHashBefore.instructionsHash} -> ${args.staticHashAfter.instructionsHash}`,
+        });
+    }
+    if (args.staticHashBefore.toolSchemaHash !== args.staticHashAfter.toolSchemaHash) {
+        violations.push({
+            invariant: 'static-hash-unchanged',
+            evidence: `toolSchemaHash ${args.staticHashBefore.toolSchemaHash} -> ${args.staticHashAfter.toolSchemaHash}`,
+        });
+    }
+    return violations;
+}
+function verifyArtifact(ref) {
+    if (!ref.path || !ref.sha256) {
+        return {
+            invariant: 'artifact-refs-resolvable',
+            evidence: `artifact ref missing path or sha256: ${JSON.stringify(ref)}`,
+            artifactRef: ref.sha256,
+        };
+    }
+    if (!existsSync(ref.path)) {
+        return {
+            invariant: 'artifact-refs-resolvable',
+            evidence: `artifact path does not exist: ${ref.path}`,
+            artifactRef: ref.sha256,
+        };
+    }
+    const physical = createHash('sha256').update(readFileSync(ref.path)).digest('hex');
+    // Refs are stored with a `sha256:` prefix per the spec's
+    // { artifactRef: 'sha256:abc...' } shape. Strip the prefix before
+    // comparing against the raw hex digest of the file contents.
+    const expected = ref.sha256.startsWith('sha256:') ? ref.sha256.slice('sha256:'.length) : ref.sha256;
+    if (physical !== expected) {
+        return {
+            invariant: 'artifact-refs-resolvable',
+            evidence: `sha256 mismatch at ${ref.path}: expected ${ref.sha256}, got ${physical}`,
+            artifactRef: ref.sha256,
+        };
+    }
+    return null;
+}
+function findFirstSecret(summaryText) {
+    // Iterate each pattern and return the first non-empty match. We do
+    // not bail on the first pattern with no hit — operators can leak via
+    // any of the shapes (Bearer headers in one section, raw AKIA in
+    // another) so we want a deterministic sweep over the union.
+    for (const pattern of SECRET_PATTERNS) {
+        // Patterns are stateful (the `g` flag tracks lastIndex), so we
+        // explicitly reset before scanning to keep the function pure.
+        pattern.lastIndex = 0;
+        const match = pattern.exec(summaryText);
+        if (match && match[0].length > 0)
+            return match[0];
+    }
+    return null;
+}
+function redact(input) {
+    // Two shapes to handle:
+    //
+    //   1. Keyword=value / keyword: value — keep the keyword visible so
+    //      the operator can see which secret leaked, but mask the value.
+    //   2. Bare token (Bearer ..., AKIA..., PEM block, etc.) — keep the
+    //      first 2 and last 2 chars of the token; mask the middle. PEM
+    //      blocks are dropped entirely except for the BEGIN line.
+    if (input.startsWith('-----BEGIN')) {
+        // PEM blocks may arrive with real newlines, with escaped `\n`
+        // (JSON-stringified payloads), or with `\r\n` (Windows). Cut on
+        // the BEGIN header end so the body never leaks.
+        // Codex P1 retro 2026-05-24: matching on `\n` only let the
+        // escaped-newline case dump the full PEM into invariant evidence.
+        const headerEnd = input.search(/-----(\r?\n|\\r?\\n|$)/);
+        const firstLine = headerEnd > 0 ? input.slice(0, headerEnd + 5) : '-----BEGIN PRIVATE KEY-----';
+        return `${firstLine} ***PEM_BODY_REDACTED***`;
+    }
+    const kv = /^([^:=]+[:=]\s*)(\S+)/.exec(input);
+    if (kv) {
+        const head = kv[1] ?? '';
+        const value = kv[2] ?? '';
+        const tail = value.length > 4 ? `${value.slice(0, 2)}***${value.slice(-2)}` : '***';
+        return `${head}${tail}`;
+    }
+    // Bare-token shape: mask the middle of the whole input.
+    if (input.length > 4) {
+        return `${input.slice(0, 2)}***${input.slice(-2)}`;
+    }
+    return '***';
+}
+//# sourceMappingURL=invariants.js.map

package/dist/core/context/markdown-loader.js

@@ -0,0 +1,270 @@
+/**
+ * PUGI.md / AGENTS.md context loader with bounded @import resolution.
+ *
+ * Per pattern card `docs/research/pugi-cli-corpus/patterns/context-compaction.md`
+ * §6 (prompt cache boundary), PUGI.md and AGENTS.md belong to the static
+ * context block. They are loaded once per session, deterministically, with
+ * the following safety budget:
+ *
+ *   - max import depth: 3 (deeper chains are skipped, not fatal)
+ *   - max total loaded bytes: 64 KB across PUGI.md + AGENTS.md + all imports
+ *   - HTML comment stripping (`<!-- ... -->`) — comments often carry stale
+ *     annotations that bias the model long after they go out of date
+ *   - workspace containment — `@import ../../../etc/passwd` is rejected
+ *
+ * Missing files are not errors. If `PUGI.md` is absent we simply skip it
+ * and report nothing; the engine builds its context from instructions +
+ * tool schemas alone.
+ *
+ * This module is pure: no logging, no side effects beyond fs reads. The
+ * caller (context builder) decides how to emit warning events.
+ */
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+export const MAX_IMPORT_DEPTH = 3;
+export const MAX_TOTAL_BYTES = 64 * 1024;
+/**
+ * Source filenames we look for at the workspace root. Order matters:
+ * PUGI.md is the canonical Pugi-native file; AGENTS.md is the
+ * cross-CLI compatibility shim used by other agentic CLIs.
+ */
+export const MARKDOWN_SOURCES = ['PUGI.md', 'AGENTS.md'];
+/**
+ * Load PUGI.md + AGENTS.md from `workspaceRoot`. Either or both may be
+ * absent. Returns the combined load result with per-file detail plus a
+ * flat list of warnings (best-effort: a missing file is a warning, not
+ * an error).
+ */
+export async function loadMarkdownContext(workspaceRoot) {
+    const warnings = [];
+    const loaded = [];
+    let budgetRemaining = MAX_TOTAL_BYTES;
+    const visited = new Set();
+    const absRoot = resolve(workspaceRoot);
+    for (const source of MARKDOWN_SOURCES) {
+        const candidate = resolve(absRoot, source);
+        if (!existsSync(candidate)) {
+            warnings.push({
+                kind: 'file_missing',
+                message: `${source} not found at workspace root`,
+                path: candidate,
+            });
+            continue;
+        }
+        if (budgetRemaining <= 0) {
+            warnings.push({
+                kind: 'budget_exhausted',
+                message: `skipped ${source}: 64 KB total budget already consumed by earlier file`,
+                path: candidate,
+            });
+            continue;
+        }
+        const expanded = expandFile({
+            filePath: candidate,
+            workspaceRoot: absRoot,
+            depth: 0,
+            visited,
+            warnings,
+            budgetRemaining,
+        });
+        loaded.push({
+            source,
+            resolvedPath: candidate,
+            rawBytes: expanded.rootRawBytes,
+            loadedBytes: expanded.bytesConsumed,
+            imports: expanded.imports,
+            truncated: expanded.truncated,
+            content: expanded.content,
+        });
+        budgetRemaining -= expanded.bytesConsumed;
+    }
+    return {
+        loaded,
+        warnings,
+        totalBytes: MAX_TOTAL_BYTES - budgetRemaining,
+    };
+}
+function expandFile(input) {
+    const { filePath, workspaceRoot, depth, visited, warnings } = input;
+    let budgetRemaining = input.budgetRemaining;
+    const imports = [];
+    let truncated = false;
+    // Cycle guard: if the same file was already visited in this load,
+    // skip re-expansion. Markdown @imports forming a cycle would explode
+    // the budget within seconds otherwise.
+    if (visited.has(filePath)) {
+        return {
+            content: '',
+            rootRawBytes: 0,
+            bytesConsumed: 0,
+            imports,
+            truncated: false,
+        };
+    }
+    visited.add(filePath);
+    let raw;
+    let rawBytes;
+    try {
+        raw = readFileSync(filePath, 'utf8');
+        rawBytes = statSync(filePath).size;
+    }
+    catch (error) {
+        warnings.push({
+            kind: 'read_error',
+            message: `could not read ${filePath}: ${error.message}`,
+            path: filePath,
+        });
+        return {
+            content: '',
+            rootRawBytes: 0,
+            bytesConsumed: 0,
+            imports,
+            truncated: false,
+        };
+    }
+    // Strip HTML comments first; budget accounting happens on the stripped
+    // body so that bloated comment blocks do not waste the operator's cap.
+    const stripped = stripHtmlComments(raw);
+    // Resolve `@import path/to/file.md` directives. Line-anchored, so a
+    // literal `@import` inside a code fence (which would not start at
+    // column 0 of a line) is left alone. We accept relative paths only;
+    // absolute paths are rejected as out-of-workspace.
+    const lines = stripped.split('\n');
+    const expandedLines = [];
+    for (const line of lines) {
+        const match = /^\s*@import\s+(\S+)\s*$/.exec(line);
+        if (!match) {
+            // Plain content line — accumulate into the budget. We do this
+            // line-by-line so an oversized file can be partially captured up
+            // to the cap rather than skipped entirely.
+            const lineBytes = Buffer.byteLength(line, 'utf8') + 1;
+            if (budgetRemaining <= 0) {
+                truncated = true;
+                break;
+            }
+            if (lineBytes > budgetRemaining) {
+                // Take what we can fit (UTF-8 safe truncation: just slice the
+                // remaining bytes — markdown does not require codepoint
+                // alignment for context purposes, but Buffer.byteLength may
+                // overshoot by 1 if we cut mid-codepoint; we bias to a safe
+                // codepoint slice via string indexing).
+                const safeChars = Math.max(0, budgetRemaining - 1);
+                expandedLines.push(line.slice(0, safeChars));
+                budgetRemaining = 0;
+                truncated = true;
+                break;
+            }
+            expandedLines.push(line);
+            budgetRemaining -= lineBytes;
+            continue;
+        }
+        const importPath = match[1] ?? '';
+        const nextDepth = depth + 1;
+        if (nextDepth > MAX_IMPORT_DEPTH) {
+            warnings.push({
+                kind: 'import_depth_exceeded',
+                message: `@import depth ${nextDepth} exceeds max ${MAX_IMPORT_DEPTH} at ${filePath} -> ${importPath}`,
+                path: importPath,
+            });
+            continue;
+        }
+        if (isAbsolute(importPath)) {
+            warnings.push({
+                kind: 'import_escapes_workspace',
+                message: `@import absolute path rejected: ${importPath} (from ${filePath})`,
+                path: importPath,
+            });
+            continue;
+        }
+        const targetPath = resolve(dirname(filePath), importPath);
+        const rel = relative(workspaceRoot, targetPath);
+        if (rel.startsWith('..') || isAbsolute(rel)) {
+            warnings.push({
+                kind: 'import_escapes_workspace',
+                message: `@import escapes workspace: ${importPath} (from ${filePath})`,
+                path: importPath,
+            });
+            continue;
+        }
+        if (!existsSync(targetPath)) {
+            warnings.push({
+                kind: 'import_missing',
+                message: `@import target not found: ${importPath} (from ${filePath})`,
+                path: targetPath,
+            });
+            continue;
+        }
+        // The string-level relative() check above only sees the path the
+        // operator typed. A symlink inside the workspace (e.g.
+        // `workspace/sneaky.md -> /etc/passwd`) passes that gate, and
+        // readFileSync then follows the symlink and inlines arbitrary
+        // contents into the static context. Realpath the target AND the
+        // workspace root so the comparison runs against the physical paths.
+        // Mirrors the apps/pugi-cli/src/core/trust.ts pattern from PR #305.
+        let realTarget;
+        let realRoot;
+        try {
+            realTarget = realpathSync(targetPath);
+            realRoot = realpathSync(workspaceRoot);
+        }
+        catch (error) {
+            warnings.push({
+                kind: 'read_error',
+                message: `realpath failed for @import: ${error.message}`,
+                path: targetPath,
+            });
+            continue;
+        }
+        const realRel = relative(realRoot, realTarget);
+        if (realRel.startsWith('..') || isAbsolute(realRel)) {
+            warnings.push({
+                kind: 'import_escapes_workspace',
+                message: `@import escapes workspace via symlink: ${importPath} -> ${realTarget} (from ${filePath})`,
+                path: importPath,
+            });
+            continue;
+        }
+        const subtree = expandFile({
+            filePath: targetPath,
+            workspaceRoot,
+            depth: nextDepth,
+            visited,
+            warnings,
+            budgetRemaining,
+        });
+        expandedLines.push(subtree.content);
+        imports.push({
+            resolvedPath: targetPath,
+            depth: nextDepth,
+            rawBytes: subtree.rootRawBytes,
+            loadedBytes: subtree.bytesConsumed,
+        });
+        imports.push(...subtree.imports);
+        budgetRemaining -= subtree.bytesConsumed;
+        if (subtree.truncated)
+            truncated = true;
+        if (budgetRemaining <= 0) {
+            truncated = true;
+            break;
+        }
+    }
+    const content = expandedLines.join('\n');
+    const bytesConsumed = input.budgetRemaining - budgetRemaining;
+    return {
+        content,
+        rootRawBytes: rawBytes,
+        bytesConsumed,
+        imports,
+        truncated,
+    };
+}
+/**
+ * Remove HTML comments `<!-- ... -->` from markdown source. Non-greedy
+ * match, multi-line aware. Matches the behaviour described in the
+ * context-compaction pattern card §6 (cache boundary): comments often
+ * carry stale annotations that bias the model long after they should.
+ */
+export function stripHtmlComments(input) {
+    return input.replace(/<!--[\s\S]*?-->/g, '');
+}
+//# sourceMappingURL=markdown-loader.js.map