@intentsolutionsio/vercel-pack 1.0.0

package/skills/vercel-load-scale/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: vercel-load-scale
+description: |
+  Implement Vercel load testing, auto-scaling, and capacity planning strategies.
+  Use when running performance tests, configuring horizontal scaling,
+  or planning capacity for Vercel integrations.
+  Trigger with phrases like "vercel load test", "vercel scale",
+  "vercel performance test", "vercel capacity", "vercel k6", "vercel benchmark".
+allowed-tools: Read, Write, Edit, Bash(k6:*), Bash(kubectl:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Load & Scale
+
+## Overview
+Load testing, scaling strategies, and capacity planning for Vercel integrations.
+
+## Prerequisites
+- k6 load testing tool installed
+- Kubernetes cluster with HPA configured
+- Prometheus for metrics collection
+- Test environment API keys
+
+## Load Testing with k6
+
+### Basic Load Test
+```javascript
+// vercel-load-test.js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  stages: [
+    { duration: '2m', target: 10 },   // Ramp up
+    { duration: '5m', target: 10 },   // Steady state
+    { duration: '2m', target: 50 },   // Ramp to peak
+    { duration: '5m', target: 50 },   // Stress test
+    { duration: '2m', target: 0 },    // Ramp down
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<100'],
+    http_req_failed: ['rate<0.01'],
+  },
+};
+
+export default function () {
+  const response = http.post(
+    'https://api.vercel.com/v1/resource',
+    JSON.stringify({ test: true }),
+    {
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${__ENV.VERCEL_API_KEY}`,
+      },
+    }
+  );
+
+  check(response, {
+    'status is 200': (r) => r.status === 200,
+    'latency < 100ms': (r) => r.timings.duration < 100,
+  });
+
+  sleep(1);
+}
+```
+
+### Run Load Test
+```bash
+# Install k6
+brew install k6  # macOS
+# or: sudo apt install k6  # Linux
+
+# Run test
+k6 run --env VERCEL_API_KEY=${VERCEL_API_KEY} vercel-load-test.js
+
+# Run with output to InfluxDB
+k6 run --out influxdb=http://localhost:8086/k6 vercel-load-test.js
+```
+
+## Scaling Patterns
+
+### Horizontal Scaling
+```yaml
+# kubernetes HPA
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: vercel-integration-hpa
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: vercel-integration
+  minReplicas: 2
+  maxReplicas: 20
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+    - type: Pods
+      pods:
+        metric:
+          name: vercel_queue_depth
+        target:
+          type: AverageValue
+          averageValue: 100
+```
+
+### Connection Pooling
+```typescript
+import { Pool } from 'generic-pool';
+
+const vercelPool = Pool.create({
+  create: async () => {
+    return new VercelClient({
+      apiKey: process.env.VERCEL_API_KEY!,
+    });
+  },
+  destroy: async (client) => {
+    await client.close();
+  },
+  max: None,
+  min: None,
+  idleTimeoutMillis: 30000,
+});
+
+async function withVercelClient<T>(
+  fn: (client: VercelClient) => Promise<T>
+): Promise<T> {
+  const client = await vercelPool.acquire();
+  try {
+    return await fn(client);
+  } finally {
+    vercelPool.release(client);
+  }
+}
+```
+
+## Capacity Planning
+
+### Metrics to Monitor
+| Metric | Warning | Critical |
+|--------|---------|----------|
+| CPU Utilization | > 70% | > 85% |
+| Memory Usage | > 75% | > 90% |
+| Request Queue Depth | > 100 | > 500 |
+| Error Rate | > 1% | > 5% |
+| P95 Latency | > 500ms | > 2000ms |
+
+### Capacity Calculation
+```typescript
+interface CapacityEstimate {
+  currentRPS: number;
+  maxRPS: number;
+  headroom: number;
+  scaleRecommendation: string;
+}
+
+function estimateVercelCapacity(
+  metrics: SystemMetrics
+): CapacityEstimate {
+  const currentRPS = metrics.requestsPerSecond;
+  const avgLatency = metrics.p50Latency;
+  const cpuUtilization = metrics.cpuPercent;
+
+  // Estimate max RPS based on current performance
+  const maxRPS = currentRPS / (cpuUtilization / 100) * 0.7; // 70% target
+  const headroom = ((maxRPS - currentRPS) / currentRPS) * 100;
+
+  return {
+    currentRPS,
+    maxRPS: Math.floor(maxRPS),
+    headroom: Math.round(headroom),
+    scaleRecommendation: headroom < 30
+      ? 'Scale up soon'
+      : headroom < 50
+      ? 'Monitor closely'
+      : 'Adequate capacity',
+  };
+}
+```
+
+## Benchmark Results Template
+
+```markdown
+## Vercel Performance Benchmark
+**Date:** YYYY-MM-DD
+**Environment:** [staging/production]
+**SDK Version:** X.Y.Z
+
+### Test Configuration
+- Duration: 10 minutes
+- Ramp: 10 → 100 → 10 VUs
+- Target endpoint: /v1/resource
+
+### Results
+| Metric | Value |
+|--------|-------|
+| Total Requests | 50,000 |
+| Success Rate | 99.9% |
+| P50 Latency | 120ms |
+| P95 Latency | 350ms |
+| P99 Latency | 800ms |
+| Max RPS Achieved | 150 |
+
+### Observations
+- [Key finding 1]
+- [Key finding 2]
+
+### Recommendations
+- [Scaling recommendation]
+```
+
+## Instructions
+
+### Step 1: Create Load Test Script
+Write k6 test script with appropriate thresholds.
+
+### Step 2: Configure Auto-Scaling
+Set up HPA with CPU and custom metrics.
+
+### Step 3: Run Load Test
+Execute test and collect metrics.
+
+### Step 4: Analyze and Document
+Record results in benchmark template.
+
+## Output
+- Load test script created
+- HPA configured
+- Benchmark results documented
+- Capacity recommendations defined
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| k6 timeout | Rate limited | Reduce RPS |
+| HPA not scaling | Wrong metrics | Verify metric name |
+| Connection refused | Pool exhausted | Increase pool size |
+| Inconsistent results | Warm-up needed | Add ramp-up phase |
+
+## Examples
+
+### Quick k6 Test
+```bash
+k6 run --vus 10 --duration 30s vercel-load-test.js
+```
+
+### Check Current Capacity
+```typescript
+const metrics = await getSystemMetrics();
+const capacity = estimateVercelCapacity(metrics);
+console.log('Headroom:', capacity.headroom + '%');
+console.log('Recommendation:', capacity.scaleRecommendation);
+```
+
+### Scale HPA Manually
+```bash
+kubectl scale deployment vercel-integration --replicas=5
+kubectl get hpa vercel-integration-hpa
+```
+
+## Resources
+- [k6 Documentation](https://k6.io/docs/)
+- [Kubernetes HPA](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)
+- [Vercel Rate Limits](https://vercel.com/docs/rate-limits)
+
+## Next Steps
+For reliability patterns, see `vercel-reliability-patterns`.

package/skills/vercel-local-dev-loop/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: vercel-local-dev-loop
+description: |
+  Configure Vercel local development with hot reload and testing.
+  Use when setting up a development environment, configuring test workflows,
+  or establishing a fast iteration cycle with Vercel.
+  Trigger with phrases like "vercel dev setup", "vercel local development",
+  "vercel dev environment", "develop with vercel".
+allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(pnpm:*), Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Local Dev Loop
+
+## Overview
+Set up a fast, reproducible local development workflow for Vercel.
+
+## Prerequisites
+- Completed `vercel-install-auth` setup
+- Node.js 18+ with npm/pnpm
+- Code editor with TypeScript support
+- Git for version control
+
+## Instructions
+
+### Step 1: Create Project Structure
+```
+my-vercel-project/
+├── src/
+│   ├── vercel/
+│   │   ├── client.ts       # Vercel client wrapper
+│   │   ├── config.ts       # Configuration management
+│   │   └── utils.ts        # Helper functions
+│   └── index.ts
+├── tests/
+│   └── vercel.test.ts
+├── .env.local              # Local secrets (git-ignored)
+├── .env.example            # Template for team
+└── package.json
+```
+
+### Step 2: Configure Environment
+```bash
+# Copy environment template
+cp .env.example .env.local
+
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+```
+
+### Step 3: Setup Hot Reload
+```json
+{
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "test": "vitest",
+    "test:watch": "vitest --watch"
+  }
+}
+```
+
+### Step 4: Configure Testing
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { VercelClient } from '../src/vercel/client';
+
+describe('Vercel Client', () => {
+  it('should initialize with API key', () => {
+    const client = new VercelClient({ apiKey: 'test-key' });
+    expect(client).toBeDefined();
+  });
+});
+```
+
+## Output
+- Working development environment with hot reload
+- Configured test suite with mocking
+- Environment variable management
+- Fast iteration cycle for Vercel development
+
+## Error Handling
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Module not found | Missing dependency | Run `npm install` |
+| Port in use | Another process | Kill process or change port |
+| Env not loaded | Missing .env.local | Copy from .env.example |
+| Test timeout | Slow network | Increase test timeout |
+
+## Examples
+
+### Mock Vercel Responses
+```typescript
+vi.mock('vercel', () => ({
+  VercelClient: vi.fn().mockImplementation(() => ({
+    // Mock methods here
+  })),
+}));
+```
+
+### Debug Mode
+```bash
+# Enable verbose logging
+DEBUG=VERCEL=* npm run dev
+```
+
+## Resources
+- [Vercel SDK Reference](https://vercel.com/docs/sdk)
+- [Vitest Documentation](https://vitest.dev/)
+- [tsx Documentation](https://github.com/esbuild-kit/tsx)
+
+## Next Steps
+See `vercel-sdk-patterns` for production-ready code patterns.

package/skills/vercel-migration-deep-dive/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: vercel-migration-deep-dive
+description: |
+  Execute Vercel major re-architecture and migration strategies with strangler fig pattern.
+  Use when migrating to or from Vercel, performing major version upgrades,
+  or re-platforming existing integrations to Vercel.
+  Trigger with phrases like "migrate vercel", "vercel migration",
+  "switch to vercel", "vercel replatform", "vercel upgrade major".
+allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(node:*), Bash(kubectl:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Migration Deep Dive
+
+## Overview
+Comprehensive guide for migrating to or from Vercel, or major version upgrades.
+
+## Prerequisites
+- Current system documentation
+- Vercel SDK installed
+- Feature flag infrastructure
+- Rollback strategy tested
+
+## Migration Types
+
+| Type | Complexity | Duration | Risk |
+|------|-----------|----------|------|
+| Fresh install | Low | Days | Low |
+| From competitor | Medium | Weeks | Medium |
+| Major version | Medium | Weeks | Medium |
+| Full replatform | High | Months | High |
+
+## Pre-Migration Assessment
+
+### Step 1: Current State Analysis
+```bash
+# Document current implementation
+find . -name "*.ts" -o -name "*.py" | xargs grep -l "vercel" > vercel-files.txt
+
+# Count integration points
+wc -l vercel-files.txt
+
+# Identify dependencies
+npm list | grep vercel
+pip freeze | grep vercel
+```
+
+### Step 2: Data Inventory
+```typescript
+interface MigrationInventory {
+  dataTypes: string[];
+  recordCounts: Record<string, number>;
+  dependencies: string[];
+  integrationPoints: string[];
+  customizations: string[];
+}
+
+async function assessVercelMigration(): Promise<MigrationInventory> {
+  return {
+    dataTypes: await getDataTypes(),
+    recordCounts: await getRecordCounts(),
+    dependencies: await analyzeDependencies(),
+    integrationPoints: await findIntegrationPoints(),
+    customizations: await documentCustomizations(),
+  };
+}
+```
+
+## Migration Strategy: Strangler Fig Pattern
+
+```
+Phase 1: Parallel Run
+┌─────────────┐     ┌─────────────┐
+│   Old       │     │   New       │
+│   System    │ ──▶ │  Vercel   │
+│   (100%)    │     │   (0%)      │
+└─────────────┘     └─────────────┘
+
+Phase 2: Gradual Shift
+┌─────────────┐     ┌─────────────┐
+│   Old       │     │   New       │
+│   (50%)     │ ──▶ │   (50%)     │
+└─────────────┘     └─────────────┘
+
+Phase 3: Complete
+┌─────────────┐     ┌─────────────┐
+│   Old       │     │   New       │
+│   (0%)      │ ──▶ │   (100%)    │
+└─────────────┘     └─────────────┘
+```
+
+## Implementation Plan
+
+### Phase 1: Setup (Week 1-2)
+```bash
+# Install Vercel SDK
+npm install vercel
+
+# Configure credentials
+cp .env.example .env.vercel
+# Edit with new credentials
+
+# Verify connectivity
+node -e "require('vercel').ping()"
+```
+
+### Phase 2: Adapter Layer (Week 3-4)
+```typescript
+// src/adapters/vercel.ts
+interface ServiceAdapter {
+  create(data: CreateInput): Promise<Resource>;
+  read(id: string): Promise<Resource>;
+  update(id: string, data: UpdateInput): Promise<Resource>;
+  delete(id: string): Promise<void>;
+}
+
+class VercelAdapter implements ServiceAdapter {
+  async create(data: CreateInput): Promise<Resource> {
+    const vercelData = this.transform(data);
+    return vercelClient.create(vercelData);
+  }
+
+  private transform(data: CreateInput): VercelInput {
+    // Map from old format to Vercel format
+  }
+}
+```
+
+### Phase 3: Data Migration (Week 5-6)
+```typescript
+async function migrateVercelData(): Promise<MigrationResult> {
+  const batchSize = 100;
+  let processed = 0;
+  let errors: MigrationError[] = [];
+
+  for await (const batch of oldSystem.iterateBatches(batchSize)) {
+    try {
+      const transformed = batch.map(transform);
+      await vercelClient.batchCreate(transformed);
+      processed += batch.length;
+    } catch (error) {
+      errors.push({ batch, error });
+    }
+
+    // Progress update
+    console.log(`Migrated ${processed} records`);
+  }
+
+  return { processed, errors };
+}
+```
+
+### Phase 4: Traffic Shift (Week 7-8)
+```typescript
+// Feature flag controlled traffic split
+function getServiceAdapter(): ServiceAdapter {
+  const vercelPercentage = getFeatureFlag('vercel_migration_percentage');
+
+  if (Math.random() * 100 < vercelPercentage) {
+    return new VercelAdapter();
+  }
+
+  return new LegacyAdapter();
+}
+```
+
+## Rollback Plan
+
+```bash
+# Immediate rollback
+kubectl set env deployment/app VERCEL_ENABLED=false
+kubectl rollout restart deployment/app
+
+# Data rollback (if needed)
+./scripts/restore-from-backup.sh --date YYYY-MM-DD
+
+# Verify rollback
+curl https://app.yourcompany.com/health | jq '.services.vercel'
+```
+
+## Post-Migration Validation
+
+```typescript
+async function validateVercelMigration(): Promise<ValidationReport> {
+  const checks = [
+    { name: 'Data count match', fn: checkDataCounts },
+    { name: 'API functionality', fn: checkApiFunctionality },
+    { name: 'Performance baseline', fn: checkPerformance },
+    { name: 'Error rates', fn: checkErrorRates },
+  ];
+
+  const results = await Promise.all(
+    checks.map(async c => ({ name: c.name, result: await c.fn() }))
+  );
+
+  return { checks: results, passed: results.every(r => r.result.success) };
+}
+```
+
+## Instructions
+
+### Step 1: Assess Current State
+Document existing implementation and data inventory.
+
+### Step 2: Build Adapter Layer
+Create abstraction layer for gradual migration.
+
+### Step 3: Migrate Data
+Run batch data migration with error handling.
+
+### Step 4: Shift Traffic
+Gradually route traffic to new Vercel integration.
+
+## Output
+- Migration assessment complete
+- Adapter layer implemented
+- Data migrated successfully
+- Traffic fully shifted to Vercel
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Data mismatch | Transform errors | Validate transform logic |
+| Performance drop | No caching | Add caching layer |
+| Rollback triggered | Errors spiked | Reduce traffic percentage |
+| Validation failed | Missing data | Check batch processing |
+
+## Examples
+
+### Quick Migration Status
+```typescript
+const status = await validateVercelMigration();
+console.log(`Migration ${status.passed ? 'PASSED' : 'FAILED'}`);
+status.checks.forEach(c => console.log(`  ${c.name}: ${c.result.success}`));
+```
+
+## Resources
+- [Strangler Fig Pattern](https://martinfowler.com/bliki/StranglerFigApplication.html)
+- [Vercel Migration Guide](https://vercel.com/docs/migration)
+
+## Flagship+ Skills
+For advanced troubleshooting, see `vercel-advanced-troubleshooting`.