@riligar/agents-kit 1.14.0 → 1.16.0

package/.agent/skills/riligar-infra-cloudfare/SKILL.md

@@ -0,0 +1,437 @@
+---
+name: riligar-infra-cloudfare
+description: "Setup domains in Cloudflare with DNS for Clerk, Vercel, and email routing. Use when adding new domains, configuring DNS records, or setting up email redirects."
+---
+
+# Cloudflare Setup
+
+Automate Cloudflare workflows: DNS setup, Clerk integration, Vercel deployment, email routing, and R2 storage.
+
+## Prerequisites
+
+### Authentication (Choose One)
+
+**Option 1: API Token (Recommended)**
+```bash
+# Add to .env.local
+CLOUDFLARE_API_TOKEN="your-api-token"
+CLOUDFLARE_ACCOUNT_ID="your-account-id"
+```
+
+Create token at: https://dash.cloudflare.com/profile/api-tokens
+Required permissions:
+- Zone:DNS:Edit
+- Zone:Zone:Read
+- Email Routing Addresses:Edit
+- Email Routing Rules:Edit
+- Account:R2:Edit (for R2 storage)
+
+**Option 2: Wrangler CLI**
+```bash
+# Install wrangler
+bun add -g wrangler
+
+# Login (opens browser)
+wrangler login
+
+# Verify
+wrangler whoami
+```
+
+### Other Tools
+```bash
+# Vercel CLI (required)
+bun add -g vercel
+vercel login
+```
+
+## Workflow
+
+When setting up a new domain, follow these steps:
+
+### Step 1: Gather Information
+
+Ask the user for:
+1. **Domain name** (e.g., `example.com`)
+2. **Clerk DNS records** (paste from Clerk dashboard)
+3. **Vercel project name** (e.g., `my-app`)
+4. **Email addresses** to create (e.g., `contact`, `support`)
+5. **Redirect target email** (e.g., `me@gmail.com`)
+
+### Step 2: Get Zone ID
+
+```bash
+# If using API token
+curl -X GET "https://api.cloudflare.com/client/v4/zones?name=DOMAIN" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  -H "Content-Type: application/json" | jq '.result[0].id'
+
+# If using wrangler
+wrangler pages project list  # Shows associated zones
+```
+
+### Step 3: Create DNS Records for Clerk
+
+Clerk provides specific DNS records for each project. Common patterns:
+
+```bash
+# Example: CNAME record
+curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "type": "CNAME",
+    "name": "clerk",
+    "content": "frontend-api.clerk.dev",
+    "ttl": 1,
+    "proxied": false
+  }'
+
+# Example: TXT record for verification
+curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "type": "TXT",
+    "name": "@",
+    "content": "clerk-verification=xxxxx",
+    "ttl": 1
+  }'
+```
+
+### Step 4: Add Domain to Vercel
+
+```bash
+# Add domain to Vercel project
+vercel domains add DOMAIN --scope=TEAM_SLUG
+
+# Or link to specific project
+vercel domains add DOMAIN PROJECT_NAME
+```
+
+Then create Vercel DNS records:
+
+```bash
+# A record for root domain
+curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "type": "A",
+    "name": "@",
+    "content": "76.76.21.21",
+    "ttl": 1,
+    "proxied": false
+  }'
+
+# CNAME for www subdomain
+curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "type": "CNAME",
+    "name": "www",
+    "content": "cname.vercel-dns.com",
+    "ttl": 1,
+    "proxied": false
+  }'
+```
+
+### Step 5: Setup Email Routing
+
+First, enable email routing for the zone (do this in Cloudflare dashboard first time).
+
+Then create routing rules:
+
+```bash
+# Create destination address (must be verified first)
+curl -X POST "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/email/routing/addresses" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "email": "your-main-email@gmail.com"
+  }'
+
+# Create routing rule for contact@domain.com
+curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/email/routing/rules" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "name": "Forward contact",
+    "enabled": true,
+    "matchers": [{"type": "literal", "field": "to", "value": "contact@DOMAIN"}],
+    "actions": [{"type": "forward", "value": ["your-main-email@gmail.com"]}]
+  }'
+```
+
+Required MX records for email routing:
+```bash
+# MX records for Cloudflare Email Routing
+curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "type": "MX",
+    "name": "@",
+    "content": "route1.mx.cloudflare.net",
+    "priority": 69,
+    "ttl": 1
+  }'
+
+curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "type": "MX",
+    "name": "@",
+    "content": "route2.mx.cloudflare.net",
+    "priority": 46,
+    "ttl": 1
+  }'
+
+curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "type": "MX",
+    "name": "@",
+    "content": "route3.mx.cloudflare.net",
+    "priority": 89,
+    "ttl": 1
+  }'
+
+# TXT record for SPF
+curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "type": "TXT",
+    "name": "@",
+    "content": "v=spf1 include:_spf.mx.cloudflare.net ~all",
+    "ttl": 1
+  }'
+```
+
+### Step 6: Verification Checklist
+
+After setup, verify:
+
+```bash
+# List all DNS records
+curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" | jq '.result[] | {type, name, content}'
+
+# Check Vercel domain status
+vercel domains inspect DOMAIN
+
+# Test email routing (send test email to contact@DOMAIN)
+```
+
+## Interactive Prompts Template
+
+When running `/cloudflare`, ask:
+
+```
+What domain are you setting up?
+> example.com
+
+Paste the Clerk DNS records from your Clerk dashboard:
+> [user pastes records]
+
+What's the Vercel project name?
+> my-saas-app
+
+What email addresses should I create? (comma-separated)
+> contact, support, hello
+
+What email should these redirect to?
+> myemail@gmail.com
+```
+
+## Common DNS Record Types
+
+| Type | Use Case | Proxied |
+|------|----------|---------|
+| A | Root domain to IP | No (for Vercel) |
+| CNAME | Subdomain to hostname | No (for Clerk/Vercel) |
+| TXT | Verification, SPF | N/A |
+| MX | Email routing | N/A |
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Zone not found | Domain must be added to Cloudflare first |
+| DNS propagation slow | Wait 5-10 minutes, check with `dig` |
+| Email not forwarding | Verify destination email first |
+| Vercel 404 | Check DNS proxied=false for Vercel records |
+| Clerk verification failed | Ensure TXT record is on root (@) |
+
+## Useful Commands
+
+```bash
+# Check DNS propagation
+dig DOMAIN +short
+dig DOMAIN MX +short
+dig DOMAIN TXT +short
+
+# List zones in account
+curl -X GET "https://api.cloudflare.com/client/v4/zones" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" | jq '.result[] | {name, id}'
+
+# Delete a DNS record
+curl -X DELETE "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records/RECORD_ID" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+```
+
+---
+
+# R2 Storage Setup
+
+Setup R2 buckets for file storage: user uploads, static assets, backups.
+
+## R2 Workflow
+
+### Step 1: Determine Use Case
+
+Ask the user:
+```
+What do you want to do with R2?
+1. Create new bucket (full setup)
+2. Configure existing bucket (CORS, public access)
+3. Setup custom domain for bucket
+```
+
+### Step 2: Gather Bucket Info
+
+```
+Bucket name?
+> my-app-uploads
+
+What will this bucket store?
+1. User uploads (images, files) - needs CORS + presigned URLs
+2. Static assets (public CDN) - needs public access
+3. Backups (private) - no public access
+> 1
+
+Custom domain? (optional, press enter to skip)
+> uploads.myapp.com
+```
+
+### Step 3: Create Bucket
+
+```bash
+# Create bucket via wrangler
+wrangler r2 bucket create my-app-uploads
+
+# Or via API
+curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/r2/buckets" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{"name": "my-app-uploads", "locationHint": "wnam"}'
+```
+
+### Step 4: Configure CORS (for user uploads)
+
+Create `cors.json`:
+```json
+{
+  "corsRules": [
+    {
+      "allowedOrigins": ["https://myapp.com", "http://localhost:3000"],
+      "allowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
+      "allowedHeaders": ["*"],
+      "exposeHeaders": ["ETag", "Content-Length"],
+      "maxAgeSeconds": 3600
+    }
+  ]
+}
+```
+
+Apply CORS:
+```bash
+wrangler r2 bucket cors put my-app-uploads --file=cors.json
+```
+
+### Step 5: Setup Public Access (for static assets)
+
+Option A: Enable R2.dev subdomain (via dashboard)
+- Go to R2 > Bucket > Settings > Public access
+
+Option B: Custom domain:
+```bash
+# Add CNAME record
+curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "type": "CNAME",
+    "name": "uploads",
+    "content": "{account_id}.r2.cloudflarestorage.com",
+    "ttl": 1,
+    "proxied": true
+  }'
+```
+
+Then enable custom domain in R2 bucket settings.
+
+### Step 6: Generate S3 API Credentials (for SDK access)
+
+1. Go to R2 > Manage R2 API Tokens
+2. Create token with Object Read & Write
+3. Add to `.env.local`:
+
+```bash
+R2_ACCESS_KEY_ID="your-access-key"
+R2_SECRET_ACCESS_KEY="your-secret-key"
+R2_ENDPOINT="https://{account_id}.r2.cloudflarestorage.com"
+R2_BUCKET_NAME="my-app-uploads"
+```
+
+## R2 Quick Commands
+
+```bash
+# List buckets
+wrangler r2 bucket list
+
+# Create bucket
+wrangler r2 bucket create BUCKET_NAME
+
+# Delete bucket
+wrangler r2 bucket delete BUCKET_NAME
+
+# List objects
+wrangler r2 object list BUCKET_NAME
+
+# Upload file
+wrangler r2 object put BUCKET_NAME/path/file.png --file=./local.png
+
+# View CORS config
+wrangler r2 bucket cors get BUCKET_NAME
+```
+
+## R2 Use Case Presets
+
+| Use Case | CORS | Public | Custom Domain |
+|----------|------|--------|---------------|
+| User uploads | Yes | No | Optional |
+| Static assets/CDN | No | Yes | Recommended |
+| Backups | No | No | No |
+| Public downloads | No | Yes | Optional |
+
+## R2 Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| CORS error in browser | Add domain to allowedOrigins |
+| 403 Forbidden | Check API token has R2:Edit permission |
+| Custom domain not working | Ensure CNAME is proxied (orange cloud) |
+| Upload fails | Verify Content-Type header matches file |
+
+---
+
+## References
+
+- **[Cloudflare API Reference](references/cloudflare-api.md)**: Auth tokens, zone operations, DNS endpoints
+- **[Email Routing](references/email-routing.md)**: Email forwarding setup and configuration
+- **[R2 Storage](references/r2-storage.md)**: Bucket management, CORS, presigned URLs

package/.agent/skills/riligar-infra-cloudfare/references/cloudflare-api.md

@@ -0,0 +1,139 @@
+# Cloudflare API Reference
+
+## Authentication
+
+### API Token (Recommended)
+```bash
+# Header format
+-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+```
+
+Create at: https://dash.cloudflare.com/profile/api-tokens
+
+Required permissions:
+- **Zone:DNS:Edit** - Create/modify DNS records
+- **Zone:Zone:Read** - List and read zone info
+- **Account:Email Routing Addresses:Edit** - Manage destination emails
+- **Zone:Email Routing Rules:Edit** - Create routing rules
+
+### Global API Key (Legacy)
+```bash
+-H "X-Auth-Email: your@email.com"
+-H "X-Auth-Key: your-global-api-key"
+```
+
+## Base URL
+```
+https://api.cloudflare.com/client/v4
+```
+
+## Zone Operations
+
+### List Zones
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/zones" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  -H "Content-Type: application/json"
+```
+
+### Get Zone by Domain
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/zones?name=example.com" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+```
+
+Response:
+```json
+{
+  "result": [{
+    "id": "zone-id-here",
+    "name": "example.com",
+    "status": "active"
+  }]
+}
+```
+
+## DNS Record Operations
+
+### List DNS Records
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+```
+
+### Create DNS Record
+```bash
+curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "type": "A",
+    "name": "@",
+    "content": "192.0.2.1",
+    "ttl": 1,
+    "proxied": false
+  }'
+```
+
+### Record Types
+
+| Type | Fields | Example Content |
+|------|--------|-----------------|
+| A | name, content, ttl, proxied | `192.0.2.1` |
+| AAAA | name, content, ttl, proxied | `2001:db8::1` |
+| CNAME | name, content, ttl, proxied | `target.example.com` |
+| TXT | name, content, ttl | `v=spf1 include:...` |
+| MX | name, content, priority, ttl | `mail.example.com` |
+
+### Special Name Values
+- `@` - Root domain
+- `*` - Wildcard
+- `subdomain` - Specific subdomain
+
+### TTL Values
+- `1` - Automatic (recommended)
+- `60` - 1 minute
+- `3600` - 1 hour
+- `86400` - 1 day
+
+### Update DNS Record
+```bash
+curl -X PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records/{record_id}" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "content": "new-value"
+  }'
+```
+
+### Delete DNS Record
+```bash
+curl -X DELETE "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records/{record_id}" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+```
+
+## Error Handling
+
+### Response Format
+```json
+{
+  "success": true,
+  "errors": [],
+  "messages": [],
+  "result": { ... }
+}
+```
+
+### Common Errors
+
+| Code | Message | Solution |
+|------|---------|----------|
+| 9109 | Invalid access token | Check token permissions |
+| 81057 | Record already exists | Delete or update existing |
+| 1004 | DNS validation error | Check record format |
+
+## Rate Limits
+
+- 1200 requests per 5 minutes per user
+- Applies across all API endpoints
+- Returns `429 Too Many Requests` when exceeded