memory-journal-mcp 7.7.0 → 8.0.0

package/skills/cloudflare/references/sandbox/patterns.md

@@ -0,0 +1,195 @@
+# Common Patterns
+
+## AI Code Execution with Code Context
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const { code, variables } = await request.json()
+    const sandbox = getSandbox(env.Sandbox, 'ai-agent')
+
+    // Create context with persistent variables
+    const ctx = await sandbox.createCodeContext({
+      language: 'python',
+      variables: variables || {},
+    })
+
+    // Execute with rich outputs (text, images, HTML)
+    const result = await ctx.runCode(code)
+
+    return Response.json({
+      outputs: result.outputs, // [{ type: 'text'|'image'|'html', content }]
+      error: result.error,
+      success: !result.error,
+    })
+  },
+}
+```
+
+## Interactive Dev Environment
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const proxyResponse = await proxyToSandbox(request, env)
+    if (proxyResponse) return proxyResponse
+
+    const sandbox = getSandbox(env.Sandbox, 'ide', { normalizeId: true })
+
+    if (request.url.endsWith('/start')) {
+      await sandbox.exec('curl -fsSL https://code-server.dev/install.sh | sh')
+      await sandbox.startProcess('code-server --bind-addr 0.0.0.0:8080', {
+        processId: 'vscode',
+      })
+
+      const exposed = await sandbox.exposePort(8080)
+      return Response.json({ url: exposed.url })
+    }
+
+    return new Response('Try /start')
+  },
+}
+```
+
+## WebSocket Real-Time Service
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const proxyResponse = await proxyToSandbox(request, env)
+    if (proxyResponse) return proxyResponse
+
+    if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket') {
+      const sandbox = getSandbox(env.Sandbox, 'realtime-service')
+      return await sandbox.wsConnect(request, 8080)
+    }
+
+    // Non-WebSocket: expose preview URL
+    const sandbox = getSandbox(env.Sandbox, 'realtime-service')
+    const { url } = await sandbox.exposePort(8080, {
+      hostname: new URL(request.url).hostname,
+    })
+    return Response.json({ wsUrl: url.replace('https', 'wss') })
+  },
+}
+```
+
+**Dockerfile**:
+
+```dockerfile
+FROM docker.io/cloudflare/sandbox:latest
+RUN npm install -g ws
+EXPOSE 8080
+```
+
+## Process Readiness Pattern
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const sandbox = getSandbox(env.Sandbox, 'app-server')
+
+    // Start server
+    const process = await sandbox.startProcess('node server.js', { processId: 'server' })
+
+    // Wait for server to be ready
+    await process.waitForPort(8080) // Wait for port listening
+
+    // Now safe to expose
+    const { url } = await sandbox.exposePort(8080)
+    return Response.json({ url })
+  },
+}
+```
+
+## Persistent Data with Bucket Mounting
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const sandbox = getSandbox(env.Sandbox, 'data-processor')
+
+    // Mount R2 bucket (production only)
+    await sandbox.mountBucket(env.DATA_BUCKET, '/data', {
+      readOnly: false,
+    })
+
+    // Process files in bucket
+    const result = await sandbox.exec('python3 /workspace/process.py', {
+      env: { DATA_DIR: '/data/input' },
+    })
+
+    // Results written to /data/output are persisted in R2
+    return Response.json({ success: result.success })
+  },
+}
+```
+
+## CI/CD Pipeline
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const { repo, branch } = await request.json()
+    const sandbox = getSandbox(env.Sandbox, `ci-${repo}-${Date.now()}`)
+
+    await sandbox.exec(`git clone -b ${branch} ${repo} /workspace/repo`)
+
+    const install = await sandbox.exec('npm install', {
+      cwd: '/workspace/repo',
+      stream: true,
+      onOutput: (stream, data) => console.log(data),
+    })
+
+    if (!install.success) {
+      return Response.json({ success: false, error: 'Install failed' })
+    }
+
+    const test = await sandbox.exec('npm test', { cwd: '/workspace/repo' })
+
+    return Response.json({
+      success: test.success,
+      output: test.stdout,
+      exitCode: test.exitCode,
+    })
+  },
+}
+```
+
+## Multi-Tenant Pattern
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const userId = request.headers.get('X-User-ID')
+    const sandbox = getSandbox(env.Sandbox, 'multi-tenant')
+
+    // Each user gets isolated session
+    let session
+    try {
+      session = await sandbox.getSession(userId)
+    } catch {
+      session = await sandbox.createSession({
+        id: userId,
+        cwd: `/workspace/users/${userId}`,
+        env: { USER_ID: userId },
+      })
+    }
+
+    const code = await request.text()
+    const result = await session.exec(`python3 -c "${code}"`)
+
+    return Response.json({ output: result.stdout })
+  },
+}
+```
+
+## Git Operations
+
+```typescript
+// Clone repo
+await sandbox.exec('git clone https://github.com/user/repo.git /workspace/repo')
+
+// Authenticated (use env secrets)
+await sandbox.exec(`git clone https://${env.GITHUB_TOKEN}@github.com/user/repo.git`)
+```

package/skills/cloudflare/references/secrets-store/README.md

@@ -0,0 +1,77 @@
+# Cloudflare Secrets Store
+
+Account-level encrypted secret management for Workers and AI Gateway.
+
+## Overview
+
+**Secrets Store**: Centralized, account-level secrets, reusable across Workers
+**Worker Secrets**: Per-Worker secrets (`wrangler secret put`)
+
+### Architecture
+
+- **Store**: Container (1/account in beta)
+- **Secret**: String ≤1024 bytes
+- **Scopes**: Permission boundaries controlling access
+  - `workers`: For Workers runtime access
+  - `ai-gateway`: For AI Gateway access
+  - Secrets must have correct scope for binding to work
+- **Bindings**: Connect secrets via `env` object
+
+**Regional Availability**: Global except China Network (unavailable)
+
+### Access Control
+
+- **Super Admin**: Full access
+- **Admin**: Create/edit/delete secrets, view metadata
+- **Deployer**: View metadata + bindings
+- **Reporter**: View metadata only
+
+API Token permissions: `Account Secrets Store Edit/Read`
+
+### Limits (Beta)
+
+- 100 secrets/account
+- 1 store/account
+- 1024 bytes max/secret
+- Production secrets count toward limit
+
+## When to Use
+
+**Use Secrets Store when:**
+
+- Multiple Workers share same credential
+- Centralized management needed
+- Compliance requires audit trail
+- Team collaboration on secrets
+
+**Use Worker Secrets when:**
+
+- Secret unique to one Worker
+- Simple single-Worker project
+- No cross-Worker sharing needed
+
+## In This Reference
+
+### Reading Order by Task
+
+| Task                     | Start Here                   | Then Read        |
+| ------------------------ | ---------------------------- | ---------------- |
+| Quick overview           | README.md                    | -                |
+| First-time setup         | README.md → configuration.md | api.md           |
+| Add secret to Worker     | configuration.md             | api.md           |
+| Implement access pattern | api.md                       | patterns.md      |
+| Debug errors             | gotchas.md                   | api.md           |
+| Secret rotation          | patterns.md                  | configuration.md |
+| Best practices           | gotchas.md                   | patterns.md      |
+
+### Files
+
+- [configuration.md](./configuration.md) - Wrangler commands, binding config
+- [api.md](./api.md) - Binding API, get/put/delete operations
+- [patterns.md](./patterns.md) - Rotation, encryption, access control
+- [gotchas.md](./gotchas.md) - Security issues, limits, best practices
+
+## See Also
+
+- [workers](../workers/) - Worker bindings integration
+- [wrangler](../wrangler/) - CLI secret management commands

package/skills/cloudflare/references/secrets-store/api.md

@@ -0,0 +1,199 @@
+# API Reference
+
+## Binding API
+
+### Basic Access
+
+**CRITICAL**: Async `.get()` required - secrets NOT directly available.
+
+**`.get()` throws on error** - does NOT return null. Always use try/catch.
+
+```typescript
+interface Env {
+  API_KEY: { get(): Promise<string> }
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const apiKey = await env.API_KEY.get()
+    return fetch('https://api.example.com', {
+      headers: { Authorization: `Bearer ${apiKey}` },
+    })
+  },
+}
+```
+
+### Error Handling
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    try {
+      const apiKey = await env.API_KEY.get()
+      return fetch('https://api.example.com', {
+        headers: { Authorization: `Bearer ${apiKey}` },
+      })
+    } catch (error) {
+      console.error('Secret access failed:', error)
+      return new Response('Configuration error', { status: 500 })
+    }
+  },
+}
+```
+
+### Multiple Secrets & Patterns
+
+```typescript
+// Parallel fetch
+const [stripeKey, sendgridKey] = await Promise.all([env.STRIPE_KEY.get(), env.SENDGRID_KEY.get()])
+
+// ❌ Missing .get()
+const key = env.API_KEY
+
+// ❌ Module-level cache
+const CACHED_KEY = await env.API_KEY.get() // Fails
+
+// ✅ Request-scope cache
+const key = await env.API_KEY.get() // OK - reuse within request
+```
+
+## REST API
+
+Base: `https://api.cloudflare.com/client/v4`
+
+### Auth
+
+```bash
+curl -H "Authorization: Bearer $CF_TOKEN" \
+  https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/secrets_store/stores
+```
+
+### Store Operations
+
+```bash
+# List
+GET /accounts/{account_id}/secrets_store/stores
+
+# Create
+POST /accounts/{account_id}/secrets_store/stores
+{"name": "my-store"}
+
+# Delete
+DELETE /accounts/{account_id}/secrets_store/stores/{store_id}
+```
+
+### Secret Operations
+
+```bash
+# List
+GET /accounts/{account_id}/secrets_store/stores/{store_id}/secrets
+
+# Create (single)
+POST /accounts/{account_id}/secrets_store/stores/{store_id}/secrets
+{
+  "name": "my_secret",
+  "value": "secret_value",
+  "scopes": ["workers"],
+  "comment": "Optional"
+}
+
+# Create (batch)
+POST /accounts/{account_id}/secrets_store/stores/{store_id}/secrets
+[
+  {"name": "secret_one", "value": "val1", "scopes": ["workers"]},
+  {"name": "secret_two", "value": "val2", "scopes": ["workers", "ai-gateway"]}
+]
+
+# Get metadata
+GET /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}
+
+# Update
+PATCH /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}
+{"value": "new_value", "comment": "Updated"}
+
+# Delete (single)
+DELETE /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}
+
+# Delete (batch)
+DELETE /accounts/{account_id}/secrets_store/stores/{store_id}/secrets
+{"secret_ids": ["id-1", "id-2"]}
+
+# Duplicate
+POST /accounts/{account_id}/secrets_store/stores/{store_id}/secrets/{secret_id}/duplicate
+{"name": "new_name"}
+
+# Quota
+GET /accounts/{account_id}/secrets_store/quota
+```
+
+### Responses
+
+Success:
+
+```json
+{
+  "success": true,
+  "result": {
+    "id": "secret-id-123",
+    "name": "my_secret",
+    "created": "2025-01-11T12:00:00Z",
+    "scopes": ["workers"]
+  }
+}
+```
+
+Error:
+
+```json
+{
+  "success": false,
+  "errors": [{ "code": 10000, "message": "Name exists" }]
+}
+```
+
+## TypeScript Helpers
+
+Official types available via `@cloudflare/workers-types`:
+
+```typescript
+import type { SecretsStoreSecret } from '@cloudflare/workers-types'
+
+interface Env {
+  STRIPE_API_KEY: SecretsStoreSecret
+  DATABASE_URL: SecretsStoreSecret
+  WORKER_SECRET: string // Regular Worker secret (direct access)
+}
+```
+
+Custom helper type:
+
+```typescript
+interface SecretsStoreBinding {
+  get(): Promise<string>
+}
+
+// Fallback helper
+async function getSecretWithFallback(
+  primary: SecretsStoreBinding,
+  fallback?: SecretsStoreBinding
+): Promise<string> {
+  try {
+    return await primary.get()
+  } catch (error) {
+    if (fallback) return await fallback.get()
+    throw error
+  }
+}
+
+// Batch helper
+async function getAllSecrets(
+  secrets: Record<string, SecretsStoreBinding>
+): Promise<Record<string, string>> {
+  const entries = await Promise.all(
+    Object.entries(secrets).map(async ([k, v]) => [k, await v.get()])
+  )
+  return Object.fromEntries(entries)
+}
+```
+
+See: [configuration.md](./configuration.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)

package/skills/cloudflare/references/secrets-store/configuration.md

@@ -0,0 +1,187 @@
+# Configuration
+
+## Wrangler Config
+
+### Basic Binding
+
+**wrangler.jsonc**:
+
+```jsonc
+{
+  "secrets_store_secrets": [
+    {
+      "binding": "API_KEY",
+      "store_id": "abc123",
+      "secret_name": "stripe_api_key",
+    },
+  ],
+}
+```
+
+**wrangler.toml** (alternative):
+
+```toml
+[[secrets_store_secrets]]
+binding = "API_KEY"
+store_id = "abc123"
+secret_name = "stripe_api_key"
+```
+
+Fields:
+
+- `binding`: Variable name for `env` access
+- `store_id`: From `wrangler secrets-store store list`
+- `secret_name`: Identifier (no spaces)
+
+### Environment-Specific
+
+**wrangler.jsonc**:
+
+```jsonc
+{
+  "env": {
+    "production": {
+      "secrets_store_secrets": [
+        {
+          "binding": "API_KEY",
+          "store_id": "prod-store",
+          "secret_name": "prod_api_key",
+        },
+      ],
+    },
+    "staging": {
+      "secrets_store_secrets": [
+        {
+          "binding": "API_KEY",
+          "store_id": "staging-store",
+          "secret_name": "staging_api_key",
+        },
+      ],
+    },
+  },
+}
+```
+
+**wrangler.toml** (alternative):
+
+```toml
+[env.production]
+[[env.production.secrets_store_secrets]]
+binding = "API_KEY"
+store_id = "prod-store"
+secret_name = "prod_api_key"
+
+[env.staging]
+[[env.staging.secrets_store_secrets]]
+binding = "API_KEY"
+store_id = "staging-store"
+secret_name = "staging_api_key"
+```
+
+## Wrangler Commands
+
+### Store Management
+
+```bash
+wrangler secrets-store store list
+wrangler secrets-store store create my-store --remote
+wrangler secrets-store store delete <store-id> --remote
+```
+
+### Secret Management (Production)
+
+```bash
+# Create (interactive)
+wrangler secrets-store secret create <store-id> \
+  --name MY_SECRET --scopes workers --remote
+
+# Create (piped)
+cat secret.txt | wrangler secrets-store secret create <store-id> \
+  --name MY_SECRET --scopes workers --remote
+
+# List/get/update/delete
+wrangler secrets-store secret list <store-id> --remote
+wrangler secrets-store secret get <store-id> --name MY_SECRET --remote
+wrangler secrets-store secret update <store-id> --name MY_SECRET --new-value "val" --remote
+wrangler secrets-store secret delete <store-id> --name MY_SECRET --remote
+
+# Duplicate
+wrangler secrets-store secret duplicate <store-id> \
+  --name ORIG --new-name COPY --remote
+```
+
+### Local Development
+
+**CRITICAL**: Production secrets (`--remote`) NOT accessible in local dev.
+
+```bash
+# Create local-only (no --remote)
+wrangler secrets-store secret create <store-id> --name DEV_KEY --scopes workers
+
+wrangler dev    # Uses local secrets
+wrangler deploy # Uses production secrets
+```
+
+Best practice: Separate names for local/prod:
+
+```jsonc
+{
+  "env": {
+    "development": {
+      "secrets_store_secrets": [
+        { "binding": "API_KEY", "store_id": "store", "secret_name": "dev_api_key" },
+      ],
+    },
+    "production": {
+      "secrets_store_secrets": [
+        { "binding": "API_KEY", "store_id": "store", "secret_name": "prod_api_key" },
+      ],
+    },
+  },
+}
+```
+
+## Dashboard
+
+### Creating Secrets
+
+1. **Secrets Store** → **Create secret**
+2. Fill: Name (no spaces), Value, Scope (`Workers`), Comment
+3. **Save** (value hidden after)
+
+### Adding Bindings
+
+**Method 1**: Worker → Settings → Bindings → Add → Secrets Store
+**Method 2**: Create secret directly from Worker settings dropdown
+
+Deploy options:
+
+- **Deploy**: Immediate 100%
+- **Save version**: Gradual rollout
+
+## CI/CD
+
+### GitHub Actions
+
+```yaml
+- name: Create secret
+  env:
+    CLOUDFLARE_API_TOKEN: ${{ secrets.CF_TOKEN }}
+  run: |
+    echo "${{ secrets.API_KEY }}" | \
+    npx wrangler secrets-store secret create $STORE_ID \
+      --name API_KEY --scopes workers --remote
+
+- name: Deploy
+  run: npx wrangler deploy
+```
+
+### GitLab CI
+
+```yaml
+script:
+  - echo "$API_KEY_VALUE" | npx wrangler secrets-store secret create $STORE_ID --name API_KEY --scopes workers --remote
+  - npx wrangler deploy
+```
+
+See: [api.md](./api.md), [patterns.md](./patterns.md)