@vibgrate/cli 1.0.46 → 1.0.47

package/DOCS.md

@@ -1,6 +1,6 @@
 # Vibgrate CLI — Full Documentation
 
-> Continuous Drift Intelligence for Node, .NET, Python, and Java
+> Continuous Drift Intelligence for Node, .NET, Python, and Java (all supported in the CLI today)
 
 For a quick overview, see the [README](./README.md). This document covers everything in detail.
 
@@ -93,6 +93,48 @@ In practice, one-off scans tell you where you are today; CI keeps you from drift
 
 ---
 
+## Feature coverage and practical usage guide
+
+This section summarizes what the CLI supports today and how to use each capability effectively.
+
+### Supported project ecosystems
+
+Vibgrate currently discovers and evaluates projects in:
+
+- **Node.js / TypeScript** (`package.json`, lockfiles)
+- **.NET** (`.sln`, `.csproj`)
+- **Python** (`requirements.txt`, `pyproject.toml`-style manifests)
+- **Java** (`pom.xml`, Gradle-style manifests)
+
+### End-to-end workflow (recommended)
+
+1. Run an initial scan.
+2. Save a baseline on your main branch.
+3. Enforce drift gates in CI.
+4. Export/report artifacts for stakeholders.
+
+Example:
+
+```bash
+# Step 1: first scan
+vibgrate scan .
+
+# Step 2: baseline
+vibgrate baseline .
+
+# Step 3: policy in CI
+vibgrate scan . --baseline .vibgrate/baseline.json --drift-budget 40 --drift-worsening 5 --fail-on error
+
+# Step 4: produce report
+vibgrate report --in .vibgrate/scan_result.json --format md
+```
+
+Expected results:
+
+- Teams get a stable score trend instead of one-time snapshots.
+- CI fails early when drift budgets are exceeded (exit code `2`).
+- Markdown/JSON/SARIF outputs are ready for engineering and governance workflows.
+
 ## Commands Reference
 
 ### vibgrate init
@@ -120,7 +162,7 @@ Creates:
 The primary command. Scans your project for upgrade drift.
 
 ```bash
-vibgrate scan [path] [--format text|json|sarif] [--out <file>] [--fail-on warn|error] [--baseline <file>] [--drift-budget <score>] [--drift-worsening <percent>] [--changed-only] [--concurrency <n>]
+vibgrate scan [path] [--format text|json|sarif] [--out <file>] [--fail-on warn|error] [--offline] [--package-manifest <file>] [--no-local-artifacts] [--max-privacy] [--baseline <file>] [--drift-budget <score>] [--drift-worsening <percent>] [--changed-only] [--concurrency <n>]
 ```
 
 | Flag | Default | Description |
@@ -133,8 +175,42 @@ vibgrate scan [path] [--format text|json|sarif] [--out <file>] [--fail-on warn|e
 | `--concurrency <n>` | `8` | Max concurrent npm registry calls |
 | `--drift-budget <score>` | — | Fitness gate: fail if drift score is above this budget |
 | `--drift-worsening <percent>` | — | Fitness gate: fail if drift worsens by more than % vs baseline |
+| `--push` | — | Upload scan artifact to dashboard after a successful scan |
+| `--dsn <dsn>` | `VIBGRATE_DSN` env | DSN used for `--push` authentication |
+| `--region <region>` | — | Override data residency (`us`, `eu`) during push |
+| `--strict` | — | Fail scan command if push fails |
+| `--install-tools` | — | Auto-install missing local security tools via Homebrew |
+| `--ui-purpose` | — | Enable optional UI-purpose evidence extraction |
+| `--offline` | — | Disable network calls and disable upload/push behavior |
+| `--package-manifest <file>` | — | JSON or ZIP package-version manifest used for offline/latest lookups (latest bundle: `https://github.com/vibgrate/manifests/latest-packages.zip`) |
+| `--no-local-artifacts` | — | Do not write `.vibgrate/*.json` scan artifacts to disk |
+| `--max-privacy` | — | Hardened privacy mode with minimal scanners and no local artifacts |
 
-The scan always writes the full artifact to `.vibgrate/scan_result.json`.
+By default, the scan writes `.vibgrate/scan_result.json`. Use `--no-local-artifacts` or `--max-privacy` to suppress local JSON artifact files.
+
+For offline drift scoring, pass `--package-manifest <file>` with a downloaded manifest bundle such as `https://github.com/vibgrate/manifests/latest-packages.zip`.
+
+Examples:
+
+```bash
+# Standard text scan
+vibgrate scan .
+
+# JSON output for automation
+vibgrate scan . --format json --out scan.json
+
+# CI gate with baseline regression protection
+vibgrate scan . --baseline .vibgrate/baseline.json --drift-budget 40 --drift-worsening 5 --fail-on error
+
+# Upload result in the same command
+vibgrate scan . --push --strict
+```
+
+Expected results:
+
+- Clear score/risk output in terminal (or JSON/SARIF when selected).
+- Exit code `2` when configured quality gates are exceeded.
+- When `--push` is enabled, artifact upload is attempted after scan completion.
 
 ---
 
@@ -418,7 +494,17 @@ Vibgrate artifacts include dependency graph and package inventory data that can
 - Phantom dependency evidence (`phantomDependencies` + details)
 - Inventory metadata that pairs well with internal SBOM pipelines
 
-> Vibgrate does not currently emit CycloneDX/SPDX files directly. Instead, it provides structured inventory data in `scan_result.json` so teams can integrate with existing SBOM tooling without slowing down CI scans.
+Vibgrate supports both direct SBOM export (`vibgrate sbom export`) and raw inventory consumption from `scan_result.json`, so teams can choose either built-in output or custom SBOM pipelines.
+
+Example:
+
+```bash
+vibgrate sbom export --in .vibgrate/scan_result.json --format spdx --out sbom.spdx.json
+```
+
+Expected result:
+
+- A standards-based SBOM file (`spdx` or `cyclonedx`) is written for downstream governance tooling.
 
 ### Tooling Inventory
 
@@ -483,12 +569,11 @@ Structural security hygiene indicators (not a secret scanner):
 
 ### Security Scanners
 
-Security scanner orchestration and readiness analysis focused on modern SAST and secrets tooling:
+Security scanner orchestration and readiness analysis for local policy and secret-scanning workflows:
 
-- Semgrep support for SAST (version detection + freshness checks)
-- Gitleaks and TruffleHog support for secret scanning readiness
-- Recommended minimum version checks to highlight stale engines/signatures
-- Config discovery (`.semgrep.yml`, `.gitleaks.toml`, `.trufflehog.yml`)
+- Scanner engine discovery (installed vs missing)
+- Version freshness checks to flag stale scanner engines/signatures
+- Local config discovery for scanner policy files
 - Cache-backed heuristic secret signals to add value even when binaries are unavailable
 
 > This scanner does not guarantee full secret detection or rule coverage by itself; it reports toolchain status and lightweight in-repo indicators so teams can decide how to harden CI enforcement.
@@ -527,7 +612,7 @@ Fast AST-based quality checks to identify upgrade friction hotspots:
 
 ### OWASP Category Mapping
 
-Maps Semgrep OSS findings into OWASP Top 10 categories for security triage inside existing drift reports:
+Maps security findings into OWASP Top 10 categories for security triage inside existing drift reports:
 
 - Supports `fast` and `cache-input` modes
 - Categorizes findings with severity and CWE metadata

package/README.md

@@ -22,6 +22,8 @@ In one command, you get:
 - Dependency age distribution + EOL proximity
 - Priority actions for what to fix next
 
+Supported ecosystems today: **Node.js/TypeScript, .NET, Python, and Java**.
+
 ---
 
 ## Why teams adopt Vibgrate
@@ -110,11 +112,11 @@ Beyond core drift scoring, Vibgrate can also detect:
 - Full tooling inventory and build/deploy surface
 - TypeScript modernity and breaking-change exposure
 - File hotspots and structural security posture
-- Security scanner readiness (Semgrep / Gitleaks / TruffleHog)
+- 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 Semgrep OSS findings
+- OWASP category mapping from security findings
 
 ### 3) SBOM Export & Delta
 
@@ -153,10 +155,28 @@ This turns drift scoring into a quality gate instead of passive reporting.
 
 ---
 
+
+## Privacy & offline-first workflows
+
+Vibgrate now supports explicit privacy controls:
+
+- `--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`.
+
+Example:
+
+```bash
+vibgrate scan . --offline --package-manifest ./package-versions.zip --max-privacy --format json --out scan.json
+```
+
+When offline mode runs without a package manifest, package freshness is marked as unknown and drift scoring is necessarily partial.
+
 ## Core commands
 
 ```bash
-vibgrate scan [path] [--format text|json|sarif] [--out <file>] [--fail-on warn|error]
+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]
@@ -164,6 +184,51 @@ vibgrate init [path] [--baseline] [--yes]
 vibgrate dsn create --workspace <id> [--region us|eu] [--write <path>]
 ```
 
+### Command examples with expected results
+
+```bash
+# 1) Scan current repo (text output)
+npx @vibgrate/cli scan .
+```
+
+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

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

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

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

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