@intentsolutionsio/vercel-pack 1.0.0

package/skills/vercel-debug-bundle/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: vercel-debug-bundle
+description: |
+  Collect Vercel debug evidence for support tickets and troubleshooting.
+  Use when encountering persistent issues, preparing support tickets,
+  or collecting diagnostic information for Vercel problems.
+  Trigger with phrases like "vercel debug", "vercel support bundle",
+  "collect vercel logs", "vercel diagnostic".
+allowed-tools: Read, Bash(grep:*), Bash(curl:*), Bash(tar:*), Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Debug Bundle
+
+## Overview
+Collect all necessary diagnostic information for Vercel support tickets.
+
+## Prerequisites
+- Vercel SDK installed
+- Access to application logs
+- Permission to collect environment info
+
+## Instructions
+
+### Step 1: Create Debug Bundle Script
+```bash
+#!/bin/bash
+# vercel-debug-bundle.sh
+
+BUNDLE_DIR="vercel-debug-$(date +%Y%m%d-%H%M%S)"
+mkdir -p "$BUNDLE_DIR"
+
+echo "=== Vercel Debug Bundle ===" > "$BUNDLE_DIR/summary.txt"
+echo "Generated: $(date)" >> "$BUNDLE_DIR/summary.txt"
+```
+
+### Step 2: Collect Environment Info
+```bash
+# Environment info
+echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
+node --version >> "$BUNDLE_DIR/summary.txt" 2>&1
+npm --version >> "$BUNDLE_DIR/summary.txt" 2>&1
+echo "VERCEL_API_KEY: ${VERCEL_API_KEY:+[SET]}" >> "$BUNDLE_DIR/summary.txt"
+```
+
+### Step 3: Gather SDK and Logs
+```bash
+# SDK version
+npm list vercel 2>/dev/null >> "$BUNDLE_DIR/summary.txt"
+
+# Recent logs (redacted)
+grep -i "vercel" ~/.npm/_logs/*.log 2>/dev/null | tail -50 >> "$BUNDLE_DIR/logs.txt"
+
+# Configuration (redacted - secrets masked)
+echo "--- Config (redacted) ---" >> "$BUNDLE_DIR/summary.txt"
+cat .env 2>/dev/null | sed 's/=.*/=***REDACTED***/' >> "$BUNDLE_DIR/config-redacted.txt"
+
+# Network connectivity test
+echo "--- Network Test ---" >> "$BUNDLE_DIR/summary.txt"
+echo -n "API Health: " >> "$BUNDLE_DIR/summary.txt"
+curl -s -o /dev/null -w "%{http_code}" https://api.vercel.com/health >> "$BUNDLE_DIR/summary.txt"
+echo "" >> "$BUNDLE_DIR/summary.txt"
+```
+
+### Step 4: Package Bundle
+```bash
+tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
+echo "Bundle created: $BUNDLE_DIR.tar.gz"
+```
+
+## Output
+- `vercel-debug-YYYYMMDD-HHMMSS.tar.gz` archive containing:
+  - `summary.txt` - Environment and SDK info
+  - `logs.txt` - Recent redacted logs
+  - `config-redacted.txt` - Configuration (secrets removed)
+
+## Error Handling
+| Item | Purpose | Included |
+|------|---------|----------|
+| Environment versions | Compatibility check | ✓ |
+| SDK version | Version-specific bugs | ✓ |
+| Error logs (redacted) | Root cause analysis | ✓ |
+| Config (redacted) | Configuration issues | ✓ |
+| Network test | Connectivity issues | ✓ |
+
+## Examples
+
+### Sensitive Data Handling
+**ALWAYS REDACT:**
+- API keys and tokens
+- Passwords and secrets
+- PII (emails, names, IDs)
+
+**Safe to Include:**
+- Error messages
+- Stack traces (redacted)
+- SDK/runtime versions
+
+### Submit to Support
+1. Create bundle: `bash vercel-debug-bundle.sh`
+2. Review for sensitive data
+3. Upload to Vercel support portal
+
+## Resources
+- [Vercel Support](https://vercel.com/docs/support)
+- [Vercel Status](https://www.vercel-status.com)
+
+## Next Steps
+For rate limit issues, see `vercel-rate-limits`.

package/skills/vercel-deploy-integration/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: vercel-deploy-integration
+description: |
+  Deploy Vercel integrations to Vercel, Fly.io, and Cloud Run platforms.
+  Use when deploying Vercel-powered applications to production,
+  configuring platform-specific secrets, or setting up deployment pipelines.
+  Trigger with phrases like "deploy vercel", "vercel Vercel",
+  "vercel production deploy", "vercel Cloud Run", "vercel Fly.io".
+allowed-tools: Read, Write, Edit, Bash(vercel:*), Bash(fly:*), Bash(gcloud:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Deploy Integration
+
+## Overview
+Deploy Vercel-powered applications to popular platforms with proper secrets management.
+
+## Prerequisites
+- Vercel API keys for production environment
+- Platform CLI installed (vercel, fly, or gcloud)
+- Application code ready for deployment
+- Environment variables documented
+
+## Vercel Deployment
+
+### Environment Setup
+```bash
+# Add Vercel secrets to Vercel
+vercel secrets add vercel_api_key sk_live_***
+vercel secrets add vercel_webhook_secret whsec_***
+
+# Link to project
+vercel link
+
+# Deploy preview
+vercel
+
+# Deploy production
+vercel --prod
+```
+
+### vercel.json Configuration
+```json
+{
+  "env": {
+    "VERCEL_API_KEY": "@vercel_api_key"
+  },
+  "functions": {
+    "api/**/*.ts": {
+      "maxDuration": 30
+    }
+  }
+}
+```
+
+## Fly.io Deployment
+
+### fly.toml
+```toml
+app = "my-vercel-app"
+primary_region = "iad1"
+
+[env]
+  NODE_ENV = "production"
+
+[http_service]
+  internal_port = 3000
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+```
+
+### Secrets
+```bash
+# Set Vercel secrets
+fly secrets set VERCEL_API_KEY=sk_live_***
+fly secrets set VERCEL_WEBHOOK_SECRET=whsec_***
+
+# Deploy
+fly deploy
+```
+
+## Google Cloud Run
+
+### Dockerfile
+```dockerfile
+FROM node:20-slim
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY . .
+CMD ["npm", "start"]
+```
+
+### Deploy Script
+```bash
+#!/bin/bash
+# deploy-cloud-run.sh
+
+PROJECT_ID="${GOOGLE_CLOUD_PROJECT}"
+SERVICE_NAME="vercel-service"
+REGION="None"
+
+# Build and push image
+gcloud builds submit --tag gcr.io/$PROJECT_ID/$SERVICE_NAME
+
+# Deploy to Cloud Run
+gcloud run deploy $SERVICE_NAME \
+  --image gcr.io/$PROJECT_ID/$SERVICE_NAME \
+  --region $REGION \
+  --platform managed \
+  --allow-unauthenticated \
+  --set-secrets=VERCEL_API_KEY=vercel-api-key:latest
+```
+
+## Environment Configuration Pattern
+
+```typescript
+// config/vercel.ts
+interface VercelConfig {
+  apiKey: string;
+  environment: 'development' | 'staging' | 'production';
+  webhookSecret?: string;
+}
+
+export function getVercelConfig(): VercelConfig {
+  const env = process.env.NODE_ENV || 'development';
+
+  return {
+    apiKey: process.env.VERCEL_API_KEY!,
+    environment: env as VercelConfig['environment'],
+    webhookSecret: process.env.VERCEL_WEBHOOK_SECRET,
+  };
+}
+```
+
+## Health Check Endpoint
+
+```typescript
+// api/health.ts
+export async function GET() {
+  const vercelStatus = await checkVercelConnection();
+
+  return Response.json({
+    status: vercelStatus ? 'healthy' : 'degraded',
+    services: {
+      vercel: vercelStatus,
+    },
+    timestamp: new Date().toISOString(),
+  });
+}
+```
+
+## Instructions
+
+### Step 1: Choose Deployment Platform
+Select the platform that best fits your infrastructure needs and follow the platform-specific guide below.
+
+### Step 2: Configure Secrets
+Store Vercel API keys securely using the platform's secrets management.
+
+### Step 3: Deploy Application
+Use the platform CLI to deploy your application with Vercel integration.
+
+### Step 4: Verify Health
+Test the health check endpoint to confirm Vercel connectivity.
+
+## Output
+- Application deployed to production
+- Vercel secrets securely configured
+- Health check endpoint functional
+- Environment-specific configuration in place
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Secret not found | Missing configuration | Add secret via platform CLI |
+| Deploy timeout | Large build | Increase build timeout |
+| Health check fails | Wrong API key | Verify environment variable |
+| Cold start issues | No warm-up | Configure minimum instances |
+
+## Examples
+
+### Quick Deploy Script
+```bash
+#!/bin/bash
+# Platform-agnostic deploy helper
+case "$1" in
+  vercel)
+    vercel secrets add vercel_api_key "$VERCEL_API_KEY"
+    vercel --prod
+    ;;
+  fly)
+    fly secrets set VERCEL_API_KEY="$VERCEL_API_KEY"
+    fly deploy
+    ;;
+esac
+```
+
+## Resources
+- [Vercel Documentation](https://vercel.com/docs)
+- [Fly.io Documentation](https://fly.io/docs)
+- [Cloud Run Documentation](https://cloud.google.com/run/docs)
+- [Vercel Deploy Guide](https://vercel.com/docs/deploy)
+
+## Next Steps
+For webhook handling, see `vercel-webhooks-events`.

package/skills/vercel-deploy-preview/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: vercel-deploy-preview
+description: |
+  Execute Vercel primary workflow: Deploy Preview.
+  Use when Deploying a preview for a pull request,
+  Testing changes before production, or Sharing preview URLs with stakeholders.
+  Trigger with phrases like "vercel deploy preview",
+  "create preview deployment with vercel".
+allowed-tools: Read, Write, Edit, Bash(npm:*), Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Deploy Preview
+
+## Overview
+Deploy preview environments for pull requests and branches.
+This is the primary workflow for Vercel - instant previews for every commit.
+
+
+## Prerequisites
+- Completed `vercel-install-auth` setup
+- Understanding of Vercel core concepts
+- Valid API credentials configured
+
+## Instructions
+
+### Step 1: Initialize
+```typescript
+// Step 1 implementation
+```
+
+### Step 2: Execute
+```typescript
+// Step 2 implementation
+```
+
+### Step 3: Finalize
+```typescript
+// Step 3 implementation
+```
+
+## Output
+- Completed Deploy Preview execution
+- Expected results from Vercel API
+- Success confirmation or error details
+
+## Error Handling
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Error 1 | Cause | Solution |
+| Error 2 | Cause | Solution |
+
+## Examples
+
+### Complete Workflow
+```typescript
+// Complete workflow example
+```
+
+### Common Variations
+- Variation 1: Description
+- Variation 2: Description
+
+## Resources
+- [Vercel Documentation](https://vercel.com/docs)
+- [Vercel API Reference](https://vercel.com/docs/api)
+
+## Next Steps
+For secondary workflow, see `vercel-edge-functions`.

package/skills/vercel-edge-functions/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: vercel-edge-functions
+description: |
+  Execute Vercel secondary workflow: Edge Functions.
+  Use when API routes with minimal latency,
+  or complementing primary workflow.
+  Trigger with phrases like "vercel edge function",
+  "deploy edge function with vercel".
+allowed-tools: Read, Write, Edit, Bash(npm:*), Grep
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Edge Functions
+
+## Overview
+Build and deploy Edge Functions for ultra-low latency at the edge.
+Serverless functions that run close to users worldwide.
+
+
+## Prerequisites
+- Completed `vercel-install-auth` setup
+- Familiarity with `vercel-deploy-preview`
+- Valid API credentials configured
+
+## Instructions
+
+### Step 1: Setup
+```typescript
+// Step 1 implementation
+```
+
+### Step 2: Process
+```typescript
+// Step 2 implementation
+```
+
+### Step 3: Complete
+```typescript
+// Step 3 implementation
+```
+
+## Output
+- Completed Edge Functions execution
+- Results from Vercel API
+- Success confirmation or error details
+
+## Error Handling
+| Aspect | Deploy Preview | Edge Functions |
+|--------|------------|------------|
+| Use Case | Deploying a preview for a pull request | API routes with minimal latency |
+| Complexity | Medium | Medium |
+| Performance | Standard | Ultra-fast (<50ms) |
+
+## Examples
+
+### Complete Workflow
+```typescript
+// Complete workflow example
+```
+
+### Error Recovery
+```typescript
+// Error handling code
+```
+
+## Resources
+- [Vercel Documentation](https://vercel.com/docs)
+- [Vercel API Reference](https://vercel.com/docs/api)
+
+## Next Steps
+For common errors, see `vercel-common-errors`.

package/skills/vercel-enterprise-rbac/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: vercel-enterprise-rbac
+description: |
+  Configure Vercel enterprise SSO, role-based access control, and organization management.
+  Use when implementing SSO integration, configuring role-based permissions,
+  or setting up organization-level controls for Vercel.
+  Trigger with phrases like "vercel SSO", "vercel RBAC",
+  "vercel enterprise", "vercel roles", "vercel permissions", "vercel SAML".
+allowed-tools: Read, Write, Edit
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+---
+
+# Vercel Enterprise RBAC
+
+## Overview
+Configure enterprise-grade access control for Vercel integrations.
+
+## Prerequisites
+- Vercel Enterprise tier subscription
+- Identity Provider (IdP) with SAML/OIDC support
+- Understanding of role-based access patterns
+- Audit logging infrastructure
+
+## Role Definitions
+
+| Role | Permissions | Use Case |
+|------|-------------|----------|
+| Admin | Full access | Platform administrators |
+| Developer | Read/write, no delete | Active development |
+| Viewer | Read-only | Stakeholders, auditors |
+| Service | API access only | Automated systems |
+
+## Role Implementation
+
+```typescript
+enum VercelRole {
+  Admin = 'admin',
+  Developer = 'developer',
+  Viewer = 'viewer',
+  Service = 'service',
+}
+
+interface VercelPermissions {
+  read: boolean;
+  write: boolean;
+  delete: boolean;
+  admin: boolean;
+}
+
+const ROLE_PERMISSIONS: Record<VercelRole, VercelPermissions> = {
+  admin: { read: true, write: true, delete: true, admin: true },
+  developer: { read: true, write: true, delete: false, admin: false },
+  viewer: { read: true, write: false, delete: false, admin: false },
+  service: { read: true, write: true, delete: false, admin: false },
+};
+
+function checkPermission(
+  role: VercelRole,
+  action: keyof VercelPermissions
+): boolean {
+  return ROLE_PERMISSIONS[role][action];
+}
+```
+
+## SSO Integration
+
+### SAML Configuration
+
+```typescript
+// Vercel SAML setup
+const samlConfig = {
+  entryPoint: 'https://idp.company.com/saml/sso',
+  issuer: 'https://vercel.com/saml/metadata',
+  cert: process.env.SAML_CERT,
+  callbackUrl: 'https://app.yourcompany.com/auth/vercel/callback',
+};
+
+// Map IdP groups to Vercel roles
+const groupRoleMapping: Record<string, VercelRole> = {
+  'Engineering': VercelRole.Developer,
+  'Platform-Admins': VercelRole.Admin,
+  'Data-Team': VercelRole.Viewer,
+};
+```
+
+### OAuth2/OIDC Integration
+
+```typescript
+import { OAuth2Client } from 'vercel';
+
+const oauthClient = new OAuth2Client({
+  clientId: process.env.VERCEL_OAUTH_CLIENT_ID!,
+  clientSecret: process.env.VERCEL_OAUTH_CLIENT_SECRET!,
+  redirectUri: 'https://app.yourcompany.com/auth/vercel/callback',
+  scopes: read, write, deploy,
+});
+```
+
+## Organization Management
+
+```typescript
+interface VercelOrganization {
+  id: string;
+  name: string;
+  ssoEnabled: boolean;
+  enforceSso: boolean;
+  allowedDomains: string[];
+  defaultRole: VercelRole;
+}
+
+async function createOrganization(
+  config: VercelOrganization
+): Promise<void> {
+  await vercelClient.organizations.create({
+    ...config,
+    settings: {
+      sso: {
+        enabled: config.ssoEnabled,
+        enforced: config.enforceSso,
+        domains: config.allowedDomains,
+      },
+    },
+  });
+}
+```
+
+## Access Control Middleware
+
+```typescript
+function requireVercelPermission(
+  requiredPermission: keyof VercelPermissions
+) {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    const user = req.user as { vercelRole: VercelRole };
+
+    if (!checkPermission(user.vercelRole, requiredPermission)) {
+      return res.status(403).json({
+        error: 'Forbidden',
+        message: `Missing permission: ${requiredPermission}`,
+      });
+    }
+
+    next();
+  };
+}
+
+// Usage
+app.delete('/vercel/resource/:id',
+  requireVercelPermission('delete'),
+  deleteResourceHandler
+);
+```
+
+## Audit Trail
+
+```typescript
+interface VercelAuditEntry {
+  timestamp: Date;
+  userId: string;
+  role: VercelRole;
+  action: string;
+  resource: string;
+  success: boolean;
+  ipAddress: string;
+}
+
+async function logVercelAccess(entry: VercelAuditEntry): Promise<void> {
+  await auditDb.insert(entry);
+
+  // Alert on suspicious activity
+  if (entry.action === 'delete' && !entry.success) {
+    await alertOnSuspiciousActivity(entry);
+  }
+}
+```
+
+## Instructions
+
+### Step 1: Define Roles
+Map organizational roles to Vercel permissions.
+
+### Step 2: Configure SSO
+Set up SAML or OIDC integration with your IdP.
+
+### Step 3: Implement Middleware
+Add permission checks to API endpoints.
+
+### Step 4: Enable Audit Logging
+Track all access for compliance.
+
+## Output
+- Role definitions implemented
+- SSO integration configured
+- Permission middleware active
+- Audit trail enabled
+
+## Error Handling
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| SSO login fails | Wrong callback URL | Verify IdP config |
+| Permission denied | Missing role mapping | Update group mappings |
+| Token expired | Short TTL | Refresh token logic |
+| Audit gaps | Async logging failed | Check log pipeline |
+
+## Examples
+
+### Quick Permission Check
+```typescript
+if (!checkPermission(user.role, 'write')) {
+  throw new ForbiddenError('Write permission required');
+}
+```
+
+## Resources
+- [Vercel Enterprise Guide](https://vercel.com/docs/enterprise)
+- [SAML 2.0 Specification](https://wiki.oasis-open.org/security/FrontPage)
+- [OpenID Connect Spec](https://openid.net/specs/openid-connect-core-1_0.html)
+
+## Next Steps
+For major migrations, see `vercel-migration-deep-dive`.