Publish Doctor

Read-only npm publish preflight for metadata, tarball contents, high-confidence secrets, trusted-publishing readiness, and version collisions.

npx @nexkit/publish-doctor

Publish Doctor never edits the target project and never runs its lifecycle scripts.

Why

npm publish is the wrong time to discover that a tarball contains credentials, test artifacts, a missing binary, an existing version, or metadata that prevents provenance from being useful. Publish Doctor runs the release checks first and produces the same result locally and in CI.

Usage

# Audit the current package
npx @nexkit/publish-doctor

# Audit another directory
npx @nexkit/publish-doctor ./packages/cli

# Fail CI on warnings
npx @nexkit/publish-doctor . --strict

# Stable machine-readable report
npx @nexkit/publish-doctor . --json

# Skip the npm registry request
npx @nexkit/publish-doctor . --offline

Options

| Option | Effect | | --- | --- | | --json | Emit schema-versioned JSON and no human report. | | --strict | Treat warnings as a failed audit. | | --offline | Skip the exact package-version lookup on the npm registry. | | --help | Show usage. | | --version | Show the Publish Doctor version. |

Exit codes

| Code | Meaning | | --- | --- | | 0 | No blocking finding; warnings are allowed unless --strict is used. | | 1 | Blocking finding, or at least one warning in strict mode. | | 2 | Invalid usage, unreadable project, invalid JSON, or npm tool failure. |

Checks

Package metadata

• Package name, strict SemVer version, private, description, and license.
• Explicit files allowlist and scoped-package public access.
• Repository, funding, and supported Node.js engine metadata.
• Disabled provenance and non-registry dependency sources.
• Install-time and publish-time lifecycle scripts.

Exact tarball

Publish Doctor asks the installed npm CLI for the exact dry-run manifest:

npm pack --dry-run --json --ignore-scripts

It checks:

• File count and unpacked size budgets.
• Sensitive filenames, key material, debug logs, tests, and coverage output.
• README, license, declared bin targets, and main/module/types/exports entrypoints.
• Binary shebangs.
• High-confidence npm, GitHub, AWS, Google, Stripe, and private-key patterns.

Secret values are never included in output. Findings contain only the file path and detector name.

Publishing readiness

• Exact name@version collision on the npm registry.
• GitHub Actions publishing workflow presence.
• OIDC id-token: write permission.
• Long-lived registry-token references.
• Staged publishing and provenance metadata signals.

Local inspection cannot verify the trusted-publisher setting stored in npm. The report explicitly reminds maintainers to verify that setting instead of claiming it passed.

JSON contract

JSON output includes:

• schemaVersion
• tool, package, and target identity
• audit options
• readiness and severity counts
• dry-run tarball metadata
• ordered findings with stable IDs

New finding IDs may be added in minor versions. Existing fields will not be removed before 1.0.0.

CI example

name: package-preflight

on:
  pull_request:
  workflow_dispatch:

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npx --yes @nexkit/publish-doctor . --strict

Pin an exact Publish Doctor version in higher-assurance workflows.

Security model

Publish Doctor is a release preflight, not a malware detector, policy engine, or isolation boundary. Passing means its documented checks found no blocking issue; it does not prove that a package is safe.

• No lifecycle scripts are executed.
• No target files are modified.
• No telemetry or analytics.
• The only network request is the exact npm registry version lookup; --offline disables it.
• Symlinks are not followed during content scanning.
• Large and binary files are not content-scanned.

See SECURITY.md for reporting guidance.

Development

Node.js 22 or newer is required.

npm run verify

The verification suite covers clean and risky fixtures, secret redaction, registry outcomes, workflow checks, strict/offline/JSON behavior, read-only operation, tarball boundaries, and isolated installation.

Support development

If Publish Doctor saves you from a broken release, you can buy me a beer. The same link is exposed through standard npm funding metadata:

npm fund @nexkit/publish-doctor

License

MIT © Nathan Pixodeo