Cloudflare Workers Publish

---
name: cloudflare-workers-publish
description: Deploy static HTML files to Cloudflare Workers with 1Password credential management.
disable-model-invocation: false
allowed-tools: Read, Bash, Grep, Write, Edit, Glob, AskUserQuestion
---

# Cloudflare Workers Publish

Deploy static HTML files (Bokeh charts, dashboards, reports) to Cloudflare Workers with Static Assets, using 1Password for credential management.

**Scope**: Static-only deployments on workers.dev. No dynamic Workers, no R2 object storage.

**Prerequisite**: 1Password CLI (`brew install 1password-cli`) + Node.js (`npx wrangler`)

---

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## When to Use This Skill

- Publishing HTML files to a public URL (too large for GitHub)
- Setting up a new Cloudflare Workers static site
- Troubleshooting a failed Cloudflare deploy
- Rotating Cloudflare API tokens in 1Password

**Do NOT use for**: Dynamic Workers (JavaScript/TypeScript logic), Cloudflare Pages (deprecated April 2025 - CFW-01), R2 object storage, or custom domains (advanced setup not covered).

---

## Architecture

```
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 Task Templates

### Template A - New Static Site (First-Time Setup)

```
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
```

### Template B - Add Files to Existing Published Site

```
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
```

### Template C - New Worker (New Subdomain/Project)

```
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
```

### Template D - Rotate Cloudflare API Token

```
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
```

### Template E - Troubleshoot Failed Deploy

```
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
```

---

## Workflow: First-Time Setup

### Phase 1: Create Cloudflare API Token

1. Go to <https://dash.cloudflare.com/profile/api-tokens>
2. Click **Create Token** > **Custom token**
3. Set permissions: **Account** > **Workers Scripts** > **Edit** (CFW-11)
4. Account Resources: **Include** > your account
5. Copy the token (shown only once)

### Phase 2: Provision 1Password Credentials

**CRITICAL (CFW-02)**: 1Password service accounts can only READ items. They CANNOT CREATE new items. Create the item manually first.

See [1Password setup guide](./references/onep-credential-setup.md) for step-by-step instructions.

After provisioning, the item should have:

| Field        | Type      | `--reveal` | Content            |
| ------------ | --------- | ---------- | ------------------ |
| `account_id` | TEXT      | No         | Cloudflare acct ID |
| `credential` | CONCEALED | **YES**    | API token          |

### Phase 3: Create wrangler.toml

See [wrangler setup guide](./references/wrangler-setup.md).

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

[assets]
directory = "."
```

### Phase 4: Create Deploy Script

Copy the bundled template and edit the 4 config variables:

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

Or reference the working implementation: `rangebar-patterns/scripts/publish_findings.sh`

### Phase 5: Create moon Task

```yaml
# 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
```

If the repo has no moon workspace yet, bootstrap one with `Skill(itp:bootstrap-monorepo)`, or run the script directly with `bash scripts/publish_myproject.sh`.

### Phase 6: Git Hygiene

**.gitignore**:

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

**.gitattributes** (for large HTML files):

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

### Phase 7: Enable workers.dev Subdomain (CFW-07)

First-time Cloudflare accounts must enable the workers.dev route:

1. Go to <https://dash.cloudflare.com> > **Workers & Pages**
2. Enable workers.dev subdomain

**The subdomain is NOT predictable** (CFW-06). Discover yours after deploy:

```bash
npx wrangler whoami
```

### Phase 8: Deploy and Verify

```bash
moon run <project>:publish-site
```

**Verify in BROWSER, not curl** (CFW-08). macOS LibreSSL can fail TLS handshake with Cloudflare but browsers handle it fine.

---

## Anti-Patterns Summary

Full details with code examples: [references/anti-patterns.md](./references/anti-patterns.md)

| ID     | Severity | Gotcha                                           | Fix                                                                                                                                                                                                                                                          |
| ------ | -------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CFW-01 | HIGH     | Cloudflare Pages deprecated (April 2025)         | Use Workers with Static Assets                                                                                                                                                                                                                               |
| CFW-02 | HIGH     | 1P service account creating items                | Pre-provision via biometric/web UI                                                                                                                                                                                                                           |
| CFW-03 | HIGH     | Missing `--reveal` for CONCEALED fields          | Always pass `--reveal` for API tokens                                                                                                                                                                                                                        |
| CFW-04 | MEDIUM   | SC2155 `export VAR=$(cmd)`                       | Split: `VAR=$(cmd)` then `export VAR`                                                                                                                                                                                                                        |
| CFW-05 | LOW      | Bash 4+ `${var^^}` on macOS                      | Use `tr '[:lower:]' '[:upper:]'`                                                                                                                                                                                                                             |
| CFW-06 | MEDIUM   | Assuming workers.dev URL format                  | Run `npx wrangler whoami` to discover slug                                                                                                                                                                                                                   |
| CFW-07 | HIGH     | workers.dev subdomain not registered             | Enable in Cloudflare dashboard first                                                                                                                                                                                                                         |
| CFW-08 | LOW      | curl SSL/TLS handshake failure on macOS          | Verify in browser instead                                                                                                                                                                                                                                    |
| CFW-09 | MEDIUM   | Overcomplicating wrangler.toml                   | Only `name`, `compatibility_date`, `[assets]`                                                                                                                                                                                                                |
| CFW-10 | HIGH     | Running wrangler from wrong directory            | Always `cd` to directory with wrangler.toml                                                                                                                                                                                                                  |
| CFW-11 | MEDIUM   | Excessive token permissions                      | Workers Scripts Edit (Account) only                                                                                                                                                                                                                          |
| CFW-12 | HIGH     | Deploying LFS pointers instead of files          | Run `git lfs pull` before deploy                                                                                                                                                                                                                             |
| CFW-13 | MEDIUM   | Inline bash in task-runner config                | Complex bash in standalone `.sh` files                                                                                                                                                                                                                       |
| CFW-14 | MEDIUM   | Pipe subshell data loss in while-read            | Use `< <(find ...)` process substitution                                                                                                                                                                                                                     |
| CFW-15 | LOW      | No directory listing page                        | Auto-generate index.html before each deploy                                                                                                                                                                                                                  |
| CFW-16 | HIGH     | Asset > 25 MiB → `Asset too large` deploy error  | Workers Static Assets hard-caps **each file at 25 MiB**. Host large ZIPs/binaries off a large-file host (R2, GitHub Release, own server); keep only ≤25 MiB files on Workers. See [large files & ZIP delivery](./references/large-files-and-zip-delivery.md) |
| CFW-17 | LOW      | Want a bulk-download ZIP, but it exceeds the cap | Downscale the ZIP tier to fit (e.g. `heic-to-jpeg-bundle --zip-cap-mib 25`), or split hosts: gallery + small ZIP on Workers, full-res ZIP on R2                                                                                                              |

---

## Large files & ZIP delivery (downloads, not just pages)

This skill also covers serving **downloadable files** (a ZIP bundle, a dataset) from
Workers — within the 25 MiB/file cap — and the **password-on-the-gateway** pattern for
gating an otherwise-unlisted download. Full guide:
[references/large-files-and-zip-delivery.md](./references/large-files-and-zip-delivery.md).

Quick rules:

- **≤ 25 MiB → Workers is fine.** A small/downscaled ZIP can sit beside the gallery and be
  linked directly. `> 25 MiB` is a hard deploy error (CFW-16) — use R2 / a GitHub Release /
  your own host for those.
- **Password-gated, unlisted download.** Encrypt the ZIP (ZipCrypto, so Windows/7-Zip/macOS
  open it natively) and put the **password only on the gateway you share** (a gist, an
  email), never on the Workers page. Finding the bare ZIP URL then isn't enough to open it.
  The `heic-to-jpeg-bundle` skill produces exactly this kind of capped, optionally-encrypted
  ZIP.

---

## Reference Implementation

The working production deployment lives in `rangebar-patterns`:

| File                              | Purpose                    |
| --------------------------------- | -------------------------- |
| `results/published/wrangler.toml` | Minimal Workers config     |
| `scripts/publish_findings.sh`     | 3-phase deploy script      |
| `.gitignore` (`.wrangler/`)       | Ignore wrangler temp files |
| `.gitattributes`                  | LFS tracking for HTML      |

**Live URL**: `https://rangebar-findings.terry-301.workers.dev/`

---

## Post-Change Checklist

After modifying this skill:

1. [ ] Anti-patterns table matches [references/anti-patterns.md](./references/anti-patterns.md)
2. [ ] All bash examples use `set -euo pipefail`
3. [ ] No hardcoded 1Password item IDs (parameterized)
4. [ ] No hardcoded workers.dev slugs (discovered at runtime)
5. [ ] Template script passes `bash -n` syntax check
6. [ ] All internal links use relative paths (`./references/...`)
7. [ ] Link validator passes
8. [ ] Skill validator passes
9. [ ] Append changes to [references/evolution-log.md](./references/evolution-log.md)

---

## Troubleshooting

| Issue                          | Cause                                 | Solution                                                      |
| ------------------------------ | ------------------------------------- | ------------------------------------------------------------- |
| `op item get` returns masked   | Missing `--reveal` flag (CFW-03)      | Add `--reveal` for CONCEALED fields                           |
| `op item create` fails         | Service account can't create (CFW-02) | Use biometric `op` or web UI to create item first             |
| wrangler: config not found     | Not in correct directory (CFW-10)     | `cd` to directory containing wrangler.toml before deploy      |
| SSL handshake failure          | macOS LibreSSL (CFW-08)               | Verify in browser; ignore curl errors                         |
| 403 on workers.dev URL         | Subdomain not enabled (CFW-07)        | Enable in Cloudflare dashboard > Workers & Pages              |
| Deploy succeeds, files missing | LFS pointers deployed (CFW-12)        | Run `git lfs pull` before deploy                              |
| `${var^^}` syntax error        | Bash 3 on macOS (CFW-05)              | Use `tr '[:lower:]' '[:upper:]'`                              |
| Task command mangled/fails     | Inline bash in task config (CFW-13)   | Move complex bash to standalone `.sh` file                    |
| Empty index.html               | No `gen*/*.html` files found          | Check file paths match `find . -path './gen*/*.html'` pattern |
| Token permission denied        | Wrong token scope (CFW-11)            | Recreate with Account > Workers Scripts > Edit permission     |

## Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. **Locate yourself.** — Find this SKILL.md's canonical path (Glob for this skill's name) before editing. All corrections target THIS file and its sibling references/ — never other documentation.
1. **What failed?** — Fix the instruction that caused it. If it could recur, add it as an anti-pattern.
2. **What worked better than expected?** — Promote it to recommended practice. Document why.
3. **What drifted?** — Any script, reference, or external dependency that no longer matches reality gets fixed now.
4. **Log it.** — Every change gets an evolution-log entry with trigger, fix, and evidence.

## Do NOT defer. The next invocation inherits whatever you leave behind