Sandbox npm Install

このスキルを使う時

以下の場合にこのスキルを使用してください:

• 新しいサンドボックスセッションで npm パッケージを初めてインストールする必要がある
• package.json または package-lock.json が変更されて再インストールが必要
• SIGILL、SIGSEGV、mmap、unaligned sysNoHugePageOS などのエラーでネイティブバイナリがクラッシュしている
• node_modules ディレクトリが見つからないか破損している

前提条件

• virtiofs でマウントされたワークスペースを持つ Docker サンドボックス環境
• コンテナで利用可能な Node.js と npm
• ターゲットワークスペースの package.json ファイル

背景

Docker サンドボックスのワークスペースは通常 virtiofs (ホストと Linux VM 間のファイル同期) でマウントされています。ネイティブな Go および Rust バイナリ (esbuild、lightningcss、rollup など) は、aarch64 上の virtiofs から実行されると mmap アライメント障害でクラッシュします。解決策は、コンテナのローカル ext4 ファイルシステムにインストールしてワークスペースにシンボリックリンクさせることです。

ステップバイステップインストール

ワークスペースルートから付属のインストールスクリプトを実行します:

bash scripts/install.sh

一般的なオプション

オプション	説明
--workspace <path>	package.json を含むディレクトリのパス (省略時は自動検出)
--playwright	E2E テスト用に Playwright Chromium ブラウザもインストール

スクリプトの実行内容

1. package.json、package-lock.json、.npmrc (存在する場合) をローカル ext4 ディレクトリにコピーする
2. ローカルファイルシステム上で npm ci (またはロックファイルがない場合は npm install) を実行する
3. node_modules をワークスペースにシンボリックリンクさせる
4. 既知のネイティブバイナリ (esbuild、rollup、lightningcss、vite) が存在する場合は検証する
5. オプションで Playwright ブラウザとシステム依存関係をインストール (利用可能な場合は sudo を使用)

検証に失敗した場合は、スクリプトを再度実行してください — クラッシュは初期セットアップ中に散発的に発生する可能性があります。

インストール後の検証

スクリプトが完了したら、ツールチェーンが機能することを確認します。例えば:

npm test             # プロジェクトテストを実行
npm run build        # プロジェクトをビルド
npm run dev          # dev サーバーを起動

重要な注記

• ローカルインストールディレクトリ (例: /home/agent/project-deps) は コンテナローカル であり、ホストに同期されません
• node_modules シンボリックリンクはホスト上では壊れたリンクとして表示されます — node_modules は通常 gitignore されているため、これは無害です
• ホスト上で npm ci または npm install を実行すると、シンボリックリンクは自然に実ディレクトリに置き換わります
• package.json または package-lock.json の変更後は、インストールスクリプトを再度実行してください
• マウントされたワークスペースで直接 npm ci または npm install を実行しないでください — ネイティブバイナリがクラッシュします

トラブルシューティング

問題	解決策
dev サーバー実行時に SIGILL または SIGSEGV が発生	インストールスクリプトを再度実行; ワークスペース内で直接 npm install を実行していないことを確認
インストール後に node_modules が見つからない	シンボリックリンクが存在することを確認: ls -la node_modules
インストール中に権限エラー	ローカル deps ディレクトリが現在のユーザーで書き込み可能であることを確認
検証が散発的に失敗	スクリプトを再度実行してください — ネイティブバイナリのクラッシュは初回読み込み時に非決定的である可能性があります

Vite との互換性

プロジェクトで Vite を使用している場合、server.fs.allow でシンボリックリンクされたパスを許可する必要があります。シンボリックリンク対象の親ディレクトリ (例: /home/agent/project-deps/) を Vite 設定に追加して、Vite がシンボリックリンク経由でファイルを提供できるようにしてください。