codexkit 1.0.0

package/.codex/skills/cloudflare/references/terraform/api.md

@@ -0,0 +1,159 @@
+# Terraform Data Sources Reference
+
+Query existing Cloudflare resources to reference in your configurations.
+
+## Zone Data Sources
+
+```hcl
+# Get zone by name
+data "cloudflare_zone" "example" {
+  name = "example.com"
+}
+
+# Use in resources
+resource "cloudflare_dns_record" "www" {
+  zone_id = data.cloudflare_zone.example.id
+  name = "www"
+  # ...
+}
+```
+
+## Account Data Sources
+
+```hcl
+# List all accounts
+data "cloudflare_accounts" "main" {
+  name = "My Account"
+}
+
+# Use account ID
+resource "cloudflare_worker_script" "api" {
+  account_id = data.cloudflare_accounts.main.accounts[0].id
+  # ...
+}
+```
+
+## Worker Data Sources
+
+```hcl
+# Get existing worker script
+data "cloudflare_worker_script" "existing" {
+  account_id = var.account_id
+  name = "existing-worker"
+}
+
+# Reference in service bindings
+resource "cloudflare_worker_script" "consumer" {
+  service_binding {
+    name = "UPSTREAM"
+    service = data.cloudflare_worker_script.existing.name
+  }
+}
+```
+
+## KV Data Sources
+
+```hcl
+# Get KV namespace
+data "cloudflare_workers_kv_namespace" "existing" {
+  account_id = var.account_id
+  namespace_id = "abc123"
+}
+
+# Use in worker binding
+resource "cloudflare_worker_script" "api" {
+  kv_namespace_binding {
+    name = "KV"
+    namespace_id = data.cloudflare_workers_kv_namespace.existing.id
+  }
+}
+```
+
+## IP Ranges Data Source
+
+```hcl
+# Get Cloudflare IP ranges (for firewall rules)
+data "cloudflare_ip_ranges" "cloudflare" {}
+
+output "ipv4_cidrs" {
+  value = data.cloudflare_ip_ranges.cloudflare.ipv4_cidr_blocks
+}
+
+output "ipv6_cidrs" {
+  value = data.cloudflare_ip_ranges.cloudflare.ipv6_cidr_blocks
+}
+
+# Use in security group rules (AWS example)
+resource "aws_security_group_rule" "allow_cloudflare" {
+  type = "ingress"
+  from_port = 443
+  to_port = 443
+  protocol = "tcp"
+  cidr_blocks = data.cloudflare_ip_ranges.cloudflare.ipv4_cidr_blocks
+  security_group_id = aws_security_group.web.id
+}
+```
+
+## Common Patterns
+
+### Import Existing Resources
+
+```bash
+# Find zone ID in dashboard
+terraform import cloudflare_zone.example <zone-id>
+
+# Import DNS record
+terraform import cloudflare_dns_record.example <zone-id>/<record-id>
+
+# Import worker script
+terraform import cloudflare_worker_script.api <account-id>/<script-name>
+
+# Import KV namespace
+terraform import cloudflare_workers_kv_namespace.cache <account-id>/<namespace-id>
+```
+
+### Reference Across Modules
+
+```hcl
+# modules/worker/main.tf
+data "cloudflare_zone" "main" {
+  name = var.domain
+}
+
+resource "cloudflare_worker_route" "api" {
+  zone_id = data.cloudflare_zone.main.id
+  pattern = "api.${var.domain}/*"
+  script_name = cloudflare_worker_script.api.name
+}
+```
+
+### Output Important Values
+
+```hcl
+output "zone_id" {
+  value = cloudflare_zone.main.id
+  description = "Zone ID for DNS management"
+}
+
+output "worker_url" {
+  value = "https://${cloudflare_worker_domain.api.hostname}"
+  description = "Worker API endpoint"
+}
+
+output "kv_namespace_id" {
+  value = cloudflare_workers_kv_namespace.app.id
+  sensitive = false
+}
+
+output "name_servers" {
+  value = cloudflare_zone.main.name_servers
+  description = "Name servers for domain registration"
+}
+```
+
+## See Also
+
+- [README](./README.md) - Provider setup
+- [Configuration Reference](./configuration.md) - All resource types
+- [Patterns](./patterns.md) - Architecture patterns
+- [Troubleshooting](./gotchas.md) - Common issues

package/.codex/skills/cloudflare/references/terraform/configuration.md

@@ -0,0 +1,156 @@
+# Terraform Configuration Reference
+
+Complete resource configurations for Cloudflare infrastructure.
+
+## Zone & DNS
+
+```hcl
+# Zone + settings
+resource "cloudflare_zone" "example" { account = { id = var.account_id }; name = "example.com"; type = "full" }
+resource "cloudflare_zone_settings_override" "example" {
+  zone_id = cloudflare_zone.example.id
+  settings { ssl = "strict"; always_use_https = "on"; min_tls_version = "1.2"; tls_1_3 = "on"; http3 = "on" }
+}
+
+# DNS records (A, CNAME, MX, TXT)
+resource "cloudflare_dns_record" "www" {
+  zone_id = cloudflare_zone.example.id; name = "www"; content = "192.0.2.1"; type = "A"; proxied = true
+}
+resource "cloudflare_dns_record" "mx" {
+  for_each = { "10" = "mail1.example.com", "20" = "mail2.example.com" }
+  zone_id = cloudflare_zone.example.id; name = "@"; content = each.value; type = "MX"; priority = each.key
+}
+```
+
+## Workers
+
+```hcl
+# Worker with bindings
+resource "cloudflare_worker_script" "api" {
+  account_id = var.account_id; name = "api-worker"; content = file("worker.js"); module = true
+  compatibility_date = "2025-01-01"
+  kv_namespace_binding { name = "KV"; namespace_id = cloudflare_workers_kv_namespace.cache.id }
+  r2_bucket_binding { name = "BUCKET"; bucket_name = cloudflare_r2_bucket.assets.name }
+  d1_database_binding { name = "DB"; database_id = cloudflare_d1_database.app.id }
+  service_binding { name = "AUTH"; service = "auth-worker" }
+  secret_text_binding { name = "SECRET"; text = var.secret }
+}
+
+# Routes & domains
+resource "cloudflare_worker_route" "api" {
+  zone_id = cloudflare_zone.example.id; pattern = "api.example.com/*"; script_name = cloudflare_worker_script.api.name
+}
+resource "cloudflare_worker_cron_trigger" "task" {
+  account_id = var.account_id; script_name = cloudflare_worker_script.api.name
+  schedules = ["*/5 * * * *"]  # Every 5min
+}
+```
+
+## Storage (KV, R2, D1)
+
+```hcl
+# KV
+resource "cloudflare_workers_kv_namespace" "cache" { account_id = var.account_id; title = "cache" }
+resource "cloudflare_workers_kv" "config" {
+  account_id = var.account_id; namespace_id = cloudflare_workers_kv_namespace.cache.id
+  key_name = "config"; value = jsonencode({ version = "1.0" })
+}
+
+# R2
+resource "cloudflare_r2_bucket" "assets" { account_id = var.account_id; name = "assets"; location = "WNAM" }
+
+# D1 (schema migrations via wrangler)
+resource "cloudflare_d1_database" "app" { account_id = var.account_id; name = "app-db" }
+```
+
+## Pages
+
+```hcl
+resource "cloudflare_pages_project" "site" {
+  account_id = var.account_id; name = "site"; production_branch = "main"
+  deployment_configs {
+    production {
+      compatibility_date = "2025-01-01"
+      environment_variables = { NODE_ENV = "production" }
+      kv_namespaces = { KV = cloudflare_workers_kv_namespace.cache.id }
+      d1_databases = { DB = cloudflare_d1_database.app.id }
+    }
+  }
+  build_config { build_command = "npm run build"; destination_dir = "dist" }
+  source { type = "github"; config { owner = "org"; repo_name = "site"; production_branch = "main" }}
+}
+
+resource "cloudflare_pages_domain" "custom" {
+  account_id = var.account_id; project_name = cloudflare_pages_project.site.name; domain = "site.example.com"
+}
+```
+
+## Rulesets (WAF, Redirects, Cache)
+
+```hcl
+# WAF
+resource "cloudflare_ruleset" "waf" {
+  zone_id = cloudflare_zone.example.id; name = "WAF"; kind = "zone"; phase = "http_request_firewall_custom"
+  rules { action = "block"; enabled = true; expression = "(cf.client.bot) and not (cf.verified_bot)" }
+}
+
+# Redirects
+resource "cloudflare_ruleset" "redirects" {
+  zone_id = cloudflare_zone.example.id; name = "Redirects"; kind = "zone"; phase = "http_request_dynamic_redirect"
+  rules {
+    action = "redirect"; enabled = true; expression = "(http.request.uri.path eq \"/old\")"
+    action_parameters { from_value { status_code = 301; target_url { value = "https://example.com/new" }}}
+  }
+}
+
+# Cache rules
+resource "cloudflare_ruleset" "cache" {
+  zone_id = cloudflare_zone.example.id; name = "Cache"; kind = "zone"; phase = "http_request_cache_settings"
+  rules {
+    action = "set_cache_settings"; enabled = true; expression = "(http.request.uri.path matches \"\\.(jpg|png|css|js)$\")"
+    action_parameters { cache = true; edge_ttl { mode = "override_origin"; default = 86400 }}
+  }
+}
+```
+
+## Load Balancers
+
+```hcl
+resource "cloudflare_load_balancer_monitor" "http" {
+  account_id = var.account_id; type = "http"; path = "/health"; interval = 60; timeout = 5
+}
+resource "cloudflare_load_balancer_pool" "api" {
+  account_id = var.account_id; name = "api-pool"; monitor = cloudflare_load_balancer_monitor.http.id
+  origins { name = "api-1"; address = "192.0.2.1" }
+  origins { name = "api-2"; address = "192.0.2.2" }
+}
+resource "cloudflare_load_balancer" "api" {
+  zone_id = cloudflare_zone.example.id; name = "api.example.com"
+  default_pool_ids = [cloudflare_load_balancer_pool.api.id]; steering_policy = "geo"
+}
+```
+
+## Access (Zero Trust)
+
+```hcl
+resource "cloudflare_access_application" "admin" {
+  account_id = var.account_id; name = "Admin"; domain = "admin.example.com"; type = "self_hosted"
+  session_duration = "24h"; allowed_idps = [cloudflare_access_identity_provider.github.id]
+}
+resource "cloudflare_access_policy" "allow" {
+  account_id = var.account_id; application_id = cloudflare_access_application.admin.id
+  name = "Allow"; decision = "allow"; precedence = 1
+  include { email = ["admin@example.com"] }
+}
+resource "cloudflare_access_identity_provider" "github" {
+  account_id = var.account_id; name = "GitHub"; type = "github"
+  config { client_id = var.github_id; client_secret = var.github_secret }
+}
+```
+
+## See Also
+
+- [README](./README.md) - Provider setup
+- [API](./api.md) - Data sources
+- [Patterns](./patterns.md) - Use cases
+- [Troubleshooting](./gotchas.md) - Issues

package/.codex/skills/cloudflare/references/terraform/gotchas.md

@@ -0,0 +1,207 @@
+# Terraform Troubleshooting & Best Practices
+
+Common issues, security considerations, and best practices.
+
+## Common Errors
+
+### "Error: couldn't find resource"
+
+**Cause**: Resource deleted outside Terraform  
+**Solution**:
+```bash
+terraform import cloudflare_zone.example <zone-id>
+# Or remove from state:
+terraform state rm cloudflare_zone.example
+```
+
+### "409 Conflict" on worker deployment
+
+**Cause**: Worker deployed by both Terraform and wrangler  
+**Solution**: Choose one deployment method. If using Terraform, remove wrangler deployments.
+
+### DNS record already exists
+
+**Cause**: Existing record not imported into Terraform  
+**Solution**:
+```bash
+# Find record ID in Cloudflare dashboard
+terraform import cloudflare_dns_record.example <zone-id>/<record-id>
+```
+
+### "Invalid provider configuration"
+
+**Cause**: API token missing or invalid  
+**Solution**:
+```bash
+export CLOUDFLARE_API_TOKEN="your-token"
+# Or check token permissions in dashboard
+```
+
+### State locking errors
+
+**Cause**: Multiple Terraform runs or stale lock  
+**Solution**:
+```bash
+# Remove stale lock (with caution!)
+terraform force-unlock <lock-id>
+```
+
+## Best Practices
+
+### 1. Resource Naming
+
+```hcl
+# Good: Consistent naming with environment
+locals { env_prefix = "${var.environment}-${var.project_name}" }
+
+resource "cloudflare_worker_script" "api" { name = "${local.env_prefix}-api" }
+resource "cloudflare_workers_kv_namespace" "cache" { title = "${local.env_prefix}-cache" }
+```
+
+### 2. Output Important Values
+
+```hcl
+output "zone_id" { value = cloudflare_zone.main.id; description = "Zone ID for DNS management" }
+output "worker_url" { value = "https://${cloudflare_worker_domain.api.hostname}"; description = "Worker API endpoint" }
+output "kv_namespace_id" { value = cloudflare_workers_kv_namespace.app.id; sensitive = false }
+```
+
+### 3. Use Data Sources for Existing Resources
+
+```hcl
+# Reference existing zone
+data "cloudflare_zone" "main" { name = var.domain }
+
+# Reference existing account
+data "cloudflare_accounts" "main" { name = var.account_name }
+
+# Use in resources
+resource "cloudflare_worker_route" "api" {
+  zone_id = data.cloudflare_zone.main.id
+  # ...
+}
+```
+
+### 4. Separate Secrets from Code
+
+```hcl
+# variables.tf
+variable "cloudflare_api_token" {
+  type = string; sensitive = true; description = "Cloudflare API token"
+}
+
+# terraform.tfvars (gitignored)
+cloudflare_api_token = "actual-token-here"
+
+# Or use environment variables
+# export TF_VAR_cloudflare_api_token="actual-token-here"
+```
+
+### 5. Use Separate Directories per Environment (RECOMMENDED)
+
+```
+environments/
+  production/    # Separate state, separate vars
+  staging/
+  development/
+```
+
+Better than workspaces for isolation and clarity.
+
+### 6. Version Control State Locking
+
+```hcl
+# S3 backend with DynamoDB locking
+terraform {
+  backend "s3" {
+    bucket = "terraform-state"; key = "cloudflare/terraform.tfstate"; region = "us-east-1"
+    dynamodb_table = "terraform-locks"; encrypt = true
+  }
+}
+```
+
+## Security Considerations
+
+1. **Never commit secrets**: Use variables + environment vars or secret management tools
+2. **Scope API tokens**: Create tokens with minimal required permissions
+3. **Enable state encryption**: Use encrypted S3 backend or Terraform Cloud
+4. **Use separate tokens per environment**: Different tokens for prod/staging
+5. **Rotate tokens regularly**: Update tokens in CI/CD systems
+6. **Review terraform plans**: Always review before applying
+7. **Use Access for sensitive applications**: Don't expose admin panels publicly
+
+## Common Commands Reference
+
+```bash
+terraform init                    # Initialize provider
+terraform plan                    # Plan changes
+terraform apply                   # Apply changes
+terraform apply -auto-approve     # Apply without confirmation
+terraform destroy                 # Destroy resources
+terraform import cloudflare_zone.example <zone-id>  # Import existing
+terraform show                    # Show current state
+terraform state list              # List resources in state
+terraform state rm cloudflare_zone.example  # Remove from state (no destroy)
+terraform refresh                 # Refresh state from infrastructure
+terraform fmt -recursive          # Format code
+terraform validate                # Validate configuration
+terraform output                  # Show outputs
+terraform output zone_id          # Show specific output
+```
+
+## Workspace Management
+
+```bash
+# Create workspace
+terraform workspace new production
+
+# List workspaces
+terraform workspace list
+
+# Switch workspace
+terraform workspace select staging
+
+# Note: Separate directories recommended over workspaces for production
+```
+
+## State Management
+
+```bash
+# List state resources
+terraform state list
+
+# Show resource details
+terraform state show cloudflare_zone.example
+
+# Move resource in state
+terraform state mv cloudflare_zone.old cloudflare_zone.new
+
+# Remove from state (no destroy)
+terraform state rm cloudflare_zone.example
+
+# Pull state to local file
+terraform state pull > terraform.tfstate.backup
+
+# Push state from local file
+terraform state push terraform.tfstate
+```
+
+## Limits
+
+| Resource | Limit | Notes |
+|----------|-------|-------|
+| API token rate limit | Varies by plan | Use `api_client_logging = true` to debug
+| Worker script size | 10 MB | Includes all dependencies
+| KV keys per namespace | Unlimited | Pay per operation
+| R2 storage | Unlimited | Pay per GB
+| D1 databases | 50,000 per account | Free tier: 10
+| Pages projects | 500 per account | 100 for free accounts
+| DNS records | 3,500 per zone | Free plan
+
+## See Also
+
+- [README](./README.md) - Provider setup
+- [Configuration](./configuration.md) - Resources
+- [API](./api.md) - Data sources
+- [Patterns](./patterns.md) - Use cases
+- Provider docs: https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs

package/.codex/skills/cloudflare/references/terraform/patterns.md

@@ -0,0 +1,135 @@
+# Terraform Patterns & Use Cases
+
+Architecture patterns, multi-environment setups, and real-world use cases.
+
+## Multi-Environment Setup
+
+```hcl
+# Directory: environments/{production,staging}/main.tf + modules/{zone,worker,pages}
+module "zone" {
+  source = "../../modules/zone"; account_id = var.account_id; zone_name = "example.com"; environment = "production"
+}
+module "api_worker" {
+  source = "../../modules/worker"; account_id = var.account_id; zone_id = module.zone.zone_id
+  name = "api-worker-prod"; script = file("../../workers/api.js"); environment = "production"
+}
+```
+
+## Worker with All Bindings
+
+```hcl
+locals { worker_name = "full-stack-worker" }
+resource "cloudflare_workers_kv_namespace" "app" { account_id = var.account_id; title = "${local.worker_name}-kv" }
+resource "cloudflare_r2_bucket" "app" { account_id = var.account_id; name = "${local.worker_name}-bucket" }
+resource "cloudflare_d1_database" "app" { account_id = var.account_id; name = "${local.worker_name}-db" }
+
+resource "cloudflare_worker_script" "app" {
+  account_id = var.account_id; name = local.worker_name; content = file("worker.js"); module = true
+  compatibility_date = "2025-01-01"
+  kv_namespace_binding { name = "KV"; namespace_id = cloudflare_workers_kv_namespace.app.id }
+  r2_bucket_binding { name = "BUCKET"; bucket_name = cloudflare_r2_bucket.app.name }
+  d1_database_binding { name = "DB"; database_id = cloudflare_d1_database.app.id }
+  secret_text_binding { name = "API_KEY"; text = var.api_key }
+}
+```
+
+## Wrangler Integration
+
+**CRITICAL**: Wrangler and Terraform must NOT manage same resources.
+
+**Terraform**: Zones, DNS, security rules, Access, load balancers, worker deployments (CI/CD), KV/R2/D1 resource creation  
+**Wrangler**: Local dev (`wrangler dev`), manual deploys, D1 migrations, KV bulk ops, log streaming (`wrangler tail`)
+
+### CI/CD Pattern
+
+```hcl
+# Terraform creates infrastructure
+resource "cloudflare_workers_kv_namespace" "app" { account_id = var.account_id; title = "app-kv" }
+resource "cloudflare_d1_database" "app" { account_id = var.account_id; name = "app-db" }
+output "kv_namespace_id" { value = cloudflare_workers_kv_namespace.app.id }
+output "d1_database_id" { value = cloudflare_d1_database.app.id }
+```
+
+```yaml
+# GitHub Actions: terraform apply → envsubst wrangler.jsonc.template → wrangler deploy
+- run: terraform apply -auto-approve
+- run: |
+    export KV_NAMESPACE_ID=$(terraform output -raw kv_namespace_id)
+    envsubst < wrangler.jsonc.template > wrangler.jsonc
+- run: wrangler deploy
+```
+
+## Use Cases
+
+### Static Site + API Worker
+
+```hcl
+resource "cloudflare_pages_project" "frontend" {
+  account_id = var.account_id; name = "frontend"; production_branch = "main"
+  build_config { build_command = "npm run build"; destination_dir = "dist" }
+}
+resource "cloudflare_worker_script" "api" {
+  account_id = var.account_id; name = "api"; content = file("api-worker.js")
+  d1_database_binding { name = "DB"; database_id = cloudflare_d1_database.api_db.id }
+}
+resource "cloudflare_dns_record" "frontend" {
+  zone_id = cloudflare_zone.main.id; name = "app"; content = cloudflare_pages_project.frontend.subdomain; type = "CNAME"; proxied = true
+}
+resource "cloudflare_worker_route" "api" {
+  zone_id = cloudflare_zone.main.id; pattern = "api.example.com/*"; script_name = cloudflare_worker_script.api.name
+}
+```
+
+### Multi-Region Load Balancing
+
+```hcl
+resource "cloudflare_load_balancer_pool" "us" {
+  account_id = var.account_id; name = "us-pool"; monitor = cloudflare_load_balancer_monitor.http.id
+  origins { name = "us-east"; address = var.us_east_ip }
+}
+resource "cloudflare_load_balancer_pool" "eu" {
+  account_id = var.account_id; name = "eu-pool"; monitor = cloudflare_load_balancer_monitor.http.id
+  origins { name = "eu-west"; address = var.eu_west_ip }
+}
+resource "cloudflare_load_balancer" "global" {
+  zone_id = cloudflare_zone.main.id; name = "api.example.com"; steering_policy = "geo"
+  default_pool_ids = [cloudflare_load_balancer_pool.us.id]
+  region_pools { region = "WNAM"; pool_ids = [cloudflare_load_balancer_pool.us.id] }
+  region_pools { region = "WEU"; pool_ids = [cloudflare_load_balancer_pool.eu.id] }
+}
+```
+
+### Secure Admin with Access
+
+```hcl
+resource "cloudflare_pages_project" "admin" { account_id = var.account_id; name = "admin"; production_branch = "main" }
+resource "cloudflare_access_application" "admin" {
+  account_id = var.account_id; name = "Admin"; domain = "admin.example.com"; type = "self_hosted"; session_duration = "24h"
+  allowed_idps = [cloudflare_access_identity_provider.google.id]
+}
+resource "cloudflare_access_policy" "allow" {
+  account_id = var.account_id; application_id = cloudflare_access_application.admin.id
+  name = "Allow admins"; decision = "allow"; precedence = 1; include { email = var.admin_emails }
+}
+```
+
+### Reusable Module
+
+```hcl
+# modules/cloudflare-zone/main.tf
+variable "account_id" { type = string }; variable "domain" { type = string }; variable "ssl_mode" { default = "strict" }
+resource "cloudflare_zone" "main" { account = { id = var.account_id }; name = var.domain }
+resource "cloudflare_zone_settings_override" "main" {
+  zone_id = cloudflare_zone.main.id; settings { ssl = var.ssl_mode; always_use_https = "on" }
+}
+output "zone_id" { value = cloudflare_zone.main.id }
+
+# Usage: module "prod" { source = "./modules/cloudflare-zone"; account_id = var.account_id; domain = "example.com" }
+```
+
+## See Also
+
+- [README](./README.md) - Provider setup
+- [Configuration Reference](./configuration.md) - All resource types
+- [API Reference](./api.md) - Data sources
+- [Troubleshooting](./gotchas.md) - Best practices, common issues