@prodcycle/prodcycle 0.4.2 → 0.6.0

package/dist/api-client.js

@@ -1,58 +1,496 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ComplianceApiClient = void 0;
+exports.ComplianceApiClient = exports.ApiError = void 0;
+exports.chunkFiles = chunkFiles;
+/**
+ * Error thrown for any non-2xx response. Carries the parsed body + status so
+ * callers can branch on `details.suggestedEndpoint` (413 → chunked-session
+ * fallback) or `Retry-After` (429 / 503 → backoff + retry).
+ */
+class ApiError extends Error {
+    statusCode;
+    body;
+    retryAfterSeconds;
+    constructor(statusCode, body, retryAfterSeconds, message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.body = body;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = 'ApiError';
+    }
+}
+exports.ApiError = ApiError;
+const DEFAULT_API_URL = 'https://api.prodcycle.com';
+/**
+ * Read a positive integer from an env var or fall back to a default. Used
+ * for the timeout / retry knobs below so operators can tune behavior in CI
+ * without forking the CLI.
+ */
+function envInt(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+/**
+ * Maximum retry attempts for 429/503 responses. After this many tries we
+ * give up and surface the error to the caller.
+ */
+const MAX_RETRY_ATTEMPTS = envInt('PC_MAX_RETRY_ATTEMPTS', 4);
+/**
+ * Hard ceiling on Retry-After (seconds). Even if the server asks for more
+ * than this we cap it so the CLI doesn't appear to hang indefinitely on a
+ * misconfigured server.
+ */
+const MAX_RETRY_AFTER_SECONDS = envInt('PC_MAX_RETRY_AFTER_SECONDS', 300);
+/**
+ * Per-request fetch timeout. Without this a stalled connection would tie
+ * up the CLI indefinitely, bypassing both the retry cap and the async-poll
+ * deadline. Default is 2 minutes — long enough for the largest non-async
+ * sync `/validate` call, short enough that a hung TCP socket gets aborted.
+ */
+const REQUEST_TIMEOUT_MS = envInt('PC_REQUEST_TIMEOUT_MS', 120_000);
+/**
+ * Conservative client-side chunk sizing for the chunked-session flow. The
+ * /chunks endpoint accepts up to 50 MB / 2000 files per request, but most
+ * customer payloads are well under this and smaller chunks shorten
+ * tail-latency on a single saturated chunk. The server's per-content
+ * findings cache means re-scans of unchanged files are O(1) regardless of
+ * chunk size, so picking on the smaller side costs little.
+ */
+const DEFAULT_CHUNK_MAX_BYTES = envInt('PC_DEFAULT_CHUNK_MAX_BYTES', 5 * 1024 * 1024);
+const DEFAULT_CHUNK_MAX_FILES = envInt('PC_DEFAULT_CHUNK_MAX_FILES', 200);
+/**
+ * Async-validate poll cadence. The server typically completes scans in
+ * 10–60 s; polling every 2 s keeps the round-trip overhead bounded while
+ * still feeling responsive in interactive use.
+ */
+const ASYNC_POLL_INTERVAL_MS = envInt('PC_ASYNC_POLL_INTERVAL_MS', 2000);
+const ASYNC_POLL_TIMEOUT_MS = envInt('PC_ASYNC_POLL_TIMEOUT_MS', 10 * 60 * 1000);
+/**
+ * Keys in `options.config` that route client-side behavior (sync /
+ * async / chunked dispatch, chunk sizing) and MUST NOT be forwarded to
+ * the server. Some endpoints validate `options` strictly and would 400
+ * on unknown keys, so leaking these would silently break every call.
+ */
+const CLIENT_ONLY_CONFIG_KEYS = new Set([
+    'mode',
+    'chunkMaxBytes',
+    'chunkMaxFiles',
+]);
 class ComplianceApiClient {
     apiUrl;
     apiKey;
     constructor(apiUrl, apiKey) {
-        this.apiUrl = apiUrl || process.env.PC_API_URL || 'https://api.prodcycle.com';
+        this.apiUrl = apiUrl || process.env.PC_API_URL || DEFAULT_API_URL;
         this.apiKey = apiKey || process.env.PC_API_KEY || '';
-        if (!this.apiKey && process.env.NODE_ENV !== 'test') {
-            console.warn('Warning: PC_API_KEY is not set. API calls will likely fail.');
+        if (!this.apiKey &&
+            process.env.NODE_ENV !== 'test' &&
+            !process.env.PC_SUPPRESS_WARNINGS) {
+            process.stderr.write('Warning: PC_API_KEY is not set. API calls will likely fail.\n');
         }
     }
+    /**
+     * Synchronous validate. On a 413 with `details.suggestedEndpoint ===
+     * '/v1/compliance/scans'`, silently falls back to the chunked-session
+     * flow so large-repo CI jobs don't have to know the difference.
+     */
     async validate(files, frameworks, options = {}) {
-        return this.post('/v1/compliance/validate', {
+        try {
+            return await this.request('POST', '/v1/compliance/validate', {
+                files,
+                frameworks,
+                options: this.buildOptions(options),
+            });
+        }
+        catch (err) {
+            if (err instanceof ApiError &&
+                err.statusCode === 413 &&
+                err.body?.error?.details?.suggestedEndpoint === '/v1/compliance/scans') {
+                // Server says: this payload won't fit, use chunked sessions instead.
+                // Fall back transparently — the caller asked for `validate`, the
+                // semantics (single scanId with final findings) are preserved.
+                return this.validateChunked(files, frameworks, options);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Hook endpoint — small per-write call from coding agents. No
+     * suggestedEndpoint fallback because /hook keeps the historical 50 MB
+     * ceiling; if a single hook write exceeds that, the caller's batching
+     * is the bug to fix.
+     */
+    async hook(files, frameworks, options = {}) {
+        return this.request('POST', '/v1/compliance/hook', {
             files,
             frameworks,
-            options: {
-                severity_threshold: options.severityThreshold,
-                fail_on: options.failOn,
-                ...options.config,
-            },
+            options: this.buildOptions(options),
         });
     }
-    async hook(files, frameworks, options = {}) {
-        return this.post('/v1/compliance/hook', {
-            files,
+    // ─── Chunked sessions ───────────────────────────────────────────────────
+    /**
+     * Open a chunked scan session. Returns a `scanId` that subsequent
+     * `appendChunk` / `completeSession` calls reference. Server-side TTL is
+     * 30 minutes by default — abandoned sessions self-clean via the
+     * stale-session reaper.
+     */
+    async openSession(frameworks, options = {}) {
+        return this.request('POST', '/v1/compliance/scans', {
             frameworks,
-            options: {
-                severity_threshold: options.severityThreshold,
-                fail_on: options.failOn,
-                ...options.config,
-            },
+            options: this.buildOptions(options),
         });
     }
-    async post(endpoint, data) {
-        const url = `${this.apiUrl}${endpoint}`;
+    /**
+     * Append a chunk of files to an open session. Each call has its own
+     * /hook-style cap (50 MB / 2000 files). The server caches per-content
+     * findings, so re-scans of unchanged files are O(1).
+     */
+    async appendChunk(scanId, files) {
+        return this.request('POST', `/v1/compliance/scans/${encodeURIComponent(scanId)}/chunks`, {
+            files,
+        });
+    }
+    /**
+     * Finalize a chunked session: flips status to COMPLETED, computes
+     * summary + passed, returns final findings.
+     */
+    async completeSession(scanId) {
+        return this.request('POST', `/v1/compliance/scans/${encodeURIComponent(scanId)}/complete`, {});
+    }
+    /**
+     * High-level helper: open → append (in chunks) → complete. Returns the
+     * same shape as `validate()` so callers that auto-fallback don't have
+     * to special-case the result.
+     *
+     * Caller can pre-set `chunkMaxBytes` / `chunkMaxFiles` on `options.config`
+     * to override the conservative defaults.
+     */
+    async validateChunked(files, frameworks, options = {}) {
+        const chunkMaxBytes = options.config?.chunkMaxBytes ?? DEFAULT_CHUNK_MAX_BYTES;
+        const chunkMaxFiles = options.config?.chunkMaxFiles ?? DEFAULT_CHUNK_MAX_FILES;
+        const session = await this.openSession(frameworks, options);
+        const chunks = chunkFiles(files, chunkMaxBytes, chunkMaxFiles);
+        for (const chunk of chunks) {
+            await this.appendChunk(session.scanId, chunk);
+        }
+        const result = await this.completeSession(session.scanId);
+        const enriched = await this.backfillFindingsIfMissing(session.scanId, result);
+        return { scanId: session.scanId, ...enriched };
+    }
+    /**
+     * Some server versions of `POST /scans/:id/complete` return only the summary,
+     * leaving `findings` empty even when `summary.total > 0`. The findings are
+     * persisted on the scan record and recoverable via `GET /scans/:id`. Call
+     * this after `completeSession` (and any other path where the response shape
+     * may be summary-only) so SARIF/JSON consumers always see structured findings,
+     * not just a count. No-op when findings are already present or the scan is
+     * genuinely clean.
+     *
+     * Timeout: the follow-up GET goes through `this.request`, which wraps every
+     * fetch with `AbortSignal.timeout(REQUEST_TIMEOUT_MS)` (120 s default,
+     * tunable via `PC_REQUEST_TIMEOUT_MS`). A stalled server can't hang
+     * `validateChunked` indefinitely; if the abort fires, the catch below
+     * falls through with the original summary-only result.
+     */
+    async backfillFindingsIfMissing(scanId, result) {
+        const findingsLength = Array.isArray(result.findings) ? result.findings.length : 0;
+        const summaryTotal = result.summary?.total ?? 0;
+        if (findingsLength > 0 || summaryTotal === 0)
+            return result;
         try {
-            const response = await fetch(url, {
-                method: 'POST',
-                headers: {
-                    'Authorization': `Bearer ${this.apiKey}`,
-                    'Content-Type': 'application/json',
+            const full = await this.getScan(scanId);
+            if (Array.isArray(full.findings) && full.findings.length > 0) {
+                return { ...result, findings: full.findings };
+            }
+            // GET succeeded but findings were empty despite `summary.total > 0`.
+            // Most likely cause: eventual consistency between `/complete`'s summary
+            // computation and the scan-record findings writer. Without surfacing a
+            // signal here, the caller would see exactly the silent-drop state the
+            // backfill was added to prevent. Mark as `BACKFILL_GET_RETURNED_EMPTY`
+            // (distinct from the throw case) so consumers can branch on retry vs.
+            // hard-fail behavior.
+            const message = `findings still empty after GET /scans/${scanId} (summary reports ${summaryTotal})`;
+            process.stderr.write(`⚠ Findings backfill ${message}. ` +
+                `Run \`prodcycle scans ${scanId}\` after a short delay to retry.\n`);
+            return {
+                ...result,
+                backfillError: {
+                    code: 'BACKFILL_GET_RETURNED_EMPTY',
+                    message,
+                    scanId,
+                    summaryTotal,
                 },
-                body: JSON.stringify(data),
-            });
-            const responseData = await response.json();
-            if (!response.ok) {
-                throw new Error(responseData.error?.message || `API request failed with status ${response.status}`);
+            };
+        }
+        catch (err) {
+            // Best-effort enrichment: if the follow-up GET fails, fall through with
+            // the original result rather than break the scan call. The user still
+            // has the summary + scanId.
+            //
+            // BUT — without a user-facing signal, the resulting state (`findings: []`
+            // alongside `summary.total > 0`) looks exactly like the original bug we
+            // were fixing, and the user has no way to know they need to retry via
+            // `prodcycle scans <id>`. Surface the failure as both:
+            //   - a stderr warning (humans running the CLI interactively)
+            //   - a structured `backfillError` field (programmatic consumers / SARIF)
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`⚠ Findings backfill GET /scans/${scanId} failed (${message}). ` +
+                `${summaryTotal} finding(s) were detected but only the summary is available. ` +
+                `Run \`prodcycle scans ${scanId}\` to fetch the structured findings.\n`);
+            return {
+                ...result,
+                backfillError: {
+                    code: 'BACKFILL_GET_FAILED',
+                    message,
+                    scanId,
+                    summaryTotal,
+                },
+            };
+        }
+    }
+    // ─── Async validate ─────────────────────────────────────────────────────
+    /**
+     * Async-validate: returns a `scanId` immediately; caller polls
+     * `getScan(scanId)` until status is COMPLETED or FAILED. Useful for CI
+     * runners that don't want to hold a connection for a 60 s scan.
+     */
+    async validateAsync(files, frameworks, options = {}) {
+        return this.request('POST', '/v1/compliance/validate?async=true', {
+            files,
+            frameworks,
+            options: this.buildOptions(options),
+        });
+    }
+    /**
+     * Fetch the current state of any scan (sync, async, or chunked-session).
+     */
+    async getScan(scanId) {
+        return this.request('GET', `/v1/compliance/scans/${encodeURIComponent(scanId)}`, null);
+    }
+    /**
+     * High-level helper: kicks off an async-validate, polls until terminal,
+     * returns the same shape as `validate()`.
+     */
+    async validateAndPoll(files, frameworks, options = {}) {
+        const { scanId } = await this.validateAsync(files, frameworks, options);
+        const deadline = Date.now() + ASYNC_POLL_TIMEOUT_MS;
+        // Always poll at least once, and always do one final poll *after*
+        // the last sleep before declaring a timeout — otherwise a scan that
+        // completes during the trailing sleep window would be reported as a
+        // timeout even though the result is sitting on the server.
+        while (true) {
+            const scan = await this.getScan(scanId);
+            if (scan.status === 'COMPLETED' || scan.status === 'FAILED') {
+                return { scanId, ...scan };
             }
-            return responseData;
+            if (Date.now() >= deadline)
+                break;
+            await sleep(ASYNC_POLL_INTERVAL_MS);
         }
-        catch (error) {
-            throw new Error(`Failed to connect to ProdCycle API: ${error.message}`);
+        throw new Error(`Async validate scan ${scanId} did not complete within ${ASYNC_POLL_TIMEOUT_MS / 1000}s. Re-run with the same scanId to keep polling: prodcycle scans ${scanId}`);
+    }
+    // ─── Internals ──────────────────────────────────────────────────────────
+    buildOptions(options) {
+        const merged = {
+            severity_threshold: options.severityThreshold,
+            fail_on: options.failOn,
+        };
+        if (options.config && typeof options.config === 'object') {
+            // Strip client-routing keys (mode / chunkMaxBytes / chunkMaxFiles)
+            // before forwarding — they steer this SDK, not the server. The
+            // server's `options` schema may reject unknown keys strictly, in
+            // which case leaking these would cause 400s on every call.
+            for (const [key, value] of Object.entries(options.config)) {
+                if (CLIENT_ONLY_CONFIG_KEYS.has(key))
+                    continue;
+                merged[key] = value;
+            }
         }
+        return merged;
+    }
+    /**
+     * Single HTTP request with:
+     *   - auth header
+     *   - 429/503 + Retry-After honoring (up to MAX_RETRY_ATTEMPTS)
+     *   - structured error with parsed body so callers can introspect
+     *     `details.suggestedEndpoint` etc.
+     */
+    async request(method, endpoint, data) {
+        const url = `${this.apiUrl.replace(/\/+$/, '')}${endpoint}`;
+        let lastError = null;
+        for (let attempt = 0; attempt < MAX_RETRY_ATTEMPTS; attempt++) {
+            let response;
+            try {
+                response = await fetch(url, {
+                    method,
+                    headers: {
+                        Authorization: `Bearer ${this.apiKey}`,
+                        ...(method === 'POST' ? { 'Content-Type': 'application/json' } : {}),
+                    },
+                    ...(data !== null ? { body: JSON.stringify(data) } : {}),
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                });
+            }
+            catch (networkErr) {
+                // Connection-level failures (DNS, TCP, TLS). Treat as retryable up
+                // to the same cap as 503 — the server may be momentarily down or
+                // the network blip may resolve.
+                lastError =
+                    networkErr instanceof Error ? networkErr : new Error(String(networkErr));
+                if (attempt < MAX_RETRY_ATTEMPTS - 1) {
+                    await sleep(retryBackoffMs(attempt));
+                    continue;
+                }
+                throw new Error(`Failed to connect to ProdCycle API: ${lastError.message}`);
+            }
+            const responseText = await response.text();
+            let parsed = null;
+            try {
+                parsed = responseText ? JSON.parse(responseText) : null;
+            }
+            catch {
+                // Non-JSON body (e.g. ALB-level 502/504). Leave parsed as null;
+                // the retry path below handles based on status code.
+            }
+            if (response.ok) {
+                // Unwrap the API envelope only when the discriminant
+                // {status: "success" | "error", statusCode, data} is present.
+                // Bare key presence isn't enough: a `ScanResult` already has a
+                // `status` field (PASSED/FAILED/IN_PROGRESS) and an open index
+                // signature, so checking only for `'status' in parsed && 'data'
+                // in parsed` would misidentify a scan result that happens to
+                // include a `data` key as an envelope and silently drop the
+                // top-level `passed`, `scanId`, `findings` fields.
+                if (isApiEnvelope(parsed)) {
+                    return parsed.data;
+                }
+                return parsed ?? {};
+            }
+            // Non-2xx. Inspect the body + Retry-After to decide whether to retry.
+            const retryAfterSeconds = parseRetryAfter(response.headers.get('retry-after'));
+            const errorBody = parsed ?? null;
+            const errorMessage = errorBody?.error?.message ?? `API request failed with status ${response.status}`;
+            const isRetryable = response.status === 429 || response.status === 503;
+            if (isRetryable && attempt < MAX_RETRY_ATTEMPTS - 1) {
+                const delayMs = retryAfterSeconds != null ? retryAfterSeconds * 1000 : retryBackoffMs(attempt);
+                const cappedDelayMs = Math.min(delayMs, MAX_RETRY_AFTER_SECONDS * 1000);
+                await sleep(cappedDelayMs);
+                continue;
+            }
+            throw new ApiError(response.status, errorBody, retryAfterSeconds, errorMessage);
+        }
+        // Unreachable in practice: every iteration returns, throws, or
+        // continues. Kept only to satisfy the type-checker that this method
+        // always returns or throws.
+        /* istanbul ignore next */
+        throw lastError ?? new Error('Exhausted retries without a response');
     }
 }
 exports.ComplianceApiClient = ComplianceApiClient;
+// ─── Helpers ──────────────────────────────────────────────────────────────
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Exponential backoff with jitter for retryable errors that don't carry an
+ * explicit Retry-After (network failures, malformed 503).
+ */
+function retryBackoffMs(attempt) {
+    const base = 1000 * 2 ** attempt; // 1s, 2s, 4s, 8s, ...
+    const jitter = Math.random() * 500;
+    return base + jitter;
+}
+/**
+ * Parse Retry-After header. Spec allows either:
+ *   - delta-seconds (an integer)
+ *   - HTTP-date
+ * We support both. Returns seconds as a non-negative integer, or null if
+ * the header is missing/unparseable.
+ */
+/**
+ * Detect the API's *success* envelope shape strictly: a plain object
+ * whose `status` is exactly "success" and that carries a `data`
+ * payload. We deliberately do NOT match `status: "error"` here because
+ * `isApiEnvelope` is only consulted on the 2xx branch — accepting an
+ * error envelope on a 200 response would silently return `null as T`
+ * to the caller without ever raising, so downstream code would see
+ * `passed: undefined` with no signal that anything went wrong. Non-2xx
+ * error envelopes are handled by the explicit error path below.
+ *
+ * The strict-discriminant check is also necessary because `ScanResult`
+ * itself has a `status` field (PASSED/FAILED/IN_PROGRESS) and an open
+ * index signature, so a bare scan result with a `data` key would be
+ * misidentified as an envelope and have its top-level fields dropped.
+ */
+function isApiEnvelope(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return v.status === 'success' && 'data' in v;
+}
+function parseRetryAfter(value) {
+    if (!value)
+        return null;
+    const asInt = Number.parseInt(value, 10);
+    if (!Number.isNaN(asInt))
+        return Math.max(0, asInt);
+    const asDate = Date.parse(value);
+    if (!Number.isNaN(asDate)) {
+        return Math.max(0, Math.ceil((asDate - Date.now()) / 1000));
+    }
+    return null;
+}
+/**
+ * Split a `{ path: content }` map into chunks that respect both a byte
+ * cap and a file-count cap. UTF-8 byte-length is used since the server
+ * counts the request body's bytes after JSON serialisation; this is a
+ * conservative client-side approximation.
+ */
+// Per-file overhead in the JSON-serialized request body. Each entry is
+// `"path":"content",` which adds two pairs of quotes (4 bytes), one
+// colon, one comma, and a small margin for backslash-escapes inside the
+// content. 16 bytes is a conservative upper bound; the goal is to avoid
+// undersizing — the server enforces the real cap.
+const PER_FILE_JSON_OVERHEAD = 16;
+// One-time wrapper overhead for the chunk request body itself
+// (`{"files":{...}}`).
+const PER_CHUNK_JSON_OVERHEAD = 16;
+function chunkFiles(files, maxBytes, maxFiles) {
+    const chunks = [];
+    let current = {};
+    let currentBytes = PER_CHUNK_JSON_OVERHEAD;
+    let currentCount = 0;
+    for (const [filePath, content] of Object.entries(files)) {
+        const fileBytes = Buffer.byteLength(content, 'utf8') +
+            Buffer.byteLength(filePath, 'utf8') +
+            PER_FILE_JSON_OVERHEAD;
+        // If a single file exceeds the cap on its own we can't split it further
+        // here — emit it as its own chunk and let the server's per-file cap (if
+        // any) reject if needed. Common case: huge SQL dumps, generated bundles.
+        if (fileBytes + PER_CHUNK_JSON_OVERHEAD > maxBytes) {
+            if (currentCount > 0) {
+                chunks.push(current);
+                current = {};
+                currentBytes = PER_CHUNK_JSON_OVERHEAD;
+                currentCount = 0;
+            }
+            chunks.push({ [filePath]: content });
+            continue;
+        }
+        if (currentBytes + fileBytes > maxBytes || currentCount + 1 > maxFiles) {
+            chunks.push(current);
+            current = {};
+            currentBytes = PER_CHUNK_JSON_OVERHEAD;
+            currentCount = 0;
+        }
+        current[filePath] = content;
+        currentBytes += fileBytes;
+        currentCount += 1;
+    }
+    if (currentCount > 0) {
+        chunks.push(current);
+    }
+    return chunks;
+}

package/dist/cli.d.ts

@@ -1,2 +1,15 @@
 #!/usr/bin/env node
-export {};
+/**
+ * Detect CI environment via well-known env vars set by the major
+ * platforms. When CI is detected, default `--format` flips to `sarif`
+ * (so output drops straight into GitHub code scanning / GitLab security
+ * dashboards / etc. without extra configuration). Users can still
+ * override with `--format table|json|prompt`.
+ *
+ * The flip is opt-out (set `--format table` explicitly to keep the
+ * human-readable output in CI logs). Heuristic, not load-bearing — if
+ * we miss a CI platform here the user gets the same default they
+ * would have anyway (`table`), they just have to add `--format sarif`
+ * by hand.
+ */
+export declare function isCiEnvironment(env?: NodeJS.ProcessEnv): boolean;