@musashishao/agent-kit 1.8.2 → 1.9.1

package/.agent/skills/gcp-cloud-run/SKILL.md

@@ -0,0 +1,358 @@
+---
+name: gcp-cloud-run
+description: "Google Cloud Run and Cloud Functions patterns. Covers containerized deployments, Cloud Functions Gen2, Firestore, Pub/Sub, and Terraform/Pulumi IaC."
+version: "1.0.0"
+---
+
+# ☁️ GCP Cloud Run
+
+You are a Google Cloud expert who has deployed production applications on Cloud Run and Cloud Functions. You understand the container-based model, scaling behavior, and GCP service integrations.
+
+---
+
+## When to Use This Skill
+
+- Deploying containerized apps with Cloud Run
+- Event-driven processing with Cloud Functions Gen2
+- Firestore/Bigtable data modeling
+- Pub/Sub message queues
+- Cloud Build CI/CD pipelines
+
+---
+
+## Capabilities
+
+- `cloud-run`
+- `cloud-functions`
+- `firestore`
+- `pub-sub`
+- `cloud-build`
+- `artifact-registry`
+- `cloud-tasks`
+- `cloud-scheduler`
+
+---
+
+## 1. Cloud Run Patterns
+
+### Dockerfile for Cloud Run
+
+```dockerfile
+# Dockerfile
+FROM node:20-slim AS builder
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+COPY . .
+RUN npm run build
+
+# Production image
+FROM node:20-slim
+
+ENV NODE_ENV=production
+WORKDIR /app
+
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY package*.json ./
+
+# Cloud Run uses PORT env var
+EXPOSE 8080
+CMD ["node", "dist/server.js"]
+```
+
+### Node.js Server
+
+```javascript
+// server.js
+const express = require('express');
+const { Firestore } = require('@google-cloud/firestore');
+
+const app = express();
+app.use(express.json());
+
+// Initialize outside request handler
+const firestore = new Firestore();
+const collection = firestore.collection('users');
+
+app.get('/users/:id', async (req, res) => {
+  try {
+    const doc = await collection.doc(req.params.id).get();
+    
+    if (!doc.exists) {
+      return res.status(404).json({ error: 'User not found' });
+    }
+    
+    res.json({ id: doc.id, ...doc.data() });
+  } catch (error) {
+    console.error('Error:', error);
+    res.status(500).json({ error: error.message });
+  }
+});
+
+app.post('/users', async (req, res) => {
+  try {
+    const docRef = await collection.add(req.body);
+    res.status(201).json({ id: docRef.id });
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+
+// Cloud Run provides PORT
+const PORT = process.env.PORT || 8080;
+app.listen(PORT, () => {
+  console.log(`Server running on port ${PORT}`);
+});
+```
+
+### Deploy Command
+
+```bash
+# Build and push
+gcloud builds submit --tag gcr.io/$PROJECT_ID/my-service
+
+# Deploy
+gcloud run deploy my-service \
+  --image gcr.io/$PROJECT_ID/my-service \
+  --platform managed \
+  --region us-central1 \
+  --allow-unauthenticated \
+  --min-instances 1 \
+  --max-instances 100 \
+  --memory 512Mi \
+  --cpu 1 \
+  --set-env-vars "NODE_ENV=production"
+```
+
+---
+
+## 2. Cloud Functions Gen2 Pattern
+
+```javascript
+// index.js
+const functions = require('@google-cloud/functions-framework');
+const { Firestore } = require('@google-cloud/firestore');
+
+const firestore = new Firestore();
+
+// HTTP function
+functions.http('helloHttp', async (req, res) => {
+  const name = req.query.name || req.body.name || 'World';
+  res.json({ message: `Hello, ${name}!` });
+});
+
+// Cloud Event function (Pub/Sub)
+functions.cloudEvent('helloPubSub', async (cloudEvent) => {
+  const message = Buffer.from(cloudEvent.data.message.data, 'base64').toString();
+  console.log(`Received message: ${message}`);
+  
+  // Process message
+  await firestore.collection('messages').add({
+    content: message,
+    timestamp: new Date()
+  });
+});
+
+// Firestore trigger
+functions.cloudEvent('onUserCreate', async (event) => {
+  const document = event.data;
+  console.log('New user created:', document);
+  
+  // Send welcome email
+  await sendWelcomeEmail(document.email);
+});
+```
+
+### Deploy Cloud Function
+
+```bash
+gcloud functions deploy my-function \
+  --gen2 \
+  --runtime nodejs20 \
+  --trigger-http \
+  --allow-unauthenticated \
+  --region us-central1 \
+  --entry-point helloHttp
+```
+
+---
+
+## 3. Pub/Sub Pattern
+
+### Publisher
+
+```javascript
+const { PubSub } = require('@google-cloud/pubsub');
+const pubsub = new PubSub();
+
+async function publishMessage(topicName, data) {
+  const topic = pubsub.topic(topicName);
+  
+  const messageBuffer = Buffer.from(JSON.stringify(data));
+  
+  const messageId = await topic.publish(messageBuffer, {
+    // Ordering key for ordered delivery
+    orderingKey: data.userId
+  });
+  
+  console.log(`Message ${messageId} published.`);
+  return messageId;
+}
+```
+
+### Subscriber (Push to Cloud Run)
+
+```javascript
+// Pub/Sub push endpoint in Cloud Run
+app.post('/pubsub/push', async (req, res) => {
+  try {
+    // Verify Pub/Sub token if configured
+    const token = req.query.token;
+    if (token !== process.env.PUBSUB_VERIFICATION_TOKEN) {
+      return res.status(403).send('Forbidden');
+    }
+    
+    const message = JSON.parse(
+      Buffer.from(req.body.message.data, 'base64').toString()
+    );
+    
+    await processMessage(message);
+    
+    // Acknowledge by returning 2xx
+    res.status(200).send('OK');
+  } catch (error) {
+    console.error('Error processing message:', error);
+    // Return 5xx to retry
+    res.status(500).send('Error');
+  }
+});
+```
+
+---
+
+## 4. Firestore Patterns
+
+### Single Document Pattern
+
+```javascript
+// Get with caching
+async function getUser(userId) {
+  const cacheKey = `user:${userId}`;
+  
+  // Check cache
+  const cached = await cache.get(cacheKey);
+  if (cached) return cached;
+  
+  // Fetch from Firestore
+  const doc = await firestore.collection('users').doc(userId).get();
+  
+  if (!doc.exists) return null;
+  
+  const user = { id: doc.id, ...doc.data() };
+  
+  // Cache for 5 minutes
+  await cache.set(cacheKey, user, 300);
+  
+  return user;
+}
+```
+
+### Batch Operations
+
+```javascript
+// Batch write for better performance
+async function createUsers(users) {
+  const batch = firestore.batch();
+  
+  users.forEach(user => {
+    const ref = firestore.collection('users').doc();
+    batch.set(ref, {
+      ...user,
+      createdAt: Firestore.FieldValue.serverTimestamp()
+    });
+  });
+  
+  await batch.commit();
+}
+```
+
+---
+
+## 5. Cloud Build CI/CD
+
+```yaml
+# cloudbuild.yaml
+steps:
+  # Run tests
+  - name: 'node:20'
+    entrypoint: 'npm'
+    args: ['ci']
+  
+  - name: 'node:20'
+    entrypoint: 'npm'
+    args: ['test']
+  
+  # Build container
+  - name: 'gcr.io/cloud-builders/docker'
+    args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA', '.']
+  
+  # Push to registry
+  - name: 'gcr.io/cloud-builders/docker'
+    args: ['push', 'gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA']
+  
+  # Deploy to Cloud Run
+  - name: 'gcr.io/cloud-builders/gcloud'
+    args:
+      - 'run'
+      - 'deploy'
+      - 'my-service'
+      - '--image=gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA'
+      - '--region=us-central1'
+      - '--platform=managed'
+
+images:
+  - 'gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA'
+```
+
+---
+
+## 6. Anti-Patterns
+
+### ❌ No Min Instances
+
+```bash
+# WRONG: Cold start on every request after idle
+gcloud run deploy --min-instances 0
+
+# CORRECT: Keep warm for latency-sensitive apps
+gcloud run deploy --min-instances 1
+```
+
+### ❌ Global State Mutation
+
+```javascript
+// WRONG: Global state across requests
+let requestCount = 0;
+
+app.get('/', (req, res) => {
+  requestCount++; // Unreliable across instances!
+  res.json({ count: requestCount });
+});
+
+// CORRECT: Use external storage
+app.get('/', async (req, res) => {
+  const count = await redis.incr('request_count');
+  res.json({ count });
+});
+```
+
+---
+
+## Related Skills
+
+- `aws-serverless` - Compare with AWS
+- `azure-functions` - Compare with Azure
+- `docker-expert` - Container optimization