npm - @namch/agent-assistant - Versions diffs - 1.0.0 - Mend

@namch/agent-assistant 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1823) hide show

package/skills/cloudflare-expert/references/pages/patterns.md ADDED Viewed

@@ -0,0 +1,145 @@
+# Patterns
+## API Routes
+```typescript
+// functions/api/todos/[id].ts
+export const onRequestGet: PagesFunction<Env> = async ({ env, params }) => {
+  const todo = await env.DB.prepare('SELECT * FROM todos WHERE id = ?').bind(params.id).first();
+  if (!todo) return new Response('Not found', { status: 404 });
+  return Response.json(todo);
+};
+export const onRequestPut: PagesFunction<Env> = async ({ env, params, request }) => {
+  const body = await request.json();
+  await env.DB.prepare('UPDATE todos SET title = ?, completed = ? WHERE id = ?')
+    .bind(body.title, body.completed, params.id).run();
+  return Response.json({ success: true });
+};
+export const onRequestDelete: PagesFunction<Env> = async ({ env, params }) => {
+  await env.DB.prepare('DELETE FROM todos WHERE id = ?').bind(params.id).run();
+  return new Response(null, { status: 204 });
+};
+```
+## Auth Middleware
+```typescript
+// functions/_middleware.ts
+const auth: PagesFunction<Env> = async (context) => {
+  if (context.request.url.includes('/public/')) return context.next();
+  const authHeader = context.request.headers.get('Authorization');
+  if (!authHeader?.startsWith('Bearer ')) return new Response('Unauthorized', { status: 401 });
+  try {
+    const payload = await verifyJWT(authHeader.substring(7), context.env.JWT_SECRET);
+    context.data.user = payload;
+    return context.next();
+  } catch (err) {
+    return new Response('Invalid token', { status: 401 });
+  }
+};
+export const onRequest = [auth];
+```
+## CORS
+```typescript
+// functions/api/_middleware.ts
+const corsHeaders = {'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS', 'Access-Control-Allow-Headers': 'Content-Type, Authorization'};
+const cors: PagesFunction = async (context) => {
+  if (context.request.method === 'OPTIONS') return new Response(null, { headers: corsHeaders });
+  const response = await context.next();
+  Object.entries(corsHeaders).forEach(([k, v]) => response.headers.set(k, v));
+  return response;
+};
+export const onRequest = [cors];
+```
+## Form Handling
+```typescript
+// functions/api/contact.ts
+export const onRequestPost: PagesFunction<Env> = async ({ request, env }) => {
+  const formData = await request.formData();
+  await env.QUEUE.send({name: formData.get('name'), email: formData.get('email'), message: formData.get('message')});
+  return new Response('<h1>Thanks!</h1>', { headers: { 'Content-Type': 'text/html' } });
+};
+```
+## Background Tasks
+```typescript
+export const onRequestPost: PagesFunction = async ({ request, waitUntil }) => {
+  const data = await request.json();
+  waitUntil(fetch('https://api.example.com/webhook', {method: 'POST', body: JSON.stringify(data)}));
+  return Response.json({ queued: true });
+};
+```
+## Error Handling
+```typescript
+// functions/_middleware.ts
+const errorHandler: PagesFunction = async (context) => {
+  try {
+    return await context.next();
+  } catch (error) {
+    console.error('Error:', error);
+    if (context.request.url.includes('/api/')) return Response.json({ error: error.message }, { status: 500 });
+    return new Response(`<html><body><h1>Error</h1><p>${error.message}</p></body></html>`, { status: 500, headers: { 'Content-Type': 'text/html' } });
+  }
+};
+export const onRequest = [errorHandler];
+```
+## Caching
+```typescript
+// functions/api/data.ts
+export const onRequestGet: PagesFunction<Env> = async ({ env, request }) => {
+  const url = new URL(request.url);
+  const cacheKey = `data:${url.pathname}`;
+  const cached = await env.KV.get(cacheKey, 'json');
+  if (cached) return Response.json(cached, { headers: { 'X-Cache': 'HIT' } });
+  const data = await env.DB.prepare('SELECT * FROM data WHERE path = ?').bind(url.pathname).first();
+  await env.KV.put(cacheKey, JSON.stringify(data), {expirationTtl: 3600});
+  return Response.json(data, {headers: {'X-Cache': 'MISS', 'Cache-Control': 'public, max-age=3600'}});
+};
+```
+## Framework Integration
+```bash
+npm create cloudflare@latest my-app -- --framework=<framework>
+# next, svelte, remix, nuxt, astro, qwik
+```
+[Framework Guides](https://developers.cloudflare.com/pages/framework-guides/)
+## Monorepo
+Dashboard → Project → Settings → Build settings → Root directory
+Set to subproject path (e.g., `apps/web`). Only builds when files in that dir change.
+## Best Practices
+### Performance
+1. Exclude static from Functions via `_routes.json`
+2. Cache with KV (API responses, rendered content)
+3. Use Cache API: `await caches.default.match(request)`
+4. Minimize Function size: tree-shake, dynamic imports, keep < 1MB
+### Security
+1. Set security headers in `_headers` for static
+2. Use secrets, never commit to wrangler.toml
+3. Validate all inputs
+4. Rate limit with KV/DO
+### Workflow
+1. Preview deployments per branch/PR
+2. Local dev: `npx wrangler pages dev ./dist`
+3. Environment-specific configs in `wrangler.toml`
+4. Rollbacks: Dashboard → Deployments → Rollback (instant)

package/skills/cloudflare-expert/references/pages-functions/README.md ADDED Viewed

@@ -0,0 +1,57 @@
+# Cloudflare Pages Functions
+Serverless functions on Cloudflare Pages using Workers runtime. Full-stack dev with file-based routing.
+## File-Based Routing
+```
+/functions
+  ├── index.js              → /
+  ├── api.js                → /api
+  ├── users/
+  │   ├── index.js          → /users/
+  │   ├── [user].js         → /users/:user
+  │   └── [[catchall]].js   → /users/*
+  └── _middleware.js        → runs on all routes
+```
+**Rules:**
+- `index.js` → directory root
+- Trailing slash optional
+- Specific routes precede catch-alls
+- Falls back to static if no match
+## Dynamic Routes
+**Single segment** `[param]` → string:
+```js
+// /functions/users/[user].js
+export function onRequest(context) {
+  return new Response(`Hello ${context.params.user}`);
+}
+// Matches: /users/nevi
+```
+**Multi-segment** `[[param]]` → array:
+```js
+// /functions/users/[[catchall]].js
+export function onRequest(context) {
+  return new Response(JSON.stringify(context.params.catchall));
+}
+// Matches: /users/nevi/foobar → ["nevi", "foobar"]
+```
+## Key Features
+- **Method handlers:** `onRequestGet`, `onRequestPost`, etc.
+- **Middleware:** `_middleware.js` for cross-cutting concerns
+- **Bindings:** KV, D1, R2, Durable Objects, Workers AI, Service bindings
+- **TypeScript:** Full type support via `@cloudflare/workers-types`
+- **Advanced mode:** Use `_worker.js` for custom routing logic
+## See Also
+- [configuration.md](./configuration.md) - Routes, headers, redirects, wrangler config
+- [api.md](./api.md) - EventContext, handlers, bindings
+- [patterns.md](./patterns.md) - Auth, CORS, rate limiting, forms, caching
+- [gotchas.md](./gotchas.md) - Common issues, debugging, limits

package/skills/cloudflare-expert/references/pages-functions/api.md ADDED Viewed

@@ -0,0 +1,201 @@
+# Function API
+## EventContext
+```typescript
+interface EventContext<Env = any> {
+  request: Request;              // Incoming request
+  functionPath: string;          // Request path
+  waitUntil(promise: Promise<any>): void;  // Background work
+  passThroughOnException(): void;          // Fallback on error
+  next(input?: Request | string, init?: RequestInit): Promise<Response>;
+  env: Env;                      // Bindings, vars, secrets
+  params: Record<string, string | string[]>;  // Route params
+  data: any;                     // Middleware shared data
+}
+```
+## Handlers
+```typescript
+// Generic (fallback)
+export async function onRequest(context: EventContext): Promise<Response> {
+  return new Response('Any method');
+}
+// Method-specific (takes precedence)
+export async function onRequestGet(context: EventContext): Promise<Response> {
+  return new Response('GET request');
+}
+export async function onRequestPost(context: EventContext): Promise<Response> {
+  const body = await context.request.json();
+  return Response.json({ received: body });
+}
+// Also: onRequestPut, onRequestPatch, onRequestDelete, onRequestHead, onRequestOptions
+```
+## Bindings
+### KV
+```typescript
+interface Env { TODO_LIST: KVNamespace; }
+export const onRequest: PagesFunction<Env> = async (context) => {
+  await context.env.TODO_LIST.put('Task:123', 'Buy milk');
+  const task = await context.env.TODO_LIST.get('Task:123');
+  await context.env.TODO_LIST.delete('Task:123');
+  const keys = await context.env.TODO_LIST.list({ prefix: 'Task:' });
+  // With options
+  await context.env.TODO_LIST.put('session', data, { expirationTtl: 3600 });
+  const value = await context.env.TODO_LIST.get('key', { type: 'json' });
+  return new Response(task);
+};
+```
+### D1
+```typescript
+interface Env { DB: D1Database; }
+export const onRequest: PagesFunction<Env> = async (context) => {
+  // Prepared statements
+  const result = await context.env.DB.prepare('SELECT * FROM users WHERE id = ?')
+    .bind(123)
+    .first();
+  // Batch
+  const data = await context.env.DB.batch([
+    context.env.DB.prepare('SELECT * FROM users'),
+    context.env.DB.prepare('SELECT * FROM posts')
+  ]);
+  return Response.json(result);
+};
+```
+### R2
+```typescript
+interface Env { BUCKET: R2Bucket; }
+export const onRequest: PagesFunction<Env> = async (context) => {
+  const url = new URL(context.request.url);
+  const key = url.pathname.slice(1);
+  // GET
+  const obj = await context.env.BUCKET.get(key);
+  if (!obj) return new Response('Not found', { status: 404 });
+  // PUT
+  await context.env.BUCKET.put(key, context.request.body, {
+    httpMetadata: { contentType: 'application/octet-stream' }
+  });
+  // DELETE
+  await context.env.BUCKET.delete(key);
+  return new Response(obj.body);
+};
+```
+### Durable Objects
+```typescript
+interface Env { COUNTER: DurableObjectNamespace; }
+export const onRequest: PagesFunction<Env> = async (context) => {
+  const id = context.env.COUNTER.idFromName('global-counter');
+  const stub = context.env.COUNTER.get(id);
+  return stub.fetch(context.request);
+};
+```
+### Workers AI
+```typescript
+interface Env { AI: Ai; }
+export const onRequest: PagesFunction<Env> = async (context) => {
+  const answer = await context.env.AI.run(
+    '@cf/meta/llama-3.1-8b-instruct',
+    { prompt: 'Hello, World?' }
+  );
+  return Response.json(answer);
+};
+```
+### Service Bindings
+```typescript
+interface Env { AUTH_SERVICE: Fetcher; }
+export const onRequest: PagesFunction<Env> = async (context) => {
+  // Forward request
+  return context.env.AUTH_SERVICE.fetch(context.request);
+  // Custom request
+  const req = new Request('https://internal/verify', {
+    method: 'POST',
+    body: JSON.stringify({ token: 'xyz' })
+  });
+  return context.env.AUTH_SERVICE.fetch(req);
+};
+```
+### Environment Variables
+```typescript
+interface Env {
+  API_KEY: string;
+  ENVIRONMENT: string;
+}
+export const onRequest: PagesFunction<Env> = async (context) => {
+  const apiKey = context.env.API_KEY;
+  const isProd = context.env.ENVIRONMENT === 'production';
+  return new Response('OK');
+};
+```
+## TypeScript
+```bash
+npm install -D @cloudflare/workers-types
+```
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "module": "ES2022",
+    "lib": ["ES2021"],
+    "types": ["@cloudflare/workers-types"]
+  }
+}
+```
+```typescript
+import type { PagesFunction, EventContext } from '@cloudflare/workers-types';
+interface Env {
+  KV: KVNamespace;
+  DB: D1Database;
+}
+export const onRequest: PagesFunction<Env> = async (context) => {
+  // context.env fully typed
+  return new Response('OK');
+};
+```
+## See Also
+- [README.md](./README.md) - Overview
+- [configuration.md](./configuration.md) - wrangler.json
+- [patterns.md](./patterns.md) - Common patterns

package/skills/cloudflare-expert/references/pages-functions/configuration.md ADDED Viewed

@@ -0,0 +1,159 @@
+# Configuration
+## wrangler.json / wrangler.toml
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "my-pages-app",
+  "pages_build_output_dir": "./dist",
+  "compatibility_date": "2024-01-15",
+  "compatibility_flags": ["nodejs_compat"],
+  "vars": { "API_URL": "https://api.example.com" },
+  "kv_namespaces": [
+    { "binding": "KV", "id": "abc123" }
+  ],
+  "d1_databases": [{
+    "binding": "DB",
+    "database_name": "production-db",
+    "database_id": "xyz789"
+  }],
+  "r2_buckets": [
+    { "binding": "BUCKET", "bucket_name": "my-bucket" }
+  ],
+  "durable_objects": {
+    "bindings": [{
+      "name": "COUNTER",
+      "class_name": "Counter",
+      "script_name": "counter-worker"
+    }]
+  },
+  "services": [
+    { "binding": "AUTH", "service": "auth-worker" }
+  ],
+  "ai": { "binding": "AI" },
+  "vectorize": [{
+    "binding": "VECTORIZE",
+    "index_name": "my-index"
+  }],
+  "hyperdrive": [{
+    "binding": "HYPERDRIVE",
+    "id": "hyperdrive-id"
+  }],
+  "analytics_engine_datasets": [{ "binding": "ANALYTICS" }]
+}
+```
+## Environment Overrides
+```jsonc
+{
+  "name": "my-app",
+  "vars": { "API_URL": "http://localhost:8787" },
+  "env": {
+    "preview": {
+      "vars": { "API_URL": "https://preview.example.com" }
+    },
+    "production": {
+      "vars": { "API_URL": "https://api.example.com" }
+    }
+  }
+}
+```
+**Rules:**
+- Top-level → local dev
+- `env.preview` → preview deployments
+- `env.production` → production
+- **Non-inheritable keys:** If overriding `vars`, `kv_namespaces`, `d1_databases`, etc., ALL must be redefined
+## Local Secrets (.dev.vars)
+```bash
+# .dev.vars (DO NOT COMMIT)
+SECRET_KEY="my-secret-value"
+API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
+```
+- Add `.dev.vars*` to `.gitignore`
+- Use `vars` for non-sensitive config
+- Environment-specific: `.dev.vars.preview`, `.dev.vars.production`
+## _routes.json (Advanced)
+Custom routing rules in build output:
+```json
+{
+  "version": 1,
+  "include": ["/api/*"],
+  "exclude": ["/static/*"]
+}
+```
+## _headers (Static)
+```
+/static/*
+  Cache-Control: public, max-age=31536000
+  X-Custom: value
+/api/*
+  Access-Control-Allow-Origin: *
+```
+## _redirects (Static)
+```
+/old-page  /new-page  301
+/docs/*    https://docs.example.com/:splat  302
+```
+## Local Dev
+```bash
+# Start dev server
+npx wrangler pages dev ./dist
+# With bindings
+npx wrangler pages dev ./dist \
+  --kv=KV \
+  --d1=DB=database-id \
+  --r2=BUCKET \
+  --binding=API_KEY=secret123
+# Durable Objects (2 terminals)
+cd do-worker && npx wrangler dev
+cd pages-project && npx wrangler pages dev ./dist \
+  --do COUNTER=CounterClass@do-worker
+```
+## Deployment
+```bash
+# Git push (auto-deploys)
+git push origin main
+# CLI
+npx wrangler pages deploy ./dist
+npx wrangler pages deploy ./dist --branch preview
+# Download config from dashboard
+npx wrangler pages download config my-project-name
+```
+## See Also
+- [README.md](./README.md) - Overview
+- [api.md](./api.md) - EventContext, bindings

package/skills/cloudflare-expert/references/pages-functions/gotchas.md ADDED Viewed

@@ -0,0 +1,151 @@
+# Gotchas & Debugging
+## Common Issues
+### Functions Not Invoking
+All requests serve static, functions never run.
+**Fix:**
+- `/functions` in correct location (project root)
+- Check `pages_build_output_dir` in wrangler.json
+- Files have `.js` or `.ts` extension
+- `_routes.json` not excluding paths
+### Binding Not Available
+`context.env.MY_BINDING is undefined`
+**Fix:**
+- Binding in wrangler.json or dashboard
+- Name matches exactly (case-sensitive)
+- Local dev: pass flags OR configure wrangler.json
+- Redeploy after changes
+### TypeScript Errors
+Type errors for `context.env`
+**Fix:**
+```typescript
+interface Env { MY_BINDING: KVNamespace; }
+export const onRequest: PagesFunction<Env> = async (context) => {
+  // context.env.MY_BINDING now typed
+};
+```
+### Middleware Not Running
+`_middleware.js` not executing
+**Fix:**
+- Named exactly `_middleware.js`
+- In correct directory for route scope
+- `onRequest` or method handler exported
+- Use `context.next()` to pass control
+### Environment Variables Missing
+`context.env.VAR_NAME is undefined`
+**Fix:**
+- `vars` in wrangler.json
+- Secrets: `.dev.vars` locally, dashboard/wrangler.json for prod
+- Redeploy after changes
+## Debugging
+### Console Logging
+```typescript
+export async function onRequest(context) {
+  console.log('Request:', context.request.method, context.request.url);
+  console.log('Headers:', Object.fromEntries(context.request.headers));
+  const response = await context.next();
+  console.log('Response status:', response.status);
+  return response;
+}
+```
+### Wrangler Tail
+```bash
+# Stream real-time logs
+npx wrangler pages deployment tail
+# Filter
+npx wrangler pages deployment tail --status error
+```
+### Source Maps
+```jsonc
+// wrangler.json
+{ "upload_source_maps": true }
+```
+## Limits
+- **CPU:** 10ms (Free), 50ms (Paid)
+- **Memory:** 128 MB
+- **Script size:** 10 MB compressed
+- **Env vars:** 5 KB per var, 64 max
+- **Requests:** 100k free/day, $0.50/million after
+## Best Practices
+**Performance:**
+- Minimize deps for cold starts
+- KV for infrequent reads, D1 for relational, R2 for large files
+- Set `Cache-Control` headers
+- Use prepared statements, batch operations
+- Handle errors gracefully
+**Security:**
+- Never commit secrets
+- Use secrets (encrypted) not vars for sensitive data
+- Validate all input
+- Sanitize before DB ops
+- Implement auth middleware
+- Set appropriate CORS headers
+- Rate limit per-IP
+## Migration
+### From Workers
+```typescript
+// Worker
+export default {
+  fetch(request, env) { }
+}
+// Pages Function
+export function onRequest(context) {
+  const { request, env } = context;
+}
+```
+In `_worker.js`: `return env.ASSETS.fetch(request)` for static assets.
+### From Other Platforms
+- `/functions/api/users.js` → `/api/users`
+- Dynamic routes: `[param]` not `:param`
+- Replace deps with Workers APIs or `nodejs_compat` flag
+## Resources
+- [Docs](https://developers.cloudflare.com/pages/functions/)
+- [Workers APIs](https://developers.cloudflare.com/workers/runtime-apis/)
+- [Examples](https://github.com/cloudflare/pages-example-projects)
+- [Discord](https://discord.gg/cloudflaredev)
+## See Also
+- [README.md](./README.md) - Overview
+- [configuration.md](./configuration.md) - wrangler.json
+- [api.md](./api.md) - EventContext, bindings
+- [patterns.md](./patterns.md) - Common patterns