@prodcycle/prodcycle 0.6.6 → 0.6.8

package/dist/api-client.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ComplianceApiClient = exports.ApiError = void 0;
 exports.chunkFiles = chunkFiles;
+const config_1 = require("./utils/config");
 /**
  * Error thrown for any non-2xx response. Carries the parsed body + status so
  * callers can branch on `details.suggestedEndpoint` (413 → chunked-session
@@ -98,8 +99,12 @@ class ComplianceApiClient {
     apiUrl;
     apiKey;
     constructor(apiUrl, apiKey) {
-        this.apiUrl = apiUrl || process.env.PC_API_URL || DEFAULT_API_URL;
-        this.apiKey = apiKey || process.env.PC_API_KEY || '';
+        // Resolution order (for both): explicit arg → env var → user config
+        // file → default. See `utils/config.ts`. Read the config file once and
+        // resolve both values from it rather than re-reading per value.
+        const config = (0, config_1.readConfig)();
+        this.apiUrl = (0, config_1.resolveApiUrl)(apiUrl, config) || DEFAULT_API_URL;
+        this.apiKey = (0, config_1.resolveApiKey)(apiKey, config);
         if (!this.apiKey &&
             process.env.NODE_ENV !== 'test' &&
             !process.env.PC_SUPPRESS_WARNINGS) {

package/dist/cli.d.ts

@@ -50,3 +50,42 @@ export declare function resolveHookFileKey(inputPath: string, realpathFile: stri
     ok: false;
     error: string;
 };
+/**
+ * True when a parsed `hook` stdin payload is a Claude Code hook event.
+ *
+ * Claude Code stamps every hook payload with a `hook_event_name` field
+ * (e.g. `"PostToolUse"`); no other supported input shape carries it. We
+ * key on its presence to switch `hook` into Claude-Code-native JSON
+ * output — see `formatClaudeHookOutput`. Pure so it's unit-testable.
+ */
+export declare function isClaudeCodeHookPayload(payload: unknown): boolean;
+/**
+ * Render a `hook` scan result as Claude Code PostToolUse hook JSON.
+ *
+ * Returns `''` when the scan passed — a clean result needs no agent
+ * feedback, so the hook stays silent. On violations it returns
+ * `{"decision":"block","reason":...}`: Claude Code feeds `reason` back to
+ * the agent as actionable feedback, which is what closes the compliance
+ * self-healing loop.
+ *
+ * The caller MUST exit 0 for Claude Code to parse this — Claude Code
+ * ignores hook JSON on any non-zero exit. Pure so it's unit-testable.
+ */
+export declare function formatClaudeHookOutput(response: {
+    exitCode: number;
+    passed?: boolean;
+    prompt?: string;
+    findings?: unknown[];
+}): string;
+/**
+ * Claude Code hook JSON for the "API key not usable" state.
+ *
+ * A missing or rejected key is a setup problem, not a compliance failure —
+ * so instead of blocking every edit with an error, we emit a `systemMessage`
+ * (shown to the user, never fed to the agent, never blocking) telling them
+ * how to fix it. `reason` distinguishes a key that is absent (`'missing'`)
+ * from one the API rejected (`'rejected'` — expired/revoked/wrong) so the
+ * message points at the right fix. The caller exits 0. Pure so it's
+ * unit-testable.
+ */
+export declare function formatClaudeHookSetupNotice(reason?: 'missing' | 'rejected'): string;

package/dist/cli.js

@@ -36,6 +36,9 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isCiEnvironment = isCiEnvironment;
 exports.resolveHookFileKey = resolveHookFileKey;
+exports.isClaudeCodeHookPayload = isClaudeCodeHookPayload;
+exports.formatClaudeHookOutput = formatClaudeHookOutput;
+exports.formatClaudeHookSetupNotice = formatClaudeHookSetupNotice;
 const commander_1 = require("commander");
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
@@ -44,6 +47,7 @@ const index_1 = require("./index");
 const table_1 = require("./formatters/table");
 const sarif_1 = require("./formatters/sarif");
 const prompt_1 = require("./formatters/prompt");
+const config_1 = require("./utils/config");
 const KNOWN_COMMANDS = new Set([
     'scan',
     'scans',
@@ -340,25 +344,63 @@ program
     .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 (opts) => {
+    // Hoisted so the catch block can branch on it (see the auth-error case).
+    let claudeHook = false;
     try {
         const frameworks = parseList(opts.framework) ?? ['soc2', 'hipaa', 'nist-csf'];
         const format = (opts.format ?? 'prompt');
-        const files = await collectHookFiles(opts.file);
-        if (!files || Object.keys(files).length === 0) {
+        const collected = await collectHookFiles(opts.file);
+        if (!collected || Object.keys(collected.files).length === 0) {
             // No files to check — exit clean so the agent proceeds.
             process.exit(0);
             return;
         }
+        claudeHook = collected.claudeHook;
+        // Graceful unconfigured state: a missing API key is a setup problem,
+        // not a compliance failure. For a Claude Code hook, surface a one-line
+        // setup notice and exit 0 so the agent is not blocked on every edit.
+        // Non-Claude callers (CI) fall through and hard-fail as before.
+        if (claudeHook && !(0, config_1.resolveApiKey)(opts.apiKey)) {
+            process.stdout.write(formatClaudeHookSetupNotice('missing') + '\n');
+            process.exit(0);
+            return;
+        }
         const response = await (0, index_1.gate)({
-            files,
+            files: collected.files,
             frameworks,
             apiUrl: opts.apiUrl,
             apiKey: opts.apiKey,
         });
+        if (claudeHook && response.exitCode !== 2) {
+            // Invoked as a Claude Code PostToolUse hook. Emit Claude Code's
+            // native hook JSON on stdout so a violation is fed back to the
+            // agent as actionable feedback — this is what closes the compliance
+            // self-healing loop. Claude Code only parses hook JSON when the
+            // command exits 0, so we exit 0 here even on violations and let
+            // `decision: "block"` carry the signal.
+            //
+            // exitCode 2 (scanner unavailable) deliberately falls through to
+            // the generic path below: it exits 2, and Claude Code surfaces a
+            // hook's stderr on a 2 — gate() already wrote the scanner-error
+            // warning there, so the agent still learns the scan was inconclusive.
+            const claudeJson = formatClaudeHookOutput(response);
+            if (claudeJson)
+                process.stdout.write(claudeJson + '\n');
+            process.exit(0);
+            return;
+        }
         writeOutput(renderReport(response, format), opts.output);
         process.exit(response.exitCode);
     }
     catch (error) {
+        // A rejected key (401/403) is a setup problem too \u2014 on the Claude Code
+        // hook path, treat it like the missing-key case rather than blocking
+        // every edit with an error.
+        if (claudeHook && isAuthError(error)) {
+            process.stdout.write(formatClaudeHookSetupNotice('rejected') + '\n');
+            process.exit(0);
+            return;
+        }
         console.error(`\u2717 Error: ${error.message}`);
         process.exit(2);
     }
@@ -409,6 +451,68 @@ function resolveHookFileKey(inputPath, realpathFile, realpathCwd) {
     }
     return { ok: true, key: relative };
 }
+/**
+ * True when a parsed `hook` stdin payload is a Claude Code hook event.
+ *
+ * Claude Code stamps every hook payload with a `hook_event_name` field
+ * (e.g. `"PostToolUse"`); no other supported input shape carries it. We
+ * key on its presence to switch `hook` into Claude-Code-native JSON
+ * output — see `formatClaudeHookOutput`. Pure so it's unit-testable.
+ */
+function isClaudeCodeHookPayload(payload) {
+    return (typeof payload === 'object' &&
+        payload !== null &&
+        typeof payload.hook_event_name === 'string');
+}
+/**
+ * Render a `hook` scan result as Claude Code PostToolUse hook JSON.
+ *
+ * Returns `''` when the scan passed — a clean result needs no agent
+ * feedback, so the hook stays silent. On violations it returns
+ * `{"decision":"block","reason":...}`: Claude Code feeds `reason` back to
+ * the agent as actionable feedback, which is what closes the compliance
+ * self-healing loop.
+ *
+ * The caller MUST exit 0 for Claude Code to parse this — Claude Code
+ * ignores hook JSON on any non-zero exit. Pure so it's unit-testable.
+ */
+function formatClaudeHookOutput(response) {
+    if (response.exitCode === 0)
+        return '';
+    const reason = typeof response.prompt === 'string' && response.prompt.trim()
+        ? response.prompt
+        : (0, prompt_1.formatPrompt)(response);
+    return JSON.stringify({ decision: 'block', reason });
+}
+/**
+ * Claude Code hook JSON for the "API key not usable" state.
+ *
+ * A missing or rejected key is a setup problem, not a compliance failure —
+ * so instead of blocking every edit with an error, we emit a `systemMessage`
+ * (shown to the user, never fed to the agent, never blocking) telling them
+ * how to fix it. `reason` distinguishes a key that is absent (`'missing'`)
+ * from one the API rejected (`'rejected'` — expired/revoked/wrong) so the
+ * message points at the right fix. The caller exits 0. Pure so it's
+ * unit-testable.
+ */
+function formatClaudeHookSetupNotice(reason = 'missing') {
+    const detail = reason === 'rejected'
+        ? 'the configured API key was rejected (it may be expired or revoked)'
+        : 'no API key found';
+    return JSON.stringify({
+        systemMessage: `ProdCycle compliance scanning is inactive — ${detail}. ` +
+            'Run `prodcycle init --api-key pc_...` to save a valid key, or set the ' +
+            'PC_API_KEY environment variable. See https://docs.prodcycle.com.',
+    });
+}
+/**
+ * True when an error is the API rejecting our credentials (401/403) — i.e.
+ * a key that is missing, wrong, or revoked. Treated as a setup problem, not
+ * a scan failure, on the Claude Code hook path.
+ */
+function isAuthError(error) {
+    return error instanceof index_1.ApiError && (error.statusCode === 401 || error.statusCode === 403);
+}
 async function collectHookFiles(filePath) {
     if (filePath) {
         const absolute = path.resolve(filePath);
@@ -427,7 +531,8 @@ async function collectHookFiles(filePath) {
             console.error(resolved.error);
             process.exit(2);
         }
-        return { [resolved.key]: content };
+        // `--file` is a manual / non-agent invocation — never Claude Code.
+        return { files: { [resolved.key]: content }, claudeHook: false };
     }
     const stdin = await readStdin();
     if (!stdin.trim()) {
@@ -442,22 +547,25 @@ async function collectHookFiles(filePath) {
         console.error(`hook: invalid JSON on stdin: ${e.message}`);
         process.exit(2);
     }
+    // Claude Code stamps its hook payloads with `hook_event_name`; detect it
+    // once here so every return below can flag a Claude Code invocation.
+    const claudeHook = isClaudeCodeHookPayload(payload);
     // Shape 1: {"files": {path: content}} — gate-compatible
     if (payload && typeof payload.files === 'object' && payload.files !== null) {
-        return payload.files;
+        return { files: payload.files, claudeHook };
     }
     // Shape 2: top-level single file. Shape 3: Claude Code tool_input nesting.
     const candidate = payload?.tool_input ?? payload;
     const hookFilePath = candidate?.file_path ?? candidate?.path;
     const hookContent = candidate?.content ?? candidate?.new_string;
     if (hookFilePath && typeof hookContent === 'string') {
-        return { [hookFilePath]: hookContent };
+        return { files: { [hookFilePath]: hookContent }, claudeHook };
     }
     if (hookFilePath && fs.existsSync(hookFilePath)) {
         // Only a path was given — read from disk so post-edit hooks still work
         // when the agent doesn't ship the content inline.
         const content = fs.readFileSync(hookFilePath, 'utf8');
-        return { [hookFilePath]: content };
+        return { files: { [hookFilePath]: content }, claudeHook };
     }
     console.error('hook: stdin payload not recognized. Expected one of:\n' +
         '  {"files": {"path": "content"}}\n' +
@@ -474,16 +582,28 @@ program
     .option('--ci <providers>', 'Comma-separated CI providers to scaffold (github, gitlab, circleci). Use "all" for every provider. Opt-in only \u2014 never auto-detected.')
     .option('--force', 'Overwrite existing compliance hook entries')
     .option('--dir <path>', 'Project directory to configure', '.')
+    .option('--api-key <key>', 'Save this API key to the user config file (~/.config/prodcycle/config.json, chmod 600) so hooks authenticate without an env var')
     .action((opts) => {
     try {
         const dir = path.resolve(opts.dir ?? '.');
+        // Persist the API key first so the post-install hints below see it.
+        if (opts.apiKey) {
+            const savedTo = (0, config_1.writeApiKey)(opts.apiKey);
+            process.stdout.write(`[config] saved API key to ${savedTo} (readable only by you).\n`);
+        }
         const agents = resolveAgents(opts.agent, dir);
         const ciProviders = resolveCiProviders(opts.ci);
         if (agents.length === 0 && ciProviders.length === 0) {
+            if (opts.apiKey) {
+                // Saving the key was itself the requested action — nothing else to do.
+                process.exit(0);
+                return;
+            }
             console.error('init: nothing to do. ' +
                 'Use --agent <name> to configure a coding agent (claude, cursor, codex, ' +
-                'opencode, github-copilot, gemini-cli, or "all"), and/or --ci <provider> ' +
-                'to scaffold CI workflows (github, gitlab, circleci, or "all"). ' +
+                'opencode, github-copilot, gemini-cli, or "all"), --ci <provider> ' +
+                'to scaffold CI workflows (github, gitlab, circleci, or "all"), ' +
+                'and/or --api-key <key> to save your credentials. ' +
                 'Without --agent the CLI also auto-detects agents already in use.');
             process.exit(2);
         }
@@ -570,6 +690,21 @@ function configureAgent(agent, dir, force, writtenPaths) {
 }
 const CLAUDE_MATCHER = 'Write|Edit|MultiEdit';
 const CLAUDE_COMMAND = 'prodcycle hook';
+/**
+ * Build the post-install hint about API-key setup. The hook authenticates
+ * against the hosted API using a key resolved from `--api-key`, the
+ * `PC_API_KEY` env var, or the user config file (see `utils/config.ts`).
+ * The config file is the robust option — unlike an env var, a GUI-launched
+ * editor picks it up with no relaunch — so when no key is found we point
+ * the user there.
+ */
+function apiKeyHint() {
+    return (0, config_1.resolveApiKey)()
+        ? 'API key configured ✓'
+        : '⚠ No API key configured — run `prodcycle init --api-key pc_...` to ' +
+            'save one (or set the PC_API_KEY env var). The hook calls the hosted ' +
+            'API and fails without it.';
+}
 function configureClaudeCode(dir, force) {
     const claudeDir = path.join(dir, '.claude');
     const settingsPath = path.join(claudeDir, 'settings.json');
@@ -617,7 +752,7 @@ function configureClaudeCode(dir, force) {
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
     return {
         status: 'installed',
-        message: `[claude] wrote PostToolUse hook to ${settingsPath}. Requires PC_API_KEY in the environment when Claude Code runs.`,
+        message: `[claude] wrote PostToolUse hook to ${settingsPath}. ${apiKeyHint()}`,
     };
 }
 const CURSOR_COMMAND = 'prodcycle hook';
@@ -665,7 +800,7 @@ function configureCursor(dir, force) {
     fs.writeFileSync(hooksPath, JSON.stringify(config, null, 2) + '\n');
     return {
         status: 'installed',
-        message: `[cursor] wrote afterFileEdit hook to ${hooksPath}. Requires PC_API_KEY in the environment when Cursor runs.`,
+        message: `[cursor] wrote afterFileEdit hook to ${hooksPath}. ${apiKeyHint()}`,
     };
 }
 // ── Instruction-file agents (codex, opencode, github-copilot, gemini-cli) ───

package/dist/utils/config.d.ts

@@ -0,0 +1,37 @@
+export interface ProdcycleConfig {
+    api_key?: string;
+    api_url?: string;
+}
+/**
+ * Path to the user-level config file:
+ * `$XDG_CONFIG_HOME/prodcycle/config.json`, falling back to
+ * `~/.config/prodcycle/config.json`. A non-absolute `XDG_CONFIG_HOME` is
+ * ignored, per the XDG Base Directory spec.
+ */
+export declare function configFilePath(): string;
+/**
+ * Read the user-level config file. Returns `{}` when the file is absent,
+ * unreadable, or malformed — a broken config must never crash a scan.
+ */
+export declare function readConfig(): ProdcycleConfig;
+/**
+ * Persist the API key to the user-level config file, merging into any keys
+ * already present. The file is written `0600` (directory `0700`) so the
+ * credential is not world-readable. Returns the path written.
+ */
+export declare function writeApiKey(apiKey: string): string;
+/**
+ * Resolve the API key, in precedence order: an explicit value (CLI
+ * `--api-key`), the `PC_API_KEY` env var, then the user-level config file.
+ * Returns `''` when none is configured.
+ *
+ * Pass an already-read `config` to avoid re-reading the file when the
+ * caller resolves several values at once (see `ComplianceApiClient`).
+ */
+export declare function resolveApiKey(explicit?: string, config?: ProdcycleConfig): string;
+/**
+ * Resolve the API URL: explicit value → `PC_API_URL` env → config file →
+ * `undefined` (the caller then applies its own default). Accepts an
+ * already-read `config` — see `resolveApiKey`.
+ */
+export declare function resolveApiUrl(explicit?: string, config?: ProdcycleConfig): string | undefined;

package/dist/utils/config.js

@@ -0,0 +1,129 @@
+"use strict";
+// User-level ProdCycle configuration.
+//
+// Lets a developer save their API key once, on disk, instead of exporting
+// `PC_API_KEY` into every shell — and, critically, into the environment a
+// GUI-launched editor runs in, which does NOT inherit shell exports. The
+// hook reads this file regardless of how the agent was launched, so
+// `prodcycle init --api-key pc_...` is a one-time setup with no relaunch.
+//
+// Mirrors `python/src/prodcycle/utils/config.py` — the two must stay in
+// lockstep.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configFilePath = configFilePath;
+exports.readConfig = readConfig;
+exports.writeApiKey = writeApiKey;
+exports.resolveApiKey = resolveApiKey;
+exports.resolveApiUrl = resolveApiUrl;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+// One-shot guard so a malformed config file warns at most once per process
+// (both `resolveApiKey` and `resolveApiUrl` call `readConfig`).
+let warnedMalformed = false;
+/**
+ * Path to the user-level config file:
+ * `$XDG_CONFIG_HOME/prodcycle/config.json`, falling back to
+ * `~/.config/prodcycle/config.json`. A non-absolute `XDG_CONFIG_HOME` is
+ * ignored, per the XDG Base Directory spec.
+ */
+function configFilePath() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    const base = xdg && path.isAbsolute(xdg) ? xdg : path.join(os.homedir(), '.config');
+    return path.join(base, 'prodcycle', 'config.json');
+}
+/**
+ * Read the user-level config file. Returns `{}` when the file is absent,
+ * unreadable, or malformed — a broken config must never crash a scan.
+ */
+function readConfig() {
+    let raw;
+    try {
+        raw = fs.readFileSync(configFilePath(), 'utf8');
+    }
+    catch {
+        return {}; // absent / unreadable — the expected case, not an error
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // fall through to the warning below
+    }
+    if (!warnedMalformed) {
+        warnedMalformed = true;
+        process.stderr.write(`Warning: ${configFilePath()} is not valid JSON — ignoring it.\n`);
+    }
+    return {};
+}
+/**
+ * Persist the API key to the user-level config file, merging into any keys
+ * already present. The file is written `0600` (directory `0700`) so the
+ * credential is not world-readable. Returns the path written.
+ */
+function writeApiKey(apiKey) {
+    const file = configFilePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const config = readConfig();
+    config.api_key = apiKey;
+    fs.writeFileSync(file, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+    // `mode` on writeFileSync is ignored when the file already exists, so set
+    // it explicitly — the credential must never be left world-readable.
+    fs.chmodSync(file, 0o600);
+    return file;
+}
+/**
+ * Resolve the API key, in precedence order: an explicit value (CLI
+ * `--api-key`), the `PC_API_KEY` env var, then the user-level config file.
+ * Returns `''` when none is configured.
+ *
+ * Pass an already-read `config` to avoid re-reading the file when the
+ * caller resolves several values at once (see `ComplianceApiClient`).
+ */
+function resolveApiKey(explicit, config) {
+    return explicit || process.env.PC_API_KEY || (config ?? readConfig()).api_key || '';
+}
+/**
+ * Resolve the API URL: explicit value → `PC_API_URL` env → config file →
+ * `undefined` (the caller then applies its own default). Accepts an
+ * already-read `config` — see `resolveApiKey`.
+ */
+function resolveApiUrl(explicit, config) {
+    return explicit || process.env.PC_API_URL || (config ?? readConfig()).api_url || undefined;
+}

package/package.json

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