@prodcycle/prodcycle 0.6.10 → 0.6.12

package/LICENSE

@@ -1,52 +1,201 @@
-Copyright (c) 2025-2026 ProdCycle, Inc. All rights reserved.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
 
-This software and associated documentation files (the "Software") are the
-proprietary property of ProdCycle, Inc. and are protected by copyright law.
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
-GRANT OF LICENSE
+   1. Definitions.
 
-Subject to valid license key activation and the terms of your ProdCycle
-subscription agreement, ProdCycle, Inc. grants you a limited, non-exclusive,
-non-transferable, revocable license to use the Software solely for your
-internal business purposes.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
 
-RESTRICTIONS
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
 
-You may not, without the prior written consent of ProdCycle, Inc.:
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
 
-  1. Copy, modify, or create derivative works of the Software;
-  2. Distribute, sublicense, lease, rent, or lend the Software to any
-     third party;
-  3. Reverse engineer, decompile, or disassemble the Software;
-  4. Remove or alter any proprietary notices, labels, or marks on the
-     Software;
-  5. Use the Software to build a competing product or service.
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
 
-COMPLIANCE POLICIES
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
 
-The compliance policy definitions (Rego rules, Cedar policies, and framework
-control mappings) included in the `policies/` and `frameworks/` directories
-are provided as part of the Software and are subject to the same license
-terms.
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
 
-DISCLAIMER OF WARRANTIES
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
 
-LIMITATION OF LIABILITY
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
 
-IN NO EVENT SHALL PRODCYCLE, INC. BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
 
-TERMINATION
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
 
-This license is effective until terminated. ProdCycle, Inc. may terminate this
-license at any time if you fail to comply with any term of this agreement.
-Upon termination, you must destroy all copies of the Software in your
-possession.
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
 
-For licensing inquiries, contact: licensing@prodcycle.com
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025-2026 ProdCycle, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -94,15 +94,27 @@ if (!result.passed) {
 An API key is required for production use to authenticate with ProdCycle. Set it via environment variable:
 
 ```bash
-export PC_API_KEY=pc_your_api_key_here
+export PRODCYCLE_API_KEY=pc_your_api_key_here
 ```
 
 API keys are created through the ProdCycle dashboard.
 
+## Exit codes
+
+`scan`, `gate`, and `hook` use exit codes designed for CI gates and agent hooks:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Pass — no findings at or above the `--fail-on` threshold (default: `critical,high`). |
+| `1` | Findings present — code is not clean. |
+| `2` | Scanner unavailable or usage error — the scan could not be certified either way (fail-closed). Distinguish this from `1` so CI/agents can treat "fix your code" differently from "investigate the scanner." |
+
+> The Claude Code `hook` path is special-cased: a missing/rejected API key or a clean result exits `0` so the agent is never blocked on setup; violations are returned to the agent as structured feedback.
+
 ## Requirements
 
-- Node.js >= 24.0.0
+- Node.js >= 22.0.0
 
 ## License
 
-MIT
+Apache-2.0 — see [LICENSE](./LICENSE).

package/dist/api-client.d.ts

@@ -88,7 +88,7 @@ export declare class ComplianceApiClient {
      * '/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>;
+    validate(files: Record<string, string>, frameworks: string[], options?: ScanOptions, vcsLocalOnly?: string[]): Promise<ScanResult>;
     /**
      * Hook endpoint — small per-write call from coding agents. No
      * suggestedEndpoint fallback because /hook keeps the historical 50 MB
@@ -102,7 +102,7 @@ export declare class ComplianceApiClient {
      * 30 minutes by default — abandoned sessions self-clean via the
      * stale-session reaper.
      */
-    openSession(frameworks: string[], options?: ScanOptions): Promise<{
+    openSession(frameworks: string[], options?: ScanOptions, vcsLocalOnly?: string[]): Promise<{
         scanId: string;
         chunkSizeBytes: number;
         maxFilesPerChunk: number;
@@ -131,7 +131,7 @@ export declare class ComplianceApiClient {
      * 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>;
+    validateChunked(files: Record<string, string>, frameworks: string[], options?: ScanOptions, vcsLocalOnly?: string[]): Promise<ScanResult>;
     /**
      * Some server versions of `POST /scans/:id/complete` return only the summary,
      * leaving `findings` empty even when `summary.total > 0`. The findings are
@@ -153,7 +153,7 @@ export declare class ComplianceApiClient {
      * `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<{
+    validateAsync(files: Record<string, string>, frameworks: string[], options?: ScanOptions, vcsLocalOnly?: string[]): Promise<{
         scanId: string;
     }>;
     /**
@@ -164,7 +164,7 @@ export declare class ComplianceApiClient {
      * 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>;
+    validateAndPoll(files: Record<string, string>, frameworks: string[], options?: ScanOptions, vcsLocalOnly?: string[]): Promise<ScanResult>;
     private buildOptions;
     /**
      * Single HTTP request with:

package/dist/api-client.js

@@ -105,10 +105,15 @@ class ComplianceApiClient {
         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) {
-            process.stderr.write('Warning: PC_API_KEY is not set. API calls will likely fail.\n');
+        // Fail fast with an actionable error rather than warning and letting the
+        // request fall over later as an opaque `fetch failed` / 401. A missing key
+        // is a setup problem the user can fix immediately. The Claude Code hook
+        // path pre-checks `resolveApiKey` and exits 0 *before* constructing a
+        // client, so this throw never blocks an agent on every edit.
+        if (!this.apiKey) {
+            throw new Error('No ProdCycle API key found. Set the PRODCYCLE_API_KEY environment variable ' +
+                'or run `prodcycle init --api-key pc_...` to save one. ' +
+                'See https://docs.prodcycle.com.');
         }
     }
     /**
@@ -116,12 +121,17 @@ class ComplianceApiClient {
      * '/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 = {}) {
+    async validate(files, frameworks, options = {}, vcsLocalOnly = []) {
         try {
             return await this.request('POST', '/v1/compliance/validate', {
                 files,
                 frameworks,
                 options: this.buildOptions(options),
+                // Top-level hint (sibling of `files`/`frameworks`, NOT an option) so
+                // the scanner can downgrade secrets that exist only in the local
+                // working tree. Omitted entirely when empty so payloads are unchanged
+                // for repos without local-only files.
+                ...(vcsLocalOnly.length > 0 && { vcsLocalOnly }),
             });
         }
         catch (err) {
@@ -131,7 +141,7 @@ class ComplianceApiClient {
                 // 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);
+                return this.validateChunked(files, frameworks, options, vcsLocalOnly);
             }
             throw err;
         }
@@ -156,10 +166,13 @@ class ComplianceApiClient {
      * 30 minutes by default — abandoned sessions self-clean via the
      * stale-session reaper.
      */
-    async openSession(frameworks, options = {}) {
+    async openSession(frameworks, options = {}, vcsLocalOnly = []) {
         return this.request('POST', '/v1/compliance/scans', {
             frameworks,
             options: this.buildOptions(options),
+            // Sent once at session-open (NOT on appendChunk) — the scanner applies
+            // it to the whole chunked scan. Omitted when empty (see `validate`).
+            ...(vcsLocalOnly.length > 0 && { vcsLocalOnly }),
         });
     }
     /**
@@ -187,10 +200,10 @@ class ComplianceApiClient {
      * Caller can pre-set `chunkMaxBytes` / `chunkMaxFiles` on `options.config`
      * to override the conservative defaults.
      */
-    async validateChunked(files, frameworks, options = {}) {
+    async validateChunked(files, frameworks, options = {}, vcsLocalOnly = []) {
         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 session = await this.openSession(frameworks, options, vcsLocalOnly);
         const chunks = chunkFiles(files, chunkMaxBytes, chunkMaxFiles);
         for (const chunk of chunks) {
             await this.appendChunk(session.scanId, chunk);
@@ -276,11 +289,13 @@ class ComplianceApiClient {
      * `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 = {}) {
+    async validateAsync(files, frameworks, options = {}, vcsLocalOnly = []) {
         return this.request('POST', '/v1/compliance/validate?async=true', {
             files,
             frameworks,
             options: this.buildOptions(options),
+            // Top-level local-only hint; omitted when empty (see `validate`).
+            ...(vcsLocalOnly.length > 0 && { vcsLocalOnly }),
         });
     }
     /**
@@ -293,8 +308,8 @@ class ComplianceApiClient {
      * 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);
+    async validateAndPoll(files, frameworks, options = {}, vcsLocalOnly = []) {
+        const { scanId } = await this.validateAsync(files, frameworks, options, vcsLocalOnly);
         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

package/dist/cli.d.ts

@@ -50,15 +50,43 @@ export declare function resolveHookFileKey(inputPath: string, realpathFile: stri
     ok: false;
     error: string;
 };
+/**
+ * Cursor hook events that carry `hook_event_name` but are not Claude Code.
+ * Cursor and Claude both stamp payloads; only Claude PostToolUse (etc.)
+ * should use Claude-Code-native JSON output.
+ *
+ * @see https://cursor.com/docs/hooks
+ */
+export declare const CURSOR_HOOK_EVENT_NAMES: Set<string>;
+/**
+ * True when stdin is a Cursor hooks payload (e.g. `afterFileEdit`).
+ * Pure so it's unit-testable.
+ */
+export declare function isCursorHookPayload(payload: unknown): boolean;
 /**
  * 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.
+ * Claude Code stamps hook payloads with `hook_event_name` (e.g.
+ * `"PostToolUse"`). Cursor uses the same field for its own events — exclude
+ * those so `hook` prints a human-readable report for Cursor's notification
+ * hooks instead of Claude's `{"decision":"block",...}` JSON. Pure so it's
+ * unit-testable.
  */
 export declare function isClaudeCodeHookPayload(payload: unknown): boolean;
+/** True when a hooks.json command invokes `prodcycle hook`. */
+export declare function isProdcycleHookCommand(command: string): boolean;
+/**
+ * Build `prodcycle hook` for agent hook configs from a resolved binary path.
+ * Quotes paths that need it so hooks.json commands survive spaces in usernames.
+ * Pure so it's unit-testable. Mirrors Python `_format_prodcycle_hook_command`.
+ */
+export declare function formatProdcycleHookCommand(bin: string): string;
+/**
+ * Resolve `prodcycle hook` for agent hook configs. GUI-launched editors
+ * (Cursor, Claude Code) often lack nvm/shims on PATH — write the absolute
+ * binary path when `which`/`where` finds one.
+ */
+export declare function resolveProdcycleHookCommand(): string;
 /**
  * Render a `hook` scan result as Claude Code PostToolUse hook JSON.
  *

package/dist/cli.js

@@ -34,9 +34,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURSOR_HOOK_EVENT_NAMES = void 0;
 exports.isCiEnvironment = isCiEnvironment;
 exports.resolveHookFileKey = resolveHookFileKey;
+exports.isCursorHookPayload = isCursorHookPayload;
 exports.isClaudeCodeHookPayload = isClaudeCodeHookPayload;
+exports.isProdcycleHookCommand = isProdcycleHookCommand;
+exports.formatProdcycleHookCommand = formatProdcycleHookCommand;
+exports.resolveProdcycleHookCommand = resolveProdcycleHookCommand;
 exports.formatClaudeHookOutput = formatClaudeHookOutput;
 exports.formatClaudeHookSetupNotice = formatClaudeHookSetupNotice;
 const commander_1 = require("commander");
@@ -171,8 +176,8 @@ program
     .option('--include <patterns>', 'Comma-separated glob patterns to include')
     .option('--exclude <patterns>', 'Comma-separated glob patterns to exclude')
     .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('--api-url <url>', 'Compliance API base URL (or PRODCYCLE_API_URL env)')
+    .option('--api-key <key>', 'API key for compliance API (or PRODCYCLE_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.')
     .option('--pr <range>', 'Scan only files changed in a git diff range (e.g. "origin/main..HEAD"). Cuts CI scan time on large repos by skipping unchanged files. Requires baseDir to be the git repo root.')
@@ -245,8 +250,8 @@ program
     .option('--framework <ids>', 'Comma-separated framework IDs to evaluate', 'soc2,hipaa,nist-csf')
     .option('--format <format>', 'Output format: json, sarif, table, prompt', 'prompt')
     .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('--api-url <url>', 'Compliance API base URL (or PRODCYCLE_API_URL env)')
+    .option('--api-key <key>', 'API key for compliance API (or PRODCYCLE_API_KEY env)')
     .action(async (opts) => {
     try {
         const frameworks = parseList(opts.framework) ?? ['soc2', 'hipaa', 'nist-csf'];
@@ -293,8 +298,8 @@ program
     .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)')
+    .option('--api-url <url>', 'Compliance API base URL (or PRODCYCLE_API_URL env)')
+    .option('--api-key <key>', 'API key for compliance API (or PRODCYCLE_API_KEY env)')
     .action(async (scanId, opts) => {
     try {
         const format = (opts.format ?? 'json');
@@ -341,13 +346,14 @@ program
     .option('--file <path>', 'Scan this file from disk (alternative to reading content from stdin)')
     .option('--fail-on <levels>', 'Severities that cause non-zero exit', 'critical,high')
     .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('--api-url <url>', 'Compliance API base URL (or PRODCYCLE_API_URL env)')
+    .option('--api-key <key>', 'API key for compliance API (or PRODCYCLE_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 failOn = parseList(opts.failOn) ?? ['critical', 'high'];
         const format = (opts.format ?? 'prompt');
         const collected = await collectHookFiles(opts.file);
         if (!collected || Object.keys(collected.files).length === 0) {
@@ -356,6 +362,7 @@ program
             return;
         }
         claudeHook = collected.claudeHook;
+        const cursorHook = collected.cursorHook;
         // 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.
@@ -368,6 +375,7 @@ program
         const response = await (0, index_1.gate)({
             files: collected.files,
             frameworks,
+            failOn: failOn,
             apiUrl: opts.apiUrl,
             apiKey: opts.apiKey,
         });
@@ -389,7 +397,13 @@ program
             process.exit(0);
             return;
         }
-        writeOutput(renderReport(response, format), opts.output);
+        const report = renderReport(response, format);
+        writeOutput(report, opts.output);
+        // Cursor's afterFileEdit hook is notification-only (no agent feedback).
+        // Mirror violations to stderr so they appear in the Hooks output channel.
+        if (cursorHook && report.trim() && !opts.output) {
+            process.stderr.write(report.endsWith('\n') ? report : report + '\n');
+        }
         process.exit(response.exitCode);
     }
     catch (error) {
@@ -451,18 +465,97 @@ function resolveHookFileKey(inputPath, realpathFile, realpathCwd) {
     }
     return { ok: true, key: relative };
 }
+/**
+ * Cursor hook events that carry `hook_event_name` but are not Claude Code.
+ * Cursor and Claude both stamp payloads; only Claude PostToolUse (etc.)
+ * should use Claude-Code-native JSON output.
+ *
+ * @see https://cursor.com/docs/hooks
+ */
+exports.CURSOR_HOOK_EVENT_NAMES = new Set([
+    'afterFileEdit',
+    'afterTabFileEdit',
+    'afterAgentResponse',
+    'afterAgentThought',
+    'afterMCPExecution',
+    'afterShellExecution',
+    'beforeMCPExecution',
+    'beforeReadFile',
+    'beforeShellExecution',
+    'beforeSubmitPrompt',
+    'beforeTabFileRead',
+    'postToolUse',
+    'postToolUseFailure',
+    'preCompact',
+    'preToolUse',
+    'sessionEnd',
+    'sessionStart',
+    'stop',
+    'subagentStart',
+    'subagentStop',
+    'workspaceOpen',
+]);
+/**
+ * True when stdin is a Cursor hooks payload (e.g. `afterFileEdit`).
+ * Pure so it's unit-testable.
+ */
+function isCursorHookPayload(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return false;
+    const name = payload.hook_event_name;
+    return typeof name === 'string' && exports.CURSOR_HOOK_EVENT_NAMES.has(name);
+}
 /**
  * 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.
+ * Claude Code stamps hook payloads with `hook_event_name` (e.g.
+ * `"PostToolUse"`). Cursor uses the same field for its own events — exclude
+ * those so `hook` prints a human-readable report for Cursor's notification
+ * hooks instead of Claude's `{"decision":"block",...}` JSON. Pure so it's
+ * unit-testable.
  */
 function isClaudeCodeHookPayload(payload) {
-    return (typeof payload === 'object' &&
-        payload !== null &&
-        typeof payload.hook_event_name === 'string');
+    if (typeof payload !== 'object' || payload === null)
+        return false;
+    const name = payload.hook_event_name;
+    if (typeof name !== 'string')
+        return false;
+    return !exports.CURSOR_HOOK_EVENT_NAMES.has(name);
+}
+/** True when a hooks.json command invokes `prodcycle hook`. */
+function isProdcycleHookCommand(command) {
+    const trimmed = command.trim();
+    return /\bprodcycle\b/.test(trimmed) && /\bhook\b/.test(trimmed);
+}
+/**
+ * Build `prodcycle hook` for agent hook configs from a resolved binary path.
+ * Quotes paths that need it so hooks.json commands survive spaces in usernames.
+ * Pure so it's unit-testable. Mirrors Python `_format_prodcycle_hook_command`.
+ */
+function formatProdcycleHookCommand(bin) {
+    const needsQuotes = /[\s"]/.test(bin);
+    const executable = needsQuotes
+        ? `"${bin.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+        : bin;
+    return `${executable} hook`;
+}
+/**
+ * Resolve `prodcycle hook` for agent hook configs. GUI-launched editors
+ * (Cursor, Claude Code) often lack nvm/shims on PATH — write the absolute
+ * binary path when `which`/`where` finds one.
+ */
+function resolveProdcycleHookCommand() {
+    try {
+        const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+        const out = (0, child_process_1.execFileSync)(whichCmd, ['prodcycle'], { encoding: 'utf8' }).trim();
+        const bin = out.split(/\r?\n/)[0]?.trim();
+        if (bin)
+            return formatProdcycleHookCommand(bin);
+    }
+    catch {
+        /* not on PATH */
+    }
+    return 'prodcycle hook';
 }
 /**
  * Render a `hook` scan result as Claude Code PostToolUse hook JSON.
@@ -502,7 +595,7 @@ function formatClaudeHookSetupNotice(reason = 'missing') {
     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.',
+            'PRODCYCLE_API_KEY environment variable. See https://docs.prodcycle.com.',
     });
 }
 /**
@@ -531,8 +624,8 @@ async function collectHookFiles(filePath) {
             console.error(resolved.error);
             process.exit(2);
         }
-        // `--file` is a manual / non-agent invocation — never Claude Code.
-        return { files: { [resolved.key]: content }, claudeHook: false };
+        // `--file` is a manual / non-agent invocation — never Claude Code or Cursor.
+        return { files: { [resolved.key]: content }, claudeHook: false, cursorHook: false };
     }
     const stdin = await readStdin();
     if (!stdin.trim()) {
@@ -547,12 +640,11 @@ 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 cursorHook = isCursorHookPayload(payload);
     const claudeHook = isClaudeCodeHookPayload(payload);
     // Shape 1: {"files": {path: content}} — gate-compatible
     if (payload && typeof payload.files === 'object' && payload.files !== null) {
-        return { files: payload.files, claudeHook };
+        return { files: payload.files, claudeHook, cursorHook };
     }
     // Shape 2: top-level single file. Shape 3: Claude Code tool_input nesting.
     const candidate = payload?.tool_input ?? payload;
@@ -571,9 +663,13 @@ async function collectHookFiles(filePath) {
             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);
+                // Out-of-repo edit: the API only accepts repo-relative paths, so a file
+                // outside the repo root isn't scannable. Skip it (exit 0 via the caller's
+                // empty-collection check) rather than hard-erroring — matches how
+                // non-scannable files are handled, and keeps an agent from being blocked
+                // when it edits files outside the project (dotfiles, sibling repos, …).
+                process.stderr.write(`hook: skipping ${hookFilePath} — outside the repo root (${process.cwd()}).\n`);
+                return null;
             }
             hookFileKey = resolved.key;
         }
@@ -588,21 +684,21 @@ async function collectHookFiles(filePath) {
             }
             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);
+                // Out-of-repo edit (see above) — skip rather than block the agent.
+                process.stderr.write(`hook: skipping ${hookFilePath} — outside the repo root (${process.cwd()}).\n`);
+                return null;
             }
             hookFileKey = rel;
         }
     }
     if (hookFileKey && typeof hookContent === 'string') {
-        return { files: { [hookFileKey]: hookContent }, claudeHook };
+        return { files: { [hookFileKey]: hookContent }, claudeHook, cursorHook };
     }
     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.
+        // when the agent doesn't ship the content inline (Cursor afterFileEdit).
         const content = fs.readFileSync(hookFilePath, 'utf8');
-        return { files: { [hookFileKey]: content }, claudeHook };
+        return { files: { [hookFileKey]: content }, claudeHook, cursorHook };
     }
     console.error('hook: stdin payload not recognized. Expected one of:\n' +
         '  {"files": {"path": "content"}}\n' +
@@ -726,11 +822,10 @@ 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`).
+ * `PRODCYCLE_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.
@@ -739,7 +834,7 @@ 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 ' +
+            'save one (or set the PRODCYCLE_API_KEY env var). The hook calls the hosted ' +
             'API and fails without it.';
 }
 function configureClaudeCode(dir, force) {
@@ -766,7 +861,7 @@ function configureClaudeCode(dir, force) {
     const hooks = (settings.hooks ??= {});
     const postToolUse = (hooks.PostToolUse ??= []);
     // Look for an existing prodcycle entry
-    const existing = postToolUse.find((b) => b.hooks?.some((h) => h.type === 'command' && h.command.trim().startsWith('prodcycle hook')));
+    const existing = postToolUse.find((b) => b.hooks?.some((h) => h.type === 'command' && isProdcycleHookCommand(h.command)));
     if (existing && !force) {
         return {
             status: 'already',
@@ -776,12 +871,12 @@ function configureClaudeCode(dir, force) {
     if (existing && force) {
         // Replace in place — preserve the matcher, rewrite the command to the canonical form
         existing.matcher = CLAUDE_MATCHER;
-        existing.hooks = [{ type: 'command', command: CLAUDE_COMMAND }];
+        existing.hooks = [{ type: 'command', command: resolveProdcycleHookCommand() }];
     }
     else {
         postToolUse.push({
             matcher: CLAUDE_MATCHER,
-            hooks: [{ type: 'command', command: CLAUDE_COMMAND }],
+            hooks: [{ type: 'command', command: resolveProdcycleHookCommand() }],
         });
     }
     if (!fs.existsSync(claudeDir))
@@ -792,8 +887,8 @@ function configureClaudeCode(dir, force) {
         message: `[claude] wrote PostToolUse hook to ${settingsPath}. ${apiKeyHint()}`,
     };
 }
-const CURSOR_COMMAND = 'prodcycle hook';
 function configureCursor(dir, force) {
+    const cursorCommand = resolveProdcycleHookCommand();
     const cursorDir = path.join(dir, '.cursor');
     const hooksPath = path.join(cursorDir, 'hooks.json');
     let config = { version: 1 };
@@ -819,7 +914,7 @@ function configureCursor(dir, force) {
         config.version = 1;
     const hooks = (config.hooks ??= {});
     const afterFileEdit = (hooks.afterFileEdit ??= []);
-    const existing = afterFileEdit.find((h) => typeof h.command === 'string' && h.command.trim().startsWith('prodcycle hook'));
+    const existing = afterFileEdit.find((h) => typeof h.command === 'string' && isProdcycleHookCommand(h.command));
     if (existing && !force) {
         return {
             status: 'already',
@@ -827,10 +922,10 @@ function configureCursor(dir, force) {
         };
     }
     if (existing && force) {
-        existing.command = CURSOR_COMMAND;
+        existing.command = cursorCommand;
     }
     else {
-        afterFileEdit.push({ command: CURSOR_COMMAND });
+        afterFileEdit.push({ command: cursorCommand });
     }
     if (!fs.existsSync(cursorDir))
         fs.mkdirSync(cursorDir, { recursive: true });
@@ -949,15 +1044,16 @@ function writeCiFile(provider, dir, relPath, content, force) {
     if (!fs.existsSync(parent))
         fs.mkdirSync(parent, { recursive: true });
     fs.writeFileSync(fullPath, content);
-    // GitHub uses the `prodcycle/actions/compliance` action, which reads
-    // its key from `secrets.PRODCYCLE_API_KEY`. GitLab and CircleCI invoke
-    // the CLI directly, which reads `PC_API_KEY` from the environment.
+    // GitHub uses the `prodcycle/actions/compliance` action, which reads its
+    // key from `secrets.PRODCYCLE_API_KEY`. GitLab and CircleCI invoke the CLI
+    // directly, which reads `PRODCYCLE_API_KEY` from the environment — so the
+    // secret/variable name is the same across all three providers.
     const followup = provider === 'gitlab'
         ? `Include it from .gitlab-ci.yml: \`include: '${relPath}'\`. `
         : provider === 'circleci'
             ? `Reference it from .circleci/config.yml or merge the contents in. `
             : '';
-    const secretName = provider === 'github' ? 'PRODCYCLE_API_KEY' : 'PC_API_KEY';
+    const secretName = 'PRODCYCLE_API_KEY';
     return {
         status: 'installed',
         message: `[ci:${provider}] wrote ${fullPath}. ` +
@@ -1000,8 +1096,8 @@ const GITLAB_WORKFLOW = `# Prodcycle compliance scan. Include from your main .gi
 #   include:
 #     - local: .gitlab-ci.prodcycle.yml
 #
-# Set PC_API_KEY as a CI/CD variable (Settings → CI/CD → Variables) before
-# the first run. Mark it Masked + Protected.
+# Set PRODCYCLE_API_KEY as a CI/CD variable (Settings → CI/CD → Variables)
+# before the first run. Mark it Masked + Protected.
 
 prodcycle:
   stage: test
@@ -1039,8 +1135,8 @@ const CIRCLECI_WORKFLOW = `# Prodcycle compliance scan. To use this, either repl
 #       jobs:
 #         - prodcycle-scan
 #
-# Set PC_API_KEY as a project environment variable in CircleCI before the
-# first run.
+# Set PRODCYCLE_API_KEY as a project environment variable in CircleCI before
+# the first run.
 #
 # CircleCI does not expose the PR target branch as a built-in env var
 # (\`CIRCLE_BASE_BRANCH\` does not exist; see

package/dist/index.js

@@ -19,6 +19,7 @@ exports.scan = scan;
 exports.gate = gate;
 const api_client_1 = require("./api-client");
 const fs_1 = require("./utils/fs");
+const vcs_1 = require("./utils/vcs");
 __exportStar(require("./api-client"), exports);
 __exportStar(require("./formatters/table"), exports);
 __exportStar(require("./formatters/prompt"), exports);
@@ -56,17 +57,24 @@ async function scan(params) {
             summary: undefined,
         };
     }
+    // Compute the local-only files (git-ignored AND untracked) from the real
+    // `.git` in this checkout. The hosted API collects files in a sandbox
+    // without a real `.git`, so it can't derive this itself — we send it as a
+    // top-level `vcsLocalOnly` hint so the scanner downgrades secrets that live
+    // only in the local working tree (e.g. a developer's `.env`). Fail-safe:
+    // returns [] on any git error / non-repo, in which case nothing changes.
+    const vcsLocalOnly = await (0, vcs_1.computeVcsLocalOnly)(repoPath, Object.keys(files));
     const client = new api_client_1.ComplianceApiClient(options.apiUrl, options.apiKey);
     const mode = options.config?.mode ?? 'sync';
     let response;
     if (mode === 'async') {
-        response = await client.validateAndPoll(files, frameworks, options);
+        response = await client.validateAndPoll(files, frameworks, options, vcsLocalOnly);
     }
     else if (mode === 'chunked') {
-        response = await client.validateChunked(files, frameworks, options);
+        response = await client.validateChunked(files, frameworks, options, vcsLocalOnly);
     }
     else {
-        response = await client.validate(files, frameworks, options);
+        response = await client.validate(files, frameworks, options, vcsLocalOnly);
     }
     // Pull `scannerError` through if the API set it. Picking the field
     // explicitly (rather than `...response`) so the CLI's public surface
@@ -109,9 +117,15 @@ async function scan(params) {
  * endpoint, used by coding-agent post-edit hooks).
  */
 async function gate(options) {
-    const { files, frameworks = ['soc2'], ...scanOpts } = options;
-    const client = new api_client_1.ComplianceApiClient(options.apiUrl, options.apiKey);
-    const response = await client.hook(files, frameworks, scanOpts);
+    const { files, frameworks = ['soc2'], severityThreshold = 'medium', failOn = ['critical', 'high'], config = {}, apiKey, apiUrl, } = options;
+    const client = new api_client_1.ComplianceApiClient(apiUrl, apiKey);
+    // Forward severityThreshold/failOn/config to the hook endpoint so programmatic
+    // callers can influence server-side filtering the same way scan() does — and
+    // so Node and Python gate() send identical defaults (medium / [critical,high])
+    // for the same input. Applying the defaults here (rather than relying on a
+    // rest-spread of caller-supplied keys) keeps the two SDKs in lockstep with the
+    // documented contract; see python/src/prodcycle/__init__.py `gate()`.
+    const response = await client.hook(files, frameworks, { severityThreshold, failOn, config });
     // Same scannerError plumbing as scan() above. Coding-agent hooks
     // especially need to distinguish "code is clean" from "scanner is
     // down" — agents should NOT proceed on the latter.

package/dist/utils/config.d.ts

@@ -22,7 +22,8 @@ export declare function readConfig(): ProdcycleConfig;
 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.
+ * `--api-key`), the `PRODCYCLE_API_KEY` env var (legacy `PC_API_KEY` still
+ * accepted with a deprecation notice), then the user-level config file.
  * Returns `''` when none is configured.
  *
  * Pass an already-read `config` to avoid re-reading the file when the
@@ -30,7 +31,8 @@ export declare function writeApiKey(apiKey: string): string;
  */
 export declare function resolveApiKey(explicit?: string, config?: ProdcycleConfig): string;
 /**
- * Resolve the API URL: explicit value → `PC_API_URL` env → config file →
+ * Resolve the API URL: explicit value → `PRODCYCLE_API_URL` env (legacy
+ * `PC_API_URL` still accepted with a deprecation notice) → config file →
  * `undefined` (the caller then applies its own default). Accepts an
  * already-read `config` — see `resolveApiKey`.
  */

package/dist/utils/config.js

@@ -2,8 +2,8 @@
 // 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
+// `PRODCYCLE_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.
 //
@@ -54,6 +54,30 @@ 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;
+// Track which deprecated env vars we've already warned about, so a long-lived
+// process (e.g. a watch-mode agent hook) warns at most once per variable.
+const warnedDeprecatedEnv = new Set();
+/**
+ * Read an env var, preferring `preferred` and falling back to the legacy
+ * `deprecated` name. When only the legacy name is set, emit a one-time
+ * deprecation notice on stderr so existing users keep working but are nudged
+ * to the new name. Returns `undefined` when neither is set.
+ *
+ * The env vars were renamed `PC_*` → `PRODCYCLE_*` to unify with the
+ * `prodcycle/actions` GitHub Action (which already used `PRODCYCLE_API_KEY`).
+ */
+function envWithDeprecatedFallback(preferred, deprecated) {
+    const current = process.env[preferred];
+    if (current)
+        return current;
+    const legacy = process.env[deprecated];
+    if (legacy && !warnedDeprecatedEnv.has(deprecated)) {
+        warnedDeprecatedEnv.add(deprecated);
+        process.stderr.write(`Warning: ${deprecated} is deprecated and will be removed in a future ` +
+            `release; use ${preferred} instead.\n`);
+    }
+    return legacy;
+}
 /**
  * Path to the user-level config file:
  * `$XDG_CONFIG_HOME/prodcycle/config.json`, falling back to
@@ -110,20 +134,28 @@ function writeApiKey(apiKey) {
 }
 /**
  * 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.
+ * `--api-key`), the `PRODCYCLE_API_KEY` env var (legacy `PC_API_KEY` still
+ * accepted with a deprecation notice), 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 || '';
+    return (explicit ||
+        envWithDeprecatedFallback('PRODCYCLE_API_KEY', 'PC_API_KEY') ||
+        (config ?? readConfig()).api_key ||
+        '');
 }
 /**
- * Resolve the API URL: explicit value → `PC_API_URL` env → config file →
+ * Resolve the API URL: explicit value → `PRODCYCLE_API_URL` env (legacy
+ * `PC_API_URL` still accepted with a deprecation notice) → 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;
+    return (explicit ||
+        envWithDeprecatedFallback('PRODCYCLE_API_URL', 'PC_API_URL') ||
+        (config ?? readConfig()).api_url ||
+        undefined);
 }

package/dist/utils/vcs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Repo-relative paths (subset of candidatePaths) that are local-only: git
+ * IGNORES them, does NOT track them, AND they were never committed in any
+ * reachable history. Async (non-blocking) variant of the engine's
+ * `computeVcsLocalOnly` in @prodcycle/compliance-code-scanner; the LOGIC is
+ * identical, so keep the two in sync. The hosted API (which collects in a
+ * sandbox without a real `.git`) relies on this hint to downgrade secrets in
+ * local-only files.
+ *
+ * Recall-safe by construction:
+ *  - tracked files (even force-added past `.gitignore`) are filtered out before
+ *    the ignore check, so a currently-committed secret is never local-only;
+ *  - a file that was committed then `rm --cached`'d + gitignored is untracked
+ *    AND ignored, yet still recoverable from `git log --all` — the history
+ *    check excludes it so its secret stays critical (the real-leak case).
+ * Fail-safe: returns [] on any git error / non-repo / shallow clone — a
+ * truncated history can't prove a path was never committed, so we downgrade
+ * nothing rather than risk masking a leak.
+ */
+export declare function computeVcsLocalOnly(repoRoot: string, candidatePaths: string[]): Promise<string[]>;

package/dist/utils/vcs.js

@@ -0,0 +1,139 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeVcsLocalOnly = computeVcsLocalOnly;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const GIT_TIMEOUT_MS = 10_000;
+const toPosix = (p) => p.split(node_path_1.default.sep).join('/');
+/**
+ * Run `git -C <repoRoot> <args>` WITHOUT blocking the event loop — the CLI runs
+ * this mid-scan alongside async HTTP, and `git ls-files` on a large repo can
+ * take seconds. Optional `input` is written to stdin (for `check-ignore
+ * --stdin`). Resolves with stdout + exit code; rejects only when git cannot be
+ * spawned (e.g. not installed).
+ */
+function runGit(repoRoot, args, input) {
+    return new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.spawn)('git', ['-C', repoRoot, ...args], {
+            stdio: ['pipe', 'pipe', 'ignore'],
+            timeout: GIT_TIMEOUT_MS,
+        });
+        let stdout = '';
+        child.stdout.setEncoding('utf-8');
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk;
+        });
+        child.once('error', reject); // git missing / spawn failure
+        child.once('close', (code) => resolve({ stdout, code: code ?? 1 }));
+        if (input !== undefined)
+            child.stdin.write(input);
+        child.stdin.end();
+    });
+}
+/**
+ * Repo-relative paths (subset of candidatePaths) that are local-only: git
+ * IGNORES them, does NOT track them, AND they were never committed in any
+ * reachable history. Async (non-blocking) variant of the engine's
+ * `computeVcsLocalOnly` in @prodcycle/compliance-code-scanner; the LOGIC is
+ * identical, so keep the two in sync. The hosted API (which collects in a
+ * sandbox without a real `.git`) relies on this hint to downgrade secrets in
+ * local-only files.
+ *
+ * Recall-safe by construction:
+ *  - tracked files (even force-added past `.gitignore`) are filtered out before
+ *    the ignore check, so a currently-committed secret is never local-only;
+ *  - a file that was committed then `rm --cached`'d + gitignored is untracked
+ *    AND ignored, yet still recoverable from `git log --all` — the history
+ *    check excludes it so its secret stays critical (the real-leak case).
+ * Fail-safe: returns [] on any git error / non-repo / shallow clone — a
+ * truncated history can't prove a path was never committed, so we downgrade
+ * nothing rather than risk masking a leak.
+ */
+async function computeVcsLocalOnly(repoRoot, candidatePaths) {
+    if (candidatePaths.length === 0)
+        return [];
+    const root = node_path_1.default.resolve(repoRoot);
+    let tracked;
+    try {
+        const { stdout, code } = await runGit(root, ['ls-files', '-z']);
+        if (code !== 0)
+            return []; // not a git work tree / git error → fail safe
+        tracked = new Set(stdout.split('\0').filter(Boolean));
+    }
+    catch {
+        return []; // git not available → fail safe
+    }
+    const candidates = [...new Set(candidatePaths.map(toPosix))].filter((p) => !tracked.has(p));
+    if (candidates.length === 0)
+        return [];
+    let ignoredUntracked;
+    try {
+        // check-ignore exits 0 when ≥1 path is ignored, 1 when none (stdout empty),
+        // 128 on error. Treat anything other than 0/1 as a failure → fail safe.
+        const { stdout, code } = await runGit(root, ['check-ignore', '--stdin', '-z'], candidates.join('\0'));
+        if (code !== 0 && code !== 1)
+            return [];
+        const ignored = new Set(stdout.split('\0').filter(Boolean));
+        ignoredUntracked = candidates.filter((p) => ignored.has(p));
+    }
+    catch {
+        return [];
+    }
+    if (ignoredUntracked.length === 0)
+        return [];
+    // Truncated history can't disprove a past commit → keep everything critical.
+    // Detect shallowness via the marker file located with `--git-path shallow`
+    // (git ≥ 2.5) rather than `--is-shallow-repository` (git ≥ 2.15), so the
+    // downgrade feature isn't silently disabled on older git toolchains.
+    try {
+        const { stdout, code } = await runGit(root, ['rev-parse', '--git-path', 'shallow']);
+        if (code !== 0)
+            return []; // old/unsupported git → fail safe
+        const marker = stdout.trim();
+        if (!marker)
+            return [];
+        const abs = node_path_1.default.isAbsolute(marker) ? marker : node_path_1.default.join(root, marker);
+        if ((0, node_fs_1.existsSync)(abs))
+            return []; // shallow clone → downgrade nothing
+    }
+    catch {
+        return [];
+    }
+    // Exclude any candidate that appears in committed history (every branch, tag,
+    // remote-tracking ref). `--all` walks all refs; `--diff-filter=A` emits only
+    // ADDED entries so a wide commit contributes just the candidate's
+    // introduction (proving it was once in history) while keeping output small.
+    // `-m` decomposes merge commits into per-parent diffs — without it, a merge's
+    // COMBINED diff omits a file added on only one side of a true 2-parent merge
+    // (a recall hole); `-m` surfaces it as "A" against the mainline parent.
+    // `--no-renames` keeps names literal so a renamed-away path still matches its
+    // old name. The `-- <paths>` pathspec restricts the walk to our candidates.
+    try {
+        const { stdout, code } = await runGit(root, [
+            'log',
+            '--all',
+            '-m',
+            '--no-renames',
+            '--diff-filter=A',
+            '--format=',
+            '--name-only',
+            '-z',
+            '--',
+            ...ignoredUntracked,
+        ]);
+        if (code !== 0)
+            return []; // fail safe: assume in history
+        const candSet = new Set(ignoredUntracked);
+        // -z separates with NUL; an empty --format still emits stray newlines. Split
+        // on both and keep only candidate tokens (membership is all we need).
+        const everCommitted = new Set(stdout.split(/[\0\n]/).filter((t) => candSet.has(t)));
+        return ignoredUntracked.filter((p) => !everCommitted.has(p));
+    }
+    catch {
+        return [];
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prodcycle/prodcycle",
-  "version": "0.6.10",
+  "version": "0.6.12",
   "description": "Multi-framework policy-as-code compliance scanner for infrastructure and application code.",
   "homepage": "https://docs.prodcycle.com",
   "repository": {
@@ -32,7 +32,10 @@
     "security"
   ],
   "author": "ProdCycle, Inc. <engineering@prodcycle.com>",
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22"
+  },
   "dependencies": {
     "commander": "^12.0.0",
     "minimatch": "^9.0.3"