@crewhaus/spec-patch 0.1.8 → 0.2.1

package/dist/index.d.ts

@@ -32,6 +32,7 @@
  */
 import { CrewhausError } from "@crewhaus/errors";
 import { type Spec } from "@crewhaus/spec";
+export { REDACTED_VALUE, isCredentialKey, maskCredentialTokens } from "./redact";
 export declare class SpecPatchError extends CrewhausError {
     readonly name = "SpecPatchError";
     constructor(message: string, cause?: unknown);
@@ -104,3 +105,60 @@ export declare function formatWriteBackHeader(opts: {
     readonly iterations: number;
     readonly timestamp?: string;
 }): string;
+/**
+ * Item 46 — the fields `formatWriteBackHeader` stamped into a written-back
+ * spec's leading comment block, recovered by `parseWriteBackHeader`. Only
+ * `runId` is guaranteed (it lives on the stamp's first line); the rest are
+ * best-effort so a hand-trimmed header still yields its surviving fields.
+ */
+export type WriteBackHeaderInfo = {
+    readonly runId: string;
+    readonly mutator?: string;
+    readonly iterations?: number;
+    readonly scoreBefore?: number;
+    readonly scoreAfter?: number;
+    readonly generated?: string;
+};
+/**
+ * Inverse of `formatWriteBackHeader`: scan the LEADING comment block of a
+ * YAML text for the optimize write-back stamp and return its fields, or
+ * `undefined` when the text was never written back. Only the leading block
+ * is scanned — a `# crewhaus optimize:` line further down (e.g. quoted
+ * inside an instructions prompt) is document content, not a header.
+ */
+export declare function parseWriteBackHeader(yamlText: string): WriteBackHeaderInfo | undefined;
+/**
+ * Item 46 — one field-level difference between two spec versions (see
+ * `diffSpecYaml`). `path` is dot-joined property keys with array indices
+ * rendered as `[i]` (e.g. `steps[2].prompt`). `before`/`after` carry the
+ * FORMATTED (truncated, credential-REDACTED — see `renderDiffValue`) values,
+ * ready for a changelog line — the differ is a reporting primitive, not a
+ * patch source.
+ */
+export type SpecDiffEntry = {
+    readonly kind: "added" | "removed" | "changed";
+    readonly path: string;
+    /** Formatted old value — absent for `"added"`. */
+    readonly before?: string;
+    /** Formatted new value — absent for `"removed"`. */
+    readonly after?: string;
+};
+/** Diff values longer than this render truncated with a trailing ellipsis. */
+export declare const DIFF_VALUE_MAX_LENGTH = 72;
+/**
+ * Render a value for a diff line: scalars as JSON (strings quoted), maps and
+ * sequences as compact JSON, truncated to `maxLength` with an ellipsis so a
+ * multi-paragraph instructions prompt doesn't flood the changelog. Pure
+ * formatting — credential redaction happens upstream in `renderDiffValue`,
+ * which is what the differ itself calls.
+ */
+export declare function formatDiffValue(value: unknown, maxLength?: number): string;
+/**
+ * Item 46 — structural (field-level) diff between two YAML documents.
+ * Parses both texts and walks the value trees: maps diff by key, sequences
+ * by index, everything else is a leaf compared by value. Comments and
+ * formatting are invisible here BY DESIGN — two texts that parse to the
+ * same values produce an empty diff. Throws `SpecPatchError` when either
+ * text is unparseable.
+ */
+export declare function diffSpecYaml(beforeYaml: string, afterYaml: string): ReadonlyArray<SpecDiffEntry>;

package/dist/index.js

@@ -32,8 +32,13 @@
  */
 import { CrewhausError } from "@crewhaus/errors";
 import { parseSpec } from "@crewhaus/spec";
-import { parseDocument } from "yaml";
+import { parse, parseDocument } from "yaml";
 import { z } from "zod";
+import { REDACTED_VALUE, isCredentialKey, maskCredentialTokens } from "./redact";
+// Re-exported so downstream renderers (the CLI changelog, future reporters)
+// can apply the SAME redaction to strings the differ never sees (rationales,
+// free-form provenance) without duplicating the pattern table a third time.
+export { REDACTED_VALUE, isCredentialKey, maskCredentialTokens } from "./redact";
 export class SpecPatchError extends CrewhausError {
     name = "SpecPatchError";
     constructor(message, cause) {
@@ -143,6 +148,10 @@ function formatPath(path) {
 export const OPTIMIZABLE_PATHS = Object.freeze({
     cli: Object.freeze([
         Object.freeze(["agent", "instructions"]),
+        // Item 14 — `crewhaus advise`'s truncation-pressure rule patches the
+        // per-turn output-token cap when max_tokens truncations recur; safe to
+        // autotune (a bigger cap can only trade cost for completeness).
+        Object.freeze(["agent", "max_tokens"]),
         Object.freeze(["failure_taxonomy"]),
         Object.freeze(["compaction", "threshold"]),
         // Pillar 2 active context curation — eval-optimizer can flip the
@@ -292,3 +301,212 @@ export function formatWriteBackHeader(opts) {
         "",
     ].join("\n");
 }
+/**
+ * Inverse of `formatWriteBackHeader`: scan the LEADING comment block of a
+ * YAML text for the optimize write-back stamp and return its fields, or
+ * `undefined` when the text was never written back. Only the leading block
+ * is scanned — a `# crewhaus optimize:` line further down (e.g. quoted
+ * inside an instructions prompt) is document content, not a header.
+ */
+export function parseWriteBackHeader(yamlText) {
+    let runId;
+    let mutator;
+    let iterations;
+    let scoreBefore;
+    let scoreAfter;
+    let generated;
+    for (const rawLine of yamlText.split("\n")) {
+        const line = rawLine.trim();
+        if (line === "")
+            continue;
+        if (!line.startsWith("#"))
+            break; // end of the leading comment block
+        const stamp = /^# crewhaus optimize: runId (\S+)$/.exec(line);
+        if (stamp?.[1] !== undefined) {
+            runId = stamp[1];
+            continue;
+        }
+        // Field lines only count once the stamp line has been seen, so ordinary
+        // leading comments (`# - mutator: ...` in a user's own notes) don't
+        // masquerade as header fields.
+        if (runId === undefined)
+            continue;
+        const field = /^# - ([a-z]+): (.*)$/.exec(line);
+        if (field?.[1] === undefined || field[2] === undefined)
+            continue;
+        const value = field[2].trim();
+        if (field[1] === "mutator") {
+            mutator = value;
+        }
+        else if (field[1] === "iterations") {
+            const n = Number.parseInt(value, 10);
+            if (!Number.isNaN(n))
+                iterations = n;
+        }
+        else if (field[1] === "score") {
+            const scores = /^([0-9.eE+-]+) → ([0-9.eE+-]+)/.exec(value);
+            const before = scores?.[1] !== undefined ? Number.parseFloat(scores[1]) : Number.NaN;
+            const after = scores?.[2] !== undefined ? Number.parseFloat(scores[2]) : Number.NaN;
+            if (!Number.isNaN(before))
+                scoreBefore = before;
+            if (!Number.isNaN(after))
+                scoreAfter = after;
+        }
+        else if (field[1] === "generated") {
+            generated = value;
+        }
+    }
+    if (runId === undefined)
+        return undefined;
+    return {
+        runId,
+        ...(mutator !== undefined ? { mutator } : {}),
+        ...(iterations !== undefined ? { iterations } : {}),
+        ...(scoreBefore !== undefined ? { scoreBefore } : {}),
+        ...(scoreAfter !== undefined ? { scoreAfter } : {}),
+        ...(generated !== undefined ? { generated } : {}),
+    };
+}
+/** Diff values longer than this render truncated with a trailing ellipsis. */
+export const DIFF_VALUE_MAX_LENGTH = 72;
+/**
+ * Render a value for a diff line: scalars as JSON (strings quoted), maps and
+ * sequences as compact JSON, truncated to `maxLength` with an ellipsis so a
+ * multi-paragraph instructions prompt doesn't flood the changelog. Pure
+ * formatting — credential redaction happens upstream in `renderDiffValue`,
+ * which is what the differ itself calls.
+ */
+export function formatDiffValue(value, maxLength = DIFF_VALUE_MAX_LENGTH) {
+    const rendered = value === undefined ? "undefined" : (JSON.stringify(value) ?? String(value));
+    if (rendered.length <= maxLength)
+        return rendered;
+    return `${rendered.slice(0, Math.max(1, maxLength - 1))}…`;
+}
+/**
+ * Item 46 — structural (field-level) diff between two YAML documents.
+ * Parses both texts and walks the value trees: maps diff by key, sequences
+ * by index, everything else is a leaf compared by value. Comments and
+ * formatting are invisible here BY DESIGN — two texts that parse to the
+ * same values produce an empty diff. Throws `SpecPatchError` when either
+ * text is unparseable.
+ */
+export function diffSpecYaml(beforeYaml, afterYaml) {
+    let before;
+    let after;
+    try {
+        before = parse(beforeYaml);
+    }
+    catch (err) {
+        throw new SpecPatchError("diff: previous YAML is not parseable", err);
+    }
+    try {
+        after = parse(afterYaml);
+    }
+    catch (err) {
+        throw new SpecPatchError("diff: new YAML is not parseable", err);
+    }
+    const out = [];
+    walkDiff(before, after, "", out, []);
+    return out;
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function leafEqual(a, b) {
+    if (a === b)
+        return true;
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Adversarial-review F1 — render a diff value with credentials removed.
+ * `diffSpecYaml`'s output lands verbatim in `.crewhaus/specs/<name>/
+ * CHANGELOG.md` on every compile and echoes through `crewhaus spec log`, so
+ * the redaction has to happen HERE in the differ, for every consumer:
+ *
+ *   - a value under a credential-carrying key — final or parent segment
+ *     (`agent.api_key`, `mcp_servers.*.env.TOKEN`, sse `headers.*`) —
+ *     renders as `[redacted]`, never the value;
+ *   - every other value has nested credential keys redacted and
+ *     credential-shaped tokens masked out of its strings (an `sk-…` pasted
+ *     into `instructions` prose) BEFORE `formatDiffValue` truncates.
+ *
+ * `keyTrail` is the chain of property keys down to the value; array indices
+ * are not keys and don't appear in it.
+ */
+function renderDiffValue(value, keyTrail) {
+    const finalKey = keyTrail[keyTrail.length - 1];
+    const parentKey = keyTrail[keyTrail.length - 2];
+    if ((finalKey !== undefined && isCredentialKey(finalKey)) ||
+        (parentKey !== undefined && isCredentialKey(parentKey))) {
+        return REDACTED_VALUE;
+    }
+    return formatDiffValue(redactTree(value));
+}
+/** Deep-copy `value` with credential-keyed leaves replaced by `[redacted]`
+ *  and credential-shaped tokens masked inside the remaining strings, so an
+ *  added/removed SUBTREE (a whole MCP server map with an `env` block) can't
+ *  smuggle secrets through its compact-JSON rendering. */
+function redactTree(value, underCredentialKey = false) {
+    if (Array.isArray(value)) {
+        return value.map((v) => redactTree(v, underCredentialKey));
+    }
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = redactTree(v, underCredentialKey || isCredentialKey(k));
+        }
+        return out;
+    }
+    if (underCredentialKey)
+        return REDACTED_VALUE;
+    return typeof value === "string" ? maskCredentialTokens(value) : value;
+}
+function walkDiff(a, b, path, out, keyTrail) {
+    if (isPlainObject(a) && isPlainObject(b)) {
+        // Union of keys, a's ordering first — deterministic output.
+        const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+        for (const key of keys) {
+            const childPath = path === "" ? key : `${path}.${key}`;
+            const childTrail = [...keyTrail, key];
+            if (!(key in a)) {
+                out.push({ kind: "added", path: childPath, after: renderDiffValue(b[key], childTrail) });
+            }
+            else if (!(key in b)) {
+                out.push({
+                    kind: "removed",
+                    path: childPath,
+                    before: renderDiffValue(a[key], childTrail),
+                });
+            }
+            else {
+                walkDiff(a[key], b[key], childPath, out, childTrail);
+            }
+        }
+        return;
+    }
+    if (Array.isArray(a) && Array.isArray(b)) {
+        const len = Math.max(a.length, b.length);
+        for (let i = 0; i < len; i++) {
+            const childPath = `${path}[${i}]`;
+            if (i >= a.length) {
+                out.push({ kind: "added", path: childPath, after: renderDiffValue(b[i], keyTrail) });
+            }
+            else if (i >= b.length) {
+                out.push({ kind: "removed", path: childPath, before: renderDiffValue(a[i], keyTrail) });
+            }
+            else {
+                walkDiff(a[i], b[i], childPath, out, keyTrail);
+            }
+        }
+        return;
+    }
+    // Leaf (or type-mismatch, e.g. map → sequence): compare whole values.
+    if (!leafEqual(a, b)) {
+        out.push({
+            kind: "changed",
+            path: path === "" ? "(root)" : path,
+            before: renderDiffValue(a, keyTrail),
+            after: renderDiffValue(b, keyTrail),
+        });
+    }
+}

package/dist/redact.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Credential redaction for HUMAN-READABLE renderings of spec/IR content —
+ * changelog diff lines (`spec-patch`) and generated bundle READMEs (`ir`).
+ * Two layers:
+ *
+ *   1. `isCredentialKey` — key-based: a value stored under a key that NAMES
+ *      a credential (`api_key`, `botToken`, `headers`, `env`, …) is redacted
+ *      wholesale, whatever the value looks like.
+ *   2. `maskCredentialTokens` — value-based: strings that are NOT under a
+ *      credential key (instructions prose, command args, URLs) are scanned
+ *      for well-known credential token shapes (`sk-…`, `ghp_…`, `xoxb-…`,
+ *      `AKIA…`, `Bearer <token>`) plus high-length opaque tokens preceded by
+ *      key-ish context words. Deliberately conservative: a bare 32-char
+ *      identifier with no "key/token/secret/password" context is left alone
+ *      so normal prose never gets chewed up.
+ *
+ * KEEP IN SYNC: this module is intentionally duplicated as
+ * `packages/ir/src/redact.ts` and `packages/spec-patch/src/redact.ts`.
+ * `@crewhaus/ir` keeps ZERO package dependencies (its `readme.ts` already
+ * mirrors `OUTWARD_TOOL_NAMES` from tool-builder for the same reason) and
+ * `spec-patch` is spec-layer infrastructure that must not grow an edge onto
+ * the IR layer — so neither package can host the single copy without a new
+ * dependency edge. Change one file, change both.
+ */
+/** Placeholder rendered in place of a value under a credential-carrying key. */
+export declare const REDACTED_VALUE = "[redacted]";
+/** Placeholder substituted for a credential-shaped token inside a string. */
+export declare const MASKED_TOKEN = "***";
+/**
+ * Whether a property key names a credential. Suffix matches require a word
+ * boundary (snake/kebab/camel) so `api_key` / `botToken` / `GITHUB_TOKEN` /
+ * `signingSecret` redact while `monkey` / `max_tokens` don't.
+ */
+export declare function isCredentialKey(key: string): boolean;
+/** A path segment / standalone word shaped like an opaque credential
+ *  (Alchemy/Infura-style `/v2/<key>`): 32+ chars of token alphabet. */
+export declare const OPAQUE_TOKEN_RE: RegExp;
+/**
+ * Mask credential-shaped tokens inside a string. Non-credential text is
+ * returned unchanged (hit/no-hit cases are unit-tested in both packages).
+ */
+export declare function maskCredentialTokens(text: string): string;

package/dist/redact.js

@@ -0,0 +1,102 @@
+/**
+ * Credential redaction for HUMAN-READABLE renderings of spec/IR content —
+ * changelog diff lines (`spec-patch`) and generated bundle READMEs (`ir`).
+ * Two layers:
+ *
+ *   1. `isCredentialKey` — key-based: a value stored under a key that NAMES
+ *      a credential (`api_key`, `botToken`, `headers`, `env`, …) is redacted
+ *      wholesale, whatever the value looks like.
+ *   2. `maskCredentialTokens` — value-based: strings that are NOT under a
+ *      credential key (instructions prose, command args, URLs) are scanned
+ *      for well-known credential token shapes (`sk-…`, `ghp_…`, `xoxb-…`,
+ *      `AKIA…`, `Bearer <token>`) plus high-length opaque tokens preceded by
+ *      key-ish context words. Deliberately conservative: a bare 32-char
+ *      identifier with no "key/token/secret/password" context is left alone
+ *      so normal prose never gets chewed up.
+ *
+ * KEEP IN SYNC: this module is intentionally duplicated as
+ * `packages/ir/src/redact.ts` and `packages/spec-patch/src/redact.ts`.
+ * `@crewhaus/ir` keeps ZERO package dependencies (its `readme.ts` already
+ * mirrors `OUTWARD_TOOL_NAMES` from tool-builder for the same reason) and
+ * `spec-patch` is spec-layer infrastructure that must not grow an edge onto
+ * the IR layer — so neither package can host the single copy without a new
+ * dependency edge. Change one file, change both.
+ */
+/** Placeholder rendered in place of a value under a credential-carrying key. */
+export const REDACTED_VALUE = "[redacted]";
+/** Placeholder substituted for a credential-shaped token inside a string. */
+export const MASKED_TOKEN = "***";
+/**
+ * Keys that carry credentials, matched case-insensitively after lowercasing.
+ * Aligned with the spec schema's credential carriers (`botToken`,
+ * `signingSecret`, `appToken`, `secretToken`, `accessToken`, `appSecret`,
+ * `retrieve.apiKey`, wallet `keyRef`) and the compiler's `lowerCredential` /
+ * `lowerWalletKeyRef` call sites — see `packages/compiler/src/index.ts` §12.
+ * `headers` and `env` are container keys: everything under them redacts.
+ */
+const CREDENTIAL_KEY_EXACT = new Set([
+    "key",
+    "apikey",
+    "api_key",
+    "api-key",
+    "token",
+    "secret",
+    "password",
+    "passwd",
+    "pwd",
+    "authorization",
+    "auth",
+    "credential",
+    "credentials",
+    "headers",
+    "env",
+    "keyref",
+    "key_ref",
+    "key-ref",
+    "privatekey",
+    "private_key",
+    "private-key",
+]);
+/**
+ * Whether a property key names a credential. Suffix matches require a word
+ * boundary (snake/kebab/camel) so `api_key` / `botToken` / `GITHUB_TOKEN` /
+ * `signingSecret` redact while `monkey` / `max_tokens` don't.
+ */
+export function isCredentialKey(key) {
+    const k = key.toLowerCase();
+    if (CREDENTIAL_KEY_EXACT.has(k))
+        return true;
+    if (/[_-](?:key|token|secret|password)$/.test(k))
+        return true;
+    return /[a-z0-9](?:Key|Token|Secret|Password)$/.test(key);
+}
+/** A path segment / standalone word shaped like an opaque credential
+ *  (Alchemy/Infura-style `/v2/<key>`): 32+ chars of token alphabet. */
+export const OPAQUE_TOKEN_RE = /^[A-Za-z0-9_-]{32,}$/;
+/** Well-known credential token shapes, masked wherever they appear. */
+const TOKEN_SHAPE_RES = [
+    /\bsk-[A-Za-z0-9_-]{8,}/g, // OpenAI/Anthropic/Stripe-style secret keys
+    /\bgh[oprsu]_[A-Za-z0-9]{16,}/g, // GitHub tokens (ghp_/gho_/ghu_/ghs_/ghr_)
+    /\bxox[abprs]-[A-Za-z0-9-]{10,}/g, // Slack tokens
+    /\bAKIA[A-Z0-9]{12,}/g, // AWS access key ids
+];
+/** `Bearer <token>` — the scheme word is kept, the token is masked. */
+const BEARER_RE = /\b(bearer)\s+[A-Za-z0-9._~+/-]{8,}=*/gi;
+/**
+ * Generic 32+-char opaque token, masked ONLY when preceded by a key-ish
+ * context word — `key: XXXX…`, `token=XXXX…` — so hashes/ids in ordinary
+ * prose survive. Group 1 (the context) is kept; the token is masked.
+ */
+const CONTEXTUAL_OPAQUE_RE = /\b((?:api[-_ ]?)?(?:key|token|secret|password|credential)s?\b["'\s:=-]{0,5})([A-Za-z0-9+/_-]{32,})/gi;
+/**
+ * Mask credential-shaped tokens inside a string. Non-credential text is
+ * returned unchanged (hit/no-hit cases are unit-tested in both packages).
+ */
+export function maskCredentialTokens(text) {
+    let out = text;
+    for (const re of TOKEN_SHAPE_RES)
+        out = out.replace(re, MASKED_TOKEN);
+    out = out.replace(BEARER_RE, `$1 ${MASKED_TOKEN}`);
+    out = out.replace(CONTEXTUAL_OPAQUE_RE, `$1${MASKED_TOKEN}`);
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/spec-patch",
-  "version": "0.1.8",
+  "version": "0.2.1",
   "type": "module",
   "description": "Pillar-2 patch infrastructure — apply a SpecPatch to a YAML source preserving comments and key order via the yaml CST. Drives the active eval optimizer's spec-level mutation loop.",
   "main": "dist/index.js",
@@ -15,8 +15,8 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.8",
-    "@crewhaus/spec": "0.1.8",
+    "@crewhaus/errors": "0.2.1",
+    "@crewhaus/spec": "0.2.1",
     "yaml": "^2.6.0",
     "zod": "^3.23.8"
   },