npm - @intentsolutionsio/vercel-pack - Versions diffs - 1.0.0 → 1.0.3 - Mend

@intentsolutionsio/vercel-pack 1.0.0 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (124) hide show

package/skills/vercel-hello-world/SKILL.md CHANGED Viewed

@@ -1,96 +1,182 @@
 ---
 name: vercel-hello-world
-description: |
-  Create a minimal working Vercel example.
-  Use when starting a new Vercel integration, testing your setup,
-  or learning basic Vercel API patterns.
+description: 'Create a minimal working Vercel deployment with a serverless API route.
+  Use when starting a new Vercel project, testing your setup,
+  or learning basic Vercel deployment and API route patterns.
   Trigger with phrases like "vercel hello world", "vercel example",
-  "vercel quick start", "simple vercel code".
-allowed-tools: Read, Write, Edit
+  "vercel quick start", "simple vercel project", "first vercel deploy".
+  '
+allowed-tools: Read, Write, Edit, Bash(vercel:*), Bash(npm:*), Bash(npx:*), Bash(curl:*)
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- api
+- quickstart
+- deployment
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
 # Vercel Hello World
 ## Overview
-Minimal working example demonstrating core Vercel functionality.
+Deploy a minimal project to Vercel with a static page and a serverless API route. Confirms your CLI auth, project structure, and deployment pipeline work end to end.
 ## Prerequisites
 - Completed `vercel-install-auth` setup
-- Valid API credentials configured
-- Development environment ready
+- Vercel CLI installed and authenticated
+- Node.js 18+
 ## Instructions
-### Step 1: Create Entry File
-Create a new file for your hello world example.
+### Step 1: Create Project Structure
-### Step 2: Import and Initialize Client
-```typescript
-import { VercelClient } from 'vercel';
+```bash
+mkdir my-vercel-app && cd my-vercel-app
+npm init -y
+```
-const client = new VercelClient({
-  apiKey: process.env.VERCEL_API_KEY,
-});
+Create the static landing page:
+```html
+<!-- public/index.html -->
+<!DOCTYPE html>
+<html>
+<head><title>Hello Vercel</title></head>
+<body>
+  <h1>Hello from Vercel</h1>
+  <p id="result">Loading...</p>
+  <script>
+    fetch('/api/hello')
+      .then(r => r.json())
+      .then(d => document.getElementById('result').textContent = d.message);
+  </script>
+</body>
+</html>
 ```
-### Step 3: Make Your First API Call
+### Step 2: Create Serverless API Route
 ```typescript
-async function main() {
-  const projects = await vercel.projects.list(); console.log('Projects:', projects.map(p => p.name));
+// api/hello.ts
+import type { VercelRequest, VercelResponse } from '@vercel/node';
+export default function handler(req: VercelRequest, res: VercelResponse) {
+  res.status(200).json({
+    message: 'Hello from Vercel Serverless Function!',
+    timestamp: new Date().toISOString(),
+    region: process.env.VERCEL_REGION || 'local',
+  });
 }
-main().catch(console.error);
 ```
-## Output
-- Working code file with Vercel client initialization
-- Successful API response confirming connection
-- Console output showing:
+Install the types:
+```bash
+npm install --save-dev @vercel/node typescript
 ```
-Success! Your Vercel connection is working.
+### Step 3: Add vercel.json Configuration
+```json
+{
+  "rewrites": [
+    { "source": "/api/(.*)", "destination": "/api/$1" }
+  ],
+  "headers": [
+    {
+      "source": "/api/(.*)",
+      "headers": [
+        { "key": "Cache-Control", "value": "s-maxage=0, stale-while-revalidate" }
+      ]
+    }
+  ]
+}
 ```
-## Error Handling
-| Error | Cause | Solution |
-|-------|-------|----------|
-| Import Error | SDK not installed | Verify with `npm list` or `pip show` |
-| Auth Error | Invalid credentials | Check environment variable is set |
-| Timeout | Network issues | Increase timeout or check connectivity |
-| Rate Limit | Too many requests | Wait and retry with exponential backoff |
+### Step 4: Deploy Preview
-## Examples
+```bash
+# Deploy to a preview URL (not production)
+vercel
-### TypeScript Example
-```typescript
-import { VercelClient } from 'vercel';
+# Output:
+# Vercel CLI 39.x.x
+# 🔗 Linked to your-team/my-vercel-app
+# 🔍 Inspect: https://vercel.com/your-team/my-vercel-app/xxx
+# ✅ Preview: https://my-vercel-app-xxx.vercel.app
+```
-const client = new VercelClient({
-  apiKey: process.env.VERCEL_API_KEY,
-});
+### Step 5: Test the Deployment
-async function main() {
-  const projects = await vercel.projects.list(); console.log('Projects:', projects.map(p => p.name));
-}
+```bash
+# Test static page
+curl -s https://my-vercel-app-xxx.vercel.app/ | head -5
-main().catch(console.error);
+# Test API route
+curl -s https://my-vercel-app-xxx.vercel.app/api/hello | jq .
+# {
+#   "message": "Hello from Vercel Serverless Function!",
+#   "timestamp": "2026-03-22T12:00:00.000Z",
+#   "region": "iad1"
+# }
 ```
-### Python Example
-```python
-from None import VercelClient
+### Step 6: Promote to Production
-client = VercelClient()
+```bash
+# Deploy directly to production
+vercel --prod
-None
+# Or promote the preview deployment
+vercel promote https://my-vercel-app-xxx.vercel.app
 ```
+## Vercel System Environment Variables
+These are available in every function at runtime:
+| Variable | Value |
+|----------|-------|
+| `VERCEL` | `"1"` — always set on Vercel |
+| `VERCEL_ENV` | `"production"`, `"preview"`, or `"development"` |
+| `VERCEL_URL` | Deployment URL (no protocol) |
+| `VERCEL_REGION` | Function region (e.g., `iad1`) |
+| `VERCEL_GIT_COMMIT_SHA` | Git commit hash |
+| `VERCEL_GIT_COMMIT_MESSAGE` | Git commit message |
+## Output
+- Static page served from Vercel CDN
+- Serverless API route returning JSON at `/api/hello`
+- Preview URL for testing before production
+- Production deployment live on your domain
+## Error Handling
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `404 NOT_FOUND` on `/api/hello` | File not in `api/` directory | Move file to project root `api/` folder |
+| `FUNCTION_INVOCATION_FAILED` | Runtime error in handler | Check function logs: `vercel logs <url>` |
+| `BUILD_FAILED` | TypeScript compilation error | Run `npx tsc --noEmit` locally first |
+| `NO_RESPONSE_FROM_FUNCTION` | Handler didn't call `res.send/json` | Ensure all code paths return a response |
+| `FUNCTION_PAYLOAD_TOO_LARGE` | Response body > 4.5 MB | Paginate or stream the response |
 ## Resources
-- [Vercel Getting Started](https://vercel.com/docs/getting-started)
-- [Vercel API Reference](https://vercel.com/docs/api)
-- [Vercel Examples](https://vercel.com/docs/examples)
+- [Vercel Serverless Functions](https://vercel.com/docs/functions)
+- [Vercel Project Configuration](https://vercel.com/docs/project-configuration)
+- [Vercel CLI Deploy](https://vercel.com/docs/cli/deploy)
+- [@vercel/node Runtime](https://vercel.com/docs/functions/runtimes/node-js)
 ## Next Steps
-Proceed to `vercel-local-dev-loop` for development workflow setup.
+Proceed to `vercel-local-dev-loop` for development workflow setup.

package/skills/vercel-incident-runbook/SKILL.md CHANGED Viewed

@@ -1,203 +1,251 @@
 ---
 name: vercel-incident-runbook
-description: |
-  Execute Vercel incident response procedures with triage, mitigation, and postmortem.
-  Use when responding to Vercel-related outages, investigating errors,
-  or running post-incident reviews for Vercel integration failures.
+description: 'Vercel incident response procedures with triage, instant rollback, and
+  postmortem.
+  Use when responding to Vercel-related outages, investigating production errors,
+  or running post-incident reviews for deployment failures.
   Trigger with phrases like "vercel incident", "vercel outage",
   "vercel down", "vercel on-call", "vercel emergency", "vercel broken".
-allowed-tools: Read, Grep, Bash(kubectl:*), Bash(curl:*)
+  '
+allowed-tools: Read, Grep, Bash(vercel:*), Bash(curl:*)
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- incident-response
+- runbook
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
 # Vercel Incident Runbook
 ## Overview
-Rapid incident response procedures for Vercel-related outages.
+Step-by-step incident response for Vercel deployment failures, function errors, and platform outages. Covers rapid triage, instant rollback, communication templates, and postmortem procedures.
 ## Prerequisites
-- Access to Vercel dashboard and status page
-- kubectl access to production cluster
-- Prometheus/Grafana access
-- Communication channels (Slack, PagerDuty)
-## Severity Levels
+- Access to Vercel dashboard and CLI
+- Access to Vercel status page (vercel-status.com)
+- Communication channels (Slack, PagerDuty) configured
+- Log drain or runtime log access
-| Level | Definition | Response Time | Examples |
-|-------|------------|---------------|----------|
-| P1 | Complete outage | < 15 min | Vercel API unreachable |
-| P2 | Degraded service | < 1 hour | High latency, partial failures |
-| P3 | Minor impact | < 4 hours | Webhook delays, non-critical errors |
-| P4 | No user impact | Next business day | Monitoring gaps |
+## Instructions
-## Quick Triage
+### Step 1: Rapid Triage (First 5 Minutes)
 ```bash
-# 1. Check Vercel status
-curl -s https://www.vercel-status.com | jq
+# 1. Check if it's a Vercel platform issue
+curl -s "https://www.vercel-status.com/api/v2/summary.json" \
+  | jq '.status.description, [.components[] | select(.status != "operational") | {name, status}]'
-# 2. Check our integration health
-curl -s https://api.yourapp.com/health | jq '.services.vercel'
+# 2. Check current production deployment status
+vercel ls --prod
+vercel inspect $(vercel ls --prod --json | jq -r '.[0].url')
-# 3. Check error rate (last 5 min)
-curl -s localhost:9090/api/v1/query?query=rate(vercel_errors_total[5m])
+# 3. Check recent deployments — did a deploy just happen?
+curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
+  "https://api.vercel.com/v6/deployments?target=production&limit=5&projectId=prj_xxx" \
+  | jq '.deployments[] | {uid, state, createdAt: (.createdAt/1000 | todate), url}'
-# 4. Recent error logs
-kubectl logs -l app=vercel-integration --since=5m | grep -i error | tail -20
+# 4. Check function logs for errors
+vercel logs $(vercel ls --prod --json | jq -r '.[0].url') --level=error --limit=20
 ```
-## Decision Tree
+### Step 2: Decision Tree
 ```
-Vercel API returning errors?
-├─ YES: Is status.vercel.com showing incident?
-│   ├─ YES → Wait for Vercel to resolve. Enable fallback.
-│   └─ NO → Our integration issue. Check credentials, config.
-└─ NO: Is our service healthy?
-    ├─ YES → Likely resolved or intermittent. Monitor.
-    └─ NO → Our infrastructure issue. Check pods, memory, network.
+Is vercel-status.com showing an incident?
+├── YES → Vercel platform issue
+│   ├── Subscribe to updates on status page
+│   ├── Post internal status: "Vercel platform incident — monitoring"
+│   └── No action needed from us — wait for Vercel resolution
+│
+└── NO → Issue is in our deployment
+    ├── Did a deployment happen in the last 30 minutes?
+    │   ├── YES → Likely deployment regression
+    │   │   └── ROLLBACK immediately (Step 3)
+    │   └── NO → Application-level issue
+    │       ├── Check function logs for new errors
+    │       ├── Check external dependency status (DB, APIs)
+    │       └── Investigate and hotfix (Step 4)
+    │
+    └── Is the issue region-specific?
+        ├── YES → Check function regions, possible edge issue
+        └── NO → Global issue, check code and env vars
 ```
-## Immediate Actions by Error Type
+### Step 3: Instant Rollback (< 30 Seconds)
-### 401/403 - Authentication
 ```bash
-# Verify API key is set
-kubectl get secret vercel-secrets -o jsonpath='{.data.api-key}' | base64 -d
-# Check if key was rotated
-# → Verify in Vercel dashboard
-# Remediation: Update secret and restart pods
-kubectl create secret generic vercel-secrets --from-literal=api-key=NEW_KEY --dry-run=client -o yaml | kubectl apply -f -
-kubectl rollout restart deployment/vercel-integration
+# Option A: Rollback to previous production deployment (fastest)
+vercel rollback
+# This instantly swaps production traffic — no rebuild needed
+# Option B: Rollback to a specific known-good deployment
+vercel rollback dpl_xxxxxxxxxxxx
+# Option C: Via API (for automation/PagerDuty integration)
+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"}'
+# Verify rollback succeeded
+vercel ls --prod
+curl -s https://yourdomain.com/api/health | jq .
 ```
-### 429 - Rate Limited
-```bash
-# Check rate limit headers
-curl -v https://api.vercel.com 2>&1 | grep -i rate
-# Enable request queuing
-kubectl set env deployment/vercel-integration RATE_LIMIT_MODE=queue
+### Step 4: Investigate Root Cause
-# Long-term: Contact Vercel for limit increase
-```
-### 500/503 - Vercel Errors
 ```bash
-# Enable graceful degradation
-kubectl set env deployment/vercel-integration VERCEL_FALLBACK=true
+# Collect evidence while it's fresh
+mkdir incident-$(date +%Y%m%d)
+cd incident-$(date +%Y%m%d)
-# Notify users of degraded service
-# Update status page
+# Function logs around the incident time
+vercel logs https://yourdomain.com --limit=200 > function-logs.txt
-# Monitor Vercel status for resolution
-```
+# Deployment diff — what changed?
+curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
+  "https://api.vercel.com/v13/deployments/dpl_broken" \
+  | jq '.meta' > broken-deployment-meta.json
-## Communication Templates
+# Compare env vars between working and broken deployments
+vercel env ls > env-vars.txt
-### Internal (Slack)
-```
-🔴 P1 INCIDENT: Vercel Integration
-Status: INVESTIGATING
-Impact: [Describe user impact]
-Current action: [What you're doing]
-Next update: [Time]
-Incident commander: @[name]
+# Check git diff between last good and broken commit
+git log --oneline -10
+git diff dpl_good_commit..dpl_broken_commit -- api/ src/
 ```
-### External (Status Page)
+### Step 5: Enable Maintenance Page (If Needed)
+```json
+// vercel.json — temporary maintenance mode via rewrite
+{
+  "rewrites": [
+    {
+      "source": "/((?!_next|api/health).*)",
+      "destination": "/maintenance.html"
+    }
+  ]
+}
 ```
-Vercel Integration Issue
-We're experiencing issues with our Vercel integration.
-Some users may experience [specific impact].
-We're actively investigating and will provide updates.
-Last updated: [timestamp]
+```html
+<!-- public/maintenance.html -->
+<!DOCTYPE html>
+<html>
+<head><title>Maintenance</title></head>
+<body>
+  <h1>We'll be right back</h1>
+  <p>We're performing scheduled maintenance. Please check back shortly.</p>
+</body>
+</html>
 ```
-## Post-Incident
+### Step 6: Communication Templates
-### Evidence Collection
-```bash
-# Generate debug bundle
-./scripts/vercel-debug-bundle.sh
+**Internal — Slack (Incident Start)**
-# Export relevant logs
-kubectl logs -l app=vercel-integration --since=1h > incident-logs.txt
-# Capture metrics
-curl "localhost:9090/api/v1/query_range?query=vercel_errors_total&start=2h" > metrics.json
+```
+:rotating_light: INCIDENT: [Project Name] production issue detected
+Status: Investigating
+Impact: [Description of user impact]
+Start time: [UTC timestamp]
+On-call: @[engineer]
+Thread: replies here
 ```
-### Postmortem Template
-```markdown
-## Incident: Vercel [Error Type]
-**Date:** YYYY-MM-DD
-**Duration:** X hours Y minutes
-**Severity:** P[1-4]
-### Summary
-[1-2 sentence description]
-### Timeline
-- HH:MM - [Event]
-- HH:MM - [Event]
+**Internal — Slack (Mitigation)**
-### Root Cause
-[Technical explanation]
+```
+:white_check_mark: MITIGATED: [Project Name]
+Action: Rolled back to deployment dpl_xxx
+Impact duration: [X minutes]
+Root cause: [Brief description]
+Postmortem: [link] scheduled for [date]
+```
-### Impact
-- Users affected: N
-- Revenue impact: $X
+**External — Status Page**
-### Action Items
-- [ ] [Preventive measure] - Owner - Due date
+```
+Title: Degraded performance on [service]
+Body: We are investigating reports of [issue]. Some users may experience
+[impact]. Our team is actively working on a resolution.
+Update: The issue has been resolved. [Brief root cause].
 ```
-## Instructions
-### Step 1: Quick Triage
-Run the triage commands to identify the issue source.
+### Step 7: Postmortem Template
-### Step 2: Follow Decision Tree
-Determine if the issue is Vercel-side or internal.
+```markdown
+# Incident Postmortem: [Title]
+## Summary
+- Duration: [start] to [end] ([X minutes])
+- Impact: [users/requests affected]
+- Severity: [P1/P2/P3]
+## Timeline (UTC)
+- HH:MM — [event]
+- HH:MM — Alert fired
+- HH:MM — On-call acknowledged
+- HH:MM — Root cause identified
+- HH:MM — Rollback executed
+- HH:MM — Service restored
+## Root Cause
+[What broke and why]
+## Resolution
+[What was done to fix it]
+## Action Items
+- [ ] [Preventive action] — Owner: @xxx — Due: [date]
+- [ ] [Detection improvement] — Owner: @xxx — Due: [date]
+- [ ] [Process improvement] — Owner: @xxx — Due: [date]
+```
-### Step 3: Execute Immediate Actions
-Apply the appropriate remediation for the error type.
+## Incident Severity Levels
-### Step 4: Communicate Status
-Update internal and external stakeholders.
+| Severity | Definition | Response Time | Rollback? |
+|----------|-----------|---------------|-----------|
+| P1 | Production down, all users affected | < 5 min | Immediate |
+| P2 | Degraded, some users affected | < 15 min | If not fixable in 30 min |
+| P3 | Minor issue, workaround exists | < 1 hour | No |
+| P4 | Cosmetic or non-urgent | Next business day | No |
 ## Output
-- Issue identified and categorized
-- Remediation applied
-- Stakeholders notified
-- Evidence collected for postmortem
+- Incident categorized and triaged within 5 minutes
+- Instant rollback executed if deployment regression detected
+- Communication sent to internal and external stakeholders
+- Postmortem scheduled with action items
 ## Error Handling
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| Can't reach status page | Network issue | Use mobile or VPN |
-| kubectl fails | Auth expired | Re-authenticate |
-| Metrics unavailable | Prometheus down | Check backup metrics |
-| Secret rotation fails | Permission denied | Escalate to admin |
-## Examples
-### One-Line Health Check
-```bash
-curl -sf https://api.yourapp.com/health | jq '.services.vercel.status' || echo "UNHEALTHY"
-```
+| Scenario | Action |
+|----------|--------|
+| Vercel status page shows incident | Monitor, communicate, no deployment changes |
+| `vercel rollback` fails | Use API promotion: POST to `/v9/projects/.../promote` |
+| Rollback deployment also broken | Deploy from a known-good git tag |
+| Cannot access Vercel dashboard | Use CLI with saved VERCEL_TOKEN |
+| Log retention expired | Check external log drain provider |
 ## Resources
 - [Vercel Status Page](https://www.vercel-status.com)
-- [Vercel Support](https://support.vercel.com)
+- [Instant Rollback](https://vercel.com/docs/instant-rollback)
+- [Vercel Support](https://vercel.com/support)
+- [Vercel Logs CLI](https://vercel.com/docs/cli/logs)
 ## Next Steps
-For data handling, see `vercel-data-handling`.
+For data handling and compliance, see `vercel-data-handling`.

package/skills/vercel-incident-runbook/references/errors.md ADDED Viewed

@@ -0,0 +1,11 @@
+# Error Handling Reference
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Can't reach status page | Network issue | Use mobile or VPN |
+| kubectl fails | Auth expired | Re-authenticate |
+| Metrics unavailable | Prometheus down | Check backup metrics |
+| Secret rotation fails | Permission denied | Escalate to admin |
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-incident-runbook/references/examples.md ADDED Viewed

@@ -0,0 +1,10 @@
+## Examples
+### One-Line Health Check
+```bash
+curl -sf https://api.yourapp.com/health | jq '.services.vercel.status' || echo "UNHEALTHY"
+```
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*