@ngxtm/devkit 3.7.0 → 3.9.0

package/merged-commands/browser-extension-builder.md

@@ -0,0 +1,261 @@
+---
+name: browser-extension-builder
+description: "Expert in building browser extensions that solve real problems - Chrome, Firefox, and cross-browser extensions. Covers extension architecture, manifest v3, content scripts, popup UIs, monetization strategies, and Chrome Web Store publishing. Use when: browser extension, chrome extension, firefox addon, extension, manifest v3."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# Browser Extension Builder
+
+**Role**: Browser Extension Architect
+
+You extend the browser to give users superpowers. You understand the
+unique constraints of extension development - permissions, security,
+store policies. You build extensions that people install and actually
+use daily. You know the difference between a toy and a tool.
+
+## Capabilities
+
+- Extension architecture
+- Manifest v3 (MV3)
+- Content scripts
+- Background workers
+- Popup interfaces
+- Extension monetization
+- Chrome Web Store publishing
+- Cross-browser support
+
+## Patterns
+
+### Extension Architecture
+
+Structure for modern browser extensions
+
+**When to use**: When starting a new extension
+
+```javascript
+## Extension Architecture
+
+### Project Structure
+```
+extension/
+├── manifest.json      # Extension config
+├── popup/
+│   ├── popup.html     # Popup UI
+│   ├── popup.css
+│   └── popup.js
+├── content/
+│   └── content.js     # Runs on web pages
+├── background/
+│   └── service-worker.js  # Background logic
+├── options/
+│   ├── options.html   # Settings page
+│   └── options.js
+└── icons/
+    ├── icon16.png
+    ├── icon48.png
+    └── icon128.png
+```
+
+### Manifest V3 Template
+```json
+{
+  "manifest_version": 3,
+  "name": "My Extension",
+  "version": "1.0.0",
+  "description": "What it does",
+  "permissions": ["storage", "activeTab"],
+  "action": {
+    "default_popup": "popup/popup.html",
+    "default_icon": {
+      "16": "icons/icon16.png",
+      "48": "icons/icon48.png",
+      "128": "icons/icon128.png"
+    }
+  },
+  "content_scripts": [{
+    "matches": ["<all_urls>"],
+    "js": ["content/content.js"]
+  }],
+  "background": {
+    "service_worker": "background/service-worker.js"
+  },
+  "options_page": "options/options.html"
+}
+```
+
+### Communication Pattern
+```
+Popup ←→ Background (Service Worker) ←→ Content Script
+              ↓
+        chrome.storage
+```
+```
+
+### Content Scripts
+
+Code that runs on web pages
+
+**When to use**: When modifying or reading page content
+
+```javascript
+## Content Scripts
+
+### Basic Content Script
+```javascript
+// content.js - Runs on every matched page
+
+// Wait for page to load
+document.addEventListener('DOMContentLoaded', () => {
+  // Modify the page
+  const element = document.querySelector('.target');
+  if (element) {
+    element.style.backgroundColor = 'yellow';
+  }
+});
+
+// Listen for messages from popup/background
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  if (message.action === 'getData') {
+    const data = document.querySelector('.data')?.textContent;
+    sendResponse({ data });
+  }
+  return true; // Keep channel open for async
+});
+```
+
+### Injecting UI
+```javascript
+// Create floating UI on page
+function injectUI() {
+  const container = document.createElement('div');
+  container.id = 'my-extension-ui';
+  container.innerHTML = `
+    <div style="position: fixed; bottom: 20px; right: 20px;
+                background: white; padding: 16px; border-radius: 8px;
+                box-shadow: 0 4px 12px rgba(0,0,0,0.15); z-index: 10000;">
+      <h3>My Extension</h3>
+      <button id="my-extension-btn">Click me</button>
+    </div>
+  `;
+  document.body.appendChild(container);
+
+  document.getElementById('my-extension-btn').addEventListener('click', () => {
+    // Handle click
+  });
+}
+
+injectUI();
+```
+
+### Permissions for Content Scripts
+```json
+{
+  "content_scripts": [{
+    "matches": ["https://specific-site.com/*"],
+    "js": ["content.js"],
+    "run_at": "document_end"
+  }]
+}
+```
+```
+
+### Storage and State
+
+Persisting extension data
+
+**When to use**: When saving user settings or data
+
+```javascript
+## Storage and State
+
+### Chrome Storage API
+```javascript
+// Save data
+chrome.storage.local.set({ key: 'value' }, () => {
+  console.log('Saved');
+});
+
+// Get data
+chrome.storage.local.get(['key'], (result) => {
+  console.log(result.key);
+});
+
+// Sync storage (syncs across devices)
+chrome.storage.sync.set({ setting: true });
+
+// Watch for changes
+chrome.storage.onChanged.addListener((changes, area) => {
+  if (changes.key) {
+    console.log('key changed:', changes.key.newValue);
+  }
+});
+```
+
+### Storage Limits
+| Type | Limit |
+|------|-------|
+| local | 5MB |
+| sync | 100KB total, 8KB per item |
+
+### Async/Await Pattern
+```javascript
+// Modern async wrapper
+async function getStorage(keys) {
+  return new Promise((resolve) => {
+    chrome.storage.local.get(keys, resolve);
+  });
+}
+
+async function setStorage(data) {
+  return new Promise((resolve) => {
+    chrome.storage.local.set(data, resolve);
+  });
+}
+
+// Usage
+const { settings } = await getStorage(['settings']);
+await setStorage({ settings: { ...settings, theme: 'dark' } });
+```
+```
+
+## Anti-Patterns
+
+### ❌ Requesting All Permissions
+
+**Why bad**: Users won't install.
+Store may reject.
+Security risk.
+Bad reviews.
+
+**Instead**: Request minimum needed.
+Use optional permissions.
+Explain why in description.
+Request at time of use.
+
+### ❌ Heavy Background Processing
+
+**Why bad**: MV3 terminates idle workers.
+Battery drain.
+Browser slows down.
+Users uninstall.
+
+**Instead**: Keep background minimal.
+Use alarms for periodic tasks.
+Offload to content scripts.
+Cache aggressively.
+
+### ❌ Breaking on Updates
+
+**Why bad**: Selectors change.
+APIs change.
+Angry users.
+Bad reviews.
+
+**Instead**: Use stable selectors.
+Add error handling.
+Monitor for breakage.
+Update quickly when broken.
+
+## Related Skills
+
+Works well with: `frontend`, `micro-saas-launcher`, `personal-tool-builder`

package/merged-commands/building-ai-agent-on-cloudflare.md

@@ -0,0 +1,391 @@
+---
+name: building-ai-agent-on-cloudflare
+description: |
+  Builds AI agents on Cloudflare using the Agents SDK with state management,
+  real-time WebSockets, scheduled tasks, tool integration, and chat capabilities.
+  Generates production-ready agent code deployed to Workers.
+
+  Use when: user wants to "build an agent", "AI agent", "chat agent", "stateful
+  agent", mentions "Agents SDK", needs "real-time AI", "WebSocket AI", or asks
+  about agent "state management", "scheduled tasks", or "tool calling".
+---
+
+# Building Cloudflare Agents
+
+Creates AI-powered agents using Cloudflare's Agents SDK with persistent state, real-time communication, and tool integration.
+
+## When to Use
+
+- User wants to build an AI agent or chatbot
+- User needs stateful, real-time AI interactions
+- User asks about the Cloudflare Agents SDK
+- User wants scheduled tasks or background AI work
+- User needs WebSocket-based AI communication
+
+## Prerequisites
+
+- Cloudflare account with Workers enabled
+- Node.js 18+ and npm/pnpm/yarn
+- Wrangler CLI (`npm install -g wrangler`)
+
+## Quick Start
+
+```bash
+npm create cloudflare@latest -- my-agent --template=cloudflare/agents-starter
+cd my-agent
+npm start
+```
+
+Agent runs at `http://localhost:8787`
+
+## Core Concepts
+
+### What is an Agent?
+
+An Agent is a stateful, persistent AI service that:
+- Maintains state across requests and reconnections
+- Communicates via WebSockets or HTTP
+- Runs on Cloudflare's edge via Durable Objects
+- Can schedule tasks and call tools
+- Scales horizontally (each user/session gets own instance)
+
+### Agent Lifecycle
+
+```
+Client connects → Agent.onConnect() → Agent processes messages
+                                    → Agent.onMessage()
+                                    → Agent.setState() (persists + syncs)
+Client disconnects → State persists → Client reconnects → State restored
+```
+
+## Basic Agent Structure
+
+```typescript
+import { Agent, Connection } from "agents";
+
+interface Env {
+  AI: Ai;  // Workers AI binding
+}
+
+interface State {
+  messages: Array<{ role: string; content: string }>;
+  preferences: Record<string, string>;
+}
+
+export class MyAgent extends Agent<Env, State> {
+  // Initial state for new instances
+  initialState: State = {
+    messages: [],
+    preferences: {},
+  };
+
+  // Called when agent starts or resumes
+  async onStart() {
+    console.log("Agent started with state:", this.state);
+  }
+
+  // Handle WebSocket connections
+  async onConnect(connection: Connection) {
+    connection.send(JSON.stringify({
+      type: "welcome",
+      history: this.state.messages,
+    }));
+  }
+
+  // Handle incoming messages
+  async onMessage(connection: Connection, message: string) {
+    const data = JSON.parse(message);
+
+    if (data.type === "chat") {
+      await this.handleChat(connection, data.content);
+    }
+  }
+
+  // Handle disconnections
+  async onClose(connection: Connection) {
+    console.log("Client disconnected");
+  }
+
+  // React to state changes
+  onStateUpdate(state: State, source: string) {
+    console.log("State updated by:", source);
+  }
+
+  private async handleChat(connection: Connection, userMessage: string) {
+    // Add user message to history
+    const messages = [
+      ...this.state.messages,
+      { role: "user", content: userMessage },
+    ];
+
+    // Call AI
+    const response = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
+      messages,
+    });
+
+    // Update state (persists and syncs to all clients)
+    this.setState({
+      ...this.state,
+      messages: [
+        ...messages,
+        { role: "assistant", content: response.response },
+      ],
+    });
+
+    // Send response
+    connection.send(JSON.stringify({
+      type: "response",
+      content: response.response,
+    }));
+  }
+}
+```
+
+## Entry Point Configuration
+
+```typescript
+// src/index.ts
+import { routeAgentRequest } from "agents";
+import { MyAgent } from "./agent";
+
+export default {
+  async fetch(request: Request, env: Env) {
+    // routeAgentRequest handles routing to /agents/:class/:name
+    return (
+      (await routeAgentRequest(request, env)) ||
+      new Response("Not found", { status: 404 })
+    );
+  },
+};
+
+export { MyAgent };
+```
+
+Clients connect via: `wss://my-agent.workers.dev/agents/MyAgent/session-id`
+
+## Wrangler Configuration
+
+```toml
+name = "my-agent"
+main = "src/index.ts"
+compatibility_date = "2024-12-01"
+
+[ai]
+binding = "AI"
+
+[durable_objects]
+bindings = [{ name = "AGENT", class_name = "MyAgent" }]
+
+[[migrations]]
+tag = "v1"
+new_classes = ["MyAgent"]
+```
+
+## State Management
+
+### Reading State
+
+```typescript
+// Current state is always available
+const currentMessages = this.state.messages;
+const userPrefs = this.state.preferences;
+```
+
+### Updating State
+
+```typescript
+// setState persists AND syncs to all connected clients
+this.setState({
+  ...this.state,
+  messages: [...this.state.messages, newMessage],
+});
+
+// Partial updates work too
+this.setState({
+  preferences: { ...this.state.preferences, theme: "dark" },
+});
+```
+
+### SQL Storage
+
+For complex queries, use the embedded SQLite database:
+
+```typescript
+// Create tables
+await this.sql`
+  CREATE TABLE IF NOT EXISTS documents (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    title TEXT NOT NULL,
+    content TEXT,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+  )
+`;
+
+// Insert
+await this.sql`
+  INSERT INTO documents (title, content)
+  VALUES (${title}, ${content})
+`;
+
+// Query
+const docs = await this.sql`
+  SELECT * FROM documents WHERE title LIKE ${`%${search}%`}
+`;
+```
+
+## Scheduled Tasks
+
+Agents can schedule future work:
+
+```typescript
+async onMessage(connection: Connection, message: string) {
+  const data = JSON.parse(message);
+
+  if (data.type === "schedule_reminder") {
+    // Schedule task for 1 hour from now
+    const { id } = await this.schedule(3600, "sendReminder", {
+      message: data.reminderText,
+      userId: data.userId,
+    });
+
+    connection.send(JSON.stringify({ type: "scheduled", taskId: id }));
+  }
+}
+
+// Called when scheduled task fires
+async sendReminder(data: { message: string; userId: string }) {
+  // Send notification, email, etc.
+  console.log(`Reminder for ${data.userId}: ${data.message}`);
+
+  // Can also update state
+  this.setState({
+    ...this.state,
+    lastReminder: new Date().toISOString(),
+  });
+}
+```
+
+### Schedule Options
+
+```typescript
+// Delay in seconds
+await this.schedule(60, "taskMethod", { data });
+
+// Specific date
+await this.schedule(new Date("2025-01-01T00:00:00Z"), "taskMethod", { data });
+
+// Cron expression (recurring)
+await this.schedule("0 9 * * *", "dailyTask", {});  // 9 AM daily
+await this.schedule("*/5 * * * *", "everyFiveMinutes", {});  // Every 5 min
+
+// Manage schedules
+const schedules = await this.getSchedules();
+await this.cancelSchedule(taskId);
+```
+
+## Chat Agent (AI-Powered)
+
+For chat-focused agents, extend `AIChatAgent`:
+
+```typescript
+import { AIChatAgent } from "agents/ai-chat-agent";
+
+export class ChatBot extends AIChatAgent<Env> {
+  // Called for each user message
+  async onChatMessage(message: string) {
+    const response = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
+      messages: [
+        { role: "system", content: "You are a helpful assistant." },
+        ...this.messages,  // Automatic history management
+        { role: "user", content: message },
+      ],
+      stream: true,
+    });
+
+    // Stream response back to client
+    return response;
+  }
+}
+```
+
+Features included:
+- Automatic message history
+- Resumable streaming (survives disconnects)
+- Built-in `saveMessages()` for persistence
+
+## Client Integration
+
+### React Hook
+
+```tsx
+import { useAgent } from "agents/react";
+
+function Chat() {
+  const { state, send, connected } = useAgent({
+    agent: "my-agent",
+    name: userId,  // Agent instance ID
+  });
+
+  const sendMessage = (text: string) => {
+    send(JSON.stringify({ type: "chat", content: text }));
+  };
+
+  return (
+    <div>
+      {state.messages.map((msg, i) => (
+        <div key={i}>{msg.role}: {msg.content}</div>
+      ))}
+      <input onKeyDown={(e) => e.key === "Enter" && sendMessage(e.target.value)} />
+    </div>
+  );
+}
+```
+
+### Vanilla JavaScript
+
+```javascript
+const ws = new WebSocket("wss://my-agent.workers.dev/agents/MyAgent/user123");
+
+ws.onopen = () => {
+  console.log("Connected to agent");
+};
+
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  console.log("Received:", data);
+};
+
+ws.send(JSON.stringify({ type: "chat", content: "Hello!" }));
+```
+
+## Common Patterns
+
+See [references/agent-patterns.md](references/agent-patterns.md) for:
+- Tool calling and function execution
+- Multi-agent orchestration
+- RAG (Retrieval Augmented Generation)
+- Human-in-the-loop workflows
+
+## Deployment
+
+```bash
+# Deploy
+npx wrangler deploy
+
+# View logs
+wrangler tail
+
+# Test endpoint
+curl https://my-agent.workers.dev/agents/MyAgent/test-user
+```
+
+## Troubleshooting
+
+See [references/troubleshooting.md](references/troubleshooting.md) for common issues.
+
+## References
+
+- [references/examples.md](references/examples.md) — Official templates and production examples
+- [references/agent-patterns.md](references/agent-patterns.md) — Advanced patterns
+- [references/state-patterns.md](references/state-patterns.md) — State management strategies
+- [references/troubleshooting.md](references/troubleshooting.md) — Error solutions