@prodcycle/prodcycle 0.4.2 → 0.5.0

package/dist/api-client.d.ts

@@ -16,11 +16,123 @@ export interface GateOptions {
     apiUrl?: string;
     config?: Record<string, unknown>;
 }
+export interface ScanResult {
+    scanId?: string;
+    passed: boolean;
+    findingsCount?: number;
+    findings?: unknown[];
+    summary?: unknown;
+    prompt?: string;
+    status?: 'IN_PROGRESS' | 'COMPLETED' | 'FAILED';
+    [key: string]: unknown;
+}
+interface ApiErrorBody {
+    status: 'error';
+    statusCode: number;
+    error?: {
+        type?: string;
+        message?: string;
+        suggestion?: string;
+        details?: {
+            maxBytes?: number;
+            maxFiles?: number;
+            chunkSizeBytes?: number;
+            receivedBytes?: number;
+            suggestedEndpoint?: string;
+            [key: string]: unknown;
+        };
+    };
+}
+/**
+ * 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).
+ */
+export declare class ApiError extends Error {
+    readonly statusCode: number;
+    readonly body: ApiErrorBody | null;
+    readonly retryAfterSeconds: number | null;
+    constructor(statusCode: number, body: ApiErrorBody | null, retryAfterSeconds: number | null, message: string);
+}
 export declare class ComplianceApiClient {
     private apiUrl;
     private apiKey;
     constructor(apiUrl?: string, apiKey?: string);
-    validate(files: Record<string, string>, frameworks: string[], options?: ScanOptions): Promise<any>;
-    hook(files: Record<string, string>, frameworks: string[], options?: ScanOptions): Promise<any>;
-    private post;
+    /**
+     * 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.
+     */
+    validate(files: Record<string, string>, frameworks: string[], options?: ScanOptions): Promise<ScanResult>;
+    /**
+     * 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.
+     */
+    hook(files: Record<string, string>, frameworks: string[], options?: ScanOptions): Promise<ScanResult>;
+    /**
+     * 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.
+     */
+    openSession(frameworks: string[], options?: ScanOptions): Promise<{
+        scanId: string;
+        chunkSizeBytes: number;
+        maxFilesPerChunk: number;
+        expiresAt: string;
+    }>;
+    /**
+     * 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).
+     */
+    appendChunk(scanId: string, files: Record<string, string>): Promise<{
+        filesScanned: number;
+        cachedFiles: number;
+        findingsAdded: number;
+    }>;
+    /**
+     * Finalize a chunked session: flips status to COMPLETED, computes
+     * summary + passed, returns final findings.
+     */
+    completeSession(scanId: string): Promise<ScanResult>;
+    /**
+     * 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.
+     */
+    validateChunked(files: Record<string, string>, frameworks: string[], options?: ScanOptions): Promise<ScanResult>;
+    /**
+     * 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.
+     */
+    validateAsync(files: Record<string, string>, frameworks: string[], options?: ScanOptions): Promise<{
+        scanId: string;
+    }>;
+    /**
+     * Fetch the current state of any scan (sync, async, or chunked-session).
+     */
+    getScan(scanId: string): Promise<ScanResult>;
+    /**
+     * High-level helper: kicks off an async-validate, polls until terminal,
+     * returns the same shape as `validate()`.
+     */
+    validateAndPoll(files: Record<string, string>, frameworks: string[], options?: ScanOptions): Promise<ScanResult>;
+    private buildOptions;
+    /**
+     * 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.
+     */
+    private request;
 }
+export declare function chunkFiles(files: Record<string, string>, maxBytes: number, maxFiles: number): Record<string, string>[];
+export {};

package/dist/api-client.js

@@ -1,58 +1,424 @@
 "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', {
+    // ─── 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: this.buildOptions(options),
+        });
+    }
+    /**
+     * 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);
+        return { scanId: session.scanId, ...result };
+    }
+    // ─── 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: {
-                severity_threshold: options.severityThreshold,
-                fail_on: options.failOn,
-                ...options.config,
-            },
+            options: this.buildOptions(options),
         });
     }
-    async post(endpoint, data) {
-        const url = `${this.apiUrl}${endpoint}`;
-        try {
-            const response = await fetch(url, {
-                method: 'POST',
-                headers: {
-                    'Authorization': `Bearer ${this.apiKey}`,
-                    'Content-Type': 'application/json',
-                },
-                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}`);
+    /**
+     * 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 };
+            }
+            if (Date.now() >= deadline)
+                break;
+            await sleep(ASYNC_POLL_INTERVAL_MS);
+        }
+        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 responseData;
         }
-        catch (error) {
-            throw new Error(`Failed to connect to ProdCycle API: ${error.message}`);
+        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.js

@@ -43,6 +43,7 @@ const sarif_1 = require("./formatters/sarif");
 const prompt_1 = require("./formatters/prompt");
 const KNOWN_COMMANDS = new Set([
     'scan',
+    'scans',
     'gate',
     'hook',
     'init',
@@ -123,13 +124,29 @@ program
     .option('--output <file>', 'Write report to file')
     .option('--api-url <url>', 'Compliance API base URL (or PC_API_URL env)')
     .option('--api-key <key>', 'API key for compliance API (or PC_API_KEY env)')
+    .option('--async', 'Use the async-validate flow (server returns 202 immediately; CLI polls until COMPLETED). Useful for large scans where holding a connection isn’t practical.')
+    .option('--chunked', 'Force the chunked-session flow regardless of payload size. The default already auto-falls-back to chunked when /validate returns 413 with a chunked-endpoint suggestion.')
     .action(async (repoPath, opts) => {
     try {
         const target = repoPath ?? '.';
         const frameworks = parseList(opts.framework) ?? ['soc2'];
         const failOn = parseList(opts.failOn) ?? ['critical', 'high'];
         const format = (opts.format ?? 'table');
-        console.error(`Scanning ${path.resolve(target)} for ${frameworks.join(', ')}...`);
+        // --async and --chunked are mutually exclusive; pick the explicit
+        // mode if either flag is set, otherwise let `scan()` pick (sync
+        // with auto-fallback to chunked on 413).
+        let mode = 'sync';
+        if (opts.async && opts.chunked) {
+            console.error('scan: --async and --chunked are mutually exclusive.');
+            process.exit(2);
+        }
+        if (opts.async)
+            mode = 'async';
+        else if (opts.chunked)
+            mode = 'chunked';
+        console.error(`Scanning ${path.resolve(target)} for ${frameworks.join(', ')}` +
+            (mode === 'sync' ? '' : ` (${mode} mode)`) +
+            '...');
         const response = await (0, index_1.scan)({
             repoPath: target,
             frameworks,
@@ -140,6 +157,7 @@ program
                 exclude: parseList(opts.exclude),
                 apiUrl: opts.apiUrl,
                 apiKey: opts.apiKey,
+                config: { mode },
             },
         });
         writeOutput(renderReport(response, format), opts.output);
@@ -196,6 +214,46 @@ program
         process.exit(2);
     }
 });
+// ── scans ───────────────────────────────────────────────────────────────────
+// Fetch the current status / final result of any scan by ID. Useful with
+// `--async` to resume a poll loop after a CI step boundary, or to inspect
+// a chunked session that was abandoned mid-flight.
+program
+    .command('scans <scanId>')
+    .description('Get the status + findings of a scan by ID')
+    .option('--format <format>', 'Output format: json, sarif, table, prompt', 'json')
+    .option('--output <file>', 'Write report to file')
+    .option('--api-url <url>', 'Compliance API base URL (or PC_API_URL env)')
+    .option('--api-key <key>', 'API key for compliance API (or PC_API_KEY env)')
+    .action(async (scanId, opts) => {
+    try {
+        const format = (opts.format ?? 'json');
+        const { ComplianceApiClient } = await Promise.resolve().then(() => __importStar(require('./api-client')));
+        const client = new ComplianceApiClient(opts.apiUrl, opts.apiKey);
+        const scan = await client.getScan(scanId);
+        const payload = {
+            scanId,
+            passed: scan.passed,
+            status: scan.status ?? 'COMPLETED',
+            findings: scan.findings ?? [],
+            summary: scan.summary,
+            exitCode: scan.passed ? 0 : 1,
+        };
+        // Use the same renderer as `scan` so format=table/sarif/prompt all work.
+        writeOutput(renderReport(payload, format), opts.output);
+        // Exit 2 if scan is still in progress — the CLI run shouldn't gate on
+        // an indeterminate result.
+        if (scan.status === 'IN_PROGRESS') {
+            console.error(`Scan ${scanId} is still IN_PROGRESS. Re-run the same command to keep polling, or use 'pc scan --async' to wait for completion.`);
+            process.exit(2);
+        }
+        process.exit(payload.exitCode);
+    }
+    catch (error) {
+        console.error(`✗ Error: ${error.message}`);
+        process.exit(2);
+    }
+});
 // ── hook ────────────────────────────────────────────────────────────────────
 program
     .command('hook')

package/dist/index.d.ts

@@ -3,33 +3,37 @@ export * from './api-client';
 export * from './formatters/table';
 export * from './formatters/prompt';
 export * from './formatters/sarif';
+interface ScanReturn {
+    scanId?: string;
+    passed: boolean;
+    exitCode: number;
+    findings: unknown[];
+    report: unknown;
+    summary: unknown;
+}
 /**
- * Scan a repository by collecting files and sending them to the API
+ * Scan a repository by collecting files and sending them to the API.
+ *
+ * Modes (selectable via `options.config`):
+ *   - default: synchronous validate; auto-falls-back to chunked sessions
+ *     if the server returns 413 with `suggestedEndpoint=/v1/compliance/scans`
+ *   - `mode: 'async'`: kicks off a 202 async-validate and polls until
+ *     terminal (returns same shape as default)
+ *   - `mode: 'chunked'`: explicit chunked-session flow regardless of size
  */
 export declare function scan(params: {
     repoPath: string;
     frameworks?: string[];
     options?: ScanOptions;
-}): Promise<{
-    passed: boolean;
-    exitCode: number;
-    findings: never[];
-    report: null;
-    summary?: undefined;
-} | {
-    passed: any;
-    exitCode: number;
-    findings: any;
-    report: any;
-    summary: any;
-}>;
+}): Promise<ScanReturn>;
 /**
- * Gate code strings directly without writing to disk
+ * Gate code strings directly without writing to disk (low-latency hook
+ * endpoint, used by coding-agent post-edit hooks).
  */
 export declare function gate(options: GateOptions): Promise<{
-    passed: any;
+    passed: boolean;
     exitCode: number;
-    findings: any;
-    prompt: any;
-    summary: any;
+    findings: unknown[];
+    prompt: string | undefined;
+    summary: unknown;
 }>;

package/dist/index.js

@@ -23,32 +23,51 @@ __exportStar(require("./formatters/table"), exports);
 __exportStar(require("./formatters/prompt"), exports);
 __exportStar(require("./formatters/sarif"), exports);
 /**
- * Scan a repository by collecting files and sending them to the API
+ * Scan a repository by collecting files and sending them to the API.
+ *
+ * Modes (selectable via `options.config`):
+ *   - default: synchronous validate; auto-falls-back to chunked sessions
+ *     if the server returns 413 with `suggestedEndpoint=/v1/compliance/scans`
+ *   - `mode: 'async'`: kicks off a 202 async-validate and polls until
+ *     terminal (returns same shape as default)
+ *   - `mode: 'chunked'`: explicit chunked-session flow regardless of size
  */
 async function scan(params) {
     const { repoPath, frameworks = ['soc2'], options = {} } = params;
-    // Collect files
     const files = await (0, fs_1.collectFiles)(repoPath, options.include, options.exclude);
     if (Object.keys(files).length === 0) {
         return {
             passed: true,
             exitCode: 0,
             findings: [],
-            report: null
+            report: null,
+            summary: undefined,
         };
     }
     const client = new api_client_1.ComplianceApiClient(options.apiUrl, options.apiKey);
-    const response = await client.validate(files, frameworks, options);
+    const mode = options.config?.mode ?? 'sync';
+    let response;
+    if (mode === 'async') {
+        response = await client.validateAndPoll(files, frameworks, options);
+    }
+    else if (mode === 'chunked') {
+        response = await client.validateChunked(files, frameworks, options);
+    }
+    else {
+        response = await client.validate(files, frameworks, options);
+    }
     return {
+        scanId: response.scanId,
         passed: response.passed,
         exitCode: response.passed ? 0 : 1,
-        findings: response.findings || [],
-        report: response.report, // The API should return the full report object if requested, or we synthesize it
-        summary: response.summary
+        findings: response.findings ?? [],
+        report: response.report ?? null,
+        summary: response.summary,
     };
 }
 /**
- * Gate code strings directly without writing to disk
+ * Gate code strings directly without writing to disk (low-latency hook
+ * endpoint, used by coding-agent post-edit hooks).
  */
 async function gate(options) {
     const { files, frameworks = ['soc2'], ...scanOpts } = options;
@@ -57,8 +76,8 @@ async function gate(options) {
     return {
         passed: response.passed,
         exitCode: response.passed ? 0 : 1,
-        findings: response.findings || [],
+        findings: response.findings ?? [],
         prompt: response.prompt,
-        summary: response.summary
+        summary: response.summary,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prodcycle/prodcycle",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Multi-framework policy-as-code compliance scanner for infrastructure and application code.",
   "homepage": "https://docs.prodcycle.com",
   "repository": {