@rainy-updates/cli 0.5.0 → 0.5.1-rc.1

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.5.1-rc.1] - 2026-02-27
+
+### Added
+
+- New `ci` command for CI-first orchestration:
+  - profile-driven automation with `--mode minimal|strict|enterprise`,
+  - warm-cache + check/upgrade flow with deterministic artifacts.
+- New rollout and orchestration flags:
+  - `--group-by none|name|scope|kind|risk`
+  - `--group-max <n>`
+  - `--cooldown-days <n>`
+  - `--pr-limit <n>`
+  - `--only-changed`
+- Additive summary/output contract fields:
+  - `groupedUpdates`
+  - `cooldownSkipped`
+  - `ciProfile`
+  - `prLimitHit`
+- Policy schema extensions:
+  - global `cooldownDays`
+  - package rule `group` and `priority`
+
+### Changed
+
+- `check` now supports cooldown-aware filtering when publish timestamps are available.
+- CI workflow templates generated by `init-ci` now use `rainy-updates ci` with explicit profile mode.
+- GitHub output, metrics output, SARIF properties, and PR report include new CI orchestration metadata.
+
+### Tests
+
+- Added parser coverage for `ci` command orchestration flags.
+- Extended workflow, policy, summary, and output tests for new metadata and profile behavior.
+
 ## [0.5.0] - 2026-02-27
 
 ### Changed

package/README.md

@@ -24,6 +24,7 @@ pnpm add -D @rainy-updates/cli
 
 - `check`: analyze dependencies and report available updates.
 - `upgrade`: rewrite dependency ranges in manifests, optionally install lockfile updates.
+- `ci`: run CI-focused dependency automation (warm cache, check/upgrade, policy gates).
 - `warm-cache`: prefetch package metadata for fast and offline checks.
 - `baseline`: save and compare dependency baseline snapshots.
 
@@ -36,6 +37,9 @@ npx @rainy-updates/cli check --format table
 # 2) Strict CI mode (non-zero when updates exist)
 npx @rainy-updates/cli check --workspace --ci --format json --json-file .artifacts/updates.json
 
+# 2b) CI orchestration mode
+npx @rainy-updates/cli ci --workspace --mode strict --format github --json-file .artifacts/updates.json
+
 # 3) Apply upgrades with workspace sync
 npx @rainy-updates/cli upgrade --target latest --workspace --sync --install
 
@@ -151,6 +155,12 @@ Schedule:
 - `--offline`
 - `--fail-on none|patch|minor|major|any`
 - `--max-updates <n>`
+- `--group-by none|name|scope|kind|risk`
+- `--group-max <n>`
+- `--cooldown-days <n>`
+- `--pr-limit <n>`
+- `--only-changed`
+- `--mode minimal|strict|enterprise` (for `ci`)
 - `--policy-file <path>`
 - `--format table|json|minimal|github`
 - `--json-file <path>`

package/dist/bin/cli.js

@@ -7,6 +7,7 @@ import { parseCliArgs } from "../core/options.js";
 import { check } from "../core/check.js";
 import { upgrade } from "../core/upgrade.js";
 import { warmCache } from "../core/warm-cache.js";
+import { runCi } from "../core/ci.js";
 import { initCiWorkflow } from "../core/init-ci.js";
 import { diffBaseline, saveBaseline } from "../core/baseline.js";
 import { applyFixPr } from "../core/fix-pr.js";
@@ -69,7 +70,7 @@ async function main() {
             const markdown = renderPrReport(result);
             await writeFileAtomic(parsed.options.prReportFile, markdown + "\n");
         }
-        if (parsed.options.fixPr && (parsed.command === "check" || parsed.command === "upgrade")) {
+        if (parsed.options.fixPr && (parsed.command === "check" || parsed.command === "upgrade" || parsed.command === "ci")) {
             result.summary.fixPrApplied = false;
             result.summary.fixBranchName = parsed.options.fixBranch ?? "chore/rainy-updates";
             result.summary.fixCommitSha = "";
@@ -85,6 +86,13 @@ async function main() {
         if (parsed.options.format === "json" || parsed.options.format === "metrics") {
             rendered = renderResult(result, parsed.options.format);
         }
+        if (parsed.options.onlyChanged &&
+            result.updates.length === 0 &&
+            result.errors.length === 0 &&
+            result.warnings.length === 0 &&
+            (parsed.options.format === "table" || parsed.options.format === "minimal" || parsed.options.format === "github")) {
+            rendered = "";
+        }
         if (parsed.options.jsonFile) {
             await writeFileAtomic(parsed.options.jsonFile, stableStringify(result, 2) + "\n");
         }
@@ -133,6 +141,11 @@ Options:
   --pr-report-file <path>
   --fail-on none|patch|minor|major|any
   --max-updates <n>
+  --group-by none|name|scope|kind|risk
+  --group-max <n>
+  --cooldown-days <n>
+  --pr-limit <n>
+  --only-changed
   --log-level error|warn|info|debug
   --ci`;
     }
@@ -176,6 +189,36 @@ Options:
   --no-pr-report
   --json-file <path>
   --pr-report-file <path>`;
+    }
+    if (isCommand && command === "ci") {
+        return `rainy-updates ci [options]
+
+Run CI-oriented dependency automation pipeline.
+
+Options:
+  --workspace
+  --mode minimal|strict|enterprise
+  --group-by none|name|scope|kind|risk
+  --group-max <n>
+  --cooldown-days <n>
+  --pr-limit <n>
+  --only-changed
+  --offline
+  --concurrency <n>
+  --fix-pr
+  --fix-branch <name>
+  --fix-commit-message <text>
+  --fix-dry-run
+  --fix-pr-no-checkout
+  --no-pr-report
+  --json-file <path>
+  --github-output <path>
+  --sarif-file <path>
+  --pr-report-file <path>
+  --fail-on none|patch|minor|major|any
+  --max-updates <n>
+  --log-level error|warn|info|debug
+  --ci`;
     }
     if (isCommand && command === "init-ci") {
         return `rainy-updates init-ci [options]
@@ -206,6 +249,7 @@ Options:
 Commands:
   check       Detect available updates
   upgrade     Apply updates to manifests
+  ci          Run CI-focused update pipeline
   warm-cache  Warm local cache for fast/offline checks
   init-ci     Scaffold GitHub Actions workflow
   baseline    Save/check dependency baseline snapshots
@@ -222,6 +266,12 @@ Global options:
   --policy-file <path>
   --fail-on none|patch|minor|major|any
   --max-updates <n>
+  --group-by none|name|scope|kind|risk
+  --group-max <n>
+  --cooldown-days <n>
+  --pr-limit <n>
+  --only-changed
+  --mode minimal|strict|enterprise
   --fix-pr
   --fix-branch <name>
   --fix-commit-message <text>
@@ -243,6 +293,9 @@ async function runCommand(parsed) {
     if (parsed.command === "warm-cache") {
         return await warmCache(parsed.options);
     }
+    if (parsed.command === "ci") {
+        return await runCi(parsed.options);
+    }
     if (parsed.options.fixPr) {
         const upgradeOptions = {
             ...parsed.options,

package/dist/config/loader.d.ts

@@ -1,4 +1,4 @@
-import type { DependencyKind, FailOnLevel, LogLevel, OutputFormat, TargetLevel } from "../types/index.js";
+import type { CiProfile, DependencyKind, FailOnLevel, GroupBy, LogLevel, OutputFormat, TargetLevel } from "../types/index.js";
 export interface FileConfig {
     target?: TargetLevel;
     filter?: string;
@@ -24,6 +24,12 @@ export interface FileConfig {
     fixPrNoCheckout?: boolean;
     noPrReport?: boolean;
     logLevel?: LogLevel;
+    groupBy?: GroupBy;
+    groupMax?: number;
+    cooldownDays?: number;
+    prLimit?: number;
+    onlyChanged?: boolean;
+    ciProfile?: CiProfile;
     install?: boolean;
     packageManager?: "auto" | "npm" | "pnpm";
     sync?: boolean;

package/dist/config/policy.d.ts

@@ -1,6 +1,7 @@
 import type { TargetLevel } from "../types/index.js";
 export interface PolicyConfig {
     ignore?: string[];
+    cooldownDays?: number;
     packageRules?: Record<string, {
         match?: string;
         maxTarget?: TargetLevel;
@@ -8,6 +9,8 @@ export interface PolicyConfig {
         maxUpdatesPerRun?: number;
         cooldownDays?: number;
         allowPrerelease?: boolean;
+        group?: string;
+        priority?: number;
     }>;
 }
 export interface PolicyRule {
@@ -17,9 +20,12 @@ export interface PolicyRule {
     maxUpdatesPerRun?: number;
     cooldownDays?: number;
     allowPrerelease?: boolean;
+    group?: string;
+    priority?: number;
 }
 export interface ResolvedPolicy {
     ignorePatterns: string[];
+    cooldownDays?: number;
     packageRules: Map<string, PolicyRule>;
     matchRules: PolicyRule[];
 }

package/dist/config/policy.js

@@ -12,6 +12,7 @@ export async function loadPolicy(cwd, policyFile) {
             const parsed = JSON.parse(content);
             return {
                 ignorePatterns: parsed.ignore ?? [],
+                cooldownDays: asNonNegativeInt(parsed.cooldownDays),
                 packageRules: new Map(Object.entries(parsed.packageRules ?? {}).map(([pkg, rule]) => [pkg, normalizeRule(rule)])),
                 matchRules: Object.values(parsed.packageRules ?? {})
                     .map((rule) => normalizeRule(rule))
@@ -24,6 +25,7 @@ export async function loadPolicy(cwd, policyFile) {
     }
     return {
         ignorePatterns: [],
+        cooldownDays: undefined,
         packageRules: new Map(),
         matchRules: [],
     };
@@ -42,6 +44,8 @@ function normalizeRule(rule) {
         maxUpdatesPerRun: asNonNegativeInt(rule.maxUpdatesPerRun),
         cooldownDays: asNonNegativeInt(rule.cooldownDays),
         allowPrerelease: rule.allowPrerelease === true,
+        group: typeof rule.group === "string" && rule.group.trim().length > 0 ? rule.group.trim() : undefined,
+        priority: asNonNegativeInt(rule.priority),
     };
 }
 function asNonNegativeInt(value) {

package/dist/core/check.js

@@ -29,6 +29,7 @@ export async function check(options) {
     let totalDependencies = 0;
     const tasks = [];
     let skipped = 0;
+    let cooldownSkipped = 0;
     for (const packageDir of packageDirs) {
         let manifest;
         try {
@@ -67,6 +68,7 @@ export async function check(options) {
             resolvedVersions.set(packageName, {
                 latestVersion: cached.latestVersion,
                 availableVersions: cached.availableVersions,
+                publishedAtByVersion: {},
             });
         }
         else {
@@ -83,6 +85,7 @@ export async function check(options) {
                     resolvedVersions.set(packageName, {
                         latestVersion: stale.latestVersion,
                         availableVersions: stale.availableVersions,
+                        publishedAtByVersion: {},
                     });
                     warnings.push(`Using stale cache for ${packageName} because --offline is enabled.`);
                 }
@@ -103,6 +106,7 @@ export async function check(options) {
                 resolvedVersions.set(packageName, {
                     latestVersion: metadata.latestVersion,
                     availableVersions: metadata.versions,
+                    publishedAtByVersion: metadata.publishedAtByVersion,
                 });
                 if (metadata.latestVersion) {
                     await cache.set(packageName, options.target, metadata.latestVersion, metadata.versions, options.cacheTtlSeconds);
@@ -116,6 +120,7 @@ export async function check(options) {
                     resolvedVersions.set(packageName, {
                         latestVersion: stale.latestVersion,
                         availableVersions: stale.availableVersions,
+                        publishedAtByVersion: {},
                     });
                     warnings.push(`Using stale cache for ${packageName} due to registry error: ${error}`);
                 }
@@ -135,6 +140,10 @@ export async function check(options) {
         const picked = pickTargetVersionFromAvailable(task.dependency.range, metadata.availableVersions, metadata.latestVersion, effectiveTarget);
         if (!picked)
             continue;
+        if (shouldSkipByCooldown(picked, metadata.publishedAtByVersion, options.cooldownDays, policy.cooldownDays, rule?.cooldownDays)) {
+            cooldownSkipped += 1;
+            continue;
+        }
         const nextRange = applyRangeStyle(task.dependency.range, picked);
         if (nextRange === task.dependency.range)
             continue;
@@ -150,7 +159,14 @@ export async function check(options) {
             reason: rule?.maxTarget ? `policy maxTarget=${rule.maxTarget}` : undefined,
         });
     }
-    const limitedUpdates = sortUpdates(applyRuleUpdateCaps(updates, policy));
+    const grouped = groupUpdates(updates, options.groupBy);
+    const groupedUpdates = grouped.length;
+    const groupedSorted = sortUpdates(grouped.flatMap((group) => group.items));
+    const groupedCapped = typeof options.groupMax === "number" ? groupedSorted.slice(0, options.groupMax) : groupedSorted;
+    const ruleLimited = applyRuleUpdateCaps(groupedCapped, policy);
+    const prLimited = typeof options.prLimit === "number" ? ruleLimited.slice(0, options.prLimit) : ruleLimited;
+    const limitedUpdates = sortUpdates(prLimited);
+    const prLimitHit = typeof options.prLimit === "number" && groupedSorted.length > options.prLimit;
     const sortedErrors = [...errors].sort((a, b) => a.localeCompare(b));
     const sortedWarnings = [...warnings].sort((a, b) => a.localeCompare(b));
     const summary = finalizeSummary(createSummary({
@@ -169,6 +185,10 @@ export async function check(options) {
             registryMs,
             cacheMs,
         },
+        groupedUpdates,
+        cooldownSkipped,
+        ciProfile: options.ciProfile,
+        prLimitHit,
     }));
     return {
         projectPath: options.cwd,
@@ -182,6 +202,51 @@ export async function check(options) {
         warnings: sortedWarnings,
     };
 }
+function groupUpdates(updates, groupBy) {
+    if (updates.length === 0) {
+        return [];
+    }
+    if (groupBy === "none") {
+        return [{ key: "all", items: [...updates] }];
+    }
+    const byGroup = new Map();
+    for (const update of updates) {
+        const key = groupKey(update, groupBy);
+        const current = byGroup.get(key) ?? [];
+        current.push(update);
+        byGroup.set(key, current);
+    }
+    return Array.from(byGroup.entries())
+        .map(([key, items]) => ({ key, items: sortUpdates(items) }))
+        .sort((left, right) => left.key.localeCompare(right.key));
+}
+function groupKey(update, groupBy) {
+    if (groupBy === "name")
+        return update.name;
+    if (groupBy === "kind")
+        return update.kind;
+    if (groupBy === "risk")
+        return update.diffType;
+    if (groupBy === "scope") {
+        if (update.name.startsWith("@")) {
+            const slash = update.name.indexOf("/");
+            if (slash > 1)
+                return update.name.slice(0, slash);
+        }
+        return "unscoped";
+    }
+    return "all";
+}
+function shouldSkipByCooldown(pickedVersion, publishedAtByVersion, optionCooldownDays, policyCooldownDays, ruleCooldownDays) {
+    const cooldownDays = ruleCooldownDays ?? optionCooldownDays ?? policyCooldownDays;
+    if (typeof cooldownDays !== "number" || cooldownDays <= 0)
+        return false;
+    const publishedAt = publishedAtByVersion[pickedVersion];
+    if (typeof publishedAt !== "number" || !Number.isFinite(publishedAt))
+        return false;
+    const threshold = Date.now() - cooldownDays * 24 * 60 * 60 * 1000;
+    return publishedAt > threshold;
+}
 function applyRuleUpdateCaps(updates, policy) {
     const limited = [];
     const seenPerPackage = new Map();

package/dist/core/ci.d.ts

@@ -0,0 +1,2 @@
+import type { CheckOptions, CheckResult } from "../types/index.js";
+export declare function runCi(options: CheckOptions): Promise<CheckResult>;

package/dist/core/ci.js

@@ -0,0 +1,30 @@
+import { check } from "./check.js";
+import { warmCache } from "./warm-cache.js";
+import { upgrade } from "./upgrade.js";
+export async function runCi(options) {
+    const profile = options.ciProfile;
+    if (profile !== "minimal") {
+        await warmCache({
+            ...options,
+            offline: false,
+            ci: true,
+            format: "minimal",
+        });
+    }
+    const checkOptions = {
+        ...options,
+        ci: true,
+        offline: profile === "minimal" ? options.offline : true,
+        concurrency: profile === "enterprise" ? Math.max(options.concurrency, 32) : options.concurrency,
+    };
+    if (options.fixPr) {
+        const upgradeOptions = {
+            ...checkOptions,
+            install: false,
+            packageManager: "auto",
+            sync: false,
+        };
+        return await upgrade(upgradeOptions);
+    }
+    return await check(checkOptions);
+}

package/dist/core/init-ci.js

@@ -46,14 +46,14 @@ function installStep(packageManager) {
     return `      - name: Install dependencies\n        run: npm ci`;
 }
 function minimalWorkflowTemplate(scheduleBlock, packageManager) {
-    return `name: Rainy Updates\n\non:\n${scheduleBlock}\n\njobs:\n  dependency-check:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n\n      - name: Setup Node\n        uses: actions/setup-node@v4\n        with:\n          node-version: '20'\n\n${installStep(packageManager)}\n\n      - name: Run dependency check\n        run: |\n          npx @rainy-updates/cli check \\\n            --workspace \\\n            --ci \\\n            --format table\n`;
+    return `name: Rainy Updates\n\non:\n${scheduleBlock}\n\njobs:\n  dependency-check:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n\n      - name: Setup Node\n        uses: actions/setup-node@v4\n        with:\n          node-version: '20'\n\n${installStep(packageManager)}\n\n      - name: Run dependency check\n        run: |\n          npx @rainy-updates/cli ci \\\n            --workspace \\\n            --mode minimal \\\n            --ci \\\n            --format table\n`;
 }
 function strictWorkflowTemplate(scheduleBlock, packageManager) {
-    return `name: Rainy Updates\n\non:\n${scheduleBlock}\n\npermissions:\n  contents: read\n  security-events: write\n\njobs:\n  dependency-check:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n\n      - name: Setup Node\n        uses: actions/setup-node@v4\n        with:\n          node-version: '20'\n\n${installStep(packageManager)}\n\n      - name: Warm cache\n        run: npx @rainy-updates/cli warm-cache --workspace --concurrency 32\n\n      - name: Run strict dependency check\n        run: |\n          npx @rainy-updates/cli check \\\n            --workspace \\\n            --offline \\\n            --ci \\\n            --concurrency 32 \\\n            --format github \\\n            --json-file .artifacts/deps-report.json \\\n            --pr-report-file .artifacts/deps-report.md \\\n            --sarif-file .artifacts/deps-report.sarif \\\n            --github-output $GITHUB_OUTPUT\n\n      - name: Upload report artifacts\n        uses: actions/upload-artifact@v4\n        with:\n          name: rainy-updates-report\n          path: .artifacts/\n\n      - name: Upload SARIF\n        uses: github/codeql-action/upload-sarif@v3\n        with:\n          sarif_file: .artifacts/deps-report.sarif\n`;
+    return `name: Rainy Updates\n\non:\n${scheduleBlock}\n\npermissions:\n  contents: read\n  security-events: write\n\njobs:\n  dependency-check:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n\n      - name: Setup Node\n        uses: actions/setup-node@v4\n        with:\n          node-version: '20'\n\n${installStep(packageManager)}\n\n      - name: Warm cache\n        run: npx @rainy-updates/cli warm-cache --workspace --concurrency 32\n\n      - name: Run strict dependency check\n        run: |\n          npx @rainy-updates/cli ci \\\n            --workspace \\\n            --mode strict \\\n            --ci \\\n            --concurrency 32 \\\n            --format github \\\n            --json-file .artifacts/deps-report.json \\\n            --pr-report-file .artifacts/deps-report.md \\\n            --sarif-file .artifacts/deps-report.sarif \\\n            --github-output $GITHUB_OUTPUT\n\n      - name: Upload report artifacts\n        uses: actions/upload-artifact@v4\n        with:\n          name: rainy-updates-report\n          path: .artifacts/\n\n      - name: Upload SARIF\n        uses: github/codeql-action/upload-sarif@v3\n        with:\n          sarif_file: .artifacts/deps-report.sarif\n`;
 }
 function enterpriseWorkflowTemplate(scheduleBlock, packageManager) {
     const detectedPmInstall = packageManager === "pnpm"
         ? "corepack enable && corepack prepare pnpm@9 --activate && pnpm install --frozen-lockfile"
         : "npm ci";
-    return `name: Rainy Updates Enterprise\n\non:\n${scheduleBlock}\n\npermissions:\n  contents: read\n  security-events: write\n  actions: read\n\nconcurrency:\n  group: rainy-updates-\${{ github.ref }}\n  cancel-in-progress: false\n\njobs:\n  dependency-check:\n    runs-on: ubuntu-latest\n    strategy:\n      fail-fast: false\n      matrix:\n        node: [20, 22]\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n\n      - name: Setup Node\n        uses: actions/setup-node@v4\n        with:\n          node-version: \${{ matrix.node }}\n\n      - name: Install dependencies\n        run: ${detectedPmInstall}\n\n      - name: Warm cache\n        run: npx @rainy-updates/cli warm-cache --workspace --concurrency 32\n\n      - name: Check updates with rollout controls\n        run: |\n          npx @rainy-updates/cli check \\\n            --workspace \\\n            --offline \\\n            --concurrency 32 \\\n            --format github \\\n            --fail-on minor \\\n            --max-updates 50 \\\n            --json-file .artifacts/deps-report-node-\${{ matrix.node }}.json \\\n            --pr-report-file .artifacts/deps-report-node-\${{ matrix.node }}.md \\\n            --sarif-file .artifacts/deps-report-node-\${{ matrix.node }}.sarif \\\n            --github-output $GITHUB_OUTPUT\n\n      - name: Upload report artifacts\n        uses: actions/upload-artifact@v4\n        with:\n          name: rainy-updates-report-node-\${{ matrix.node }}\n          path: .artifacts/\n          retention-days: 14\n\n      - name: Upload SARIF\n        uses: github/codeql-action/upload-sarif@v3\n        with:\n          sarif_file: .artifacts/deps-report-node-\${{ matrix.node }}.sarif\n`;
+    return `name: Rainy Updates Enterprise\n\non:\n${scheduleBlock}\n\npermissions:\n  contents: read\n  security-events: write\n  actions: read\n\nconcurrency:\n  group: rainy-updates-\${{ github.ref }}\n  cancel-in-progress: false\n\njobs:\n  dependency-check:\n    runs-on: ubuntu-latest\n    strategy:\n      fail-fast: false\n      matrix:\n        node: [20, 22]\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n\n      - name: Setup Node\n        uses: actions/setup-node@v4\n        with:\n          node-version: \${{ matrix.node }}\n\n      - name: Install dependencies\n        run: ${detectedPmInstall}\n\n      - name: Warm cache\n        run: npx @rainy-updates/cli warm-cache --workspace --concurrency 32\n\n      - name: Check updates with rollout controls\n        run: |\n          npx @rainy-updates/cli ci \\\n            --workspace \\\n            --mode enterprise \\\n            --concurrency 32 \\\n            --format github \\\n            --fail-on minor \\\n            --max-updates 50 \\\n            --json-file .artifacts/deps-report-node-\${{ matrix.node }}.json \\\n            --pr-report-file .artifacts/deps-report-node-\${{ matrix.node }}.md \\\n            --sarif-file .artifacts/deps-report-node-\${{ matrix.node }}.sarif \\\n            --github-output $GITHUB_OUTPUT\n\n      - name: Upload report artifacts\n        uses: actions/upload-artifact@v4\n        with:\n          name: rainy-updates-report-node-\${{ matrix.node }}\n          path: .artifacts/\n          retention-days: 14\n\n      - name: Upload SARIF\n        uses: github/codeql-action/upload-sarif@v3\n        with:\n          sarif_file: .artifacts/deps-report-node-\${{ matrix.node }}.sarif\n`;
 }

package/dist/core/options.d.ts

@@ -9,6 +9,9 @@ export type ParsedCliArgs = {
 } | {
     command: "warm-cache";
     options: CheckOptions;
+} | {
+    command: "ci";
+    options: CheckOptions;
 } | {
     command: "init-ci";
     options: {

package/dist/core/options.js

@@ -7,7 +7,7 @@ const DEFAULT_INCLUDE_KINDS = [
     "optionalDependencies",
     "peerDependencies",
 ];
-const KNOWN_COMMANDS = ["check", "upgrade", "warm-cache", "init-ci", "baseline"];
+const KNOWN_COMMANDS = ["check", "upgrade", "warm-cache", "init-ci", "baseline", "ci"];
 export async function parseCliArgs(argv) {
     const firstArg = argv[0];
     const isKnownCommand = KNOWN_COMMANDS.includes(firstArg);
@@ -43,6 +43,12 @@ export async function parseCliArgs(argv) {
         fixPrNoCheckout: false,
         noPrReport: false,
         logLevel: "info",
+        groupBy: "none",
+        groupMax: undefined,
+        cooldownDays: undefined,
+        prLimit: undefined,
+        onlyChanged: false,
+        ciProfile: "minimal",
     };
     let force = false;
     let initCiMode = "enterprise";
@@ -237,7 +243,12 @@ export async function parseCliArgs(argv) {
             throw new Error("Missing value for --pm");
         }
         if (current === "--mode" && next) {
-            initCiMode = ensureInitCiMode(next);
+            if (command === "init-ci") {
+                initCiMode = ensureInitCiMode(next);
+            }
+            else {
+                base.ciProfile = ensureCiProfile(next);
+            }
             index += 1;
             continue;
         }
@@ -280,6 +291,54 @@ export async function parseCliArgs(argv) {
         if (current === "--max-updates") {
             throw new Error("Missing value for --max-updates");
         }
+        if (current === "--group-by" && next) {
+            base.groupBy = ensureGroupBy(next);
+            index += 1;
+            continue;
+        }
+        if (current === "--group-by") {
+            throw new Error("Missing value for --group-by");
+        }
+        if (current === "--group-max" && next) {
+            const parsed = Number(next);
+            if (!Number.isInteger(parsed) || parsed < 1) {
+                throw new Error("--group-max must be a positive integer");
+            }
+            base.groupMax = parsed;
+            index += 1;
+            continue;
+        }
+        if (current === "--group-max") {
+            throw new Error("Missing value for --group-max");
+        }
+        if (current === "--cooldown-days" && next) {
+            const parsed = Number(next);
+            if (!Number.isInteger(parsed) || parsed < 0) {
+                throw new Error("--cooldown-days must be a non-negative integer");
+            }
+            base.cooldownDays = parsed;
+            index += 1;
+            continue;
+        }
+        if (current === "--cooldown-days") {
+            throw new Error("Missing value for --cooldown-days");
+        }
+        if (current === "--pr-limit" && next) {
+            const parsed = Number(next);
+            if (!Number.isInteger(parsed) || parsed < 1) {
+                throw new Error("--pr-limit must be a positive integer");
+            }
+            base.prLimit = parsed;
+            index += 1;
+            continue;
+        }
+        if (current === "--pr-limit") {
+            throw new Error("Missing value for --pr-limit");
+        }
+        if (current === "--only-changed") {
+            base.onlyChanged = true;
+            continue;
+        }
         if (current === "--save") {
             baselineAction = "save";
             continue;
@@ -336,6 +395,9 @@ export async function parseCliArgs(argv) {
     if (command === "warm-cache") {
         return { command, options: base };
     }
+    if (command === "ci") {
+        return { command, options: base };
+    }
     if (command === "init-ci") {
         return {
             command,
@@ -429,6 +491,24 @@ function applyConfig(base, config) {
     if (typeof config.logLevel === "string") {
         base.logLevel = ensureLogLevel(config.logLevel);
     }
+    if (typeof config.groupBy === "string") {
+        base.groupBy = ensureGroupBy(config.groupBy);
+    }
+    if (typeof config.groupMax === "number" && Number.isInteger(config.groupMax) && config.groupMax > 0) {
+        base.groupMax = config.groupMax;
+    }
+    if (typeof config.cooldownDays === "number" && Number.isInteger(config.cooldownDays) && config.cooldownDays >= 0) {
+        base.cooldownDays = config.cooldownDays;
+    }
+    if (typeof config.prLimit === "number" && Number.isInteger(config.prLimit) && config.prLimit > 0) {
+        base.prLimit = config.prLimit;
+    }
+    if (typeof config.onlyChanged === "boolean") {
+        base.onlyChanged = config.onlyChanged;
+    }
+    if (typeof config.ciProfile === "string") {
+        base.ciProfile = ensureCiProfile(config.ciProfile);
+    }
 }
 function parsePackageManager(args) {
     const index = args.indexOf("--pm");
@@ -497,3 +577,15 @@ function ensureFailOn(value) {
     }
     throw new Error("--fail-on must be none, patch, minor, major or any");
 }
+function ensureGroupBy(value) {
+    if (value === "none" || value === "name" || value === "scope" || value === "kind" || value === "risk") {
+        return value;
+    }
+    throw new Error("--group-by must be none, name, scope, kind or risk");
+}
+function ensureCiProfile(value) {
+    if (value === "minimal" || value === "strict" || value === "enterprise") {
+        return value;
+    }
+    throw new Error("--mode must be minimal, strict or enterprise");
+}

package/dist/core/summary.d.ts

@@ -16,6 +16,10 @@ export declare function createSummary(input: {
     errors: string[];
     warnings: string[];
     durations: DurationInput;
+    groupedUpdates?: number;
+    cooldownSkipped?: number;
+    ciProfile?: Summary["ciProfile"];
+    prLimitHit?: boolean;
 }): 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;

package/dist/core/summary.js

@@ -33,6 +33,10 @@ export function createSummary(input) {
         fixPrApplied: false,
         fixBranchName: "",
         fixCommitSha: "",
+        groupedUpdates: Math.max(0, Math.round(input.groupedUpdates ?? 0)),
+        cooldownSkipped: Math.max(0, Math.round(input.cooldownSkipped ?? 0)),
+        ciProfile: input.ciProfile ?? "minimal",
+        prLimitHit: input.prLimitHit === true,
     };
 }
 export function finalizeSummary(summary) {

package/dist/core/warm-cache.js

@@ -102,6 +102,7 @@ export async function warmCache(options) {
             registryMs,
             cacheMs,
         },
+        ciProfile: options.ciProfile,
     }));
     return {
         projectPath: options.cwd,

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export { check } from "./core/check.js";
 export { upgrade } from "./core/upgrade.js";
 export { warmCache } from "./core/warm-cache.js";
+export { runCi } from "./core/ci.js";
 export { initCiWorkflow } from "./core/init-ci.js";
 export { saveBaseline, diffBaseline } from "./core/baseline.js";
 export { createSarifReport } from "./output/sarif.js";
 export { writeGitHubOutput, renderGitHubAnnotations } from "./output/github.js";
 export { renderPrReport } from "./output/pr-report.js";
-export type { CheckOptions, CheckResult, DependencyKind, FailOnLevel, OutputFormat, PackageUpdate, RunOptions, TargetLevel, UpgradeOptions, UpgradeResult, } from "./types/index.js";
+export type { CheckOptions, CheckResult, CiProfile, DependencyKind, FailOnLevel, GroupBy, OutputFormat, PackageUpdate, RunOptions, TargetLevel, UpgradeOptions, UpgradeResult, } from "./types/index.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 export { check } from "./core/check.js";
 export { upgrade } from "./core/upgrade.js";
 export { warmCache } from "./core/warm-cache.js";
+export { runCi } from "./core/ci.js";
 export { initCiWorkflow } from "./core/init-ci.js";
 export { saveBaseline, diffBaseline } from "./core/baseline.js";
 export { createSarifReport } from "./output/sarif.js";

package/dist/output/format.js

@@ -32,6 +32,10 @@ export function renderResult(result, format) {
             `duration_registry_ms=${result.summary.durationMs.registry}`,
             `duration_cache_ms=${result.summary.durationMs.cache}`,
             `duration_render_ms=${result.summary.durationMs.render}`,
+            `grouped_updates=${result.summary.groupedUpdates}`,
+            `cooldown_skipped=${result.summary.cooldownSkipped}`,
+            `ci_profile=${result.summary.ciProfile}`,
+            `pr_limit_hit=${result.summary.prLimitHit ? "1" : "0"}`,
         ].join("\n");
     }
     const lines = [];
@@ -70,6 +74,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(`Groups=${result.summary.groupedUpdates}, cooldownSkipped=${result.summary.cooldownSkipped}, ciProfile=${result.summary.ciProfile}, prLimitHit=${result.summary.prLimitHit ? "yes" : "no"}`);
     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

@@ -14,6 +14,10 @@ export async function writeGitHubOutput(filePath, result) {
         `duration_registry_ms=${result.summary.durationMs.registry}`,
         `duration_cache_ms=${result.summary.durationMs.cache}`,
         `duration_render_ms=${result.summary.durationMs.render}`,
+        `grouped_updates=${result.summary.groupedUpdates}`,
+        `cooldown_skipped=${result.summary.cooldownSkipped}`,
+        `ci_profile=${result.summary.ciProfile}`,
+        `pr_limit_hit=${result.summary.prLimitHit === true ? "1" : "0"}`,
         `fix_pr_applied=${result.summary.fixPrApplied === true ? "1" : "0"}`,
         `fix_pr_branch=${result.summary.fixBranchName ?? ""}`,
         `fix_pr_commit=${result.summary.fixCommitSha ?? ""}`,

package/dist/output/pr-report.js

@@ -7,6 +7,10 @@ export function renderPrReport(result) {
     lines.push(`- Updates found: ${result.summary.updatesFound}`);
     lines.push(`- Errors: ${result.errors.length}`);
     lines.push(`- Warnings: ${result.warnings.length}`);
+    lines.push(`- Grouped updates: ${result.summary.groupedUpdates}`);
+    lines.push(`- Cooldown skipped: ${result.summary.cooldownSkipped}`);
+    lines.push(`- CI profile: ${result.summary.ciProfile}`);
+    lines.push(`- PR limit hit: ${result.summary.prLimitHit ? "yes" : "no"}`);
     lines.push("");
     if (result.updates.length > 0) {
         lines.push("## Proposed Updates");

package/dist/output/sarif.js

@@ -67,8 +67,12 @@ export function createSarifReport(result) {
                     contractVersion: result.summary.contractVersion,
                     failReason: result.summary.failReason,
                     updatesFound: result.summary.updatesFound,
+                    groupedUpdates: result.summary.groupedUpdates,
+                    cooldownSkipped: result.summary.cooldownSkipped,
                     errorsCount: result.summary.errorCounts.total,
                     warningsCount: result.summary.warningCounts.total,
+                    ciProfile: result.summary.ciProfile,
+                    prLimitHit: result.summary.prLimitHit,
                     durationMs: result.summary.durationMs,
                 },
             },

package/dist/registry/npm.d.ts

@@ -6,6 +6,7 @@ export interface ResolveManyResult {
     metadata: Map<string, {
         latestVersion: string | null;
         versions: string[];
+        publishedAtByVersion: Record<string, number>;
     }>;
     errors: Map<string, string>;
 }
@@ -15,6 +16,7 @@ export declare class NpmRegistryClient {
     resolvePackageMetadata(packageName: string, timeoutMs?: number): Promise<{
         latestVersion: string | null;
         versions: string[];
+        publishedAtByVersion: Record<string, number>;
     }>;
     resolveLatestVersion(packageName: string, timeoutMs?: number): Promise<string | null>;
     resolveManyPackageMetadata(packageNames: string[], options: ResolveManyOptions): Promise<ResolveManyResult>;

package/dist/registry/npm.js

@@ -18,7 +18,7 @@ export class NpmRegistryClient {
             try {
                 const response = await requester(packageName, timeoutMs);
                 if (response.status === 404) {
-                    return { latestVersion: null, versions: [] };
+                    return { latestVersion: null, versions: [], publishedAtByVersion: {} };
                 }
                 if (response.status === 429 || response.status >= 500) {
                     throw new RetryableRegistryError(`Registry temporary error: ${response.status}`, response.retryAfterMs ?? computeBackoffMs(attempt));
@@ -27,7 +27,11 @@ export class NpmRegistryClient {
                     throw new Error(`Registry request failed: ${response.status}`);
                 }
                 const versions = Object.keys(response.data?.versions ?? {});
-                return { latestVersion: response.data?.["dist-tags"]?.latest ?? null, versions };
+                return {
+                    latestVersion: response.data?.["dist-tags"]?.latest ?? null,
+                    versions,
+                    publishedAtByVersion: extractPublishTimes(response.data?.time),
+                };
             }
             catch (error) {
                 lastError = String(error);
@@ -262,3 +266,17 @@ function parseRetryAfterHeader(value) {
         return 0;
     return delta;
 }
+function extractPublishTimes(timeMap) {
+    if (!timeMap)
+        return {};
+    const publishedAtByVersion = {};
+    for (const [version, rawDate] of Object.entries(timeMap)) {
+        if (version === "created" || version === "modified")
+            continue;
+        const timestamp = Date.parse(rawDate);
+        if (Number.isFinite(timestamp)) {
+            publishedAtByVersion[version] = timestamp;
+        }
+    }
+    return publishedAtByVersion;
+}

package/dist/types/index.d.ts

@@ -1,5 +1,7 @@
 export type DependencyKind = "dependencies" | "devDependencies" | "optionalDependencies" | "peerDependencies";
 export type TargetLevel = "patch" | "minor" | "major" | "latest";
+export type GroupBy = "none" | "name" | "scope" | "kind" | "risk";
+export type CiProfile = "minimal" | "strict" | "enterprise";
 export type OutputFormat = "table" | "json" | "minimal" | "github" | "metrics";
 export type FailOnLevel = "none" | "patch" | "minor" | "major" | "any";
 export type LogLevel = "error" | "warn" | "info" | "debug";
@@ -30,6 +32,12 @@ export interface RunOptions {
     fixPrNoCheckout?: boolean;
     noPrReport?: boolean;
     logLevel: LogLevel;
+    groupBy: GroupBy;
+    groupMax?: number;
+    cooldownDays?: number;
+    prLimit?: number;
+    onlyChanged: boolean;
+    ciProfile: CiProfile;
 }
 export interface CheckOptions extends RunOptions {
 }
@@ -92,6 +100,10 @@ export interface Summary {
     fixPrApplied: boolean;
     fixBranchName: string;
     fixCommitSha: string;
+    groupedUpdates: number;
+    cooldownSkipped: number;
+    ciProfile: CiProfile;
+    prLimitHit: boolean;
 }
 export interface CheckResult {
     projectPath: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainy-updates/cli",
-  "version": "0.5.0",
+  "version": "0.5.1-rc.1",
   "description": "Agentic CLI to check and upgrade npm/pnpm dependencies for CI workflows",
   "type": "module",
   "private": false,