@titannio/webtoolkit-cli 1.3.0

package/dist/upgrade.js

@@ -0,0 +1,674 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { prepareCorepackPnpm } from './environment.js';
+import { buildFreshPackageManagerCommand, buildPackageManagerCommand, formatCommand, runCommandBuffered, runCommandInherited } from './process.js';
+const colors = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+    red: '\x1b[31m',
+    gray: '\x1b[90m',
+};
+const manifestVersionFields = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+const skippedReasonOrder = ['cooldown', 'major', 'protected-singleton'];
+const skippedReasonLabels = {
+    cooldown: 'Cooldown',
+    major: 'Major',
+    'protected-singleton': 'Protected singleton',
+};
+const skippedReasonPriority = {
+    cooldown: 0,
+    major: 1,
+    'protected-singleton': 2,
+};
+function colorize(value, color) {
+    return `${color}${value}${colors.reset}`;
+}
+function uniqueSorted(values) {
+    return Array.from(new Set(values)).sort((left, right) => left.localeCompare(right));
+}
+function normalizeVersionSpec(version) {
+    return version.replace(/^[~^]/u, '');
+}
+function validatePinnedPnpmVersion(version) {
+    if (!version || version.includes(' ') || version === 'latest' || version === '11') {
+        throw new Error(`packageManager must pin an exact pnpm version, but found ${JSON.stringify(`pnpm@${version}`)}.`);
+    }
+}
+function parsePnpmPackageManagerVersion(packageManager) {
+    if (typeof packageManager !== 'string' || !packageManager.startsWith('pnpm@'))
+        return null;
+    const version = packageManager.slice('pnpm@'.length).trim();
+    validatePinnedPnpmVersion(version);
+    return version;
+}
+function getVersionMajor(versionSpec) {
+    const matched = normalizeVersionSpec(versionSpec).match(/^(\d+)/u);
+    return matched ? Number.parseInt(matched[1], 10) : null;
+}
+function shouldIncludeOutdatedTarget(currentVersion, latestVersion, target) {
+    if (!currentVersion || !latestVersion || currentVersion === latestVersion)
+        return false;
+    if (target === 'latest')
+        return true;
+    const currentMajor = getVersionMajor(currentVersion);
+    const latestMajor = getVersionMajor(latestVersion);
+    return currentMajor !== null && latestMajor !== null && currentMajor === latestMajor;
+}
+function applyManifestVersionStyle(currentVersion, targetVersion) {
+    if (currentVersion?.startsWith('^'))
+        return `^${normalizeVersionSpec(targetVersion)}`;
+    if (currentVersion?.startsWith('~'))
+        return `~${normalizeVersionSpec(targetVersion)}`;
+    return normalizeVersionSpec(targetVersion);
+}
+function unquoteYamlScalar(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith("'") && trimmed.endsWith("'")) || (trimmed.startsWith('"') && trimmed.endsWith('"'))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function sortUpdatesByFile(updatesByFile) {
+    return Object.fromEntries(Object.entries(updatesByFile)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([filePath, updates]) => [
+        filePath,
+        Object.fromEntries(Object.entries(updates).sort(([left], [right]) => left.localeCompare(right))),
+    ]));
+}
+function mergeWorkspaceUpdates(...sources) {
+    const merged = {};
+    for (const source of sources) {
+        for (const [filePath, updates] of Object.entries(source)) {
+            merged[filePath] = { ...(merged[filePath] ?? {}), ...updates };
+        }
+    }
+    return sortUpdatesByFile(merged);
+}
+function normalizeNcuJson(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return {};
+    const parsed = JSON.parse(trimmed);
+    const entries = Object.entries(parsed);
+    const looksLikeWorkspaceMap = entries.every(([, value]) => value !== null && typeof value === 'object' && !Array.isArray(value));
+    if (!looksLikeWorkspaceMap) {
+        return {
+            'package.json': Object.fromEntries(entries.filter(([, value]) => typeof value === 'string')),
+        };
+    }
+    return sortUpdatesByFile(Object.fromEntries(entries.map(([filePath, value]) => [
+        filePath,
+        Object.fromEntries(Object.entries(value).filter(([, version]) => typeof version === 'string')),
+    ])));
+}
+function parseJsonObjectFromCommandOutput(raw) {
+    const start = raw.indexOf('{');
+    if (start === -1)
+        throw new Error('No JSON object found.');
+    let depth = 0;
+    let inString = false;
+    let escaping = false;
+    for (let index = start; index < raw.length; index += 1) {
+        const character = raw[index];
+        if (escaping) {
+            escaping = false;
+            continue;
+        }
+        if (character === '\\') {
+            escaping = inString;
+            continue;
+        }
+        if (character === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString)
+            continue;
+        if (character === '{')
+            depth += 1;
+        if (character === '}') {
+            depth -= 1;
+            if (depth === 0) {
+                return JSON.parse(raw.slice(start, index + 1));
+            }
+        }
+    }
+    throw new Error('Unterminated JSON object.');
+}
+function toWorkspaceManifestPath(location, workspaceRoot) {
+    const relativeLocation = path.relative(workspaceRoot, location);
+    if (relativeLocation.startsWith('..') || path.isAbsolute(relativeLocation))
+        return null;
+    const normalizedLocation = relativeLocation.replace(/\\/gu, '/');
+    return normalizedLocation ? `${normalizedLocation}/package.json` : 'package.json';
+}
+function normalizePnpmOutdatedJson(raw, workspaceRoot, target) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return {};
+    const parsed = JSON.parse(trimmed);
+    const updatesByFile = {};
+    for (const [packageName, packageInfo] of Object.entries(parsed)) {
+        const currentVersion = typeof packageInfo.current === 'string' ? packageInfo.current : null;
+        const latestVersion = typeof packageInfo.latest === 'string' ? packageInfo.latest : null;
+        if (!currentVersion || !latestVersion || !shouldIncludeOutdatedTarget(currentVersion, latestVersion, target))
+            continue;
+        const dependentPackages = Array.isArray(packageInfo.dependentPackages) ? packageInfo.dependentPackages : [];
+        for (const dependentPackage of dependentPackages) {
+            const location = typeof dependentPackage === 'object' && dependentPackage !== null && 'location' in dependentPackage
+                ? dependentPackage.location
+                : null;
+            if (typeof location !== 'string')
+                continue;
+            const manifestPath = toWorkspaceManifestPath(location, workspaceRoot);
+            if (!manifestPath)
+                continue;
+            updatesByFile[manifestPath] = {
+                ...(updatesByFile[manifestPath] ?? {}),
+                [packageName]: latestVersion,
+            };
+        }
+    }
+    return sortUpdatesByFile(updatesByFile);
+}
+async function readManifestVersions(filePath) {
+    const manifest = JSON.parse(await readFile(filePath, 'utf8'));
+    const versions = {};
+    for (const field of manifestVersionFields) {
+        const section = manifest[field];
+        if (!section || typeof section !== 'object' || Array.isArray(section))
+            continue;
+        for (const [packageName, version] of Object.entries(section)) {
+            if (typeof version === 'string')
+                versions[packageName] = version;
+        }
+    }
+    return versions;
+}
+async function readRootPnpmPackageManagerVersion(rootDir) {
+    const manifest = JSON.parse(await readFile(path.join(rootDir, 'package.json'), 'utf8'));
+    return parsePnpmPackageManagerVersion(manifest.packageManager);
+}
+async function getManifestVersionsByFile(updatesByFile, rootDir) {
+    const files = Object.keys(updatesByFile);
+    const entries = await Promise.all(files.map(async (filePath) => [filePath, await readManifestVersions(path.join(rootDir, filePath))]));
+    return Object.fromEntries(entries);
+}
+function buildUpgradeEntries(updatesByFile, resolveCurrentVersion) {
+    const entries = [];
+    for (const [filePath, updates] of Object.entries(sortUpdatesByFile(updatesByFile))) {
+        for (const [packageName, targetVersion] of Object.entries(updates)) {
+            entries.push({
+                filePath,
+                packageName,
+                currentVersion: resolveCurrentVersion(filePath, packageName, targetVersion),
+                targetVersion,
+            });
+        }
+    }
+    return entries;
+}
+function buildSkippedUpgradeEntries(updatesByFile, reason, resolveCurrentVersion) {
+    return buildUpgradeEntries(updatesByFile, resolveCurrentVersion).map((entry) => ({
+        ...entry,
+        reason,
+    }));
+}
+function getUpgradeEntryKey(filePath, packageName) {
+    return `${filePath}::${packageName}`;
+}
+function filterWorkspaceUpdatesByPackageNames(updatesByFile, packageNames) {
+    return sortUpdatesByFile(Object.fromEntries(Object.entries(updatesByFile)
+        .map(([filePath, updates]) => [
+        filePath,
+        Object.fromEntries(Object.entries(updates).filter(([packageName]) => packageNames.has(packageName))),
+    ])
+        .filter(([, updates]) => Object.keys(updates).length > 0)));
+}
+function subtractWorkspaceUpdates(minuend, subtrahend) {
+    return sortUpdatesByFile(Object.fromEntries(Object.entries(minuend)
+        .map(([filePath, updates]) => [
+        filePath,
+        Object.fromEntries(Object.entries(updates).filter(([packageName]) => !(packageName in (subtrahend[filePath] ?? {})))),
+    ])
+        .filter(([, updates]) => Object.keys(updates).length > 0)));
+}
+function addSkippedEntries(target, entries) {
+    for (const entry of entries) {
+        const key = getUpgradeEntryKey(entry.filePath, entry.packageName);
+        const existing = target.get(key);
+        if (!existing || skippedReasonPriority[entry.reason] < skippedReasonPriority[existing.reason]) {
+            target.set(key, entry);
+        }
+    }
+}
+function readProtectedOverrides(rootDir, relativeFilePath) {
+    const filePath = path.join(rootDir, relativeFilePath);
+    if (!existsSync(filePath))
+        return {};
+    const lines = readFileSync(filePath, 'utf8').split(/\r?\n/u);
+    const overrides = {};
+    let insideOverrides = false;
+    for (const line of lines) {
+        if (!insideOverrides) {
+            if (/^overrides:\s*$/u.test(line))
+                insideOverrides = true;
+            continue;
+        }
+        if (/^\S/u.test(line))
+            break;
+        const match = line.match(/^(\s{2,})([^:#][^:]*):\s*(.*?)\s*$/u);
+        if (!match)
+            continue;
+        overrides[unquoteYamlScalar(match[2])] = unquoteYamlScalar(match[3]);
+    }
+    return overrides;
+}
+async function updateProtectedOverrides(rootDir, relativeFilePath, overrideUpdates) {
+    if (Object.keys(overrideUpdates).length === 0)
+        return;
+    const filePath = path.join(rootDir, relativeFilePath);
+    const lines = (await readFile(filePath, 'utf8')).split(/\r?\n/u);
+    const remainingPackages = new Set(Object.keys(overrideUpdates));
+    let insideOverrides = false;
+    let modified = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (!insideOverrides) {
+            if (/^overrides:\s*$/u.test(line))
+                insideOverrides = true;
+            continue;
+        }
+        if (/^\S/u.test(line))
+            break;
+        const match = line.match(/^(\s{2,})([^:#][^:]*):\s*(.*?)\s*$/u);
+        if (!match)
+            continue;
+        const packageName = unquoteYamlScalar(match[2]);
+        const targetVersion = overrideUpdates[packageName];
+        if (!targetVersion)
+            continue;
+        lines[index] = `${match[1]}${match[2]}: ${targetVersion}`;
+        remainingPackages.delete(packageName);
+        modified = true;
+    }
+    if (remainingPackages.size > 0) {
+        throw new Error(`Unable to update protected override(s): ${Array.from(remainingPackages).join(', ')}`);
+    }
+    if (modified)
+        await writeFile(filePath, lines.join('\n'));
+}
+function getProtectedDependencyNames(runtime) {
+    return Object.keys(readProtectedOverrides(runtime.cwd, runtime.config.upgrade?.protectedOverridesFile ?? 'pnpm-workspace.yaml')).sort((left, right) => left.localeCompare(right));
+}
+export function mergeRejectLists(baseRejectList, protectedDependencyNames) {
+    return uniqueSorted([...baseRejectList, ...protectedDependencyNames]);
+}
+async function runBufferedPm(runtime, args, rejectOnNonZero = true) {
+    const command = buildPackageManagerCommand(runtime.config.packageManager, args);
+    const result = await runCommandBuffered(command, runtime.cwd);
+    if (rejectOnNonZero && result.code !== 0) {
+        throw new Error(`Command failed: ${formatCommand(command.command, command.args ?? [])}\n${result.output}`);
+    }
+    return result;
+}
+function runInheritedPm(runtime, args, buildCommand = buildPackageManagerCommand) {
+    const command = buildCommand(runtime.config.packageManager, args);
+    const code = runCommandInherited(command, runtime.cwd);
+    if (code !== 0) {
+        throw new Error(`Command failed: ${formatCommand(command.command, command.args ?? [])}`);
+    }
+}
+async function collectNcuUpdates(runtime, target, rejectList, includeProtected) {
+    const protectedNames = getProtectedDependencyNames(runtime);
+    const mergedRejectList = includeProtected ? rejectList : mergeRejectLists(rejectList, protectedNames);
+    const args = ['exec', 'ncu', '--jsonUpgraded', '--workspaces', '--root', '--target', target];
+    if (mergedRejectList.length > 0)
+        args.push('--reject', mergedRejectList.join(','));
+    const result = await runBufferedPm(runtime, args);
+    return normalizeNcuJson(result.output);
+}
+async function collectOutdatedUpdates(runtime, target, rejectList, includeProtected) {
+    const protectedNames = getProtectedDependencyNames(runtime);
+    const mergedRejectList = new Set(includeProtected ? rejectList : mergeRejectLists(rejectList, protectedNames));
+    const result = await runBufferedPm(runtime, ['outdated', '--format', 'json', '--recursive'], false);
+    if (result.code !== 0 && result.code !== 1) {
+        throw new Error(`Command failed: pnpm outdated --format json --recursive\n${result.output}`);
+    }
+    const rawUpdates = normalizePnpmOutdatedJson(result.output, runtime.cwd, target);
+    const filteredUpdates = Object.fromEntries(Object.entries(rawUpdates)
+        .map(([filePath, updates]) => [
+        filePath,
+        Object.fromEntries(Object.entries(updates).filter(([packageName]) => !mergedRejectList.has(packageName))),
+    ])
+        .filter(([, updates]) => Object.keys(updates).length > 0));
+    const versionsByFile = await getManifestVersionsByFile(filteredUpdates, runtime.cwd);
+    return sortUpdatesByFile(Object.fromEntries(Object.entries(filteredUpdates).map(([filePath, updates]) => [
+        filePath,
+        Object.fromEntries(Object.entries(updates).map(([packageName, targetVersion]) => [
+            packageName,
+            applyManifestVersionStyle(versionsByFile[filePath]?.[packageName], targetVersion),
+        ])),
+    ])));
+}
+async function collectUpgradeCandidates(runtime, target, rejectList, includeProtected = false) {
+    const [outdatedUpdates, ncuUpdates] = await Promise.all([
+        collectOutdatedUpdates(runtime, target, rejectList, includeProtected),
+        collectNcuUpdates(runtime, target, rejectList, includeProtected),
+    ]);
+    return mergeWorkspaceUpdates(outdatedUpdates, ncuUpdates);
+}
+async function collectProtectedHoldUpdates(runtime, target, rejectList = []) {
+    const protectedNames = new Set(getProtectedDependencyNames(runtime));
+    const allCandidates = await collectUpgradeCandidates(runtime, target, rejectList, true);
+    return sortUpdatesByFile(Object.fromEntries(Object.entries(allCandidates)
+        .map(([filePath, updates]) => [
+        filePath,
+        Object.fromEntries(Object.entries(updates).filter(([packageName]) => protectedNames.has(packageName))),
+    ])
+        .filter(([, updates]) => Object.keys(updates).length > 0)));
+}
+function deriveProtectedOverrideTargetVersion(currentOverride, normalizedTargetVersion) {
+    if (currentOverride?.startsWith('^'))
+        return `^${normalizedTargetVersion}`;
+    if (currentOverride?.startsWith('~'))
+        return `~${normalizedTargetVersion}`;
+    return normalizedTargetVersion;
+}
+function buildProtectedUpgradePlans(runtime, entries) {
+    const currentOverrides = readProtectedOverrides(runtime.cwd, runtime.config.upgrade?.protectedOverridesFile ?? 'pnpm-workspace.yaml');
+    const hints = runtime.config.upgrade?.protectedDependencyUpstreamHints ?? {};
+    const normalizedTargetsByPackage = new Map();
+    for (const entry of entries) {
+        const normalizedTargets = normalizedTargetsByPackage.get(entry.packageName) ?? new Set();
+        normalizedTargets.add(normalizeVersionSpec(entry.targetVersion));
+        normalizedTargetsByPackage.set(entry.packageName, normalizedTargets);
+    }
+    return Array.from(normalizedTargetsByPackage.entries())
+        .map(([packageName, targets]) => {
+        if (targets.size !== 1) {
+            throw new Error(`Protected singleton upgrade target is ambiguous for "${packageName}".`);
+        }
+        const [targetVersion] = Array.from(targets);
+        const currentOverride = currentOverrides[packageName] ?? null;
+        return {
+            packageName,
+            currentOverride,
+            targetVersion: deriveProtectedOverrideTargetVersion(currentOverride, targetVersion),
+            upstreamHints: hints[packageName] ?? [],
+        };
+    })
+        .sort((left, right) => left.packageName.localeCompare(right.packageName));
+}
+async function getReleaseDate(runtime, packageName, version) {
+    const command = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const result = await runCommandBuffered({ command, args: ['view', packageName, 'time', '--json'] }, runtime.cwd);
+    if (result.code !== 0 || !result.output.trim()) {
+        throw new Error(`Unable to read npm release metadata for "${packageName}".`);
+    }
+    try {
+        const times = parseJsonObjectFromCommandOutput(result.output);
+        const releaseTime = times[version];
+        if (typeof releaseTime !== 'string')
+            return null;
+        if (!releaseTime)
+            return null;
+        const releaseDate = new Date(releaseTime);
+        return Number.isNaN(releaseDate.getTime()) ? null : releaseDate;
+    }
+    catch {
+        throw new Error(`Invalid npm release metadata for "${packageName}".`);
+    }
+}
+async function getCooldownRejectList(runtime, days, target) {
+    if (days <= 0)
+        return [];
+    try {
+        console.info(colorize(`Checking release age for ${target} updates (${days}-day cooldown)...`, colors.cyan));
+        const candidatesByFile = await collectUpgradeCandidates(runtime, target, [], true);
+        const allCandidates = new Map();
+        for (const fileUpdates of Object.values(candidatesByFile)) {
+            for (const [packageName, targetVersion] of Object.entries(fileUpdates)) {
+                allCandidates.set(packageName, targetVersion);
+            }
+        }
+        const rejectList = [];
+        let processed = 0;
+        const candidates = Array.from(allCandidates.entries());
+        for (const [packageName, targetVersion] of candidates) {
+            const releaseDate = await getReleaseDate(runtime, packageName, normalizeVersionSpec(targetVersion));
+            processed += 1;
+            process.stdout.write(`\rCooldown ${processed}/${candidates.length}`);
+            if (!releaseDate) {
+                rejectList.push(packageName);
+                console.warn(colorize(`\nCooldown hold: ${packageName} has unknown release age.`, colors.yellow));
+                continue;
+            }
+            const ageInDays = (Date.now() - releaseDate.getTime()) / (1000 * 60 * 60 * 24);
+            if (ageInDays < days)
+                rejectList.push(packageName);
+        }
+        if (candidates.length > 0)
+            console.info('');
+        return rejectList.sort((left, right) => left.localeCompare(right));
+    }
+    catch (error) {
+        throw new Error(`Cooldown pre-check failed before manifests were changed. ${error.message} Rerun with --no-cooldown to bypass release-age checks explicitly.`);
+    }
+}
+function formatEntryGroups(entries) {
+    const byFile = new Map();
+    for (const entry of entries) {
+        const list = byFile.get(entry.filePath) ?? [];
+        list.push(entry);
+        byFile.set(entry.filePath, list);
+    }
+    return Array.from(byFile.entries()).flatMap(([filePath, fileEntries]) => [
+        colorize(filePath, colors.cyan),
+        ...fileEntries.map((entry) => `  ${entry.packageName}: ${entry.currentVersion ?? '?'} -> ${entry.targetVersion}`),
+    ]);
+}
+async function applyWorkspaceUpgrades(runtime, target, rejectList = [], filterPackages = []) {
+    const args = ['exec', 'ncu', '--workspaces', '--root', '--color', '-u', '--target', target];
+    if (rejectList.length > 0)
+        args.push('--reject', rejectList.join(','));
+    if (filterPackages.length > 0)
+        args.push('--filter', filterPackages.join(','));
+    runInheritedPm(runtime, args);
+}
+async function installDependencies(runtime, useFreshPackageManager) {
+    try {
+        runInheritedPm(runtime, ['install'], useFreshPackageManager ? buildFreshPackageManagerCommand : buildPackageManagerCommand);
+    }
+    catch (error) {
+        throw new Error([
+            'Dependency install failed after manifest updates.',
+            'The package.json files may already be changed while the lockfile/install is incomplete.',
+            `Run ${formatCommand(runtime.config.packageManager, ['install'])} after fixing the package-manager environment.`,
+            error.message,
+        ].join('\n'));
+    }
+}
+async function preparePackageManagerAfterManifestUpdates(runtime, previousPnpmVersion) {
+    const currentPnpmVersion = await readRootPnpmPackageManagerVersion(runtime.cwd);
+    if (!currentPnpmVersion || currentPnpmVersion === previousPnpmVersion)
+        return false;
+    console.info(colorize(`Preparing pnpm ${currentPnpmVersion} via Corepack...`, colors.cyan));
+    prepareCorepackPnpm(runtime, runtime.cwd, currentPnpmVersion);
+    return true;
+}
+function runConfiguredStep(runtime, step) {
+    if (!step.command) {
+        throw new Error(`Configured upgrade step "${step.label}" must define command.`);
+    }
+    console.info(colorize(step.label, colors.cyan));
+    const code = runCommandInherited({
+        command: step.command,
+        args: step.args ?? [],
+        cwd: step.cwd,
+        env: step.env,
+    }, runtime.cwd);
+    if (code !== 0)
+        process.exit(code);
+}
+function parseCliArgs(runtime, rawArgs) {
+    const verbose = rawArgs.includes('--verbose');
+    const daysArg = rawArgs.find((arg) => arg.startsWith('--days='));
+    const defaultDays = runtime.config.upgrade?.defaultCooldownDays ?? 7;
+    const days = daysArg
+        ? Number.parseInt(daysArg.slice('--days='.length), 10)
+        : rawArgs.includes('--no-cooldown') ? 0 : defaultDays;
+    return {
+        allowMajor: rawArgs.includes('--major') || rawArgs.includes('--latest'),
+        verbose,
+        alignProtectedSingletons: rawArgs.includes('--isolated') || rawArgs.includes('--align-protected-singletons'),
+        days: Number.isFinite(days) && days > 0 ? days : 0,
+    };
+}
+export function parseYesNo(answer, defaultValue) {
+    const normalized = answer.trim().toLowerCase();
+    if (!normalized)
+        return defaultValue;
+    if (['s', 'sim', 'y', 'yes'].includes(normalized))
+        return true;
+    if (['n', 'nao', 'não', 'no'].includes(normalized))
+        return false;
+    return null;
+}
+export function formatYesNoPrompt(icon, question, defaultValue) {
+    return `${icon} ${question} ${defaultValue ? '[Y/n]' : '[y/N]'} `;
+}
+async function promptYesNo(prompt, question, defaultValue) {
+    while (true) {
+        const parsed = parseYesNo(await prompt.question(question), defaultValue);
+        if (parsed !== null)
+            return parsed;
+        console.info(colorize('Invalid answer. Use Y or N.', colors.yellow));
+    }
+}
+async function resolveOptions(runtime, rawArgs) {
+    const cliOptions = parseCliArgs(runtime, rawArgs);
+    if (rawArgs.includes('--yes') || !input.isTTY || !output.isTTY)
+        return cliOptions;
+    console.info(colorize('Upgrade configuration', colors.bright));
+    const prompt = createInterface({ input, output });
+    try {
+        const cooldownEnabled = await promptYesNo(prompt, formatYesNoPrompt('❄', 'Cooldown enabled?', cliOptions.days > 0), cliOptions.days > 0);
+        const allowMajor = await promptYesNo(prompt, formatYesNoPrompt('↗', 'Major upgrades?', cliOptions.allowMajor), cliOptions.allowMajor);
+        const alignProtectedSingletons = await promptYesNo(prompt, formatYesNoPrompt('🔄', 'Protected singleton upgrades?', cliOptions.alignProtectedSingletons), cliOptions.alignProtectedSingletons);
+        return {
+            allowMajor,
+            verbose: cliOptions.verbose,
+            alignProtectedSingletons,
+            days: cooldownEnabled ? (cliOptions.days > 0 ? cliOptions.days : (runtime.config.upgrade?.defaultCooldownDays ?? 7)) : 0,
+        };
+    }
+    finally {
+        prompt.close();
+    }
+}
+export async function runUpgradeEngine(runtime, rawArgs) {
+    const options = await resolveOptions(runtime, rawArgs);
+    const target = options.allowMajor ? 'latest' : 'minor';
+    const protectedNames = getProtectedDependencyNames(runtime);
+    console.info(colorize('Checking eligible dependency updates...', colors.cyan));
+    const cooldownRejectList = await getCooldownRejectList(runtime, options.days, target);
+    const currentTargetCandidates = await collectUpgradeCandidates(runtime, target, [], true);
+    const cooldownHoldUpdates = filterWorkspaceUpdatesByPackageNames(currentTargetCandidates, new Set(cooldownRejectList));
+    const cooldownHoldVersionsByFile = await getManifestVersionsByFile(cooldownHoldUpdates, runtime.cwd);
+    const skippedEntriesByKey = new Map();
+    addSkippedEntries(skippedEntriesByKey, buildSkippedUpgradeEntries(cooldownHoldUpdates, 'cooldown', (filePath, packageName) => cooldownHoldVersionsByFile[filePath]?.[packageName] ?? null));
+    if (!options.allowMajor) {
+        const latestCandidates = await collectUpgradeCandidates(runtime, 'latest', [], true);
+        const majorHoldUpdates = subtractWorkspaceUpdates(latestCandidates, currentTargetCandidates);
+        const majorHoldVersionsByFile = await getManifestVersionsByFile(majorHoldUpdates, runtime.cwd);
+        addSkippedEntries(skippedEntriesByKey, buildSkippedUpgradeEntries(majorHoldUpdates, 'major', (filePath, packageName) => majorHoldVersionsByFile[filePath]?.[packageName] ?? null));
+    }
+    const upgradeCandidates = await collectUpgradeCandidates(runtime, target, cooldownRejectList);
+    const versionsByFile = await getManifestVersionsByFile(upgradeCandidates, runtime.cwd);
+    const updatedEntries = buildUpgradeEntries(upgradeCandidates, (filePath, packageName) => versionsByFile[filePath]?.[packageName] ?? null);
+    const protectedHoldUpdates = await collectProtectedHoldUpdates(runtime, target, cooldownRejectList);
+    const protectedHoldVersionsByFile = await getManifestVersionsByFile(protectedHoldUpdates, runtime.cwd);
+    let protectedHoldEntries = buildUpgradeEntries(protectedHoldUpdates, (filePath, packageName) => protectedHoldVersionsByFile[filePath]?.[packageName] ?? null);
+    let protectedUpgradedEntries = [];
+    if (updatedEntries.length > 0) {
+        console.info(colorize('Applying dependency updates...', colors.cyan));
+        const previousPnpmVersion = await readRootPnpmPackageManagerVersion(runtime.cwd);
+        await applyWorkspaceUpgrades(runtime, target, mergeRejectLists(cooldownRejectList, protectedNames));
+        const useFreshPackageManager = await preparePackageManagerAfterManifestUpdates(runtime, previousPnpmVersion);
+        console.info(colorize('Installing dependencies...', colors.cyan));
+        await installDependencies(runtime, useFreshPackageManager);
+    }
+    if (options.alignProtectedSingletons && protectedHoldEntries.length > 0) {
+        const plans = buildProtectedUpgradePlans(runtime, protectedHoldEntries);
+        const selectedPackages = plans.map((plan) => plan.packageName);
+        const overrideUpdates = Object.fromEntries(plans.map((plan) => [plan.packageName, plan.targetVersion]));
+        console.info(colorize('Applying protected singleton upgrades...', colors.cyan));
+        const previousPnpmVersion = await readRootPnpmPackageManagerVersion(runtime.cwd);
+        await applyWorkspaceUpgrades(runtime, target, cooldownRejectList, selectedPackages);
+        console.info(colorize('Updating protected dependency overrides...', colors.cyan));
+        await updateProtectedOverrides(runtime.cwd, runtime.config.upgrade?.protectedOverridesFile ?? 'pnpm-workspace.yaml', overrideUpdates);
+        const useFreshPackageManager = await preparePackageManagerAfterManifestUpdates(runtime, previousPnpmVersion);
+        console.info(colorize('Installing dependencies after protected singleton upgrades...', colors.cyan));
+        await installDependencies(runtime, useFreshPackageManager);
+        if (runtime.config.upgrade?.singletonGuardCommand) {
+            runConfiguredStep(runtime, runtime.config.upgrade.singletonGuardCommand);
+        }
+        const selected = new Set(selectedPackages);
+        protectedUpgradedEntries = protectedHoldEntries.filter((entry) => selected.has(entry.packageName));
+        protectedHoldEntries = protectedHoldEntries.filter((entry) => !selected.has(entry.packageName));
+    }
+    addSkippedEntries(skippedEntriesByKey, protectedHoldEntries.map((entry) => ({
+        ...entry,
+        reason: 'protected-singleton',
+    })));
+    console.info('');
+    console.info(colorize('Upgrade complete', `${colors.bright}${colors.green}`));
+    console.info('');
+    console.info(colorize('Updated', colors.bright));
+    if (updatedEntries.length === 0) {
+        console.info('- No eligible dependency updates.');
+    }
+    else {
+        for (const line of formatEntryGroups(updatedEntries))
+            console.info(`- ${line}`);
+    }
+    const skippedEntries = Array.from(skippedEntriesByKey.values());
+    if (skippedEntries.length > 0) {
+        const hints = runtime.config.upgrade?.protectedDependencyUpstreamHints ?? {};
+        console.info('');
+        console.info(colorize('Not updated', colors.bright));
+        for (const reason of skippedReasonOrder) {
+            const reasonEntries = skippedEntries.filter((entry) => entry.reason === reason);
+            if (reasonEntries.length === 0)
+                continue;
+            console.info(`- ${colorize(skippedReasonLabels[reason], colors.yellow)}`);
+            for (const line of formatEntryGroups(reasonEntries))
+                console.info(`  ${line}`);
+            if (reason !== 'protected-singleton')
+                continue;
+            for (const packageName of uniqueSorted(reasonEntries.map((entry) => entry.packageName))) {
+                const upstreamPackages = hints[packageName] ?? [];
+                if (upstreamPackages.length > 0) {
+                    console.info(`  ${colorize(packageName, colors.cyan)}: review/update ${colorize(upstreamPackages.join(', '), colors.bright)} before upgrading.`);
+                }
+            }
+        }
+    }
+    if (protectedUpgradedEntries.length > 0) {
+        console.info('');
+        console.info(colorize('Protected singleton upgrades', colors.bright));
+        for (const line of formatEntryGroups(protectedUpgradedEntries))
+            console.info(`- ${line}`);
+    }
+    if (options.verbose) {
+        console.info(colorize(`Executed with target=${target}.`, colors.gray));
+    }
+}

package/dist/validate.d.ts

@@ -0,0 +1,7 @@
+import type { WebToolkitCliConfig } from './config.js';
+type Runtime = {
+    cwd: string;
+    config: WebToolkitCliConfig;
+};
+export declare function runValidateEngine(runtime: Runtime): Promise<void>;
+export {};