@rainy-updates/cli 0.5.0-rc.2 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.5.0] - 2026-02-27
+
+### Changed
+
+- Promoted `0.5.0-rc.4` to General Availability.
+- Stabilized deterministic CI artifact behavior for JSON, SARIF, and GitHub outputs.
+- Finalized fix-PR summary metadata contract defaults for automation pipelines.
+
+### Added
+
+- GA release gate includes `perf:smoke` CI check for regression protection.
+
+## [0.5.0-rc.4] - 2026-02-27
+
+### Changed
+
+- Hardened deterministic CI artifacts:
+  - stable key ordering for JSON and SARIF files,
+  - deterministic sorting for updates, warnings, and errors in output pipelines.
+- Improved fail-reason classification consistency for registry/runtime failures across commands.
+- Fix-PR metadata in summary now has stable defaults (`fixPrApplied`, `fixBranchName`, `fixCommitSha`) to reduce contract drift.
+- Fix-PR staging now includes only updated manifests plus explicit report files, with deterministic file ordering.
+- Added warning when Bun runtime falls back from SQLite cache backend to file cache backend.
+
+### Added
+
+- Added `perf:smoke` script and CI gate to enforce a basic performance regression threshold.
+- Added deterministic output and summary regression tests.
+
 ## [0.5.0-rc.2] - 2026-02-27
 
 ### Added

package/README.md

@@ -205,6 +205,7 @@ rainy-updates --version
 This package ships with production CI/CD pipelines in the repository:
 
 - Continuous integration pipeline for typecheck, tests, build, and production smoke checks.
+- Performance smoke gate (`perf:smoke`) to catch startup/runtime regressions in CI.
 - Tag-driven release pipeline for npm publishing with provenance.
 - Release preflight validation for npm auth/scope checks before publishing.
 

package/dist/bin/cli.js

@@ -14,6 +14,9 @@ import { renderResult } from "../output/format.js";
 import { writeGitHubOutput } from "../output/github.js";
 import { createSarifReport } from "../output/sarif.js";
 import { renderPrReport } from "../output/pr-report.js";
+import { writeFileAtomic } from "../utils/io.js";
+import { resolveFailReason } from "../core/summary.js";
+import { stableStringify } from "../utils/stable-json.js";
 async function main() {
     try {
         const argv = process.argv.slice(2);
@@ -64,30 +67,36 @@ async function main() {
         const result = await runCommand(parsed);
         if (parsed.options.prReportFile) {
             const markdown = renderPrReport(result);
-            await fs.mkdir(path.dirname(parsed.options.prReportFile), { recursive: true });
-            await fs.writeFile(parsed.options.prReportFile, markdown + "\n", "utf8");
+            await writeFileAtomic(parsed.options.prReportFile, markdown + "\n");
         }
         if (parsed.options.fixPr && (parsed.command === "check" || parsed.command === "upgrade")) {
+            result.summary.fixPrApplied = false;
+            result.summary.fixBranchName = parsed.options.fixBranch ?? "chore/rainy-updates";
+            result.summary.fixCommitSha = "";
             const fixResult = await applyFixPr(parsed.options, result, parsed.options.prReportFile ? [parsed.options.prReportFile] : []);
             result.summary.fixPrApplied = fixResult.applied;
-            result.summary.fixBranchName = fixResult.branchName;
-            result.summary.fixCommitSha = fixResult.commitSha;
+            result.summary.fixBranchName = fixResult.branchName ?? "";
+            result.summary.fixCommitSha = fixResult.commitSha ?? "";
+        }
+        result.summary.failReason = resolveFailReason(result.updates, result.errors, parsed.options.failOn, parsed.options.maxUpdates, parsed.options.ci);
+        const renderStartedAt = Date.now();
+        let rendered = renderResult(result, parsed.options.format);
+        result.summary.durationMs.render = Math.max(0, Date.now() - renderStartedAt);
+        if (parsed.options.format === "json" || parsed.options.format === "metrics") {
+            rendered = renderResult(result, parsed.options.format);
         }
         if (parsed.options.jsonFile) {
-            await fs.mkdir(path.dirname(parsed.options.jsonFile), { recursive: true });
-            await fs.writeFile(parsed.options.jsonFile, JSON.stringify(result, null, 2) + "\n", "utf8");
+            await writeFileAtomic(parsed.options.jsonFile, stableStringify(result, 2) + "\n");
         }
         if (parsed.options.githubOutputFile) {
             await writeGitHubOutput(parsed.options.githubOutputFile, result);
         }
         if (parsed.options.sarifFile) {
             const sarif = createSarifReport(result);
-            await fs.mkdir(path.dirname(parsed.options.sarifFile), { recursive: true });
-            await fs.writeFile(parsed.options.sarifFile, JSON.stringify(sarif, null, 2) + "\n", "utf8");
+            await writeFileAtomic(parsed.options.sarifFile, stableStringify(sarif, 2) + "\n");
         }
-        const rendered = renderResult(result, parsed.options.format);
         process.stdout.write(rendered + "\n");
-        process.exitCode = resolveExitCode(result, parsed.options.failOn, parsed.options.maxUpdates, parsed.options.ci);
+        process.exitCode = resolveExitCode(result, result.summary.failReason);
     }
     catch (error) {
         process.stderr.write(`rainy-updates: ${String(error)}\n`);
@@ -116,6 +125,7 @@ Options:
   --fix-branch <name>
   --fix-commit-message <text>
   --fix-dry-run
+  --fix-pr-no-checkout
   --no-pr-report
   --json-file <path>
   --github-output <path>
@@ -123,6 +133,7 @@ Options:
   --pr-report-file <path>
   --fail-on none|patch|minor|major|any
   --max-updates <n>
+  --log-level error|warn|info|debug
   --ci`;
     }
     if (isCommand && command === "warm-cache") {
@@ -161,6 +172,7 @@ Options:
   --fix-branch <name>
   --fix-commit-message <text>
   --fix-dry-run
+  --fix-pr-no-checkout
   --no-pr-report
   --json-file <path>
   --pr-report-file <path>`;
@@ -202,7 +214,7 @@ Global options:
   --cwd <path>
   --workspace
   --target patch|minor|major|latest
-  --format table|json|minimal|github
+  --format table|json|minimal|github|metrics
   --json-file <path>
   --github-output <path>
   --sarif-file <path>
@@ -214,7 +226,9 @@ Global options:
   --fix-branch <name>
   --fix-commit-message <text>
   --fix-dry-run
+  --fix-pr-no-checkout
   --no-pr-report
+  --log-level error|warn|info|debug
   --concurrency <n>
   --cache-ttl <seconds>
   --offline
@@ -247,22 +261,10 @@ async function readPackageVersion() {
     const parsed = JSON.parse(content);
     return parsed.version ?? "0.0.0";
 }
-function resolveExitCode(result, failOn, maxUpdates, ciMode) {
+function resolveExitCode(result, failReason) {
     if (result.errors.length > 0)
         return 2;
-    if (typeof maxUpdates === "number" && result.updates.length > maxUpdates)
+    if (failReason !== "none")
         return 1;
-    const effectiveFailOn = failOn && failOn !== "none" ? failOn : ciMode ? "any" : "none";
-    if (!shouldFailForUpdates(result.updates, effectiveFailOn))
-        return 0;
-    return 1;
-}
-function shouldFailForUpdates(updates, failOn) {
-    if (failOn === "none")
-        return false;
-    if (failOn === "any" || failOn === "patch")
-        return updates.length > 0;
-    if (failOn === "minor")
-        return updates.some((update) => update.diffType === "minor" || update.diffType === "major");
-    return updates.some((update) => update.diffType === "major");
+    return 0;
 }

package/dist/cache/cache.d.ts

@@ -1,6 +1,8 @@
 import type { CachedVersion, TargetLevel } from "../types/index.js";
 export declare class VersionCache {
     private readonly store;
+    readonly backend: "sqlite" | "file";
+    readonly degraded: boolean;
     private constructor();
     static create(customPath?: string): Promise<VersionCache>;
     getValid(packageName: string, target: TargetLevel): Promise<CachedVersion | null>;

package/dist/cache/cache.js

@@ -106,17 +106,22 @@ class SqliteCacheStore {
 }
 export class VersionCache {
     store;
-    constructor(store) {
+    backend;
+    degraded;
+    constructor(store, backend, degraded) {
         this.store = store;
+        this.backend = backend;
+        this.degraded = degraded;
     }
     static async create(customPath) {
         const basePath = customPath ?? path.join(os.homedir(), ".cache", "rainy-updates");
         const sqlitePath = path.join(basePath, "cache.db");
         const sqliteStore = await tryCreateSqliteStore(sqlitePath);
         if (sqliteStore)
-            return new VersionCache(sqliteStore);
+            return new VersionCache(sqliteStore, "sqlite", false);
         const jsonPath = path.join(basePath, "cache.json");
-        return new VersionCache(new FileCacheStore(jsonPath));
+        const degraded = typeof Bun !== "undefined";
+        return new VersionCache(new FileCacheStore(jsonPath), "file", degraded);
     }
     async getValid(packageName, target) {
         const entry = await this.store.get(packageName, target);

package/dist/config/loader.d.ts

@@ -1,4 +1,4 @@
-import type { DependencyKind, FailOnLevel, OutputFormat, TargetLevel } from "../types/index.js";
+import type { DependencyKind, FailOnLevel, LogLevel, OutputFormat, TargetLevel } from "../types/index.js";
 export interface FileConfig {
     target?: TargetLevel;
     filter?: string;
@@ -21,7 +21,9 @@ export interface FileConfig {
     fixBranch?: string;
     fixCommitMessage?: string;
     fixDryRun?: boolean;
+    fixPrNoCheckout?: boolean;
     noPrReport?: boolean;
+    logLevel?: LogLevel;
     install?: boolean;
     packageManager?: "auto" | "npm" | "pnpm";
     sync?: boolean;

package/dist/config/policy.d.ts

@@ -2,15 +2,26 @@ import type { TargetLevel } from "../types/index.js";
 export interface PolicyConfig {
     ignore?: string[];
     packageRules?: Record<string, {
+        match?: string;
         maxTarget?: TargetLevel;
         ignore?: boolean;
+        maxUpdatesPerRun?: number;
+        cooldownDays?: number;
+        allowPrerelease?: boolean;
     }>;
 }
+export interface PolicyRule {
+    match?: string;
+    maxTarget?: TargetLevel;
+    ignore: boolean;
+    maxUpdatesPerRun?: number;
+    cooldownDays?: number;
+    allowPrerelease?: boolean;
+}
 export interface ResolvedPolicy {
     ignorePatterns: string[];
-    packageRules: Map<string, {
-        maxTarget?: TargetLevel;
-        ignore: boolean;
-    }>;
+    packageRules: Map<string, PolicyRule>;
+    matchRules: PolicyRule[];
 }
 export declare function loadPolicy(cwd: string, policyFile?: string): Promise<ResolvedPolicy>;
+export declare function resolvePolicyRule(packageName: string, policy: ResolvedPolicy): PolicyRule | undefined;

package/dist/config/policy.js

@@ -12,13 +12,10 @@ export async function loadPolicy(cwd, policyFile) {
             const parsed = JSON.parse(content);
             return {
                 ignorePatterns: parsed.ignore ?? [],
-                packageRules: new Map(Object.entries(parsed.packageRules ?? {}).map(([pkg, rule]) => [
-                    pkg,
-                    {
-                        maxTarget: rule.maxTarget,
-                        ignore: rule.ignore === true,
-                    },
-                ])),
+                packageRules: new Map(Object.entries(parsed.packageRules ?? {}).map(([pkg, rule]) => [pkg, normalizeRule(rule)])),
+                matchRules: Object.values(parsed.packageRules ?? {})
+                    .map((rule) => normalizeRule(rule))
+                    .filter((rule) => typeof rule.match === "string" && rule.match.length > 0),
             };
         }
         catch {
@@ -28,5 +25,36 @@ export async function loadPolicy(cwd, policyFile) {
     return {
         ignorePatterns: [],
         packageRules: new Map(),
+        matchRules: [],
     };
 }
+export function resolvePolicyRule(packageName, policy) {
+    const exact = policy.packageRules.get(packageName);
+    if (exact)
+        return exact;
+    return policy.matchRules.find((rule) => matchesPattern(packageName, rule.match));
+}
+function normalizeRule(rule) {
+    return {
+        match: typeof rule.match === "string" ? rule.match : undefined,
+        maxTarget: rule.maxTarget,
+        ignore: rule.ignore === true,
+        maxUpdatesPerRun: asNonNegativeInt(rule.maxUpdatesPerRun),
+        cooldownDays: asNonNegativeInt(rule.cooldownDays),
+        allowPrerelease: rule.allowPrerelease === true,
+    };
+}
+function asNonNegativeInt(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0)
+        return undefined;
+    return value;
+}
+function matchesPattern(value, pattern) {
+    if (!pattern || pattern.length === 0)
+        return false;
+    if (pattern === "*")
+        return true;
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    const regex = new RegExp(`^${escaped}$`);
+    return regex.test(value);
+}

package/dist/core/check.js

@@ -6,16 +6,26 @@ import { VersionCache } from "../cache/cache.js";
 import { NpmRegistryClient } from "../registry/npm.js";
 import { detectPackageManager } from "../pm/detect.js";
 import { discoverPackageDirs } from "../workspace/discover.js";
-import { loadPolicy } from "../config/policy.js";
+import { loadPolicy, resolvePolicyRule } from "../config/policy.js";
+import { createSummary, finalizeSummary } from "./summary.js";
 export async function check(options) {
+    const startedAt = Date.now();
+    let discoveryMs = 0;
+    let cacheMs = 0;
+    let registryMs = 0;
+    const discoveryStartedAt = Date.now();
     const packageManager = await detectPackageManager(options.cwd);
     const packageDirs = await discoverPackageDirs(options.cwd, options.workspace);
+    discoveryMs += Date.now() - discoveryStartedAt;
     const cache = await VersionCache.create();
     const registryClient = new NpmRegistryClient(options.cwd);
     const policy = await loadPolicy(options.cwd, options.policyFile);
     const updates = [];
     const errors = [];
     const warnings = [];
+    if (cache.degraded) {
+        warnings.push("SQLite cache backend unavailable in Bun runtime. Falling back to file cache backend.");
+    }
     let totalDependencies = 0;
     const tasks = [];
     let skipped = 0;
@@ -35,7 +45,7 @@ export async function check(options) {
                 continue;
             if (options.reject && matchesPattern(dep.name, options.reject))
                 continue;
-            const rule = policy.packageRules.get(dep.name);
+            const rule = resolvePolicyRule(dep.name, policy);
             if (rule?.ignore === true) {
                 skipped += 1;
                 continue;
@@ -47,9 +57,10 @@ export async function check(options) {
             tasks.push({ packageDir, dependency: dep });
         }
     }
-    const uniquePackageNames = Array.from(new Set(tasks.map((task) => task.dependency.name)));
+    const uniquePackageNames = Array.from(new Set(tasks.map((task) => task.dependency.name))).sort((a, b) => a.localeCompare(b));
     const resolvedVersions = new Map();
     const unresolvedPackages = [];
+    const cacheLookupStartedAt = Date.now();
     for (const packageName of uniquePackageNames) {
         const cached = await cache.getValid(packageName, options.target);
         if (cached) {
@@ -62,8 +73,10 @@ export async function check(options) {
             unresolvedPackages.push(packageName);
         }
     }
+    cacheMs += Date.now() - cacheLookupStartedAt;
     if (unresolvedPackages.length > 0) {
         if (options.offline) {
+            const cacheFallbackStartedAt = Date.now();
             for (const packageName of unresolvedPackages) {
                 const stale = await cache.getAny(packageName, options.target);
                 if (stale) {
@@ -77,11 +90,15 @@ export async function check(options) {
                     errors.push(`Offline cache miss for ${packageName}. Run once without --offline to warm cache.`);
                 }
             }
+            cacheMs += Date.now() - cacheFallbackStartedAt;
         }
         else {
+            const registryStartedAt = Date.now();
             const fetched = await registryClient.resolveManyPackageMetadata(unresolvedPackages, {
                 concurrency: options.concurrency,
             });
+            registryMs += Date.now() - registryStartedAt;
+            const cacheWriteStartedAt = Date.now();
             for (const [packageName, metadata] of fetched.metadata) {
                 resolvedVersions.set(packageName, {
                     latestVersion: metadata.latestVersion,
@@ -91,6 +108,8 @@ export async function check(options) {
                     await cache.set(packageName, options.target, metadata.latestVersion, metadata.versions, options.cacheTtlSeconds);
                 }
             }
+            cacheMs += Date.now() - cacheWriteStartedAt;
+            const cacheStaleStartedAt = Date.now();
             for (const [packageName, error] of fetched.errors) {
                 const stale = await cache.getAny(packageName, options.target);
                 if (stale) {
@@ -104,13 +123,14 @@ export async function check(options) {
                     errors.push(`Unable to resolve ${packageName}: ${error}`);
                 }
             }
+            cacheMs += Date.now() - cacheStaleStartedAt;
         }
     }
     for (const task of tasks) {
         const metadata = resolvedVersions.get(task.dependency.name);
         if (!metadata?.latestVersion)
             continue;
-        const rule = policy.packageRules.get(task.dependency.name);
+        const rule = resolvePolicyRule(task.dependency.name, policy);
         const effectiveTarget = clampTarget(options.target, rule?.maxTarget);
         const picked = pickTargetVersionFromAvailable(task.dependency.range, metadata.availableVersions, metadata.latestVersion, effectiveTarget);
         if (!picked)
@@ -130,15 +150,26 @@ export async function check(options) {
             reason: rule?.maxTarget ? `policy maxTarget=${rule.maxTarget}` : undefined,
         });
     }
-    const summary = {
+    const limitedUpdates = sortUpdates(applyRuleUpdateCaps(updates, policy));
+    const sortedErrors = [...errors].sort((a, b) => a.localeCompare(b));
+    const sortedWarnings = [...warnings].sort((a, b) => a.localeCompare(b));
+    const summary = finalizeSummary(createSummary({
         scannedPackages: packageDirs.length,
         totalDependencies,
         checkedDependencies: tasks.length,
-        updatesFound: updates.length,
+        updatesFound: limitedUpdates.length,
         upgraded: 0,
         skipped,
         warmedPackages: 0,
-    };
+        errors: sortedErrors,
+        warnings: sortedWarnings,
+        durations: {
+            totalMs: Date.now() - startedAt,
+            discoveryMs,
+            registryMs,
+            cacheMs,
+        },
+    }));
     return {
         projectPath: options.cwd,
         packagePaths: packageDirs,
@@ -146,8 +177,44 @@ export async function check(options) {
         target: options.target,
         timestamp: new Date().toISOString(),
         summary,
-        updates,
-        errors,
-        warnings,
+        updates: limitedUpdates,
+        errors: sortedErrors,
+        warnings: sortedWarnings,
     };
 }
+function applyRuleUpdateCaps(updates, policy) {
+    const limited = [];
+    const seenPerPackage = new Map();
+    for (const update of updates) {
+        const rule = resolvePolicyRule(update.name, policy);
+        const cap = rule?.maxUpdatesPerRun;
+        if (typeof cap !== "number") {
+            limited.push(update);
+            continue;
+        }
+        const seen = seenPerPackage.get(update.name) ?? 0;
+        if (seen >= cap) {
+            continue;
+        }
+        seenPerPackage.set(update.name, seen + 1);
+        limited.push(update);
+    }
+    return limited;
+}
+function sortUpdates(updates) {
+    return [...updates].sort((left, right) => {
+        const byPath = left.packagePath.localeCompare(right.packagePath);
+        if (byPath !== 0)
+            return byPath;
+        const byName = left.name.localeCompare(right.name);
+        if (byName !== 0)
+            return byName;
+        const byKind = left.kind.localeCompare(right.kind);
+        if (byKind !== 0)
+            return byKind;
+        const byFrom = left.fromRange.localeCompare(right.fromRange);
+        if (byFrom !== 0)
+            return byFrom;
+        return left.toRange.localeCompare(right.toRange);
+    });
+}

package/dist/core/fix-pr.js

@@ -3,28 +3,42 @@ import path from "node:path";
 export async function applyFixPr(options, result, extraFiles) {
     if (!options.fixPr)
         return { applied: false };
-    if (result.updates.length === 0)
-        return { applied: false };
+    if (result.updates.length === 0) {
+        return {
+            applied: false,
+            branchName: options.fixBranch ?? "chore/rainy-updates",
+            commitSha: "",
+        };
+    }
     const status = await runGit(options.cwd, ["status", "--porcelain"]);
     if (status.stdout.trim().length > 0) {
         throw new Error("Cannot run --fix-pr with a dirty git working tree.");
     }
     const branch = options.fixBranch ?? "chore/rainy-updates";
-    const branchCheck = await runGit(options.cwd, ["rev-parse", "--verify", "--quiet", branch], true);
-    if (branchCheck.code === 0) {
-        await runGit(options.cwd, ["checkout", branch]);
+    const headRef = await runGit(options.cwd, ["symbolic-ref", "--quiet", "--short", "HEAD"], true);
+    if (headRef.code !== 0 && !options.fixPrNoCheckout) {
+        throw new Error("Cannot run --fix-pr in detached HEAD state without --fix-pr-no-checkout.");
     }
-    else {
-        await runGit(options.cwd, ["checkout", "-b", branch]);
+    if (!options.fixPrNoCheckout) {
+        const branchCheck = await runGit(options.cwd, ["rev-parse", "--verify", "--quiet", branch], true);
+        if (branchCheck.code === 0) {
+            await runGit(options.cwd, ["checkout", branch]);
+        }
+        else {
+            await runGit(options.cwd, ["checkout", "-b", branch]);
+        }
     }
     if (options.fixDryRun) {
         return {
             applied: false,
             branchName: branch,
+            commitSha: "",
         };
     }
-    const manifestFiles = Array.from(new Set(result.packagePaths.map((pkgPath) => path.join(pkgPath, "package.json"))));
-    const filesToStage = Array.from(new Set([...manifestFiles, ...extraFiles]));
+    const manifestFiles = Array.from(new Set(result.updates.map((update) => path.resolve(update.packagePath, "package.json"))));
+    const filesToStage = Array.from(new Set([...manifestFiles, ...extraFiles]
+        .map((entry) => path.resolve(options.cwd, entry))
+        .filter((entry) => entry.startsWith(path.resolve(options.cwd) + path.sep) || entry === path.resolve(options.cwd)))).sort((a, b) => a.localeCompare(b));
     if (filesToStage.length > 0) {
         await runGit(options.cwd, ["add", "--", ...filesToStage]);
     }
@@ -33,6 +47,7 @@ export async function applyFixPr(options, result, extraFiles) {
         return {
             applied: false,
             branchName: branch,
+            commitSha: "",
         };
     }
     const message = options.fixCommitMessage ?? `chore(deps): apply rainy-updates (${result.updates.length} updates)`;

package/dist/core/options.js

@@ -40,7 +40,9 @@ export async function parseCliArgs(argv) {
         fixBranch: "chore/rainy-updates",
         fixCommitMessage: undefined,
         fixDryRun: false,
+        fixPrNoCheckout: false,
         noPrReport: false,
+        logLevel: "info",
     };
     let force = false;
     let initCiMode = "enterprise";
@@ -208,6 +210,18 @@ export async function parseCliArgs(argv) {
             base.noPrReport = true;
             continue;
         }
+        if (current === "--fix-pr-no-checkout") {
+            base.fixPrNoCheckout = true;
+            continue;
+        }
+        if (current === "--log-level" && next) {
+            base.logLevel = ensureLogLevel(next);
+            index += 1;
+            continue;
+        }
+        if (current === "--log-level") {
+            throw new Error("Missing value for --log-level");
+        }
         if (current === "--install" && command === "upgrade") {
             continue;
         }
@@ -406,9 +420,15 @@ function applyConfig(base, config) {
     if (typeof config.fixDryRun === "boolean") {
         base.fixDryRun = config.fixDryRun;
     }
+    if (typeof config.fixPrNoCheckout === "boolean") {
+        base.fixPrNoCheckout = config.fixPrNoCheckout;
+    }
     if (typeof config.noPrReport === "boolean") {
         base.noPrReport = config.noPrReport;
     }
+    if (typeof config.logLevel === "string") {
+        base.logLevel = ensureLogLevel(config.logLevel);
+    }
 }
 function parsePackageManager(args) {
     const index = args.indexOf("--pm");
@@ -427,10 +447,16 @@ function ensureTarget(value) {
     throw new Error("--target must be patch, minor, major, latest");
 }
 function ensureFormat(value) {
-    if (value === "table" || value === "json" || value === "minimal" || value === "github") {
+    if (value === "table" || value === "json" || value === "minimal" || value === "github" || value === "metrics") {
+        return value;
+    }
+    throw new Error("--format must be table, json, minimal, github or metrics");
+}
+function ensureLogLevel(value) {
+    if (value === "error" || value === "warn" || value === "info" || value === "debug") {
         return value;
     }
-    throw new Error("--format must be table, json, minimal or github");
+    throw new Error("--log-level must be error, warn, info or debug");
 }
 function parseDependencyKinds(value) {
     const mapped = value

package/dist/core/summary.d.ts

@@ -0,0 +1,22 @@
+import type { FailOnLevel, FailReason, PackageUpdate, Summary } from "../types/index.js";
+export interface DurationInput {
+    totalMs: number;
+    discoveryMs: number;
+    registryMs: number;
+    cacheMs: number;
+}
+export declare function createSummary(input: {
+    scannedPackages: number;
+    totalDependencies: number;
+    checkedDependencies: number;
+    updatesFound: number;
+    upgraded: number;
+    skipped: number;
+    warmedPackages: number;
+    errors: string[];
+    warnings: string[];
+    durations: DurationInput;
+}): Summary;
+export declare function finalizeSummary(summary: Summary): Summary;
+export declare function resolveFailReason(updates: PackageUpdate[], errors: string[], failOn: FailOnLevel | undefined, maxUpdates: number | undefined, ciMode: boolean): FailReason;
+export declare function shouldFailForUpdates(updates: PackageUpdate[], failOn: FailOnLevel): boolean;

package/dist/core/summary.js

@@ -0,0 +1,78 @@
+export function createSummary(input) {
+    const offlineCacheMiss = input.errors.filter((error) => isOfflineCacheMissError(error)).length;
+    const registryFailure = input.errors.filter((error) => isRegistryFailureError(error)).length;
+    const staleCache = input.warnings.filter((warning) => warning.includes("Using stale cache")).length;
+    return {
+        contractVersion: "2",
+        scannedPackages: input.scannedPackages,
+        totalDependencies: input.totalDependencies,
+        checkedDependencies: input.checkedDependencies,
+        updatesFound: input.updatesFound,
+        upgraded: input.upgraded,
+        skipped: input.skipped,
+        warmedPackages: input.warmedPackages,
+        failReason: "none",
+        errorCounts: {
+            total: input.errors.length,
+            offlineCacheMiss,
+            registryFailure,
+            other: 0,
+        },
+        warningCounts: {
+            total: input.warnings.length,
+            staleCache,
+            other: 0,
+        },
+        durationMs: {
+            total: Math.max(0, Math.round(input.durations.totalMs)),
+            discovery: Math.max(0, Math.round(input.durations.discoveryMs)),
+            registry: Math.max(0, Math.round(input.durations.registryMs)),
+            cache: Math.max(0, Math.round(input.durations.cacheMs)),
+            render: 0,
+        },
+        fixPrApplied: false,
+        fixBranchName: "",
+        fixCommitSha: "",
+    };
+}
+export function finalizeSummary(summary) {
+    const errorOther = summary.errorCounts.total - summary.errorCounts.offlineCacheMiss - summary.errorCounts.registryFailure;
+    const warningOther = summary.warningCounts.total - summary.warningCounts.staleCache;
+    summary.errorCounts.other = Math.max(0, errorOther);
+    summary.warningCounts.other = Math.max(0, warningOther);
+    return summary;
+}
+export function resolveFailReason(updates, errors, failOn, maxUpdates, ciMode) {
+    if (errors.some((error) => isOfflineCacheMissError(error))) {
+        return "offline-cache-miss";
+    }
+    if (errors.some((error) => isRegistryFailureError(error))) {
+        return "registry-failure";
+    }
+    if (typeof maxUpdates === "number" && updates.length > maxUpdates) {
+        return "updates-threshold";
+    }
+    const effectiveFailOn = failOn && failOn !== "none" ? failOn : ciMode ? "any" : "none";
+    if (shouldFailForUpdates(updates, effectiveFailOn)) {
+        return "severity-threshold";
+    }
+    return "none";
+}
+export function shouldFailForUpdates(updates, failOn) {
+    if (failOn === "none")
+        return false;
+    if (failOn === "any" || failOn === "patch")
+        return updates.length > 0;
+    if (failOn === "minor")
+        return updates.some((update) => update.diffType === "minor" || update.diffType === "major");
+    return updates.some((update) => update.diffType === "major");
+}
+function isOfflineCacheMissError(value) {
+    return value.includes("Offline cache miss");
+}
+function isRegistryFailureError(value) {
+    return (value.includes("Unable to resolve") ||
+        value.includes("Unable to warm") ||
+        value.includes("Registry request failed") ||
+        value.includes("Registry temporary error"));
+}

package/dist/core/warm-cache.js

@@ -4,13 +4,23 @@ import { VersionCache } from "../cache/cache.js";
 import { NpmRegistryClient } from "../registry/npm.js";
 import { detectPackageManager } from "../pm/detect.js";
 import { discoverPackageDirs } from "../workspace/discover.js";
+import { createSummary, finalizeSummary } from "./summary.js";
 export async function warmCache(options) {
+    const startedAt = Date.now();
+    let discoveryMs = 0;
+    let cacheMs = 0;
+    let registryMs = 0;
+    const discoveryStartedAt = Date.now();
     const packageManager = await detectPackageManager(options.cwd);
     const packageDirs = await discoverPackageDirs(options.cwd, options.workspace);
+    discoveryMs += Date.now() - discoveryStartedAt;
     const cache = await VersionCache.create();
     const registryClient = new NpmRegistryClient(options.cwd);
     const errors = [];
     const warnings = [];
+    if (cache.degraded) {
+        warnings.push("SQLite cache backend unavailable in Bun runtime. Falling back to file cache backend.");
+    }
     let totalDependencies = 0;
     const packageNames = new Set();
     for (const packageDir of packageDirs) {
@@ -30,16 +40,19 @@ export async function warmCache(options) {
             errors.push(`Failed to read package.json in ${packageDir}: ${String(error)}`);
         }
     }
-    const names = Array.from(packageNames);
+    const names = Array.from(packageNames).sort((a, b) => a.localeCompare(b));
     const needsFetch = [];
+    const cacheLookupStartedAt = Date.now();
     for (const pkg of names) {
         const valid = await cache.getValid(pkg, options.target);
         if (!valid)
             needsFetch.push(pkg);
     }
+    cacheMs += Date.now() - cacheLookupStartedAt;
     let warmed = 0;
     if (needsFetch.length > 0) {
         if (options.offline) {
+            const cacheFallbackStartedAt = Date.now();
             for (const pkg of needsFetch) {
                 const stale = await cache.getAny(pkg, options.target);
                 if (stale) {
@@ -50,23 +63,30 @@ export async function warmCache(options) {
                     errors.push(`Offline cache miss for ${pkg}. Cannot warm cache in --offline mode.`);
                 }
             }
+            cacheMs += Date.now() - cacheFallbackStartedAt;
         }
         else {
+            const registryStartedAt = Date.now();
             const fetched = await registryClient.resolveManyPackageMetadata(needsFetch, {
                 concurrency: options.concurrency,
             });
+            registryMs += Date.now() - registryStartedAt;
+            const cacheWriteStartedAt = Date.now();
             for (const [pkg, metadata] of fetched.metadata) {
                 if (metadata.latestVersion) {
                     await cache.set(pkg, options.target, metadata.latestVersion, metadata.versions, options.cacheTtlSeconds);
                     warmed += 1;
                 }
             }
+            cacheMs += Date.now() - cacheWriteStartedAt;
             for (const [pkg, error] of fetched.errors) {
                 errors.push(`Unable to warm ${pkg}: ${error}`);
             }
         }
     }
-    const summary = {
+    const sortedErrors = [...errors].sort((a, b) => a.localeCompare(b));
+    const sortedWarnings = [...warnings].sort((a, b) => a.localeCompare(b));
+    const summary = finalizeSummary(createSummary({
         scannedPackages: packageDirs.length,
         totalDependencies,
         checkedDependencies: names.length,
@@ -74,7 +94,15 @@ export async function warmCache(options) {
         upgraded: 0,
         skipped: 0,
         warmedPackages: warmed,
-    };
+        errors: sortedErrors,
+        warnings: sortedWarnings,
+        durations: {
+            totalMs: Date.now() - startedAt,
+            discoveryMs,
+            registryMs,
+            cacheMs,
+        },
+    }));
     return {
         projectPath: options.cwd,
         packagePaths: packageDirs,
@@ -83,7 +111,7 @@ export async function warmCache(options) {
         timestamp: new Date().toISOString(),
         summary,
         updates: [],
-        errors,
-        warnings,
+        errors: sortedErrors,
+        warnings: sortedWarnings,
     };
 }

package/dist/output/format.js

@@ -1,7 +1,8 @@
 import { renderGitHubAnnotations } from "./github.js";
+import { stableStringify } from "../utils/stable-json.js";
 export function renderResult(result, format) {
     if (format === "json") {
-        return JSON.stringify(result, null, 2);
+        return stableStringify(result, 2);
     }
     if (format === "minimal") {
         if (result.updates.length === 0 && result.summary.warmedPackages > 0) {
@@ -16,6 +17,23 @@ export function renderResult(result, format) {
     if (format === "github") {
         return renderGitHubAnnotations(result);
     }
+    if (format === "metrics") {
+        return [
+            `contract_version=${result.summary.contractVersion}`,
+            `updates_found=${result.summary.updatesFound}`,
+            `errors_count=${result.summary.errorCounts.total}`,
+            `warnings_count=${result.summary.warningCounts.total}`,
+            `checked_dependencies=${result.summary.checkedDependencies}`,
+            `scanned_packages=${result.summary.scannedPackages}`,
+            `warmed_packages=${result.summary.warmedPackages}`,
+            `fail_reason=${result.summary.failReason}`,
+            `duration_total_ms=${result.summary.durationMs.total}`,
+            `duration_discovery_ms=${result.summary.durationMs.discovery}`,
+            `duration_registry_ms=${result.summary.durationMs.registry}`,
+            `duration_cache_ms=${result.summary.durationMs.cache}`,
+            `duration_render_ms=${result.summary.durationMs.render}`,
+        ].join("\n");
+    }
     const lines = [];
     lines.push(`Project: ${result.projectPath}`);
     lines.push(`Scanned packages: ${result.summary.scannedPackages}`);
@@ -52,6 +70,7 @@ export function renderResult(result, format) {
     }
     lines.push("");
     lines.push(`Summary: ${result.summary.updatesFound} updates, ${result.summary.checkedDependencies}/${result.summary.totalDependencies} checked, ${result.summary.warmedPackages} warmed`);
+    lines.push(`Contract v${result.summary.contractVersion}, failReason=${result.summary.failReason}, duration=${result.summary.durationMs.total}ms`);
     if (result.summary.fixPrApplied) {
         lines.push(`Fix PR: applied on branch ${result.summary.fixBranchName ?? "unknown"} (${result.summary.fixCommitSha ?? "no-commit"})`);
     }

package/dist/output/github.js

@@ -1,29 +1,40 @@
-import { promises as fs } from "node:fs";
-import path from "node:path";
+import { writeFileAtomic } from "../utils/io.js";
 export async function writeGitHubOutput(filePath, result) {
     const lines = [
+        `contract_version=${result.summary.contractVersion}`,
         `updates_found=${result.summary.updatesFound}`,
-        `errors_count=${result.errors.length}`,
-        `warnings_count=${result.warnings.length}`,
+        `errors_count=${result.summary.errorCounts.total}`,
+        `warnings_count=${result.summary.warningCounts.total}`,
         `checked_dependencies=${result.summary.checkedDependencies}`,
         `scanned_packages=${result.summary.scannedPackages}`,
         `warmed_packages=${result.summary.warmedPackages}`,
+        `fail_reason=${result.summary.failReason}`,
+        `duration_total_ms=${result.summary.durationMs.total}`,
+        `duration_discovery_ms=${result.summary.durationMs.discovery}`,
+        `duration_registry_ms=${result.summary.durationMs.registry}`,
+        `duration_cache_ms=${result.summary.durationMs.cache}`,
+        `duration_render_ms=${result.summary.durationMs.render}`,
         `fix_pr_applied=${result.summary.fixPrApplied === true ? "1" : "0"}`,
         `fix_pr_branch=${result.summary.fixBranchName ?? ""}`,
         `fix_pr_commit=${result.summary.fixCommitSha ?? ""}`,
     ];
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await fs.writeFile(filePath, lines.join("\n") + "\n", "utf8");
+    await writeFileAtomic(filePath, lines.join("\n") + "\n");
 }
 export function renderGitHubAnnotations(result) {
     const lines = [];
-    for (const update of result.updates) {
+    const sortedUpdates = [...result.updates].sort((left, right) => {
+        const byName = left.name.localeCompare(right.name);
+        if (byName !== 0)
+            return byName;
+        return left.packagePath.localeCompare(right.packagePath);
+    });
+    for (const update of sortedUpdates) {
         lines.push(`::notice title=Dependency Update::${update.name} ${update.fromRange} -> ${update.toRange} (${update.packagePath})`);
     }
-    for (const warning of result.warnings) {
+    for (const warning of [...result.warnings].sort((a, b) => a.localeCompare(b))) {
         lines.push(`::warning title=Rainy Updates::${warning}`);
     }
-    for (const error of result.errors) {
+    for (const error of [...result.errors].sort((a, b) => a.localeCompare(b))) {
         lines.push(`::error title=Rainy Updates::${error}`);
     }
     if (lines.length === 0) {

package/dist/output/sarif.js

@@ -4,7 +4,13 @@ import { fileURLToPath } from "node:url";
 export function createSarifReport(result) {
     const dependencyRuleId = "rainy-updates/dependency-update";
     const runtimeRuleId = "rainy-updates/runtime-error";
-    const updateResults = result.updates.map((update) => ({
+    const sortedUpdates = [...result.updates].sort((left, right) => {
+        const byName = left.name.localeCompare(right.name);
+        if (byName !== 0)
+            return byName;
+        return left.packagePath.localeCompare(right.packagePath);
+    });
+    const updateResults = sortedUpdates.map((update) => ({
         ruleId: dependencyRuleId,
         level: "warning",
         message: {
@@ -26,7 +32,7 @@ export function createSarifReport(result) {
             resolvedVersion: update.toVersionResolved,
         },
     }));
-    const errorResults = result.errors.map((error) => ({
+    const errorResults = [...result.errors].sort((a, b) => a.localeCompare(b)).map((error) => ({
         ruleId: runtimeRuleId,
         level: "error",
         message: {
@@ -57,6 +63,14 @@ export function createSarifReport(result) {
                     },
                 },
                 results: [...updateResults, ...errorResults],
+                properties: {
+                    contractVersion: result.summary.contractVersion,
+                    failReason: result.summary.failReason,
+                    updatesFound: result.summary.updatesFound,
+                    errorsCount: result.summary.errorCounts.total,
+                    warningsCount: result.summary.warningCounts.total,
+                    durationMs: result.summary.durationMs,
+                },
             },
         ],
     };

package/dist/registry/npm.js

@@ -21,7 +21,7 @@ export class NpmRegistryClient {
                     return { latestVersion: null, versions: [] };
                 }
                 if (response.status === 429 || response.status >= 500) {
-                    throw new Error(`Registry temporary error: ${response.status}`);
+                    throw new RetryableRegistryError(`Registry temporary error: ${response.status}`, response.retryAfterMs ?? computeBackoffMs(attempt));
                 }
                 if (response.status < 200 || response.status >= 300) {
                     throw new Error(`Registry request failed: ${response.status}`);
@@ -32,7 +32,8 @@ export class NpmRegistryClient {
             catch (error) {
                 lastError = String(error);
                 if (attempt < 3) {
-                    await sleep(120 * attempt);
+                    const backoffMs = error instanceof RetryableRegistryError ? error.waitMs : computeBackoffMs(attempt);
+                    await sleep(backoffMs);
                 }
             }
         }
@@ -84,6 +85,18 @@ export class NpmRegistryClient {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function computeBackoffMs(attempt) {
+    const baseMs = Math.max(120, attempt * 180);
+    const jitterMs = Math.floor(Math.random() * 120);
+    return baseMs + jitterMs;
+}
+class RetryableRegistryError extends Error {
+    waitMs;
+    constructor(message, waitMs) {
+        super(message);
+        this.waitMs = waitMs;
+    }
+}
 async function createRequester(cwd) {
     const registryConfig = await loadRegistryConfig(cwd ?? process.cwd());
     const undiciRequester = await tryCreateUndiciRequester(registryConfig);
@@ -103,7 +116,11 @@ async function createRequester(cwd) {
                 signal: controller.signal,
             });
             const data = (await response.json().catch(() => null));
-            return { status: response.status, data };
+            return {
+                status: response.status,
+                data,
+                retryAfterMs: parseRetryAfterHeader(response.headers.get("retry-after")),
+            };
         }
         finally {
             clearTimeout(timeout);
@@ -136,7 +153,19 @@ async function tryCreateUndiciRequester(registryConfig) {
                 catch {
                     data = null;
                 }
-                return { status: res.statusCode, data };
+                const retryAfter = (() => {
+                    const header = res.headers["retry-after"];
+                    if (Array.isArray(header))
+                        return header[0] ?? null;
+                    if (typeof header === "string")
+                        return header;
+                    return null;
+                })();
+                return {
+                    status: res.statusCode,
+                    data,
+                    retryAfterMs: parseRetryAfterHeader(retryAfter),
+                };
             }
             finally {
                 clearTimeout(timeout);
@@ -218,3 +247,18 @@ function buildRegistryUrl(registry, packageName) {
     const base = normalizeRegistryUrl(registry);
     return new URL(encodeURIComponent(packageName), base).toString();
 }
+function parseRetryAfterHeader(value) {
+    if (!value)
+        return null;
+    const parsedSeconds = Number(value);
+    if (Number.isFinite(parsedSeconds) && parsedSeconds >= 0) {
+        return Math.round(parsedSeconds * 1000);
+    }
+    const untilMs = Date.parse(value);
+    if (!Number.isFinite(untilMs))
+        return null;
+    const delta = untilMs - Date.now();
+    if (delta <= 0)
+        return 0;
+    return delta;
+}

package/dist/types/index.d.ts

@@ -1,7 +1,9 @@
 export type DependencyKind = "dependencies" | "devDependencies" | "optionalDependencies" | "peerDependencies";
 export type TargetLevel = "patch" | "minor" | "major" | "latest";
-export type OutputFormat = "table" | "json" | "minimal" | "github";
+export type OutputFormat = "table" | "json" | "minimal" | "github" | "metrics";
 export type FailOnLevel = "none" | "patch" | "minor" | "major" | "any";
+export type LogLevel = "error" | "warn" | "info" | "debug";
+export type FailReason = "none" | "updates-threshold" | "severity-threshold" | "registry-failure" | "offline-cache-miss" | "policy-blocked";
 export interface RunOptions {
     cwd: string;
     target: TargetLevel;
@@ -25,7 +27,9 @@ export interface RunOptions {
     fixBranch?: string;
     fixCommitMessage?: string;
     fixDryRun?: boolean;
+    fixPrNoCheckout?: boolean;
     noPrReport?: boolean;
+    logLevel: LogLevel;
 }
 export interface CheckOptions extends RunOptions {
 }
@@ -58,6 +62,7 @@ export interface PackageUpdate {
     reason?: string;
 }
 export interface Summary {
+    contractVersion: "2";
     scannedPackages: number;
     totalDependencies: number;
     checkedDependencies: number;
@@ -65,9 +70,28 @@ export interface Summary {
     upgraded: number;
     skipped: number;
     warmedPackages: number;
-    fixPrApplied?: boolean;
-    fixBranchName?: string;
-    fixCommitSha?: string;
+    failReason: FailReason;
+    errorCounts: {
+        total: number;
+        offlineCacheMiss: number;
+        registryFailure: number;
+        other: number;
+    };
+    warningCounts: {
+        total: number;
+        staleCache: number;
+        other: number;
+    };
+    durationMs: {
+        total: number;
+        discovery: number;
+        registry: number;
+        cache: number;
+        render: number;
+    };
+    fixPrApplied: boolean;
+    fixBranchName: string;
+    fixCommitSha: string;
 }
 export interface CheckResult {
     projectPath: string;

package/dist/utils/io.d.ts

@@ -0,0 +1 @@
+export declare function writeFileAtomic(filePath: string, content: string): Promise<void>;

package/dist/utils/io.js

@@ -0,0 +1,10 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+export async function writeFileAtomic(filePath, content) {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    const tempPath = path.join(dir, `.tmp-${path.basename(filePath)}-${crypto.randomUUID()}`);
+    await fs.writeFile(tempPath, content, "utf8");
+    await fs.rename(tempPath, filePath);
+}

package/dist/utils/stable-json.d.ts

@@ -0,0 +1 @@
+export declare function stableStringify(value: unknown, indent?: number): string;

package/dist/utils/stable-json.js

@@ -0,0 +1,20 @@
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sortValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => sortValue(item));
+    }
+    if (!isPlainObject(value)) {
+        return value;
+    }
+    const sorted = {};
+    const keys = Object.keys(value).sort((a, b) => a.localeCompare(b));
+    for (const key of keys) {
+        sorted[key] = sortValue(value[key]);
+    }
+    return sorted;
+}
+export function stableStringify(value, indent = 2) {
+    return JSON.stringify(sortValue(value), null, indent);
+}

package/dist/workspace/discover.js

@@ -1,5 +1,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
+const HARD_IGNORE_DIRS = new Set(["node_modules", ".git", ".turbo", ".next", "dist", "coverage"]);
+const MAX_DISCOVERED_DIRS = 20000;
 export async function discoverPackageDirs(cwd, workspaceMode) {
     if (!workspaceMode) {
         return [cwd];
@@ -84,6 +86,9 @@ async function expandWorkspacePattern(cwd, pattern) {
     return Array.from(results);
 }
 async function collectMatches(baseDir, segments, index, out) {
+    if (out.size > MAX_DISCOVERED_DIRS) {
+        throw new Error(`Workspace discovery exceeded ${MAX_DISCOVERED_DIRS} directories. Refine workspace patterns.`);
+    }
     if (index >= segments.length) {
         out.add(baseDir);
         return;
@@ -111,7 +116,8 @@ async function readChildDirs(dir) {
         const entries = await fs.readdir(dir, { withFileTypes: true });
         return entries
             .filter((entry) => entry.isDirectory())
-            .filter((entry) => entry.name !== "node_modules" && !entry.name.startsWith("."))
+            .filter((entry) => !HARD_IGNORE_DIRS.has(entry.name))
+            .filter((entry) => !entry.name.startsWith("."))
             .map((entry) => path.join(dir, entry.name));
     }
     catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainy-updates/cli",
-  "version": "0.5.0-rc.2",
+  "version": "0.5.0",
   "description": "Agentic CLI to check and upgrade npm/pnpm dependencies for CI workflows",
   "type": "module",
   "private": false,
@@ -47,6 +47,7 @@
     "test": "bun test",
     "lint": "bunx biome check src tests",
     "check": "bun run typecheck && bun test",
+    "perf:smoke": "node scripts/perf-smoke.mjs",
     "test:prod": "node dist/bin/cli.js --help && node dist/bin/cli.js --version",
     "prepublishOnly": "bun run check && bun run build && bun run test:prod"
   },