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

package/CHANGELOG.md

@@ -2,6 +2,58 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.5.0-rc.1] - 2026-02-27
+
+### Added
+
+- New CI rollout controls:
+  - `--fail-on none|patch|minor|major|any`
+  - `--max-updates <n>`
+- New baseline workflow command:
+  - `baseline --save --file <path>` to snapshot dependency state
+  - `baseline --check --file <path>` to detect dependency drift
+- New `init-ci --mode enterprise` template:
+  - Node runtime matrix (`20`, `22`)
+  - stricter default permissions
+  - artifact retention policy
+  - built-in rollout gate flags (`--fail-on`, `--max-updates`)
+
+### Changed
+
+- Dependency target selection now evaluates available package versions from registry metadata, improving `patch|minor|major` accuracy.
+- CLI parser now rejects unknown options and missing option values with explicit errors (safer CI behavior).
+- SARIF output now reports the actual package version dynamically.
+
+### Tests
+
+- Added baseline snapshot/diff tests.
+- Added enterprise workflow generation tests.
+- Added semver target selection tests using available version sets.
+- Added parser tests for baseline command, rollout flags, and unknown option rejection.
+
+## [0.4.4] - 2026-02-27
+
+### Changed
+
+- Version bump to `0.4.4` for production stabilization.
+- Simplified public documentation to focus on end-user CLI usage.
+- Removed user-facing instructions for GitHub Actions configuration from README.
+
+### Fixed
+
+- Removed optional `better-sqlite3` dependency to avoid deprecated native install warnings (`prebuild-install`).
+- Cache backend now uses `bun:sqlite` when available and falls back cleanly to file-based cache without native Node addons.
+
+### Added
+
+- `SECURITY.md` with vulnerability disclosure guidance.
+- `CODE_OF_CONDUCT.md` for OSS community standards.
+- Automatic CI bootstrap improvements in `init-ci`:
+  - `--mode minimal|strict`
+  - `--schedule weekly|daily|off`
+  - package-manager-aware install step generation (npm/pnpm)
+
+
 ## [0.4.0] - 2026-02-27
 
 ### Added
@@ -126,7 +178,7 @@ All notable changes to this project are documented in this file.
   - `--dep-kinds deps,dev,optional,peer`
 - Runtime controls:
   - `--concurrency` for parallel dependency checks.
-  - `--cache-ttl` for cache freshness tuning.
+- `--cache-ttl` for cache freshness tuning.
 - Cache layer improvements:
   - SQLite-first cache backend when available.
   - JSON fallback cache backend.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Code of Conduct
+
+## Our Standards
+
+We are committed to a respectful, inclusive, and harassment-free community.
+
+Expected behavior:
+
+- be respectful and constructive
+- focus on technical issues, not personal attacks
+- welcome feedback and different viewpoints
+
+Unacceptable behavior:
+
+- harassment, discrimination, or abusive language
+- doxxing or threats
+- trolling and persistent disruption
+
+## Enforcement
+
+Project maintainers are responsible for clarifying and enforcing this code of conduct.
+
+## Reporting
+
+Report unacceptable behavior through private communication with maintainers or GitHub moderation tools.

package/README.md

@@ -1,6 +1,16 @@
 # @rainy-updates/cli
 
-Agentic OSS CLI for dependency updates focused on speed, CI automation, and workspace-scale maintenance.
+Agentic CLI to detect, control, and apply dependency updates across npm/pnpm projects and monorepos.
+
+`@rainy-updates/cli` is built for teams that need fast dependency intelligence, policy-aware upgrades, and automation-ready output for CI/CD and pull request workflows.
+
+## Why this package
+
+- Detects updates quickly across single-package repos and workspaces.
+- Applies updates safely with configurable targets (`patch`, `minor`, `major`, `latest`).
+- Enforces policy rules per package (ignore rules and max upgrade level).
+- Supports offline and cache-warmed execution for deterministic CI runs.
+- Produces machine-readable artifacts (JSON, SARIF, GitHub outputs, PR markdown report).
 
 ## Install
 
@@ -10,64 +20,58 @@ npm i -D @rainy-updates/cli
 pnpm add -D @rainy-updates/cli
 ```
 
-## Commands
+## Core commands
 
-- `check`: detect available dependency updates.
-- `upgrade`: rewrite dependency ranges (optional install + workspace sync).
-- `warm-cache`: pre-fetch package metadata into local cache for faster CI checks.
-- `init-ci`: scaffold `.github/workflows/rainy-updates.yml`.
+- `check`: analyze dependencies and report available updates.
+- `upgrade`: rewrite dependency ranges in manifests, optionally install lockfile updates.
+- `warm-cache`: prefetch package metadata for fast and offline checks.
+- `baseline`: save and compare dependency baseline snapshots.
 
-## Quick start
+## Quick usage
 
 ```bash
-# check and fail CI if updates are found
-npx @rainy-updates/cli check --ci --format json --json-file .artifacts/deps-report.json
+# 1) Detect updates
+npx @rainy-updates/cli check --format table
 
-# pre-warm cache before strict offline checks
-npx @rainy-updates/cli warm-cache --workspace --concurrency 32
-npx @rainy-updates/cli check --workspace --offline --ci
+# 2) Strict CI mode (non-zero when updates exist)
+npx @rainy-updates/cli check --workspace --ci --format json --json-file .artifacts/updates.json
 
-# upgrade ranges and install lockfiles
+# 3) Apply upgrades with workspace sync
 npx @rainy-updates/cli upgrade --target latest --workspace --sync --install
 
-# scaffold GitHub Actions workflow
-npx @rainy-updates/cli init-ci
+# 4) Warm cache for deterministic offline checks
+npx @rainy-updates/cli warm-cache --workspace --concurrency 32
+npx @rainy-updates/cli check --workspace --offline --ci
+
+# 5) Save and compare baseline drift in CI
+npx @rainy-updates/cli baseline --save --file .artifacts/deps-baseline.json --workspace
+npx @rainy-updates/cli baseline --check --file .artifacts/deps-baseline.json --workspace --ci
 ```
 
-## Core options
+## What it does in production
 
-- `--target patch|minor|major|latest`
-- `--filter <pattern>`
-- `--reject <pattern>`
-- `--dep-kinds deps,dev,optional,peer`
-- `--workspace`
-- `--concurrency <n>`
-- `--cache-ttl <seconds>`
-- `--offline` (cache-only mode)
-- `--cwd <path>`
+### Update detection engine
 
-## Output options
+- Scans dependency groups: `dependencies`, `devDependencies`, `optionalDependencies`, `peerDependencies`.
+- Resolves versions per unique package to reduce duplicate network requests.
+- Uses network concurrency controls and resilient retries.
+- Supports stale-cache fallback when registry calls fail.
 
-- `--format table|json|minimal|github`
-- `--json-file <path>`
-- `--github-output <path>`
-- `--sarif-file <path>`
-- `--pr-report-file <path>` (generates markdown report for PR comments)
+### Workspace support
 
-## Upgrade options
+- Detects package workspaces from:
+  - `package.json` workspaces
+  - `pnpm-workspace.yaml`
+- Handles multi-manifest upgrade flows.
+- Graph-aware sync mode (`--sync`) avoids breaking `workspace:*` references.
 
-- `--install`
-- `--pm auto|npm|pnpm`
-- `--sync` (graph-aware version alignment across workspace packages)
-
-## Policy controls
+### Policy-aware control
 
-- `--policy-file <path>` to apply package-level policy rules.
-- default policy discovery:
-  - `.rainyupdates-policy.json`
-  - `rainy-updates.policy.json`
+- Apply global ignore patterns.
+- Apply package-specific rules.
+- Enforce max upgrade target per package (for safer rollout).
 
-Policy example:
+Example policy file:
 
 ```json
 {
@@ -79,63 +83,127 @@ Policy example:
 }
 ```
 
-## CLI help
+Use it with:
 
 ```bash
-rainy-updates --help
-rainy-updates <command> --help
-rainy-updates --version
+npx @rainy-updates/cli check --policy-file .rainyupdates-policy.json
 ```
 
-## CI behavior
+## Output and reporting
 
-- `--ci`: returns exit code `1` when updates are found.
-- returns exit code `2` for operational errors (registry/IO/runtime failures).
+### Human output
 
-## Config files
+- `--format table`
+- `--format minimal`
 
-Supported:
+### Automation output
 
-- `.rainyupdatesrc`
-- `.rainyupdatesrc.json`
-- `package.json` -> `rainyUpdates`
+- `--format json`
+- `--json-file <path>`
+- `--sarif-file <path>`
+- `--github-output <path>`
+- `--pr-report-file <path>`
 
-Example:
+These outputs are designed for CI pipelines, security tooling, and PR review automation.
 
-```json
-{
-  "rainyUpdates": {
-    "target": "minor",
-    "workspace": true,
-    "concurrency": 24,
-    "offline": false,
-    "format": "json",
-    "cacheTtlSeconds": 1800,
-    "jsonFile": ".artifacts/deps.json",
-    "sarifFile": ".artifacts/deps.sarif",
-    "prReportFile": ".artifacts/deps.md",
-    "policyFile": ".rainyupdates-policy.json"
-  }
-}
+
+## Automatic CI bootstrap
+
+Generate a workflow in the target project automatically:
+
+```bash
+# strict mode (recommended)
+npx @rainy-updates/cli init-ci --mode enterprise --schedule weekly
+
+# lightweight mode
+npx @rainy-updates/cli init-ci --mode minimal --schedule daily
 ```
 
-## Production release
+Generated file:
+
+- `.github/workflows/rainy-updates.yml`
+
+Modes:
+
+- `strict`: warm-cache + offline check + artifacts + SARIF upload.
+- `enterprise`: strict checks + runtime matrix + retention policy + rollout gates.
+- `minimal`: fast check-only workflow for quick adoption.
+
+Schedule:
+
+- `weekly`, `daily`, or `off` (manual dispatch only).
+
+## Command options
+
+### Global
+
+- `--cwd <path>`
+- `--workspace`
+- `--target patch|minor|major|latest`
+- `--filter <pattern>`
+- `--reject <pattern>`
+- `--dep-kinds deps,dev,optional,peer`
+- `--concurrency <n>`
+- `--cache-ttl <seconds>`
+- `--offline`
+- `--fail-on none|patch|minor|major|any`
+- `--max-updates <n>`
+- `--policy-file <path>`
+- `--format table|json|minimal|github`
+- `--json-file <path>`
+- `--github-output <path>`
+- `--sarif-file <path>`
+- `--pr-report-file <path>`
+- `--ci`
+
+### Upgrade-only
+
+- `--install`
+- `--pm auto|npm|pnpm`
+- `--sync`
+
+### Baseline-only
+
+- `--save`
+- `--check`
+- `--file <path>`
+
+## Config support
+
+Configuration can be loaded from:
+
+- `.rainyupdatesrc`
+- `.rainyupdatesrc.json`
+- `package.json` field: `rainyUpdates`
+
+## CLI help
 
 ```bash
-bun run prepublishOnly
-node scripts/release-preflight.mjs
-npm publish --provenance --access public
+rainy-updates --help
+rainy-updates <command> --help
+rainy-updates --version
 ```
 
-If publishing in GitHub Actions, set `NPM_TOKEN` in repository secrets.
+## Reliability characteristics
+
+- Node.js 20+ runtime.
+- Works with npm and pnpm workflows.
+- Uses optional `undici` pool path for high-throughput HTTP.
+- Cache-first architecture for speed and resilience.
+
+## CI/CD included
+
+This package ships with production CI/CD pipelines in the repository:
+
+- Continuous integration pipeline for typecheck, tests, build, and production smoke checks.
+- Tag-driven release pipeline for npm publishing with provenance.
+- Release preflight validation for npm auth/scope checks before publishing.
+
 
-The repository includes:
+## Product roadmap
 
-- `.github/workflows/ci.yml` for test/typecheck/build/smoke checks.
-- `.github/workflows/release.yml` for tag-driven npm publishing.
+The long-term roadmap is maintained in [`ROADMAP.md`](./ROADMAP.md).
 
-## Performance and runtime notes
+## License
 
-- Resolves dependency metadata by unique package name to avoid duplicate network calls.
-- Uses `undici` pool with HTTP/2 when available; falls back to native `fetch` automatically.
-- Uses layered cache with stale fallback for resilient CI runs.
+MIT

package/SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are applied to the latest released version.
+
+## Reporting vulnerabilities
+
+Report vulnerabilities privately through GitHub Security Advisories.
+
+Include:
+
+- affected version
+- reproduction steps
+- impact assessment
+- proof-of-concept if available
+
+Do not open public issues for unpatched security vulnerabilities.

package/dist/bin/cli.js

@@ -8,6 +8,7 @@ import { check } from "../core/check.js";
 import { upgrade } from "../core/upgrade.js";
 import { warmCache } from "../core/warm-cache.js";
 import { initCiWorkflow } from "../core/init-ci.js";
+import { diffBaseline, saveBaseline } from "../core/baseline.js";
 import { renderResult } from "../output/format.js";
 import { writeGitHubOutput } from "../output/github.js";
 import { createSarifReport } from "../output/sarif.js";
@@ -25,12 +26,40 @@ async function main() {
         }
         const parsed = await parseCliArgs(argv);
         if (parsed.command === "init-ci") {
-            const workflow = await initCiWorkflow(parsed.options.cwd, parsed.options.force);
+            const workflow = await initCiWorkflow(parsed.options.cwd, parsed.options.force, {
+                mode: parsed.options.mode,
+                schedule: parsed.options.schedule,
+            });
             process.stdout.write(workflow.created
                 ? `Created CI workflow at ${workflow.path}\n`
                 : `CI workflow already exists at ${workflow.path}. Use --force to overwrite.\n`);
             return;
         }
+        if (parsed.command === "baseline") {
+            if (parsed.options.action === "save") {
+                const saved = await saveBaseline(parsed.options);
+                process.stdout.write(`Saved baseline at ${saved.filePath} (${saved.entries} entries)\n`);
+                return;
+            }
+            const diff = await diffBaseline(parsed.options);
+            const changes = diff.added.length + diff.removed.length + diff.changed.length;
+            if (changes === 0) {
+                process.stdout.write(`No baseline drift detected (${diff.filePath}).\n`);
+                return;
+            }
+            process.stdout.write(`Baseline drift detected (${diff.filePath}).\n`);
+            if (diff.added.length > 0) {
+                process.stdout.write(`Added: ${diff.added.length}\n`);
+            }
+            if (diff.removed.length > 0) {
+                process.stdout.write(`Removed: ${diff.removed.length}\n`);
+            }
+            if (diff.changed.length > 0) {
+                process.stdout.write(`Changed: ${diff.changed.length}\n`);
+            }
+            process.exitCode = 1;
+            return;
+        }
         const result = parsed.command === "upgrade"
             ? await upgrade(parsed.options)
             : parsed.command === "warm-cache"
@@ -55,13 +84,7 @@ async function main() {
             await fs.mkdir(path.dirname(parsed.options.sarifFile), { recursive: true });
             await fs.writeFile(parsed.options.sarifFile, JSON.stringify(sarif, null, 2) + "\n", "utf8");
         }
-        if (parsed.options.ci && result.updates.length > 0) {
-            process.exitCode = 1;
-            return;
-        }
-        if (result.errors.length > 0) {
-            process.exitCode = 2;
-        }
+        process.exitCode = resolveExitCode(result, parsed.options.failOn, parsed.options.maxUpdates, parsed.options.ci);
     }
     catch (error) {
         process.stderr.write(`rainy-updates: ${String(error)}\n`);
@@ -107,10 +130,28 @@ Options:
   --pr-report-file <path>`;
     }
     if (isCommand && command === "init-ci") {
-        return `rainy-updates init-ci [--force]
+        return `rainy-updates init-ci [options]
 
 Create a GitHub Actions workflow template at:
-  .github/workflows/rainy-updates.yml`;
+  .github/workflows/rainy-updates.yml
+
+Options:
+  --force
+  --mode minimal|strict|enterprise
+  --schedule weekly|daily|off`;
+    }
+    if (isCommand && command === "baseline") {
+        return `rainy-updates baseline [options]
+
+Save or compare dependency baseline snapshots.
+
+Options:
+  --save
+  --check
+  --file <path>
+  --workspace
+  --dep-kinds deps,dev,optional,peer
+  --ci`;
     }
     return `rainy-updates <command> [options]
 
@@ -119,6 +160,7 @@ Commands:
   upgrade     Apply updates to manifests
   warm-cache  Warm local cache for fast/offline checks
   init-ci     Scaffold GitHub Actions workflow
+  baseline    Save/check dependency baseline snapshots
 
 Global options:
   --cwd <path>
@@ -130,6 +172,8 @@ Global options:
   --sarif-file <path>
   --pr-report-file <path>
   --policy-file <path>
+  --fail-on none|patch|minor|major|any
+  --max-updates <n>
   --concurrency <n>
   --cache-ttl <seconds>
   --offline
@@ -144,3 +188,22 @@ async function readPackageVersion() {
     const parsed = JSON.parse(content);
     return parsed.version ?? "0.0.0";
 }
+function resolveExitCode(result, failOn, maxUpdates, ciMode) {
+    if (result.errors.length > 0)
+        return 2;
+    if (typeof maxUpdates === "number" && result.updates.length > maxUpdates)
+        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");
+}

package/dist/cache/cache.d.ts

@@ -5,5 +5,5 @@ export declare class VersionCache {
     static create(customPath?: string): Promise<VersionCache>;
     getValid(packageName: string, target: TargetLevel): Promise<CachedVersion | null>;
     getAny(packageName: string, target: TargetLevel): Promise<CachedVersion | null>;
-    set(packageName: string, target: TargetLevel, latestVersion: string, ttlSeconds: number): Promise<void>;
+    set(packageName: string, target: TargetLevel, latestVersion: string, availableVersions: string[], ttlSeconds: number): Promise<void>;
 }

package/dist/cache/cache.js

@@ -9,7 +9,13 @@ class FileCacheStore {
     async get(packageName, target) {
         const entries = await this.readEntries();
         const key = this.getKey(packageName, target);
-        return entries[key] ?? null;
+        const entry = entries[key];
+        if (!entry)
+            return null;
+        return {
+            ...entry,
+            availableVersions: Array.isArray(entry.availableVersions) ? entry.availableVersions : [entry.latestVersion],
+        };
     }
     async set(entry) {
         const entries = await this.readEntries();
@@ -39,31 +45,63 @@ class SqliteCacheStore {
         package_name TEXT NOT NULL,
         target TEXT NOT NULL,
         latest_version TEXT NOT NULL,
+        available_versions TEXT NOT NULL,
         fetched_at INTEGER NOT NULL,
         ttl_seconds INTEGER NOT NULL,
         PRIMARY KEY (package_name, target)
       );
     `);
+        this.ensureSchema();
     }
     async get(packageName, target) {
-        const row = this.db
-            .prepare(`SELECT package_name, target, latest_version, fetched_at, ttl_seconds FROM versions WHERE package_name = ? AND target = ?`)
-            .get(packageName, target);
+        let row;
+        try {
+            row = this.db
+                .prepare(`SELECT package_name, target, latest_version, available_versions, fetched_at, ttl_seconds FROM versions WHERE package_name = ? AND target = ?`)
+                .get(packageName, target);
+        }
+        catch {
+            row = this.db
+                .prepare(`SELECT package_name, target, latest_version, fetched_at, ttl_seconds FROM versions WHERE package_name = ? AND target = ?`)
+                .get(packageName, target);
+        }
         if (!row)
             return null;
         return {
             packageName: row.package_name,
             target: row.target,
             latestVersion: row.latest_version,
+            availableVersions: parseJsonArray(row.available_versions ?? row.latest_version, row.latest_version),
             fetchedAt: row.fetched_at,
             ttlSeconds: row.ttl_seconds,
         };
     }
     async set(entry) {
-        this.db
-            .prepare(`INSERT OR REPLACE INTO versions (package_name, target, latest_version, fetched_at, ttl_seconds)
-         VALUES (?, ?, ?, ?, ?)`)
-            .run(entry.packageName, entry.target, entry.latestVersion, entry.fetchedAt, entry.ttlSeconds);
+        try {
+            this.db
+                .prepare(`INSERT OR REPLACE INTO versions (package_name, target, latest_version, available_versions, fetched_at, ttl_seconds)
+           VALUES (?, ?, ?, ?, ?, ?)`)
+                .run(entry.packageName, entry.target, entry.latestVersion, JSON.stringify(entry.availableVersions), entry.fetchedAt, entry.ttlSeconds);
+        }
+        catch {
+            this.db
+                .prepare(`INSERT OR REPLACE INTO versions (package_name, target, latest_version, fetched_at, ttl_seconds)
+           VALUES (?, ?, ?, ?, ?)`)
+                .run(entry.packageName, entry.target, entry.latestVersion, entry.fetchedAt, entry.ttlSeconds);
+        }
+    }
+    ensureSchema() {
+        try {
+            const columns = this.db.prepare("PRAGMA table_info(versions);").all();
+            const hasAvailableVersions = columns.some((column) => column.name === "available_versions");
+            if (!hasAvailableVersions) {
+                this.db.exec("ALTER TABLE versions ADD COLUMN available_versions TEXT;");
+            }
+            this.db.exec("UPDATE versions SET available_versions = latest_version WHERE available_versions IS NULL;");
+        }
+        catch {
+            // Best-effort migration.
+        }
     }
 }
 export class VersionCache {
@@ -92,11 +130,12 @@ export class VersionCache {
     async getAny(packageName, target) {
         return this.store.get(packageName, target);
     }
-    async set(packageName, target, latestVersion, ttlSeconds) {
+    async set(packageName, target, latestVersion, availableVersions, ttlSeconds) {
         await this.store.set({
             packageName,
             target,
             latestVersion,
+            availableVersions,
             fetchedAt: Date.now(),
             ttlSeconds,
         });
@@ -111,15 +150,21 @@ async function tryCreateSqliteStore(dbPath) {
         }
     }
     catch {
-        // noop
+        return null;
     }
+    return null;
+}
+function parseJsonArray(raw, fallback) {
+    if (typeof raw !== "string")
+        return [fallback];
     try {
-        const maybeRequire = Function("return require")();
-        const Database = maybeRequire("better-sqlite3");
-        const db = new Database(dbPath);
-        return new SqliteCacheStore(db);
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [fallback];
+        const values = parsed.filter((value) => typeof value === "string");
+        return values.length > 0 ? values : [fallback];
     }
     catch {
-        return null;
+        return [fallback];
     }
 }

package/dist/config/loader.d.ts

@@ -1,4 +1,4 @@
-import type { DependencyKind, OutputFormat, TargetLevel } from "../types/index.js";
+import type { DependencyKind, FailOnLevel, OutputFormat, TargetLevel } from "../types/index.js";
 export interface FileConfig {
     target?: TargetLevel;
     filter?: string;
@@ -15,6 +15,8 @@ export interface FileConfig {
     offline?: boolean;
     policyFile?: string;
     prReportFile?: string;
+    failOn?: FailOnLevel;
+    maxUpdates?: number;
     install?: boolean;
     packageManager?: "auto" | "npm" | "pnpm";
     sync?: boolean;