npq 3.24.0 → 3.26.0

package/README.md

@@ -230,6 +230,13 @@ Use `--json` for a non-interactive, audit-only result suitable for CI:
 npq install express --json
 ```
 
+When npq detects a supported coding-agent environment, it automatically uses
+the same audit-only JSON mode. This applies to `npq` and to install commands
+intercepted by `npq-hero`; non-install `npq-hero` commands still pass through to
+the configured package manager. See the [full coding-agent detection signal
+table](docs/feature/json-output.md#coding-agent-detection) for the supported
+signals and contextual matchers.
+
 JSON mode never invokes the package manager. It exits `0` for a clean audit,
 `1` for findings, and `2` when the audit cannot complete. See
 [JSON audit output](docs/feature/json-output.md).

package/bin/npq-hero.js

@@ -14,126 +14,142 @@ const { Spinner } = require('../lib/helpers/cliSpinner')
 const { promiseThrottleHelper } = require('../lib/helpers/promiseThrottler')
 const RegistryConfig = require('../lib/helpers/registryConfig')
 const RegistryClient = require('../lib/helpers/registryClient')
+const { createJsonOutput } = require('../lib/helpers/jsonOutput')
+const { runJsonCli, writeInvalidJsonInvocation } = require('../lib/jsonCli')
+const { isCodingAgentEnvironment } = require('../lib/helpers/codingAgentEnvironment')
 
 const PACKAGE_MANAGER_TOOL = process.env.NPQ_PKG_MGR
 const DISABLE_AUTO_CONTINUE = process.env.NPQ_DISABLE_AUTO_CONTINUE === 'true'
 
-const cliArgs = CliParser.parseArgsMinimal()
+const codingAgentEnvironment = isCodingAgentEnvironment()
+let cliArgs
 
-const silentModeNoPackages = !cliArgs || !cliArgs.packages || cliArgs.packages.length === 0
+try {
+  cliArgs = CliParser.parseArgsMinimal({ codingAgentEnvironment })
+} catch (error) {
+  if (!error || error.npqJsonMode !== true) throw error
+  writeInvalidJsonInvocation(createJsonOutput())
+  process.exitCode = 2
+}
 
-const isInteractive = cliSupport.isInteractiveTerminal() && !silentModeNoPackages
-const spinner = isInteractive ? new Spinner({ text: 'Initiating...' }) : null
+if (cliArgs && cliArgs.json) {
+  runJsonCli(cliArgs, { output: createJsonOutput() })
+} else if (cliArgs) {
+  const silentModeNoPackages = !cliArgs || !cliArgs.packages || cliArgs.packages.length === 0
 
-if (spinner) {
-  spinner.start()
-}
+  const isInteractive = cliSupport.isInteractiveTerminal() && !silentModeNoPackages
+  const spinner = isInteractive ? new Spinner({ text: 'Initiating...' }) : null
+
+  if (spinner) {
+    spinner.start()
+  }
 
-RegistryConfig.load({ argv: cliArgs.registryConfigArgs || [] })
-  .then((registryConfig) => {
-    const registryClient = new RegistryClient(registryConfig)
-    const marshall = new Marshall({
-      pkgs: cliArgs.packages,
-      registryClient,
-      progressManager: spinner,
-      promiseThrottleHelper
+  RegistryConfig.load({ argv: cliArgs.registryConfigArgs || [] })
+    .then((registryConfig) => {
+      const registryClient = new RegistryClient(registryConfig)
+      const marshall = new Marshall({
+        pkgs: cliArgs.packages,
+        registryClient,
+        progressManager: spinner,
+        promiseThrottleHelper
+      })
+      return marshall.process()
     })
-    return marshall.process()
-  })
-  .then((marshallResults) => {
-    if (spinner) {
-      spinner.stop()
-    }
+    .then((marshallResults) => {
+      if (spinner) {
+        spinner.stop()
+      }
 
-    const results = reportResults(marshallResults)
-    if (
-      results &&
-      Object.hasOwn(results, 'countErrors') &&
-      Object.hasOwn(results, 'countWarnings')
-    ) {
-      const { countErrors, countWarnings, countNotEvaluated = 0, useRichFormatting } = results
-      const hasFindings = countErrors > 0 || countWarnings > 0
-      const hasReportableResults = hasFindings || countNotEvaluated > 0
+      const results = reportResults(marshallResults)
+      if (
+        results &&
+        Object.hasOwn(results, 'countErrors') &&
+        Object.hasOwn(results, 'countWarnings')
+      ) {
+        const { countErrors, countWarnings, countNotEvaluated = 0, useRichFormatting } = results
+        const hasFindings = countErrors > 0 || countWarnings > 0
+        const hasReportableResults = hasFindings || countNotEvaluated > 0
 
-      if (hasReportableResults) {
-        console.log()
-        console.log(hasFindings ? 'Packages with issues found:' : 'Package checks not evaluated:')
+        if (hasReportableResults) {
+          console.log()
+          console.log(hasFindings ? 'Packages with issues found:' : 'Package checks not evaluated:')
 
-        if (useRichFormatting) {
-          console.log(results.resultsForPrettyPrint)
-          console.log(results.summaryForPrettyPrint)
-        } else {
-          console.log(results.resultsForPlainTextPrint)
-          console.log(results.summaryForPlainTextPrint)
+          if (useRichFormatting) {
+            console.log(results.resultsForPrettyPrint)
+            console.log(results.summaryForPrettyPrint)
+          } else {
+            console.log(results.resultsForPlainTextPrint)
+            console.log(results.summaryForPlainTextPrint)
+          }
         }
-      }
 
-      return {
-        anyIssues: hasFindings,
-        countErrors,
-        countWarnings,
-        countNotEvaluated
+        return {
+          anyIssues: hasFindings,
+          countErrors,
+          countWarnings,
+          countNotEvaluated
+        }
       }
-    }
-    return undefined
-  })
-  .then((result) => {
-    if (result && result.countErrors > 0) {
-      console.log()
-      return cliPrompt.prompt({
-        name: 'install',
-        message: 'Continue install ?',
-        default: false
-      })
-    } else {
-      if (result && result.countWarnings > 0) {
+      return undefined
+    })
+    .then((result) => {
+      if (result && result.countErrors > 0) {
         console.log()
-        // Check if auto-continue is disabled via environment variable
-        if (DISABLE_AUTO_CONTINUE) {
-          return cliPrompt.prompt({
+        return cliPrompt.prompt({
+          name: 'install',
+          message: 'Continue install ?',
+          default: false
+        })
+      } else {
+        if (result && result.countWarnings > 0) {
+          console.log()
+          // Check if auto-continue is disabled via environment variable
+          if (DISABLE_AUTO_CONTINUE) {
+            return cliPrompt.prompt({
+              name: 'install',
+              message: 'Continue install ?',
+              default: false
+            })
+          }
+          return cliPrompt.autoContinue({
             name: 'install',
-            message: 'Continue install ?',
-            default: false
+            message: 'Auto-continue with install in... ',
+            timeInSeconds: 15
           })
         }
-        return cliPrompt.autoContinue({
-          name: 'install',
-          message: 'Auto-continue with install in... ',
-          timeInSeconds: 15
-        })
       }
-    }
 
-    return { install: true }
-  })
-  .then((status) => {
-    if (
-      status &&
-      Object.prototype.hasOwnProperty.call(status, 'install') &&
-      status.install === true
-    ) {
-      return pkgMgr.process(PACKAGE_MANAGER_TOOL)
-    }
-  })
-  .then((exitCode) => {
-    if (typeof exitCode === 'number') {
-      process.exitCode = exitCode
-    }
-  })
-  .catch((error) => {
-    // Ensure errorCode is always a number
-    let errorCode = -1
-    if (typeof error.code === 'number') {
-      errorCode = error.code
-    } else if (error.code === 'ABORT_ERR') {
-      errorCode = 1
-    } else if (error.code === 'USER_ABORT') {
-      errorCode = error.exitCode || 1
-    }
+      return { install: true }
+    })
+    .then((status) => {
+      if (
+        status &&
+        Object.prototype.hasOwnProperty.call(status, 'install') &&
+        status.install === true
+      ) {
+        return pkgMgr.process(PACKAGE_MANAGER_TOOL)
+      }
+    })
+    .then((exitCode) => {
+      if (typeof exitCode === 'number') {
+        process.exitCode = exitCode
+      }
+    })
+    .catch((error) => {
+      // Ensure errorCode is always a number
+      let errorCode = -1
+      if (typeof error.code === 'number') {
+        errorCode = error.code
+      } else if (error.code === 'ABORT_ERR') {
+        errorCode = 1
+      } else if (error.code === 'USER_ABORT') {
+        errorCode = error.exitCode || 1
+      }
 
-    CliParser.exit({
-      errorCode,
-      message: error.message || 'An error occurred',
-      spinner
+      CliParser.exit({
+        errorCode,
+        message: error.message || 'An error occurred',
+        spinner
+      })
     })
-  })
+}

package/bin/npq.js

@@ -17,12 +17,13 @@ const { Spinner } = require('../lib/helpers/cliSpinner')
 const { promiseThrottleHelper } = require('../lib/helpers/promiseThrottler')
 const { createJsonOutput } = require('../lib/helpers/jsonOutput')
 const { runJsonCli, writeInvalidJsonInvocation } = require('../lib/jsonCli')
+const { isCodingAgentEnvironment } = require('../lib/helpers/codingAgentEnvironment')
 const RegistryConfig = require('../lib/helpers/registryConfig')
 const RegistryClient = require('../lib/helpers/registryClient')
 
 const debug = util.debuglog('npq')
 
-const jsonRequested = process.argv.slice(2).includes('--json')
+const jsonRequested = process.argv.slice(2).includes('--json') || isCodingAgentEnvironment()
 const jsonOutput = jsonRequested ? createJsonOutput() : null
 let cliArgs
 

package/lib/cli.js

@@ -3,6 +3,7 @@
 const { parseArgs } = require('node:util')
 const npa = require('npm-package-arg')
 const { parseJsonRegistryPackageSpec } = require('./helpers/jsonPackageSpec')
+const { isCodingAgentEnvironment } = require('./helpers/codingAgentEnvironment')
 const pkg = require('../package.json')
 const { parsePackageManagerArguments } = require('./helpers/packageManagerArgumentParser')
 
@@ -132,11 +133,8 @@ curated by Liran Tal at https://github.com/lirantal/npq`)
     }
 
     // Process install command and packages
-    const normalizedPackages = this._extractPackagesFromPositionals(
-      positionals,
-      false,
-      values.json === true
-    )
+    const json = values.json === true || isCodingAgentEnvironment()
+    const normalizedPackages = this._extractPackagesFromPositionals(positionals, false, json)
     const installSubcommandExplicit =
       positionals.length > 0 && this.isInstallSubcommand(positionals[0])
 
@@ -145,7 +143,7 @@ curated by Liran Tal at https://github.com/lirantal/npq`)
       packageManager: process.env.NPQ_PKG_MGR || values.packageManager || values.pkgMgr || 'npm',
       dryRun: values['dry-run'] || false,
       plain: values.plain || false,
-      json: values.json || false,
+      json,
       disableAutoContinue:
         values['disable-auto-continue'] || process.env.NPQ_DISABLE_AUTO_CONTINUE === 'true',
       registryConfigArgs: this.registryConfigArgs(values),
@@ -153,19 +151,31 @@ curated by Liran Tal at https://github.com/lirantal/npq`)
     }
   }
 
-  static parseArgsMinimal() {
+  static parseArgsMinimal({ codingAgentEnvironment = isCodingAgentEnvironment() } = {}) {
     const packageManager = process.env.NPQ_PKG_MGR || 'npm'
     const { values, positionals } = parsePackageManagerArguments({
       packageManager,
       args: process.argv.slice(2)
     })
-
-    const earlyExitNoInstall = true
-    const normalizedPackages = this._extractPackagesFromPositionals(positionals, earlyExitNoInstall)
+    const installSubcommandExplicit =
+      positionals.length > 0 && this.isInstallSubcommand(positionals[0])
+    const json = codingAgentEnvironment && installSubcommandExplicit
+    let normalizedPackages
+
+    try {
+      normalizedPackages = this._extractPackagesFromPositionals(positionals, true, json)
+    } catch (error) {
+      if (json && error && typeof error === 'object') {
+        Object.defineProperty(error, 'npqJsonMode', { value: true })
+      }
+      throw error
+    }
 
     return {
       packages: normalizedPackages,
-      registryConfigArgs: this.registryConfigArgs(values)
+      registryConfigArgs: this.registryConfigArgs(values),
+      installSubcommandExplicit,
+      json
     }
   }
 }

package/lib/helpers/codingAgentEnvironment.js

@@ -0,0 +1,44 @@
+'use strict'
+
+const CODING_AGENT_ENVIRONMENT_VARIABLES = Object.freeze([
+  'CLAUDECODE',
+  'CLAUDE_CODE_CHILD_SESSION',
+  'CURSOR_AGENT',
+  'PI_CODING_AGENT',
+  'CODEX_SANDBOX',
+  'CODEX_THREAD_ID',
+  'GEMINI_CLI',
+  'WINDSURF_AGENT',
+  'CODEIUM_AGENT',
+  'AGENT',
+  'AI_AGENT',
+  'CLAUDE_CODE',
+  'REPL_ID',
+  'OPENCODE',
+  'AUGMENT_AGENT',
+  'GOOSE_PROVIDER',
+  'JUNIE_DATA',
+  'JUNIE_SHIM_PATH'
+])
+
+function hasNonEmptyValue(env, name) {
+  return typeof env[name] === 'string' && env[name].length > 0
+}
+
+function isCodingAgentEnvironment(env = process.env, { stdoutIsTTY = process.stdout?.isTTY } = {}) {
+  if (CODING_AGENT_ENVIRONMENT_VARIABLES.some((name) => hasNonEmptyValue(env, name))) {
+    return true
+  }
+
+  if (typeof env.PATH === 'string' && /\.pi[\\/]agent/.test(env.PATH)) {
+    return true
+  }
+
+  if (typeof env.EDITOR === 'string' && /devin/i.test(env.EDITOR)) {
+    return true
+  }
+
+  return !stdoutIsTTY && typeof env.TERM_PROGRAM === 'string' && /kiro/i.test(env.TERM_PROGRAM)
+}
+
+module.exports = { CODING_AGENT_ENVIRONMENT_VARIABLES, isCodingAgentEnvironment }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "npq",
-  "version": "3.24.0",
+  "version": "3.26.0",
   "description": "marshall your npm/npm package installs with high quality and class 🎖",
   "bin": {
     "npq": "./bin/npq.js",