@checkvibe/ci 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CheckVibe
+
+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,28 @@
+# @checkvibe/ci
+
+Run CheckVibe's pull-request security review from any CI job and fail the build on what the pull request introduces.
+
+```yaml
+# GitHub Actions
+- run: npx @checkvibe/ci pr-scan --fail-on high
+  env:
+    CHECKVIBE_API_KEY: ${{ secrets.CHECKVIBE_API_KEY }}
+```
+
+```yaml
+# GitLab CI
+checkvibe:
+  script: npx @checkvibe/ci pr-scan --fail-on high
+  only: [merge_requests]
+```
+
+The repository and pull request are read from the CI's own variables (`GITHUB_REPOSITORY`/`GITHUB_REF`, `CI_PROJECT_PATH`/`CI_MERGE_REQUEST_IID`, `BITBUCKET_REPO_FULL_NAME`/`BITBUCKET_PR_ID`) or passed with `--repo` and `--pr`. The API key needs the `scan:write` and `scan:read` scopes (Settings › API keys). The repository must already be connected to CheckVibe.
+
+| Exit | Meaning |
+|---|---|
+| 0 | passed |
+| 1 | blocked: new findings at or above `--fail-on` (or the repository's threshold; the Merge Gate's verdict wins when it ran) |
+| 2 | the review did not complete, or timed out (`--timeout`, default 600 s) |
+| 3 | usage or authentication error |
+
+`--json` prints the scan as the API returns it. `--full` skips the fast lane and clones the repository in full. On GitHub Actions each finding is also emitted as a `::error`/`::warning` annotation on its line.

package/bin/checkvibe-ci.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { decideExit, EXIT, inferPullRequest, isTerminal, parseArgs, renderText, USAGE } from '../src/index.mjs';
+
+const args = parseArgs(process.argv.slice(2));
+const command = args._[0];
+if (command !== 'pr-scan' || args.help) {
+    console.log(USAGE);
+    process.exit(command ? EXIT.PASS : EXIT.USAGE);
+}
+const apiKey = args['api-key'] ?? process.env.CHECKVIBE_API_KEY;
+if (!apiKey) {
+    console.error('checkvibe-ci: no API key — pass --api-key or set CHECKVIBE_API_KEY');
+    process.exit(EXIT.USAGE);
+}
+const inferred = inferPullRequest(process.env);
+const repo = args.repo ?? inferred?.repo;
+const pr = Number(args.pr ?? inferred?.pr);
+if (!repo || !Number.isInteger(pr) || pr < 1) {
+    console.error('checkvibe-ci: could not tell which pull request this is — pass --repo and --pr');
+    process.exit(EXIT.USAGE);
+}
+const origin = (args.origin ?? process.env.CHECKVIBE_ORIGIN ?? 'https://checkvibe.dev').replace(/\/$/, '');
+const timeoutMs = Number(args.timeout ?? 600) * 1000;
+const intervalMs = Math.max(2, Number(args.interval ?? 5)) * 1000;
+const headers = { 'content-type': 'application/json', authorization: `Bearer ${apiKey}`, 'user-agent': 'checkvibe-ci/0.1' };
+const onActions = !!process.env.GITHUB_ACTIONS;
+
+async function api(path, init) {
+    const res = await fetch(`${origin}${path}`, { ...init, headers, signal: AbortSignal.timeout(30_000) });
+    const text = await res.text();
+    let body = null;
+    try { body = JSON.parse(text); } catch { /* prose error */ }
+    return { ok: res.ok, status: res.status, body, text };
+}
+
+const started = await api('/api/v1/pr-scans', { method: 'POST', body: JSON.stringify({ repo, pr_number: pr, full: !!args.full }) });
+if (!started.ok || !started.body?.id) {
+    console.error(`checkvibe-ci: could not start the review (${started.status}): ${started.body?.message ?? started.body?.error ?? started.text.slice(0, 200)}`);
+    process.exit(started.status === 401 || started.status === 403 ? EXIT.USAGE : EXIT.INCOMPLETE);
+}
+const id = started.body.id;
+if (!args.json) console.log(`checkvibe-ci: review ${id} ${started.body.result} · ${started.body.dashboard_url}`);
+
+const deadline = Date.now() + timeoutMs;
+let scan = null;
+for (;;) {
+    const res = await api(`/api/v1/pr-scans/${id}`, { method: 'GET' });
+    if (res.ok && res.body) {
+        scan = res.body;
+        if (isTerminal(scan.status)) break;
+    } else if (res.status === 401 || res.status === 403 || res.status === 404) {
+        console.error(`checkvibe-ci: poll refused (${res.status})`);
+        process.exit(EXIT.USAGE);
+    }
+    if (Date.now() >= deadline) {
+        console.error(`checkvibe-ci: timed out after ${timeoutMs / 1000}s — the review is still running: ${origin}/dashboard/repositories/pull-requests/${id}`);
+        process.exit(EXIT.INCOMPLETE);
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+}
+if (args.json) console.log(JSON.stringify(scan, null, 2));
+else console.log(renderText(scan, { actions: onActions }));
+process.exit(decideExit(scan, args['fail-on']));

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@checkvibe/ci",
+  "version": "0.1.0",
+  "description": "Run CheckVibe's pull-request security review from any CI job and fail the build on what the pull request introduces. Zero dependencies.",
+  "type": "module",
+  "bin": { "checkvibe-ci": "./bin/checkvibe-ci.mjs" },
+  "main": "./src/index.mjs",
+  "files": ["bin", "src", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "scripts": { "test": "node --test test/*.test.mjs" },
+  "keywords": ["security", "ci", "pull-request", "sast", "secrets", "dependencies"],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/YvesMatteo/VibeCodeDetector.git", "directory": "packages/checkvibe-ci" },
+  "homepage": "https://checkvibe.dev",
+  "publishConfig": { "access": "public" }
+}

package/src/index.mjs

@@ -0,0 +1,85 @@
+/**
+ * The pure parts of `checkvibe-ci pr-scan`: reading the pull request from
+ * the CI environment, deciding an exit code, rendering the result. No
+ * network here — the bin wires these to fetch.
+ */
+
+export const EXIT = Object.freeze({ PASS: 0, BLOCKED: 1, INCOMPLETE: 2, USAGE: 3 });
+
+const SEV_RANK = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+const THRESHOLD_RANK = { never: null, critical: 0, high: 1, medium: 2, all: 4 };
+
+/** The repository and pull request the job is running for, from the CI's own variables. */
+export function inferPullRequest(env) {
+    // GitHub Actions: GITHUB_REPOSITORY=owner/name, GITHUB_REF=refs/pull/N/merge
+    const ghRef = /^refs\/pull\/(\d+)\//.exec(env.GITHUB_REF ?? '');
+    if (env.GITHUB_REPOSITORY && ghRef) return { repo: env.GITHUB_REPOSITORY, pr: Number(ghRef[1]), provider: 'github' };
+    // GitLab CI: CI_PROJECT_PATH=group/project, CI_MERGE_REQUEST_IID=N
+    if (env.CI_PROJECT_PATH && env.CI_MERGE_REQUEST_IID) return { repo: env.CI_PROJECT_PATH, pr: Number(env.CI_MERGE_REQUEST_IID), provider: 'gitlab' };
+    // Bitbucket Pipelines: BITBUCKET_REPO_FULL_NAME=workspace/repo, BITBUCKET_PR_ID=N
+    if (env.BITBUCKET_REPO_FULL_NAME && env.BITBUCKET_PR_ID) return { repo: env.BITBUCKET_REPO_FULL_NAME, pr: Number(env.BITBUCKET_PR_ID), provider: 'bitbucket' };
+    return null;
+}
+
+/** `--flag value` / `--flag=value` / `--bool`. Positionals kept in `_`. */
+export function parseArgs(argv) {
+    const out = { _: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith('--')) { out._.push(a); continue; }
+        const eq = a.indexOf('=');
+        if (eq >= 0) { out[a.slice(2, eq)] = a.slice(eq + 1); continue; }
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith('--')) { out[a.slice(2)] = next; i++; }
+        else out[a.slice(2)] = true;
+    }
+    return out;
+}
+
+export function isTerminal(status) {
+    return status === 'completed' || status === 'partial' || status === 'failed' || status === 'skipped';
+}
+
+/**
+ * The exit code for a finished scan. `failOn` overrides the repository's
+ * configured threshold when given; the gate's own verdict wins when it ran.
+ */
+export function decideExit(scan, failOn) {
+    if (!isTerminal(scan.status)) return EXIT.INCOMPLETE;
+    if (scan.status === 'failed' || scan.status === 'skipped') return EXIT.INCOMPLETE;
+    if (scan.gate && scan.gate.verdict) return scan.gate.passed ? EXIT.PASS : EXIT.BLOCKED;
+    const threshold = failOn ?? scan.gate?.fail_on ?? 'never';
+    const rank = THRESHOLD_RANK[threshold];
+    if (rank === null || rank === undefined) return EXIT.PASS;
+    const blocking = (scan.findings ?? []).filter((f) => f.novelty !== 'existing' && (SEV_RANK[f.severity] ?? 9) <= rank);
+    return blocking.length ? EXIT.BLOCKED : EXIT.PASS;
+}
+
+/** One line per finding, plus GitHub Actions annotations when running there. */
+export function renderText(scan, { actions = false } = {}) {
+    const lines = [];
+    const c = scan.counts ?? {};
+    lines.push(`CheckVibe · ${scan.repo} #${scan.pr_number} · ${scan.status}${scan.error ? ` (${scan.error})` : ''}`);
+    if (typeof c.new === 'number') lines.push(`${c.new} new · ${c.solved ?? '?'} solved · ${c.existing ?? 0} pre-existing · ${c.files_changed ?? '?'} files changed${c.truncated ? ' · list truncated' : ''}`);
+    for (const f of scan.findings ?? []) {
+        const where = f.file ? `${f.file}${f.line ? `:${f.line}` : ''}` : f.package ?? '';
+        lines.push(`  [${f.severity}] ${f.title}${where ? ` — ${where}` : ''}${f.novelty === 'undetermined' ? ' (unplaced, treated as new)' : ''}`);
+        if (actions && f.file) {
+            const level = f.severity === 'critical' || f.severity === 'high' ? 'error' : 'warning';
+            lines.push(`::${level} file=${f.file}${f.line ? `,line=${f.line}` : ''},title=CheckVibe::${f.title.replace(/[\r\n]/g, ' ')}`);
+        }
+    }
+    if (scan.gate) lines.push(scan.gate.passed === null ? 'gate: not decided' : scan.gate.passed ? `gate: passed (fails at ${scan.gate.fail_on})` : `gate: FAILED — ${scan.gate.blocking_count} blocking at ${scan.gate.fail_on}`);
+    lines.push(scan.dashboard_url);
+    return lines.join('\n');
+}
+
+export const USAGE = `checkvibe-ci pr-scan [--repo owner/name] [--pr N] [--fail-on never|critical|high|medium|all]
+                      [--timeout 600] [--interval 5] [--full] [--json] [--api-key KEY] [--origin https://checkvibe.dev]
+
+Starts CheckVibe's pull-request security review and waits for it. Repository and
+pull request are read from GITHUB_REPOSITORY/GITHUB_REF, CI_PROJECT_PATH/
+CI_MERGE_REQUEST_IID or BITBUCKET_REPO_FULL_NAME/BITBUCKET_PR_ID when not given.
+The API key comes from --api-key or CHECKVIBE_API_KEY (scopes scan:write + scan:read).
+
+Exit codes: 0 passed · 1 blocked by findings · 2 review did not complete · 3 usage or auth error.`;