@intentsolutionsio/vercel-pack 1.0.0

package/skills/vercel-policy-guardrails/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: vercel-policy-guardrails
+description: |
+  Implement Vercel lint rules, policy enforcement, and automated guardrails.
+  Use when setting up code quality rules for Vercel integrations, implementing
+  pre-commit hooks, or configuring CI policy checks for Vercel best practices.
+  Trigger with phrases like "vercel policy", "vercel lint",
+  "vercel guardrails", "vercel best practices check", "vercel eslint".
+allowed-tools: Read, Write, Edit, Bash(npx:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Policy & Guardrails
+
+## Overview
+Automated policy enforcement and guardrails for Vercel integrations.
+
+## Prerequisites
+- ESLint configured in project
+- Pre-commit hooks infrastructure
+- CI/CD pipeline with policy checks
+- TypeScript for type enforcement
+
+## ESLint Rules
+
+### Custom Vercel Plugin
+```javascript
+// eslint-plugin-vercel/rules/no-hardcoded-keys.js
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow hardcoded Vercel API keys',
+    },
+    fixable: 'code',
+  },
+  create(context) {
+    return {
+      Literal(node) {
+        if (typeof node.value === 'string') {
+          if (node.value.match(/^sk_(live|test)_[a-zA-Z0-9]{24,}/)) {
+            context.report({
+              node,
+              message: 'Hardcoded Vercel API key detected',
+            });
+          }
+        }
+      },
+    };
+  },
+};
+```
+
+### ESLint Configuration
+```javascript
+// .eslintrc.js
+module.exports = {
+  plugins: ['vercel'],
+  rules: {
+    'vercel/no-hardcoded-keys': 'error',
+    'vercel/require-error-handling': 'warn',
+    'vercel/use-typed-client': 'warn',
+  },
+};
+```
+
+## Pre-Commit Hooks
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: vercel-secrets-check
+        name: Check for Vercel secrets
+        entry: bash -c 'git diff --cached --name-only | xargs grep -l "sk_live_" && exit 1 || exit 0'
+        language: system
+        pass_filenames: false
+
+      - id: vercel-config-validate
+        name: Validate Vercel configuration
+        entry: node scripts/validate-vercel-config.js
+        language: node
+        files: '\.vercel\.json$'
+```
+
+## TypeScript Strict Patterns
+
+```typescript
+// Enforce typed configuration
+interface VercelStrictConfig {
+  apiKey: string;  // Required
+  environment: 'development' | 'staging' | 'production';  // Enum
+  timeout: number;  // Required number, not optional
+  retries: number;
+}
+
+// Disallow any in Vercel code
+// @ts-expect-error - Using any is forbidden
+const client = new Client({ apiKey: any });
+
+// Prefer this
+const client = new VercelClient(config satisfies VercelStrictConfig);
+```
+
+## Architecture Decision Records
+
+### ADR Template
+```markdown
+# ADR-001: Vercel Client Initialization
+
+## Status
+Accepted
+
+## Context
+We need to decide how to initialize the Vercel client across our application.
+
+## Decision
+We will use the singleton pattern with lazy initialization.
+
+## Consequences
+- Pro: Single client instance, connection reuse
+- Pro: Easy to mock in tests
+- Con: Global state requires careful lifecycle management
+
+## Enforcement
+- ESLint rule: vercel/use-singleton-client
+- CI check: grep for "new VercelClient(" outside allowed files
+```
+
+## Policy-as-Code (OPA)
+
+```rego
+# vercel-policy.rego
+package vercel
+
+# Deny production API keys in non-production environments
+deny[msg] {
+  input.environment != "production"
+  startswith(input.apiKey, "sk_live_")
+  msg := "Production API keys not allowed in non-production environment"
+}
+
+# Require minimum timeout
+deny[msg] {
+  input.timeout < 10000
+  msg := sprintf("Timeout too low: %d < 10000ms minimum", [input.timeout])
+}
+
+# Require retry configuration
+deny[msg] {
+  not input.retries
+  msg := "Retry configuration is required"
+}
+```
+
+## CI Policy Checks
+
+```yaml
+# .github/workflows/vercel-policy.yml
+name: Vercel Policy Check
+
+on: [push, pull_request]
+
+jobs:
+  policy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check for hardcoded secrets
+        run: |
+          if grep -rE "sk_(live|test)_[a-zA-Z0-9]{24,}" --include="*.ts" --include="*.js" .; then
+            echo "ERROR: Hardcoded Vercel keys found"
+            exit 1
+          fi
+
+      - name: Validate configuration schema
+        run: |
+          npx ajv validate -s vercel-config.schema.json -d config/vercel/*.json
+
+      - name: Run ESLint Vercel rules
+        run: npx eslint --plugin vercel --rule 'vercel/no-hardcoded-keys: error' src/
+```
+
+## Runtime Guardrails
+
+```typescript
+// Prevent dangerous operations in production
+const BLOCKED_IN_PROD = ['deleteAll', 'resetData', 'migrateDown'];
+
+function guardVercelOperation(operation: string): void {
+  const isProd = process.env.NODE_ENV === 'production';
+
+  if (isProd && BLOCKED_IN_PROD.includes(operation)) {
+    throw new Error(`Operation '${operation}' blocked in production`);
+  }
+}
+
+// Rate limit protection
+function guardRateLimits(requestsInWindow: number): void {
+  const limit = parseInt(process.env.VERCEL_RATE_LIMIT || '100');
+
+  if (requestsInWindow > limit * 0.9) {
+    console.warn('Approaching Vercel rate limit');
+  }
+
+  if (requestsInWindow >= limit) {
+    throw new Error('Vercel rate limit exceeded - request blocked');
+  }
+}
+```
+
+## Instructions
+
+### Step 1: Create ESLint Rules
+Implement custom lint rules for Vercel patterns.
+
+### Step 2: Configure Pre-Commit Hooks
+Set up hooks to catch issues before commit.
+
+### Step 3: Add CI Policy Checks
+Implement policy-as-code in CI pipeline.
+
+### Step 4: Enable Runtime Guardrails
+Add production safeguards for dangerous operations.
+
+## Output
+- ESLint plugin with Vercel rules
+- Pre-commit hooks blocking secrets
+- CI policy checks passing
+- Runtime guardrails active
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| ESLint rule not firing | Wrong config | Check plugin registration |
+| Pre-commit skipped | --no-verify | Enforce in CI |
+| Policy false positive | Regex too broad | Narrow pattern match |
+| Guardrail triggered | Actual issue | Fix or whitelist |
+
+## Examples
+
+### Quick ESLint Check
+```bash
+npx eslint --plugin vercel --rule 'vercel/no-hardcoded-keys: error' src/
+```
+
+## Resources
+- [ESLint Plugin Development](https://eslint.org/docs/latest/extend/plugins)
+- [Pre-commit Framework](https://pre-commit.com/)
+- [Open Policy Agent](https://www.openpolicyagent.org/)
+
+## Next Steps
+For architecture blueprints, see `vercel-architecture-variants`.

package/skills/vercel-prod-checklist/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: vercel-prod-checklist
+description: |
+  Execute Vercel production deployment checklist and rollback procedures.
+  Use when deploying Vercel integrations to production, preparing for launch,
+  or implementing go-live procedures.
+  Trigger with phrases like "vercel production", "deploy vercel",
+  "vercel go-live", "vercel launch checklist".
+allowed-tools: Read, Bash(kubectl:*), Bash(curl:*), Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Production Checklist
+
+## Overview
+Complete checklist for deploying Vercel integrations to production.
+
+## Prerequisites
+- Staging environment tested and verified
+- Production API keys available
+- Deployment pipeline configured
+- Monitoring and alerting ready
+
+## Instructions
+
+### Step 1: Pre-Deployment Configuration
+- [ ] Production API keys in secure vault
+- [ ] Environment variables set in deployment platform
+- [ ] API key scopes are minimal (least privilege)
+- [ ] Webhook endpoints configured with HTTPS
+- [ ] Webhook secrets stored securely
+
+### Step 2: Code Quality Verification
+- [ ] All tests passing (`npm test`)
+- [ ] No hardcoded credentials
+- [ ] Error handling covers all Vercel error types
+- [ ] Rate limiting/backoff implemented
+- [ ] Logging is production-appropriate
+
+### Step 3: Infrastructure Setup
+- [ ] Health check endpoint includes Vercel connectivity
+- [ ] Monitoring/alerting configured
+- [ ] Circuit breaker pattern implemented
+- [ ] Graceful degradation configured
+
+### Step 4: Documentation Requirements
+- [ ] Incident runbook created
+- [ ] Key rotation procedure documented
+- [ ] Rollback procedure documented
+- [ ] On-call escalation path defined
+
+### Step 5: Deploy with Gradual Rollout
+```bash
+# Pre-flight checks
+curl -f https://staging.example.com/health
+curl -s https://www.vercel-status.com
+
+# Gradual rollout - start with canary (10%)
+kubectl apply -f k8s/production.yaml
+kubectl set image deployment/vercel-integration app=image:new --record
+kubectl rollout pause deployment/vercel-integration
+
+# Monitor canary traffic for 10 minutes
+sleep 600
+# Check error rates and latency before continuing
+
+# If healthy, continue rollout to 50%
+kubectl rollout resume deployment/vercel-integration
+kubectl rollout pause deployment/vercel-integration
+sleep 300
+
+# Complete rollout to 100%
+kubectl rollout resume deployment/vercel-integration
+kubectl rollout status deployment/vercel-integration
+```
+
+## Output
+- Deployed Vercel integration
+- Health checks passing
+- Monitoring active
+- Rollback procedure documented
+
+## Error Handling
+| Alert | Condition | Severity |
+|-------|-----------|----------|
+| API Down | 5xx errors > 10/min | P1 |
+| High Latency | p99 > 5000ms | P2 |
+| Rate Limited | 429 errors > 5/min | P2 |
+| Auth Failures | 401/403 errors > 0 | P1 |
+
+## Examples
+
+### Health Check Implementation
+```typescript
+async function healthCheck(): Promise<{ status: string; vercel: any }> {
+  const start = Date.now();
+  try {
+    await vercelClient.ping();
+    return { status: 'healthy', vercel: { connected: true, latencyMs: Date.now() - start } };
+  } catch (error) {
+    return { status: 'degraded', vercel: { connected: false, latencyMs: Date.now() - start } };
+  }
+}
+```
+
+### Immediate Rollback
+```bash
+kubectl rollout undo deployment/vercel-integration
+kubectl rollout status deployment/vercel-integration
+```
+
+## Resources
+- [Vercel Status](https://www.vercel-status.com)
+- [Vercel Support](https://vercel.com/docs/support)
+
+## Next Steps
+For version upgrades, see `vercel-upgrade-migration`.

package/skills/vercel-rate-limits/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: vercel-rate-limits
+description: |
+  Implement Vercel rate limiting, backoff, and idempotency patterns.
+  Use when handling rate limit errors, implementing retry logic,
+  or optimizing API request throughput for Vercel.
+  Trigger with phrases like "vercel rate limit", "vercel throttling",
+  "vercel 429", "vercel retry", "vercel backoff".
+allowed-tools: Read, Write, Edit
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Rate Limits
+
+## Overview
+Handle Vercel rate limits gracefully with exponential backoff and idempotency.
+
+## Prerequisites
+- Vercel SDK installed
+- Understanding of async/await patterns
+- Access to rate limit headers
+
+## Instructions
+
+### Step 1: Understand Rate Limit Tiers
+
+| Tier | Requests/min | Requests/day | Burst |
+|------|-------------|--------------|-------|
+| Hobby | 100 | 100,000 | 10 |
+| Pro | 1,000 | 1,000,000 | 50 |
+| Enterprise | 10,000 | Unlimited | 200 |
+
+### Step 2: Implement Exponential Backoff with Jitter
+
+```typescript
+async function withExponentialBackoff<T>(
+  operation: () => Promise<T>,
+  config = { maxRetries: 5, baseDelayMs: 1000, maxDelayMs: 32000, jitterMs: 500 }
+): Promise<T> {
+  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error: any) {
+      if (attempt === config.maxRetries) throw error;
+      const status = error.status || error.response?.status;
+      if (status !== 429 && (status < 500 || status >= 600)) throw error;
+
+      // Exponential delay with jitter to prevent thundering herd
+      const exponentialDelay = config.baseDelayMs * Math.pow(2, attempt);
+      const jitter = Math.random() * config.jitterMs;
+      const delay = Math.min(exponentialDelay + jitter, config.maxDelayMs);
+
+      console.log(`Rate limited. Retrying in ${delay.toFixed(0)}ms...`);
+      await new Promise(r => setTimeout(r, delay));
+    }
+  }
+  throw new Error('Unreachable');
+}
+```
+
+### Step 3: Add Idempotency Keys
+
+```typescript
+import { v4 as uuidv4 } from 'uuid';
+import crypto from 'crypto';
+
+// Generate deterministic key from operation params (for safe retries)
+function generateIdempotencyKey(operation: string, params: Record<string, any>): string {
+  const data = JSON.stringify({ operation, params });
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+async function idempotentRequest<T>(
+  client: VercelClient,
+  params: Record<string, any>,
+  idempotencyKey?: string  // Pass existing key for retries
+): Promise<T> {
+  // Use provided key (for retries) or generate deterministic key from params
+  const key = idempotencyKey || generateIdempotencyKey(params.method || 'POST', params);
+  return client.request({
+    ...params,
+    headers: { 'Idempotency-Key': key, ...params.headers },
+  });
+}
+```
+
+## Output
+- Reliable API calls with automatic retry
+- Idempotent requests preventing duplicates
+- Rate limit headers properly handled
+
+## Error Handling
+| Header | Description | Action |
+|--------|-------------|--------|
+| X-RateLimit-Limit | Max requests | Monitor usage |
+| X-RateLimit-Remaining | Remaining requests | Throttle if low |
+| X-RateLimit-Reset | Reset timestamp | Wait until reset |
+| Retry-After | Seconds to wait | Honor this value |
+
+## Examples
+
+### Queue-Based Rate Limiting
+```typescript
+import PQueue from 'p-queue';
+
+const queue = new PQueue({
+  concurrency: 5,
+  interval: 1000,
+  intervalCap: 10,
+});
+
+async function queuedRequest<T>(operation: () => Promise<T>): Promise<T> {
+  return queue.add(operation);
+}
+```
+
+### Monitor Rate Limit Usage
+```typescript
+class RateLimitMonitor {
+  private remaining: number = 60;
+  private resetAt: Date = new Date();
+
+  updateFromHeaders(headers: Headers) {
+    this.remaining = parseInt(headers.get('X-RateLimit-Remaining') || '60');
+    const resetTimestamp = headers.get('X-RateLimit-Reset');
+    if (resetTimestamp) {
+      this.resetAt = new Date(parseInt(resetTimestamp) * 1000);
+    }
+  }
+
+  shouldThrottle(): boolean {
+    // Only throttle if low remaining AND reset hasn't happened yet
+    return this.remaining < 5 && new Date() < this.resetAt;
+  }
+
+  getWaitTime(): number {
+    return Math.max(0, this.resetAt.getTime() - Date.now());
+  }
+}
+```
+
+## Resources
+- [Vercel Rate Limits](https://vercel.com/docs/rate-limits)
+- [p-queue Documentation](https://github.com/sindresorhus/p-queue)
+
+## Next Steps
+For security configuration, see `vercel-security-basics`.