opencodekit 0.15.4 → 0.15.5

package/dist/template/.opencode/skill/cloudflare/references/pages/api.md

@@ -0,0 +1,200 @@
+# Functions API
+
+## File-Based Routing
+
+```
+/functions
+  /index.ts                    → example.com/
+  /api
+    /users.ts                  → example.com/api/users
+    /users
+      /[id].ts                 → example.com/api/users/:id
+      /[[catchall]].ts         → example.com/api/users/*
+  /_middleware.ts              → Runs before all routes
+```
+
+**Rules**: `[param]` = single segment, `[[param]]` = multi-segment wildcard, more specific wins, falls back to static assets.
+
+## Request Handlers
+
+```typescript
+import type { PagesFunction } from '@cloudflare/workers-types';
+
+interface Env {
+  DB: D1Database;
+  KV: KVNamespace;
+}
+
+// All methods
+export const onRequest: PagesFunction<Env> = async (context) => {
+  return new Response('All methods');
+};
+
+// Method-specific
+export const onRequestGet: PagesFunction<Env> = async (context) => {
+  const { request, env, params, data } = context;
+  
+  const user = await env.DB.prepare(
+    'SELECT * FROM users WHERE id = ?'
+  ).bind(params.id).first();
+  
+  return Response.json(user);
+};
+
+export const onRequestPost: PagesFunction<Env> = async (context) => {
+  const body = await context.request.json();
+  return Response.json({ success: true });
+};
+
+// Also: onRequestPut, onRequestPatch, onRequestDelete, onRequestHead, onRequestOptions
+```
+
+## Context Object
+
+```typescript
+interface EventContext<Env, Params, Data> {
+  request: Request;              // Incoming HTTP request
+  env: Env;                      // Bindings (KV, D1, R2, etc.)
+  params: Params;                // Dynamic route parameters
+  data: Data;                    // Shared data from middleware
+  functionPath: string;          // Current function path
+  waitUntil: (promise: Promise<any>) => void;  // Background tasks
+  next: (input?: RequestInfo, init?: RequestInit) => Promise<Response>;
+  passThroughOnException: () => void;  // Fallback on error (not in advanced mode)
+}
+```
+
+## Dynamic Routes
+
+### Single Segment
+```typescript
+// functions/users/[id].ts
+export const onRequestGet: PagesFunction = async ({ params }) => {
+  // /users/123 → params.id = "123"
+  return Response.json({ userId: params.id });
+};
+```
+
+### Multi-Segment
+```typescript
+// functions/files/[[path]].ts
+export const onRequestGet: PagesFunction = async ({ params }) => {
+  // /files/docs/api/v1.md → params.path = ["docs", "api", "v1.md"]
+  const filePath = (params.path as string[]).join('/');
+  return new Response(filePath);
+};
+```
+
+## Middleware
+
+```typescript
+// functions/_middleware.ts
+import type { PagesFunction } from '@cloudflare/workers-types';
+
+// Single
+export const onRequest: PagesFunction = async (context) => {
+  const response = await context.next();
+  response.headers.set('X-Custom-Header', 'value');
+  return response;
+};
+
+// Chained (runs in order)
+const errorHandler: PagesFunction = async (context) => {
+  try {
+    return await context.next();
+  } catch (err) {
+    return new Response(err.message, { status: 500 });
+  }
+};
+
+const auth: PagesFunction = async (context) => {
+  const token = context.request.headers.get('Authorization');
+  if (!token) return new Response('Unauthorized', { status: 401 });
+  
+  context.data.userId = await verifyToken(token);
+  return context.next();
+};
+
+export const onRequest = [errorHandler, auth];
+```
+
+**Scope**:
+- `functions/_middleware.ts` → ALL requests (including static)
+- `functions/api/_middleware.ts` → `/api/*` only
+
+## Bindings Usage
+
+```typescript
+export const onRequestGet: PagesFunction<Env> = async ({ env, request }) => {
+  // KV
+  const cached = await env.KV.get('key', 'json');
+  await env.KV.put('key', JSON.stringify({ data: 'value' }), {
+    expirationTtl: 3600
+  });
+  
+  // D1
+  const result = await env.DB.prepare(
+    'SELECT * FROM users WHERE id = ?'
+  ).bind(userId).first();
+  
+  // R2
+  const object = await env.BUCKET.get('file.txt');
+  const content = await object?.text();
+  
+  // Queue
+  await env.QUEUE.send({ event: 'user.signup', userId: 123 });
+  
+  // AI
+  const aiResponse = await env.AI.run('@cf/meta/llama-2-7b-chat-int8', {
+    prompt: 'Hello world'
+  });
+  
+  return Response.json({ success: true });
+};
+```
+
+## Advanced Mode
+
+Full Workers API, bypasses file-based routing:
+
+```javascript
+// functions/_worker.js
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+    
+    // Custom routing
+    if (url.pathname.startsWith('/api/')) {
+      return new Response('API response');
+    }
+    
+    // REQUIRED: Serve static assets
+    return env.ASSETS.fetch(request);
+  }
+};
+```
+
+**When to use**: WebSockets, complex routing, scheduled handlers, email handlers.
+
+## getRequestContext (Framework SSR)
+
+Access bindings in framework code (Next.js, SvelteKit, etc.):
+
+```typescript
+import { getRequestContext } from '@cloudflare/next-on-pages';
+
+export async function GET(request: Request) {
+  const { env, cf, ctx } = getRequestContext();
+  
+  const data = await env.DB.prepare(
+    'SELECT * FROM users'
+  ).all();
+  
+  return Response.json(data);
+}
+```
+
+**Note**: Adapter-specific. Check framework docs:
+- Next.js: `@cloudflare/next-on-pages`
+- SvelteKit: `@sveltejs/adapter-cloudflare`
+- Remix: `@remix-run/cloudflare-pages`

package/dist/template/.opencode/skill/cloudflare/references/pages/configuration.md

@@ -0,0 +1,228 @@
+# Configuration
+
+## wrangler.toml
+
+```toml
+name = "my-pages-project"
+pages_build_output_dir = "./dist"
+compatibility_date = "2024-01-01"
+compatibility_flags = ["nodejs_compat"]
+
+# Bindings
+[[kv_namespaces]]
+binding = "KV"
+id = "abcd1234..."
+
+[[d1_databases]]
+binding = "DB"
+database_id = "xxxx-xxxx-xxxx-xxxx"
+database_name = "production-db"
+
+[[r2_buckets]]
+binding = "BUCKET"
+bucket_name = "my-bucket"
+
+[[durable_objects.bindings]]
+name = "COUNTER"
+class_name = "Counter"
+script_name = "counter-worker"
+
+[[services]]
+binding = "API"
+service = "api-worker"
+
+[[queues.producers]]
+binding = "QUEUE"
+queue = "my-queue"
+
+[[vectorize]]
+binding = "VECTORIZE"
+index_name = "my-index"
+
+[ai]
+binding = "AI"
+
+[[analytics_engine_datasets]]
+binding = "ANALYTICS"
+
+# Vars (non-sensitive)
+[vars]
+API_URL = "https://api.example.com"
+ENVIRONMENT = "production"
+
+# Environment overrides
+[env.preview]
+[env.preview.vars]
+API_URL = "https://staging-api.example.com"
+
+[[env.preview.kv_namespaces]]
+binding = "KV"
+id = "preview-namespace-id"
+```
+
+## Build Config
+
+**Git deployment**: Dashboard → Project → Settings → Build settings
+- Build command: `npm run build`
+- Output directory: `dist` / `out` / `build`
+- Environment variables: Set per environment (preview/production)
+
+**Framework detection**: Auto-configures build command + output dir for common frameworks
+
+## Environment Variables
+
+### Local Secrets (.dev.vars)
+```bash
+# .dev.vars (never commit)
+SECRET_KEY="local-secret-key"
+API_TOKEN="dev-token-123"
+DATABASE_URL="http://localhost:5432"
+```
+
+### Production Secrets
+```bash
+# Interactive
+echo "super-secret-value" | npx wrangler pages secret put SECRET_KEY --project-name=my-project
+
+# Per environment
+echo "prod-secret" | npx wrangler pages secret put SECRET_KEY --project-name=my-project --env=production
+
+# List
+npx wrangler pages secret list --project-name=my-project
+
+# Delete
+npx wrangler pages secret delete SECRET_KEY --project-name=my-project
+```
+
+Access like bindings: `env.SECRET_KEY`
+
+## Static Config Files
+
+### _redirects
+Place in build output (e.g., `dist/_redirects`):
+
+```txt
+# Simple (302)
+/old-page /new-page
+
+# Permanent (301)
+/old-page /new-page 301
+
+# External
+/blog https://blog.example.com
+
+# Splat wildcard
+/blog/* /news/:splat 301
+
+# Placeholders
+/users/:id /members/:id 301
+
+# Proxying (200)
+/api/* /api-v2/:splat 200
+
+# Limits: 2,100 total (2,000 static + 100 dynamic), 1,000 char/line
+```
+
+**Important**: Redirects don't apply to Functions routes. Functions take precedence.
+
+### _headers
+```txt
+# Security
+/secure/*
+  X-Frame-Options: DENY
+  X-Content-Type-Options: nosniff
+  Referrer-Policy: no-referrer
+
+# CORS
+/api/*
+  Access-Control-Allow-Origin: *
+  Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
+
+# Cache
+/static/*
+  Cache-Control: public, max-age=31536000, immutable
+
+# Prevent indexing previews
+https://:project.pages.dev/*
+  X-Robots-Tag: noindex
+
+# Remove header
+/special-page
+  ! X-Frame-Options
+
+# Limits: 100 rules, 2,000 char/line
+```
+
+**Important**: Headers don't apply to Functions responses. Set in Response object.
+
+### _routes.json
+Controls which requests invoke Functions (auto-generated for most frameworks):
+
+```json
+{
+  "version": 1,
+  "include": ["/*"],
+  "exclude": [
+    "/build/*",
+    "/static/*",
+    "/assets/*",
+    "/*.ico",
+    "/*.png",
+    "/*.jpg",
+    "/*.css",
+    "/*.js"
+  ]
+}
+```
+
+**Purpose**: Functions are metered; static requests are free. `exclude` takes precedence. Max 100 rules, 100 char/rule.
+
+## TypeScript
+
+Generate types:
+```bash
+npx wrangler types --path='./functions/types.d.ts'
+```
+
+```json
+// functions/tsconfig.json
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "lib": ["esnext"],
+    "types": ["./types.d.ts"]
+  }
+}
+```
+
+## Local Dev
+
+```bash
+# Basic
+npx wrangler pages dev ./dist
+
+# With bindings
+npx wrangler pages dev ./dist --kv KV --d1 DB=local-db-id --r2 BUCKET
+
+# Persistence
+npx wrangler pages dev ./dist --persist-to=./.wrangler/state/v3
+
+# Custom port
+npx wrangler pages dev ./dist --port=3000
+
+# Live reload
+npx wrangler pages dev ./dist --live-reload
+
+# Proxy mode (SSR frameworks)
+npx wrangler pages dev -- npm run dev
+```
+
+## Limits
+
+- **Functions**: 100k req/day (Free), 10ms CPU, 128MB memory, 1MB script
+- **Deployments**: 500/month (Free), 20k files, 25MB/file
+- **Config**: 2,100 redirects, 100 header rules, 100 route rules
+- **Build**: 20min timeout, no Docker
+
+[Full limits](https://developers.cloudflare.com/pages/platform/limits/)

package/dist/template/.opencode/skill/cloudflare/references/pages/gotchas.md

@@ -0,0 +1,161 @@
+# Gotchas
+
+## Functions Not Running
+
+1. **Check `_routes.json`**: May be excluding Function routes
+2. **Verify file naming**: Must be `.js` or `.ts`, NOT `.jsx` or `.tsx`
+3. **Check build output**: Functions dir must be at root of output dir
+4. **Functions precedence**: Functions always override redirects/static
+
+## 404 on Static Assets
+
+1. **Build output dir**: Verify setting matches actual build output
+2. **Functions catching requests**: Use `_routes.json` to exclude static paths
+3. **Advanced mode**: Must call `env.ASSETS.fetch()` or static won't serve
+
+## Bindings Not Working
+
+1. **wrangler.toml syntax**: Check for TOML errors
+2. **Binding IDs**: Verify correct (especially for KV/D1/R2)
+3. **Local dev**: Check `.dev.vars` exists and has correct values
+4. **Regenerate types**: `npx wrangler types --path='./functions/types.d.ts'`
+5. **Environment**: Production bindings ≠ preview bindings (set separately)
+
+## Build Failures
+
+1. **Build logs**: Check in Dashboard → Deployments → Build log
+2. **Build command**: Verify correct for framework
+3. **Output directory**: Must match actual build output
+4. **Node version**: Check compatibility (set via `.nvmrc` or env var)
+5. **Environment variables**: Review in Settings → Environment variables
+6. **Timeout**: 20min max. Long builds may fail.
+7. **Memory**: Build can OOM on large projects
+
+## Deployment Fails
+
+1. **File count**: Max 20,000 files per deployment
+2. **File size**: Max 25MB per file
+3. **Build errors**: Check build output in logs
+4. **wrangler.toml validation**: `npx wrangler pages project validate`
+5. **Bindings**: Verify all referenced bindings exist
+
+## Middleware Not Running
+
+1. **File location**: Must be `_middleware.ts` (underscore prefix)
+2. **Export**: Must export `onRequest` or method-specific handlers
+3. **Must call `next()`**: Or return Response directly
+4. **Scope**: `functions/_middleware.ts` applies to ALL (including static)
+5. **Order**: Array order matters: `[errorHandler, auth, logging]`
+
+## Headers Not Applied
+
+1. **Functions responses**: `_headers` only applies to static assets
+2. **Set in code**: Functions must set headers via Response object
+3. **Syntax**: Check `_headers` file syntax (path, then indented headers)
+4. **Limits**: Max 100 header rules
+
+## Redirects Not Working
+
+1. **Functions take precedence**: Redirects don't apply to Function routes
+2. **Syntax**: Check `_redirects` file format
+3. **Limits**: Max 2,100 redirects (2,000 static + 100 dynamic)
+4. **Query strings**: Preserved automatically
+5. **Testing**: Preview deployments to test before production
+
+## TypeScript Errors
+
+1. **Generate types**: `npx wrangler types` before dev
+2. **tsconfig**: Point `types` to generated file
+3. **Env interface**: Must match wrangler.toml bindings
+4. **Type imports**: `import type { PagesFunction } from '@cloudflare/workers-types'`
+
+## Local Dev Issues
+
+1. **Port conflicts**: Use `--port=3000` to change
+2. **Bindings**: Must pass via CLI flags or wrangler.toml
+3. **Persistence**: Use `--persist-to` to keep data between restarts
+4. **Hot reload**: May need manual restart for some changes
+5. **HTTPS**: Local dev uses HTTP, production uses HTTPS (affects cookies, etc.)
+
+## Preview vs Production
+
+1. **Different bindings**: Set separately in Dashboard
+2. **Different env vars**: Configure per environment
+3. **Branch deploys**: Every branch gets preview deployment
+4. **URLs**: `https://branch.project.pages.dev` vs `https://project.pages.dev`
+
+## Performance Issues
+
+1. **Function invocations**: Exclude static assets via `_routes.json`
+2. **Cold starts**: First request after deploy may be slower
+3. **CPU time**: 10ms limit per request (can hit on complex operations)
+4. **Memory**: 128MB limit (watch for large JSON parsing)
+5. **Bundle size**: Keep Functions < 1MB compressed
+
+## Framework-Specific
+
+### Next.js
+- Use `@cloudflare/next-on-pages` adapter
+- Some features unsupported (ISR, Middleware with waitUntil in body)
+- Check [compatibility](https://github.com/cloudflare/next-on-pages/blob/main/docs/compatibility.md)
+
+### SvelteKit
+- Use `@sveltejs/adapter-cloudflare`
+- Set `platform: 'cloudflare'` in svelte.config.js
+
+### Remix
+- Use `@remix-run/cloudflare-pages`
+- Check server context for bindings
+
+## Debugging
+
+```typescript
+// Log everything
+console.log('Request:', {
+  method: request.method,
+  url: request.url,
+  headers: Object.fromEntries(request.headers),
+});
+console.log('Env:', Object.keys(env));
+console.log('Params:', params);
+console.log('Data:', data);
+```
+
+**View logs**:
+```bash
+npx wrangler pages deployment tail --project-name=my-project
+```
+
+## Common Errors
+
+**"Module not found"**: Check build output, ensure dependencies bundled
+
+**"Binding not found"**: Verify wrangler.toml and regenerate types
+
+**"Request exceeded CPU limit"**: Optimize hot paths, use Workers for heavy compute
+
+**"Script too large"**: Tree-shake, dynamic imports, code-split
+
+**"Too many subrequests"**: Max 50 subreqs per request, batch where possible
+
+**"KV key not found"**: Check namespaces match (production vs preview)
+
+**"D1 error"**: Verify database_id, check migrations applied
+
+## Limits Reference
+
+- **Functions**: 100k req/day (Free), 10ms CPU, 128MB memory, 1MB script
+- **Deployments**: 500/month (Free), 20k files, 25MB/file
+- **Config**: 2,100 redirects, 100 headers, 100 routes
+- **Build**: 20min timeout
+- **Subrequests**: 50/request
+- **Request size**: 100MB
+
+[Full limits](https://developers.cloudflare.com/pages/platform/limits/)
+
+## Getting Help
+
+1. Check [Pages Docs](https://developers.cloudflare.com/pages/)
+2. Search [Discord #functions](https://discord.com/channels/595317990191398933/910978223968518144)
+3. Review [Workers Examples](https://developers.cloudflare.com/workers/examples/)
+4. Check framework-specific docs/adapters