npq 3.25.0 → 3.27.0

package/README.md

@@ -31,7 +31,7 @@ Media coverage about npq:
 
 ## About
 
-Once npq is installed, you can safely* install packages:
+Once npq is installed, you can safely\* install packages:
 
 ```bash
 npq install express
@@ -39,12 +39,12 @@ npq install express
 
 `npq` will perform the following steps to sanity check that the package is safe by employing syntactic heuristics and querying a CVE database:
 
-* Consult the [snyk.io database of publicly disclosed vulnerabilities](https://snyk.io/vuln) to check if a security vulnerability exists for this package and its version.
-* Package age on npm
-* Package download count as a popularity metric
-* Package has a README file
-* Package has a LICENSE file
-* Package has pre/post install scripts
+- Consult the [snyk.io database of publicly disclosed vulnerabilities](https://snyk.io/vuln) to check if a security vulnerability exists for this package and its version.
+- Package age on npm
+- Package download count as a popularity metric
+- Package has a README file
+- Package has a LICENSE file
+- Package has pre/post install scripts
 
 **IMPORTANT**: npq by default uses an auto-continue mode when warnings are detected (no errors), waiting 15 seconds before proceeding with the installation. You can disable this behavior via the `--disable-auto-continue` CLI flag or the `NPQ_DISABLE_AUTO_CONTINUE=true` environment variable to enforce a strict review and security hardened installs. See [the auto-continue documentation](docs/feature/auto-continue.md) for more details.
 
@@ -62,7 +62,7 @@ When npq completes its signal checks it hands over the actual package install jo
 npm install -g npq
 ```
 
-*Note: we recommend installing with `npm` rather than `yarn`. That way, `npq` can automatically install shell aliases for you.*
+_Note: we recommend installing with `npm` rather than `yarn`. That way, `npq` can automatically install shell aliases for you._
 
 You can also install `npq` via [Homebrew](https://brew.sh) on macOS or Linux:
 
@@ -114,7 +114,7 @@ alias yarn="NPQ_PKG_MGR=yarn npq-hero"
 NPQ_PKG_MGR=yarn yarn run npq-hero
 ```
 
-or 
+or
 
 ```bash
 NPQ_PKG_MGR=yarn yarn exec npq-hero
@@ -137,23 +137,23 @@ Note: `npq` by default will offload all commands and their arguments to the `npm
 
 ## Marshalls
 
-| Marshall Name | Description | Notes
-| --- | --- | ---
-| age | Will show a warning for a package if its age on npm is less than 22 days | Checks a package creation date, not a specific version
-| author | Validates the resolved version’s publisher (`_npmUser`), flags a **new** maintainer on the package (first publish by that email within 21 days), **dormant maintainer** gaps (warning if over ~6 months since their last publish on that package, error if over ~9 months), and very **recent** publishes | See [docs/feature/author-marshall.md](docs/feature/author-marshall.md)
-| downloads | Will show a warning for a package if its download count in the last month is less than 20 | Reports `not evaluated` for custom-registry packages instead of querying the public npm downloads service
-| readme | Will show a warning if a package has no README or it has been detected as a security placeholder package by npm staff
-| repo | Will show a warning if a package has been found without a valid and working repository URL | Checks the latest version for a repository URL
-| scripts | Will show a warning if a package has a pre/post install script which could potentially be malicious
-| snyk | Will show a warning if a package has been found with vulnerabilities in Snyk's database | For Snyk to work you need to either have the `snyk` npm package installed with a valid API token, or make the token available in the `SNYK_TOKEN` environment variable, and npq will use it
-| license | Will show a warning if a package has been found without a license field | Checks the latest version for a license
-| expired domains | Normalizes and checks complete maintainer email hosts, then corroborates a simple two-label DNS failure through authoritative RDAP before warning | Multipart and otherwise inconclusive results are reported as not evaluated; see [expired-domain marshall documentation](docs/feature/expired-domains.md)
-| signatures | Will compare the package's signature as it shows on the registry's packument with signing keys published by the selected registry | Reports `not evaluated` if the selected registry does not expose signing keys
-| provenance | Will verify the package's attestations of provenance metadata for the published package, and **error** on [provenance regression](docs/feature/provenance.md) (an older semver had registry provenance metadata but the version you install does not) | Reports `not evaluated` if the selected registry does not expose signing keys or attestations
-| version-maturity | Will show an error if the specific version being installed was published less than 7 days ago | Suggests the highest older semver outside npq's 30-day version-recency window when one is available
-| newBin | Will show a warning if the package version being installed introduces a new command-line binary (via the `bin` field in `package.json`) that was not present in its previous version. | Helps identify potentially unexpected new executables being added to your `node_modules/.bin/` directory.
-| typosquatting | Will show a warning if the package name is similar to a popular package name, which could indicate a potential typosquatting attack. | Helps identify packages that may be trying to trick users into installing them by mimicking popular package names.
-| deprecation | Will show a warning if the package version is deprecated on npm or if its GitHub repository has been archived. | Helps identify packages that are no longer maintained or recommended for use. Set `GITHUB_TOKEN` environment variable for higher GitHub API rate limits.
+| Marshall Name    | Description                                                                                                                                                                                                                                                                                               | Notes                                                                                                                                                                                       |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| age              | Will show a warning for a package if its age on npm is less than 22 days                                                                                                                                                                                                                                  | Checks a package creation date, not a specific version                                                                                                                                      |
+| author           | Validates the resolved version’s publisher (`_npmUser`), flags a **new** maintainer on the package (first publish by that email within 21 days), **dormant maintainer** gaps (warning if over ~6 months since their last publish on that package, error if over ~9 months), and very **recent** publishes | See [docs/feature/author-marshall.md](docs/feature/author-marshall.md)                                                                                                                      |
+| downloads        | Will show a warning for a package if its download count in the last month is less than 20                                                                                                                                                                                                                 | Reports `not evaluated` for custom-registry packages instead of querying the public npm downloads service                                                                                   |
+| readme           | Will show a warning if a package has no README or it has been detected as a security placeholder package by npm staff                                                                                                                                                                                     |
+| repo             | Will show a warning if a package has been found without a valid and working repository URL                                                                                                                                                                                                                | Checks the latest version for a repository URL                                                                                                                                              |
+| scripts          | Will show a warning if a package has a pre/post install script which could potentially be malicious                                                                                                                                                                                                       |
+| snyk             | Will show a warning if a package has been found with vulnerabilities in Snyk's database                                                                                                                                                                                                                   | For Snyk to work you need to either have the `snyk` npm package installed with a valid API token, or make the token available in the `SNYK_TOKEN` environment variable, and npq will use it |
+| license          | Will show a warning if a package has been found without a license field                                                                                                                                                                                                                                   | Checks the latest version for a license                                                                                                                                                     |
+| expired domains  | Normalizes and checks complete maintainer email hosts, then corroborates a simple two-label DNS failure through authoritative RDAP before warning                                                                                                                                                         | Multipart and otherwise inconclusive results are reported as not evaluated; see [expired-domain marshall documentation](docs/feature/expired-domains.md)                                    |
+| signatures       | Will compare the package's signature as it shows on the registry's packument with signing keys published by the selected registry                                                                                                                                                                         | Reports `not evaluated` if the selected registry does not expose signing keys                                                                                                               |
+| provenance       | Will verify the package's attestations of provenance metadata for the published package, and **error** on [provenance regression](docs/feature/provenance.md) (an older semver had registry provenance metadata but the version you install does not)                                                     | Reports `not evaluated` if the selected registry does not expose signing keys or attestations                                                                                               |
+| version-maturity | Will show an error if the specific version being installed was published less than 7 days ago                                                                                                                                                                                                             | Suggests the highest older semver outside npq's 30-day version-recency window when one is available                                                                                         |
+| newBin           | Will show a warning if the package version being installed introduces a new command-line binary (via the `bin` field in `package.json`) that was not present in its previous version.                                                                                                                     | Helps identify potentially unexpected new executables being added to your `node_modules/.bin/` directory.                                                                                   |
+| typosquatting    | Will show a warning if the package name is similar to a popular package name, which could indicate a potential typosquatting attack.                                                                                                                                                                      | Helps identify packages that may be trying to trick users into installing them by mimicking popular package names.                                                                          |
+| deprecation      | Will show a warning if the package version is deprecated on npm or if its GitHub repository has been archived.                                                                                                                                                                                            | Helps identify packages that are no longer maintained or recommended for use. Set `GITHUB_TOKEN` environment variable for higher GitHub API rate limits.                                    |
 
 ### Older release suggestions
 
@@ -186,13 +186,12 @@ Example, to disable the Snyk vulnerability marshall:
 MARSHALL_DISABLE_SNYK=1 npq install express
 ```
 
-
 #### Available Marshall Environment Variables
 
 Here are all the available environment variable names for disabling specific marshalls:
 
 | Marshall Name    | Environment Variable                          | Description                                         |
-|------------------|-----------------------------------------------|-----------------------------------------------------|
+| ---------------- | --------------------------------------------- | --------------------------------------------------- |
 | age              | `MARSHALL_DISABLE_AGE`                        | Disable package age checks                          |
 | author           | `MARSHALL_DISABLE_AUTHOR`                     | Disable package author verification                 |
 | downloads        | `MARSHALL_DISABLE_DOWNLOADS`                  | Disable download count checks                       |
@@ -212,6 +211,8 @@ Here are all the available environment variable names for disabling specific mar
 
 Running `npq` without an `install` / `i` / `add` subcommand (for example from a project directory with a `package.json`) audits dependencies only and does not run the package manager. The same applies to `npq <package>`: checks only, no install passthrough. Use `npq install …` when you want npq to hand off to npm (or `NPQ_PKG_MGR`) after the checks.
 
+Project-mode audits currently cover only declared direct dependencies from the current project's `package.json` (`dependencies` and `devDependencies`). They do not read lockfiles or discover transitive dependencies.
+
 ```sh
 npq install express --dry-run
 ```
@@ -230,18 +231,47 @@ 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 [JSON audit output](docs/feature/json-output.md#coding-agent-detection).
+When npq detects a supported coding-agent environment, non-install audits still
+use the same audit-only JSON mode automatically. Explicit `npq install ...` and
+recognized `npq-hero install ...` commands keep the normal audit/install
+pipeline instead, using coding-agent detection as an authorization for
+warning-only installs. 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).
 
+### Non-interactive installs
+
+npq never uses the warning countdown when standard input is not interactive. If
+an audit reports warnings or errors in CI, npq exits nonzero and does not
+invoke the package manager.
+
+For ordinary automation that intentionally wants warning-only installs to
+continue, opt in explicitly:
+
+```sh
+npq install express --allow-non-interactive-install
+NPQ_ALLOW_NON_INTERACTIVE_INSTALL=true npq install express
+```
+
+When you use `npq-hero` or an aliased package manager, the ordinary opt-in is
+environment-only because the wrapper does not expose its own CLI flags:
+
+```sh
+NPQ_ALLOW_NON_INTERACTIVE_INSTALL=true npm install express
+```
+
+Detected coding-agent environments are treated as an explicit opt-in for
+`npq install express` and `npq-hero install express`, so agent-driven
+package-manager installs continue without the extra flag. Explicit `--json`
+remains audit-only and never invokes the package manager.
+
 ### 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:
+By default, when npq detects only warnings (no errors), it automatically proceeds with installation after a 15-second countdown. To disable this behavior and require explicit confirmation in an interactive terminal:
 
 **Using the CLI flag:**
 
@@ -262,7 +292,10 @@ Or set it permanently in your shell profile (`.bashrc`, `.zshrc`, etc.):
 export NPQ_DISABLE_AUTO_CONTINUE=true
 ```
 
-When auto-continue is disabled, npq will always prompt for explicit confirmation before proceeding with installation, even when only warnings are detected.
+When auto-continue is disabled, npq prompts for explicit confirmation in an
+interactive terminal. Non-interactive warning-only installs remain fail-closed
+unless the explicit non-interactive install opt-in or coding-agent authorization
+applies.
 
 ## Learn Node.js Security
 
@@ -286,25 +319,25 @@ When auto-continue is disabled, npq will always prompt for explicit confirmation
 
 1. **What is the difference between `npq` and `npq-hero`?**
 
-* `npq` is meant to be its own stand-alone CLI so it has command line flags like `--dry-run` and others (see `npq --help`). However, when you want to alias the `npm` CLI to NPQ you should use `npq-hero` as the executable of the alias to npm (e.g: `alias npm=npq`), which means `npq-hero` can't have its own command-line flags because they could conflict with the `npm` executable.
+- `npq` is meant to be its own stand-alone CLI so it has command line flags like `--dry-run` and others (see `npq --help`). However, when you want to alias the `npm` CLI to NPQ you should use `npq-hero` as the executable of the alias to npm (e.g: `alias npm=npq`), which means `npq-hero` can't have its own command-line flags because they could conflict with the `npm` executable.
 
 2. **Can I use NPQ without having npm or yarn?**
 
-* NPQ will audit a package for possible security issues, but it isn't a replacement for npm or yarn. When you choose to continue installing the package, it will offload the installation process to your choice of either npm or yarn.
+- NPQ will audit a package for possible security issues, but it isn't a replacement for npm or yarn. When you choose to continue installing the package, it will offload the installation process to your choice of either npm or yarn.
 
 3. **How is NPQ different from npm audit?**
 
-* `npm install` will install a module even if it has vulnerabilities; NPQ will display the issues detected, and prompt the user for confirmation on whether to proceed installing it.
-* NPQ will run synthetic checks, called [marshalls](https://github.com/lirantal/npq#marshalls), on the characteristics of a module, such as whether the module you are going to install has a `pre-install` script which can be potentially harmful for your system and prompt you whether to install it. Whereas `npm audit` will not perform any such checks, and only consults a vulnerability database for known security issues.
-* `npm audit` is closer in functionality to what Snyk does, rather than what NPQ does.
+- `npm install` will install a module even if it has vulnerabilities; NPQ will display the issues detected, and prompt the user for confirmation on whether to proceed installing it.
+- NPQ will run synthetic checks, called [marshalls](https://github.com/lirantal/npq#marshalls), on the characteristics of a module, such as whether the module you are going to install has a `pre-install` script which can be potentially harmful for your system and prompt you whether to install it. Whereas `npm audit` will not perform any such checks, and only consults a vulnerability database for known security issues.
+- `npm audit` is closer in functionality to what Snyk does, rather than what NPQ does.
 
 4. **Do I require a Snyk API key in order to use NPQ?**
 
-* It's not required. If NPQ is unable to detect a Snyk API key for the user running NPQ, then it will skip the database vulnerabilities check. We do, however, greatly encourage you to use Snyk, and connect it with NPQ for broader security.
+- It's not required. If NPQ is unable to detect a Snyk API key for the user running NPQ, then it will skip the database vulnerabilities check. We do, however, greatly encourage you to use Snyk, and connect it with NPQ for broader security.
 
 5. **Why is NPQ connecting to external domains like gmail.com or personal websites during installation?**
 
-* This is not telemetry. NPQ does not collect any usage data. When auditing a package, NPQ fetches the maintainers/authors of the dependency and checks their email addresses to verify they are valid and not associated with expired domains. Expired domains can be abused by attackers for account takeover (ATO) attacks to compromise packages with malicious versions. Hence, NPQ may make DNS requests to domains like `gmail.com` or personal domains found in maintainer emails. After a simple two-label domain returns NXDOMAIN and its top-level domain resolves, NPQ may fetch the official IANA RDAP bootstrap and query the selected authoritative HTTPS RDAP service, sending only the normalized two-label domain. Additionally, NPQ makes HTTP requests to `osv.dev` to fetch security vulnerability data (or uses Snyk if configured, as a prioritized option).
+- This is not telemetry. NPQ does not collect any usage data. When auditing a package, NPQ fetches the maintainers/authors of the dependency and checks their email addresses to verify they are valid and not associated with expired domains. Expired domains can be abused by attackers for account takeover (ATO) attacks to compromise packages with malicious versions. Hence, NPQ may make DNS requests to domains like `gmail.com` or personal domains found in maintainer emails. After a simple two-label domain returns NXDOMAIN and its top-level domain resolves, NPQ may fetch the official IANA RDAP bootstrap and query the selected authoritative HTTPS RDAP service, sending only the normalized two-label domain. Additionally, NPQ makes HTTP requests to `osv.dev` to fetch security vulnerability data (or uses Snyk if configured, as a prioritized option).
 
 ## Documentation
 

package/bin/npq-hero.js

@@ -8,6 +8,7 @@ cliSupport.isEnvSupport() || (cliSupport.noSupportError() && cliSupport.packageM
 const pkgMgr = require('../lib/packageManager')
 const Marshall = require('../lib/marshall')
 const { CliParser } = require('../lib/cli')
+const { getProjectPackages } = require('../lib/helpers/sourcePackages')
 const cliPrompt = require('../lib/helpers/cliPrompt.js')
 const { reportResults } = require('../lib/helpers/reportResults')
 const { Spinner } = require('../lib/helpers/cliSpinner')
@@ -17,6 +18,10 @@ 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 {
+  getInstallAction,
+  createNonInteractiveInstallError
+} = require('../lib/helpers/installPolicy')
 
 const PACKAGE_MANAGER_TOOL = process.env.NPQ_PKG_MGR
 const DISABLE_AUTO_CONTINUE = process.env.NPQ_DISABLE_AUTO_CONTINUE === 'true'
@@ -35,25 +40,39 @@ try {
 if (cliArgs && cliArgs.json) {
   runJsonCli(cliArgs, { output: createJsonOutput() })
 } else if (cliArgs) {
-  const silentModeNoPackages = !cliArgs || !cliArgs.packages || cliArgs.packages.length === 0
-
-  const isInteractive = cliSupport.isInteractiveTerminal() && !silentModeNoPackages
-  const spinner = isInteractive ? new Spinner({ text: 'Initiating...' }) : null
+  const isInteractive = cliSupport.isInteractiveTerminal()
+  const silentModeNoPackages = !cliArgs.installSubcommandExplicit && cliArgs.packages.length === 0
+  const spinner =
+    isInteractive && !silentModeNoPackages ? 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
+      const packagePromise =
+        cliArgs.installSubcommandExplicit && cliArgs.packages.length === 0
+          ? getProjectPackages()
+          : Promise.resolve(cliArgs.packages)
+
+      return packagePromise.then((packages) => {
+        if (packages && packages.error) {
+          CliParser.exit({
+            errorCode: typeof packages.error.code === 'number' ? packages.error.code : -1,
+            message: packages.message,
+            spinner
+          })
+        }
+
+        const marshall = new Marshall({
+          pkgs: packages,
+          registryClient,
+          progressManager: spinner,
+          promiseThrottleHelper
+        })
+        return marshall.process()
       })
-      return marshall.process()
     })
     .then((marshallResults) => {
       if (spinner) {
@@ -93,30 +112,32 @@ if (cliArgs && cliArgs.json) {
       return undefined
     })
     .then((result) => {
-      if (result && result.countErrors > 0) {
-        console.log()
+      const action = getInstallAction({
+        countErrors: result?.countErrors || 0,
+        countWarnings: result?.countWarnings || 0,
+        isInteractive,
+        disableAutoContinue: DISABLE_AUTO_CONTINUE,
+        allowNonInteractiveInstall: cliArgs.allowNonInteractiveInstall
+      })
+
+      if (action === 'reject') {
+        throw createNonInteractiveInstallError()
+      }
+
+      if (action === '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: 'Auto-continue with install in... ',
-            timeInSeconds: 15
-          })
-        }
+      }
+
+      if (action === 'countdown') {
+        return cliPrompt.autoContinue({
+          name: 'install',
+          message: 'Auto-continue with install in... ',
+          timeInSeconds: 15
+        })
       }
 
       return { install: true }
@@ -140,6 +161,8 @@ if (cliArgs && cliArgs.json) {
       let errorCode = -1
       if (typeof error.code === 'number') {
         errorCode = error.code
+      } else if (typeof error.exitCode === 'number') {
+        errorCode = error.exitCode
       } else if (error.code === 'ABORT_ERR') {
         errorCode = 1
       } else if (error.code === 'USER_ABORT') {

package/bin/npq.js

@@ -18,6 +18,10 @@ 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 {
+  getInstallAction,
+  createNonInteractiveInstallError
+} = require('../lib/helpers/installPolicy')
 const RegistryConfig = require('../lib/helpers/registryConfig')
 const RegistryClient = require('../lib/helpers/registryClient')
 
@@ -39,8 +43,8 @@ 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
+  const isInteractive = cliSupport.isInteractiveTerminal()
+  const spinner = isInteractive && !cliArgs.plain ? new Spinner({ text: 'Initiating...' }) : null
 
   if (spinner) {
     spinner.start()
@@ -127,30 +131,32 @@ if (cliArgs && cliArgs.json) {
         return undefined
       }
 
-      if (result && result.countErrors > 0) {
-        console.log()
+      const action = getInstallAction({
+        countErrors: result?.countErrors || 0,
+        countWarnings: result?.countWarnings || 0,
+        isInteractive,
+        disableAutoContinue: cliArgs.disableAutoContinue,
+        allowNonInteractiveInstall: cliArgs.allowNonInteractiveInstall
+      })
+
+      if (action === 'reject') {
+        throw createNonInteractiveInstallError()
+      }
+
+      if (action === '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: 'Auto-continue with install in... ',
-            timeInSeconds: 15
-          })
-        }
+      }
+
+      if (action === 'countdown') {
+        return cliPrompt.autoContinue({
+          name: 'install',
+          message: 'Auto-continue with install in... ',
+          timeInSeconds: 15
+        })
       }
 
       return { install: true }
@@ -174,6 +180,8 @@ if (cliArgs && cliArgs.json) {
       let errorCode = -1
       if (typeof error.code === 'number') {
         errorCode = error.code
+      } else if (typeof error.exitCode === 'number') {
+        errorCode = error.exitCode
       } else if (error.code === 'ABORT_ERR') {
         errorCode = 1
       } else if (error.code === 'USER_ABORT') {

package/lib/cli.js

@@ -74,6 +74,7 @@ class CliParser {
       'dry-run': { type: 'boolean' },
       plain: { type: 'boolean' },
       json: { type: 'boolean' },
+      'allow-non-interactive-install': { type: 'boolean' },
       packageManager: { type: 'string' },
       pkgMgr: { type: 'string' },
       'disable-auto-continue': { type: 'boolean' },
@@ -106,9 +107,10 @@ Options:
       --dry-run               Run checks only, don't install
       --plain                 Force non-rich text output
       --json                  Emit JSON and never install
+      --allow-non-interactive-install Allow warning-only installs without a TTY
       --packageManager        Package Manager to use (default: npm)
       --pkgMgr                Alias for packageManager
-      --disable-auto-continue Disable auto-continue countdown, always prompt
+      --disable-auto-continue Disable countdown; prompt when interactive
       --registry              npm registry used for audit and install
       --userconfig            Path to the user npm configuration file
       --globalconfig          Path to the global npm configuration file
@@ -118,6 +120,7 @@ Options:
 Environment Variables:
   NPQ_PKG_MGR                 Package manager to use; overrides --packageManager when set (default: npm)
   NPQ_DISABLE_AUTO_CONTINUE   Set to 'true' to disable auto-continue
+  NPQ_ALLOW_NON_INTERACTIVE_INSTALL Set to 'true' to allow warning-only non-TTY installs
 
 Examples:
   npq install express
@@ -133,10 +136,22 @@ curated by Liran Tal at https://github.com/lirantal/npq`)
     }
 
     // Process install command and packages
-    const json = values.json === true || isCodingAgentEnvironment()
-    const normalizedPackages = this._extractPackagesFromPositionals(positionals, false, json)
+    const explicitJson = values.json === true
     const installSubcommandExplicit =
       positionals.length > 0 && this.isInstallSubcommand(positionals[0])
+    const codingAgentDetected = isCodingAgentEnvironment()
+    const json = explicitJson || (codingAgentDetected && !installSubcommandExplicit)
+    const jsonPackageParsing = explicitJson || codingAgentDetected
+    const normalizedPackages = this._extractPackagesFromPositionals(
+      positionals,
+      false,
+      jsonPackageParsing
+    )
+    const allowNonInteractiveInstall =
+      !explicitJson &&
+      (values['allow-non-interactive-install'] === true ||
+        process.env.NPQ_ALLOW_NON_INTERACTIVE_INSTALL === 'true' ||
+        (codingAgentDetected && installSubcommandExplicit))
 
     return {
       packages: normalizedPackages,
@@ -144,6 +159,7 @@ curated by Liran Tal at https://github.com/lirantal/npq`)
       dryRun: values['dry-run'] || false,
       plain: values.plain || false,
       json,
+      allowNonInteractiveInstall,
       disableAutoContinue:
         values['disable-auto-continue'] || process.env.NPQ_DISABLE_AUTO_CONTINUE === 'true',
       registryConfigArgs: this.registryConfigArgs(values),
@@ -159,13 +175,21 @@ curated by Liran Tal at https://github.com/lirantal/npq`)
     })
     const installSubcommandExplicit =
       positionals.length > 0 && this.isInstallSubcommand(positionals[0])
-    const json = codingAgentEnvironment && installSubcommandExplicit
+    const codingAgentInstall = codingAgentEnvironment && installSubcommandExplicit
+    const jsonPackageParsing = codingAgentInstall
+    const json = false
+    const allowNonInteractiveInstall =
+      codingAgentInstall || process.env.NPQ_ALLOW_NON_INTERACTIVE_INSTALL === 'true'
     let normalizedPackages
 
     try {
-      normalizedPackages = this._extractPackagesFromPositionals(positionals, true, json)
+      normalizedPackages = this._extractPackagesFromPositionals(
+        positionals,
+        true,
+        jsonPackageParsing
+      )
     } catch (error) {
-      if (json && error && typeof error === 'object') {
+      if (jsonPackageParsing && error && typeof error === 'object') {
         Object.defineProperty(error, 'npqJsonMode', { value: true })
       }
       throw error
@@ -175,7 +199,8 @@ curated by Liran Tal at https://github.com/lirantal/npq`)
       packages: normalizedPackages,
       registryConfigArgs: this.registryConfigArgs(values),
       installSubcommandExplicit,
-      json
+      json,
+      allowNonInteractiveInstall
     }
   }
 }

package/lib/helpers/cliPrompt.js

@@ -3,6 +3,7 @@
 const { setTimeout } = require('node:timers/promises')
 const readline = require('node:readline/promises')
 const { stdin, stdout } = require('node:process')
+const { createNonInteractiveInstallError } = require('./installPolicy')
 
 /**
  * Simple CLI prompt for yes/no confirmation
@@ -70,6 +71,10 @@ async function prompt(options = {}) {
 }
 
 async function autoContinue({ name, message, timeInSeconds = 5 } = {}) {
+  if (!process.stdin.isTTY) {
+    throw createNonInteractiveInstallError()
+  }
+
   let aborted = false
   let userProceeded = false
 
@@ -150,32 +155,6 @@ async function autoContinue({ name, message, timeInSeconds = 5 } = {}) {
       cleanup()
       throw error
     }
-  } else {
-    // Fallback for non-TTY environments (tests, etc.)
-    // Show countdown message with instruction
-    process.stdout.write(`${message}${timeInSeconds} (press 'y' to proceed)`)
-
-    // Count down from timeInSeconds-1 to 1
-    for (let i = timeInSeconds - 1; i > 0; i--) {
-      await setTimeout(1000)
-
-      // Update similar to TTY version - backspace over number and instruction
-      const instructionText = " (press 'y' to proceed)"
-      const prevNumber = i + 1
-      const totalTextLength = prevNumber.toString().length + instructionText.length
-
-      // Backspace over everything, write new number and instruction
-      const backspaces = '\b'.repeat(totalTextLength)
-      process.stdout.write(`${backspaces}${i}${instructionText}`)
-    }
-
-    // Wait for the final second
-    await setTimeout(1000)
-
-    // Move to next line after countdown completes
-    console.log('')
-
-    return { [name]: true }
   }
 }
 

package/lib/helpers/cliSupportHandler.js

@@ -5,6 +5,20 @@ const { styleText } = require('node:util')
 const childProcess = require('child_process')
 const semver = require('semver')
 
+const CI_ENV_VARS = [
+  'CI',
+  'CONTINUOUS_INTEGRATION',
+  'BUILD_NUMBER',
+  'RUN_ID',
+  'GITHUB_ACTIONS',
+  'GITLAB_CI',
+  'TRAVIS',
+  'CIRCLECI',
+  'JENKINS_URL',
+  'TEAMCITY_VERSION',
+  'TF_BUILD'
+]
+
 const DEFAULT_PKGMGR = process.env.NPQ_PKG_MGR || 'npm'
 
 const nodeVersion = process.versions.node
@@ -46,31 +60,18 @@ function packageManagerPassthrough() {
  */
 function isInteractiveTerminal() {
   // Check common CI environment variables
-  const ciEnvVars = [
-    'CI',
-    'CONTINUOUS_INTEGRATION',
-    'BUILD_NUMBER',
-    'RUN_ID',
-    'GITHUB_ACTIONS',
-    'GITLAB_CI',
-    'TRAVIS',
-    'CIRCLECI',
-    'JENKINS_URL',
-    'TEAMCITY_VERSION',
-    'TF_BUILD'
-  ]
-
   // If any CI environment variable is set, we're likely in a CI environment
-  const isCI = ciEnvVars.some((envVar) => process.env[envVar])
+  const isCI = CI_ENV_VARS.some((envVar) => process.env[envVar])
 
-  // Check if stdout is a TTY (terminal)
-  const isTTY = Boolean(process.stdout.isTTY)
+  // Check if both stdin and stdout are TTYs (terminal)
+  const isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY)
 
   // We're interactive if we're in a TTY and not in CI
   return isTTY && !isCI
 }
 
 module.exports = {
+  CI_ENV_VARS,
   isEnvSupport,
   noSupportError,
   packageManagerPassthrough,

package/lib/helpers/codingAgentEnvironment.js

@@ -11,13 +11,34 @@ const CODING_AGENT_ENVIRONMENT_VARIABLES = Object.freeze([
   'WINDSURF_AGENT',
   'CODEIUM_AGENT',
   'AGENT',
-  'AI_AGENT'
+  'AI_AGENT',
+  'CLAUDE_CODE',
+  'REPL_ID',
+  'OPENCODE',
+  'AUGMENT_AGENT',
+  'GOOSE_PROVIDER',
+  'JUNIE_DATA',
+  'JUNIE_SHIM_PATH'
 ])
 
-function isCodingAgentEnvironment(env = process.env) {
-  return CODING_AGENT_ENVIRONMENT_VARIABLES.some(
-    (name) => typeof env[name] === 'string' && env[name].length > 0
-  )
+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/lib/helpers/installPolicy.js

@@ -0,0 +1,37 @@
+'use strict'
+
+function getInstallAction({
+  countErrors = 0,
+  countWarnings = 0,
+  isInteractive = false,
+  disableAutoContinue = false,
+  allowNonInteractiveInstall = false
+} = {}) {
+  if (countErrors > 0) {
+    return isInteractive ? 'prompt' : 'reject'
+  }
+
+  if (countWarnings > 0) {
+    if (isInteractive) {
+      return disableAutoContinue ? 'prompt' : 'countdown'
+    }
+
+    return !disableAutoContinue && allowNonInteractiveInstall ? 'install' : 'reject'
+  }
+
+  return 'install'
+}
+
+function createNonInteractiveInstallError() {
+  const error = new Error(
+    'Installation blocked: findings require an interactive terminal or an explicit non-interactive install opt-in.'
+  )
+  error.code = 'NON_INTERACTIVE_INSTALL'
+  error.exitCode = 1
+  return error
+}
+
+module.exports = {
+  getInstallAction,
+  createNonInteractiveInstallError
+}

package/lib/packageManager.js

@@ -1,6 +1,7 @@
 'use strict'
 
-const childProcess = require('child_process')
+const crossSpawn = require('cross-spawn')
+const LINE_BREAK_PATTERN = /[\r\n]/
 const DEFAULT_PKGMGR = 'npm'
 
 class packageManager {
@@ -10,35 +11,45 @@ class packageManager {
   }
 
   static spawnPackageManager(packageManagerOption) {
-    let args = []
-    args = args.concat(process.argv.slice(2)).filter((item) => {
+    const args = process.argv.slice(2).filter((item) => {
       switch (item) {
         case '--packageManager':
         case '--pkgMgr':
         case '--dry-run':
+        case '--allow-non-interactive-install':
           return false
         default:
-          return true
+          return !item.startsWith('--allow-non-interactive-install=')
       }
     })
 
-    let cmd = `${packageManagerOption}`
-    if (args.length > 0) {
-      cmd += ` ${args.join(' ')}`
+    if (args.some((item) => LINE_BREAK_PATTERN.test(item))) {
+      return Promise.reject(new Error('package manager arguments cannot contain line breaks'))
     }
 
-    const child = childProcess.spawn(cmd, {
+    const { executable, args: launchArgs } = packageManager.getPackageManagerLaunchSpec(
+      packageManagerOption,
+      args
+    )
+
+    const child = crossSpawn.spawn(executable, launchArgs, {
       stdio: 'inherit',
-      shell: true
+      shell: false
     })
 
-    return new Promise((resolve) => {
-      child.on('close', (code) => {
-        resolve(code)
-      })
+    return new Promise((resolve, reject) => {
+      child.once('error', reject)
+      child.once('close', resolve)
     })
   }
 
+  static getPackageManagerLaunchSpec(packageManagerOption, args) {
+    return {
+      executable: packageManagerOption,
+      args
+    }
+  }
+
   static validatePackageManager(packageManagerOption) {
     if (!packageManagerOption) {
       packageManagerOption = packageManager.getDefaultPackageManager()
@@ -48,6 +59,10 @@ class packageManager {
       throw new Error('a packageManager should be specified as a string')
     }
 
+    if (LINE_BREAK_PATTERN.test(packageManagerOption)) {
+      throw new Error('a packageManager should not contain line breaks')
+    }
+
     return packageManagerOption
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "npq",
-  "version": "3.25.0",
+  "version": "3.27.0",
   "description": "marshall your npm/npm package installs with high quality and class 🎖",
   "bin": {
     "npq": "./bin/npq.js",
@@ -45,6 +45,7 @@
   },
   "dependencies": {
     "@npmcli/config": "^10.10.0",
+    "cross-spawn": "^7.0.6",
     "npm-package-arg": "^13.0.2",
     "npm-registry-fetch": "^19.1.1",
     "semver": "^7.7.4",