upstreamfix 0.0.0-stage → 0.1.0

package/dist/core/runner.js

@@ -0,0 +1,826 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { execFile as execFileCallback } from 'node:child_process';
+import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { structuredPatch } from 'diff';
+import { Project } from 'ts-morph';
+const execFile = promisify(execFileCallback);
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs']);
+const IGNORED_DIRS = new Set(['node_modules', 'dist', 'coverage', '.next', '.git', '.venv', 'venv']);
+export function loadProject(cwd, packageName = 'firebase-admin') {
+    const project = new Project({
+        skipAddingFilesFromTsConfig: true,
+        compilerOptions: { allowJs: true },
+    });
+    for (const sourcePath of findSourceFiles(cwd, packageName))
+        project.addSourceFileAtPath(sourcePath);
+    return project;
+}
+function loadScopedProject(root, migration) {
+    const project = new Project({
+        skipAddingFilesFromTsConfig: true,
+        compilerOptions: { allowJs: true },
+    });
+    const manifests = findPackageManifests(root).map((file) => {
+        let parsed;
+        let invalid = false;
+        try {
+            parsed = JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+        }
+        catch {
+            invalid = true;
+        }
+        return { file, parsed, invalid };
+    });
+    const manual = [];
+    const manifestBySource = new Map();
+    for (const sourcePath of findSourceFiles(root, migration.packageName)) {
+        const containingManifests = manifests
+            .filter(({ file }) => {
+            const directory = path.dirname(file);
+            return sourcePath === directory || sourcePath.startsWith(directory + path.sep);
+        })
+            .sort((left, right) => right.file.length - left.file.length);
+        let declaration;
+        let invalidManifest;
+        for (const candidate of containingManifests) {
+            if (candidate.invalid) {
+                invalidManifest = { file: candidate.file, reason: 'is invalid JSON' };
+                break;
+            }
+            const manifest = candidate.parsed;
+            if (!manifest)
+                continue;
+            const ranges = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']
+                .map((section) => manifest[section]?.[migration.packageName])
+                .filter((value) => typeof value === 'string');
+            if (ranges.length > 0) {
+                if (new Set(ranges).size === 1)
+                    declaration = { file: candidate.file, range: ranges[0] };
+                else
+                    invalidManifest = { file: candidate.file, reason: 'declares conflicting dependency ranges' };
+                break;
+            }
+        }
+        if (invalidManifest) {
+            manual.push({
+                file: sourcePath,
+                line: 1,
+                reason: `The ${migration.packageName} version could not be confirmed because ${path.relative(root, invalidManifest.file)} ${invalidManifest.reason}.`,
+                snippet: readFileSync(sourcePath, 'utf8').split(/\r?\n/, 1)[0] ?? '',
+            });
+            continue;
+        }
+        if (!declaration) {
+            manual.push({
+                file: sourcePath,
+                line: 1,
+                reason: `No containing package.json declares ${migration.packageName}; this file was not transformed because its SDK version is unknown.`,
+                snippet: readFileSync(sourcePath, 'utf8').split(/\r?\n/, 1)[0] ?? '',
+            });
+            continue;
+        }
+        if (!isSourceMajorRange(declaration.range, migration.fromMajor)) {
+            manual.push({
+                file: sourcePath,
+                line: 1,
+                reason: `${migration.packageName} is declared as \`${declaration.range}\` in ${path.relative(root, declaration.file)}; this migration only analyzes major v${migration.fromMajor} ranges.`,
+                snippet: readFileSync(sourcePath, 'utf8').split(/\r?\n/, 1)[0] ?? '',
+            });
+            continue;
+        }
+        project.addSourceFileAtPath(sourcePath);
+        manifestBySource.set(sourcePath, declaration.file);
+    }
+    return { project, manual, manifestBySource };
+}
+function isSourceMajorRange(range, major) {
+    return new RegExp(`^\\s*[~^]?${major}(?:\\.(?:\\d+|x|\\*)){0,2}\\s*$`, 'i').test(range);
+}
+function isRegistryVersionSpec(spec) {
+    // A deliberately narrow subset: registry dist-tags or ordinary semver ranges.
+    // Anything that can name a path, URL, Git host, workspace, alias, or patch is manual.
+    if (/^(?:latest|next|beta|canary|rc)$/i.test(spec))
+        return true;
+    return /^(?:\^|~|>=?|<=?|=)?\s*v?\d+(?:\.\d+|\.x|\.\*){0,2}(?:\s*(?:\|\||-\s*v?\d+(?:\.\d+|\.x|\.\*){0,2}|\s+(?:<|>|<=|>=)\s*v?\d+(?:\.\d+|\.x|\.\*){0,2}))*$/.test(spec.trim());
+}
+export function hasUnsafeDependencySpecs(manifest) {
+    const dependencies = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']
+        .flatMap((section) => Object.values(manifest[section] ?? {}));
+    if (dependencies.some((value) => typeof value !== 'string' || !isRegistryVersionSpec(value)))
+        return true;
+    const candidate = manifest;
+    const nestedStrings = [];
+    const collect = (value) => {
+        if (typeof value === 'string')
+            nestedStrings.push(value);
+        else if (value && typeof value === 'object')
+            Object.values(value).forEach(collect);
+    };
+    collect(candidate.overrides);
+    collect(candidate.resolutions);
+    collect(candidate.pnpm?.overrides);
+    return nestedStrings.some((spec) => !isRegistryVersionSpec(spec));
+}
+export function lockfileCommandEnvironment(home) {
+    const allowed = new Set(['PATH', 'SYSTEMROOT', 'WINDIR', 'TMP', 'TEMP', 'TMPDIR', 'LANG', 'LC_ALL', 'TZ']);
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => allowed.has(key)));
+    return {
+        ...env,
+        HOME: home,
+        USERPROFILE: home,
+        NPM_CONFIG_USERCONFIG: path.join(home, 'upstreamfix-empty-user.npmrc'),
+        NPM_CONFIG_GLOBALCONFIG: path.join(home, 'upstreamfix-empty-global.npmrc'),
+        NPM_CONFIG_CACHE: path.join(home, 'npm-cache'),
+        NPM_CONFIG_AUDIT: 'false',
+        NPM_CONFIG_FUND: 'false',
+        NPM_CONFIG_IGNORE_SCRIPTS: 'true',
+        COREPACK_ENABLE_PROJECT_SPEC: '0',
+        GIT_CONFIG_NOSYSTEM: '1',
+        GIT_TERMINAL_PROMPT: '0',
+    };
+}
+function findSourceFiles(root, packageName) {
+    const found = [];
+    const visit = (directory) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const absolutePath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (!IGNORED_DIRS.has(entry.name))
+                    visit(absolutePath);
+                continue;
+            }
+            if (!entry.isFile() || entry.name.endsWith('.d.ts'))
+                continue;
+            if (!SOURCE_EXTENSIONS.has(path.extname(entry.name).toLowerCase()))
+                continue;
+            if (readFileSync(absolutePath, 'utf8').includes(packageName))
+                found.push(absolutePath);
+        }
+    };
+    visit(root);
+    return found;
+}
+export async function runMigration(migration, options) {
+    if (!options.dryRun) {
+        throw new Error('Direct writes through runMigration are unavailable; use --write for verified Git branch commits.');
+    }
+    if (options.nodeRuntime && migration.id !== 'firebase-admin@14') {
+        throw new Error('--node-runtime 22 is supported only for firebase-admin@14.');
+    }
+    const scoped = loadScopedProject(options.cwd, migration);
+    const project = scoped.project;
+    const originalSources = new Map(project.getSourceFiles().map((file) => [file.getFilePath(), file.getFullText()]));
+    const result = migration.transform(project);
+    result.manual.unshift(...scoped.manual);
+    const compatibilityNotes = migration.inspectManifest
+        ? await inspectManifests(migration, options.cwd)
+        : [];
+    if (!options.dryRun && result.manual.length > 0) {
+        throw new Error('This migration has manual review items; no files were written. Resolve them and preview again.');
+    }
+    const manifestsWithChangedCode = new Set(result.filesChanged.map((sourcePath) => scoped.manifestBySource.get(sourcePath)).filter((file) => Boolean(file)));
+    const manifest = result.manual.length === 0 && result.changes.length > 0
+        ? await migrateManifests(migration, options, manifestsWithChangedCode)
+        : {
+            notes: [result.manual.length > 0
+                    ? 'Dependency versions were left unchanged because this migration has items requiring manual review.'
+                    : 'Dependency versions were left unchanged because no supported code changes were found.'],
+            changes: [],
+            manual: [],
+        };
+    if (!options.dryRun && manifest.manual.length > 0) {
+        throw new Error('A dependency manifest needs manual review; no files were written. Resolve it and preview again.');
+    }
+    const sourceUpdates = new Map((result.fileUpdates ?? []).map((update) => [update.file, update.contents]));
+    const proposedFiles = [];
+    const proposedDiff = result.filesChanged.flatMap((filePath) => {
+        const before = originalSources.get(filePath);
+        const after = sourceUpdates.get(filePath);
+        if (before === undefined || after === undefined)
+            return [];
+        const relativePath = path.relative(options.cwd, filePath);
+        proposedFiles.push({ relativePath, before, after });
+        const diff = unifiedDiff(relativePath, before, after);
+        return diff ? [diff] : [];
+    });
+    for (const change of manifest.changes) {
+        proposedFiles.push({ relativePath: change.relativePath, before: change.before, after: change.after });
+        const diff = unifiedDiff(change.relativePath, change.before, change.after);
+        if (diff)
+            proposedDiff.push(diff);
+    }
+    return {
+        ...result,
+        filesChanged: [
+            ...result.filesChanged.map((file) => path.relative(options.cwd, file)),
+            ...manifest.changes.map((change) => change.relativePath),
+        ],
+        changes: result.changes.map((c) => ({ ...c, file: path.relative(options.cwd, c.file) })),
+        manual: [...result.manual, ...manifest.manual].map((m) => ({ ...m, file: path.relative(options.cwd, m.file) })),
+        manifestNotes: [...new Set([...compatibilityNotes, ...manifest.notes])],
+        proposedDiff,
+        proposedFiles,
+    };
+}
+async function inspectManifests(migration, cwd) {
+    const notes = [];
+    for (const manifestPath of findPackageManifests(cwd)) {
+        const raw = await readFile(manifestPath, 'utf8');
+        if (!raw.includes(JSON.stringify(migration.packageName)))
+            continue;
+        try {
+            const manifest = JSON.parse(raw.replace(/^\uFEFF/, ''));
+            notes.push(...(migration.inspectManifest?.(manifest) ?? []));
+        }
+        catch {
+            // Invalid manifests are already surfaced as manual review items for source files.
+        }
+    }
+    return [...new Set(notes)];
+}
+async function migrateManifests(migration, options, manifestsWithChangedCode) {
+    if (!migration.updateManifest)
+        return { notes: [], changes: [], manual: [] };
+    const notes = [];
+    const changes = [];
+    const manual = [];
+    for (const manifestPath of findPackageManifests(options.cwd)) {
+        const raw = await readFile(manifestPath, 'utf8');
+        if (!raw.includes(JSON.stringify(migration.packageName)))
+            continue;
+        const relativePath = path.relative(options.cwd, manifestPath);
+        if (!manifestsWithChangedCode.has(manifestPath)) {
+            notes.push(`\`${relativePath}\` was left unchanged because no analyzed source file owned by this package received a code transformation.`);
+            continue;
+        }
+        let manifest;
+        try {
+            manifest = JSON.parse(raw.replace(/^\uFEFF/, ''));
+        }
+        catch {
+            manual.push({
+                file: relativePath,
+                line: 1,
+                reason: 'This package.json is invalid JSON; its dependency version was left unchanged.',
+                snippet: raw.split(/\r?\n/, 1)[0] ?? '',
+            });
+            continue;
+        }
+        const before = structuredClone(manifest);
+        if (options.nodeRuntime === 22) {
+            if (manifest.engines !== undefined && (typeof manifest.engines !== 'object' || Array.isArray(manifest.engines) || manifest.engines === null)) {
+                manual.push({
+                    file: relativePath,
+                    line: 1,
+                    reason: 'engines must be an object in package.json before --node-runtime 22 can add a Node.js range.',
+                    snippet: 'engines',
+                });
+                continue;
+            }
+            const declared = manifest.engines?.node;
+            if (declared !== undefined && (typeof declared !== 'string' || !/^(?:>=\s*22(?:\.\d+){0,2}|(?:\^|~)\s*22(?:\.\d+){0,2}|22(?:\.\d+){0,2})$/.test(declared.trim()))) {
+                manual.push({
+                    file: relativePath,
+                    line: 1,
+                    reason: `engines.node is already declared as ${JSON.stringify(declared)}. Review and update it manually for Node.js 22 before migrating firebase-admin v14; --node-runtime never overrides a declared range.`,
+                    snippet: `engines.node: ${declared}`,
+                });
+                continue;
+            }
+            if (declared === undefined)
+                manifest.engines = { ...manifest.engines, node: '>=22' };
+        }
+        const fileNotes = migration.updateManifest(manifest);
+        if (options.nodeRuntime === 22 && before.engines?.node === undefined) {
+            fileNotes.unshift(`\`${relativePath}\`: added \`engines.node\` = \`>=22\` after explicit --node-runtime 22 confirmation.`);
+        }
+        if (JSON.stringify(manifest) === JSON.stringify(before)) {
+            notes.push(...fileNotes);
+            continue;
+        }
+        const versionUpdated = preserveManifestFormatting(raw, before, manifest, migration.packageName);
+        const updated = versionUpdated && options.nodeRuntime === 22 && before.engines?.node === undefined
+            ? addNodeEngineToManifest(versionUpdated)
+            : versionUpdated;
+        if (updated === undefined) {
+            notes.push(...fileNotes.filter((note) => !note.includes(' → ')));
+            manual.push({
+                file: relativePath,
+                line: 1,
+                reason: 'The dependency version could not be updated without rewriting or ambiguously editing package.json; update it manually.',
+                snippet: `${migration.packageName} dependency update withheld`,
+            });
+            continue;
+        }
+        const existingLocks = await findLockfiles(options.cwd, path.dirname(manifestPath));
+        let lockChange;
+        if (existingLocks.length > 0) {
+            const lockResult = existingLocks.length === 1 && path.basename(existingLocks[0]) === 'package-lock.json'
+                ? await regeneratePackageLock(manifestPath, path.resolve(options.cwd, existingLocks[0]), updated, options.cwd)
+                : existingLocks.length === 1 && path.basename(existingLocks[0]) === 'pnpm-lock.yaml'
+                    ? await regeneratePnpmLock(manifestPath, path.resolve(options.cwd, existingLocks[0]), updated, options.cwd)
+                    : existingLocks.length === 1 && path.basename(existingLocks[0]) === 'yarn.lock'
+                        ? await regenerateYarnLock(manifestPath, path.resolve(options.cwd, existingLocks[0]), updated, options.cwd)
+                        : { reason: `This package uses unsupported lockfile(s): ${existingLocks.join(', ')}.` };
+            if (!lockResult.contents) {
+                notes.push(...fileNotes.filter((note) => !note.includes(' → ')));
+                manual.push({
+                    file: relativePath,
+                    line: 1,
+                    reason: `${lockResult.reason} The dependency and lockfile were left unchanged.`,
+                    snippet: `${migration.packageName} dependency update withheld`,
+                });
+                continue;
+            }
+            const lockPath = path.resolve(options.cwd, existingLocks[0]);
+            lockChange = {
+                absolutePath: lockPath,
+                relativePath: path.relative(options.cwd, lockPath),
+                before: lockResult.before ?? '',
+                after: lockResult.contents,
+            };
+        }
+        notes.push(...fileNotes);
+        if (updated !== raw)
+            changes.push({ absolutePath: manifestPath, relativePath, before: raw, after: updated });
+        if (lockChange && lockChange.after !== lockChange.before) {
+            changes.push(lockChange);
+            const managerName = path.basename(lockChange.relativePath) === 'pnpm-lock.yaml'
+                ? 'pnpm'
+                : path.basename(lockChange.relativePath) === 'yarn.lock'
+                    ? 'Yarn Classic'
+                    : 'npm';
+            notes.push(`\`${lockChange.relativePath}\` was regenerated by ${managerName} in a temporary directory; preview requires registry access and install scripts were disabled.`);
+        }
+    }
+    if (manual.length > 0)
+        changes.length = 0;
+    if (changes.length === 0 && notes.length === 0 && manual.length === 0) {
+        notes.push(`No package.json containing ${migration.packageName} was found.`);
+    }
+    return { notes, changes, manual };
+}
+async function regeneratePackageLock(manifestPath, lockPath, updatedManifest, projectRoot) {
+    const directory = path.dirname(manifestPath);
+    if (directory !== path.dirname(lockPath)) {
+        return { reason: 'The package-lock.json is not beside the package.json; workspace lockfile updates are not supported yet.' };
+    }
+    if (directory !== projectRoot) {
+        return { reason: 'Nested package manifests require workspace-aware lockfile regeneration, which is not supported yet.' };
+    }
+    let manifest;
+    let before;
+    let lock;
+    try {
+        manifest = JSON.parse(updatedManifest.replace(/^\uFEFF/, ''));
+        before = await readFile(lockPath, 'utf8');
+        lock = JSON.parse(before);
+    }
+    catch {
+        return { reason: 'The package.json or package-lock.json could not be parsed for a safe lockfile update.' };
+    }
+    if (lock.lockfileVersion !== 3) {
+        return { reason: 'Only npm package-lock.json version 3 can currently be regenerated automatically.' };
+    }
+    if ('workspaces' in manifest) {
+        return { reason: 'npm workspaces are not supported by the isolated lockfile updater yet.' };
+    }
+    if (hasUnsafeDependencySpecs(manifest)) {
+        return { reason: 'Only ordinary npm registry versions and approved dist-tags are supported; Git, URL, local, aliased, override, resolution, and non-registry specs require manual lockfile updates.' };
+    }
+    let configDirectory = directory;
+    while (configDirectory === projectRoot || configDirectory.startsWith(projectRoot + path.sep)) {
+        if (await exists(path.join(configDirectory, '.npmrc'))) {
+            return { reason: 'A project .npmrc may contain registry or resolution settings that the isolated updater cannot safely reproduce.' };
+        }
+        if (configDirectory === projectRoot)
+            break;
+        configDirectory = path.dirname(configDirectory);
+    }
+    let temporaryDirectory;
+    try {
+        temporaryDirectory = await mkdtemp(path.join(tmpdir(), 'upstreamfix-npm-lock-'));
+        await writeFile(path.join(temporaryDirectory, 'package.json'), updatedManifest, 'utf8');
+        await writeFile(path.join(temporaryDirectory, 'package-lock.json'), before, 'utf8');
+        const args = ['install', '--package-lock-only', '--lockfile-version=3', '--ignore-scripts', '--no-audit', '--no-fund'];
+        await execFile('npm', args, { cwd: temporaryDirectory, env: lockfileCommandEnvironment(temporaryDirectory), timeout: 120_000, maxBuffer: 4 * 1024 * 1024 });
+        const contents = await readFile(path.join(temporaryDirectory, 'package-lock.json'), 'utf8');
+        return { before, contents };
+    }
+    catch {
+        return { reason: 'npm could not regenerate package-lock.json in an isolated temporary directory.' };
+    }
+    finally {
+        if (temporaryDirectory)
+            await rm(temporaryDirectory, { recursive: true, force: true });
+    }
+}
+async function regeneratePnpmLock(manifestPath, lockPath, updatedManifest, projectRoot) {
+    const directory = path.dirname(manifestPath);
+    if (directory !== path.dirname(lockPath)) {
+        return { reason: 'The pnpm-lock.yaml is not beside the package.json; workspace lockfile updates are not supported yet.' };
+    }
+    if (directory !== projectRoot) {
+        return { reason: 'Nested package manifests require workspace-aware lockfile regeneration, which is not supported yet.' };
+    }
+    let manifest;
+    let before;
+    try {
+        manifest = JSON.parse(updatedManifest.replace(/^\uFEFF/, ''));
+        before = await readFile(lockPath, 'utf8');
+    }
+    catch {
+        return { reason: 'The package.json or pnpm-lock.yaml could not be read for a safe lockfile update.' };
+    }
+    const lockVersion = /^lockfileVersion:\s*["']?([\d]+(?:\.[\d]+)?)/m.exec(before)?.[1];
+    if (!lockVersion)
+        return { reason: 'The pnpm lockfile version could not be identified safely.' };
+    if ('workspaces' in manifest)
+        return { reason: 'pnpm workspaces are not supported by the isolated lockfile updater yet.' };
+    if (hasUnsafeDependencySpecs(manifest)) {
+        return { reason: 'Only ordinary npm registry versions and approved dist-tags are supported; Git, URL, local, aliased, override, resolution, and non-registry specs require manual lockfile updates.' };
+    }
+    let configDirectory = directory;
+    while (configDirectory === projectRoot || configDirectory.startsWith(projectRoot + path.sep)) {
+        for (const configName of ['.npmrc', '.pnpmfile.cjs', '.pnpmfile.mjs', 'pnpm-workspace.yaml']) {
+            if (await exists(path.join(configDirectory, configName))) {
+                return { reason: `A project ${configName} may contain registry, resolution, hook, or workspace settings that the isolated updater cannot safely reproduce.` };
+            }
+        }
+        if (configDirectory === projectRoot)
+            break;
+        configDirectory = path.dirname(configDirectory);
+    }
+    const declaredManager = manifest.packageManager;
+    if (declaredManager !== undefined && (typeof declaredManager !== 'string' || !/^pnpm@\d+\.\d+\.\d+(?:[-+].*)?$/.test(declaredManager))) {
+        return { reason: 'The packageManager field does not pin an exact pnpm version, so lockfile regeneration cannot be version-checked safely.' };
+    }
+    let temporaryDirectory;
+    try {
+        const probeHome = await mkdtemp(path.join(tmpdir(), 'upstreamfix-pnpm-home-'));
+        let versionOutput;
+        try {
+            ({ stdout: versionOutput } = await execFile('pnpm', ['--version'], {
+                cwd: tmpdir(),
+                env: lockfileCommandEnvironment(probeHome),
+                timeout: 15_000,
+                maxBuffer: 1024 * 1024,
+            }));
+        }
+        finally {
+            await rm(probeHome, { recursive: true, force: true });
+        }
+        const installedVersion = versionOutput.trim();
+        if (!/^\d+\.\d+\.\d+(?:[-+].*)?$/.test(installedVersion)) {
+            return { reason: 'The installed pnpm version could not be identified safely.' };
+        }
+        if (typeof declaredManager === 'string') {
+            const pinnedVersion = /^pnpm@([^+]+)(?:\+.*)?$/.exec(declaredManager)?.[1];
+            if (pinnedVersion !== installedVersion) {
+                return { reason: `This project pins ${declaredManager}, but the installed package manager is pnpm@${installedVersion}; lockfile regeneration was withheld.` };
+            }
+        }
+        temporaryDirectory = await mkdtemp(path.join(tmpdir(), 'upstreamfix-pnpm-lock-'));
+        // pnpm reads packageManager and may download a different CLI automatically. The exact
+        // version was checked above, so omit this metadata from the isolated temporary manifest.
+        delete manifest.packageManager;
+        await writeFile(path.join(temporaryDirectory, 'package.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+        await writeFile(path.join(temporaryDirectory, 'pnpm-lock.yaml'), before, 'utf8');
+        await execFile('pnpm', ['install', '--lockfile-only', '--ignore-scripts', '--no-frozen-lockfile'], {
+            cwd: temporaryDirectory,
+            env: lockfileCommandEnvironment(temporaryDirectory),
+            timeout: 120_000,
+            maxBuffer: 4 * 1024 * 1024,
+        });
+        const contents = await readFile(path.join(temporaryDirectory, 'pnpm-lock.yaml'), 'utf8');
+        const generatedVersion = /^lockfileVersion:\s*["']?([\d]+(?:\.[\d]+)?)/m.exec(contents)?.[1];
+        if (generatedVersion !== lockVersion) {
+            return { reason: `The installed pnpm would change the lockfile format from ${lockVersion} to ${generatedVersion ?? 'unknown'}; update it manually with the project's pinned package manager.` };
+        }
+        return { before, contents };
+    }
+    catch {
+        return { reason: 'pnpm could not regenerate pnpm-lock.yaml in an isolated temporary directory; ensure the pinned pnpm version is installed and registry access is available.' };
+    }
+    finally {
+        if (temporaryDirectory)
+            await rm(temporaryDirectory, { recursive: true, force: true });
+    }
+}
+async function regenerateYarnLock(manifestPath, lockPath, updatedManifest, projectRoot) {
+    const directory = path.dirname(manifestPath);
+    if (directory !== path.dirname(lockPath)) {
+        return { reason: 'The yarn.lock is not beside the package.json; workspace lockfile updates are not supported yet.' };
+    }
+    if (directory !== projectRoot) {
+        return { reason: 'Nested package manifests require workspace-aware lockfile regeneration, which is not supported yet.' };
+    }
+    let manifest;
+    let before;
+    try {
+        manifest = JSON.parse(updatedManifest.replace(/^\uFEFF/, ''));
+        before = await readFile(lockPath, 'utf8');
+    }
+    catch {
+        return { reason: 'The package.json or yarn.lock could not be read for a safe lockfile update.' };
+    }
+    if ('workspaces' in manifest)
+        return { reason: 'Yarn workspaces are not supported by the isolated lockfile updater yet.' };
+    if (!before.startsWith('# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.')) {
+        return { reason: 'Only Yarn Classic lockfile format can currently be regenerated automatically.' };
+    }
+    if (hasUnsafeDependencySpecs(manifest)) {
+        return { reason: 'Only ordinary npm registry versions and approved dist-tags are supported; Git, URL, local, aliased, override, resolution, and non-registry specs require manual lockfile updates.' };
+    }
+    let configDirectory = directory;
+    while (configDirectory === projectRoot || configDirectory.startsWith(projectRoot + path.sep)) {
+        for (const configName of ['.npmrc', '.yarnrc', '.yarnrc.yml', 'yarn.config.cjs']) {
+            if (await exists(path.join(configDirectory, configName))) {
+                return { reason: `A project ${configName} may contain registry, resolution, hook, or workspace settings that the isolated updater cannot safely reproduce.` };
+            }
+        }
+        if (await exists(path.join(configDirectory, '.yarn'))) {
+            return { reason: 'A project .yarn directory may contain Yarn Berry releases, plugins, patches, or configuration that cannot be safely reproduced in isolation.' };
+        }
+        if (configDirectory === projectRoot)
+            break;
+        configDirectory = path.dirname(configDirectory);
+    }
+    const declaredManager = manifest.packageManager;
+    if (declaredManager !== undefined && (typeof declaredManager !== 'string' || !/^yarn@1\.\d+\.\d+(?:[-+].*)?$/.test(declaredManager))) {
+        return { reason: 'Only an exact Yarn Classic 1.x packageManager pin is supported for automatic lockfile regeneration.' };
+    }
+    let temporaryDirectory;
+    try {
+        const probeHome = await mkdtemp(path.join(tmpdir(), 'upstreamfix-yarn-home-'));
+        let versionOutput;
+        try {
+            ({ stdout: versionOutput } = await execFile('yarn', ['--version'], {
+                cwd: tmpdir(),
+                env: lockfileCommandEnvironment(probeHome),
+                timeout: 15_000,
+                maxBuffer: 1024 * 1024,
+            }));
+        }
+        finally {
+            await rm(probeHome, { recursive: true, force: true });
+        }
+        const installedVersion = versionOutput.trim();
+        if (!/^1\.\d+\.\d+$/.test(installedVersion)) {
+            return { reason: `Yarn ${installedVersion || '(unknown version)'} is not Yarn Classic 1.x; this version's lockfile updater is not supported yet.` };
+        }
+        if (typeof declaredManager === 'string') {
+            const pinnedVersion = /^yarn@([^+]+)(?:\+.*)?$/.exec(declaredManager)?.[1];
+            if (pinnedVersion !== installedVersion) {
+                return { reason: `This project pins ${declaredManager}, but the installed package manager is yarn@${installedVersion}; lockfile regeneration was withheld.` };
+            }
+        }
+        temporaryDirectory = await mkdtemp(path.join(tmpdir(), 'upstreamfix-yarn-lock-'));
+        delete manifest.packageManager;
+        await writeFile(path.join(temporaryDirectory, 'package.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+        await writeFile(path.join(temporaryDirectory, 'yarn.lock'), before, 'utf8');
+        await execFile('yarn', ['install', '--ignore-scripts', '--non-interactive', '--no-progress'], {
+            cwd: temporaryDirectory,
+            env: lockfileCommandEnvironment(temporaryDirectory),
+            timeout: 120_000,
+            maxBuffer: 4 * 1024 * 1024,
+        });
+        const contents = await readFile(path.join(temporaryDirectory, 'yarn.lock'), 'utf8');
+        if (!contents.startsWith('# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.')) {
+            return { reason: 'Yarn generated an unrecognized lockfile format; the lockfile update was withheld.' };
+        }
+        return { before, contents };
+    }
+    catch {
+        return { reason: 'Yarn Classic could not regenerate yarn.lock in an isolated temporary directory; ensure the pinned Yarn 1.x version is installed and registry access is available.' };
+    }
+    finally {
+        if (temporaryDirectory)
+            await rm(temporaryDirectory, { recursive: true, force: true });
+    }
+}
+async function exists(file) {
+    try {
+        await stat(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function findLockfiles(root, packageDirectory) {
+    const names = ['package-lock.json', 'npm-shrinkwrap.json', 'pnpm-lock.yaml', 'yarn.lock'];
+    const found = [];
+    let directory = packageDirectory;
+    while (directory === root || directory.startsWith(root + path.sep)) {
+        for (const name of names) {
+            try {
+                await stat(path.join(directory, name));
+                found.push(path.relative(root, path.join(directory, name)));
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        if (directory === root)
+            break;
+        directory = path.dirname(directory);
+    }
+    return found;
+}
+function findPackageManifests(root) {
+    const found = [];
+    const visit = (directory) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const absolutePath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (!IGNORED_DIRS.has(entry.name))
+                    visit(absolutePath);
+            }
+            else if (entry.isFile() && entry.name === 'package.json') {
+                found.push(absolutePath);
+            }
+        }
+    };
+    visit(root);
+    return found;
+}
+function addNodeEngineToManifest(raw) {
+    const rootStart = raw.charCodeAt(0) === 0xfeff ? 1 : 0;
+    if (raw[rootStart] !== '{')
+        return undefined;
+    const engineMember = findJsonObjectMember(raw, rootStart, 'engines');
+    if (!engineMember && Object.hasOwn(JSON.parse(raw.replace(/^\uFEFF/, '')), 'engines'))
+        return undefined;
+    const objectStart = engineMember?.valueStart ?? rootStart;
+    if (raw[objectStart] !== '{')
+        return undefined;
+    const objectEnd = jsonValueEnd(raw, objectStart);
+    if (objectEnd < 0)
+        return undefined;
+    const close = objectEnd - 1;
+    const whitespace = raw.slice(objectStart + 1, close).match(/\s*$/)?.[0] ?? '';
+    const insertAt = close - whitespace.length;
+    const hasMembers = raw.slice(objectStart + 1, insertAt).trim().length > 0;
+    const lineEnding = raw.includes('\r\n') ? '\r\n' : '\n';
+    const indent = raw.match(/(?:\r?\n)([ \t]+)"[^"\r\n]+"\s*:/)?.[1] ?? '  ';
+    const childIndent = engineMember ? indent + indent : indent;
+    const addition = raw.includes('\n')
+        ? `${hasMembers ? ',' : ''}${lineEnding}${childIndent}${engineMember ? '"node": ">=22"' : '"engines": { "node": ">=22" }'}`
+        : `${hasMembers ? ', ' : ''}${engineMember ? '"node": ">=22"' : '"engines": { "node": ">=22" }'}`;
+    const updated = raw.slice(0, insertAt) + addition + raw.slice(insertAt);
+    try {
+        const parsed = JSON.parse(updated.replace(/^\uFEFF/, ''));
+        return parsed.engines?.node === '>=22' ? updated : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function preserveManifestFormatting(raw, before, after, packageName) {
+    let updated = raw;
+    for (const section of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+        const oldValue = before[section]?.[packageName];
+        const newValue = after[section]?.[packageName];
+        if (typeof oldValue !== 'string' || typeof newValue !== 'string' || oldValue === newValue)
+            continue;
+        const rootStart = updated.charCodeAt(0) === 0xfeff ? 1 : 0;
+        const sectionMember = findJsonObjectMember(updated, rootStart, section);
+        if (!sectionMember || updated[sectionMember.valueStart] !== '{')
+            return undefined;
+        const dependencyMember = findJsonObjectMember(updated, sectionMember.valueStart, packageName);
+        if (!dependencyMember || updated[dependencyMember.valueStart] !== '"')
+            return undefined;
+        let decoded;
+        try {
+            decoded = JSON.parse(updated.slice(dependencyMember.valueStart, dependencyMember.valueEnd));
+        }
+        catch {
+            return undefined;
+        }
+        if (decoded !== oldValue)
+            return undefined;
+        updated =
+            updated.slice(0, dependencyMember.valueStart) +
+                JSON.stringify(newValue) +
+                updated.slice(dependencyMember.valueEnd);
+    }
+    return updated;
+}
+function findJsonObjectMember(text, objectStart, targetKey) {
+    if (text[objectStart] !== '{')
+        return undefined;
+    let cursor = objectStart + 1;
+    let found;
+    while (cursor < text.length) {
+        cursor = skipWhitespace(text, cursor);
+        if (text[cursor] === '}')
+            return found;
+        if (text[cursor] !== '"')
+            return undefined;
+        const keyEnd = jsonStringEnd(text, cursor);
+        if (keyEnd < 0)
+            return undefined;
+        let key;
+        try {
+            key = JSON.parse(text.slice(cursor, keyEnd));
+        }
+        catch {
+            return undefined;
+        }
+        cursor = skipWhitespace(text, keyEnd);
+        if (text[cursor] !== ':')
+            return undefined;
+        const valueStart = skipWhitespace(text, cursor + 1);
+        const valueEnd = jsonValueEnd(text, valueStart);
+        if (valueEnd < 0)
+            return undefined;
+        if (key === targetKey) {
+            if (found)
+                return undefined;
+            found = { valueStart, valueEnd };
+        }
+        cursor = skipWhitespace(text, valueEnd);
+        if (text[cursor] === ',')
+            cursor++;
+        else if (text[cursor] !== '}')
+            return undefined;
+    }
+    return undefined;
+}
+function skipWhitespace(text, start) {
+    let cursor = start;
+    while (/\s/.test(text[cursor] ?? ''))
+        cursor++;
+    return cursor;
+}
+function jsonStringEnd(text, start) {
+    let escaped = false;
+    for (let cursor = start + 1; cursor < text.length; cursor++) {
+        const char = text[cursor];
+        if (escaped)
+            escaped = false;
+        else if (char === '\\')
+            escaped = true;
+        else if (char === '"')
+            return cursor + 1;
+    }
+    return -1;
+}
+function jsonValueEnd(text, start) {
+    if (text[start] === '"')
+        return jsonStringEnd(text, start);
+    if (text[start] === '{' || text[start] === '[') {
+        const stack = [text[start] === '{' ? '}' : ']'];
+        let inString = false;
+        let escaped = false;
+        for (let cursor = start + 1; cursor < text.length; cursor++) {
+            const char = text[cursor];
+            if (inString) {
+                if (escaped)
+                    escaped = false;
+                else if (char === '\\')
+                    escaped = true;
+                else if (char === '"')
+                    inString = false;
+                continue;
+            }
+            if (char === '"')
+                inString = true;
+            else if (char === '{')
+                stack.push('}');
+            else if (char === '[')
+                stack.push(']');
+            else if (char === '}' || char === ']') {
+                if (stack.pop() !== char)
+                    return -1;
+                if (stack.length === 0)
+                    return cursor + 1;
+            }
+        }
+        return -1;
+    }
+    let cursor = start;
+    while (cursor < text.length && !',}]'.includes(text[cursor]))
+        cursor++;
+    while (cursor > start && /\s/.test(text[cursor - 1]))
+        cursor--;
+    return cursor > start ? cursor : -1;
+}
+export function unifiedDiff(file, before, after) {
+    if (before === after)
+        return '';
+    const patch = structuredPatch(`a/${file}`, `b/${file}`, before.replace(/\r\n/g, '\n'), after.replace(/\r\n/g, '\n'), '', '', { context: 3 });
+    const output = [`--- a/${file}`, `+++ b/${file}`];
+    for (const hunk of patch.hunks) {
+        output.push(`@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`);
+        output.push(...hunk.lines);
+    }
+    return output.join('\n');
+}