specrails-core 6.6.5 → 6.7.0

package/dist/pipeline/spec-trace.js

@@ -0,0 +1,392 @@
+// Requirement ↔ test traceability.
+//
+// Every OpenSpec requirement (`### Requirement: <name>` in
+// `openspec/specs/<capability>/spec.md`) has a stable id
+// `<capability>/<slug>`. A test claims a requirement with a tag in its title
+// (`[spec:<capability>/<slug>]`) or a comment on the line before it
+// (`// spec: <capability>/<slug>`, `# spec: …` for Python and shell; any
+// language). The scanner crosses the tags with verification receipts: a
+// requirement is demonstrated when a tagged test file was executed by a
+// verification command that exited 0.
+//
+// This file is copied on its own into projects as
+// `.specrails/runtime/spec-trace.mjs`, like pipeline-state.ts: Node built-ins
+// only, no imports from the rest of Core.
+import { existsSync, lstatSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+export const SPEC_TRACE_SCHEMA_VERSION = 1;
+export const SPEC_TRACE_FILE = 'spec-trace.json';
+const MAX_FILES = 20_000;
+const MAX_FILE_BYTES = 1_048_576;
+const SKIPPED_DIRECTORIES = new Set(['node_modules', '.git', '.hg', '.svn', 'dist', 'build', 'out', 'coverage', '.specrails', 'vendor', 'target', '.venv', 'venv', '__pycache__', '.next', '.nuxt', '.turbo', '.cache', 'openspec']);
+/** A file that IS a test across ecosystems: `x.test.ts`, `x.spec.js`, `test_x.py`, `x_test.go`, `x_spec.rb`, `XTest.java`, `test_x.sh`, `x.bats`. */
+export const TEST_FILE = /(?:^|\/)(?:test_[^/]+\.(?:py|sh)|[^/]+(?:\.(?:test|spec)\.[a-z0-9]+|_test\.(?:go|py|rs|rb|exs?|ts|js|sh)|_spec\.rb|Tests?\.(?:java|kt|cs|swift)|\.bats))$/i;
+/** `capability/slug`: lowercase, accents removed (NFKD), every run of non-alphanumerics a single dash, no leading or trailing dash. */
+export function requirementSlug(name) {
+    return name.normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+export function requirementId(capability, name) { return `${capability}/${requirementSlug(name)}`; }
+const posix = (file) => file.replace(/\\/g, '/').replace(/^\.\//, '');
+function readText(file) {
+    try {
+        const stat = lstatSync(file);
+        if (!stat.isFile() || stat.size > MAX_FILE_BYTES)
+            return undefined;
+        return readFileSync(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function directories(root) {
+    try {
+        return readdirSync(root, { withFileTypes: true }).filter(entry => entry.isDirectory() && !entry.isSymbolicLink()).map(entry => entry.name).sort();
+    }
+    catch {
+        return [];
+    }
+}
+const REQUIREMENT = /^###\s+Requirement:\s*(.+?)\s*$/;
+/** Requirements of the canonical specs, in capability then file order. */
+export function readSpecRequirements(specsRoot) {
+    const base = path.join(specsRoot, 'openspec', 'specs');
+    return directories(base).flatMap(capability => {
+        const file = path.join(base, capability, 'spec.md');
+        const text = readText(file);
+        if (text === undefined)
+            return [];
+        return text.split(/\r?\n/).flatMap((line, index) => {
+            const match = REQUIREMENT.exec(line);
+            return match ? [{ id: requirementId(capability, match[1]), capability, name: match[1], file: posix(path.relative(specsRoot, file)), line: index + 1 }] : [];
+        });
+    });
+}
+/** The change's directory: active, or its most recent archive (`archive/YYYY-MM-DD-<change>`). */
+export function changeDirectory(specsRoot, change) {
+    const active = path.join(specsRoot, 'openspec', 'changes', change);
+    if (existsSync(active))
+        return active;
+    const archive = path.join(specsRoot, 'openspec', 'changes', 'archive');
+    const found = directories(archive).filter(name => name === change || (/^\d{4}-\d{2}-\d{2}-/.test(name) && name.slice(11) === change)).at(-1);
+    return found ? path.join(archive, found) : undefined;
+}
+/** ADDED / MODIFIED / REMOVED / RENAMED requirements of a change's delta specs. */
+export function readChangeDelta(specsRoot, change) {
+    const delta = { added: [], modified: [], removed: [], renamed: [] };
+    const directory = changeDirectory(specsRoot, change);
+    if (!directory)
+        return delta;
+    for (const capability of directories(path.join(directory, 'specs'))) {
+        const file = path.join(directory, 'specs', capability, 'spec.md');
+        const text = readText(file);
+        if (text === undefined)
+            continue;
+        let section = '';
+        let from;
+        text.split(/\r?\n/).forEach((line, index) => {
+            const heading = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\b/i.exec(line);
+            if (heading) {
+                section = heading[1].toUpperCase();
+                return;
+            }
+            if (/^##\s/.test(line)) {
+                section = '';
+                return;
+            }
+            const requirement = (name) => ({ id: requirementId(capability, name), capability, name, file: posix(path.relative(specsRoot, file)), line: index + 1 });
+            if (section === 'RENAMED') {
+                const rename = /^\s*-\s*(FROM|TO):\s*`?\s*###\s+Requirement:\s*(.+?)\s*`?\s*$/i.exec(line);
+                if (!rename)
+                    return;
+                if (rename[1].toUpperCase() === 'FROM')
+                    from = requirementId(capability, rename[2]);
+                else if (from) {
+                    delta.renamed.push({ from, to: requirement(rename[2]) });
+                    from = undefined;
+                }
+                return;
+            }
+            const match = REQUIREMENT.exec(line);
+            if (!match)
+                return;
+            if (section === 'ADDED')
+                delta.added.push(requirement(match[1]));
+            else if (section === 'MODIFIED')
+                delta.modified.push(requirement(match[1]));
+            else if (section === 'REMOVED')
+                delta.removed.push(requirementId(capability, match[1]));
+        });
+    }
+    return delta;
+}
+/** Active (unarchived) changes, for a CI check that names none. */
+export function activeChanges(specsRoot) {
+    return directories(path.join(specsRoot, 'openspec', 'changes')).filter(name => name !== 'archive' && existsSync(path.join(specsRoot, 'openspec', 'changes', name, 'specs')));
+}
+const TITLE_TAG = /\[spec:\s*([^\]\s]+)\s*\]/gi;
+const COMMENT_TAG = /^\s*(?:\/\/+|#+|--+|;+|%+|\/\*+|\*+|<!--|\{-|\(\*)\s*spec:\s*([^\s*]+)/i;
+/** Tags in a test file's text with their 1-based lines. */
+export function scanTags(text) {
+    const tags = [];
+    text.split(/\r?\n/).forEach((line, index) => {
+        const comment = COMMENT_TAG.exec(line);
+        if (comment) {
+            tags.push({ tag: comment[1].replace(/[,;.]+$/, '').toLowerCase(), line: index + 1, form: 'comment' });
+            return;
+        }
+        for (const match of line.matchAll(TITLE_TAG))
+            tags.push({ tag: match[1].toLowerCase(), line: index + 1, form: 'title' });
+    });
+    return tags;
+}
+function globToRegExp(glob) {
+    const source = posix(glob).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*\//g, '\u0001').replace(/\*\*/g, '\u0002').replace(/\*/g, '[^/]*').replace(/\?/g, '[^/]').replace(/\u0001/g, '(?:.*/)?').replace(/\u0002/g, '.*');
+    return new RegExp(`^${source}$`);
+}
+function discoverTests(root, globs) {
+    const found = [];
+    const walk = (directory, relative) => {
+        if (found.length >= MAX_FILES)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name, 'en'))) {
+            if (entry.isSymbolicLink())
+                continue;
+            const name = relative ? relative + '/' + entry.name : entry.name;
+            if (entry.isDirectory()) {
+                if (!SKIPPED_DIRECTORIES.has(entry.name))
+                    walk(path.join(directory, entry.name), name);
+                continue;
+            }
+            if (entry.isFile() && (globs ? globs.some(glob => glob.test(name)) : TEST_FILE.test(name)))
+                found.push(name);
+            if (found.length >= MAX_FILES)
+                return;
+        }
+    };
+    walk(root, '');
+    return found;
+}
+/** Literal reachability: a command naming test-shaped paths reaches only those; any other command is assumed to discover every test. */
+export const literalReaches = (root, command, file) => {
+    const base = path.resolve(root, command.cwd ?? '.');
+    const target = posix(path.relative(base, path.resolve(root, file)));
+    const tokens = [command.command, ...command.args].filter(token => !token.startsWith('-')).map(posix);
+    // A bare word is a path only when it names an existing directory (`pytest tests`), never a script or verb (`npm test`).
+    const directory = (token) => { try {
+        return lstatSync(path.resolve(base, token)).isDirectory();
+    }
+    catch {
+        return false;
+    } };
+    const paths = tokens.slice(1).filter(token => TEST_FILE.test(token) || token.includes('*') || ((token.includes('/') || directory(token)) && !/^(?:run|test|exec)$/.test(token)));
+    if (!paths.length)
+        return true;
+    return paths.some(token => token === target || target.startsWith(token.replace(/\/$/, '') + '/') || (token.includes('*') && globToRegExp(token).test(target)));
+};
+/** The traceability report for the specs and tests under the input roots. Never throws for unreadable files; they are skipped. */
+export function traceSpecs(input) {
+    const changes = [...new Set(input.changes ?? [])];
+    const requirements = new Map();
+    for (const requirement of readSpecRequirements(input.specsRoot))
+        if (!requirements.has(requirement.id))
+            requirements.set(requirement.id, requirement);
+    const touched = new Set();
+    for (const change of changes) {
+        const delta = readChangeDelta(input.specsRoot, change);
+        for (const id of delta.removed)
+            requirements.delete(id);
+        for (const { from, to } of delta.renamed) {
+            requirements.delete(from);
+            requirements.set(to.id, to);
+            touched.add(to.id);
+        }
+        for (const requirement of [...delta.added, ...delta.modified]) {
+            if (!requirements.has(requirement.id))
+                requirements.set(requirement.id, requirement);
+            touched.add(requirement.id);
+        }
+    }
+    const globs = input.testGlobs?.length ? input.testGlobs.map(globToRegExp) : undefined;
+    const tags = [];
+    let scannedFiles = 0;
+    for (const repository of input.repositories) {
+        const files = new Set(discoverTests(repository.root, globs));
+        for (const explicit of input.testFiles ?? [])
+            if (explicit.repositoryId === repository.id)
+                files.add(posix(explicit.file));
+        for (const file of [...files].sort()) {
+            const absolute = path.resolve(repository.root, file);
+            const relative = posix(path.relative(repository.root, absolute));
+            if (!relative || relative.startsWith('..'))
+                continue;
+            const text = readText(absolute);
+            if (text === undefined)
+                continue;
+            scannedFiles += 1;
+            for (const tag of scanTags(text))
+                tags.push({ ...tag, repositoryId: repository.id, file: relative });
+        }
+    }
+    const receipt = input.receipt ?? null;
+    const evidence = receipt ? 'receipt' : input.testsPassed ? 'tests-passed' : 'none';
+    const reaches = input.reaches ?? literalReaches;
+    const roots = new Map(input.repositories.map(repository => [repository.id, repository.root]));
+    const execution = new Map();
+    const executed = (test) => {
+        const key = test.repositoryId + '\0' + test.file;
+        const cached = execution.get(key);
+        if (cached)
+            return cached;
+        let result = evidence === 'tests-passed' ? 'passed' : 'not-executed';
+        if (receipt) {
+            const root = roots.get(test.repositoryId);
+            const reaching = receipt.commands.filter(command => command.repositoryId === test.repositoryId && safeReach(reaches, root, command, test.file));
+            result = reaching.some(command => command.exitCode === 0) ? 'passed' : reaching.length ? 'failed' : 'not-executed';
+        }
+        execution.set(key, result);
+        return result;
+    };
+    const byRequirement = new Map();
+    const untagged = [];
+    for (const tag of tags) {
+        if (!requirements.has(tag.tag)) {
+            untagged.push(tag);
+            continue;
+        }
+        const list = byRequirement.get(tag.tag) ?? [];
+        if (!list.some(item => item.repositoryId === tag.repositoryId && item.file === tag.file && item.line === tag.line))
+            list.push({ repositoryId: tag.repositoryId, file: tag.file, line: tag.line });
+        byRequirement.set(tag.tag, list);
+    }
+    const demonstrated = [];
+    const undemonstrated = [];
+    for (const requirement of [...requirements.values()].sort((left, right) => left.id.localeCompare(right.id, 'en'))) {
+        const tests = byRequirement.get(requirement.id) ?? [];
+        const outcomes = tests.map(executed);
+        if (outcomes.includes('passed'))
+            demonstrated.push({ id: requirement.id, name: requirement.name, tests: tests.filter((_, index) => outcomes[index] === 'passed') });
+        else
+            undemonstrated.push({ id: requirement.id, name: requirement.name, reason: !tests.length ? 'no-test' : outcomes.includes('failed') ? 'failed' : 'not-executed', tests });
+    }
+    const missing = new Set(undemonstrated.map(item => item.id));
+    return {
+        schemaVersion: SPEC_TRACE_SCHEMA_VERSION, generatedAt: (input.now?.() ?? new Date()).toISOString(), changes, evidence, receiptId: receipt?.id ?? null,
+        requirements: requirements.size, demonstrated, undemonstrated, untagged, touched: [...touched].sort(), touchedUndemonstrated: [...touched].filter(id => missing.has(id)).sort(), scannedFiles,
+    };
+}
+function safeReach(reaches, root, command, file) {
+    try {
+        return reaches(root, { command: command.command, args: command.args, ...(command.cwd ? { cwd: command.cwd } : {}) }, file);
+    }
+    catch {
+        return true;
+    }
+}
+/** Requirement ids a change adds, modifies or renames: the ones its developer tags and `--check` enforces. */
+export function touchedRequirements(specsRoot, change) {
+    const delta = readChangeDelta(specsRoot, change);
+    return [...new Set([...delta.added, ...delta.modified, ...delta.renamed.map(item => item.to)].map(item => item.id))].sort();
+}
+/** One-line summary shown to hosts and reviewers: `Requirements demonstrated X/Y`. */
+export function traceSummary(report) {
+    return `Requirements demonstrated ${report.demonstrated.length}/${report.requirements}`;
+}
+export function renderTraceReport(report) {
+    const lines = [traceSummary(report) + (report.evidence === 'none' ? ' (no verification evidence: pass --tests-passed after running the tests, or --context for a run receipt)' : '')];
+    if (report.touched.length)
+        lines.push(`Touched by ${report.changes.join(', ')}: ${report.touched.length - report.touchedUndemonstrated.length}/${report.touched.length} demonstrated`);
+    for (const item of report.undemonstrated)
+        lines.push(`  ${report.touched.includes(item.id) ? '!' : '-'} ${item.id} (${item.reason}${item.tests.length ? ': ' + item.tests.map(test => test.file + ':' + test.line).join(', ') : ''})`);
+    for (const tag of report.untagged)
+        lines.push(`  ? ${tag.repositoryId}:${tag.file}:${tag.line} tags unknown requirement ${tag.tag}`);
+    return lines.join('\n') + '\n';
+}
+function parseTraceFlags(argv) {
+    const flags = { change: [], tests: [], testsPassed: false, check: false, json: false };
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        const [name, inline] = arg.startsWith('--') && arg.includes('=') ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)] : [arg, undefined];
+        const value = () => {
+            const next = inline ?? argv[++index];
+            if (next === undefined || next.startsWith('--'))
+                throw new Error(`${name} needs a value`);
+            return next;
+        };
+        if (name === 'trace')
+            continue;
+        else if (name === '--check')
+            flags.check = true;
+        else if (name === '--json')
+            flags.json = true;
+        else if (name === '--tests-passed')
+            flags.testsPassed = true;
+        else if (name === '--root')
+            flags.root = value();
+        else if (name === '--context')
+            flags.context = value();
+        else if (name === '--out')
+            flags.out = value();
+        else if (name === '--change')
+            flags.change.push(...value().split(',').map(item => item.trim()).filter(Boolean));
+        else if (name === '--tests')
+            flags.tests.push(...value().split(',').map(item => item.trim()).filter(Boolean));
+        else
+            throw new Error('Unknown trace option: ' + arg);
+    }
+    return flags;
+}
+function contextInput(file, flags) {
+    const context = JSON.parse(readFileSync(file, 'utf8'));
+    if (typeof context.artifactRoot !== 'string' || !Array.isArray(context.repositories))
+        throw new Error('Invalid pipeline context: artifactRoot and repositories are required');
+    const repositories = context.repositories.map(item => item).filter(item => typeof item.id === 'string' && typeof item.path === 'string').map(item => ({ id: item.id, root: item.path }));
+    let receipt = null;
+    let change;
+    if (typeof context.backlogRoot === 'string' && typeof context.runId === 'string' && /^[A-Za-z0-9._-]+$/.test(context.runId)) {
+        const stateFile = path.join(context.backlogRoot, '.specrails', 'pipeline', context.runId, 'state.json');
+        const state = existsSync(stateFile) ? JSON.parse(readFileSync(stateFile, 'utf8')) : undefined;
+        if (typeof state?.change === 'string')
+            change = state.change;
+        if (state?.verification && Array.isArray(state.verification.commands))
+            receipt = { ...(state.verification.id ? { id: state.verification.id } : {}), commands: state.verification.commands };
+    }
+    return { specsRoot: context.artifactRoot, repositories, changes: flags.change.length ? flags.change : change ? [change] : activeChanges(context.artifactRoot), receipt, testsPassed: flags.testsPassed, ...(flags.tests.length ? { testGlobs: flags.tests } : {}) };
+}
+/**
+ * `pipeline trace [--root <dir>] [--context <context.json>] [--change <name>[,…]] [--tests <glob>[,…]] [--tests-passed] [--check] [--json] [--out <file>]`.
+ * Normal mode is fail-open: it reports and exits 0 even when it cannot read
+ * something. `--check` exits 1 when a requirement touched by the change is
+ * not demonstrated (or the scan itself fails).
+ */
+export async function runSpecTraceCli(argv, options = {}) {
+    const stdout = options.stdout ?? (text => process.stdout.write(text));
+    const stderr = options.stderr ?? (text => process.stderr.write(text));
+    let flags;
+    try {
+        flags = parseTraceFlags(argv);
+        const root = path.resolve(flags.root ?? process.cwd());
+        const input = flags.context
+            ? contextInput(flags.context, flags)
+            : { specsRoot: root, repositories: [{ id: path.basename(root) || 'root', root }], changes: flags.change.length ? flags.change : activeChanges(root), testsPassed: flags.testsPassed, ...(flags.tests.length ? { testGlobs: flags.tests } : {}) };
+        const report = traceSpecs({ ...input, ...(options.reaches ? { reaches: options.reaches } : {}) });
+        if (flags.out)
+            writeFileSync(flags.out, JSON.stringify(report, null, 2) + '\n');
+        stdout(flags.json ? JSON.stringify(report) + '\n' : renderTraceReport(report));
+        if (flags.check && report.touchedUndemonstrated.length) {
+            stderr(`Spec trace check failed: ${report.touchedUndemonstrated.length} touched requirement${report.touchedUndemonstrated.length === 1 ? '' : 's'} not demonstrated: ${report.touchedUndemonstrated.join(', ')}\n`);
+            return 1;
+        }
+        return 0;
+    }
+    catch (error) {
+        stderr('Spec trace: ' + (error instanceof Error ? error.message : String(error)) + '\n');
+        return flags?.check || argv.includes('--check') ? 1 : 0;
+    }
+}

package/dist/shared/secret-redaction.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Deterministic secret redaction for text and structured values that Core
+ * persists for display (the agent session journal).
+ *
+ * Every pattern is bounded: quantifiers have explicit upper limits and no
+ * pattern nests unbounded repetition, so the work per input character is
+ * constant and a 1 MB string redacts in linear time. PEM blocks are found with
+ * `indexOf`, not a regex, for the same reason.
+ *
+ * The rules favour leaking less over keeping every byte: a value assigned to a
+ * secret-like name is replaced even when it is not a credential (for example
+ * `token = readToken()` in a file read). Words that merely contain a secret
+ * word are not names: `author`, `authority`, `authenticate`, `max_tokens` and
+ * `tokenizer` stay readable. Bare `session` / `sessionId` are protocol
+ * identifiers and are not redacted; `session_token`, `session_secret`,
+ * `session_key` and `session_cookie` are.
+ *
+ * Known limits (documented in docs/agent-sessions/journal.md):
+ * - A secret split across two separately redacted strings (for example two
+ *   streamed output deltas) can leak the part after the split.
+ * - Short flags such as `mysql -pSECRET` and secrets with no recognisable name
+ *   or format are not detected.
+ *
+ * `src/pipeline/pipeline-state.ts` keeps its own self-contained
+ * `redactRuntimeText` because it is copied into projects and may only use Node
+ * built-ins; it is not replaced by this module.
+ */
+export declare const REDACTED = "[REDACTED]";
+/** True when a key, variable or flag name looks like it holds a secret. */
+export declare function isSecretName(name: string): boolean;
+/**
+ * Replace secrets inside free text. Idempotent: redacting a redacted string
+ * returns it unchanged. Non-secret text is returned byte for byte.
+ */
+export declare function redactSecrets(text: string): string;
+/**
+ * Redact a JSON-like value: object entries whose key is secret-like have their
+ * string leaves replaced; every other string goes through `redactSecrets`.
+ * Numbers, booleans and null are kept (a numeric `max_tokens` stays readable).
+ * Returns a new value; the input is not mutated. Depth is bounded.
+ */
+export declare function redactSecretsDeep<T>(value: T): T;

package/dist/shared/secret-redaction.js

@@ -0,0 +1,184 @@
+/**
+ * Deterministic secret redaction for text and structured values that Core
+ * persists for display (the agent session journal).
+ *
+ * Every pattern is bounded: quantifiers have explicit upper limits and no
+ * pattern nests unbounded repetition, so the work per input character is
+ * constant and a 1 MB string redacts in linear time. PEM blocks are found with
+ * `indexOf`, not a regex, for the same reason.
+ *
+ * The rules favour leaking less over keeping every byte: a value assigned to a
+ * secret-like name is replaced even when it is not a credential (for example
+ * `token = readToken()` in a file read). Words that merely contain a secret
+ * word are not names: `author`, `authority`, `authenticate`, `max_tokens` and
+ * `tokenizer` stay readable. Bare `session` / `sessionId` are protocol
+ * identifiers and are not redacted; `session_token`, `session_secret`,
+ * `session_key` and `session_cookie` are.
+ *
+ * Known limits (documented in docs/agent-sessions/journal.md):
+ * - A secret split across two separately redacted strings (for example two
+ *   streamed output deltas) can leak the part after the split.
+ * - Short flags such as `mysql -pSECRET` and secrets with no recognisable name
+ *   or format are not detected.
+ *
+ * `src/pipeline/pipeline-state.ts` keeps its own self-contained
+ * `redactRuntimeText` because it is copied into projects and may only use Node
+ * built-ins; it is not replaced by this module.
+ */
+export const REDACTED = '[REDACTED]';
+const MAX_PEM_BODY = 16_384;
+/**
+ * Secret words inside a normalized (lower-case, `_`-separated) name.
+ * `auth` must end a word so `author`/`authority`/`authenticate` do not match.
+ * `token` must not be followed by `s`/`iz` so token counts and tokenizers stay.
+ */
+const SECRET_NAME = /(?:passw(?:or)?d|passphrase|secret|token(?!s|iz)|api_?key|access_?key|private_?key|signing_?key|encryption_?key|credentials?|(?:^|_)auth(?:orization)?(?:_|$)|bearer|cookie|session_(?:token|secret|key|cookie))/;
+/** Lower-case and split camelCase / kebab-case / dotted names into `_` words. */
+function normalizeName(name) {
+    return name
+        .slice(0, 128)
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_');
+}
+/** True when a key, variable or flag name looks like it holds a secret. */
+export function isSecretName(name) {
+    return SECRET_NAME.test(normalizeName(name));
+}
+// ── Inline patterns ─────────────────────────────────────────────────────────
+/** Well-known credential formats, replaced wherever they appear. */
+const KNOWN_FORMATS = [
+    // OpenAI / Anthropic style keys: sk-..., sk-proj-..., sk-ant-...; must contain a digit.
+    /\bsk-(?=[A-Za-z0-9_-]{0,200}\d)[A-Za-z0-9_-]{20,512}/g,
+    // GitHub tokens.
+    /\bgh[pousr]_[A-Za-z0-9]{36,255}\b/g,
+    /\bgithub_pat_[A-Za-z0-9_]{22,255}\b/g,
+    // GitLab and npm tokens.
+    /\bglpat-[A-Za-z0-9_-]{20,255}\b/g,
+    /\bnpm_[A-Za-z0-9]{36,255}\b/g,
+    // Slack tokens.
+    /\bxox[abeoprs]-[A-Za-z0-9-]{10,255}/g,
+    /\bxapp-[A-Za-z0-9-]{10,255}/g,
+    // AWS access key ids.
+    /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g,
+    // Google API keys.
+    /\bAIza[0-9A-Za-z_-]{35}(?![0-9A-Za-z_-])/g,
+    // JSON Web Tokens.
+    /\beyJ[A-Za-z0-9_-]{8,4096}\.eyJ[A-Za-z0-9_-]{8,4096}\.[A-Za-z0-9_-]{8,4096}/g,
+];
+/** `Authorization: Bearer x`, `"authorization": "Basic x"`, `Proxy-Authorization=...`; keeps the scheme. */
+const AUTHORIZATION_HEADER = /\b((?:proxy-)?authorization["']?[ \t]{0,8}[:=][ \t]{0,8}["']?)((?:bearer|basic|token|digest|negotiate)[ \t]{1,8})?([^\s"'`,;]{1,4096})/gi;
+/** A standalone `Bearer <token>` (the token must be long enough not to be prose). */
+const BEARER = /\b(bearer[ \t]{1,8})([A-Za-z0-9._~+/-]{16,4096}=*)/gi;
+/** `scheme://user:password@host` → keeps the user and host. */
+const URL_CREDENTIALS = /\b([a-z][a-z0-9+.-]{0,20}:\/\/[^\s:/@]{1,256}:)([^\s/@]{1,256})(@)/gi;
+/**
+ * `--token v`, `--api-key=v`, `--password "v"`: the flag name must END with the
+ * secret word, so `--password-stdin` or `--token-file` are left alone; a value
+ * starting with `-` is the next flag, not a secret.
+ */
+const SECRET_FLAG = /(^|[\s"'=])(--?(?:[a-z0-9]{1,24}[-_]){0,4}(?:token|api[-_]?key|apikey|password|passwd|passphrase|secret|private[-_]?key|access[-_]?key|auth|credentials?))(=|[ \t]{1,8})("[^"\n]{0,4096}"|'[^'\n]{0,4096}'|[^\s"'-][^\s"']{0,4095})/gi;
+/**
+ * `NAME=value`, `NAME: value`, `"name": "value"`, `export NAME='v'` where the
+ * name contains a secret word. The name starts at a non-name character so
+ * matching is attempted only at word starts; `isSecretName` then refines it.
+ */
+const ASSIGNMENT = /(?<![A-Za-z0-9_.-])(["']?)([A-Za-z_][A-Za-z0-9_.-]{0,127})\1([ \t]{0,4}[:=][ \t]{0,4})("[^"\n]{0,4096}"|'[^'\n]{0,4096}'|\[REDACTED\][^\s"',;&|<>(){}[\]]{1,4096}|(?![ \t]|\/\/)[^\s"',;&|<>(){}[\]]{1,4096})/g;
+/** Values that are not secrets even after a secret-like name (types, flags, empty literals). */
+const KEPT_VALUES = new Set(['', 'true', 'false', 'null', 'undefined', 'none', 'string', 'number', 'boolean', 'unknown', 'any', 'required', 'optional']);
+const PEM_BEGIN = /-----BEGIN [A-Z0-9 ]{0,40}PRIVATE KEY-----/g;
+function replaceValue(quoted) {
+    if (quoted.startsWith('"') && quoted.endsWith('"') && quoted.length >= 2)
+        return `"${REDACTED}"`;
+    if (quoted.startsWith("'") && quoted.endsWith("'") && quoted.length >= 2)
+        return `'${REDACTED}'`;
+    return REDACTED;
+}
+/** PEM private key blocks: BEGIN..END, or BEGIN plus its base64 body when END is missing (truncated output). */
+function redactPem(text) {
+    if (!text.includes('PRIVATE KEY-----'))
+        return text;
+    let out = '';
+    let cursor = 0;
+    // The next END marker is searched once and reused, so a text full of BEGIN
+    // markers without END stays linear.
+    let nextEnd = -2;
+    PEM_BEGIN.lastIndex = 0;
+    for (let match = PEM_BEGIN.exec(text); match; match = PEM_BEGIN.exec(text)) {
+        const begin = match.index;
+        if (begin < cursor)
+            continue;
+        const bodyStart = begin + match[0].length;
+        if (nextEnd !== -1 && nextEnd < bodyStart)
+            nextEnd = text.indexOf('-----END ', bodyStart);
+        const endMarker = nextEnd;
+        let stop;
+        if (endMarker >= 0 && endMarker - bodyStart <= MAX_PEM_BODY) {
+            const close = text.indexOf('-----', endMarker + 9);
+            stop = close >= 0 && close - endMarker <= 60 ? close + 5 : endMarker + 9;
+        }
+        else {
+            stop = bodyStart;
+            const limit = Math.min(text.length, bodyStart + MAX_PEM_BODY);
+            while (stop < limit && /[A-Za-z0-9+/=\s]/.test(text[stop]))
+                stop++;
+        }
+        out += text.slice(cursor, begin) + REDACTED;
+        cursor = stop;
+        PEM_BEGIN.lastIndex = Math.max(stop, bodyStart);
+    }
+    return out + text.slice(cursor);
+}
+/**
+ * Replace secrets inside free text. Idempotent: redacting a redacted string
+ * returns it unchanged. Non-secret text is returned byte for byte.
+ */
+export function redactSecrets(text) {
+    if (text.length === 0)
+        return text;
+    let result = redactPem(text);
+    for (const pattern of KNOWN_FORMATS)
+        result = result.replace(pattern, REDACTED);
+    result = result.replace(AUTHORIZATION_HEADER, (_match, prefix, scheme) => `${prefix}${scheme ?? ''}${REDACTED}`);
+    result = result.replace(BEARER, (_match, prefix) => `${prefix}${REDACTED}`);
+    result = result.replace(URL_CREDENTIALS, (_match, prefix, _password, at) => `${prefix}${REDACTED}${at}`);
+    result = result.replace(SECRET_FLAG, (_match, lead, flag, separator, value) => `${lead}${flag}${separator}${replaceValue(value)}`);
+    result = result.replace(ASSIGNMENT, (match, quote, name, separator, value, offset, whole) => {
+        if (!isSecretName(name))
+            return match;
+        const bare = value.replace(/^["']|["']$/g, '');
+        if (bare === REDACTED || KEPT_VALUES.has(bare.toLowerCase()) || bare.startsWith('$'))
+            return match;
+        // `Authorization: Bearer [REDACTED]` was already handled: do not take the scheme for the value.
+        if (whole.slice(offset + match.length, offset + match.length + 24).trimStart().startsWith(REDACTED))
+            return match;
+        return `${quote}${name}${quote}${separator}${replaceValue(value)}`;
+    });
+    return result;
+}
+/**
+ * Redact a JSON-like value: object entries whose key is secret-like have their
+ * string leaves replaced; every other string goes through `redactSecrets`.
+ * Numbers, booleans and null are kept (a numeric `max_tokens` stays readable).
+ * Returns a new value; the input is not mutated. Depth is bounded.
+ */
+export function redactSecretsDeep(value) {
+    return redactValue(value, false, 0);
+}
+const MAX_DEPTH = 32;
+function redactValue(value, secret, depth) {
+    if (typeof value === 'string')
+        return secret ? (value.length === 0 ? value : REDACTED) : redactSecrets(value);
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (depth >= MAX_DEPTH)
+        return secret ? REDACTED : value;
+    if (Array.isArray(value))
+        return value.map((item) => redactValue(item, secret, depth + 1));
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        out[key] = redactValue(item, secret || isSecretName(key), depth + 1);
+    }
+    return out;
+}