npm パッケージリリース強化は何をしますか？

目標

npm パッケージを「ローカルで動作する」状態から「正直で、検査可能で、安全に公開できる」状態に仕上げます。雰囲気ではなく実際の検証を優先します。パッケージの tarball 内容、ランタイムコントラクト、CI、GitHub 設定、依存関係更新の衛生状態を検証します。

開始方法

正確なリポジトリを確認:

pwd
git status --short --branch
git remote -v

パッケージの表面を調査:

cat package.json
ls -la
find .github -maxdepth 3 -type f -print 2>/dev/null

ロックファイルからパッケージマネージャーを検出:

package-lock.json -> npm
pnpm-lock.yaml -> pnpm
yarn.lock -> yarn

デフォルトでは npm コマンドを使用しますが、検出されたパッケージマネージャーに合わせてコマンドを変換します。

パッケージコントラクト

package.json が真実を伝えるようにします:

name: 公開対象が意図的で利用可能であること
version: 現在の意図された公開バージョン
description、keywords: レジストリ検索に十分な有用性があること
license: 存在し、LICENSE と一致すること
repository、homepage、bugs: 公開リポジトリを指していること。公開リポジトリの URL がまだ確定していない場合は、黙って省略するのではなく、公開前の TODO として明示的にフラグを立てること
type、exports、main、bin: ユーザーがインポートまたは実行するものと一致すること
files: tarball を公開可能なアーティファクトに限定すること
engines.node: パッケージが実際にサポートする最小ランタイム
prepublishOnly または同等のスクリプト: 古いビルド出力の公開を防ぐこと

CLI パッケージの場合、bin ターゲットがビルド済みで、必要に応じて実行可能であり、ユーザーが実行するコマンドを通じてスモークテストされていることを確認します。

ランタイムフロアルール

Node エンジンは約束であり、飾りではありません。

engines.node が >=20 の場合、CI は Node 20 でテストする必要があります。
@types/node はサポートする最小ランタイムと同じメジャーラインに保ちます。
@types/node はそのランタイムラインの最新パッチに正確に固定することを推奨します。
ランタイムフロアを超える @types/node のメジャーバンプは、engines.node も引き上げない限りマージしないでください。
engines.node は参考情報です。npm は警告を表示するだけで、ユーザーが engine-strict を設定しない限りインストールをハードブロックしません。したがって、フロアバージョンでの CI が実際に約束を強制します。

理由: Node の型は開発時のみですが、TypeScript が許可するコードを変更します。@types/node@26 を使用すると、Node 20 のユーザーには失敗する API を使用したコードがコンパイルできてしまう可能性があります。

検証コマンド

npm プロジェクトの場合:

npm ci
npm run build --if-present
npm test --if-present
npm audit --omit=dev
npm pack --dry-run

pnpm/yarn の場合は、同等の install/build/test/audit/pack コマンドを使用します。audit のサポートが異なる場合は、そのように明示します。

CLI の場合は、少なくとも1つの外部からのスモークテストも実行します:

node dist/path/to/cli.js --help
npm pack --dry-run

可能であれば、パックされた .tgz を一時ディレクトリにインストールし、ユーザーが実行するのとまったく同じようにバイナリを実行します。

Tarball レビュー

npm pack --dry-run がレジストリの真実の表面です。以下を確認します:

ビルド出力が含まれていること
README.md と LICENSE が含まれていること
ソースのみのゴミ、テンポラリファイル、テスト、プライベートドキュメント、フィクスチャ、ローカルデータベース、シークレットが除外されていること
パッケージサイズが妥当であること
CLI の bin パスが tarball に含まれていること

files フィールドがない場合は追加します。公開ポリシーとして .gitignore に依存しないでください。

GitHub ベースライン

以下を追加または確認:

.github/workflows/ci.yml
.github/dependabot.yml
.github/CODEOWNERS
.github/pull_request_template.md
SECURITY.md

GitHub 所有のアクションには現在サポートされているメジャーバージョンを使用します。Actions がアクションランタイムの非推奨を警告した場合は、CI が成功した後にアクションのメジャーを更新します。

CI には通常以下を含めます:

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@CURRENT_MAJOR
      - uses: actions/setup-node@CURRENT_MAJOR
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test --if-present

node-version をパッケージの最小サポートランタイムに調整し、各 @CURRENT_MAJOR をアクションの現在のメジャータグ（例: actions/checkout@v4）に置き換えます。実際のメジャーに固定し、プレースホルダーをコミットしないでください。

Dependabot ベースライン

パッケージと GitHub Actions の両方の更新を設定:

version: 2
updates:
  - package-ecosystem: npm
    directory: /
    schedule:
      interval: weekly
    open-pull-requests-limit: 5
    commit-message:
      prefix: deps
      include: scope

  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly
    open-pull-requests-limit: 5
    commit-message:
      prefix: deps
      include: scope

Dependabot が設定直後に PR を開いた場合、それは設定が有効である証拠として扱います。PR をトリアージします。すべてのグリーンチェックを盲目的にマージしないでください。

Dependabot トリアージ

以下の経験則を使用します:

ランタイム依存関係のパッチ/マイナー: チェックが成功し、リリースノートが問題なければマージ。
ランタイム依存関係のメジャー: リリースノートを調査し、実際のパッケージ動作をスモークテスト。
開発ツールのメジャー: build/test/pack が成功し、ランタイムコントラクトを変更しなければマージ。
ランタイムフロアを超える @types/node: クローズするか、ランタイムフロアへの固定に置き換え。
GitHub Actions のメジャー: CI が成功し、非推奨警告が削除されればマージ。

2つの PR が小さな設定ファイルで競合する場合は、1つをマージしてからもう1つを更新するか、2つ目を直接適用し、それが置き換えられたことを明確にコメントします。

GitHub リモート強化

リポジトリ/アカウントがサポートするものを適用し、gh または API 読み取りで実際の設定を確認します。

有用な設定:

gh repo edit OWNER/REPO \
  --delete-branch-on-merge \
  --enable-squash-merge \
  --enable-merge-commit=false \
  --enable-rebase-merge=false \
  --allow-update-branch

gh api --method PUT repos/OWNER/REPO/vulnerability-alerts --silent
gh api --method PUT repos/OWNER/REPO/automated-security-fixes --silent
gh api --method PUT repos/OWNER/REPO/actions/permissions/workflow \
  -f default_workflow_permissions=read \
  -F can_approve_pull_request_reviews=false --silent

Actions の許可リストについては、ワークフローが GitHub 所有のアクションのみを使用する場合は、GitHub 所有のアクションのみを推奨します。サードパーティのアクションが必要な場合は、最小限のセットを明示的に許可します。

公開リポジトリは通常、より多くのセキュリティコントロールを利用できます。無料プランのプライベートリポジトリでは以下がブロックされる場合があります:

ブランチ保護またはルールセット
コードスキャン
シークレットスキャン
プッシュ保護

ブロッカーを明確に報告します。利用できないコントロールを有効として報告しないでください。

ブランチ保護

利用可能な場合、デフォルトブランチを以下で保護:

マージ前にプルリクエストを必須にする
CI ステータスチェックを必須にする
プロジェクトに合う場合はブランチが最新であることを必須にする
会話の解決を必須にする
フォースプッシュをブロック
削除をブロック
スカッシュマージのみを使用する場合は線形履歴を必須にする

保護を有効にした後は、ユーザーが明示的に依頼し、バイパスを理解しない限り、main への直接プッシュを停止します。

ゲート付き PR ツール

自動レビュー/ゲートツールを使用する場合、ゲートに PR の作成を依頼する前に、リモートにデフォルト/ベースブランチがあることを確認します。空の新しいリモートは、多くの場合、最初に main をプッシュする必要があります。そうしないと、ゲートがフィーチャーブランチを検証してプッシュできても、ベースブランチがないため PR 作成に失敗します。

公開チェックリスト

npm publish の前に:

npm whoami が意図したアカウントを表示すること
npm view PACKAGE_NAME name version で名前の状態を確認
公開するコミットの CI がグリーンであること
npm pack --dry-run がレビュー済みであること
README のインストール/使用例が実際の動作と一致すること
repository、homepage、bugs が実際の公開リポジトリを解決すること（URL が未確定の場合は TODO として明示的にフラグが立てられていること）
リリースをブロックする Dependabot/セキュリティアラートが残っていないこと
バージョンバンプが意図的であり、git でタグ付けされ（git tag vX.Y.Z && git push --tags）、CHANGELOG または GitHub リリースに反映されていること
スコープ付きパッケージ（@scope/name）は --access public で公開すること（スコープ付きパッケージはデフォルトで制限/プライベート）

Web/パスキー/2FA 認証を使用するアカウントの場合:

npm publish --auth-type=web

検証可能なサプライチェーンリンクのために、provenance（出所証明）付きで CI から公開することを推奨します。Provenance には、公開パッケージ、GitHub Actions などのサポートされている CI、およびジョブの id-token: write 権限が必要です:

npm publish --provenance --access public

公開後:

npm view PACKAGE_NAME version
npm view PACKAGE_NAME bin files engines repository --json
npx -y PACKAGE_NAME --help

provenance 付きで公開した場合、レジストリのパッケージページに provenance /「Built and signed」証明書が表示されることを確認します。

最終応答

実際に確認された内容のみを報告:

実行したパッケージチェック
tarball の結果
依存関係の PR 決定
作成またはマージされたコミット/PR
確認された GitHub 設定
プラン/可視性によってブロックされたコントロール
公開された場合のリリースタグと provenance ステータス
ユーザー所有の場合の公開コマンドまたは公開後の検証

npm パッケージリリース強化