run は何をしますか?
サイトは、実際に動いている姿を見るまでは完成したとは言えません。ソースコードは作者の意図を教えてくれますが、ブラウザはユーザーが実際に目にするものを教えてくれます。このスキルは、フォルダからレンダリングされたページへの最短経路です。
実行方法
node <skill folder>/scripts/serve.mjs <dir> [--port 4173] [--open] [--shot out.png] [--stop] [--detect]
--detectは検出結果を表示して何も起動しません。フォルダが不明な場合は最初にこれを行ってください。--portはそこから空きポートを探し始めます。これにより、2つのプロジェクトを同時に実行できます。--openはデフォルトのブラウザを開きます。--shot out.pngは Playwright を使ってページを幅1440、フルハイトでレンダリングします。--stopは.run/state.jsonからプロセスツリーを強制終了します。
プロジェクトの隣に .run/state.json (pid, port, url, command) と .run/server.log が書き込まれます。この2つのファイルが、起動と停止の間のすべての引き継ぎ情報となります。
検出するもの
| 検出対象 | 実行内容 |
|---|---|
dev, start, serve, preview のいずれかを含む package.json | 空きポートで npm run <該当スクリプト> を実行し、PORT を設定 |
ルートの index.html | そのフォルダで python -m http.server を実行 |
public/index.html, dist/index.html, build/index.html | ビルド出力をルートとした静的サーバーを実行 |
| 設定ファイルのみでスクリプトがない | 報告して停止:プロジェクトは独自のコマンドが必要 |
go.mod, Cargo.toml, pubspec.yaml | 報告して停止:プロジェクト独自の実行コマンドを使用 |
フレームワーク固有の情報、ポートのデフォルト値、知っておくべき障害モードについては、references/stacks.md を参照してください。
結果の解釈
このスクリプトは、以下の3点を証明するだけです。プロセスが起動したこと、ポートが応答したこと、ページがレンダリングされたこと。これではわからないことは次の通りです。
- レイアウトが375、768、1440の各幅で適切かどうか(これには
sitecraft/scripts/verify.mjsを使用) - コンソールがクリーンかどうか(ここではキャプチャされません。
verify.mjsがキャプチャします) - スクリーンショットを撮ったページがユーザーの意図したページかどうか(URL を、あなたがリクエストしたルートと照合してください)
したがって、ループは次のようになります。serve.mjs --shot を実行し、自分の目で画像を確認し、修正し、再度スクリーンショットを撮る。1回のパスでスクリーンショットは3回までとします。それを超えた場合、問題はCSSではなく計画にあります。
ルール
- サーバーを稼働させたままにしないでください。 チェックが終わったら停止するか、まだ起動中でありそのポート番号を明確に伝えてください。ユーザーのマシンに放置された開発サーバーは、ユーザーが後片付けをしなければならない問題です。
- 止められないものは起動しないでください。 プロジェクトに Docker、データベース、有料のAPIキーが必要な場合は、何かを起動する前にその旨を伝えてください。
- 実際のURLを報告してください。 「アプリ」ではなく
localhost:4173と報告します。ポート4173が使用中で番号が変わった場合は、新しいポート番号を伝えてください。 - 推測する前にログを読んでください。 起動失敗のほとんどは、依存関係の欠落、環境変数の欠落、ポートの既存バインドが原因です。
.run/server.logに答えがあり、実際のエラーを引用することが理論よりも効果的です。 - 断りなしにインストールしないでください。
node_modulesがない場合、npm installは通常正しい対応ですが、それはプロジェクトに変更を加えることでもあります。実行した場合はその旨を伝え、インストールが大規模な場合は一度確認を取ってください。 - フレームワークより静的を優先。 ビルド出力が存在し最新の場合、
dist/を配信する方が開発サーバーよりも高速で信頼性が高くなります。
起動しない場合
.run/server.logを読み、最初の実際のエラーを引用してください(最後の行ではありません)。- 依存関係の欠落:プロジェクトで
npm installを実行してから再試行してください。 - 環境変数の欠落:
.env.exampleを探し、必要なものを特定し、値が秘密で欠落している場合は停止してください。 - ポートが既にバインドされている:スクリプトは次の空きポートに自動的に移動します。それでも失敗する場合、フレームワーク設定でポートがハードコードされているのが通常の原因です。
- ビルドステップが必要:最初に
npm run buildを実行し、その後dist/を配信してください。 - ネイティブまたはコンテナ化:プロジェクトがドキュメント化しているコマンドをユーザーに返してください。すべてのスタックがスクリプトで処理できるわけではありません。
チェックリスト
- スタックを推測ではなく検出した
- 起動し、実際のHTTP応答を確認した(単にプロセスを起動しただけではない)
- 正確なURLとポートを報告した
- ログだけでなくスクリーンショットも確認した
- ルートが意図したページと一致していることを確認した
- 停止した、またはまだ実行中でその場所を伝えた
- 失敗した場合は実際のエラーを引用した