@vibgrate/cli 1.0.45 → 1.0.47

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <strong>@vibgrate/cli</strong>
   <br />
-  Continuous Upgrade Drift Intelligence for Node & .NET
+  Continuous Upgrade Drift Intelligence for engineering teams
 </p>
 
 <p align="center">
@@ -11,230 +11,249 @@
   <img src="https://img.shields.io/node/v/@vibgrate/cli" alt="node version" />
 </p>
 
+Vibgrate gives you a clear answer to one question:
+**How far behind is this repo, and what should we upgrade first?**
+
+In one command, you get:
+
+- A deterministic **Upgrade Drift Score** (0–100)
+- A clear risk level (**Low / Moderate / High**)
+- Runtime + framework major-version lag
+- Dependency age distribution + EOL proximity
+- Priority actions for what to fix next
+
+Supported ecosystems today: **Node.js/TypeScript, .NET, Python, and Java**.
+
 ---
 
-Modern codebases don't break all at once — they decay silently. Node runtimes fall behind LTS. .NET frameworks approach end-of-life. Core dependencies lag multiple major versions. Upgrade cost compounds until it becomes a project in itself.
+## Why teams adopt Vibgrate
+
+Most systems do not fail all at once. They accumulate upgrade debt silently until migrations become expensive.
 
-**Vibgrate turns that invisible decay into a measurable signal.** One CLI command gives you an Upgrade Drift Score (0–100), actionable findings, and a clear picture of where your upgrade debt lives.
+Vibgrate makes drift measurable and repeatable:
+
+- **Developers** run a one-off scan to understand current debt.
+- **CI pipelines** run every PR/build to stop regression.
+- **Engineering leaders** track trends over time in the dashboard (optional push).
 
 ---
 
-## Quick Start
+## One-off scan vs CI-integrated drift tracking
+
+| Mode                   | What you get                                                      | Best for                                     |
+| ---------------------- | ----------------------------------------------------------------- | -------------------------------------------- |
+| **One-off scan**       | Fast snapshot of score, lag, and findings                         | Audits, due diligence, migration planning    |
+| **CI-integrated scan** | Continuous drift signal, SARIF annotations, regression guardrails | Keeping upgrade debt under control long-term |
 
-Run instantly with npx — no install required:
+Recommended rollout: start with a one-off scan now, then add Vibgrate to CI this week.
+
+---
+
+## Quick start
+
+Run instantly (no install):
 
 ```bash
-npx @vibgrate/cli scan
+npx @vibgrate/cli scan .
 ```
 
-Or install as a dev dependency:
+Or install locally:
 
 ```bash
 npm install -D @vibgrate/cli
+npx vibgrate scan .
 ```
 
-Then scan your project:
+Add an npm script:
 
-```bash
-npx vibgrate scan
+```json
+{
+  "scripts": {
+    "drift": "vibgrate scan ."
+  }
+}
 ```
 
-> **Why `npx`?** Installing with `-D` places the binary in `node_modules/.bin/`, which isn't on your system PATH. Use `npx` to run it, or add a script to your `package.json`:
->
-> ```json
-> "scripts": {
->   "drift": "vibgrate scan"
-> }
-> ```
->
-> Then run `npm run drift`. Alternatively, install globally with `npm install -g @vibgrate/cli` to use `vibgrate` directly.
-
-That's it. You'll see a full drift report in seconds.
+> Local binaries are in `node_modules/.bin`, so use `npx` (or an npm script) unless you install globally.
 
 ---
 
-## What You Get
+## What the report contains
 
-```
-    ╭───╮➜
-   ╭┤◉ ◉├╮  V I B G R A T E
-   ╰┤───├╯  Drift Intelligence Engine v1.x.x
-    ╰───╯
-
-╔══════════════════════════════════════════╗
-║        Vibgrate Drift Report             ║
-╚══════════════════════════════════════════╝
-
-  Drift Score:  72/100
-  Risk Level:   LOW
-  Projects:     3
-  VCS:          git main a1b2c3d
-
-  Score Breakdown
-    Runtime:      ████████████████████ 100
-    Frameworks:   ████████████████░░░░  78
-    Dependencies: ██████████████░░░░░░  64
-    EOL Risk:     ████████████████████ 100
-
-  ── my-api (node) src/api
-     Runtime: 20.11.0 (current)
-     Frameworks:
-       NestJS: 10.3.0 → 11.0.0 (1 behind)
-     Dependencies:
-       42 current  8 1-behind  3 2+ behind
-
-  ── web-app (node) src/web
-     Runtime: 20.11.0 (current)
-     Frameworks:
-       React: 18.2.0 → 19.0.0 (1 behind)
-     Dependencies:
-       31 current  5 1-behind  2 2+ behind
-
-  Tech Stack
-    Frontend: React, Tailwind CSS
-    Bundlers: Vite
-    Testing: Vitest, Playwright
-    Lint & Format: ESLint, Prettier
-
-  Services & Integrations
-    Cloud: AWS SDK v3
-    Databases: PostgreSQL
-
-  TypeScript
-    v5.4.2 · strict ✔ · ESM · target: ES2022
-
-  Build & Deploy
-    CI: GitHub Actions
-    Docker: 2 Dockerfiles (node:20-alpine)
-    Package Managers: pnpm
-
-  Security Posture
-    Lockfile ✔ · .env ✔ · node_modules ✔
-
-  Dependency Graph
-    pnpm-lock.yaml: 312 unique, 487 installed
-    5 duplicated packages
-
-  Findings (2 warnings, 1 note)
-    ⚠ Framework "NestJS" is 1 major version(s) behind
-      framework/outdated in src/api/package.json
-    ⚠ 12% of dependencies are 2+ major versions behind
-      dependency/outdated in src/api/package.json
-    ℹ TypeScript target is ES2022
-      ts/target in tsconfig.json
-
-╔══════════════════════════════════════════╗
-║        Top Priority Actions              ║
-╚══════════════════════════════════════════╝
-
-  1. Upgrade NestJS 10.3.0 → 11.0.0 in my-api
-     1 major version behind. Major framework drift increases
-     breaking change risk and blocks access to security fixes.
-     ./src/api
-       NestJS: 10.3.0 → 11.0.0 (1 behind)
-     Impact: +5–15 points (framework score)
-
-  2. Reduce dependency rot in my-api (42% severely outdated)
-     3 of 53 dependencies are 2+ majors behind. Run `npm outdated`
-     and prioritise packages with known CVEs.
-     ./src/api
-       express: 3.4.0 → 5.0.0 (2 majors behind)
-       lodash: 3.10.1 → 4.17.21 (1 major behind)
-       ... and 1 more
-     Impact: +5–10 points (dependency score)
-
-  Scanned at 2026-02-16T00:00:00.000Z · 1.2s · 48 files scanned
-```
+Every scan includes:
+
+- **Overall score** and risk level
+- **Score breakdown** (runtime, frameworks, dependencies, EOL)
+- **Per-project details** across Node, .NET, Python, and Java
+- **Actionable findings** (warnings/errors/notes)
+- **Top Priority Actions** ranked by likely impact
+
+We keep output plain and operational: easy to convert into backlog items and CI policy.
 
 ---
 
-## Key Features
+## New capabilities included in this release
 
-### Upgrade Drift Score
+### 1) Multi-language workspace scanning
 
-A single 0–100 number that tells you how upgrade-ready your codebase is. Computed from runtime lag, framework versions, dependency age distribution, and EOL proximity. Deterministic and comparable across repos.
+Vibgrate recursively scans mixed repositories and supports:
 
-### Multi-Platform Scanning
+- Node.js / TypeScript (`package.json`)
+- .NET (`.sln`, `.csproj`)
+- Python (`requirements.txt`, `pyproject.toml` style ecosystems)
+- Java (`pom.xml`, Gradle-style manifest ecosystems)
 
-Works across **Node.js/TypeScript** and **.NET** projects in the same scan. Detects `package.json`, `.sln`, and `.csproj` files recursively.
+### 2) Extended scanner suite
 
-### CI-Native
+Beyond core drift scoring, Vibgrate can also detect:
 
-Designed to live in your build pipeline. Returns meaningful exit codes, produces SARIF output for GitHub Code Scanning and Azure DevOps, and requires zero configuration to get started.
+- Platform matrix and native-module risk
+- Dependency risk, graph duplication, and phantom dependencies
+- Full tooling inventory and build/deploy surface
+- TypeScript modernity and breaking-change exposure
+- File hotspots and structural security posture
+- Security scanner readiness and local policy coverage checks
+- Service dependency mapping (cloud, db, auth, messaging, etc.)
+- Architecture layer mapping
+- Code-quality metrics (complexity, nesting, cycles, god files)
+- OWASP category mapping from security findings
 
-### 13 Extended Scanners
+### 3) SBOM Export & Delta
 
-Beyond the core drift score, Vibgrate runs a suite of extended scanners — all optional, all privacy-safe:
+Vibgrate now emits rich dependency inventory data in the JSON artifact, including lockfile-derived package graphs, duplicate-version hotspots, and phantom dependencies.
 
-| Scanner | What It Finds |
-|---------|---------------|
-| **Platform Matrix** | Native modules, OS assumptions, Docker base images, architecture risks |
-| **Dependency Risk** | Deprecated packages, native module flags, platform-specific dependencies |
-| **Dependency Graph** | Duplicated packages, phantom dependencies, lockfile analysis |
-| **Tooling Inventory** | Full tech stack map — frameworks, bundlers, ORMs, testing tools |
-| **Build & Deploy** | CI systems, Docker, IaC, release tooling, monorepo tools |
-| **TypeScript Modernity** | Strict mode, module system, ESM readiness |
-| **Breaking Change Exposure** | Packages known to cause upgrade pain, legacy polyfills |
-| **File Hotspots** | Codebase shape — file counts, sizes, depth, shared packages |
-| **Security Posture** | Lockfile hygiene, `.gitignore` coverage, audit severity counts |
-| **Security Scanners** | Semgrep (SAST) + Gitleaks/TruffleHog readiness, version risk checks, heuristic secret signals |
-| **Service Dependencies** | External SDK detection — payment, auth, cloud, databases, messaging |
-| **Code Quality** | Cyclomatic complexity, function length, nesting depth, god files, dead-code estimate, circular imports |
-| **OWASP Category Mapping** | Semgrep OSS findings mapped to OWASP Top 10 categories (fast or cache-input mode) |
+This gives teams practical **SBOM-ready supply-chain visibility** for governance workflows while keeping the scan fast and CI-friendly.
 
-### Baseline & Delta Tracking
+Use scan artifacts as operational SBOM intelligence in either CycloneDX or SPDX format:
 
-Take a baseline snapshot, then measure drift over time:
+```bash
+npx vibgrate sbom export --format cyclonedx --out sbom.cdx.json
+npx vibgrate sbom export --format spdx --out sbom.spdx.json
+```
+
+Compare two scan artifacts to see dependency additions/removals/version changes between releases:
+
+```bash
+npx vibgrate sbom delta --from .vibgrate/baseline.json --to .vibgrate/scan_result.json --out sbom-delta.txt
+```
+
+This keeps reports plain and actionable, so teams can go from scan output to backlog tasks quickly.
+
+### 4) Baseline, Drift Budgets & Fitness Gates
+
+Take a baseline snapshot, then enforce dependency drift fitness functions in CI:
 
 ```bash
 npx vibgrate baseline .
-npx vibgrate scan --baseline .vibgrate/baseline.json
+npx vibgrate scan --baseline .vibgrate/baseline.json --drift-worsening 5 --drift-budget 40
 ```
 
-### Multiple Output Formats
+- `--drift-budget <score>` fails the build if absolute drift score exceeds your budget.
+- `--drift-worsening <percent>` fails the build if drift worsens by more than X% relative to baseline.
 
-| Format | Use Case |
-|--------|----------|
-| `text` | Terminal output, local development |
-| `json` | Programmatic consumption, artifact storage |
-| `sarif` | GitHub Code Scanning, Azure DevOps integration |
-| `md` | PR comments, documentation, wikis |
+This turns drift scoring into a quality gate instead of passive reporting.
 
-### Dashboard Upload (Optional)
+---
+
+
+## Privacy & offline-first workflows
+
+Vibgrate now supports explicit privacy controls:
 
-Push scan results to the [Vibgrate Dashboard](https://vibgrate.com) for trend analysis, cross-repo comparison, and team-wide visibility. Upload is always opt-in — the CLI provides full value offline.
+- `--no-local-artifacts` prevents writing `.vibgrate/*.json` files to disk.
+- `--max-privacy` enables a hardened profile (suppresses local artifact writes and disables high-context scanners such as UI-purpose evidence and architecture/code-quality enrichment).
+- `--offline` disables live registry/network lookups and never uploads scan results.
+- `--package-manifest <file>` accepts a local JSON or ZIP package-version manifest so drift can still be calculated offline. Download the latest bundle at `https://github.com/vibgrate/manifests/latest-packages.zip`.
 
-The easiest way is to combine scan and push in a single command:
+Example:
 
 ```bash
-VIBGRATE_DSN="..." npx @vibgrate/cli scan --push
+vibgrate scan . --offline --package-manifest ./package-versions.zip --max-privacy --format json --out scan.json
 ```
 
-Or pass the DSN directly:
+When offline mode runs without a package manifest, package freshness is marked as unknown and drift scoring is necessarily partial.
+
+## Core commands
 
 ```bash
-npx @vibgrate/cli scan --push --dsn "vibgrate+https://<key_id>:<secret>@us.ingest.vibgrate.com/<workspace_id>"
+vibgrate scan [path] [--format text|json|sarif] [--out <file>] [--fail-on warn|error] [--offline] [--package-manifest <file>] [--no-local-artifacts] [--max-privacy]
+vibgrate baseline [path]
+vibgrate report [--in <artifact.json>] [--format md|text|json]
+vibgrate push [--dsn <dsn>] [--file <artifact.json>] [--strict]
+vibgrate init [path] [--baseline] [--yes]
+vibgrate dsn create --workspace <id> [--region us|eu] [--write <path>]
 ```
 
-You can also push a previously generated artifact separately:
+### Command examples with expected results
 
 ```bash
-VIBGRATE_DSN="..." vibgrate push
+# 1) Scan current repo (text output)
+npx @vibgrate/cli scan .
 ```
 
-> **Get your DSN:** Sign up at [vibgrate.com](https://vibgrate.com) and your workspace will be created automatically with a ready-to-paste code snippet containing your DSN.
+Expected result:
+
+- Prints overall score + risk level
+- Shows detected projects (Node/.NET/Python/Java)
+- Writes `.vibgrate/scan_result.json` unless disabled
+
+```bash
+# 2) Scan with CI gating
+npx @vibgrate/cli scan . --fail-on error --drift-budget 40
+```
+
+Expected result:
+
+- Exit code `0` when no error-level finding and score is within budget
+- Exit code `2` when the configured gate is exceeded
+
+```bash
+# 3) Offline scan using local package-version bundle
+npx @vibgrate/cli scan . --offline --package-manifest ./latest-packages.zip --format json --out scan.json
+```
+
+Expected result:
+
+- No registry/network lookup
+- JSON artifact in `scan.json`
+- Package freshness may be marked unknown if manifest lacks entries
+
+```bash
+# 4) Export SBOM and compare two runs
+npx @vibgrate/cli sbom export --format cyclonedx --out sbom.cdx.json
+npx @vibgrate/cli sbom delta --from .vibgrate/baseline.json --to .vibgrate/scan_result.json --out sbom-delta.txt
+```
+
+Expected result:
+
+- CycloneDX (or SPDX) JSON export file
+- Human-readable delta report with added/removed/changed dependencies
+
+Common usage:
+
+```bash
+# Standard scan
+npx @vibgrate/cli scan .
+
+# CI-ready SARIF output
+npx @vibgrate/cli scan . --format sarif --out vibgrate.sarif --fail-on error
+
+# Baseline and compare drift deltas over time
+npx @vibgrate/cli baseline .
+npx @vibgrate/cli scan . --baseline .vibgrate/baseline.json
+```
 
 ---
 
-## CI Integration
+## CI integration (recommended)
 
 ### GitHub Actions
 
 ```yaml
-- name: Vibgrate Scan
+- name: Vibgrate scan
   env:
     VIBGRATE_DSN: ${{ secrets.VIBGRATE_DSN }}
-  run: npx @vibgrate/cli scan --push --format sarif --out vibgrate.sarif --fail-on error
+  run: npx @vibgrate/cli scan . --push --format sarif --out vibgrate.sarif --fail-on error
 
 - name: Upload SARIF
   if: always()
@@ -243,63 +262,55 @@ VIBGRATE_DSN="..." vibgrate push
     sarif_file: vibgrate.sarif
 ```
 
-> **Setup:** Add your DSN as a repository secret named `VIBGRATE_DSN` under **Settings → Secrets and variables → Actions**. Get your DSN from [vibgrate.com](https://vibgrate.com) — it's generated automatically when you create a workspace.
-
 ### Azure DevOps
 
 ```yaml
-- script: npx @vibgrate/cli scan --format sarif --out vibgrate.sarif --fail-on error
-  displayName: Vibgrate Scan
+- script: npx @vibgrate/cli scan . --format sarif --out vibgrate.sarif --fail-on error
+  displayName: Vibgrate scan
 ```
 
-Works in any CI environment. No login required. No configuration needed.
+### GitLab CI
+
+```yaml
+vibgrate:
+  image: node:20
+  script:
+    - npx @vibgrate/cli scan . --push --fail-on error
+```
 
 ---
 
-## Configuration
+## Dashboard upload (optional)
 
-Optionally create a `vibgrate.config.ts` to customise thresholds and scanner toggles:
+The CLI is fully useful offline. Upload is opt-in.
+
+If you want trend analysis across runs/repos, push scan artifacts with a DSN:
 
 ```bash
-vibgrate init
+VIBGRATE_DSN="vibgrate+https://<key_id>:<secret>@us.ingest.vibgrate.com/<workspace_id>" \
+  npx @vibgrate/cli scan . --push
 ```
 
-```typescript
-import type { VibgrateConfig } from '@vibgrate/cli';
-
-const config: VibgrateConfig = {
-  exclude: ['legacy/**'],
-  thresholds: {
-    failOnError: {
-      eolDays: 180,
-      frameworkMajorLag: 3,
-      dependencyTwoPlusPercent: 50,
-    },
-  },
-};
-
-export default config;
-```
+You can also upload an existing artifact:
 
----
+```bash
+VIBGRATE_DSN="..." npx @vibgrate/cli push --file .vibgrate/scan_result.json
+```
 
-## Privacy First
+Get your DSN from [vibgrate.com](https://vibgrate.com). For CI, always store it as a secret (never commit it).
 
-Vibgrate is designed to be safe to run on any codebase:
+---
 
-- **No source code content is exfiltrated** — code-quality metrics are computed locally and only aggregated numbers are emitted
-- **Source code is only read when explicitly needed** — core drift scanners use manifests/configs; OWASP mapping can inspect source files via Semgrep
-- **No secrets are scanned** — ever
-- **No git history, authors, or commit messages** — only HEAD SHA and branch name for traceability
-- **No data leaves your machine** unless you explicitly run `vibgrate push` or `vibgrate scan --push`
-- **No login required** — works fully offline
+## Privacy and safety
 
-### `.gitignore`
+- No data leaves your machine unless you run `--push` / `vibgrate push`
+- Core drift analysis is based on manifests/configs
+- Works without login and without SaaS dependencies
+- `.vibgrate/` artifacts are local outputs and may be gitignored
 
-The `.vibgrate/` directory contains ephemeral scan results and should not be committed to version control. Add it to your `.gitignore`:
+Add this to `.gitignore`:
 
 ```gitignore
-# Vibgrate scan results (do not commit)
 .vibgrate/
 ```
 
@@ -315,6 +326,8 @@ The CLI writes per-project score files to `.vibgrate/` inside each detected proj
 | `vibgrate scan --push` | Scan and auto-push to dashboard |
 | `vibgrate baseline [path]` | Create a drift baseline |
 | `vibgrate report` | Generate a report from a scan artifact |
+| `vibgrate sbom export` | Export scan artifact as CycloneDX or SPDX SBOM |
+| `vibgrate sbom delta` | Compare two artifacts and report SBOM drift delta |
 | `vibgrate init [path]` | Initialise config and `.vibgrate/` directory |
 | `vibgrate push` | Upload scan results to dashboard |
 | `vibgrate dsn create` | Generate a DSN token |
@@ -324,22 +337,15 @@ The CLI writes per-project score files to `.vibgrate/` inside each detected proj
 
 ## Requirements
 
-- **Node.js** >= 20.0.0
-- Works on macOS, Linux, and Windows
-
----
-
-## Full Documentation
-
-See [DOCS.md](https://github.com/crowers/vibgrate-cli/blob/main/packages/vibgrate-cli/DOCS.md) for the complete reference — all commands, all flags, configuration options, extended scanner details, CI examples, and more.
+- Node.js **20+**
+- macOS, Linux, Windows
 
 ---
 
-## Links
+## Full docs
 
-- [Website](https://vibgrate.com)
-- [Documentation](https://github.com/crowers/vibgrate-cli/blob/main/packages/vibgrate-cli/DOCS.md)
+For full command reference, configuration, scanner details, and advanced examples, see [DOCS.md](./DOCS.md).
 
 ---
 
-Copyright © 2026 Vibgrate. All rights reserved. See [LICENSE.md](./LICENSE) for terms.
+Copyright © 2026 Vibgrate. All rights reserved. See [LICENSE.md](./LICENSE.md) for terms.

package/dist/{baseline-FDWMBM2O.js → baseline-K7V6GAP3.js}

@@ -1,8 +1,8 @@
 import {
   baselineCommand,
   runBaseline
-} from "./chunk-LO66M6OC.js";
-import "./chunk-YFJC5JSQ.js";
+} from "./chunk-NASGRGXK.js";
+import "./chunk-UVFIFNYG.js";
 import "./chunk-RNVZIZNL.js";
 export {
   baselineCommand,

package/dist/{chunk-LO66M6OC.js → chunk-NASGRGXK.js}

@@ -1,6 +1,6 @@
 import {
   runScan
-} from "./chunk-YFJC5JSQ.js";
+} from "./chunk-UVFIFNYG.js";
 import {
   writeJsonFile
 } from "./chunk-RNVZIZNL.js";

package/dist/{chunk-GN3IWKSY.js → chunk-PTMLMDZU.js}

@@ -51,6 +51,26 @@ function formatMarkdown(artifact) {
     }
     lines.push("");
   }
+  if (artifact.extended?.uiPurpose) {
+    const up = artifact.extended.uiPurpose;
+    lines.push("## Product Purpose Signals");
+    lines.push("");
+    lines.push(`- **Frameworks:** ${up.detectedFrameworks.length > 0 ? up.detectedFrameworks.join(", ") : "unknown"}`);
+    lines.push(`- **Evidence Items:** ${up.topEvidence.length}${up.capped ? ` (capped from ${up.evidenceCount})` : ""}`);
+    if (up.topEvidence.length > 0) {
+      lines.push("- **Top Evidence:**");
+      for (const item of up.topEvidence.slice(0, 10)) {
+        lines.push(`  - [${item.kind}] ${item.value} (${item.file})`);
+      }
+    }
+    if (up.unknownSignals.length > 0) {
+      lines.push("- **Unknowns:**");
+      for (const u of up.unknownSignals.slice(0, 5)) {
+        lines.push(`  - ${u}`);
+      }
+    }
+    lines.push("");
+  }
   if (artifact.findings.length > 0) {
     lines.push("## Findings");
     lines.push("");