@prodcycle/prodcycle 0.6.7 → 0.6.9

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

@@ -77,3 +77,15 @@ export declare function formatClaudeHookOutput(response: {
     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

@@ -38,6 +38,7 @@ 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"));
@@ -46,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',
@@ -342,6 +344,8 @@ 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');
@@ -351,13 +355,23 @@ program
             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: collected.files,
             frameworks,
             apiUrl: opts.apiUrl,
             apiKey: opts.apiKey,
         });
-        if (collected.claudeHook && response.exitCode !== 2) {
+        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
@@ -379,6 +393,14 @@ program
         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);
     }
@@ -462,6 +484,35 @@ function formatClaudeHookOutput(response) {
         : (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);
@@ -507,14 +558,51 @@ async function collectHookFiles(filePath) {
     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 { files: { [hookFilePath]: hookContent }, claudeHook };
+    // Coding agents (Claude Code's PostToolUse in particular) pass the file
+    // path as an absolute path. The compliance API rejects absolute paths
+    // (`File path must be relative`), so we relativise here against cwd's
+    // realpath — same code path as `--file <path>`, just driven by the stdin
+    // payload. Without this fix every PostToolUse hook call from Claude Code
+    // failed with "File path must be relative".
+    let hookFileKey = hookFilePath;
+    if (hookFilePath && path.isAbsolute(hookFilePath)) {
+        try {
+            const realpathFile = fs.realpathSync(path.resolve(hookFilePath));
+            const realpathCwd = fs.realpathSync(process.cwd());
+            const resolved = resolveHookFileKey(hookFilePath, realpathFile, realpathCwd);
+            if (!resolved.ok) {
+                // The helper's message references `--file`; rewrite for the stdin call site.
+                console.error(resolved.error.replace('hook: --file ', 'hook: file_path '));
+                process.exit(2);
+            }
+            hookFileKey = resolved.key;
+        }
+        catch (err) {
+            // File may not exist on disk yet (e.g. a Write event mid-creation) —
+            // ONLY ENOENT triggers the lexical fallback. Re-throw permission /
+            // symlink-loop / other fs errors so a real problem isn't silently
+            // converted into a degraded lexical-only key.
+            const code = err?.code;
+            if (code !== 'ENOENT') {
+                throw err;
+            }
+            const rel = path.relative(process.cwd(), hookFilePath);
+            if (rel.startsWith('..') || path.isAbsolute(rel)) {
+                console.error(`hook: file_path ${hookFilePath} is outside the current directory ` +
+                    `(${process.cwd()}). Pass a path relative to the repo root.`);
+                process.exit(2);
+            }
+            hookFileKey = rel;
+        }
+    }
+    if (hookFileKey && typeof hookContent === 'string') {
+        return { files: { [hookFileKey]: hookContent }, claudeHook };
     }
-    if (hookFilePath && fs.existsSync(hookFilePath)) {
+    if (hookFilePath && hookFileKey && 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 { files: { [hookFilePath]: content }, claudeHook };
+        return { files: { [hookFileKey]: content }, claudeHook };
     }
     console.error('hook: stdin payload not recognized. Expected one of:\n' +
         '  {"files": {"path": "content"}}\n' +
@@ -531,16 +619,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);
         }
@@ -628,20 +728,19 @@ 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.
+ * 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(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 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');
@@ -690,7 +789,7 @@ function configureClaudeCode(dir, force) {
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
     return {
         status: 'installed',
-        message: `[claude] wrote PostToolUse hook to ${settingsPath}. ${apiKeyHint('Claude Code')}`,
+        message: `[claude] wrote PostToolUse hook to ${settingsPath}. ${apiKeyHint()}`,
     };
 }
 const CURSOR_COMMAND = 'prodcycle hook';
@@ -738,7 +837,7 @@ function configureCursor(dir, force) {
     fs.writeFileSync(hooksPath, JSON.stringify(config, null, 2) + '\n');
     return {
         status: 'installed',
-        message: `[cursor] wrote afterFileEdit hook to ${hooksPath}. ${apiKeyHint('Cursor')}`,
+        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/dist/utils/fs.js

@@ -335,7 +335,13 @@ async function collectFiles(baseDir, includePatterns, excludePatterns) {
     const files = {};
     const state = { count: 0, limitReached: false };
     walk(repoRoot, repoRoot, gitignores, prodcycleIgnores, includePatterns, excludePatterns, files, state);
-    return files;
+    // Canonical sort by path. Object iteration order is insertion order, which
+    // reflects directory-walk order — that differs between Node's `readdirSync`
+    // and Python's `os.walk`, so the two CLIs would otherwise chunk the same
+    // file set into different request shapes and the server-side per-chunk
+    // evaluation produced subtle finding divergences (CLAUDE.md "Node and
+    // Python must stay symmetric"). Sorting here makes the wire shape identical.
+    return Object.fromEntries(Object.entries(files).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
 }
 function walk(dir, repoRoot, gitignores, prodcycleIgnores, includePatterns, userExcludes, files, state) {
     if (state.limitReached)

package/package.json

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