npm - @stella-studio/ck - Versions diffs - 1.0.0 - Mend

@stella-studio/ck 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 (1202) hide show

package/.claude/skills/devops/references/browser-rendering.md ADDED Viewed

@@ -0,0 +1,305 @@
+# Cloudflare Browser Rendering
+Headless browser automation with Puppeteer/Playwright on Cloudflare Workers.
+## Setup
+**wrangler.toml:**
+```toml
+name = "browser-worker"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+browser = { binding = "MYBROWSER" }
+```
+## Basic Screenshot Worker
+```typescript
+import puppeteer from '@cloudflare/puppeteer';
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const browser = await puppeteer.launch(env.MYBROWSER);
+    const page = await browser.newPage();
+    await page.goto('https://example.com', { waitUntil: 'networkidle2' });
+    const screenshot = await page.screenshot({ type: 'png' });
+    await browser.close();
+    return new Response(screenshot, {
+      headers: { 'Content-Type': 'image/png' }
+    });
+  }
+};
+```
+## Session Reuse (Cost Optimization)
+```typescript
+// Disconnect instead of close
+await browser.disconnect();
+// Retrieve and reconnect
+const sessions = await puppeteer.sessions(env.MYBROWSER);
+const freeSession = sessions.find(s => !s.connectionId);
+if (freeSession) {
+  const browser = await puppeteer.connect(env.MYBROWSER, freeSession.sessionId);
+}
+```
+## PDF Generation
+```typescript
+const browser = await puppeteer.launch(env.MYBROWSER);
+const page = await browser.newPage();
+await page.setContent(`
+  <!DOCTYPE html>
+  <html>
+    <head>
+      <style>
+        body { font-family: Arial; padding: 50px; }
+        h1 { color: #2c3e50; }
+      </style>
+    </head>
+    <body>
+      <h1>Certificate</h1>
+      <p>Awarded to: <strong>John Doe</strong></p>
+    </body>
+  </html>
+`);
+const pdf = await page.pdf({
+  format: 'A4',
+  printBackground: true,
+  margin: { top: '1cm', right: '1cm', bottom: '1cm', left: '1cm' }
+});
+await browser.close();
+return new Response(pdf, {
+  headers: { 'Content-Type': 'application/pdf' }
+});
+```
+## Durable Objects for Persistent Sessions
+```typescript
+export class Browser {
+  state: DurableObjectState;
+  browser: any;
+  lastUsed: number;
+  constructor(state: DurableObjectState, env: Env) {
+    this.state = state;
+    this.lastUsed = Date.now();
+  }
+  async fetch(request: Request, env: Env) {
+    if (!this.browser) {
+      this.browser = await puppeteer.launch(env.MYBROWSER);
+    }
+    this.lastUsed = Date.now();
+    await this.state.storage.setAlarm(Date.now() + 10000);
+    const page = await this.browser.newPage();
+    const url = new URL(request.url).searchParams.get('url');
+    await page.goto(url);
+    const screenshot = await page.screenshot();
+    await page.close();
+    return new Response(screenshot, {
+      headers: { 'Content-Type': 'image/png' }
+    });
+  }
+  async alarm() {
+    if (Date.now() - this.lastUsed > 60000) {
+      await this.browser?.close();
+      this.browser = null;
+    } else {
+      await this.state.storage.setAlarm(Date.now() + 10000);
+    }
+  }
+}
+```
+## AI-Powered Web Scraper
+```typescript
+import { Ai } from '@cloudflare/ai';
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const browser = await puppeteer.launch(env.MYBROWSER);
+    const page = await browser.newPage();
+    await page.goto('https://news.ycombinator.com');
+    const content = await page.content();
+    await browser.close();
+    const ai = new Ai(env.AI);
+    const response = await ai.run('@cf/meta/llama-3-8b-instruct', {
+      messages: [
+        {
+          role: 'system',
+          content: 'Extract top 5 article titles and URLs as JSON'
+        },
+        { role: 'user', content: content }
+      ]
+    });
+    return Response.json(response);
+  }
+};
+```
+## Crawler with Queues
+```typescript
+export default {
+  async queue(batch: MessageBatch<any>, env: Env): Promise<void> {
+    const browser = await puppeteer.launch(env.MYBROWSER);
+    for (const message of batch.messages) {
+      const page = await browser.newPage();
+      await page.goto(message.body.url);
+      const links = await page.evaluate(() => {
+        return Array.from(document.querySelectorAll('a')).map(a => a.href);
+      });
+      for (const link of links) {
+        await env.QUEUE.send({ url: link });
+      }
+      await page.close();
+      message.ack();
+    }
+    await browser.close();
+  }
+};
+```
+## Configuration
+### Timeout
+```typescript
+await page.goto(url, {
+  timeout: 60000,  // 60 seconds max
+  waitUntil: 'networkidle2'
+});
+await page.waitForSelector('.content', { timeout: 45000 });
+```
+### Viewport
+```typescript
+await page.setViewport({ width: 1920, height: 1080 });
+```
+### Screenshot Options
+```typescript
+const screenshot = await page.screenshot({
+  type: 'png',       // 'png' | 'jpeg' | 'webp'
+  quality: 90,       // JPEG/WebP only
+  fullPage: true,    // Full scrollable page
+  clip: {            // Crop
+    x: 0, y: 0,
+    width: 800,
+    height: 600
+  }
+});
+```
+## Limits & Pricing
+### Free Plan
+- 10 minutes/day
+- 3 concurrent browsers
+- 3 new browsers/minute
+### Paid Plan
+- 10 hours/month included
+- 30 concurrent browsers
+- 30 new browsers/minute
+- $0.09/hour overage
+- $2.00/concurrent browser overage
+### Cost Optimization
+1. Use `disconnect()` instead of `close()`
+2. Enable Keep-Alive (10 min max)
+3. Pool tabs with browser contexts
+4. Cache auth state with KV
+5. Implement Durable Objects cleanup
+## Best Practices
+### Session Management
+- Always use `disconnect()` for reuse
+- Implement session pooling
+- Track session IDs and states
+### Performance
+- Cache content in KV
+- Use browser contexts vs multiple browsers
+- Choose appropriate `waitUntil` strategy
+- Set realistic timeouts
+### Error Handling
+- Handle timeout errors gracefully
+- Check session availability before connecting
+- Validate responses before caching
+### Security
+- Validate user-provided URLs
+- Implement authentication
+- Sanitize extracted content
+- Set appropriate CORS headers
+## Troubleshooting
+**Timeout Errors:**
+```typescript
+await page.goto(url, {
+  timeout: 60000,
+  waitUntil: 'domcontentloaded'  // Faster than networkidle2
+});
+```
+**Memory Issues:**
+```typescript
+await page.close();  // Close pages
+await browser.disconnect();  // Reuse session
+```
+**Font Rendering:**
+Use supported fonts (Noto Sans, Roboto, etc.) or inject custom:
+```html
+<link href="https://fonts.googleapis.com/css2?family=Poppins" rel="stylesheet">
+```
+## Key Methods
+### Puppeteer
+- `puppeteer.launch(binding)` - Start browser
+- `puppeteer.connect(binding, sessionId)` - Reconnect
+- `puppeteer.sessions(binding)` - List sessions
+- `browser.newPage()` - Create page
+- `browser.disconnect()` - Disconnect (keep alive)
+- `browser.close()` - Close (terminate)
+- `page.goto(url, options)` - Navigate
+- `page.screenshot(options)` - Capture
+- `page.pdf(options)` - Generate PDF
+- `page.content()` - Get HTML
+- `page.evaluate(fn)` - Execute JS
+## Resources
+- Docs: https://developers.cloudflare.com/browser-rendering/
+- Puppeteer: https://pptr.dev/
+- Examples: https://developers.cloudflare.com/workers/examples/

package/.claude/skills/devops/references/cloudflare-d1-kv.md ADDED Viewed

@@ -0,0 +1,123 @@
+# Cloudflare D1 & KV
+## D1 (SQLite Database)
+### Setup
+```bash
+# Create database
+wrangler d1 create my-database
+# Add to wrangler.toml
+[[d1_databases]]
+binding = "DB"
+database_name = "my-database"
+database_id = "YOUR_DATABASE_ID"
+# Apply schema
+wrangler d1 execute my-database --file=./schema.sql
+```
+### Usage
+```typescript
+// Query
+const result = await env.DB.prepare(
+  "SELECT * FROM users WHERE id = ?"
+).bind(userId).first();
+// Insert
+await env.DB.prepare(
+  "INSERT INTO users (name, email) VALUES (?, ?)"
+).bind("Alice", "alice@example.com").run();
+// Batch (atomic)
+await env.DB.batch([
+  env.DB.prepare("UPDATE accounts SET balance = balance - 100 WHERE id = ?").bind(user1),
+  env.DB.prepare("UPDATE accounts SET balance = balance + 100 WHERE id = ?").bind(user2)
+]);
+// All results
+const { results } = await env.DB.prepare("SELECT * FROM users").all();
+```
+### Features
+- Global read replication (low-latency reads)
+- Single-writer consistency
+- Standard SQLite syntax
+- 25GB database size limit
+- ACID transactions with batch
+## KV (Key-Value Store)
+### Setup
+```bash
+# Create namespace
+wrangler kv:namespace create MY_KV
+# Add to wrangler.toml
+[[kv_namespaces]]
+binding = "KV"
+id = "YOUR_NAMESPACE_ID"
+```
+### Usage
+```typescript
+// Put with TTL
+await env.KV.put("session:token", JSON.stringify(data), {
+  expirationTtl: 3600,
+  metadata: { userId: "123" }
+});
+// Get
+const value = await env.KV.get("session:token");
+const json = await env.KV.get("session:token", "json");
+const buffer = await env.KV.get("session:token", "arrayBuffer");
+const stream = await env.KV.get("session:token", "stream");
+// Get with metadata
+const { value, metadata } = await env.KV.getWithMetadata("session:token");
+// Delete
+await env.KV.delete("session:token");
+// List
+const list = await env.KV.list({ prefix: "user:" });
+```
+### Features
+- Sub-millisecond reads (edge-cached)
+- Eventual consistency (~60 seconds globally)
+- 25MB value size limit
+- Automatic expiration (TTL)
+## Use Cases
+### D1
+- Relational data
+- Complex queries with JOINs
+- ACID transactions
+- User accounts, orders, inventory
+### KV
+- Cache
+- Sessions
+- Feature flags
+- Rate limiting
+- Real-time counters
+## Decision Matrix
+| Need | Choose |
+|------|--------|
+| SQL queries | D1 |
+| Sub-millisecond reads | KV |
+| ACID transactions | D1 |
+| Large values (>25MB) | R2 |
+| Strong consistency | D1 (writes), Durable Objects |
+| Automatic expiration | KV |
+## Resources
+- D1: https://developers.cloudflare.com/d1/
+- KV: https://developers.cloudflare.com/kv/

package/.claude/skills/devops/references/cloudflare-platform.md ADDED Viewed

@@ -0,0 +1,271 @@
+# Cloudflare Platform Overview
+Cloudflare Developer Platform: comprehensive edge computing ecosystem for full-stack applications on global network across 300+ cities.
+## Core Concepts
+### Edge Computing Model
+**Global Network:**
+- Code runs on servers in 300+ cities globally
+- Requests execute from nearest location
+- Ultra-low latency (<50ms typical)
+- Automatic failover and redundancy
+**V8 Isolates:**
+- Lightweight execution environments (faster than containers)
+- Millisecond cold starts
+- Zero infrastructure management
+- Automatic scaling
+- Pay-per-request pricing
+### Key Components
+**Workers** - Serverless functions on edge
+- HTTP/scheduled/queue/email handlers
+- JavaScript/TypeScript/Python/Rust support
+- Max 50ms CPU (free), 30s (paid)
+- 128MB memory limit
+**D1** - SQLite database with global read replication
+- Standard SQLite syntax
+- Single-writer consistency
+- Global read replication
+- 25GB database size limit
+- Batch operations for transactions
+**KV** - Distributed key-value store
+- Sub-millisecond reads (edge-cached)
+- Eventual consistency (~60s globally)
+- 25MB value size limit
+- Automatic TTL expiration
+- Best for: cache, sessions, feature flags
+**R2** - Object storage (S3-compatible)
+- Zero egress fees (huge cost advantage)
+- Unlimited storage
+- 5TB object size limit
+- S3-compatible API
+- Multipart upload support
+**Durable Objects** - Stateful compute with WebSockets
+- Single-instance coordination (strong consistency)
+- Persistent storage (1GB limit paid)
+- WebSocket support
+- Automatic hibernation
+**Queues** - Message queue system
+- At-least-once delivery
+- Automatic retries (exponential backoff)
+- Dead-letter queue support
+- Batch processing
+**Pages** - Static site hosting + serverless functions
+- Git integration (auto-deploy)
+- Directory-based routing
+- Framework support (Next.js, Remix, Astro, SvelteKit)
+- Built-in preview deployments
+**Workers AI** - Run AI models on edge
+- LLMs (Llama 3, Mistral, Gemma, Qwen)
+- Image generation (Stable Diffusion, DALL-E)
+- Embeddings (BGE, GTE)
+- Speech recognition (Whisper)
+- No GPU management required
+**Browser Rendering** - Headless browser automation
+- Puppeteer/Playwright support
+- Screenshots, PDFs, web scraping
+- Session reuse for cost optimization
+- MCP server support for AI agents
+## Architecture Patterns
+### Full-Stack Application
+```
+┌─────────────────────────────────────────┐
+│    Cloudflare Pages (Frontend)          │
+│    Next.js / Remix / Astro               │
+└──────────────────┬──────────────────────┘
+                   │
+┌──────────────────▼──────────────────────┐
+│    Workers (API Layer)                   │
+│    - Routing                             │
+│    - Authentication                      │
+│    - Business logic                      │
+└─┬──────┬──────┬──────┬──────┬───────────┘
+  │      │      │      │      │
+  ▼      ▼      ▼      ▼      ▼
+┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────────────┐
+│ D1 │ │ KV │ │ R2 │ │ DO │ │ Workers AI │
+└────┘ └────┘ └────┘ └────┘ └────────────┘
+```
+### Polyglot Storage Pattern
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    // KV: Fast cache
+    const cached = await env.KV.get(key);
+    if (cached) return new Response(cached);
+    // D1: Structured data
+    const user = await env.DB.prepare(
+      "SELECT * FROM users WHERE id = ?"
+    ).bind(userId).first();
+    // R2: Media files
+    const avatar = await env.R2_BUCKET.get(`avatars/${user.id}.jpg`);
+    // Durable Objects: Real-time
+    const chat = env.CHAT_ROOM.get(env.CHAT_ROOM.idFromName(roomId));
+    // Queue: Async processing
+    await env.EMAIL_QUEUE.send({ to: user.email, template: 'welcome' });
+    return new Response(JSON.stringify({ user }));
+  }
+};
+```
+## Wrangler CLI Essentials
+### Installation
+```bash
+npm install -g wrangler
+wrangler login
+wrangler init my-worker
+```
+### Core Commands
+```bash
+# Development
+wrangler dev                    # Local dev server
+wrangler dev --remote          # Dev on real edge
+# Deployment
+wrangler deploy                # Deploy to production
+wrangler deploy --dry-run      # Preview changes
+# Logs
+wrangler tail                  # Real-time logs
+wrangler tail --format pretty  # Formatted logs
+# Versions
+wrangler deployments list      # List deployments
+wrangler rollback [version]    # Rollback
+# Secrets
+wrangler secret put SECRET_NAME
+wrangler secret list
+```
+### Resource Management
+```bash
+# D1
+wrangler d1 create my-db
+wrangler d1 execute my-db --file=schema.sql
+# KV
+wrangler kv:namespace create MY_KV
+wrangler kv:key put --binding=MY_KV "key" "value"
+# R2
+wrangler r2 bucket create my-bucket
+wrangler r2 object put my-bucket/file.txt --file=./file.txt
+```
+## Configuration (wrangler.toml)
+```toml
+name = "my-worker"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+# Environment variables
+[vars]
+ENVIRONMENT = "production"
+# D1 Database
+[[d1_databases]]
+binding = "DB"
+database_name = "my-database"
+database_id = "YOUR_DATABASE_ID"
+# KV Namespace
+[[kv_namespaces]]
+binding = "KV"
+id = "YOUR_NAMESPACE_ID"
+# R2 Bucket
+[[r2_buckets]]
+binding = "R2_BUCKET"
+bucket_name = "my-bucket"
+# Durable Objects
+[[durable_objects.bindings]]
+name = "COUNTER"
+class_name = "Counter"
+script_name = "my-worker"
+# Queues
+[[queues.producers]]
+binding = "MY_QUEUE"
+queue = "my-queue"
+# Workers AI
+[ai]
+binding = "AI"
+# Cron triggers
+[triggers]
+crons = ["0 0 * * *"]
+```
+## Best Practices
+### Performance
+- Keep Workers lightweight (<1MB bundled)
+- Use bindings over fetch (faster than HTTP)
+- Leverage KV and Cache API for frequently accessed data
+- Use D1 batch for multiple queries
+- Stream large responses
+### Security
+- Use `wrangler secret` for API keys
+- Separate production/staging/development environments
+- Validate user input
+- Implement rate limiting (KV or Durable Objects)
+- Configure proper CORS headers
+### Cost Optimization
+- R2 for large files (zero egress fees vs S3)
+- KV for caching (reduce D1/R2 requests)
+- Request deduplication with caching
+- Efficient D1 queries (proper indexing)
+- Monitor usage via Cloudflare Analytics
+## Decision Matrix
+| Need | Choose |
+|------|--------|
+| Sub-millisecond reads | KV |
+| SQL queries | D1 |
+| Large files (>25MB) | R2 |
+| Real-time WebSockets | Durable Objects |
+| Async background jobs | Queues |
+| ACID transactions | D1 |
+| Strong consistency | Durable Objects |
+| Zero egress costs | R2 |
+| AI inference | Workers AI |
+| Static site hosting | Pages |
+## Resources
+- Docs: https://developers.cloudflare.com
+- Wrangler: https://developers.cloudflare.com/workers/wrangler/
+- Discord: https://discord.cloudflare.com
+- Examples: https://developers.cloudflare.com/workers/examples/
+- Status: https://www.cloudflarestatus.com