npmpreflight

npmpreflight

悪い公開もまだ簡単に取り消せるうちに、npm publish の前にパッケージディレクトリを監査します。

npmpreflight は、実際にパッケージに含まれるファイル一式を解決し、同梱ファイル内のシークレットパターンをスキャンし、サイズを合計して、公開に必要なフィールドとエントリーポイントが package.json にあるかを確認します。リリース後に判明すると気まずい問題、たとえば、公開ファイルに認証情報が含まれていないか、bin のターゲットが tarball に存在するか、ライセンスフィールドが設定されているか、スコープ付きパッケージを制限付きで公開しようとしていないか、といった疑問に答えます。

インストール

インストールせずに実行します。

npx @reneturcios/npmpreflight check .

または、グローバルにインストールします。

npm install -g @reneturcios/npmpreflight
npmpreflight check .

Node 20 以降が必要です。

CLI の使い方

npmpreflight check [path] [--json]
npmpreflight mcp
npmpreflight --version

• check [path] は、path のパッケージディレクトリ（デフォルト：カレントディレクトリ）を監査し、人が読みやすいレポートを出力します。機械可読なレポートを出力するには、--json を追加します。
• mcp は、stdio 経由で MCP サーバーを起動します（下記を参照）。
• --version はバージョンを出力します。

終了コード：判定が READY の場合は 0、それ以外の判定では 1、使い方に誤りがある場合や package.json が読み取れない、または無効な場合は 2、出力パイプが早期に閉じられた場合は 141 です。

出力例：

npmpreflight check .: FIX-FIRST
  files: 4, bytes: 603, findings: 2 (high: 2, medium: 0, low: 0, info: 0)
  summary: 4 shipped file(s), 603 byte(s), 2 finding(s) (2 high, 0 medium, 0 low, 0 info). High-severity findings must be fixed before publishing.
  [HIGH] SECRET-LEAK src/index.js:2 Shipped file matches the secret pattern private-key-block. Remove the credential from the package and rotate it if it was ever real. (evidence: private-key-block)
  [HIGH] SECRET-LEAK src/index.js:3 Shipped file matches the secret pattern github-pat-classic. Remove the credential from the package and rotate it if it was ever real. (evidence: github-pat-classic)
FIX-FIRST: resolve the high-severity findings before publishing.

検出結果には、一致したシークレットのテキストは含まれません。シークレット検出結果の証拠として示されるのはパターン ID のみで、ファイルと行番号も記載されるため、レポートを安心してイシューや CI ログに貼り付けられます。

MCP

同じ監査を、stdio 経由の MCP ツールとして利用できます。

• ツール：preflight_package
• 入力：確認するパッケージディレクトリを指定する path
• 出力：check --json と同一の JSON レポート

npmpreflight mcp で起動するか、MCP クライアントで npx @reneturcios/npmpreflight mcp を実行するよう設定します。このサーバーは OCI イメージとしても公開されており、server.json に io.github.CloudCorpRecords/npmpreflight という名前で登録されています。

チェック項目

ルール	重大度	検出内容
MISSING-FIELD	高	package.json に name、version、license、description のいずれかがありません（フィールドごとに 1 件検出）。
BIN-MISSING	高	package.json の bin パスが、同梱ファイル一式に含まれていません。
MAIN-MISSING	高	main エントリーポイントが、同梱ファイル一式に含まれていません。
SECRET-LEAK	高	同梱されたテキストファイルがシークレットパターンに一致します。対象は、秘密鍵ブロックのヘッダー、AWS アクセスキー ID の形式（AKIA に続く 16 文字）、従来形式の GitHub トークンの形式（ghp_ に続く 36 文字以上）、きめ細かいアクセス許可の GitHub トークン形式（github_pat_ プレフィックス）、sk- API キー形式、または長い引用符付きの値を含む汎用的な api_key 形式の代入です。証拠として示されるのはパターン ID のみです。
OVERSIZE	中	同梱ファイルの合計サイズが 10 MiB を超える場合、または同梱ファイルのいずれか 1 つが 1 MiB を超える場合（サイズ超過のファイルごとに 1 件検出）。
SCOPED-NO-PUBLISHCONFIG	中	パッケージ名がスコープ付き（@ で始まる）で、publishConfig.access が public ではありません。
NO-README	低	同梱ファイル一式に README ファイルがありません。
NO-ENGINES	情報	package.json に engines の範囲が宣言されていません。

各レポートには、同梱ファイル数と合計バイト数、および重大度ごとの検出件数が記載されます。

判定

• 重大度が高い検出結果がない場合は READY です。重大度が中、低、情報の検出結果は報告されますが、判定を妨げません。
• 重大度が高い検出結果が 1 件以上ある場合は FIX-FIRST です。

出荷されるファイルセットの解決方法

• package.json に files 配列がある場合、その配列に記載されたパスが含まれます。 ファイルは直接追加され、ディレクトリは再帰的に走査されます。 package.json、README、LICENSE は、記載されているかどうかにかかわらず、 存在する場合は常に含まれます。これは npm の動作に準拠しています。
• files 配列がない場合、ディレクトリ内のすべてが含まれます。 ただし、node_modules、.git、および .npmignore がある場合はそれに一致するパスを除きます。 上記の常に含まれるファイルは、無視ルールに一致しても含まれます。
• 走査対象は出荷ファイル 5000 件までです。上限に達すると、 レポートの件数にそのことが記録され（truncated: 1 と、 filesSeen および maxFiles）、レンダリング結果には残りの ファイルが走査されなかったことが記載されます。

制限事項

クリーンという判定を信頼する前に、以下をお読みください。

• ファイルセットは静的に解決されるものであり、バイト単位で正確な npm pack の結果ではありません。 npm では、静的な処理では再現されない追加のルール（独自の常時除外ファイル、ライフサイクルで生成されるファイル、公開時の動作）が適用されます。 npmpreflight は事前チェックとして扱い、リリース前に npm pack --dry-run で確認してください。
• .npmignore のサポートは単純なサブセットです。空行、# コメント、 通常の行（任意の階層にあるファイル名、または相対パスとの完全一致）、 / で終わるディレクトリパターンに対応しています。.npmignore のグロブ、否定、 文字クラスはサポートされていないため、そのような行は npm と同じ方法では一致しません。
• files の項目は、リテラルのファイル、リテラルのディレクトリ、単純な * および ** のグロブ、 ならびにそれらに対する ! による否定に対応しています。それ以上に複雑な指定は リテラルとして解決されるため、npm の動作と異なる場合があります。
• シークレットスキャンではテキストファイルのみを読み取ります。スキャン対象の先頭部分に NUL バイトを含むファイルはバイナリとして扱われ、スキップされます。各ファイルの先頭 512 KiB のみをスキャンするため、 大きなファイルでその位置より後にあるシークレットは検出されません。パターンは形式を示すものであり、証明ではありません。 一致したものがテスト用フィクスチャや例である場合もあれば、認識されない形式の実際の認証情報は一致しない場合もあります。
• シンボリックリンクは追跡されず、出荷されません。
• 出力は決定論的です。検出結果は並べ替えられ、件数は安定しており、 タイムスタンプは出力されません。

開発

npm install
npm run build
npm test

ライセンス

MIT