@intentsolutionsio/vercel-pack 1.0.0 → 1.0.3

package/skills/vercel-incident-runbook/references/immediate-actions-by-error-type.md

@@ -0,0 +1,41 @@
+# Immediate Actions By Error Type
+
+## Immediate Actions by Error Type
+
+### 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
+```
+
+### 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
+
+# Long-term: Contact Vercel for limit increase
+```
+
+### 500/503 - Vercel Errors
+
+```bash
+# Enable graceful degradation
+kubectl set env deployment/vercel-integration VERCEL_FALLBACK=true
+
+# Notify users of degraded service
+# Update status page
+
+# Monitor Vercel status for resolution
+```

package/skills/vercel-install-auth/SKILL.md

@@ -1,90 +1,167 @@
 ---
 name: vercel-install-auth
-description: |
-  Install and configure Vercel SDK/CLI authentication.
-  Use when setting up a new Vercel integration, configuring API keys,
-  or initializing Vercel in your project.
+description: 'Install Vercel CLI and configure API token authentication.
+
+  Use when setting up Vercel for the first time, creating access tokens,
+
+  or initializing a project with vercel link.
+
   Trigger with phrases like "install vercel", "setup vercel",
-  "vercel auth", "configure vercel API key".
-allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(pip:*), Grep
+
+  "vercel auth", "configure vercel token", "vercel login".
+
+  '
+allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(npx:*), Bash(vercel:*), Grep
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- authentication
+- cli
+- setup
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Vercel Install & Auth
 
 ## Overview
-Set up Vercel SDK/CLI and configure authentication credentials.
+
+Install the Vercel CLI, create a scoped access token, and link your local project to a Vercel project. This skill covers both interactive login and headless CI token authentication via the REST API.
 
 ## Prerequisites
-- Node.js 18+ or Python 3.10+
-- Package manager (npm, pnpm, or pip)
-- Vercel account with API access
-- API key from Vercel dashboard
+
+- Node.js 18+ installed
+- npm, pnpm, or yarn available
+- A Vercel account (hobby, pro, or enterprise)
 
 ## Instructions
 
-### Step 1: Install SDK
+### Step 1: Install Vercel CLI
+
 ```bash
-# Node.js
-npm install vercel
+set -euo pipefail
+# Global install (recommended)
+npm install -g vercel@latest
 
-# Python
-pip install None
+# Or project-local
+npm install --save-dev vercel@latest
+
+# Verify installation
+vercel --version
 ```
 
-### Step 2: Configure Authentication
+### Step 2: Authenticate — Interactive Login
+
 ```bash
-# Set environment variable
-export VERCEL_API_KEY="your-api-key"
+# Opens browser for OAuth login, stores token in ~/.config/com.vercel.cli
+vercel login
 
-# Or create .env file
-echo 'VERCEL_API_KEY=your-api-key' >> .env
+# Or login with a specific email
+vercel login your@email.com
+
+# Login with GitHub
+vercel login --github
+
+# Login with GitLab
+vercel login --gitlab
 ```
 
-### Step 3: Verify Connection
-```typescript
-const teams = await vercel.teams.list(); console.log(teams.length > 0 ? 'OK' : 'No teams');
+### Step 3: Authenticate — Headless Token (CI/CD)
+
+Create a token in the Vercel dashboard at **Settings > Tokens** or via the API:
+
+```bash
+# Use a pre-created token — set as environment variable
+export VERCEL_TOKEN="your-access-token-here"
+
+# The CLI reads VERCEL_TOKEN automatically — no login needed
+vercel whoami
+# Output: your-username
+
+# Scope the token to a specific team
+export VERCEL_ORG_ID="team_xxxxxxxxxxxx"
+export VERCEL_PROJECT_ID="prj_xxxxxxxxxxxx"
 ```
 
-## Output
-- Installed SDK package in node_modules or site-packages
-- Environment variable or .env file with API key
-- Successful connection verification output
+### Step 4: Link Local Project
 
-## Error Handling
-| Error | Cause | Solution |
-|-------|-------|----------|
-| Invalid API Key | Incorrect or expired key | Verify key in Vercel dashboard |
-| Rate Limited | Exceeded quota | Check quota at https://vercel.com/docs |
-| Network Error | Firewall blocking | Ensure outbound HTTPS allowed |
-| Module Not Found | Installation failed | Run `npm install` or `pip install` again |
+```bash
+# Interactive — walks you through project selection
+vercel link
+
+# Or link to a specific project by name
+vercel link --project my-project-name
+
+# Verify the link — pulls .vercel/project.json
+cat .vercel/project.json
+# {"orgId":"team_xxx","projectId":"prj_xxx"}
+```
 
-## Examples
+### Step 5: Verify Connection via REST API
 
-### TypeScript Setup
-```typescript
-import { VercelClient } from 'vercel';
+```bash
+# Test token against the REST API directly
+curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
+  https://api.vercel.com/v9/projects | jq '.projects[].name'
 
-const client = new VercelClient({
-  apiKey: process.env.VERCEL_API_KEY,
-});
+# List teams
+curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
+  https://api.vercel.com/v2/teams | jq '.teams[].name'
 ```
 
-### Python Setup
-```python
-from None import VercelClient
+### Step 6: Pull Environment Variables
 
-client = VercelClient(
-    api_key=os.environ.get('VERCEL_API_KEY')
-)
+```bash
+# Pull remote env vars to local .env.development.local
+vercel env pull .env.development.local
+
+# Pull for a specific environment
+vercel env pull --environment=preview
+```
+
+## Token Scopes Reference
+
+| Scope | Access | Use Case |
+|-------|--------|----------|
+| Full Account | All projects, all teams | Personal dev |
+| Team-scoped | One team only | Team CI/CD |
+| Project-scoped | One project only | Per-project automation |
+
+Tokens support optional expiration dates. Set short-lived tokens (90 days) for CI and rotate them on a schedule.
+
+## Output
+
+- Vercel CLI installed and on PATH
+- Authentication token stored or environment variable set
+- Local project linked to Vercel project via `.vercel/project.json`
+- Environment variables pulled to local `.env.development.local`
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Error: No token found` | Not logged in, no VERCEL_TOKEN | Run `vercel login` or export VERCEL_TOKEN |
+| `Error: Invalid token` | Token expired or revoked | Generate new token at vercel.com/account/tokens |
+| `EACCES permission denied` | Global install without sudo | Use `npx vercel` or install with `--prefix ~/.npm-global` |
+| `Error: Team not found` | Wrong VERCEL_ORG_ID | Check team ID in Vercel dashboard > Settings > General |
+| `fetch failed` | Network or proxy issue | Check `HTTPS_PROXY` env var, ensure port 443 outbound |
+
+## `.gitignore` Setup
+
+```gitignore
+# Vercel
+.vercel/
+.env*.local
 ```
 
 ## Resources
-- [Vercel Documentation](https://vercel.com/docs)
-- [Vercel Dashboard](https://api.vercel.com)
-- [Vercel Status](https://www.vercel-status.com)
+
+- [Vercel CLI Overview](https://vercel.com/docs/cli)
+- [Access Tokens](https://vercel.com/docs/rest-api#creating-an-access-token)
+- [CLI Project Linking](https://vercel.com/docs/cli/project-linking)
+- [Vercel REST API Reference](https://vercel.com/docs/rest-api)
 
 ## Next Steps
-After successful auth, proceed to `vercel-hello-world` for your first API call.
+
+After successful auth, proceed to `vercel-hello-world` for your first deployment.