opencode-starterkit 1.0.1

package/baseline/skill/cloudflare/references/pulumi/README.md

@@ -0,0 +1,107 @@
+# Cloudflare Pulumi Provider
+
+Expert guidance for Cloudflare Pulumi Provider (@pulumi/cloudflare).
+
+## Overview
+
+Programmatic management of Cloudflare resources: Workers, Pages, D1, KV, R2, DNS, Queues, etc.
+
+**Packages:**
+- TypeScript/JS: `@pulumi/cloudflare`
+- Python: `pulumi-cloudflare`
+- Go: `github.com/pulumi/pulumi-cloudflare/sdk/v6/go/cloudflare`
+- .NET: `Pulumi.Cloudflare`
+
+**Version:** v6.x
+
+## Core Principles
+
+1. Use API tokens (not legacy API keys)
+2. Store accountId in stack config
+3. Match binding names across code/config
+4. Use `module: true` for ES modules
+5. Set `compatibilityDate` to lock behavior
+
+## Authentication
+
+Three methods (mutually exclusive):
+
+**1. API Token (Recommended)**
+```typescript
+import * as cloudflare from "@pulumi/cloudflare";
+
+const provider = new cloudflare.Provider("cf", {
+    apiToken: process.env.CLOUDFLARE_API_TOKEN,
+});
+```
+Env: `CLOUDFLARE_API_TOKEN`
+
+**2. API Key (Legacy)**
+```typescript
+const provider = new cloudflare.Provider("cf", {
+    apiKey: process.env.CLOUDFLARE_API_KEY,
+    email: process.env.CLOUDFLARE_EMAIL,
+});
+```
+Env: `CLOUDFLARE_API_KEY`, `CLOUDFLARE_EMAIL`
+
+**3. API User Service Key**
+```typescript
+const provider = new cloudflare.Provider("cf", {
+    apiUserServiceKey: process.env.CLOUDFLARE_API_USER_SERVICE_KEY,
+});
+```
+Env: `CLOUDFLARE_API_USER_SERVICE_KEY`
+
+## Setup
+
+**Pulumi.yaml:**
+```yaml
+name: my-cloudflare-app
+runtime: nodejs
+config:
+  cloudflare:apiToken:
+    value: ${CLOUDFLARE_API_TOKEN}
+```
+
+**Pulumi.<stack>.yaml:**
+```yaml
+config:
+  cloudflare:accountId: "abc123..."
+```
+
+**index.ts:**
+```typescript
+import * as pulumi from "@pulumi/pulumi";
+import * as cloudflare from "@pulumi/cloudflare";
+
+const config = new pulumi.Config("cloudflare");
+const accountId = config.require("accountId");
+```
+
+## Essential Imports
+```typescript
+import * as pulumi from "@pulumi/pulumi";
+import * as cloudflare from "@pulumi/cloudflare";
+```
+
+## Common Resource Types
+- `Provider` - Provider config
+- `WorkerScript` - Worker
+- `WorkersKvNamespace` - KV
+- `R2Bucket` - R2
+- `D1Database` - D1
+- `Queue` - Queue
+- `PagesProject` - Pages
+- `DnsRecord` - DNS
+- `WorkerRoute` - Worker route
+- `WorkersDomain` - Custom domain
+
+## Key Properties
+- `accountId` - Required for most resources
+- `zoneId` - Required for DNS/domain
+- `name`/`title` - Resource identifier
+- `*Bindings` - Connect resources to Workers
+
+---
+See: [configuration.md](./configuration.md), [api.md](./api.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)

package/baseline/skill/cloudflare/references/pulumi/api.md

@@ -0,0 +1,194 @@
+# API & Data Sources
+
+## Outputs and Exports
+
+Export resource identifiers:
+
+```typescript
+export const kvId = kv.id;
+export const bucketName = bucket.name;
+export const workerUrl = worker.subdomain;
+export const dbId = db.id;
+```
+
+## Resource Dependencies
+
+Implicit dependencies via outputs:
+
+```typescript
+const kv = new cloudflare.WorkersKvNamespace("kv", {
+    accountId: accountId,
+    title: "my-kv",
+});
+
+// Worker depends on KV (implicit via kv.id)
+const worker = new cloudflare.WorkerScript("worker", {
+    accountId: accountId,
+    name: "my-worker",
+    content: code,
+    kvNamespaceBindings: [{name: "MY_KV", namespaceId: kv.id}], // Creates dependency
+});
+```
+
+Explicit dependencies:
+
+```typescript
+const migration = new command.local.Command("migration", {
+    create: pulumi.interpolate`wrangler d1 execute ${db.name} --file ./schema.sql`,
+}, {dependsOn: [db]});
+
+const worker = new cloudflare.WorkerScript("worker", {
+    accountId: accountId,
+    name: "worker",
+    content: code,
+    d1DatabaseBindings: [{name: "DB", databaseId: db.id}],
+}, {dependsOn: [migration]}); // Ensure migrations run first
+```
+
+## Using Outputs with API Calls
+
+```typescript
+const db = new cloudflare.D1Database("db", {
+    accountId: accountId,
+    name: "my-db",
+});
+
+db.id.apply(async (dbId) => {
+    const response = await fetch(
+        `https://api.cloudflare.com/client/v4/accounts/${accountId}/d1/database/${dbId}/query`,
+        {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${apiToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({sql: "CREATE TABLE users (id INT PRIMARY KEY, name TEXT)"}),
+        }
+    );
+    return response.json();
+});
+```
+
+## Custom Dynamic Providers
+
+For resources not in provider:
+
+```typescript
+import * as pulumi from "@pulumi/pulumi";
+
+class D1MigrationProvider implements pulumi.dynamic.ResourceProvider {
+    async create(inputs: any): Promise<pulumi.dynamic.CreateResult> {
+        const response = await fetch(
+            `https://api.cloudflare.com/client/v4/accounts/${inputs.accountId}/d1/database/${inputs.databaseId}/query`,
+            {
+                method: "POST",
+                headers: {
+                    "Authorization": `Bearer ${inputs.apiToken}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({sql: inputs.sql}),
+            }
+        );
+        const result = await response.json();
+        return {id: `${inputs.databaseId}-${Date.now()}`, outs: result};
+    }
+
+    async update(id: string, olds: any, news: any): Promise<pulumi.dynamic.UpdateResult> {
+        if (olds.sql !== news.sql) await this.create(news);
+        return {};
+    }
+
+    async delete(id: string, props: any): Promise<void> {}
+}
+
+class D1Migration extends pulumi.dynamic.Resource {
+    constructor(name: string, args: any, opts?: pulumi.CustomResourceOptions) {
+        super(new D1MigrationProvider(), name, args, opts);
+    }
+}
+
+// Usage
+const migration = new D1Migration("migration", {
+    accountId: accountId,
+    databaseId: db.id,
+    apiToken: apiToken,
+    sql: "CREATE TABLE users (id INT PRIMARY KEY, name TEXT)",
+}, {dependsOn: [db]});
+```
+
+## Data Sources
+
+**Get Zone:**
+```typescript
+const zone = cloudflare.getZone({name: "example.com"});
+const zoneId = zone.then(z => z.id);
+```
+
+**Get Accounts (via API):**
+Use Cloudflare API directly or custom dynamic resources.
+
+## Import Existing Resources
+
+```bash
+# Import worker
+pulumi import cloudflare:index/workerScript:WorkerScript my-worker <account_id>/<worker_name>
+
+# Import KV namespace
+pulumi import cloudflare:index/workersKvNamespace:WorkersKvNamespace my-kv <namespace_id>
+
+# Import R2 bucket
+pulumi import cloudflare:index/r2Bucket:R2Bucket my-bucket <account_id>/<bucket_name>
+
+# Import D1 database
+pulumi import cloudflare:index/d1Database:D1Database my-db <account_id>/<database_id>
+
+# Import DNS record
+pulumi import cloudflare:index/dnsRecord:DnsRecord my-record <zone_id>/<record_id>
+```
+
+## Secrets Management
+
+```typescript
+import * as pulumi from "@pulumi/pulumi";
+
+const config = new pulumi.Config();
+const apiKey = config.requireSecret("apiKey"); // Encrypted in state
+
+const worker = new cloudflare.WorkerScript("worker", {
+    accountId: accountId,
+    name: "my-worker",
+    content: code,
+    secretTextBindings: [{name: "API_KEY", text: apiKey}],
+});
+```
+
+Store secrets:
+```bash
+pulumi config set --secret apiKey "secret-value"
+```
+
+## Transform Pattern
+
+Modify resource args before creation:
+
+```typescript
+import {Transform} from "@pulumi/pulumi";
+
+interface BucketArgs {
+    accountId: pulumi.Input<string>;
+    transform?: {bucket?: Transform<cloudflare.R2BucketArgs>};
+}
+
+function createBucket(name: string, args: BucketArgs) {
+    const bucketArgs: cloudflare.R2BucketArgs = {
+        accountId: args.accountId,
+        name: name,
+        location: "auto",
+    };
+    const finalArgs = args.transform?.bucket?.(bucketArgs) ?? bucketArgs;
+    return new cloudflare.R2Bucket(name, finalArgs);
+}
+```
+
+---
+See: [README.md](./README.md), [configuration.md](./configuration.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)

package/baseline/skill/cloudflare/references/pulumi/configuration.md

@@ -0,0 +1,216 @@
+# Resource Configuration
+
+## Workers (cloudflare.WorkerScript)
+
+```typescript
+import * as cloudflare from "@pulumi/cloudflare";
+import * as fs from "fs";
+
+const worker = new cloudflare.WorkerScript("my-worker", {
+    accountId: accountId,
+    name: "my-worker",
+    content: fs.readFileSync("./dist/worker.js", "utf8"),
+    module: true, // ES modules
+    compatibilityDate: "2024-01-01",
+    compatibilityFlags: ["nodejs_compat"],
+    
+    // Bindings
+    kvNamespaceBindings: [{name: "MY_KV", namespaceId: kv.id}],
+    r2BucketBindings: [{name: "MY_BUCKET", bucketName: bucket.name}],
+    d1DatabaseBindings: [{name: "DB", databaseId: db.id}],
+    queueBindings: [{name: "MY_QUEUE", queue: queue.id}],
+    serviceBindings: [{name: "OTHER_SERVICE", service: other.name}],
+    plainTextBindings: [{name: "ENV_VAR", text: "value"}],
+    secretTextBindings: [{name: "API_KEY", text: secret}],
+});
+```
+
+## Workers KV (cloudflare.WorkersKvNamespace)
+
+```typescript
+const kv = new cloudflare.WorkersKvNamespace("my-kv", {
+    accountId: accountId,
+    title: "my-kv-namespace",
+});
+
+// Write values
+const kvValue = new cloudflare.WorkersKvValue("config", {
+    accountId: accountId,
+    namespaceId: kv.id,
+    key: "config",
+    value: JSON.stringify({foo: "bar"}),
+});
+```
+
+## R2 Buckets (cloudflare.R2Bucket)
+
+```typescript
+const bucket = new cloudflare.R2Bucket("my-bucket", {
+    accountId: accountId,
+    name: "my-bucket",
+    location: "auto", // or "wnam", etc.
+});
+```
+
+## D1 Databases (cloudflare.D1Database)
+
+```typescript
+const db = new cloudflare.D1Database("my-db", {
+    accountId: accountId,
+    name: "my-database",
+});
+
+// Migrations: use command or wrangler
+import * as command from "@pulumi/command";
+
+const migration = new command.local.Command("d1-migration", {
+    create: pulumi.interpolate`wrangler d1 execute ${db.name} --command "CREATE TABLE users (id INT PRIMARY KEY, name TEXT)"`,
+}, {dependsOn: [db]});
+```
+
+## Queues (cloudflare.Queue)
+
+```typescript
+const queue = new cloudflare.Queue("my-queue", {
+    accountId: accountId,
+    name: "my-queue",
+});
+
+// Producer
+const producer = new cloudflare.WorkerScript("producer", {
+    accountId: accountId,
+    name: "producer",
+    content: code,
+    queueBindings: [{name: "MY_QUEUE", queue: queue.id}],
+});
+
+// Consumer
+const consumer = new cloudflare.WorkerScript("consumer", {
+    accountId: accountId,
+    name: "consumer",
+    content: code,
+    queueConsumers: [{
+        queue: queue.name,
+        maxBatchSize: 10,
+        maxRetries: 3,
+        maxWaitTimeMs: 5000,
+    }],
+});
+```
+
+## Pages Projects (cloudflare.PagesProject)
+
+```typescript
+const pages = new cloudflare.PagesProject("my-site", {
+    accountId: accountId,
+    name: "my-site",
+    productionBranch: "main",
+    buildConfig: {
+        buildCommand: "npm run build",
+        destinationDir: "dist",
+        rootDir: "",
+    },
+    source: {
+        type: "github",
+        config: {
+            owner: "my-org",
+            repoName: "my-repo",
+            productionBranch: "main",
+            prCommentsEnabled: true,
+            deploymentsEnabled: true,
+        },
+    },
+    deploymentConfigs: {
+        production: {
+            environmentVariables: {NODE_VERSION: "18"},
+            kvNamespaces: {MY_KV: kv.id},
+            d1Databases: {DB: db.id},
+            r2Buckets: {MY_BUCKET: bucket.name},
+        },
+    },
+});
+```
+
+## DNS Records (cloudflare.DnsRecord)
+
+```typescript
+const zone = cloudflare.getZone({name: "example.com"});
+
+const record = new cloudflare.DnsRecord("www", {
+    zoneId: zone.then(z => z.id),
+    name: "www",
+    type: "A",
+    content: "192.0.2.1",
+    ttl: 3600,
+    proxied: true,
+});
+
+// CNAME
+const cname = new cloudflare.DnsRecord("api", {
+    zoneId: zone.then(z => z.id),
+    name: "api",
+    type: "CNAME",
+    content: worker.subdomain,
+    proxied: true,
+});
+```
+
+## Workers Domains/Routes
+
+```typescript
+// Route (pattern-based)
+const route = new cloudflare.WorkerRoute("my-route", {
+    zoneId: zoneId,
+    pattern: "example.com/api/*",
+    scriptName: worker.name,
+});
+
+// Domain (dedicated subdomain)
+const domain = new cloudflare.WorkersDomain("my-domain", {
+    accountId: accountId,
+    hostname: "api.example.com",
+    service: worker.name,
+    zoneId: zoneId,
+});
+```
+
+## Multi-Language Examples
+
+**Python:**
+```python
+import pulumi
+import pulumi_cloudflare as cloudflare
+
+config = pulumi.Config()
+account_id = config.require("accountId")
+
+kv = cloudflare.WorkersKvNamespace("my-kv", account_id=account_id, title="my-kv")
+worker = cloudflare.WorkerScript("my-worker", account_id=account_id, name="my-worker", 
+    content=open("./dist/worker.js").read(), module=True,
+    kv_namespace_bindings=[cloudflare.WorkerScriptKvNamespaceBindingArgs(name="MY_KV", namespace_id=kv.id)])
+```
+
+**Go:**
+```go
+import (
+    "github.com/pulumi/pulumi-cloudflare/sdk/v6/go/cloudflare"
+    "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
+    "github.com/pulumi/pulumi/sdk/v3/go/pulumi/config"
+)
+
+func main() {
+    pulumi.Run(func(ctx *pulumi.Context) error {
+        cfg := config.New(ctx, "")
+        accountId := cfg.Require("accountId")
+        
+        kv, _ := cloudflare.NewWorkersKvNamespace(ctx, "my-kv", &cloudflare.WorkersKvNamespaceArgs{
+            AccountId: pulumi.String(accountId),
+            Title: pulumi.String("my-kv"),
+        })
+        return nil
+    })
+}
+```
+
+---
+See: [README.md](./README.md), [api.md](./api.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)