devstack 0.1.0

package/vendor/skills/skills/cloudflare/references/pages/README.md

@@ -0,0 +1,92 @@
+# Cloudflare Pages
+
+JAMstack platform for full-stack apps on Cloudflare's global network.
+
+## Key Features
+
+- **Git-based deploys**: Auto-deploy from GitHub/GitLab
+- **Preview deployments**: Unique URL per branch/PR
+- **Pages Functions**: File-based serverless routing (Workers runtime)
+- **Static + dynamic**: Smart asset caching + edge compute
+- **Smart Placement**: Automatic function optimization based on traffic patterns
+- **Framework optimized**: SvelteKit, Astro, Nuxt, Qwik, Solid Start
+
+## Deployment Methods
+
+### 1. Git Integration (Production)
+
+Dashboard → Workers & Pages → Create → Connect to Git → Configure build
+
+### 2. Direct Upload
+
+```bash
+npx wrangler pages deploy ./dist --project-name=my-project
+npx wrangler pages deploy ./dist --project-name=my-project --branch=staging
+```
+
+### 3. C3 CLI
+
+```bash
+npm create cloudflare@latest my-app
+# Select framework → auto-setup + deploy
+```
+
+## vs Workers
+
+- **Pages**: Static sites, JAMstack, frameworks, git workflow, file-based routing
+- **Workers**: Pure APIs, complex routing, WebSockets, scheduled tasks, email handlers
+- **Combine**: Pages Functions use Workers runtime, can bind to Workers
+
+## Quick Start
+
+```bash
+# Create
+npm create cloudflare@latest
+
+# Local dev
+npx wrangler pages dev ./dist
+
+# Deploy
+npx wrangler pages deploy ./dist --project-name=my-project
+
+# Types
+npx wrangler types --path='./functions/types.d.ts'
+
+# Secrets
+echo "value" | npx wrangler pages secret put KEY --project-name=my-project
+
+# Logs
+npx wrangler pages deployment tail --project-name=my-project
+```
+
+## Resources
+
+- [Pages Docs](https://developers.cloudflare.com/pages/)
+- [Functions API](https://developers.cloudflare.com/pages/functions/api-reference/)
+- [Framework Guides](https://developers.cloudflare.com/pages/framework-guides/)
+- [Discord #functions](https://discord.com/channels/595317990191398933/910978223968518144)
+
+## Reading Order
+
+**New to Pages?** Start here:
+
+1. README.md (you are here) - Overview & quick start
+2. [configuration.md](./configuration.md) - Project setup, wrangler.jsonc, bindings
+3. [api.md](./api.md) - Functions API, routing, context
+4. [patterns.md](./patterns.md) - Common implementations
+5. [gotchas.md](./gotchas.md) - Troubleshooting & pitfalls
+
+**Quick reference?** Jump to relevant file above.
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.jsonc, build, env vars, Smart Placement
+- [api.md](./api.md) - Functions API, bindings, context, advanced mode
+- [patterns.md](./patterns.md) - Full-stack patterns, framework integration
+- [gotchas.md](./gotchas.md) - Build issues, limits, debugging, framework warnings
+
+## See Also
+
+- [pages-functions](../pages-functions/) - File-based routing, middleware
+- [d1](../d1/) - SQL database for Pages Functions
+- [kv](../kv/) - Key-value storage for caching/state

package/vendor/skills/skills/cloudflare/references/pages/api.md

@@ -0,0 +1,205 @@
+# Functions API
+
+## File-Based Routing
+
+```
+/functions/index.ts              → example.com/
+/functions/api/users.ts          → example.com/api/users
+/functions/api/users/[id].ts     → example.com/api/users/:id
+/functions/api/users/[[path]].ts → example.com/api/users/* (catchall)
+/functions/_middleware.ts        → Runs before all routes
+```
+
+**Rules**: `[param]` = single segment, `[[param]]` = multi-segment catchall, more specific wins.
+
+## 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; // HTTP request
+  env: Env; // Bindings (KV, D1, R2, etc.)
+  params: Params; // Route parameters
+  data: Data; // Middleware-shared data
+  waitUntil: (promise: Promise<any>) => void; // Background tasks
+  next: () => Promise<Response>; // Next handler
+  passThroughOnException: () => void; // Error fallback (not in advanced mode)
+}
+```
+
+## Dynamic Routes
+
+```typescript
+// Single segment: functions/users/[id].ts
+export const onRequestGet: PagesFunction = async ({ params }) => {
+  // /users/123 → params.id = "123"
+  return Response.json({ userId: params.id });
+};
+
+// Multi-segment: 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
+// 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; `functions/api/_middleware.ts` → `/api/*` only
+
+## Bindings Usage
+
+```typescript
+export const onRequestGet: PagesFunction<Env> = async ({ env }) => {
+  // 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, Queue, AI - see respective reference docs
+
+  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.
+
+## Smart Placement
+
+Automatically optimizes function execution location based on traffic patterns.
+
+**Configuration** (in wrangler.jsonc):
+
+```jsonc
+{
+  "placement": {
+    "mode": "smart", // Enables optimization (default: off)
+  },
+}
+```
+
+**How it works**: Analyzes traffic patterns over time and places functions closer to users or data sources (e.g., D1 databases). Requires no code changes.
+
+**Trade-offs**: Initial requests may see slightly higher latency during learning period (hours-days). Performance improves as system optimizes.
+
+**When to use**: Global apps with centralized databases or geographically concentrated traffic sources.
+
+## getRequestContext (Framework SSR)
+
+Access bindings in framework code:
+
+```typescript
+// SvelteKit
+import type { RequestEvent } from "@sveltejs/kit";
+export async function load({ platform }: RequestEvent) {
+  const data = await platform.env.DB.prepare("SELECT * FROM users").all();
+  return { users: data.results };
+}
+
+// Astro
+const { DB } = Astro.locals.runtime.env;
+const data = await DB.prepare("SELECT * FROM users").all();
+
+// Solid Start (server function)
+import { getRequestEvent } from "solid-js/web";
+const event = getRequestEvent();
+const data = await event.locals.runtime.env.DB.prepare("SELECT * FROM users").all();
+```
+
+**✅ Supported adapters** (2026):
+
+- **SvelteKit**: `@sveltejs/adapter-cloudflare`
+- **Astro**: Built-in Cloudflare adapter
+- **Nuxt**: Set `nitro.preset: 'cloudflare-pages'` in `nuxt.config.ts`
+- **Qwik**: Built-in Cloudflare adapter
+- **Solid Start**: `@solidjs/start-cloudflare-pages`
+
+**❌ Deprecated/Unsupported**:
+
+- **Next.js**: Official adapter (`@cloudflare/next-on-pages`) deprecated. Use Vercel or self-host on Workers.
+- **Remix**: Official adapter (`@remix-run/cloudflare-pages`) deprecated. Migrate to supported frameworks.
+
+See [gotchas.md](./gotchas.md#framework-specific) for migration guidance.

package/vendor/skills/skills/cloudflare/references/pages/configuration.md

@@ -0,0 +1,216 @@
+# Configuration
+
+## wrangler.jsonc
+
+```jsonc
+{
+  "name": "my-pages-project",
+  "pages_build_output_dir": "./dist",
+  "compatibility_date": "2026-01-01", // Use current date for new projects
+  "compatibility_flags": ["nodejs_compat"],
+  "placement": {
+    "mode": "smart", // Optional: Enable Smart Placement
+  },
+  "kv_namespaces": [{ "binding": "KV", "id": "abcd1234..." }],
+  "d1_databases": [
+    { "binding": "DB", "database_id": "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": { "API_URL": "https://api.example.com", "ENVIRONMENT": "production" },
+  "env": {
+    "preview": {
+      "vars": { "API_URL": "https://staging-api.example.com" },
+      "kv_namespaces": [{ "binding": "KV", "id": "preview-namespace-id" }],
+    },
+  },
+}
+```
+
+## Build Config
+
+**Git deployment**: Dashboard → Project → Settings → Build settings  
+Set build command, output dir, env vars. Framework auto-detection configures automatically.
+
+## Environment Variables
+
+### Local (.dev.vars)
+
+```bash
+# .dev.vars (never commit)
+SECRET_KEY="local-secret-key"
+API_TOKEN="dev-token-123"
+```
+
+### Production
+
+```bash
+echo "secret-value" | npx wrangler pages secret put SECRET_KEY --project-name=my-project
+npx wrangler pages secret list --project-name=my-project
+npx wrangler pages secret delete SECRET_KEY --project-name=my-project
+```
+
+Access: `env.SECRET_KEY`
+
+## Static Config Files
+
+### \_redirects
+
+Place in build output (e.g., `dist/_redirects`):
+
+```txt
+/old-page /new-page 301          # 301 redirect
+/blog/* /news/:splat 301         # Splat wildcard
+/users/:id /members/:id 301      # Placeholders
+/api/* /api-v2/:splat 200        # Proxy (no redirect)
+```
+
+**Limits**: 2,100 total (2,000 static + 100 dynamic), 1,000 char/line  
+**Note**: Functions take precedence
+
+### \_headers
+
+```txt
+/secure/*
+  X-Frame-Options: DENY
+  X-Content-Type-Options: nosniff
+
+/api/*
+  Access-Control-Allow-Origin: *
+
+/static/*
+  Cache-Control: public, max-age=31536000, immutable
+```
+
+**Limits**: 100 rules, 2,000 char/line  
+**Note**: Only static assets; Functions set headers in Response
+
+### \_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
+
+```bash
+npx wrangler types --path='./functions/types.d.ts'
+```
+
+Point `types` in `functions/tsconfig.json` to generated file.
+
+## Smart Placement
+
+Automatically optimizes function execution location based on request patterns.
+
+```jsonc
+{
+  "placement": {
+    "mode": "smart", // Enable optimization (default: off)
+  },
+}
+```
+
+**How it works**: System analyzes traffic over hours/days and places function execution closer to:
+
+- User clusters (e.g., regional traffic)
+- Data sources (e.g., D1 database primary location)
+
+**Benefits**:
+
+- Lower latency for read-heavy apps with centralized databases
+- Better performance for apps with regional traffic patterns
+
+**Trade-offs**:
+
+- Initial learning period: First requests may be slower while system optimizes
+- Optimization time: Performance improves over 24-48 hours
+
+**When to enable**: Global apps with D1/Durable Objects in specific regions, or apps with concentrated geographic traffic.
+
+**When to skip**: Evenly distributed global traffic with no data locality constraints.
+
+## Remote Bindings (Local Dev)
+
+Connect local dev server to production bindings instead of local mocks:
+
+```bash
+# All bindings remote
+npx wrangler pages dev ./dist --remote
+
+# Specific bindings remote (others local)
+npx wrangler pages dev ./dist --remote --kv=KV --d1=DB
+```
+
+**Use cases**:
+
+- Test against production data (read-only operations)
+- Debug binding-specific behavior
+- Validate changes before deployment
+
+**⚠️ Warning**:
+
+- Writes affect **real production data**
+- Use only for read-heavy debugging or with non-production accounts
+- Consider creating separate preview environments instead
+
+**Requirements**: Must be logged in (`npx wrangler login`) with access to bindings.
+
+## Local Dev
+
+```bash
+# Basic
+npx wrangler pages dev ./dist
+
+# With bindings
+npx wrangler pages dev ./dist --kv KV --d1 DB=local-db-id
+
+# Remote bindings (production data)
+npx wrangler pages dev ./dist --remote
+
+# Persistence
+npx wrangler pages dev ./dist --persist-to=./.wrangler/state/v3
+
+# Proxy mode (SSR frameworks)
+npx wrangler pages dev -- npm run dev
+```
+
+## Limits (as of Jan 2026)
+
+| Resource               | Free                            | Paid                          |
+| ---------------------- | ------------------------------- | ----------------------------- |
+| **Functions Requests** | 100k/day                        | Unlimited (metered)           |
+| **Function CPU Time**  | 10ms/req                        | 30ms/req (Workers Paid)       |
+| **Function Memory**    | 128MB                           | 128MB                         |
+| **Script Size**        | 1MB compressed                  | 10MB compressed               |
+| **Deployments**        | 500/month                       | 5,000/month                   |
+| **Files per Deploy**   | 20,000                          | 20,000                        |
+| **File Size**          | 25MB                            | 25MB                          |
+| **Build Time**         | 20min                           | 20min                         |
+| **Redirects**          | 2,100 (2k static + 100 dynamic) | Same                          |
+| **Header Rules**       | 100                             | 100                           |
+| **Route Rules**        | 100                             | 100                           |
+| **Subrequests**        | 50/request                      | 10,000/request (Workers Paid) |
+
+**Notes**:
+
+- Functions use Workers runtime; Workers Paid plan increases limits
+- Free plan sufficient for most projects
+- Static requests always free (not counted toward limits)
+
+[Full limits](https://developers.cloudflare.com/pages/platform/limits/)