utels-project-bootstrap

utels プロジェクトの初期設定

production/staging の utels.dev プロジェクトを登録し、それぞれ返された取り込みトークンを pnpm exec cf workers secrets update UTELS_INGEST_TOKEN --worker <name> --body @/dev/stdin に渡します。JSON 本文は macOS/Linux では標準入力を介して送信されます。トークンは引数、一時ファイル、コマンドログのいずれにも含まれません。

ヘルパー

setup-utels.ts を Worker の scripts/ ディレクトリにコピーしてください。Node.js 24 以降と、プロジェクトローカルの cf 依存関係を使用します。動作確認済みの実装は cf beta.5 を対象としています。アップグレード時は cf schema workers secrets update とインストール済みの実装を確認してください。

入力：

入力	用途
UTELS_BOOTSTRAP_TOKEN	必須の登録用認証情報。通常は dotenvx で復号します
APP_WORKER_PROD / APP_WORKER_STAGING	選択した各ターゲットに必要な Worker 名。cf のリソースコマンドでは従来の --env による選択は使用しません
APP_SERVER_DIR	Worker プロジェクトのディレクトリ。デフォルトでは、コピーしたスクリプトディレクトリの親です
APP_UTELS_PROJECT_PROD / APP_UTELS_PROJECT_STAGING	プロジェクトのスラッグ。サンプルのデフォルト値を置き換えてください
UTELS_ENDPOINT / --endpoint=<url>	登録先ホスト。デフォルトは https://utels.dev です
--only=production / --only=staging	部分的に失敗した後の再試行を含め、1 つの環境のみを登録します
DRY_RUN=1	登録とシークレットへの書き込みをスキップします

使用前に targets の表示名とオリジン URL をカスタマイズしてください。utels はサーバーサイドプロジェクトでもオリジンを検証します。明示的に選択した dotenvx ファイルを通じて設定する場合も含め、CLOUDFLARE_API_TOKEN と CLOUDFLARE_ACCOUNT_ID で cf の認証情報を指定してください。

ヘルパーでは --text "$TOKEN" や @- ではなく、--body @/dev/stdin を使用します。API エラーにリクエスト本文が含まれる可能性があるため、子プロセスの出力は無視し、失敗時には cf の終了ステータスを報告します。認証は cf auth whoami で個別に確認してください。シークレットへの書き込みに失敗した場合、登録済みのスラッグが残ることがあります。登録はべき等性が保証されておらず、ヘルパーがプロジェクトを自動削除することもありません。

登録の衝突

以前に登録したスラッグを使うと、D1 の一意制約エラーが発生し、HTTP 500 / Worker 1101 として表面化することがあります。再試行する前に、utels データベースを ID でクエリしてください：

pnpm exec cf d1 query DATABASE_ID --sql "SELECT project_id FROM project WHERE project_id LIKE '<your-slug>%';"

別のスラッグを選ぶか、運用担当者がサポートする手順で既存のトークンを復旧してください。破壊的な削除は初期設定の対象外です。

検証と関連ガイダンス

統合テストでは、utels の登録と pnpm の子プロセスをモックし、リモート環境に変更を加えることなく、Worker の選択、標準入力の JSON、書き込みの失敗、トークンを含まない出力を検証します。

• Cloudflare テレメトリー：返された取り込みトークンを Worker バインディングとして設定します。
• cf API ガイド：シークレットとコマンドの検索方法について説明します。
• 元のヘルパー：登録プロトコルの参照元。このバージョンでは、シークレットの受け渡し方法を cf 向けに調整しています。