npq 3.23.3 → 3.25.0

package/README.md

@@ -222,6 +222,23 @@ npq install express --dry-run
 npq install express --plain
 ```
 
+### Machine-readable audits
+
+Use `--json` for a non-interactive, audit-only result suitable for CI:
+
+```sh
+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 [JSON audit output](docs/feature/json-output.md#coding-agent-detection).
+
+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).
+
 ### Disable auto-continue countdown
 
 By default, when npq detects only warnings (no errors), it automatically proceeds with installation after a 15-second countdown. To disable this behavior and always require explicit confirmation:

package/bin/npq-hero.js

@@ -14,133 +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

@@ -15,171 +15,183 @@ const cliPrompt = require('../lib/helpers/cliPrompt.js')
 const { reportResults } = require('../lib/helpers/reportResults')
 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 cliArgs = CliParser.parseArgsFull()
-const auditOnly = cliArgs.dryRun || !cliArgs.installSubcommandExplicit
-const isInteractive = cliSupport.isInteractiveTerminal() && !cliArgs.plain
-const spinner = isInteractive ? new Spinner({ text: 'Initiating...' }) : null
+const jsonRequested = process.argv.slice(2).includes('--json') || isCodingAgentEnvironment()
+const jsonOutput = jsonRequested ? createJsonOutput() : null
+let cliArgs
 
-if (spinner) {
-  spinner.start()
+try {
+  cliArgs = CliParser.parseArgsFull()
+} catch (error) {
+  if (!jsonRequested) throw error
+  writeInvalidJsonInvocation(jsonOutput)
+  process.exitCode = 2
 }
 
-let registryClient
+if (cliArgs && cliArgs.json) {
+  runJsonCli(cliArgs, { output: jsonOutput })
+} else if (cliArgs) {
+  const auditOnly = cliArgs.dryRun || !cliArgs.installSubcommandExplicit
+  const isInteractive = cliSupport.isInteractiveTerminal() && !cliArgs.plain
+  const spinner = isInteractive ? new Spinner({ text: 'Initiating...' }) : null
 
-RegistryConfig.load({ argv: cliArgs.registryConfigArgs || [] })
-  .then((registryConfig) => {
-    registryClient = new RegistryClient(registryConfig)
-  })
-  .then(() => {
-    if (cliArgs.packages.length === 0) {
-      debug('\nNo packages specified, using project packages from package.json')
-      return getProjectPackages()
-    }
+  if (spinner) {
+    spinner.start()
+  }
 
-    return cliArgs.packages
-  })
-  .then((packages) => {
-    if (packages.error) {
-      console.log()
-      CliParser.exit({
-        errorCode: packages.error.code || -1,
-        message: packages.message,
-        spinner
-      })
-    }
+  let registryClient
 
-    const marshall = new Marshall({
-      pkgs: packages,
-      registryClient,
-      progressManager: spinner,
-      promiseThrottleHelper
+  Promise.resolve()
+    .then(() => RegistryConfig.load({ argv: cliArgs.registryConfigArgs || [] }))
+    .then((registryConfig) => {
+      registryClient = new RegistryClient(registryConfig)
     })
+    .then(() => {
+      if (cliArgs.packages.length === 0) {
+        debug('\nNo packages specified, using project packages from package.json')
+        return getProjectPackages()
+      }
 
-    return marshall.process()
-  })
-  .then((marshallResults) => {
-    if (spinner) {
-      spinner.stop()
-    }
-
-    const results = reportResults(marshallResults, { plain: cliArgs.plain })
-    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) {
+      return cliArgs.packages
+    })
+    .then((packages) => {
+      if (packages.error) {
         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)
-        }
+        CliParser.exit({
+          errorCode: packages.error.code || -1,
+          message: packages.message,
+          spinner
+        })
       }
 
-      return {
-        anyIssues: hasFindings,
-        countErrors,
-        countWarnings,
-        countNotEvaluated
-      }
-    }
-    return undefined
-  })
-  .then((result) => {
-    if (auditOnly) {
-      const auditFailed = result && (result.countErrors > 0 || result.countWarnings > 0)
-      CliParser.exit({
-        errorCode: auditFailed ? 1 : 0,
-        spinner
+      const marshall = new Marshall({
+        pkgs: packages,
+        registryClient,
+        progressManager: spinner,
+        promiseThrottleHelper
       })
+
+      return marshall.process()
+    })
+    .then((marshallResults) => {
+      if (spinner) {
+        spinner.stop()
+      }
+
+      const results = reportResults(marshallResults, { plain: cliArgs.plain })
+      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 (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 undefined
-    }
-
-    if (result && result.countErrors > 0) {
-      console.log()
-      return cliPrompt.prompt({
-        name: 'install',
-        message: 'Continue install ?',
-        default: false
-      })
-    } else {
-      if (result && result.countWarnings > 0) {
+    })
+    .then((result) => {
+      if (auditOnly) {
+        const auditFailed = result && (result.countErrors > 0 || result.countWarnings > 0)
+        CliParser.exit({
+          errorCode: auditFailed ? 1 : 0,
+          spinner
+        })
+        return undefined
+      }
+
+      if (result && result.countErrors > 0) {
         console.log()
-        // Check if auto-continue is disabled via CLI flag or environment variable
-        if (cliArgs.disableAutoContinue) {
-          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 CLI flag or environment variable
+          if (cliArgs.disableAutoContinue) {
+            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(cliArgs.packageManager)
-    }
-  })
-  .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(cliArgs.packageManager)
+      }
+    })
+    .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
+      })
+    })
 
+  // attach event handler for CTRL+C
+  process.on('SIGINT', () => {
     CliParser.exit({
-      errorCode,
-      message: error.message || 'An error occurred',
+      errorCode: 0,
       spinner
     })
   })
-
-// attach event handler for CTRL+C
-process.on('SIGINT', () => {
-  CliParser.exit({
-    errorCode: 0,
-    spinner
-  })
-})
+}