pi-cloudflare 0.1.0

package/skills/cloudflare/references/artifacts/README.md

@@ -0,0 +1,79 @@
+# Cloudflare Artifacts
+
+Store versioned file trees behind a repo-style interface that works from Workers, the REST API, and Git-compatible tooling.
+
+## Overview
+
+Use **Artifacts** when the thing you need to store is a versioned filesystem tree rather than a single object, key, or SQL row.
+
+Typical Artifacts use cases:
+- Git-style repositories
+- Per-agent, per-session, or per-task repos
+- Build outputs and deployment bundles
+- Checkpoints and generated assets
+- Shared file trees passed between developer tools and Workers
+
+Artifacts is a good fit when the same content needs to be addressable from **Workers**, the **REST API**, and **Git-compatible clients**.
+
+Artifacts is especially useful for agent and automation workflows where each unit of work should have its own isolated repo and token.
+
+**Prefer retrieval over memory** for current availability, authentication details, route shapes, limits, and pricing. Start at `https://developers.cloudflare.com/artifacts/`.
+
+## When to Use Artifacts
+
+| Need | Use | Why |
+|------|-----|-----|
+| Versioned file trees such as repos, build outputs, checkpoints, or generated assets | Artifacts | Artifacts stores and shares **versioned filesystem content** |
+| A git-compatible workflow with `clone`, `fetch`, `pull`, or `push` | Artifacts | Artifacts exposes **git-over-HTTPS remotes** and repo-scoped tokens |
+| The same artifact accessible from Workers, HTTP APIs, and developer tooling | Artifacts | Artifacts is available through a **Workers binding**, **REST API**, and **git-compatible interface** |
+| Large files by object key, app config by key, or relational app data | R2, KV, or D1 | Use storage products directly when you need **objects, key-value entries, or SQL rows**, not versioned file trees |
+
+## Recommended Workflow
+
+- Create one repo per agent, session, user workspace, or task when work should stay isolated.
+- Fork from a stable baseline when many repos need the same starter files or prompts.
+- Use branches only when collaborators share the same lifecycle and need to work in one repo.
+- Use namespaces to separate environments, teams, or high-rate workloads.
+
+## Quick Start
+
+**From a Worker:**
+
+```typescript
+interface Env {
+  ARTIFACTS: Artifacts;
+}
+
+const created = await env.ARTIFACTS.create("starter-repo");
+// created.remote -> git remote URL
+// created.token -> initial repo token
+```
+
+**From the REST API:**
+
+Use the namespace-scoped Artifacts base URL plus a gateway JWT. For imports from existing HTTPS remotes, use the REST API rather than the Workers binding.
+
+## Reading Order
+
+| Task | Read |
+|------|------|
+| Decide whether Artifacts is the right product | README only |
+| Create or manage repos from a Worker | README → configuration.md → api.md |
+| Integrate Artifacts from an external system | README → api.md |
+| Set up agent or sandbox workflows | README → configuration.md |
+| Verify exact auth, routes, limits, or pricing | Live docs first: `https://developers.cloudflare.com/artifacts/` |
+
+## In This Reference
+
+- **[api.md](api.md)** - Workers binding methods, REST routes, token and repo operations
+- **[configuration.md](configuration.md)** - Wrangler binding shape, Worker typing, REST configuration guidance
+
+## See Also
+
+- [Cloudflare Artifacts Docs](https://developers.cloudflare.com/artifacts/)
+- [Artifacts Git Protocol Docs](https://developers.cloudflare.com/artifacts/api/git-protocol/)
+- [ArtifactFS Docs](https://developers.cloudflare.com/artifacts/api/artifactfs/)
+- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)
+- [Cloudflare Durable Objects Docs](https://developers.cloudflare.com/durable-objects/)
+- [Cloudflare R2 Docs](https://developers.cloudflare.com/r2/)
+- [Cloudflare D1 Docs](https://developers.cloudflare.com/d1/)

package/skills/cloudflare/references/artifacts/api.md

@@ -0,0 +1,128 @@
+# Artifacts API Reference
+
+Use Artifacts through the **Workers binding**, the **REST control plane**, and **Git-compatible remotes**.
+
+**Prefer retrieval** for exact request and response details. Verify current behavior at `https://developers.cloudflare.com/artifacts/` before relying on specific auth flows, route details, or generated binding types.
+
+## Workers Binding
+
+Artifacts exposes a Worker binding on `env.ARTIFACTS`.
+
+### Namespace Methods
+
+| Method | Use For |
+|--------|---------|
+| `create(name, opts?)` | Create a repo and receive its initial remote and token |
+| `get(name)` | Resolve a repo handle for repo-scoped operations |
+| `list(opts?)` | List repos in a namespace |
+| `delete(name)` | Delete a repo |
+
+```typescript
+const created = await env.ARTIFACTS.create("starter-repo", {
+  description: "Repository for automation experiments",
+  setDefaultBranch: "main"
+});
+const repo = await env.ARTIFACTS.get("starter-repo");
+const page = await env.ARTIFACTS.list({ limit: 10 });
+```
+
+Use the REST API when you need to import a repo from another HTTPS remote.
+
+### Repo Handle Methods
+
+Use a repo handle returned by `get()` or `create()`.
+
+| Method | Use For |
+|--------|---------|
+| `info()` | Read repo metadata, including the remote URL |
+| `createToken(scope?, ttl?)` | Mint a repo-scoped read or write token |
+| `listTokens()` | Inspect active tokens |
+| `validateToken(token)` | Check whether a token is still valid |
+| `revokeToken(tokenOrId)` | Revoke a token by ID or value |
+| `fork(name, opts?)` | Fork one repo into another |
+
+```typescript
+const repo = await env.ARTIFACTS.get("starter-repo");
+if (!repo) throw new Error("Repo not found");
+
+const info = await repo.info();
+const token = await repo.createToken("read", 3600);
+const forked = await repo.fork("starter-repo-copy", {
+  defaultBranchOnly: true
+});
+```
+
+### Binding Notes
+
+- Current docs describe the runtime binding surface as `create`, `get`, `list`, `delete`, and repo-handle methods like `info`, `createToken`, and `fork`.
+- Use `npx wrangler types` in the target project and treat the generated `worker-configuration.d.ts` as the source of truth for that environment.
+- If generated types appear to expose `import()` or a different `get()` shape, verify the live docs before depending on those methods.
+
+Verify current runtime behavior in the live docs before depending on methods that are not shown in the Workers binding reference.
+
+## REST API
+
+Artifacts currently documents a namespace-scoped control plane:
+
+```txt
+https://artifacts.cloudflare.net/v1/api/namespaces/$ARTIFACTS_NAMESPACE
+```
+
+Some deployments also expose an `/edge/v1/api/...` base path. Verify the correct base URL for your environment in the live docs.
+
+Requests to the standard `/v1/api/...` routes use a **gateway JWT** with Bearer authentication.
+
+Returned repo tokens authenticate **Git operations** against the repo `remote`. They do not authenticate REST control-plane requests.
+
+Current docs show the standard Cloudflare v4 response envelope around REST results.
+
+### Repo Routes
+
+| Route | Use For |
+|-------|---------|
+| `POST /repos` | Create a repo |
+| `GET /repos` | List repos |
+| `GET /repos/:name` | Read repo metadata and remote |
+| `DELETE /repos/:name` | Delete a repo |
+| `POST /repos/:name/fork` | Fork a repo |
+| `POST /repos/:name/import` | Import a public HTTPS remote |
+
+```bash
+curl --request POST "$ARTIFACTS_BASE_URL/repos" \
+  --header "Authorization: Bearer $ARTIFACTS_JWT" \
+  --header "Content-Type: application/json" \
+  --data '{"name":"starter-repo"}'
+```
+
+Important current details from the docs draft:
+- `POST /repos/:name/import` accepts a full HTTPS remote URL such as GitHub or GitLab.
+- Import supports options such as `branch`, `depth`, and `read_only`.
+- Repo metadata includes fields such as description, default branch, timestamps, and the Git `remote`.
+
+### Token Routes
+
+| Route | Use For |
+|-------|---------|
+| `GET /repos/:name/tokens` | List repo tokens |
+| `POST /tokens` | Create a token for a repo |
+| `DELETE /tokens/:id` | Revoke a token by ID |
+
+Current docs show list-token filtering and pagination by token state. Retrieve the exact query shape from the live docs when you need token audit or cleanup workflows.
+
+Use **read** tokens for clone, fetch, pull, and indexing workflows. Use **write** tokens only when a workflow must push or otherwise mutate a repo.
+
+## Git-Compatible Access
+
+Artifacts returns repo `remote` URLs that work with standard git-over-HTTPS tooling.
+
+Recommended current auth pattern for local workflows:
+
+```bash
+git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" clone "$ARTIFACTS_REMOTE" artifacts-clone
+```
+
+Use a self-contained Basic-auth remote only for short-lived commands that need credentials embedded in the URL.
+
+`read` tokens support `clone`, `fetch`, and `pull`. `git push` requires a `write` token.
+
+For large repos where startup time matters more than a full clone, Artifacts also documents **ArtifactFS**. Retrieve current details from `https://developers.cloudflare.com/artifacts/` when you need mount-style access.

package/skills/cloudflare/references/artifacts/configuration.md

@@ -0,0 +1,92 @@
+# Artifacts Configuration
+
+## Worker Binding
+
+Configure the `artifacts` binding in your Wrangler config:
+
+```toml
+[[artifacts]]
+binding = "ARTIFACTS"
+namespace = "default"
+```
+
+This exposes Artifacts on `env.ARTIFACTS` inside your Worker.
+
+If you authenticate with `wrangler login`, current docs say Wrangler requests `artifacts:write` by default.
+
+## TypeScript
+
+Regenerate Worker types after adding the binding:
+
+```bash
+npx wrangler types
+```
+
+Use the generated binding type in your environment definition:
+
+```typescript
+interface Env {
+  ARTIFACTS: Artifacts;
+}
+```
+
+Wrangler generates the `Artifacts` type from the binding. Treat the generated `worker-configuration.d.ts` file as the source of truth for your environment.
+
+## Structure Repos for Isolation
+
+Artifacts works best when autonomous work is isolated:
+- Create one repo per agent, session, sandbox, or task when work should stay separate.
+- Fork from a reviewed baseline instead of copying starter files into every new repo.
+- Use branches only when collaborators share the same lifecycle and need to work in one repo.
+- Use namespaces to separate environments, teams, or high-rate workloads.
+
+## REST Configuration
+
+For external systems, configure the namespace-scoped base URL and gateway JWT:
+
+```bash
+export ARTIFACTS_NAMESPACE="default"
+export ARTIFACTS_JWT="<YOUR_GATEWAY_JWT>"
+export ARTIFACTS_BASE_URL="https://artifacts.cloudflare.net/v1/api/namespaces/$ARTIFACTS_NAMESPACE"
+```
+
+Some environments also expose an `/edge/v1/api/...` base path. Verify the correct host and base path in the live docs for your Artifacts environment.
+
+Use environment variables or your secret manager. Do not hardcode gateway JWTs or repo tokens.
+
+## Repo Tokens
+
+Artifacts workflows usually involve repo-scoped tokens returned by `create()` or minted later through the binding or REST API.
+
+Keep the control plane and data plane separate:
+- Use the **Workers binding** or **REST API** with a gateway JWT to create repos and mint tokens.
+- Use repo-scoped tokens only for **Git operations** against the returned `remote`.
+
+Recommended handling:
+- Mint the narrowest scope you need: `read` or `write`
+- Prefer short-lived tokens for handoff between systems
+- Revoke tokens that are no longer needed
+
+Verify the current token behavior and auth guidance in `https://developers.cloudflare.com/artifacts/` before building long-lived automation.
+
+## Git Consumers
+
+Artifacts is designed to work with standard git-over-HTTPS clients once you have a repo `remote` and an access token.
+
+Prefer header-based auth for local tooling so the full token stays out of the remote URL:
+
+```bash
+git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" clone "$ARTIFACTS_REMOTE" artifacts-clone
+```
+
+Use a Basic-auth remote only for short-lived commands that need a self-contained URL.
+
+## Retrieval Checklist
+
+Check the live docs before relying on:
+- the current Workers binding surface
+- exact token formats
+- availability or product status
+- route details for import, fork, and token-management flows
+- the correct control-plane host or `/edge/v1` base path for your environment
+- platform limits or pricing

package/skills/cloudflare/references/bindings/README.md

@@ -0,0 +1,122 @@
+# Cloudflare Bindings Skill Reference
+
+Expert guidance on Cloudflare Workers Bindings - the runtime APIs that connect Workers to Cloudflare platform resources.
+
+## What Are Bindings?
+
+Bindings are how Workers access Cloudflare resources (storage, compute, services) via the `env` object. They're configured in `wrangler.jsonc`, type-safe via TypeScript, and zero-overhead at runtime.
+
+## Reading Order
+
+1. **This file** - Binding catalog and selection guide
+2. **[api.md](api.md)** - TypeScript types and env access patterns
+3. **[configuration.md](configuration.md)** - Complete wrangler.jsonc examples
+4. **[patterns.md](patterns.md)** - Best practices and common patterns
+5. **[gotchas.md](gotchas.md)** - Critical pitfalls and troubleshooting
+
+## Binding Catalog
+
+### Storage Bindings
+
+| Binding | Use Case | Access Pattern |
+|---------|----------|----------------|
+| **KV** | Key-value cache, CDN-backed reads | `env.MY_KV.get(key)` |
+| **R2** | Object storage (S3-compatible) | `env.MY_BUCKET.get(key)` |
+| **D1** | SQL database (SQLite) | `env.DB.prepare(sql).all()` |
+| **Durable Objects** | Coordination, real-time state | `env.MY_DO.get(id)` |
+| **Vectorize** | Vector embeddings search | `env.VECTORIZE.query(vector)` |
+| **Queues** | Async message processing | `env.MY_QUEUE.send(msg)` |
+
+### Compute Bindings
+
+| Binding | Use Case | Access Pattern |
+|---------|----------|----------------|
+| **Service** | Worker-to-Worker RPC | `env.MY_SERVICE.fetch(req)` |
+| **Workers AI** | LLM inference | `env.AI.run(model, input)` |
+| **Browser Rendering** | Headless Chrome | `env.BROWSER.fetch(url)` |
+
+### Platform Bindings
+
+| Binding | Use Case | Access Pattern |
+|---------|----------|----------------|
+| **Analytics Engine** | Custom metrics | `env.ANALYTICS.writeDataPoint(data)` |
+| **mTLS** | Client certificates | `env.MY_CERT` (string) |
+| **Hyperdrive** | Database pooling | `env.HYPERDRIVE.connectionString` |
+| **Rate Limiting** | Request throttling | `env.RATE_LIMITER.limit(id)` |
+| **Workflows** | Long-running workflows | `env.MY_WORKFLOW.create()` |
+
+### Configuration Bindings
+
+| Binding | Use Case | Access Pattern |
+|---------|----------|----------------|
+| **Environment Variables** | Non-sensitive config | `env.API_URL` (string) |
+| **Secrets** | Sensitive values | `env.API_KEY` (string) |
+| **Text/Data Blobs** | Static files | `env.MY_BLOB` (string) |
+| **WASM** | WebAssembly modules | `env.MY_WASM` (WebAssembly.Module) |
+
+## Quick Selection Guide
+
+**Need persistent storage?**
+- Key-value < 25MB → **KV**
+- Files/objects → **R2**
+- Relational data → **D1**
+- Real-time coordination → **Durable Objects**
+
+**Need AI/compute?**
+- LLM inference → **Workers AI**
+- Scraping/PDFs → **Browser Rendering**
+- Call another Worker → **Service binding**
+
+**Need async processing?**
+- Background jobs → **Queues**
+
+**Need config?**
+- Public values → **Environment Variables**
+- Secrets → **Secrets** (never commit)
+
+## Quick Start
+
+1. **Add binding to wrangler.jsonc:**
+```jsonc
+{
+  "kv_namespaces": [
+    { "binding": "MY_KV", "id": "your-kv-id" }
+  ]
+}
+```
+
+2. **Generate types:**
+```bash
+npx wrangler types
+```
+
+3. **Access in Worker:**
+```typescript
+export default {
+  async fetch(request, env, ctx) {
+    await env.MY_KV.put('key', 'value');
+    return new Response('OK');
+  }
+}
+```
+
+## Type Safety
+
+Bindings are fully typed via `wrangler types`. See [api.md](api.md) for details.
+
+## Limits
+
+- 64 bindings max per Worker (all types combined)
+- See [gotchas.md](gotchas.md) for per-binding limits
+
+## Key Concepts
+
+**Zero-overhead access:** Bindings compiled into Worker, no network calls to access
+**Type-safe:** Full TypeScript support via `wrangler types`
+**Per-environment:** Different IDs for dev/staging/production
+**Secrets vs Vars:** Secrets encrypted at rest, never in config files
+
+## See Also
+
+- [Cloudflare Docs: Bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/)
+- [Wrangler Configuration](https://developers.cloudflare.com/workers/wrangler/configuration/)

package/skills/cloudflare/references/bindings/api.md

@@ -0,0 +1,203 @@
+# Bindings API Reference
+
+## TypeScript Types
+
+Cloudflare generates binding types via `npx wrangler types`. This creates `.wrangler/types/runtime.d.ts` with your Env interface.
+
+### Generated Env Interface
+
+After running `wrangler types`, TypeScript knows your bindings:
+
+```typescript
+interface Env {
+  // From wrangler.jsonc bindings
+  MY_KV: KVNamespace;
+  MY_BUCKET: R2Bucket;
+  DB: D1Database;
+  MY_SERVICE: Fetcher;
+  AI: Ai;
+  
+  // From vars
+  API_URL: string;
+  
+  // From secrets (set via wrangler secret put)
+  API_KEY: string;
+}
+```
+
+### Binding Types
+
+| Config | TypeScript Type | Package |
+|--------|-----------------|---------|
+| `kv_namespaces` | `KVNamespace` | `@cloudflare/workers-types` |
+| `r2_buckets` | `R2Bucket` | `@cloudflare/workers-types` |
+| `d1_databases` | `D1Database` | `@cloudflare/workers-types` |
+| `durable_objects.bindings` | `DurableObjectNamespace` | `@cloudflare/workers-types` |
+| `vectorize` | `VectorizeIndex` | `@cloudflare/workers-types` |
+| `queues.producers` | `Queue` | `@cloudflare/workers-types` |
+| `services` | `Fetcher` | `@cloudflare/workers-types` |
+| `ai` | `Ai` | `@cloudflare/workers-types` |
+| `browser` | `Fetcher` | `@cloudflare/workers-types` |
+| `analytics_engine_datasets` | `AnalyticsEngineDataset` | `@cloudflare/workers-types` |
+| `hyperdrive` | `Hyperdrive` | `@cloudflare/workers-types` |
+| `rate_limiting` | `RateLimit` | `@cloudflare/workers-types` |
+| `workflows` | `Workflow` | `@cloudflare/workers-types` |
+| `mtls_certificates` / `vars` / `text_blobs` / `data_blobs` | `string` | Built-in |
+| `wasm_modules` | `WebAssembly.Module` | Built-in |
+
+## Accessing Bindings
+
+### Method 1: fetch() Handler (Recommended)
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const value = await env.MY_KV.get('key');
+    return new Response(value);
+  }
+}
+```
+
+**Why:** Type-safe, aligns with Workers API, supports ctx for waitUntil/passThroughOnException.
+
+### Method 2: Hono Framework
+
+```typescript
+import { Hono } from 'hono';
+
+const app = new Hono<{ Bindings: Env }>();
+
+app.get('/', async (c) => {
+  const value = await c.env.MY_KV.get('key');
+  return c.json({ value });
+});
+
+export default app;
+```
+
+**Why:** c.env auto-typed, ergonomic for routing-heavy apps.
+
+### Method 3: Module Workers (Legacy)
+
+```typescript
+export async function handleRequest(request: Request, env: Env): Promise<Response> {
+  const value = await env.MY_KV.get('key');
+  return new Response(value);
+}
+
+addEventListener('fetch', (event) => {
+  // env not directly available - requires workarounds
+});
+```
+
+**Avoid:** Use fetch() handler instead (Method 1).
+
+## Type Generation Workflow
+
+### Initial Setup
+
+```bash
+# Install wrangler
+npm install -D wrangler
+
+# Generate types from wrangler.jsonc
+npx wrangler types
+```
+
+### After Changing Bindings
+
+```bash
+# Added/modified binding in wrangler.jsonc
+npx wrangler types
+
+# TypeScript now sees updated Env interface
+```
+
+**Note:** `wrangler types` outputs to `.wrangler/types/runtime.d.ts`. TypeScript picks this up automatically if `@cloudflare/workers-types` is in `tsconfig.json` `"types"` array.
+
+## Key Binding Methods
+
+**KV:**
+```typescript
+await env.MY_KV.get(key, { type: 'json' });  // text|json|arrayBuffer|stream
+await env.MY_KV.put(key, value, { expirationTtl: 3600 });
+await env.MY_KV.delete(key);
+await env.MY_KV.list({ prefix: 'user:' });
+```
+
+**R2:**
+```typescript
+await env.BUCKET.get(key);
+await env.BUCKET.put(key, value);
+await env.BUCKET.delete(key);
+await env.BUCKET.list({ prefix: 'images/' });
+```
+
+**D1:**
+```typescript
+await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();
+await env.DB.batch([stmt1, stmt2]);
+```
+
+**Service:**
+```typescript
+await env.MY_SERVICE.fetch(new Request('https://fake/path'));
+```
+
+**Workers AI:**
+```typescript
+await env.AI.run('@cf/meta/llama-3.1-8b-instruct', { prompt: 'Hello' });
+```
+
+**Queues:**
+```typescript
+await env.MY_QUEUE.send({ userId: 123, action: 'process' });
+```
+
+**Durable Objects:**
+```typescript
+const id = env.MY_DO.idFromName('user-123');
+const stub = env.MY_DO.get(id);
+await stub.fetch(new Request('https://fake/increment'));
+```
+
+## Runtime vs Build-Time Types
+
+| Type Source | When Generated | Use Case |
+|-------------|----------------|----------|
+| `@cloudflare/workers-types` | npm install | Base Workers APIs (Request, Response, etc.) |
+| `wrangler types` | After config change | Your specific bindings (Env interface) |
+
+**Install both:**
+```bash
+npm install -D @cloudflare/workers-types
+npx wrangler types
+```
+
+## Type Safety Best Practices
+
+1. **Never use `any` for env:**
+```typescript
+// ❌ BAD
+async fetch(request: Request, env: any) { }
+
+// ✅ GOOD
+async fetch(request: Request, env: Env) { }
+```
+
+2. **Run wrangler types after config changes:**
+```bash
+# After editing wrangler.jsonc
+npx wrangler types
+```
+
+3. **Check generated types match config:**
+```bash
+# View generated Env interface
+cat .wrangler/types/runtime.d.ts
+```
+
+## See Also
+
+- [Workers Types Package](https://www.npmjs.com/package/@cloudflare/workers-types)
+- [Wrangler Types Command](https://developers.cloudflare.com/workers/wrangler/commands/#types)