RonanCodes/skills/cf-ship

CF Ship

Deploy a Cloudflare Workers app (TanStack Start on Path C) with a pre-flight gate. Prevents shipping broken code.

Usage

/ro:cf-ship                       # full pipeline
/ro:cf-ship --skip-tests          # skip pnpm test (hotfix mode)
/ro:cf-ship --skip-migrations     # skip D1 migrations (schema unchanged)
/ro:cf-ship --env staging         # deploy to a non-default wrangler env

Prerequisites

• wrangler authed. Three options in priority order:

  1. ~/.claude/.env has CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID from /ro:cloudflare-setup (the default for this user). Source pattern:

     set -a && source "$(ro context env)" && set +a
     unset GH_TOKEN GITHUB_TOKEN   # ~/.claude/.env shadows gh CLI keychain — must unset before any gh call
     

     Always grep this file BEFORE asking the user to paste a token or run wrangler login — for already-onboarded providers, the value is there.

     ★ Token capability matters: pick by capability, not the first match. On the personal ronanconnolly.dev account (c421a1b2…) there are two token classes and they are NOT interchangeable:

     • CLOUDFLARE_ACCOUNT_TOKEN_RONAN (a cfat_ account token, dashboard name "porkbun") has FULL access: D1, Containers, R2, KV, Queues, Vectorize, secrets, Workers, Zone. Use it whenever the app has a D1 binding (the deploy validates the binding, which needs D1 read), uses Containers, or you run wrangler d1 … / wrangler secret put.
     • CLOUDFLARE_API_TOKEN_RONAN (= _NUTMEG = _RONANCONNOLLY; a cfut_ user token) is Zone + Workers only (NO D1, NO Containers). Fine for a plain Workers/Pages deploy + DNS, nothing more.
     • Symptom of the wrong pick: Authentication error [10000] on wrangler d1/secrets, or binding … of type d1 must have a valid database_id [10021] on deploy. Switch to the cfat_ account token.
     • For other accounts the same rule holds: prefer the account-scoped (cfat_) token for D1/Containers. Memory reference_cloudflare_accounts has the matrix.

  2. wrangler login (browser OAuth) — fine for one-off interactive runs

  3. ${CLAUDE_PLUGIN_DATA}/.env (legacy, prefer ~/.claude/.env)

• wrangler.toml in repo root with a valid main or TanStack Start preset configured
• Clean or near-clean git tree (skill warns on uncommitted changes)

Process

1. Sanity check

Run in parallel:

git status --short
wrangler whoami
git rev-parse HEAD

If uncommitted changes exist, warn the user — offer to proceed anyway or abort. Print the current commit SHA and branch so there's a paper trail of what's shipping.

2. Pre-flight gates

Run in this order. Stop on first failure — do not try to "fix forward" without asking.

pnpm typecheck          # tsc --noEmit, strict mode
pnpm lint               # eslint .
pnpm format:check       # prettier --check .
pnpm test               # vitest run (skip if --skip-tests)

If any fails, surface the output and stop. Suggest /ro:commit after the fix.

3. D1 migrations

Unless --skip-migrations:

pnpm drizzle-kit generate                              # generate any pending migrations
wrangler d1 migrations list <db-name> --remote          # show what's pending remotely

Read the db name from wrangler.toml ([[d1_databases]] database_name). Show the user the list. If migrations are pending, confirm before applying:

wrangler d1 migrations apply <db-name> --remote

Apply local too (keeps dev DB matching):

wrangler d1 migrations apply <db-name> --local

Schema-assert (do not skip when drizzle/ exists). Applying migrations is not proof the prod DB has the schema the code expects: the apply can no-op against a wrongly-tracked or wrong database. After the remote apply, assert the code-expected schema is actually present on prod. For each table the current Drizzle schema declares, probe the live DB (PRAGMA table_info(<table>) via wrangler d1 execute <db-name> --remote --command=...) and fail the deploy loudly if any table or column is missing. Print exactly what is missing; never swallow it with || true. This gate exists because nutmeg 2026-06-11 shipped code whose schema prod lacked (silently unapplied migrations) and caused a user-facing P1. Full rule: canon/db-deploy-gate.md.

4. Secrets check

List current secrets and compare against .dev.vars:

wrangler secret list
grep -E '^[A-Z_]+=' .dev.vars 2>/dev/null | cut -d= -f1

If .dev.vars has a key that's NOT in wrangler secret list, warn the user and offer to push it:

wrangler secret put KEY_NAME        # prompts for value

Never auto-push secrets without confirmation.

5. Build + deploy

pnpm build
wrangler deploy                     # add --env <name> if --env passed

Capture the deployed URL from wrangler's output (https://<worker>.<account>.workers.dev or custom domain).

6. Smoke check

curl -sfI <deployed-url> | head -1        # expect HTTP/2 200 or 301

If it returns non-2xx/3xx, surface it immediately. Offer to tail logs:

wrangler tail

7. Infrastructure docs (post-first-deploy)

Once the smoke check passes: if docs/infrastructure/ does not exist (this is the first successful deploy), OR this deploy changed bindings/resources, run /ro:infra-docs to generate (or refresh) living architecture documentation — the live resource inventory, C4 + sequence diagrams, security model, and provisioning runbook. Standing up a new app should always leave it documented. The skill is idempotent, so a periodic re-run after notable deploys keeps it honest.

8. Tag + report

Offer to tag the release (optional):

git tag -a "deploy-$(date +%Y%m%d-%H%M%S)" -m "🚀 deploy: $(git log -1 --pretty=%s)"

Report to user: commit SHA, deployed URL, migrations applied, secrets status, smoke-check result, and whether infra docs were generated/refreshed.

Failure modes

• typecheck fails — stop. Fix types, commit via /ro:commit, re-run /ro:cf-ship.
• test fails — stop. Don't use --skip-tests as a habit; treat red tests as the signal they are.
• Migration apply errors — common cause: migration was generated against a stale schema. Re-run drizzle-kit generate with a clean working DB first.
• wrangler deploy fails on compatibility_date — bump to today's date in wrangler.toml.
• Smoke check 500 — wrangler tail immediately; usually a missing secret or bad D1 binding.

Safety

• Never --skip-tests + --skip-migrations together without explicit user confirmation
• Never deploy to prod (--env production) without showing current vs new commit first
• wrangler delete / wrangler d1 delete are NOT part of this skill — refuse if asked

See also

• /ro:commit — emoji commits (use before shipping)
• /ro:new-tanstack-app — scaffold that this skill ships
• /ro:cloudflare-dns — add a custom domain after first deploy