npm-git-install

Git ベースの Node パッケージのインストール

「どのインストールパケットを信頼すべきか、この依存関係にはどの配布方法が適しているか、次に何をすべきか」が主な質問である場合に、このスキルを使用します。

すべての構文バリエーションを並べたり、Git からの直接インストールを通常のインフラとして扱ったりすることが目的ではありません。 目的は次のとおりです。

1. すでに手元にあるパッケージ配布パケットを標準化する
2. 主な配布方法を1つ選ぶ
3. 耐久性、認証、ビルドへの影響を明確にする
4. 実際に使用しているパッケージマネージャーに合わせてコマンドを調整する
5. 一時的な Git ブリッジが恒久的なものになりかけたときに、明確な移行先を示す

見慣れない配布パケットを扱う前に、references/intake-packets-and-route-outs.md を読んでください。 Git、tarball、ワークスペース、先行公開のいずれかを決める際は、references/delivery-decision-matrix.md を読んでください。 パッケージマネージャー固有の注意事項については、references/package-manager-behavior.md を読んでください。 CI またはプライベート認証がすでにパケットに含まれている場合は、references/private-auth-and-ci.md を読んでください。

このスキルを使用する場合

• ユーザーが GitHub または別の Git ホストから Node パッケージをインストールしたい
• パッケージが未公開、フォーク、ブランチ固定、タグ固定、コミット固定、またはプライベートである
• パッケージがモノレポにあり、Git インストール、ワークスペースリンク、tarball、先行公開のどれが適切かユーザーが判断できていない
• ユーザーが git+ssh、git+https、github:owner/repo、tarball インストール、npm pack、または file: ／ワークスペースリンクについて質問している
• 共有依存関係が一時的な Git の近道として扱われ続けており、その近道を続けるべきか判断する必要がある

このスキルを使用しない場合

• 主な作業がローカルの Git ブランチ／履歴の問題の修正である → git-workflow を使用します
• 主な作業が管理者レベルでの GitHub リポジトリ、パッケージ、リリースの作成または運用である → github-repo-management を使用します
• 主な作業がパッケージ配布方法の選択ではなく、モノレポ／タスクランナーの自動化である → deployment-automation を使用します
• 主な作業が、より広範なランタイム、マシン、コンテナー、またはサービスのセットアップである → system-environment-setup を使用します
• ユーザーがすでに通常のレジストリ依存関係を使用しており、通常のバージョン更新だけが必要である

手順

ステップ 1：すでに手元にある配布パケットから始める

references/intake-packets-and-route-outs.md を使用します。

リクエストを次のいずれかのパケット形式に標準化します。

• temporary-bridge-packet — 作業をすぐに進めるための未公開修正、フォーク、PR ブランチ、または短期間のブリッジ
• shared-bridge-packet — チームメイトや CI もブリッジを必要としており、ブランチのずれやロックファイルの安定性が重要
• private-auth-packet — インストール経路がプライベートであり、実際のリスクがローカルと CI 間の認証情報の同等性にある
• artifact-fallback-packet — Git ソースからの直接インストールは脆弱すぎるが、完全なレジストリワークフローはまだ重すぎる
• workspace-inner-loop-packet — アプリとパッケージの両方をローカルまたはモノレポ内で同時に開発している
• durable-distribution-packet — 依存関係が一時的なブリッジではなくなっており、ブリッジのような扱いをやめるべき可能性が高い

最低限必要な情報を記録します。

Packet: shared-bridge-packet
Package manager: pnpm
Package state: unpublished fork fix
Audience: CI + teammates
Current ref: feature branch
Main risk: branch drift and auth parity

ルール：ユーザーがすでに持っているパケットから始めます。回答する前に、完璧なリリース管理テンプレートに沿うようユーザーに強制しないでください。

ステップ 2：主な配布方法を 1 つ選ぶ

主な方法を必ず 1 つ選んでください。

• direct-git-bridge — ローカルのみ、または Git を使った明らかに一時的なブリッジ
• sha-pinned-shared-bridge — 引き続き Git をブリッジとして使いますが、共有環境での再現性が重要
• private-git-auth-path — 短期的な解決策は引き続きプライベート Git で、認証の整合性が主な制約
• tarball-or-pack-artifact — Git のソースをそのままインストールする挙動に頼らず、依存関係をパッケージ化
• workspace-or-file-link — 共同開発をローカルまたはモノレポ内に維持
• publish-first-registry-path — 持続性のある配布チャネルへ移行

任意：フォールバック方法を 1 つ挙げてもかまいませんが、すべてのリクエストを 6 つの選択肢から選ぶ形式にしないでください。

ステップ 3：持続性を分類する

簡潔な持続性モデルを使用してください。

• Tier 0 — ローカルのみ
• Tier 1 — チーム／CI ブリッジ
• Tier 2 — 持続性のある共有パッケージ
• Tier 3 — 本番／リリースインフラストラクチャ

判断に影響する項目だけを記録してください。

• 誰が利用するか
• ref が変動するものか固定されているか
• ソースをそのままインストールする挙動を許容できるか
• ローカルと CI で認証方式がすでに共通しているか
• 依存関係が残り続ける場合の移行先

複数の Tier にまたがる場合は、最も高い Tier を前提に計画してください。

ステップ 4：選択肢の中から最も安全な方法を選ぶ

references/delivery-decision-matrix.md を使用してください。

デフォルトの優先順位：

1. publish-first-registry-path
2. workspace-or-file-link
3. sha-pinned-shared-bridge
4. tarball-or-pack-artifact
5. direct-git-bridge

ルール：

• 共有利用では、変動するブランチより SHA ピンを優先してください
• Git のビルド／prepare の挙動がリスクとなる場合は、アーティファクトまたは公開を優先してください
• 両方の側がローカルで同時に変更される場合は、workspace／fileを優先してください
• プライベート認証は制約として扱い、長期的にも Git が適切な配布チャネルである証拠とは見なさないでください

ステップ 5：使用中のパッケージマネージャーに合わせてコマンドを調整する

必要最小限の正しい構文だけを示してください。

一般的な形式：

• SHA ピン付きブリッジ：npm install github:owner/repo#<commit> / pnpm add github:owner/repo#<commit> / yarn add owner/repo#<commit> / bun add github:owner/repo#<commit>
• Git URL 形式：git+https://github.com/owner/repo.git#<commit> または git+ssh://[email protected]/owner/repo.git#<commit>
• Tarball：npm install https://.../package.tgz（または pnpm／Yarn／Bun の同等の形式）
• ローカルパス："dep": "file:../relative-path" または通常の workspace の手順

公開を優先するのが適切な場合は、一時的な Git 構文を並べる前に、移行計画を示してください。

ステップ 6：認証、ビルド、再現性を明確にする

すべての回答で、以下を扱ってください。

• 選択した ref／アーティファクト／公開バージョンの方針
• インストール時にソースをそのまま取得するか、およびライフサイクル／ビルドの挙動
• ローカルと CI の認証方式
• 決定的なインストールの見込み（npm ci、ロックファイルを固定する同等の方法、ピン留めした ref）
• 依存関係が一時的なものではなくなった場合の移行先

デフォルト：

• 変動するブランチは利便性のための近道であり、共有インフラストラクチャではありません
• プライベート Git の信頼性は、認証設定が最も不十分な環境に左右されます
• tarball は Git にまつわる予期せぬ問題を減らす代わりに、アーティファクトの管理責任が生じます
• パッケージが日常的に共有インフラストラクチャとして使われるようになったら、通常は公開を優先するのが誠実な答えです

ステップ 7：次の担当者へ速やかに引き継ぐ

このスキルが担うのはパッケージの配布方法の選択であり、その後のすべての作業ではありません。

一般的な引き継ぎ先：

• git-workflow — 基盤となるブランチ／履歴の状態を修正または整備
• github-repo-management — リポジトリ、パッケージ、リリース、パッケージホストの設定を管理
• deployment-automation — 選択したパッケージのフローに合わせて、再現可能なリポジトリスクリプトやモノレポの自動化を構成
• system-environment-setup — 依存関係の問題が主な障害ではなくなった後の、マシン／ランタイム／コンテナ／サービスのセットアップを担当

ユーザーが「このパッケージをどのように使うべきか」と尋ねた場合は、ここで対応してください。 「プラットフォームレベルでホスティングを管理する方法、または認証を修正する方法」を尋ねた場合は、適切な担当先へ引き継いでください。

ステップ 8：簡潔なインストール概要を作成する

次の項目を含む、オペレーター向けの簡潔な概要を返します。

• 手元にあるパケット
• 主なモード
• 耐久性ティア
• 推奨ステップを1～3件
• 必要なコマンドのみ
• 認証／ビルド／再現性に関する注意事項
• 終了戦略
• このスキルの範囲を超える作業の次の担当者

正直な答えが「公開するか、適切にパッケージ化してください」であれば、そのとおりに伝えます。

出力形式

必ず Git パッケージインストール概要、アーティファクト推奨概要、または 公開優先の引き継ぎ概要 を返します。

必須要件：

• すでに手元にあるパケットを特定する
• 主な配布モードを1つ選ぶ
• 耐久性を明示的に分類する
• 認証／ビルド／再現性への影響を明確にする
• 実際に使用されているパッケージマネージャーに合わせてコマンドを提示する
• 明確な終了戦略を示す
• パッケージのホスティング、リポジトリ管理、ワークフロー連携、または環境設定を適切な関連スキルに引き継ぐ

例

例 1：CI で未公開の修正を共有する

入力

npm アプリで GitHub リポジトリの未公開の修正が必要です。ブランチからインストールすべきでしょうか。それとも、CI でもっと安全な方法がありますか？

望ましい出力の方向性

• shared-bridge-packet
• sha-pinned-shared-bridge
• CI で共有する場合、変動するブランチの使用は避ける
• npm 専用のコマンドを1つ提示し、終了への道筋も示す

例 2：プライベートパッケージの認証トラブル

入力

パッケージはプライベートな GitHub リポジトリにあり、CI で pnpm install が失敗し続けています。どの方法を取るべきでしょうか？

望ましい出力の方向性

• private-auth-packet
• private-git-auth-path または publish-first-registry-path を選ぶ
• CI での認証情報の同等性を明確にし、コミット済みのシークレットを避ける

例 3：モノレポまたは長期的に共有するパッケージ

入力

パッケージはモノレポにあります。ローカルでは Yarn を使っていますが、チームの他のメンバーは通常のプロジェクトでそのパッケージを使うだけです。GitHub から直接インストールすべきでしょうか？

望ましい出力の方向性

• workspace-inner-loop-packet または durable-distribution-packet
• ローカルで共同開発する場合は workspace／file: を優先し、長期利用には公開を優先する
• 生の Git インストールを過大に推奨しない

ベストプラクティス

1. 好みの構文形式ではなく、すでに手元にある配布パケットから始めます。
2. Git の参照先は橋渡しの手段として扱い、既定のリリースチャネルにはしません。
3. Git 依存関係を共有する場合は、変動するブランチより SHA 固定を優先します。
4. ライフサイクル／ビルドの挙動を早い段階で明らかにします。生の Git インストールは、レジストリからのダウンロードではなく、ソースのパッケージ化として動作する場合があります。
5. ローカル利用、チーム／CI での利用、長期的な共有利用を明確に分けます。
6. プライベート認証の問題は、認証情報を際限なく継ぎ足すのではなく、配布経路を見直すサインとして扱います。
7. 依存関係が一時的なものではなくなったら、長期利用に適した終了経路を推奨します。
8. 入口となる説明文を大きく変更した場合は、簡潔な案内とディスカバリー向けの案内も更新します。

参考資料

• 受付パケットと引き継ぎ先
• 配布判断マトリックス
• パッケージマネージャーの挙動
• プライベート認証と CI に関する注意事項
• ../git-workflow/SKILL.md
• ../github-repo-management/SKILL.md
• ../deployment-automation/SKILL.md
• ../system-environment-setup/SKILL.md
• npm パッケージ仕様：https://docs.npmjs.com/cli/v11/using-npm/package-spec
• npm package.json の Git に関するドキュメント：https://docs.npmjs.com/cli/v11/configuring-npm/package-json
• npm pack：https://docs.npmjs.com/cli/v11/commands/npm-pack
• pnpm add：https://pnpm.io/cli/add
• pnpm workspaces：https://pnpm.io/workspaces
• Yarn Git プロトコル：https://yarnpkg.com/protocol/git
• Yarn workspaces：https://yarnpkg.com/features/workspaces
• Bun add：https://bun.sh/docs/pm/cli/add
• GitHub Packages：https://docs.github.com/en/packages/learn-github-packages/introduction-to-github-packages