@ngxtm/devkit 3.7.0 → 3.9.0

package/merged-commands/gcp-cloud-run.md

@@ -0,0 +1,288 @@
+---
+name: gcp-cloud-run
+description: "Specialized skill for building production-ready serverless applications on GCP. Covers Cloud Run services (containerized), Cloud Run Functions (event-driven), cold start optimization, and event-driven architecture with Pub/Sub."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# GCP Cloud Run
+
+## Patterns
+
+### Cloud Run Service Pattern
+
+Containerized web service on Cloud Run
+
+**When to use**: ['Web applications and APIs', 'Need any runtime or library', 'Complex services with multiple endpoints', 'Stateless containerized workloads']
+
+```javascript
+```dockerfile
+# Dockerfile - Multi-stage build for smaller image
+FROM node:20-slim AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+FROM node:20-slim
+WORKDIR /app
+
+# Copy only production dependencies
+COPY --from=builder /app/node_modules ./node_modules
+COPY src ./src
+COPY package.json ./
+
+# Cloud Run uses PORT env variable
+ENV PORT=8080
+EXPOSE 8080
+
+# Run as non-root user
+USER node
+
+CMD ["node", "src/index.js"]
+```
+
+```javascript
+// src/index.js
+const express = require('express');
+const app = express();
+
+app.use(express.json());
+
+// Health check endpoint
+app.get('/health', (req, res) => {
+  res.status(200).send('OK');
+});
+
+// API routes
+app.get('/api/items/:id', async (req, res) => {
+  try {
+    const item = await getItem(req.params.id);
+    res.json(item);
+  } catch (error) {
+    console.error('Error:', error);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+// Graceful shutdown
+process.on('SIGTERM', () => {
+  console.log('SIGTERM received, shutting down gracefully');
+  server.close(() => {
+    console.log('Server closed');
+    process.exit(0);
+  });
+});
+
+const PORT = process.env.PORT || 8080;
+const server = app.listen(PORT, () => {
+  console.log(`Server listening on port ${PORT}`);
+});
+```
+
+```yaml
+# cloudbuild.yaml
+steps:
+  # Build the container image
+  - name: 'gcr.io/cloud-builders/docker'
+    args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA', '.']
+
+  # Push the container image
+  - name: 'gcr.io/cloud-builders/docker'
+    args: ['push', 'gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA']
+
+  # Deploy to Cloud Run
+  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
+    entrypoint: gcloud
+    args:
+      - 'run'
+      - 'deploy'
+      - 'my-service'
+      - '--image=gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA'
+      - '--region=us-central1'
+      - '--platform=managed'
+      - '--allow-unauthenticated'
+      - '--memory=512Mi'
+      - '--cpu=1'
+      - '--min-instances=1'
+      - '--max-instances=100'
+     
+```
+
+### Cloud Run Functions Pattern
+
+Event-driven functions (formerly Cloud Functions)
+
+**When to use**: ['Simple event handlers', 'Pub/Sub message processing', 'Cloud Storage triggers', 'HTTP webhooks']
+
+```javascript
+```javascript
+// HTTP Function
+// index.js
+const functions = require('@google-cloud/functions-framework');
+
+functions.http('helloHttp', (req, res) => {
+  const name = req.query.name || req.body.name || 'World';
+  res.send(`Hello, ${name}!`);
+});
+```
+
+```javascript
+// Pub/Sub Function
+const functions = require('@google-cloud/functions-framework');
+
+functions.cloudEvent('processPubSub', (cloudEvent) => {
+  // Decode Pub/Sub message
+  const message = cloudEvent.data.message;
+  const data = message.data
+    ? JSON.parse(Buffer.from(message.data, 'base64').toString())
+    : {};
+
+  console.log('Received message:', data);
+
+  // Process message
+  processMessage(data);
+});
+```
+
+```javascript
+// Cloud Storage Function
+const functions = require('@google-cloud/functions-framework');
+
+functions.cloudEvent('processStorageEvent', async (cloudEvent) => {
+  const file = cloudEvent.data;
+
+  console.log(`Event: ${cloudEvent.type}`);
+  console.log(`Bucket: ${file.bucket}`);
+  console.log(`File: ${file.name}`);
+
+  if (cloudEvent.type === 'google.cloud.storage.object.v1.finalized') {
+    await processUploadedFile(file.bucket, file.name);
+  }
+});
+```
+
+```bash
+# Deploy HTTP function
+gcloud functions deploy hello-http \
+  --gen2 \
+  --runtime nodejs20 \
+  --trigger-http \
+  --allow-unauthenticated \
+  --region us-central1
+
+# Deploy Pub/Sub function
+gcloud functions deploy process-messages \
+  --gen2 \
+  --runtime nodejs20 \
+  --trigger-topic my-topic \
+  --region us-central1
+
+# Deploy Cloud Storage function
+gcloud functions deploy process-uploads \
+  --gen2 \
+  --runtime nodejs20 \
+  --trigger-event-filters="type=google.cloud.storage.object.v1.finalized" \
+  --trigger-event-filters="bucket=my-bucket" \
+  --region us-central1
+```
+```
+
+### Cold Start Optimization Pattern
+
+Minimize cold start latency for Cloud Run
+
+**When to use**: ['Latency-sensitive applications', 'User-facing APIs', 'High-traffic services']
+
+```javascript
+## 1. Enable Startup CPU Boost
+
+```bash
+gcloud run deploy my-service \
+  --cpu-boost \
+  --region us-central1
+```
+
+## 2. Set Minimum Instances
+
+```bash
+gcloud run deploy my-service \
+  --min-instances 1 \
+  --region us-central1
+```
+
+## 3. Optimize Container Image
+
+```dockerfile
+# Use distroless for minimal image
+FROM node:20-slim AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+FROM gcr.io/distroless/nodejs20-debian12
+WORKDIR /app
+COPY --from=builder /app/node_modules ./node_modules
+COPY src ./src
+CMD ["src/index.js"]
+```
+
+## 4. Lazy Initialize Heavy Dependencies
+
+```javascript
+// Lazy load heavy libraries
+let bigQueryClient = null;
+
+function getBigQueryClient() {
+  if (!bigQueryClient) {
+    const { BigQuery } = require('@google-cloud/bigquery');
+    bigQueryClient = new BigQuery();
+  }
+  return bigQueryClient;
+}
+
+// Only initialize when needed
+app.get('/api/analytics', async (req, res) => {
+  const client = getBigQueryClient();
+  const results = await client.query({...});
+  res.json(results);
+});
+```
+
+## 5. Increase Memory (More CPU)
+
+```bash
+# Higher memory = more CPU during startup
+gcloud run deploy my-service \
+  --memory 1Gi \
+  --cpu 2 \
+  --region us-central1
+```
+```
+
+## Anti-Patterns
+
+### ❌ CPU-Intensive Work Without Concurrency=1
+
+**Why bad**: CPU is shared across concurrent requests. CPU-bound work
+will starve other requests, causing timeouts.
+
+### ❌ Writing Large Files to /tmp
+
+**Why bad**: /tmp is an in-memory filesystem. Large files consume
+your memory allocation and can cause OOM errors.
+
+### ❌ Long-Running Background Tasks
+
+**Why bad**: Cloud Run throttles CPU to near-zero when not handling
+requests. Background tasks will be extremely slow or stall.
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Issue | high | ## Calculate memory including /tmp usage |
+| Issue | high | ## Set appropriate concurrency |
+| Issue | high | ## Enable CPU always allocated |
+| Issue | medium | ## Configure connection pool with keep-alive |
+| Issue | high | ## Enable startup CPU boost |
+| Issue | medium | ## Explicitly set execution environment |
+| Issue | medium | ## Set consistent timeouts |

package/merged-commands/gdpr-data-handling.md

@@ -0,0 +1,33 @@
+---
+name: gdpr-data-handling
+description: Implement GDPR-compliant data handling with consent management, data subject rights, and privacy by design. Use when building systems that process EU personal data, implementing privacy controls, or conducting GDPR compliance reviews.
+---
+
+# GDPR Data Handling
+
+Practical implementation guide for GDPR-compliant data processing, consent management, and privacy controls.
+
+## Use this skill when
+
+- Building systems that process EU personal data
+- Implementing consent management
+- Handling data subject requests (DSRs)
+- Conducting GDPR compliance reviews
+- Designing privacy-first architectures
+- Creating data processing agreements
+
+## Do not use this skill when
+
+- The task is unrelated to gdpr data handling
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed patterns and examples.

package/merged-commands/geo-fundamentals.md

@@ -0,0 +1,156 @@
+---
+name: geo-fundamentals
+description: Generative Engine Optimization for AI search engines (ChatGPT, Claude, Perplexity).
+allowed-tools: Read, Glob, Grep
+---
+
+# GEO Fundamentals
+
+> Optimization for AI-powered search engines.
+
+---
+
+## 1. What is GEO?
+
+**GEO** = Generative Engine Optimization
+
+| Goal | Platform |
+|------|----------|
+| Be cited in AI responses | ChatGPT, Claude, Perplexity, Gemini |
+
+### SEO vs GEO
+
+| Aspect | SEO | GEO |
+|--------|-----|-----|
+| Goal | #1 ranking | AI citations |
+| Platform | Google | AI engines |
+| Metrics | Rankings, CTR | Citation rate |
+| Focus | Keywords | Entities, data |
+
+---
+
+## 2. AI Engine Landscape
+
+| Engine | Citation Style | Opportunity |
+|--------|----------------|-------------|
+| **Perplexity** | Numbered [1][2] | Highest citation rate |
+| **ChatGPT** | Inline/footnotes | Custom GPTs |
+| **Claude** | Contextual | Long-form content |
+| **Gemini** | Sources section | SEO crossover |
+
+---
+
+## 3. RAG Retrieval Factors
+
+How AI engines select content to cite:
+
+| Factor | Weight |
+|--------|--------|
+| Semantic relevance | ~40% |
+| Keyword match | ~20% |
+| Authority signals | ~15% |
+| Freshness | ~10% |
+| Source diversity | ~15% |
+
+---
+
+## 4. Content That Gets Cited
+
+| Element | Why It Works |
+|---------|--------------|
+| **Original statistics** | Unique, citable data |
+| **Expert quotes** | Authority transfer |
+| **Clear definitions** | Easy to extract |
+| **Step-by-step guides** | Actionable value |
+| **Comparison tables** | Structured info |
+| **FAQ sections** | Direct answers |
+
+---
+
+## 5. GEO Content Checklist
+
+### Content Elements
+
+- [ ] Question-based titles
+- [ ] Summary/TL;DR at top
+- [ ] Original data with sources
+- [ ] Expert quotes (name, title)
+- [ ] FAQ section (3-5 Q&A)
+- [ ] Clear definitions
+- [ ] "Last updated" timestamp
+- [ ] Author with credentials
+
+### Technical Elements
+
+- [ ] Article schema with dates
+- [ ] Person schema for author
+- [ ] FAQPage schema
+- [ ] Fast loading (< 2.5s)
+- [ ] Clean HTML structure
+
+---
+
+## 6. Entity Building
+
+| Action | Purpose |
+|--------|---------|
+| Google Knowledge Panel | Entity recognition |
+| Wikipedia (if notable) | Authority source |
+| Consistent info across web | Entity consolidation |
+| Industry mentions | Authority signals |
+
+---
+
+## 7. AI Crawler Access
+
+### Key AI User-Agents
+
+| Crawler | Engine |
+|---------|--------|
+| GPTBot | ChatGPT/OpenAI |
+| Claude-Web | Claude |
+| PerplexityBot | Perplexity |
+| Googlebot | Gemini (shared) |
+
+### Access Decision
+
+| Strategy | When |
+|----------|------|
+| Allow all | Want AI citations |
+| Block GPTBot | Don't want OpenAI training |
+| Selective | Allow some, block others |
+
+---
+
+## 8. Measurement
+
+| Metric | How to Track |
+|--------|--------------|
+| AI citations | Manual monitoring |
+| "According to [Brand]" mentions | Search in AI |
+| Competitor citations | Compare share |
+| AI-referred traffic | UTM parameters |
+
+---
+
+## 9. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Publish without dates | Add timestamps |
+| Vague attributions | Name sources |
+| Skip author info | Show credentials |
+| Thin content | Comprehensive coverage |
+
+---
+
+> **Remember:** AI cites content that's clear, authoritative, and easy to extract. Be the best answer.
+
+---
+
+## Script
+
+| Script | Purpose | Command |
+|--------|---------|---------|
+| `scripts/geo_checker.py` | GEO audit (AI citation readiness) | `python scripts/geo_checker.py <project_path>` |
+