upstreamfix 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UpstreamFix contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# UpstreamFix
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**UpstreamFix previews code changes for supported breaking SDK upgrades, reports cases that need a developer, and can commit verified changes on a dedicated Git branch.**
+
+> **Experimental (0.1.0).** Review every proposed change and test your application before using a migration in production. The source code is available in the [public GitHub repository](https://github.com/ivanDev237/upstreamfix).
+
+## Demo
+
+![Illustrative terminal walkthrough of listing, scanning, and previewing a migration](docs/upstreamfix-demo.gif)
+
+The frames show the intended command flow. Output varies with the project and migration findings.
+
+## Quick start
+
+Once a release is available on npm, start with `npx upstreamfix@latest list`. To inspect a project without changing its files, run:
+
+```sh
+npx --yes upstreamfix@latest list
+npx --yes upstreamfix@latest scan --cwd /path/to/your/project
+npx --yes upstreamfix@latest migrate firebase-admin@14 --cwd /path/to/your/project --report /tmp/firebase-admin-v14.md
+```
+
+The report path is explicit; preview commands do not create report files unless `--report` is supplied. The Firebase Admin migration currently targets projects using the namespaced API and proposes modular API changes. Review the diff and manual findings against the [official migration guide](https://firebase.google.com/docs/admin/migrate-node-v10).
+
+## Supported migrations
+
+| Migration | What it previews | Status |
+|---|---|---|
+| `firebase-admin@14` | Firebase Admin SDK v13 namespaced API to v14 modular API | Benchmarked on 12 valid public repositories; 316 of 340 detected change groups migrated automatically. Manual findings and runtime prerequisites still require review. |
+| `stripe@22` | Stripe Node SDK v21 to v22 | Benchmarked on 6 installable public repositories; payment-sensitive cases remain manual. See [Stripe's v22 guide](https://github.com/stripe/stripe-node/wiki/Migration-guide-for-v22). |
+| `stripe@23` | Stripe Node SDK v22 to v23 | Benchmarked on 4 public repositories; a removed payment parameter was identified for manual review. See [Stripe's v23 guide](https://github.com/stripe/stripe-node/wiki/Migration-guide-for-v23). |
+
+Run `upstreamfix list` for the catalog included in the installed version. Run `upstreamfix scan --cwd <project>` to select migrations from package versions declared in root or nested `package.json` files.
+
+## What is not supported
+
+- The GitHub Action exits without changing a repository; automatic pull requests are not available.
+- UpstreamFix does not watch package registries, discover new API changes, or invent migrations. It only previews migration rules already included in the release.
+- Only migrations shown by `upstreamfix list` are supported. Unsupported, ambiguous, or semantic API changes require manual work.
+- Lockfile previews cover standalone root projects using npm v3, pnpm, or Yarn Classic lockfiles. Regenerating a lockfile may contact the package registry; pnpm or Yarn must already be installed and match any `packageManager` pin. Workspaces, Yarn Berry, shrinkwrap, project package-manager configuration files, and local or non-registry dependencies are left for manual review.
+
+## Safety and data
+
+UpstreamFix runs locally. It reads source files, package manifests, and supported lockfiles in the selected project. It does not upload project source to an UpstreamFix service. A preview can invoke npm, pnpm, or Yarn to regenerate a supported lockfile; this may contact the package registry, but the updater uses a fresh temporary home and does not pass your environment tokens or package-manager config. Preview does not write project files unless you explicitly request a report with `--report`.
+
+Optional `--verify` requires a Git working tree and copies tracked or non-ignored files into a size-limited temporary directory. It excludes common credential files, package-manager configuration, and symlinks, then installs dependencies with scripts disabled. Configured typecheck and test scripts still execute on your machine with a restricted environment; they are project code, can run arbitrary commands, and can access the network. Only verify projects and scripts you trust, and avoid projects whose tests can access production services or perform external side effects. Dependency installation can contact the package registry. The original project directory is left unchanged.
+
+After reviewing a preview, `--write` verifies the migration in an isolated Git worktree and commits it on a new `upstreamfix/<migration>` branch. It refuses non-Git projects, dirty trees (unless `--allow-dirty` is supplied), manual findings, missing or failed verification checks, and source changes whose containing manifest does not declare the target SDK major. It never switches or edits your current working tree. Verification still runs project scripts on your machine, so use it only with projects you trust. No branch is merged or pushed automatically.
+
+Firebase Admin v14 requires Node.js 22 or newer. If your project omits `engines.node`, the preview explains why the dependency cannot yet be upgraded. Once you have confirmed your deployment runtime, add `"engines": { "node": ">=22" }` yourself or pass `--node-runtime 22` to `migrate firebase-admin@14` (including with `--write`). That option proposes the Node range alongside the SDK update. It never overrides an existing incompatible `engines.node` range.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, test guidance, and how to add a migration. Security reports belong in the private reporting process described in [SECURITY.md](SECURITY.md). UpstreamFix is licensed under the [MIT License](LICENSE).
+
+## Development
+
+Requires Node.js 22.12 or newer.
+
+```sh
+npm ci
+npm run typecheck
+npm test
+```
+
+To build and run the CLI from this checkout:
+
+```sh
+npm run build
+node dist/cli.js list
+node dist/cli.js migrate firebase-admin@14 --cwd /path/to/fixture
+```
+
+Add a migration scaffold with `npm run new-migration -- <npm-package> <target-major>`. Its real-SDK compatibility test is opt-in because it downloads SDK versions: set `UPSTREAMFIX_RUN_REAL_SDK_TESTS=1` when running that generated test.

package/dist/cli.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+import { Command, CommanderError, InvalidArgumentError } from 'commander';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { renderMarkdownReport, renderTerminalReport } from './core/report.js';
+import { runMigration } from './core/runner.js';
+import { verifyProposedMigration } from './core/verify.js';
+import { writeMigrationOnBranch } from './core/write-branch.js';
+import { assertWritesEnabled } from './core/safety.js';
+import { findApplicableMigrations, migrations } from './migrations/index.js';
+function existingMigration(value) {
+    if (!migrations.some((migration) => migration.id === value)) {
+        throw new InvalidArgumentError(`Unknown migration "${value}". Available: ${migrations.map((migration) => migration.id).join(', ')}`);
+    }
+    return value;
+}
+export function createProgram() {
+    const program = new Command();
+    program
+        .name('upstreamfix')
+        .description('Prepare and review automated code migrations for breaking SDK changes.')
+        .showHelpAfterError()
+        .exitOverride();
+    program
+        .command('list')
+        .description('List the migrations included in this UpstreamFix release.')
+        .action(() => {
+        if (migrations.length === 0) {
+            console.log('No migrations are available in this release.');
+            return;
+        }
+        console.log('| Migration | Package | From → To | Released | Automated rules |');
+        console.log('|---|---|---:|---|---|');
+        for (const migration of migrations) {
+            console.log(`| ${migration.id} | ${migration.packageName} | ${migration.fromMajor} → ${migration.toMajor} | ${migration.releasedAt} | ${migration.rules.join(', ')} |`);
+        }
+    });
+    program
+        .command('migrate')
+        .description('Run a supported migration against a project.')
+        .argument('<migration>', 'migration identifier, for example firebase-admin@14', existingMigration)
+        .option('-C, --cwd <directory>', 'project directory to migrate', process.cwd())
+        .option('--write', 'apply verified changes in a new Git branch and create a commit')
+        .option('--allow-dirty', 'allow a dirty working tree; the migration branch is based on committed HEAD')
+        .option('--verify', 'verify proposed changes in a temporary project copy')
+        .option('--node-runtime <major>', 'confirm Firebase Admin v14 will run on Node.js 22+ and add engines.node when absent', parseNodeRuntime)
+        .option('--verify-timeout <seconds>', 'maximum time per verification command', parsePositiveInteger)
+        .option('--report <file>', 'write the Markdown report to this explicit path (relative paths use --cwd)')
+        .action(async (migrationId, options) => {
+        const migration = migrations.find((candidate) => candidate.id === migrationId);
+        if (options.nodeRuntime && migration.id !== 'firebase-admin@14')
+            throw new Error('--node-runtime 22 is supported only for firebase-admin@14.');
+        const cwd = path.resolve(options.cwd);
+        if (options.allowDirty && !options.write)
+            throw new Error('--allow-dirty can only be used together with --write.');
+        let writeResult;
+        if (options.write) {
+            assertWritesEnabled(false);
+            writeResult = await writeMigrationOnBranch(migration, {
+                cwd,
+                allowDirty: options.allowDirty,
+                nodeRuntime: options.nodeRuntime,
+                timeoutMs: (options.verifyTimeout ?? 300) * 1000,
+            });
+        }
+        const outcome = writeResult?.outcome ?? await runMigration(migration, { cwd, dryRun: true, nodeRuntime: options.nodeRuntime });
+        const verification = writeResult?.verification ?? (options.verify
+            ? await verifyProposedMigration(cwd, outcome.proposedDiff, { packageName: migration.packageName, fileChanges: outcome.proposedFiles, timeoutMs: (options.verifyTimeout ?? 300) * 1000 })
+            : undefined);
+        const report = renderMarkdownReport(migration, outcome, !options.write, verification);
+        console.log(renderTerminalReport(report));
+        if (options.report) {
+            const reportPath = path.resolve(cwd, options.report);
+            await mkdir(path.dirname(reportPath), { recursive: true });
+            await writeFile(reportPath, report, 'utf8');
+            console.log(`Report saved to ${path.relative(cwd, reportPath) || path.basename(reportPath)}`);
+        }
+        if (writeResult)
+            console.log(`Committed on branch ${writeResult.branch}: ${writeResult.commit}`);
+        if (verification?.status === 'failed')
+            process.exitCode = 1;
+        if (!options.write)
+            console.log('Preview only. No project files were written.');
+    });
+    program
+        .command('scan')
+        .description('Run supported migrations that match dependencies declared in a project.')
+        .option('-C, --cwd <directory>', 'project directory to scan', process.cwd())
+        .option('--write', 'apply each verified migration in a new Git branch and create a commit')
+        .option('--allow-dirty', 'allow a dirty working tree; migration branches use committed HEAD')
+        .option('--verify', 'verify each proposed migration in a temporary project copy')
+        .option('--node-runtime <major>', 'confirm Firebase Admin v14 will run on Node.js 22+ and add engines.node when absent', parseNodeRuntime)
+        .option('--verify-timeout <seconds>', 'maximum time per verification command', parsePositiveInteger)
+        .option('--report <file>', 'write Markdown reports to this explicit path (relative paths use --cwd)')
+        .action(async (options) => {
+        const cwd = path.resolve(options.cwd);
+        if (options.allowDirty && !options.write)
+            throw new Error('--allow-dirty can only be used together with --write.');
+        const reports = [];
+        const commits = [];
+        let verificationFailed = false;
+        const applicable = await findApplicableMigrations(cwd);
+        if (applicable.length === 0) {
+            console.log('No supported migration applies to the dependencies declared in this project.');
+            return;
+        }
+        for (const migration of applicable) {
+            let writeResult;
+            if (options.write) {
+                assertWritesEnabled(false);
+                writeResult = await writeMigrationOnBranch(migration, {
+                    cwd,
+                    allowDirty: options.allowDirty,
+                    nodeRuntime: migration.id === 'firebase-admin@14' ? options.nodeRuntime : undefined,
+                    timeoutMs: (options.verifyTimeout ?? 300) * 1000,
+                });
+                commits.push({ branch: writeResult.branch, commit: writeResult.commit });
+            }
+            const outcome = writeResult?.outcome ?? await runMigration(migration, { cwd, dryRun: true, nodeRuntime: migration.id === 'firebase-admin@14' ? options.nodeRuntime : undefined });
+            const verification = writeResult?.verification ?? (options.verify
+                ? await verifyProposedMigration(cwd, outcome.proposedDiff, { packageName: migration.packageName, fileChanges: outcome.proposedFiles, timeoutMs: (options.verifyTimeout ?? 300) * 1000 })
+                : undefined);
+            if (verification?.status === 'failed')
+                verificationFailed = true;
+            reports.push(renderMarkdownReport(migration, outcome, !options.write, verification));
+        }
+        const report = reports.join('\n---\n\n');
+        console.log(renderTerminalReport(report));
+        if (options.report) {
+            const reportPath = path.resolve(cwd, options.report);
+            await mkdir(path.dirname(reportPath), { recursive: true });
+            await writeFile(reportPath, report, 'utf8');
+            console.log(`Report saved to ${path.relative(cwd, reportPath) || path.basename(reportPath)}`);
+        }
+        for (const commit of commits)
+            console.log(`Committed on branch ${commit.branch}: ${commit.commit}`);
+        if (verificationFailed)
+            process.exitCode = 1;
+        if (!options.write)
+            console.log('Preview only. No project files were written.');
+    });
+    return program;
+}
+function parsePositiveInteger(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1)
+        throw new Error('Timeout must be a positive integer number of seconds.');
+    return parsed;
+}
+function parseNodeRuntime(value) {
+    if (value !== '22')
+        throw new InvalidArgumentError('Only --node-runtime 22 is supported for firebase-admin@14.');
+    return 22;
+}
+const invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : '';
+if (invokedPath === fileURLToPath(import.meta.url)) {
+    createProgram().parseAsync().catch((error) => {
+        if (error instanceof CommanderError && error.exitCode === 0) {
+            process.exitCode = 0;
+            return;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`upstreamfix: ${message}`);
+        process.exitCode = 1;
+    });
+}

package/dist/core/diagnostic-diff.js

@@ -0,0 +1,41 @@
+/** Parse the ordinary, non-pretty `tsc` output without executing project code. */
+export function parseTypeScriptDiagnostics(output) {
+    const diagnostics = [];
+    // A failed command can prepend text on the same line as the first tsc
+    // diagnostic; begin at the source path, never at the command wrapper.
+    const pattern = /(?:^|\s)([^\s():]+\.(?:[cm]?tsx?|jsx?))\((\d+),(\d+)\): error TS(\d+): ([^\r\n]+)/g;
+    for (const match of output.matchAll(pattern)) {
+        const file = match[1].replaceAll('\\', '/').replace(/^\/workspace\//, '').replace(/^\.\//, '');
+        diagnostics.push({
+            file,
+            line: Number(match[2]),
+            column: Number(match[3]),
+            code: Number(match[4]),
+            message: match[5].trim().replace(/\s+/g, ' '),
+        });
+    }
+    return diagnostics;
+}
+/**
+ * Compare diagnostic multisets by file, error code and message. Positions are
+ * intentionally excluded: a harmless preceding edit must not create a finding.
+ * These are candidates only; a changed SDK is not necessarily the cause.
+ */
+export function newTypeScriptDiagnostics(before, after) {
+    const existing = new Map();
+    for (const diagnostic of before) {
+        const key = diagnosticKey(diagnostic);
+        existing.set(key, (existing.get(key) ?? 0) + 1);
+    }
+    return after.filter((diagnostic) => {
+        const key = diagnosticKey(diagnostic);
+        const previous = existing.get(key) ?? 0;
+        if (previous === 0)
+            return true;
+        existing.set(key, previous - 1);
+        return false;
+    });
+}
+function diagnosticKey(diagnostic) {
+    return `${diagnostic.file}\0${diagnostic.code}\0${diagnostic.message}`;
+}

package/dist/core/process-cleanup.js

@@ -0,0 +1,77 @@
+const processGroups = new Set();
+const temporaryCleanups = new Set();
+let handlersInstalled = false;
+let shutdownStarted = false;
+export function trackProcessGroup(pid) {
+    processGroups.add(pid);
+    installSignalHandlers();
+    return () => {
+        processGroups.delete(pid);
+        uninstallSignalHandlersIfIdle();
+    };
+}
+export function registerTemporaryCleanup(cleanup) {
+    temporaryCleanups.add(cleanup);
+    installSignalHandlers();
+    return () => {
+        temporaryCleanups.delete(cleanup);
+        uninstallSignalHandlersIfIdle();
+    };
+}
+export async function terminateProcessGroup(pid, graceMs = 100) {
+    signalGroup(pid, 'SIGTERM');
+    if (graceMs > 0)
+        await new Promise((resolve) => setTimeout(resolve, graceMs));
+    signalGroup(pid, 'SIGKILL');
+    processGroups.delete(pid);
+}
+function signalGroup(pid, signal) {
+    try {
+        if (process.platform === 'win32')
+            process.kill(pid, signal);
+        else
+            process.kill(-pid, signal);
+    }
+    catch (error) {
+        if (error.code !== 'ESRCH') {
+            try {
+                process.kill(pid, signal);
+            }
+            catch { /* The process already exited. */ }
+        }
+    }
+}
+function installSignalHandlers() {
+    if (handlersInstalled)
+        return;
+    process.on('SIGINT', handleSigint);
+    process.on('SIGTERM', handleSigterm);
+    handlersInstalled = true;
+}
+function uninstallSignalHandlersIfIdle() {
+    if (!handlersInstalled || processGroups.size > 0 || temporaryCleanups.size > 0)
+        return;
+    process.off('SIGINT', handleSigint);
+    process.off('SIGTERM', handleSigterm);
+    handlersInstalled = false;
+}
+function handleSigint() {
+    void shutdown('SIGINT');
+}
+function handleSigterm() {
+    void shutdown('SIGTERM');
+}
+async function shutdown(signal) {
+    if (shutdownStarted)
+        return;
+    shutdownStarted = true;
+    const pids = [...processGroups];
+    for (const pid of pids)
+        signalGroup(pid, 'SIGTERM');
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    for (const pid of pids)
+        signalGroup(pid, 'SIGKILL');
+    processGroups.clear();
+    await Promise.allSettled([...temporaryCleanups].map((cleanup) => cleanup()));
+    process.exit(signal === 'SIGINT' ? 130 : 143);
+}

package/dist/core/report.js

@@ -0,0 +1,131 @@
+export function renderMarkdownReport(migration, outcome, dryRun, verification) {
+    const lines = [];
+    const total = outcome.changes.length + outcome.manual.length;
+    lines.push(`# Migration report: ${migration.title}`);
+    lines.push('');
+    if (dryRun)
+        lines.push('> Dry run: no file was written.\n');
+    lines.push(`- Findings: **${total}**`);
+    lines.push(`- ${dryRun ? 'Proposed transformations' : 'Applied transformations'}: **${outcome.changes.length}**`);
+    lines.push(`- Need your attention: **${outcome.manual.length}**`);
+    lines.push(`- ${dryRun ? 'Files with proposed changes' : 'Files changed'}: **${outcome.filesChanged.length}**`);
+    lines.push(`- Official guide: ${migration.guideUrl}`);
+    lines.push('');
+    if (total === 0) {
+        lines.push('No supported Firebase Admin namespace usages were found in the scanned files.');
+        lines.push('');
+    }
+    if (outcome.manual.length > 0) {
+        lines.push('## Needs your attention');
+        lines.push('');
+        for (const item of outcome.manual) {
+            lines.push(`- ${inlineCode(`${item.file}:${item.line}`)} ${escapeMarkdownText(item.reason).replace(/\r?\n/g, ' ')}`);
+            lines.push(`  ${inlineCode(item.snippet)}`);
+        }
+        lines.push('');
+    }
+    if (outcome.manifestNotes.length > 0) {
+        lines.push('## package.json');
+        lines.push('');
+        for (const note of outcome.manifestNotes)
+            lines.push(`- ${escapeMarkdownText(note).replace(/\r?\n/g, ' ')}`);
+        lines.push('');
+    }
+    if (verification) {
+        lines.push('## Verification');
+        lines.push('');
+        lines.push(`- Result: **${verification.status}**`);
+        lines.push('- Scope: temporary project copy; the original project was not changed.');
+        lines.push('- Verification commands run on this machine with a restricted environment, without copied credentials or package install scripts; project test code is still executable code and is not network-isolated.');
+        if (verification.note)
+            lines.push(`- Note: ${verification.note}`);
+        if (verification.checks.length > 0) {
+            lines.push('');
+            lines.push('| Check | Command | Result | Duration | Output |');
+            lines.push('|---|---|---|---:|---|');
+            for (const check of verification.checks) {
+                lines.push(`| ${markdownCell(check.name)} | ${inlineCode(check.command)} | ${check.status} | ${(check.durationMs / 1000).toFixed(2)}s | ${markdownCell(check.output || '—')} |`);
+            }
+        }
+        lines.push('');
+    }
+    if (outcome.changes.length > 0) {
+        lines.push(dryRun ? '## Proposed transformations' : '## Applied transformations');
+        lines.push('');
+        lines.push('| Location | Rule | Before | After |');
+        lines.push('|---|---|---|---|');
+        for (const c of outcome.changes) {
+            lines.push(`| ${inlineCode(`${c.file}:${c.line}`)} | ${markdownCell(c.rule)} | ${markdownCell(c.before)} | ${markdownCell(c.after)} |`);
+        }
+        lines.push('');
+    }
+    if (outcome.proposedDiff.length > 0) {
+        lines.push(dryRun ? '## Proposed diff (not applied)' : '## Applied diff');
+        lines.push('');
+        for (const diff of outcome.proposedDiff) {
+            const longestBacktickRun = Math.max(0, ...[...diff.matchAll(/`+/g)].map(([run]) => run.length));
+            const fence = '`'.repeat(Math.max(4, longestBacktickRun + 1));
+            lines.push(`${fence}diff`);
+            lines.push(diff);
+            lines.push(fence);
+            lines.push('');
+        }
+    }
+    lines.push('## Next steps');
+    lines.push('');
+    if (dryRun) {
+        lines.push('1. Review the preview and the official migration guide before applying changes to a repository.');
+        lines.push('2. After review, use --write to verify and commit supported changes on a new Git branch. The command refuses manual findings and failed or missing checks.');
+        lines.push('3. Use the official migration guide and handle the items listed under "Needs your attention" manually.');
+    }
+    else {
+        lines.push('1. Review the applied changes (`git diff`).');
+        lines.push('2. Reinstall dependencies and run your type checker and tests.');
+        lines.push('3. Handle the items listed under "Needs your attention".');
+    }
+    lines.push('');
+    const raw = lines.join('\n');
+    const sanitized = maskSecrets(raw);
+    return sanitized === raw ? raw : `${sanitized}\n> Warning: possible credentials were detected in the report and redacted. Review the source before sharing this report.`;
+}
+/** Redact common provider credentials and private-key material from every report field. */
+export function maskSecrets(value) {
+    return value
+        .replace(/-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/g, '[PRIVATE KEY REDACTED]')
+        .replace(/((?:"|\b)private_key(?:"|\b)\s*:\s*)(?:"(?:\\.|[^"\\])*"|'[^']*'|[^,\r\n}]+)/gi, '$1"[REDACTED]"')
+        .replace(/\b(?:sk|rk|pk)\\?_(?:live|test)\\?_(?:[A-Za-z0-9-]|\\?_){8,}\b/gi, '[API key redacted]')
+        .replace(/\bwhsec\\?_(?:[A-Za-z0-9-]|\\?_){8,}\b/gi, '[webhook secret redacted]')
+        .replace(/\bAIza[0-9A-Za-z_-]{20,}\b/g, '[API key redacted]');
+}
+/** Keep the Markdown artifact intact while making prose readable in a terminal. */
+export function renderTerminalReport(markdown) {
+    let inFence = false;
+    const readable = markdown.split('\n').map((line) => {
+        if (/^`{4,}/.test(line)) {
+            inFence = !inFence;
+            return line;
+        }
+        if (inFence || !line.startsWith('- '))
+            return line;
+        return line
+            .replace(/&lt;/g, '<')
+            .replace(/&gt;/g, '>')
+            .replace(/&amp;/g, '&')
+            .replace(/\\([\\`*_{}\[\]()#+.!])/g, '$1');
+    }).join('\n');
+    return maskSecrets(readable);
+}
+function markdownCell(value) {
+    return escapeMarkdownText(value).replace(/\|/g, '\\|').replace(/\r?\n/g, '<br>');
+}
+function escapeMarkdownText(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+        .replace(/([\\`*_{}\[\]()#+.!])/g, '\\$1');
+}
+function inlineCode(value) {
+    const normalized = value.replace(/\r?\n/g, ' ').replace(/\|/g, '\\|');
+    const runs = [...normalized.matchAll(/`+/g)].map(([run]) => run.length);
+    const delimiter = '`'.repeat(Math.max(1, ...runs) + 1);
+    const needsPadding = normalized.startsWith('`') || normalized.endsWith('`') || /^\s|\s$/.test(normalized);
+    return `${delimiter}${needsPadding ? ' ' : ''}${normalized}${needsPadding ? ' ' : ''}${delimiter}`;
+}