@intentsolutionsio/vercel-pack 1.0.0 → 1.0.3

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

@@ -1,209 +1,216 @@
 ---
 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:*)
+description: 'Deploy and manage Vercel production deployments with promotion, rollback,
+  and multi-region strategies.
+
+  Use when deploying to production, configuring deployment regions,
+
+  or setting up blue-green deployment patterns on Vercel.
+
+  Trigger with phrases like "deploy vercel", "vercel production deploy",
+
+  "vercel promote", "vercel rollback", "vercel regions".
+
+  '
+allowed-tools: Read, Write, Edit, Bash(vercel:*), Bash(curl:*)
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- deployment
+- production
+- rollback
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Vercel Deploy Integration
 
 ## Overview
-Deploy Vercel-powered applications to popular platforms with proper secrets management.
+
+Deploy Vercel applications to production using CLI, API, and Git-triggered workflows. Covers deployment promotion, instant rollback, rolling releases, multi-region function configuration, and deploy hooks for headless CMS integration.
 
 ## Prerequisites
-- Vercel API keys for production environment
-- Platform CLI installed (vercel, fly, or gcloud)
-- Application code ready for deployment
-- Environment variables documented
 
-## Vercel Deployment
+- Vercel project linked and configured
+- Production environment variables set
+- Custom domain configured (optional)
+- `VERCEL_TOKEN` for API-based deployments
 
-### 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
+## Instructions
 
-# Deploy preview
-vercel
+### Step 1: Production Deploy Methods
 
-# Deploy production
+```bash
+# Method 1: CLI direct production deploy
 vercel --prod
-```
 
-### vercel.json Configuration
-```json
-{
-  "env": {
-    "VERCEL_API_KEY": "@vercel_api_key"
-  },
-  "functions": {
-    "api/**/*.ts": {
-      "maxDuration": 30
+# Method 2: Promote a preview deployment to production
+vercel promote https://my-app-preview-xxx.vercel.app
+
+# Method 3: API-based deployment
+curl -X POST "https://api.vercel.com/v13/deployments" \
+  -H "Authorization: Bearer $VERCEL_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "my-app",
+    "target": "production",
+    "gitSource": {
+      "type": "github",
+      "repoId": "123456789",
+      "ref": "main",
+      "sha": "'$(git rev-parse HEAD)'"
     }
-  }
-}
-```
-
-## 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
+# Method 4: Deploy Hook (for CMS-triggered rebuilds)
+curl -X POST "https://api.vercel.com/v1/integrations/deploy/prj_xxx/hook_xxx"
 ```
 
-### Secrets
+### Step 2: Instant Rollback
+
 ```bash
-# Set Vercel secrets
-fly secrets set VERCEL_API_KEY=sk_live_***
-fly secrets set VERCEL_WEBHOOK_SECRET=whsec_***
+# Roll back to the previous production deployment (no rebuild)
+vercel rollback
 
-# Deploy
-fly deploy
-```
+# Roll back to a specific deployment
+vercel rollback dpl_xxxxxxxxxxxx
 
-## Google Cloud Run
+# Verify the rollback
+vercel ls --prod
+curl -s https://yourdomain.com/api/health | jq .
 
-### Dockerfile
-```dockerfile
-FROM node:20-slim
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --only=production
-COPY . .
-CMD ["npm", "start"]
+# Via API — promote a known-good deployment
+curl -X POST "https://api.vercel.com/v9/projects/my-app/promote" \
+  -H "Authorization: Bearer $VERCEL_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"deploymentId": "dpl_known_good_id"}'
 ```
 
-### 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
-```
+Key points:
 
-## Environment Configuration Pattern
+- Instant rollback swaps production traffic without rebuilding
+- The rolled-back deployment retains its original environment variables
+- All production domains immediately point to the rolled-back deployment
 
-```typescript
-// config/vercel.ts
-interface VercelConfig {
-  apiKey: string;
-  environment: 'development' | 'staging' | 'production';
-  webhookSecret?: string;
-}
+### Step 3: Rolling Releases (Gradual Rollout)
 
-export function getVercelConfig(): VercelConfig {
-  const env = process.env.NODE_ENV || 'development';
+Configure rolling releases in the dashboard under **Settings > Rolling Releases**:
 
-  return {
-    apiKey: process.env.VERCEL_API_KEY!,
-    environment: env as VercelConfig['environment'],
-    webhookSecret: process.env.VERCEL_WEBHOOK_SECRET,
-  };
+```json
+// vercel.json — rolling release config
+{
+  "rollingRelease": {
+    "enabled": true,
+    "stages": [
+      { "targetPercentage": 10, "duration": 300 },
+      { "targetPercentage": 50, "duration": 600 },
+      { "targetPercentage": 100 }
+    ]
+  }
 }
 ```
 
-## Health Check Endpoint
+This routes 10% of traffic to the new deployment for 5 minutes, then 50% for 10 minutes, then 100%. If errors spike during any stage, rollback instantly.
 
-```typescript
-// api/health.ts
-export async function GET() {
-  const vercelStatus = await checkVercelConnection();
+### Step 4: Multi-Region Function Configuration
 
-  return Response.json({
-    status: vercelStatus ? 'healthy' : 'degraded',
-    services: {
-      vercel: vercelStatus,
+```json
+// vercel.json — deploy functions to specific regions
+{
+  "regions": ["iad1", "sfo1", "cdg1", "hnd1"],
+  "functions": {
+    "api/user.ts": {
+      "memory": 1024,
+      "maxDuration": 30
     },
-    timestamp: new Date().toISOString(),
-  });
+    "api/heavy-compute.ts": {
+      "memory": 3008,
+      "maxDuration": 60,
+      "regions": ["iad1"]
+    }
+  }
 }
 ```
 
-## Instructions
+Available regions:
 
-### Step 1: Choose Deployment Platform
-Select the platform that best fits your infrastructure needs and follow the platform-specific guide below.
+| Region | Location | Code |
+|--------|----------|------|
+| Washington, D.C. | US East | `iad1` |
+| San Francisco | US West | `sfo1` |
+| Paris | Europe | `cdg1` |
+| Tokyo | Asia | `hnd1` |
+| Sydney | Australia | `syd1` |
+| S. Paulo | South America | `gru1` |
+| London | Europe | `lhr1` |
 
-### Step 2: Configure Secrets
-Store Vercel API keys securely using the platform's secrets management.
+### Step 5: Deploy Hooks (CMS Triggers)
 
-### Step 3: Deploy Application
-Use the platform CLI to deploy your application with Vercel integration.
+Create deploy hooks in **Settings > Git > Deploy Hooks**:
 
-### 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
+```bash
+# Create via dashboard, then trigger with POST
+curl -X POST "https://api.vercel.com/v1/integrations/deploy/prj_xxx/hook_xxx"
 
-## 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 |
+# Common CMS integrations:
+# Contentful — webhook URL → Vercel deploy hook
+# Sanity — GROQ listener → deploy hook
+# Strapi — lifecycle hook → deploy hook
+```
 
-## Examples
+### Step 6: Deployment Monitoring
 
-### 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
+# List recent production deployments
+vercel ls --prod --limit=5
+
+# Check deployment state
+curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
+  "https://api.vercel.com/v6/deployments?target=production&limit=5&projectId=prj_xxx" \
+  | jq '.deployments[] | {uid, url, state, createdAt}'
+
+# Monitor deployment logs in real-time
+vercel logs https://yourdomain.com --follow
+```
+
+## Deploy Lifecycle
+
 ```
+git push main
+  → Vercel builds (BUILDING)
+    → Build succeeds (READY)
+      → Traffic routes to new deployment
+        → Old deployment kept for instant rollback
+```
+
+## Output
+
+- Production deployment live via CLI, API, or Git push
+- Instant rollback configured to previous deployment
+- Rolling releases for gradual traffic shifting
+- Function regions optimized for user geography
+- Deploy hooks for CMS-triggered rebuilds
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `DEPLOYMENT_BLOCKED` | Deployment freeze or branch protection | Disable freeze in Settings or use --force |
+| Promotion fails | Preview deployment has different env vars | Verify env vars match between preview and production |
+| Rolling release stuck | Error threshold exceeded | Fix the code, then restart the rollout |
+| Deploy hook returns 404 | Hook deleted or project ID wrong | Recreate the hook in Settings > Git |
+| Region not available | Plan doesn't support multi-region | Upgrade to Pro or Enterprise |
 
 ## 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)
+
+- [Deploying to Vercel](https://vercel.com/docs/deployments)
+- [Instant Rollback](https://vercel.com/docs/instant-rollback)
+- [Rolling Releases](https://vercel.com/docs/rolling-releases)
+- [Promoting Deployments](https://vercel.com/docs/deployments/promoting-a-deployment)
+- [Deploy Hooks](https://vercel.com/docs/deploy-hooks)
+- [Function Regions](https://vercel.com/docs/functions/configuring-functions)
 
 ## Next Steps
-For webhook handling, see `vercel-webhooks-events`.
+
+For webhook integration, see `vercel-webhooks-events`.

package/skills/vercel-deploy-integration/references/errors.md

@@ -0,0 +1,11 @@
+# Error Handling Reference
+
+| 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 |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-deploy-integration/references/examples.md

@@ -0,0 +1,21 @@
+## 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
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-deploy-integration/references/google-cloud-run.md

@@ -0,0 +1,36 @@
+# Google Cloud Run
+
+## 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
+```

package/skills/vercel-deploy-integration/references/vercel-deployment.md

@@ -0,0 +1,35 @@
+# Vercel Deployment
+
+## 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
+    }
+  }
+}
+```