cloudflare-workers-publish

Cloudflare Workers の公開

1Password で認証情報を管理しながら、Static Assets を使用して静的 HTML ファイル（Bokeh のチャート、ダッシュボード、レポート）を Cloudflare Workers にデプロイします。

対象範囲：workers.dev での静的ファイルのみのデプロイ。動的な Workers や R2 オブジェクトストレージは対象外です。

前提条件：1Password CLI（brew install 1password-cli）＋ Node.js（npx wrangler）

---

自己進化型スキル：このスキルは使用を通じて改善されます。手順が間違っていた場合、パラメーターに変更があった場合、または回避策が必要だった場合は、先送りせずにこのファイルをすぐに修正してください。実際に再現可能な問題がある場合のみ更新してください。

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

• HTML ファイルを公開 URL で公開する場合（GitHub には大きすぎる場合）
• 新しい Cloudflare Workers 静的サイトを設定する場合
• Cloudflare のデプロイ失敗をトラブルシューティングする場合
• 1Password 内の Cloudflare API トークンをローテーションする場合

次の用途には使用しないでください：動的な Workers（JavaScript／TypeScript のロジック）、Cloudflare Pages（2025 年 4 月に非推奨化 - CFW-01）、R2 オブジェクトストレージ、またはカスタムドメイン（高度な設定のため対象外）。

---

アーキテクチャ

Local project/
├── results/published/              # Deploy root (contains wrangler.toml)
│   ├── wrangler.toml               # Workers config (name + assets)
│   ├── index.html                  # Auto-generated directory listing
│   └── gen800/                     # Subdirectories with HTML files
│       └── XRPUSDT_750/
│           └── equity_plot.html    # 13MB Bokeh chart
└── scripts/
    └── publish_findings.sh         # Deploy script (3 phases)

Credential flow:

1Password (Claude Automation vault)
   ├── account_id (TEXT)      →  CLOUDFLARE_ACCOUNT_ID env var
   └── credential (CONCEALED) →  CLOUDFLARE_API_TOKEN env var
                                       ↓
                                 npx wrangler deploy
                                       ↓
                                 https://{name}.{slug}.workers.dev/

---

TodoWrite タスクテンプレート

テンプレート A - 新しい静的サイト（初回セットアップ）

1. [Preflight] Verify Node.js and 1Password CLI installed
2. [Preflight] Create Cloudflare API token (Workers Scripts Edit permission)
3. [Execute] Pre-provision 1Password item in Claude Automation vault (biometric)
4. [Execute] Store token + account ID in 1Password item fields
5. [Execute] Create publish directory with wrangler.toml (3 fields only)
6. [Execute] Create deploy script from skill template (parameterize 4 vars)
7. [Execute] Add a moon task wrapper (publish-site) to moon.yml
8. [Execute] Add .wrangler/ to .gitignore
9. [Execute] Add LFS tracking for large HTML files in .gitattributes
10. [Verify] Enable workers.dev subdomain in Cloudflare dashboard
11. [Verify] Run first deploy and verify URL in browser (NOT curl)
12. [Verify] Document the workers.dev URL in project docs

テンプレート B - 公開済みサイトにファイルを追加

1. [Preflight] Verify files are real content, not LFS pointers (head -1)
2. [Execute] Copy HTML files to published/{generation}/{symbol_threshold}/
3. [Execute] Run deploy script (index.html auto-regenerates)
4. [Verify] Verify new files appear at workers.dev URL in browser

テンプレート C - 新しい Worker（新しいサブドメイン／プロジェクト）

1. [Preflight] Choose worker name ({name}.{slug}.workers.dev)
2. [Execute] Create 1Password item OR reuse existing Cloudflare credentials
3. [Execute] Create wrangler.toml with chosen name and today's date
4. [Execute] Create parameterized deploy script from skill template
5. [Execute] Add a moon task wrapper to moon.yml
6. [Verify] Deploy and discover actual workers.dev URL via wrangler output

テンプレート D - Cloudflare API トークンのローテーション

1. [Execute] Create new API token in Cloudflare dashboard (Workers Scripts Edit)
2. [Execute] Update 1Password item credential field (biometric required)
3. [Verify] Run deploy script to verify new token works
4. [Execute] Revoke old token in Cloudflare dashboard

テンプレート E - デプロイ失敗のトラブルシューティング

1. Is wrangler.toml in current directory? (CFW-10)
2. Are credentials populated? Print first 8 chars of account ID
3. Is --reveal present for CONCEALED fields? (CFW-03)
4. Is workers.dev subdomain registered in CF dashboard? (CFW-07)
5. Does token have Workers Scripts Edit permission? (CFW-11)
6. Are HTML files real content or LFS pointers? head -1 file (CFW-12)
7. SSL handshake error? Verify in browser, not curl (CFW-08)
8. Is npx wrangler installed? npx wrangler --version

---

ワークフロー：初回セットアップ

フェーズ 1：Cloudflare API トークンの作成

1. https://dash.cloudflare.com/profile/api-tokens にアクセスします
2. Create Token > Custom token をクリックします
3. 権限を設定します：Account > Workers Scripts > Edit（CFW-11）
4. アカウントリソース：Include > 使用するアカウント
5. トークンをコピーします（表示されるのは一度だけです）

フェーズ 2：1Password 認証情報のプロビジョニング

重要（CFW-02）：1Password サービスアカウントはアイテムの読み取りのみ可能です。新しいアイテムを作成することはできません。事前にアイテムを手動で作成してください。

手順については、1Password セットアップガイドを参照してください。

プロビジョニング後、アイテムには次の内容が含まれている必要があります。

フィールド	タイプ	--reveal	内容
account_id	TEXT	いいえ	Cloudflare アカウント ID
credential	CONCEALED	はい	API トークン

フェーズ 3：wrangler.toml の作成

wrangler セットアップガイドを参照してください。

# Minimal Workers Static Assets config (CFW-09)
name = "my-project-name"
compatibility_date = "2026-02-18"

[assets]
directory = "."

フェーズ 4：デプロイスクリプトの作成

同梱のテンプレートをコピーし、4 つの設定変数を編集します。

cp "$(skill-path)/scripts/publish_static.sh" scripts/publish_myproject.sh
# Edit: PUBLISH_DIR, OP_ITEM_ID, SITE_TITLE, PROJECT_URL

または、動作する実装例として rangebar-patterns/scripts/publish_findings.sh を参照してください。

フェーズ 5：moon タスクの作成

# moon.yml (CFW-13: bash in a .sh file, not inline in the task command)
tasks:
  publish-site:
    command: 'bash scripts/publish_myproject.sh'
    options:
      cache: false

リポジトリに moon ワークスペースがまだない場合は、Skill(itp:bootstrap-monorepo) で初期設定するか、bash scripts/publish_myproject.sh でスクリプトを直接実行してください。

フェーズ 6：Git の管理

.gitignore：

# Wrangler temp files (Cloudflare Workers deploy)
.wrangler/
results/published/.wrangler/

.gitattributes（大きな HTML ファイル用）：

results/published/**/*.html filter=lfs diff=lfs merge=lfs -text

フェーズ 7：workers.dev サブドメインの有効化（CFW-07）

初めて Cloudflare を使うアカウントでは、workers.dev ルートを有効にする必要があります。

1. https://dash.cloudflare.com > Workers & Pages にアクセスします
2. workers.dev サブドメインを有効にします

サブドメインは予測できません（CFW-06）。デプロイ後にサブドメインを確認してください。

npx wrangler whoami

フェーズ 8：デプロイと検証

moon run <project>:publish-site

curl ではなくブラウザーで検証してください（CFW-08）。macOS の LibreSSL では Cloudflare との TLS ハンドシェイクに失敗することがありますが、ブラウザーでは正常に処理できます。

---

アンチパターンの概要

コード例を含む詳細については、references/anti-patterns.mdを参照してください。

ID	重大度	注意点	対処
CFW-01	HIGH	Cloudflare Pages は廃止予定です（2025年4月）	Static Assets を使用して Workers を利用します
CFW-02	HIGH	1P サービスアカウントでアイテムを作成する	生体認証または Web UI で事前にプロビジョニングします
CFW-03	HIGH	CONCEALED フィールドで --reveal が不足している	API トークンには必ず --reveal を指定します
CFW-04	MEDIUM	SC2155 export VAR=$(cmd)	分けて記述します：VAR=$(cmd) の後に export VAR
CFW-05	LOW	macOS で Bash 4 以降の ${var^^} を使用する	tr '[:lower:]' '[:upper:]' を使用します
CFW-06	MEDIUM	workers.dev の URL 形式を決めつける	npx wrangler whoami を実行してスラッグを確認します
CFW-07	HIGH	workers.dev サブドメインが登録されていない	まず Cloudflare ダッシュボードで有効にします
CFW-08	LOW	macOS で curl の SSL/TLS ハンドシェイクに失敗する	代わりにブラウザーで確認します
CFW-09	MEDIUM	wrangler.toml を複雑にしすぎる	name、compatibility_date、[assets] のみを使用します
CFW-10	HIGH	誤ったディレクトリから wrangler を実行する	必ず wrangler.toml があるディレクトリに cd します
CFW-11	MEDIUM	トークンの権限が過剰	Workers Scripts Edit（Account）のみ
CFW-12	HIGH	ファイルではなく LFS ポインターをデプロイする	デプロイ前に git lfs pull を実行します
CFW-13	MEDIUM	タスクランナー設定に Bash をインラインで記述する	複雑な Bash は独立した .sh ファイルに記述します
CFW-14	MEDIUM	while-read でパイプのサブシェルによりデータが失われる	< <(find ...) のプロセス置換を使用します
CFW-15	LOW	ディレクトリ一覧ページがない	デプロイごとに index.html を自動生成します
CFW-16	HIGH	アセットが 25 MiB 超 → デプロイエラー Asset too large	Workers Static Assets では各ファイルが 25 MiB に制限されています。大きな ZIP／バイナリは大容量ファイル用ホスト（R2、GitHub Release、自前サーバー）でホストし、Workers には 25 MiB 以下のファイルのみを置きます。大容量ファイルと ZIP の配信を参照してください
CFW-17	LOW	一括ダウンロード用 ZIP が上限を超える場合	ZIP のサイズ区分を縮小して上限内に収める（例：heic-to-jpeg-bundle --zip-cap-mib 25）か、ホストを分けます：ギャラリーと小さな ZIP は Workers に、フル解像度の ZIP は R2 に置きます

---

大きなファイルと ZIP の配信（ページだけでなくダウンロードも）

このスキルでは、Workers からダウンロード可能なファイル（ZIP バンドルやデータセット）を配信する方法（1 ファイルあたり 25 MiB の上限内）と、通常は公開されていないダウンロードへのアクセスを制限するゲートウェイでのパスワード認証パターンも扱います。詳しいガイド： references/large-files-and-zip-delivery.md。

簡単なルール：

• 25 MiB 以下 → Workers で問題ありません。 小さめの ZIP や縮小版の ZIP はギャラリーの隣に配置して、直接リンクできます。> 25 MiB はデプロイ時に必ずエラーになります（CFW-16）。その場合は、R2／GitHub Release／独自のホストを使用してください。
• パスワードで保護された非公開ダウンロード。 ZIP を暗号化し（ZipCrypto を使用するため、Windows／7-Zip／macOS でそのまま開けます）、パスワードは共有するゲートウェイ（gist やメールなど）にのみ記載します。Workers ページには絶対に記載しないでください。ZIP の URL が分かっただけでは、ファイルを開けません。heic-to-jpeg-bundle スキルを使うと、上限内のこの種の ZIP（任意で暗号化可能）をそのまま作成できます。

---

リファレンス実装

本番環境で稼働しているデプロイは rangebar-patterns にあります。

ファイル	目的
results/published/wrangler.toml	最小限の Workers 設定
scripts/publish_findings.sh	3 フェーズのデプロイスクリプト
.gitignore（.wrangler/）	wrangler の一時ファイルを無視
.gitattributes	HTML の LFS トラッキング

稼働 URL：https://rangebar-findings.terry-301.workers.dev/

---

変更後のチェックリスト

このスキルを変更した後：

1. アンチパターンの表が references/anti-patterns.md と一致している
2. すべての bash の例で set -euo pipefail を使用している
3. 1Password アイテム ID がハードコードされていない（パラメーター化されている）
4. workers.dev のスラッグがハードコードされていない（実行時に検出される）
5. テンプレートスクリプトが bash -n の構文チェックに合格する
6. 内部リンクがすべて相対パス（./references/...）になっている
7. リンク検証に合格する
8. スキル検証に合格する
9. 変更内容を references/evolution-log.md に追記する

---

トラブルシューティング

問題	原因	解決策
op item get でマスクされた値が返る	--reveal フラグがない（CFW-03）	CONCEALED フィールドに --reveal を追加する
op item create が失敗する	サービスアカウントに作成権限がない（CFW-02）	まず生体認証対応の op またはウェブ UI を使ってアイテムを作成する
wrangler：設定が見つからない	正しいディレクトリにいない（CFW-10）	デプロイ前に wrangler.toml を含むディレクトリへ cd する
SSL ハンドシェイクに失敗する	macOS の LibreSSL（CFW-08）	ブラウザーで確認し、curl のエラーは無視する
workers.dev URL で 403 が発生する	サブドメインが有効になっていない（CFW-07）	Cloudflare ダッシュボード > Workers & Pages で有効にする
デプロイは成功するが、ファイルがない	LFS ポインターがデプロイされた（CFW-12）	デプロイ前に git lfs pull を実行する
${var^^} の構文エラー	macOS の Bash 3（CFW-05）	tr '[:lower:]' '[:upper:]' を使用する
タスクコマンドが壊れる／失敗する	タスク設定内のインライン bash（CFW-13）	複雑な bash を独立した .sh ファイルに移す
空の index.html	gen*/*.html ファイルが見つからない	ファイルパスが find . -path './gen*/*.html' パターンに一致するか確認する
トークンの権限が拒否される	トークンのスコープが誤っている（CFW-11）	Account > Workers Scripts > Edit 権限を付与して作り直す

実行後の振り返り

このスキルの実行後、タスクを終了する前に振り返りを行います。

0. 現在の場所を確認する。 — 編集する前に、この SKILL.md の正式なパスを見つけます（このスキル名で Glob を実行します）。修正の対象はこのファイルとその兄弟にあたる references/ のみです。他のドキュメントには手を加えないでください。
1. 何が失敗したか？ — 原因となった指示を修正します。再発する可能性がある場合は、アンチパターンとして追加します。
2. 予想以上にうまくいったことは？ — 推奨プラクティスとして採用します。理由も記録します。
3. 何が現状とずれていたか？ — 実態に合わなくなったスクリプト、リファレンス、外部依存関係は、今すぐ修正します。
4. 記録する。 — 変更ごとに、きっかけ、修正内容、根拠を含む進化ログのエントリーを記録します。

先送りしないでください。次回の実行では、残した状態が引き継がれます。