@rainy-updates/cli 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,158 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [0.4.0] - 2026-02-27
+
+### Added
+
+- Production hardening for CLI UX:
+  - global and command-level help (`--help`, `-h`),
+  - version output (`--version`, `-v`),
+  - strict unknown command rejection.
+- OSS/release infrastructure:
+  - `LICENSE` (MIT),
+  - `CONTRIBUTING.md`,
+  - project CI workflow (`.github/workflows/ci.yml`),
+  - npm release workflow (`.github/workflows/release.yml`).
+- Packaging stabilization:
+  - `types` export path,
+  - production scripts (`clean`, `test:prod`, `prepublishOnly`),
+  - publish config with npm provenance and public access.
+
+### Changed
+
+- Registry client now retries latest-version resolution with backoff for transient failures.
+- Output formatting now shows cache warming summary when relevant.
+
+### Fixed
+
+- Parser now fails fast for unknown commands instead of silently defaulting to `check`.
+
+## [0.3.0] - 2026-02-27
+
+### Added
+
+- `warm-cache` command:
+  - pre-fetches package metadata into cache,
+  - supports workspace scanning,
+  - supports offline behavior with explicit cache-miss reporting.
+- `init-ci` command:
+  - scaffolds `.github/workflows/rainy-updates.yml`,
+  - supports `--force` overwrite behavior.
+- Policy engine:
+  - `--policy-file` to load package update rules,
+  - default discovery of `.rainyupdates-policy.json` and `rainy-updates.policy.json`,
+  - rule-level controls:
+    - global ignore patterns,
+    - per-package ignore,
+    - per-package `maxTarget` update ceiling.
+- PR report output:
+  - `--pr-report-file` emits markdown report for pull request comments.
+- New summary metric:
+  - `warmedPackages` in results and GitHub output values.
+- New tests:
+  - warm cache behavior,
+  - policy loading,
+  - CI workflow scaffolding,
+  - PR markdown report rendering,
+  - parser support for new commands/flags.
+
+### Changed
+
+- Check pipeline now applies policy constraints before update proposals.
+- Output summary now includes warmed cache package count.
+- CLI command parser supports additional commands (`warm-cache`, `init-ci`) and options (`--policy-file`, `--pr-report-file`, `--force`).
+
+## [0.2.0] - 2026-02-27
+
+### Added
+
+- High-throughput registry resolution architecture:
+  - batched unique package resolution,
+  - configurable concurrency with `--concurrency`,
+  - optional `undici` pool + HTTP/2 path when available,
+  - automatic fallback to native `fetch` when `undici` is unavailable.
+- Offline execution mode:
+  - `--offline` runs in cache-only mode,
+  - reports cache misses explicitly for deterministic CI behavior.
+- Workspace graph module:
+  - detects local package graph,
+  - computes topological order,
+  - detects simple cycle groups and surfaces warnings.
+- Graph-aware sync in upgrade flow:
+  - `--sync` now aligns versions following workspace graph order,
+  - preserves `workspace:*` protocol references.
+- Additional test coverage:
+  - workspace graph ordering,
+  - workspace protocol edge handling,
+  - offline cache miss behavior.
+
+### Changed
+
+- `check` pipeline now resolves versions by unique dependency name first, then applies results across all manifests.
+- stale cache fallback is applied after registry failures to reduce flaky CI checks.
+- options/config surface expanded with `offline` and stronger CI-oriented controls.
+
+### OSS Quality
+
+- README expanded with performance/runtime notes and complete options matrix.
+- Output and artifact model reinforced for CI systems (JSON, GitHub outputs, SARIF).
+
+## [0.1.0] - 2026-02-27
+
+### Added
+
+- New npm package identity: `@rainy-updates/cli` with CLI binary `rainy-updates`.
+- Core commands:
+  - `check` for update detection.
+  - `upgrade` for manifest rewriting with optional installation step.
+- Multi-format output system:
+  - `table`, `json`, `minimal`, and `github` annotation output.
+- CI artifact outputs:
+  - `--json-file` for machine-readable check results.
+  - `--github-output` for key-value GitHub Actions outputs.
+  - `--sarif-file` for SARIF 2.1.0 compatible reports.
+- Configuration support:
+  - `.rainyupdatesrc`
+  - `.rainyupdatesrc.json`
+  - `package.json` field: `rainyUpdates`
+- Workspace-aware scanning (`--workspace`):
+  - `package.json` workspaces detection.
+  - `pnpm-workspace.yaml` package pattern detection.
+- Workspace upgrade harmonization:
+  - `--sync` aligns dependency versions across scanned manifests.
+- Dependency category filtering:
+  - `--dep-kinds deps,dev,optional,peer`
+- Runtime controls:
+  - `--concurrency` for parallel dependency checks.
+  - `--cache-ttl` for cache freshness tuning.
+- Cache layer improvements:
+  - SQLite-first cache backend when available.
+  - JSON fallback cache backend.
+  - stale cache fallback path when registry requests fail.
+- Programmatic exports:
+  - `check`, `upgrade`, SARIF and GitHub output helpers.
+- Test suite expanded with coverage for:
+  - semver utilities,
+  - CLI option parsing,
+  - config loading,
+  - workspace discovery,
+  - SARIF generation,
+  - GitHub output writing.
+
+### Changed
+
+- Project structure refactored into modular layers (`core`, `config`, `workspace`, `output`, `cache`, `registry`, `pm`, `utils`, `types`).
+- CLI parser upgraded to async workflow to support config loading and cwd-based config resolution.
+- Upgrade pipeline now supports writing updates across multiple workspace package manifests.
+
+### Fixed
+
+- Argument parsing now correctly handles flags when command is omitted (`check` default mode).
+- Type-safe discriminated command parsing for `check` vs `upgrade` options.
+
+### Notes
+
+- In network-restricted environments, registry lookups fail gracefully and return exit code `2` with detailed error output.
+- `pnpm` and `npm` are the official package-manager scope for this release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rainy Updates
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# @rainy-updates/cli
+
+Agentic OSS CLI for dependency updates focused on speed, CI automation, and workspace-scale maintenance.
+
+## Install
+
+```bash
+npm i -D @rainy-updates/cli
+# or
+pnpm add -D @rainy-updates/cli
+```
+
+## 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`.
+
+## Quick start
+
+```bash
+# check and fail CI if updates are found
+npx @rainy-updates/cli check --ci --format json --json-file .artifacts/deps-report.json
+
+# pre-warm cache before strict offline checks
+npx @rainy-updates/cli warm-cache --workspace --concurrency 32
+npx @rainy-updates/cli check --workspace --offline --ci
+
+# upgrade ranges and install lockfiles
+npx @rainy-updates/cli upgrade --target latest --workspace --sync --install
+
+# scaffold GitHub Actions workflow
+npx @rainy-updates/cli init-ci
+```
+
+## Core options
+
+- `--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>`
+
+## Output options
+
+- `--format table|json|minimal|github`
+- `--json-file <path>`
+- `--github-output <path>`
+- `--sarif-file <path>`
+- `--pr-report-file <path>` (generates markdown report for PR comments)
+
+## Upgrade options
+
+- `--install`
+- `--pm auto|npm|pnpm`
+- `--sync` (graph-aware version alignment across workspace packages)
+
+## Policy controls
+
+- `--policy-file <path>` to apply package-level policy rules.
+- default policy discovery:
+  - `.rainyupdates-policy.json`
+  - `rainy-updates.policy.json`
+
+Policy example:
+
+```json
+{
+  "ignore": ["@types/*", "eslint*"],
+  "packageRules": {
+    "react": { "maxTarget": "minor" },
+    "typescript": { "ignore": true }
+  }
+}
+```
+
+## CLI help
+
+```bash
+rainy-updates --help
+rainy-updates <command> --help
+rainy-updates --version
+```
+
+## CI behavior
+
+- `--ci`: returns exit code `1` when updates are found.
+- returns exit code `2` for operational errors (registry/IO/runtime failures).
+
+## Config files
+
+Supported:
+
+- `.rainyupdatesrc`
+- `.rainyupdatesrc.json`
+- `package.json` -> `rainyUpdates`
+
+Example:
+
+```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"
+  }
+}
+```
+
+## Production release
+
+```bash
+bun run prepublishOnly
+node scripts/release-preflight.mjs
+npm publish --provenance --access public
+```
+
+If publishing in GitHub Actions, set `NPM_TOKEN` in repository secrets.
+
+The repository includes:
+
+- `.github/workflows/ci.yml` for test/typecheck/build/smoke checks.
+- `.github/workflows/release.yml` for tag-driven npm publishing.
+
+## Performance and runtime notes
+
+- 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.

package/dist/bin/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/cli.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+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 { initCiWorkflow } from "../core/init-ci.js";
+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";
+async function main() {
+    try {
+        const argv = process.argv.slice(2);
+        if (argv.includes("--version") || argv.includes("-v")) {
+            process.stdout.write((await readPackageVersion()) + "\n");
+            return;
+        }
+        if (argv.includes("--help") || argv.includes("-h")) {
+            process.stdout.write(renderHelp(argv[0]) + "\n");
+            return;
+        }
+        const parsed = await parseCliArgs(argv);
+        if (parsed.command === "init-ci") {
+            const workflow = await initCiWorkflow(parsed.options.cwd, parsed.options.force);
+            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;
+        }
+        const result = parsed.command === "upgrade"
+            ? await upgrade(parsed.options)
+            : parsed.command === "warm-cache"
+                ? await warmCache(parsed.options)
+                : await check(parsed.options);
+        const rendered = renderResult(result, parsed.options.format);
+        process.stdout.write(rendered + "\n");
+        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");
+        }
+        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");
+        }
+        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");
+        }
+        if (parsed.options.ci && result.updates.length > 0) {
+            process.exitCode = 1;
+            return;
+        }
+        if (result.errors.length > 0) {
+            process.exitCode = 2;
+        }
+    }
+    catch (error) {
+        process.stderr.write(`rainy-updates: ${String(error)}\n`);
+        process.exitCode = 2;
+    }
+}
+void main();
+function renderHelp(command) {
+    const isCommand = command && !command.startsWith("-");
+    if (isCommand && command === "warm-cache") {
+        return `rainy-updates warm-cache [options]
+
+Pre-warm local metadata cache for faster CI checks.
+
+Options:
+  --workspace
+  --target patch|minor|major|latest
+  --filter <pattern>
+  --reject <pattern>
+  --dep-kinds deps,dev,optional,peer
+  --concurrency <n>
+  --cache-ttl <seconds>
+  --offline
+  --json-file <path>
+  --github-output <path>
+  --sarif-file <path>
+  --pr-report-file <path>`;
+    }
+    if (isCommand && command === "upgrade") {
+        return `rainy-updates upgrade [options]
+
+Apply dependency updates to package.json manifests.
+
+Options:
+  --workspace
+  --sync
+  --install
+  --pm auto|npm|pnpm
+  --target patch|minor|major|latest
+  --policy-file <path>
+  --concurrency <n>
+  --json-file <path>
+  --pr-report-file <path>`;
+    }
+    if (isCommand && command === "init-ci") {
+        return `rainy-updates init-ci [--force]
+
+Create a GitHub Actions workflow template at:
+  .github/workflows/rainy-updates.yml`;
+    }
+    return `rainy-updates <command> [options]
+
+Commands:
+  check       Detect available updates
+  upgrade     Apply updates to manifests
+  warm-cache  Warm local cache for fast/offline checks
+  init-ci     Scaffold GitHub Actions workflow
+
+Global options:
+  --cwd <path>
+  --workspace
+  --target patch|minor|major|latest
+  --format table|json|minimal|github
+  --json-file <path>
+  --github-output <path>
+  --sarif-file <path>
+  --pr-report-file <path>
+  --policy-file <path>
+  --concurrency <n>
+  --cache-ttl <seconds>
+  --offline
+  --ci
+  --help, -h
+  --version, -v`;
+}
+async function readPackageVersion() {
+    const currentFile = fileURLToPath(import.meta.url);
+    const packageJsonPath = path.resolve(path.dirname(currentFile), "../../package.json");
+    const content = await fs.readFile(packageJsonPath, "utf8");
+    const parsed = JSON.parse(content);
+    return parsed.version ?? "0.0.0";
+}

package/dist/cache/cache.d.ts

@@ -0,0 +1,9 @@
+import type { CachedVersion, TargetLevel } from "../types/index.js";
+export declare class VersionCache {
+    private readonly store;
+    private constructor();
+    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>;
+}

package/dist/cache/cache.js

@@ -0,0 +1,125 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+class FileCacheStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async get(packageName, target) {
+        const entries = await this.readEntries();
+        const key = this.getKey(packageName, target);
+        return entries[key] ?? null;
+    }
+    async set(entry) {
+        const entries = await this.readEntries();
+        entries[this.getKey(entry.packageName, entry.target)] = entry;
+        await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+        await fs.writeFile(this.filePath, JSON.stringify(entries), "utf8");
+    }
+    async readEntries() {
+        try {
+            const content = await fs.readFile(this.filePath, "utf8");
+            return JSON.parse(content);
+        }
+        catch {
+            return {};
+        }
+    }
+    getKey(packageName, target) {
+        return `${packageName}:${target}`;
+    }
+}
+class SqliteCacheStore {
+    db;
+    constructor(db) {
+        this.db = db;
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS versions (
+        package_name TEXT NOT NULL,
+        target TEXT NOT NULL,
+        latest_version TEXT NOT NULL,
+        fetched_at INTEGER NOT NULL,
+        ttl_seconds INTEGER NOT NULL,
+        PRIMARY KEY (package_name, target)
+      );
+    `);
+    }
+    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);
+        if (!row)
+            return null;
+        return {
+            packageName: row.package_name,
+            target: row.target,
+            latestVersion: 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);
+    }
+}
+export class VersionCache {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    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);
+        const jsonPath = path.join(basePath, "cache.json");
+        return new VersionCache(new FileCacheStore(jsonPath));
+    }
+    async getValid(packageName, target) {
+        const entry = await this.store.get(packageName, target);
+        if (!entry)
+            return null;
+        const expiresAt = entry.fetchedAt + entry.ttlSeconds * 1000;
+        if (Date.now() > expiresAt)
+            return null;
+        return entry;
+    }
+    async getAny(packageName, target) {
+        return this.store.get(packageName, target);
+    }
+    async set(packageName, target, latestVersion, ttlSeconds) {
+        await this.store.set({
+            packageName,
+            target,
+            latestVersion,
+            fetchedAt: Date.now(),
+            ttlSeconds,
+        });
+    }
+}
+async function tryCreateSqliteStore(dbPath) {
+    try {
+        if (typeof Bun !== "undefined") {
+            const mod = await import("bun:sqlite");
+            const db = new mod.Database(dbPath, { create: true });
+            return new SqliteCacheStore(db);
+        }
+    }
+    catch {
+        // noop
+    }
+    try {
+        const maybeRequire = Function("return require")();
+        const Database = maybeRequire("better-sqlite3");
+        const db = new Database(dbPath);
+        return new SqliteCacheStore(db);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/config/loader.d.ts

@@ -0,0 +1,22 @@
+import type { DependencyKind, OutputFormat, TargetLevel } from "../types/index.js";
+export interface FileConfig {
+    target?: TargetLevel;
+    filter?: string;
+    reject?: string;
+    cacheTtlSeconds?: number;
+    includeKinds?: DependencyKind[];
+    ci?: boolean;
+    format?: OutputFormat;
+    workspace?: boolean;
+    jsonFile?: string;
+    githubOutputFile?: string;
+    sarifFile?: string;
+    concurrency?: number;
+    offline?: boolean;
+    policyFile?: string;
+    prReportFile?: string;
+    install?: boolean;
+    packageManager?: "auto" | "npm" | "pnpm";
+    sync?: boolean;
+}
+export declare function loadConfig(cwd: string): Promise<FileConfig>;

package/dist/config/loader.js

@@ -0,0 +1,35 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+export async function loadConfig(cwd) {
+    const fromRc = await loadRcFile(cwd);
+    const fromPackage = await loadPackageConfig(cwd);
+    return {
+        ...fromPackage,
+        ...fromRc,
+    };
+}
+async function loadRcFile(cwd) {
+    const candidates = [".rainyupdatesrc", ".rainyupdatesrc.json"];
+    for (const candidate of candidates) {
+        const filePath = path.join(cwd, candidate);
+        try {
+            const content = await fs.readFile(filePath, "utf8");
+            return JSON.parse(content);
+        }
+        catch {
+            // noop
+        }
+    }
+    return {};
+}
+async function loadPackageConfig(cwd) {
+    const packagePath = path.join(cwd, "package.json");
+    try {
+        const content = await fs.readFile(packagePath, "utf8");
+        const parsed = JSON.parse(content);
+        return parsed.rainyUpdates ?? {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/config/policy.d.ts

@@ -0,0 +1,16 @@
+import type { TargetLevel } from "../types/index.js";
+export interface PolicyConfig {
+    ignore?: string[];
+    packageRules?: Record<string, {
+        maxTarget?: TargetLevel;
+        ignore?: boolean;
+    }>;
+}
+export interface ResolvedPolicy {
+    ignorePatterns: string[];
+    packageRules: Map<string, {
+        maxTarget?: TargetLevel;
+        ignore: boolean;
+    }>;
+}
+export declare function loadPolicy(cwd: string, policyFile?: string): Promise<ResolvedPolicy>;