node-ci-preflight

Deterministic, local-only diagnostics for Node.js package-manager, workspace, version-policy, and GitHub Actions install-command metadata.

node-ci-preflight is intentionally a diagnostic, not a package manager. It does not install dependencies, execute project code or lifecycle scripts, contact registries, rewrite files, parse/execute workflow YAML, or print package values other than a small allow-list of version metadata.

Install and run

npm install --save-dev node-ci-preflight
node-ci-preflight .
node-ci-preflight packages/app --json
node-ci-preflight . --format github

Node.js 18 or newer is required.

CLI and exits

node-ci-preflight [path] [--json | --format github]

• Exit 0: no findings.
• Exit 1: diagnostics found (warnings and errors are policy failures for CI).
• Exit 2: invalid arguments or malformed, unsafe, or unsupported metadata (including an invalid packageManager declaration).

Human output is the default. --json writes exactly one JSON document to stdout. --json and --format github are mutually exclusive. --format github emits GitHub workflow-command annotations such as:

::warning file=.github/workflows/ci.yml::[workflow-install-manager-mismatch] A GitHub Actions workflow contains a recognized install command for a different package manager.

The equivalent structured information is always available in JSON (ruleId, severity, evidence, explanation, remediation).

Checks

The tool detects an effective manager from local packageManager/lockfiles, an ancestor pnpm-workspace.yaml, or an ancestor packageManager/lockfile context (npm, pnpm, Yarn, and Bun). It reports:

• lockfile-conflict — lockfiles for more than one manager at the same root.
• package-manager-lockfile-mismatch — packageManager conflicts with a detected lockfile.
• node-version-mismatch — engines.node, .nvmrc, .node-version, or volta.node differ.
• workflow-install-manager-mismatch — a regular .github/workflows/*.yml|yaml file has an inline run: command for another manager (npm ci/install/i, pnpm install/i, yarn/yarn install, or bun install/i).
• unsafe-symlink — a candidate lockfile or the workflows directory is a symbolic link; it is not followed.

Evidence paths are project-relative where possible and values are limited to manager/version metadata or normalized recognized install commands. Arbitrary package.json fields, workflow text, environment values, and secrets are never reported.

Safety model and limits

Inputs are untrusted. Malformed package.json, unsafe/unsupported packageManager, and unsafe Node version metadata are invalid input (exit 2); symlinked lockfiles and workflow directories are not followed. Workflow inspection only recognizes inline run: values in regular files and is not a YAML parser: it may miss multiline, shell-variable, or unusual command forms, but ignores comments and non-run: text and never executes content. A present but unreadable workflow directory is invalid input rather than silently ignored. The CLI reads metadata only and does not modify the target repository.

Library API

import { inspectProject } from 'node-ci-preflight';

const report = await inspectProject('/workspace/project');
for (const finding of report.findings) {
  console.log(finding.ruleId, finding.severity);
}

inspectProject(path) resolves the supplied local path and returns a deterministic PreflightReport. Findings include a stable ruleId, severity (error, warning, or info), safe evidence, an explanation, and remediation.

Development

npm ci --ignore-scripts
npm run typecheck
npm test
npm pack --dry-run
npm audit

See CHANGELOG.md and LICENSE.