node-packaging

node-packaging

サポートすると明言したすべての利用者に対して、正しくインストールされ、解決されるパッケージを作成します。対象には、モジュール形式、exports マップ、型、tarball の内容が含まれます。このスキルが解決する問題：利用者が使う Node のバージョン範囲を確認せずに「今は ESM のみで問題ない」と宣言する、型が解決されない exports マップを書く、ソースや CI の不要なファイルだらけの tarball を公開するといった問題です。

使用しない場合

• バージョン更新、変更履歴、公開、OIDC → node-release。
• 宣言ファイルの出力／tsconfig → node-typescript（このスキルが扱うのは、出力済みの宣言を利用者が解決する方法です）。
• 依存関係の衛生管理 → node-supply-chain。

ワークフロー

1. 流行ではなく根拠に基づいて形式を決定します — ESM 優先であり、常に ESM ではありません： package.json#engines と、実際の利用者の状況を確認します。require(esm) が使えるのは特定の Node のバージョン系列に限られ、実際の制約もあります（読み込む依存グラフにトップレベル await がないこと）。サポートマトリクスと判断フレームワークは references/packaging-playbook.md にあります。古いエンジン、ツール、または明示された利用者の要件がある場合は、プレイブックにあるデュアルパッケージの問題への対策と併せて ESM+CJS の両方を提供します。
2. exports マップを明示的に記述します（プレイブックに ESM のみの場合とデュアル形式の場合の例があります）：types 条件を正しい位置に置き、サポート対象の API に限ってサブパスをエクスポートし、該当する場合は sideEffects を設定します。
3. ビルド：現在のデフォルトは tsdown です（理由があれば tsup も可）。宣言ファイルの出力を有効にし、engines に合ったターゲットを指定します。
4. tarball の衛生管理：files の許可リストを使用します（.npmignore の履歴を掘り返す方法は使いません）。engines を設定し、リポジトリで固定している場合は packageManager も設定します。
5. ゲート — 決して省略しないでください：

   bash "${CLAUDE_SKILL_DIR}/scripts/check_package.sh"
   

   （npm pack のドライランによる検査 + publint + arethetypeswrong。正確なコマンドはスクリプトに記載されています。問題が見つかると終了コードが 0 以外になります。）
6. 利用者側のエラー診断（ERR_REQUIRE_ESM、「types not found」）：プレイブックに判断ツリーがあります。まず利用者の Node／モジュールのコンテキストを特定します。選択肢は、サポート範囲を文書化する、真のデュアルビルドを行う、または exports を修正することです。根拠なく CJS を追加してはいけません。

出力仕様

明示的な exports マップ、engines の根拠を記した形式の決定、exports の宣言どおりの成果物を出力するビルド、files の許可リスト、両方のゲート（publint、attw）の合格、npm pack --dry-run で生成した tarball の確認が必要です。公開済みパッケージの形式や exports を変更すると semver のメジャー変更になります。その旨を明記してください。

注意点

• デュアルパッケージの問題（モジュールのインスタンスが二重になること）は実際に起こります。シングルトン／状態を持つパッケージには、プレイブックに記載された対策を適用するか、範囲を文書化したうえで ESM のみを使用してください。
• attw のエラーは分かりにくいことがあります。プレイブックでは、エラーコードと具体的な exports マップの修正方法を対応づけています。
• engines は後続のすべてに影響します（node-ci の CI マトリクス、このスキルでの形式選択）。慎重に設定し、暗黙に引き継がないでください。
• require(esm) のサポートマトリクスは Node のバージョンに応じて確認してください。使用時に nodejs.org のドキュメントで Node のバージョン範囲を再検証してください。

ファイル

• references/packaging-playbook.md — require(esm) のマトリクス、形式決定のフレームワーク、exports の例、バンドラーの状況、問題への対策、エラーの判断ツリー。
• scripts/check_package.sh — pack のドライラン + publint + attw のゲート。問題が見つかると終了コードが 0 以外になります。Node／npx が利用できない場合は、明確なメッセージを表示して処理を続行できるようにします。