@prodcycle/prodcycle 0.6.5 → 0.6.7

package/dist/api-client.js

@@ -399,7 +399,20 @@ class ComplianceApiClient {
             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;
+            // 429 (rate limit) and 503 (service unavailable) honor Retry-After.
+            // 502 (bad gateway) and 504 (gateway timeout) are transient ALB-layer
+            // failures — the backend wasn't reached / didn't respond in time, so
+            // the request was not processed and a fresh attempt has a clean
+            // chance of succeeding. Concrete case: openbao-openbao got an
+            // instantaneous 502 during the 2026-05-13 GA-validation sweep and
+            // the CLI bailed without retry, even though the very next repo
+            // scanned cleanly. 500 is deliberately NOT retried — that's an
+            // application-level error and retrying could double-process or
+            // just deterministically refail.
+            const isRetryable = response.status === 429 ||
+                response.status === 502 ||
+                response.status === 503 ||
+                response.status === 504;
             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);

package/dist/cli.d.ts

@@ -50,3 +50,30 @@ 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;

package/dist/cli.js

@@ -36,6 +36,8 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isCiEnvironment = isCiEnvironment;
 exports.resolveHookFileKey = resolveHookFileKey;
+exports.isClaudeCodeHookPayload = isClaudeCodeHookPayload;
+exports.formatClaudeHookOutput = formatClaudeHookOutput;
 const commander_1 = require("commander");
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
@@ -343,18 +345,36 @@ program
     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;
         }
         const response = await (0, index_1.gate)({
-            files,
+            files: collected.files,
             frameworks,
             apiUrl: opts.apiUrl,
             apiKey: opts.apiKey,
         });
+        if (collected.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);
     }
@@ -409,6 +429,39 @@ 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 });
+}
 async function collectHookFiles(filePath) {
     if (filePath) {
         const absolute = path.resolve(filePath);
@@ -427,7 +480,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 +496,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' +
@@ -570,6 +627,22 @@ function configureAgent(agent, dir, force, writtenPaths) {
 }
 const CLAUDE_MATCHER = 'Write|Edit|MultiEdit';
 const CLAUDE_COMMAND = 'prodcycle hook';
+/**
+ * Build the post-install hint about `PC_API_KEY`. The hook calls the hosted
+ * API, which needs the key in the environment the agent runs in — the most
+ * common reason a freshly-installed hook fails. We can only inspect the shell
+ * running `init`, which is NOT necessarily the environment the agent runs in
+ * (e.g. a macOS GUI-launched editor does not inherit shell exports), so the
+ * "set" branch points the user at making the key available there too.
+ */
+function apiKeyHint(agentLabel) {
+    return process.env.PC_API_KEY
+        ? `PC_API_KEY is set in this shell ✓ — make sure it is also available in ` +
+            `the environment ${agentLabel} runs in (e.g. add it to your shell profile).`
+        : `⚠ Set PC_API_KEY before launching ${agentLabel} — run ` +
+            '`export PC_API_KEY=pc_...` in that shell (or add it to your shell ' +
+            'profile). 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 +690,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('Claude Code')}`,
     };
 }
 const CURSOR_COMMAND = 'prodcycle hook';
@@ -665,7 +738,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('Cursor')}`,
     };
 }
 // ── Instruction-file agents (codex, opencode, github-copilot, gemini-cli) ───

package/package.json

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