pi-cloudflare 0.1.0

package/skills/turnstile-spin/scripts/persist-skill.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# Persists the canonical Spin skill bundle into the current project.
+
+set +x
+set -uo pipefail
+
+unset CLOUDFLARE_API_TOKEN CF_API_TOKEN CLOUDFLARE_API_KEY CF_API_KEY
+unset CLOUDFLARE_EMAIL CF_API_EMAIL WIDGET_SECRET TURNSTILE_SECRET
+unset WRANGLER_BIN WRANGLER_VERSION
+unset GITHUB_TOKEN GH_TOKEN GITLAB_TOKEN NPM_TOKEN
+
+need_arg() {
+  if [[ -z "${2-}" || "$2" == --* ]]; then
+    echo "persist-skill: missing value for $1" >&2
+    exit 2
+  fi
+}
+
+PATH_ARG=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --path) need_arg "$1" "${2-}"; PATH_ARG="$2"; shift 2 ;;
+    *) echo "persist-skill: unknown arg $1" >&2; exit 2 ;;
+  esac
+done
+
+[[ -n "$PATH_ARG" ]] || { echo "persist-skill: --path required" >&2; exit 2; }
+if [[ "$(basename "$PATH_ARG")" != "SKILL.md" ]]; then
+  echo "persist-skill: --path must end in SKILL.md for a directory-based skill bundle" >&2
+  echo '{"status":"error","reason":"file_target_not_supported"}'
+  exit 2
+fi
+
+for command_name in git python3; do
+  command -v "$command_name" >/dev/null 2>&1 || {
+    echo "persist-skill: $command_name is required" >&2
+    echo "{\"status\":\"error\",\"reason\":\"${command_name}_not_available\"}"
+    exit 1
+  }
+done
+
+PROJECT_ROOT="$(pwd -P)"
+TARGET_DIR="$(python3 -I -c 'import os,sys; print(os.path.realpath(os.path.abspath(sys.argv[1])))' "$(dirname "$PATH_ARG")")"
+if [[ "$TARGET_DIR" != "$PROJECT_ROOT" && "$TARGET_DIR" != "$PROJECT_ROOT/"* ]]; then
+  echo "persist-skill: target must be inside the current project" >&2
+  echo '{"status":"error","reason":"target_outside_project"}'
+  exit 1
+fi
+if [[ -e "$TARGET_DIR" ]] && ! python3 -I -c 'import os,sys; raise SystemExit(0 if not os.listdir(sys.argv[1]) else 1)' "$TARGET_DIR"; then
+  echo "persist-skill: target directory is not empty" >&2
+  echo '{"status":"error","reason":"target_not_empty"}'
+  exit 1
+fi
+
+if ! TEMP_DIR="$(mktemp -d "${TMPDIR:-/tmp}/turnstile-spin-persist.XXXXXX")"; then
+  echo "persist-skill: could not create a temporary directory" >&2
+  echo '{"status":"error","reason":"temporary_directory_failed"}'
+  exit 1
+fi
+trap 'rm -rf "$TEMP_DIR"' EXIT
+
+if ! git -c core.hooksPath=/dev/null clone \
+  --quiet \
+  --depth 1 \
+  --filter=blob:none \
+  --sparse \
+  "https://github.com/cloudflare/skills.git" \
+  "$TEMP_DIR/repo"; then
+  echo "persist-skill: clone failed" >&2
+  echo '{"status":"error","reason":"clone_failed"}'
+  exit 1
+fi
+if ! git -C "$TEMP_DIR/repo" -c core.hooksPath=/dev/null sparse-checkout set skills/turnstile-spin; then
+  echo "persist-skill: sparse checkout failed" >&2
+  echo '{"status":"error","reason":"sparse_checkout_failed"}'
+  exit 1
+fi
+
+SOURCE_DIR="$TEMP_DIR/repo/skills/turnstile-spin"
+if [[ ! -f "$SOURCE_DIR/SKILL.md" ]]; then
+  echo "persist-skill: canonical bundle is missing SKILL.md" >&2
+  echo '{"status":"error","reason":"skill_missing"}'
+  exit 1
+fi
+
+python3 -I - "$SOURCE_DIR" "$TARGET_DIR" <<'PY'
+import pathlib
+import shutil
+import sys
+
+source = pathlib.Path(sys.argv[1])
+target = pathlib.Path(sys.argv[2])
+if target.exists():
+    target.rmdir()
+target.parent.mkdir(parents=True, exist_ok=True)
+shutil.copytree(source, target, dirs_exist_ok=False)
+for script in (target / "scripts").glob("*.sh"):
+    script.chmod(0o755)
+PY
+
+python3 -I - "$PATH_ARG" "$TARGET_DIR" <<'PY'
+import json
+import pathlib
+import sys
+
+path_arg, bundle_root = sys.argv[1], pathlib.Path(sys.argv[2])
+scripts = sorted(path.name for path in (bundle_root / "scripts").glob("*.sh"))
+print(json.dumps({
+    "status": "ok",
+    "path": path_arg,
+    "bundle_root": str(bundle_root),
+    "scripts": scripts,
+}))
+PY

package/skills/turnstile-spin/scripts/validate.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# Validates a Turnstile widget without placing its secret in arguments,
+# exported environment variables, logs, or temporary files.
+
+set +x
+set -euo pipefail
+
+usage() {
+  echo "Usage: printf '%s' \"\$TURNSTILE_SECRET\" | $0 --sitekey <sitekey> --account-id <account-id> --expected-domains '<json-array>'" >&2
+  exit 2
+}
+
+need_arg() {
+  if [[ -z "${2-}" || "$2" == --* ]]; then
+    usage
+  fi
+}
+
+SITEKEY=""
+ACCOUNT_ID=""
+EXPECTED_DOMAINS_JSON=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --sitekey)
+      need_arg "$1" "${2-}"
+      SITEKEY="$2"
+      shift 2
+      ;;
+    --account-id)
+      need_arg "$1" "${2-}"
+      ACCOUNT_ID="$2"
+      shift 2
+      ;;
+    --expected-domains)
+      need_arg "$1" "${2-}"
+      EXPECTED_DOMAINS_JSON="$2"
+      shift 2
+      ;;
+    *) usage ;;
+  esac
+done
+
+[[ -n "$SITEKEY" && -n "$ACCOUNT_ID" && -n "$EXPECTED_DOMAINS_JSON" ]] || usage
+: "${CLOUDFLARE_API_TOKEN:?CLOUDFLARE_API_TOKEN must be set}"
+API_TOKEN="$CLOUDFLARE_API_TOKEN"
+unset CLOUDFLARE_API_TOKEN
+[[ "$API_TOKEN" =~ ^[A-Za-z0-9_-]+$ ]] || {
+  echo "validate: CLOUDFLARE_API_TOKEN has an invalid format" >&2
+  exit 1
+}
+
+for command_name in curl jq python3; do
+  command -v "$command_name" >/dev/null 2>&1 || {
+    echo "validate: $command_name is required" >&2
+    exit 1
+  }
+done
+
+if ! jq -e '
+  type == "array" and
+  length > 0 and
+  all(.[]; type == "string" and length > 0)
+' <<<"$EXPECTED_DOMAINS_JSON" >/dev/null; then
+  echo "validate: --expected-domains must be a non-empty JSON array of domains" >&2
+  exit 2
+fi
+
+WIDGET_SECRET=""
+IFS= read -r -d '' WIDGET_SECRET || true
+trap 'unset API_TOKEN WIDGET_SECRET WIDGET_API_SECRET WIDGET_RESPONSE SITEVERIFY_RESPONSE' EXIT
+
+if [[ -z "$WIDGET_SECRET" || "$WIDGET_SECRET" =~ [[:space:]] ]]; then
+  echo "validate: standard input must contain one non-empty secret without whitespace" >&2
+  exit 1
+fi
+
+ACCOUNT_ENCODED="$(python3 -I -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$ACCOUNT_ID")"
+SITEKEY_ENCODED="$(python3 -I -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$SITEKEY")"
+
+if ! WIDGET_RESPONSE="$(
+  printf 'header = "Authorization: Bearer %s"\n' "$API_TOKEN" |
+    curl --disable --config - --fail --silent --show-error \
+      "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ENCODED/challenges/widgets/$SITEKEY_ENCODED"
+)"; then
+  echo "validate: widget metadata lookup failed" >&2
+  exit 1
+fi
+
+if ! printf '%s' "$WIDGET_RESPONSE" | jq -e --arg sitekey "$SITEKEY" --argjson expected "$EXPECTED_DOMAINS_JSON" '
+  . as $widget
+  | (.success == true) and
+    (.result.sitekey == $sitekey) and
+    ((.result.clearance_level | type) == "string") and
+    (.result.clearance_level as $clearance | ["no_clearance", "interactive", "managed", "jschallenge"] | index($clearance) != null) and
+    ((.result.domains | type) == "array") and
+    (all($expected[]; . as $domain | $widget.result.domains | index($domain) != null))
+' >/dev/null; then
+  echo "validate: widget sitekey, domains, or clearance level was invalid" >&2
+  exit 1
+fi
+
+if ! WIDGET_API_SECRET="$(printf '%s' "$WIDGET_RESPONSE" | jq -er '.result.secret | select(type == "string" and test("^\\S+$"))')"; then
+  echo "validate: widget metadata did not include a valid secret" >&2
+  exit 1
+fi
+if [[ "$WIDGET_API_SECRET" != "$WIDGET_SECRET" ]]; then
+  echo "validate: secret does not belong to the requested sitekey" >&2
+  exit 1
+fi
+unset WIDGET_API_SECRET
+unset WIDGET_RESPONSE
+
+if ! SITEVERIFY_RESPONSE="$(
+  printf '%s' "$WIDGET_SECRET" |
+    python3 -I -c 'import sys,urllib.parse; print(urllib.parse.urlencode({"secret":sys.stdin.read(),"response":"XXXX.DUMMY.TOKEN.XXXX"}),end="")' |
+    curl --disable --fail --silent --show-error \
+      "https://challenges.cloudflare.com/turnstile/v0/siteverify" \
+      -H "Content-Type: application/x-www-form-urlencoded" \
+      --data-binary @-
+)"; then
+  echo "validate: dummy-token siteverify request failed" >&2
+  exit 1
+fi
+
+if ! jq -e '
+  (.success == false) and
+  ((.["error-codes"] | type) == "array") and
+  ((.["error-codes"] | index("invalid-input-response")) != null) and
+  ((.["error-codes"] | index("invalid-input-secret")) == null)
+' <<<"$SITEVERIFY_RESPONSE" >/dev/null; then
+  echo "validate: siteverify did not confirm the widget secret" >&2
+  exit 1
+fi
+
+unset WIDGET_SECRET SITEVERIFY_RESPONSE
+echo '{"status":"ok","metadata_check":"ran","dummy_siteverify":"ran"}'

package/skills/turnstile-spin/scripts/widget-create.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# Creates a Turnstile widget without writing credentials or the response to disk.
+
+set +x
+set -uo pipefail
+
+need_arg() {
+  if [[ -z "${2-}" || "$2" == --* ]]; then
+    echo "widget-create: missing value for $1" >&2
+    exit 2
+  fi
+}
+
+MODE="managed"
+ACCOUNT_ID=""
+NAME=""
+DOMAINS=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --account-id) need_arg "$1" "${2-}"; ACCOUNT_ID="$2"; shift 2 ;;
+    --name) need_arg "$1" "${2-}"; NAME="$2"; shift 2 ;;
+    --domains) need_arg "$1" "${2-}"; DOMAINS="$2"; shift 2 ;;
+    --mode) need_arg "$1" "${2-}"; MODE="$2"; shift 2 ;;
+    *) echo "widget-create: unknown arg $1" >&2; exit 2 ;;
+  esac
+done
+
+: "${CLOUDFLARE_API_TOKEN:?CLOUDFLARE_API_TOKEN must be set}"
+API_TOKEN="$CLOUDFLARE_API_TOKEN"
+unset CLOUDFLARE_API_TOKEN
+[[ -n "$ACCOUNT_ID" ]] || { echo "widget-create: --account-id required" >&2; exit 2; }
+[[ -n "$NAME" ]] || { echo "widget-create: --name required" >&2; exit 2; }
+[[ -n "$DOMAINS" ]] || { echo "widget-create: --domains required" >&2; exit 2; }
+[[ "$API_TOKEN" =~ ^[A-Za-z0-9_-]+$ ]] || {
+  echo "widget-create: CLOUDFLARE_API_TOKEN has an invalid format" >&2
+  exit 1
+}
+case "$MODE" in
+  managed|invisible|non-interactive) ;;
+  *) echo "widget-create: unsupported mode" >&2; exit 2 ;;
+esac
+
+for command_name in curl python3; do
+  command -v "$command_name" >/dev/null 2>&1 || {
+    echo "widget-create: $command_name is required" >&2
+    exit 1
+  }
+done
+
+BODY_JSON="$(python3 -I -c '
+import json, sys
+name, domains_csv, mode = sys.argv[1], sys.argv[2], sys.argv[3]
+domains = [domain.strip() for domain in domains_csv.split(",") if domain.strip()]
+if not domains:
+    raise SystemExit(2)
+print(json.dumps({"name": name, "domains": domains, "mode": mode}))
+' "$NAME" "$DOMAINS" "$MODE")" || {
+  echo "widget-create: --domains must include at least one domain" >&2
+  exit 2
+}
+ACCOUNT_ENCODED="$(python3 -I -c 'import sys,urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$ACCOUNT_ID")"
+
+if ! API_RESPONSE="$(
+  printf 'header = "Authorization: Bearer %s"\n' "$API_TOKEN" |
+    curl --disable --config - --silent --show-error --write-out $'\n%{http_code}' -X POST \
+      "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ENCODED/challenges/widgets" \
+      -H "Content-Type: application/json" \
+      --data "$BODY_JSON"
+)"; then
+  echo "widget-create: Cloudflare API request failed" >&2
+  echo '{"status":"error","code":0,"message":"Cloudflare API request failed"}'
+  exit 1
+fi
+unset BODY_JSON
+unset API_TOKEN
+
+HTTP_CODE="${API_RESPONSE##*$'\n'}"
+RESPONSE_BODY="${API_RESPONSE%$'\n'*}"
+unset API_RESPONSE
+
+if ! printf '%s' "$RESPONSE_BODY" | python3 -I -c '
+import json
+import re
+import sys
+
+http_code = sys.argv[1]
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    print(f"widget-create: non-JSON response (HTTP {http_code})", file=sys.stderr)
+    print(json.dumps({"status":"error","code":0,"message":"Cloudflare API returned an invalid response"}))
+    raise SystemExit(1)
+
+errors = data.get("errors") if isinstance(data, dict) else []
+first = errors[0] if isinstance(errors, list) and errors and isinstance(errors[0], dict) else {}
+code = first.get("code", 0)
+if not isinstance(data, dict) or data.get("success") is not True:
+    print(f"widget-create: request failed (HTTP {http_code}, code={code})", file=sys.stderr)
+    print(json.dumps({"status":"error","code":code,"message":"Cloudflare API request failed"}))
+    raise SystemExit(1)
+
+result = data.get("result")
+sitekey = result.get("sitekey") if isinstance(result, dict) else None
+secret = result.get("secret") if isinstance(result, dict) else None
+if not (
+    isinstance(sitekey, str)
+    and re.fullmatch(r"\S{1,256}", sitekey)
+    and isinstance(secret, str)
+    and re.fullmatch(r"\S{1,1024}", secret)
+):
+    print("widget-create: API returned invalid widget credentials", file=sys.stderr)
+    print(json.dumps({"status":"error","code":0,"message":"Cloudflare API returned invalid widget credentials"}))
+    raise SystemExit(1)
+
+print(json.dumps({"status":"ok","sitekey":sitekey,"secret":secret}))
+' "$HTTP_CODE"; then
+  unset RESPONSE_BODY
+  exit 1
+fi
+unset RESPONSE_BODY

package/skills/turnstile-spin/tests/validation.md

@@ -0,0 +1,62 @@
+# Skill validation cases
+
+These cases match the assertions in the Turnstile Spin PRD. Run them after editing this skill to confirm an agent loading it can still execute the wizard end-to-end.
+
+## Test 1: Dummy Siteverify returns a structured error
+
+Step 10's `validate.sh` sends a deliberately-invalid token directly to `challenges.cloudflare.com/turnstile/v0/siteverify` using the captured secret. The expected response is `success: false` with `error-codes: ["invalid-input-response"]`. Anything else means the secret is wrong or the widget is misconfigured.
+
+```sh
+printf '%s' "$WIDGET_SECRET" |
+  python3 -I -c 'import sys,urllib.parse; print(urllib.parse.urlencode({"secret":sys.stdin.read(),"response":"XXXX.DUMMY.TOKEN.XXXX"}),end="")' |
+  curl --disable --fail --silent --show-error \
+    "https://challenges.cloudflare.com/turnstile/v0/siteverify" \
+    -H "Content-Type: application/x-www-form-urlencoded" \
+    --data-binary @- |
+  jq -e '.success == false and (.["error-codes"] | index("invalid-input-response"))'
+```
+
+Expected exit code: 0.
+
+## Test 2: Metadata matches the sitekey and secret
+
+```sh
+printf '%s' "$WIDGET_SECRET" |
+  scripts/validate.sh \
+    --sitekey "$SITEKEY" \
+    --account-id "$ACCOUNT_ID" \
+    --expected-domains '["example.com","localhost","127.0.0.1"]'
+```
+
+Expected exit code: 0 for all valid clearance levels: `no_clearance`, `interactive`, `managed`, and `jschallenge`. A secret from another sitekey must fail.
+
+## Test 3: Runtime checks match the protected surface
+
+Inspect every generated frontend and backend pair:
+
+- The widget has a meaningful action such as `signup`, `login`, or `contact`.
+- The backend requires the same `result.action` value.
+- The backend requires `result.hostname` to match its deployment-specific frontend hostname allowlist.
+- A production hostname allowlist does not contain `localhost` or `127.0.0.1`.
+
+## Test 4: Same-page retries reset the correct widget
+
+Native forms that navigate do not need reset logic. For each same-page flow, verify that the code retains the widget ID returned by `turnstile.render()` and calls `turnstile.reset(widgetId)` after the request completes. Multiple protected surfaces must not share a widget ID or reset without an ID.
+
+## Test 5: Skill persists to a bundle location
+
+After Step 11:
+
+```sh
+test -f .claude/skills/turnstile-spin/SKILL.md \
+  || test -f .codex/skills/turnstile-spin/SKILL.md \
+  || test -f .opencode/skills/turnstile-spin/SKILL.md
+```
+
+Expected exit code: 0. File-oriented rules targets install the hosted `prompt.md` directly instead of using `persist-skill.sh`.
+
+## Running all cases
+
+The consuming test harness must pass the widget secret through standard input. It must not export it or place it in a command argument.
+
+(`run-all.sh` is not bundled with this skill; the cases above are intended to be wired into the consuming agent's own test harness, or run by hand after a deploy.)

package/skills/workers-best-practices/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: workers-best-practices
+description: Reviews and authors Cloudflare Workers code against production best practices. Load when writing new Workers, reviewing Worker code, configuring wrangler.jsonc, or checking for common Workers anti-patterns (streaming, floating promises, global state, secrets, bindings, observability). Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
+---
+
+Your knowledge of Cloudflare Workers APIs, types, and configuration may be outdated. **Prefer retrieval over pre-training** for any Workers code task — writing or reviewing.
+
+## Retrieval Sources
+
+Fetch the **latest** versions before writing or reviewing Workers code. Do not rely on baked-in knowledge for API signatures, config fields, or binding shapes.
+
+| Source | How to retrieve | Use for |
+|--------|----------------|---------|
+| Workers best practices | Fetch `https://developers.cloudflare.com/workers/best-practices/workers-best-practices/` | Canonical rules, patterns, anti-patterns |
+| Workers types | See `references/review.md` for retrieval steps | API signatures, handler types, binding types |
+| Wrangler config schema | `node_modules/wrangler/config-schema.json` | Config fields, binding shapes, allowed values |
+| Cloudflare docs | Search tool or `https://developers.cloudflare.com/workers/` | API reference, compatibility dates/flags |
+
+## FIRST: Fetch Latest References
+
+Before reviewing or writing Workers code, retrieve the current best practices page and relevant type definitions. If the project's `node_modules` has an older version, **prefer the latest published version**.
+
+```bash
+# Fetch latest workers types
+mkdir -p /tmp/workers-types-latest && \
+  npm pack @cloudflare/workers-types --pack-destination /tmp/workers-types-latest && \
+  tar -xzf /tmp/workers-types-latest/cloudflare-workers-types-*.tgz -C /tmp/workers-types-latest
+# Types at /tmp/workers-types-latest/package/index.d.ts
+```
+
+## Reference Documentation
+
+- `references/rules.md` — all best practice rules with code examples and anti-patterns
+- `references/review.md` — type validation, config validation, binding access patterns, review process
+
+## Rules Quick Reference
+
+### Configuration
+
+| Rule | Summary |
+|------|---------|
+| Compatibility date | Set `compatibility_date` to today on new projects; update periodically on existing ones |
+| nodejs_compat | Enable the `nodejs_compat` flag — many libraries depend on Node.js built-ins |
+| wrangler types | Run `wrangler types` to generate `Env` — never hand-write binding interfaces |
+| Secrets | Use `wrangler secret put`, never hardcode secrets in config or source |
+| wrangler.jsonc | Use JSONC config for non-secret settings — newer features are JSON-only |
+
+### Request & Response Handling
+
+| Rule | Summary |
+|------|---------|
+| Streaming | Stream large/unknown payloads — never `await response.text()` on unbounded data |
+| waitUntil | Use `ctx.waitUntil()` for post-response work; do not destructure `ctx` |
+
+### Architecture
+
+| Rule | Summary |
+|------|---------|
+| Bindings over REST | Use in-process bindings (KV, R2, D1, Queues) — not the Cloudflare REST API |
+| Queues & Workflows | Move async/background work off the critical path |
+| Service bindings | Use service bindings for Worker-to-Worker calls — not public HTTP |
+| Hyperdrive | Always use Hyperdrive for external PostgreSQL/MySQL connections |
+
+### Observability
+
+| Rule | Summary |
+|------|---------|
+| Logs & Traces | Enable `observability` in config with `head_sampling_rate`; use structured JSON logging |
+
+### Code Patterns
+
+| Rule | Summary |
+|------|---------|
+| No global request state | Never store request-scoped data in module-level variables |
+| Floating promises | Every Promise must be `await`ed, `return`ed, `void`ed, or passed to `ctx.waitUntil()` |
+
+### Security
+
+| Rule | Summary |
+|------|---------|
+| Web Crypto | Use `crypto.randomUUID()` / `crypto.getRandomValues()` — never `Math.random()` for security |
+| No passThroughOnException | Use explicit try/catch with structured error responses |
+
+## Anti-Patterns to Flag
+
+| Anti-pattern | Why it matters |
+|-------------|----------------|
+| `await response.text()` on unbounded data | Memory exhaustion — 128 MB limit |
+| Hardcoded secrets in source or config | Credential leak via version control |
+| `Math.random()` for tokens/IDs | Predictable, not cryptographically secure |
+| Bare `fetch()` without `await` or `waitUntil` | Floating promise — dropped result, swallowed error |
+| Module-level mutable variables for request state | Cross-request data leaks, stale state, I/O errors |
+| Cloudflare REST API from inside a Worker | Unnecessary network hop, auth overhead, added latency |
+| `ctx.passThroughOnException()` as error handling | Hides bugs, makes debugging impossible |
+| Hand-written `Env` interface | Drifts from actual wrangler config bindings |
+| Direct string comparison for secret values | Timing side-channel — use `crypto.subtle.timingSafeEqual` |
+| Destructuring `ctx` (`const { waitUntil } = ctx`) | Loses `this` binding — throws "Illegal invocation" at runtime |
+| `any` on `Env` or handler params | Defeats type safety for all binding access |
+| `as unknown as T` double-cast | Hides real type incompatibilities — fix the design |
+| `implements` on platform base classes (instead of `extends`) | Legacy — loses `this.ctx`, `this.env`. Applies to DurableObject, WorkerEntrypoint, Workflow |
+| `env.X` inside platform base class | Should be `this.env.X` in classes extending DurableObject, WorkerEntrypoint, etc. |
+
+## Review Workflow
+
+1. **Retrieve** — fetch latest best practices page, workers types, and wrangler schema
+2. **Read full files** — not just diffs; context matters for binding access patterns
+3. **Check types** — binding access, handler signatures, no `any`, no unsafe casts (see `references/review.md`)
+4. **Check config** — compatibility_date, nodejs_compat, observability, secrets, binding-code consistency
+5. **Check patterns** — streaming, floating promises, global state, serialization boundaries
+6. **Check security** — crypto usage, secret handling, timing-safe comparisons, error handling
+7. **Validate with tools** — `npx tsc --noEmit`, lint for `no-floating-promises`
+8. **Reference rules** — see `references/rules.md` for each rule's correct pattern
+
+## Scope
+
+This skill covers Workers-specific best practices and code review. For related topics:
+
+- **Durable Objects**: load the `durable-objects` skill
+- **Workflows**: see [Rules of Workflows](https://developers.cloudflare.com/workflows/build/rules-of-workflows/)
+- **Wrangler CLI commands**: load the `wrangler` skill
+
+## Principles
+
+- **Be certain.** Retrieve before flagging. If unsure about an API, config field, or pattern, fetch the docs first.
+- **Provide evidence.** Reference line numbers, tool output, or docs links.
+- **Focus on what developers will copy.** Workers code in examples and docs gets pasted into production.
+- **Correctness over completeness.** A concise example that works beats a comprehensive one with errors.