@intentsolutionsio/vercel-pack 1.0.0 → 1.0.3

package/skills/vercel-data-handling/references/implementation.md

@@ -0,0 +1,223 @@
+# Data Handling Reference
+
+## Overview
+
+Handle sensitive data correctly when integrating with Vercel.
+
+## Prerequisites
+
+- Understanding of GDPR/CCPA requirements
+- Vercel SDK with data export capabilities
+- Database for audit logging
+- Scheduled job infrastructure for cleanup
+
+## Data Classification
+
+| Category | Examples | Handling |
+|----------|----------|----------|
+| PII | Email, name, phone | Encrypt, minimize |
+| Sensitive | API keys, tokens | Never log, rotate |
+| Business | Usage metrics | Aggregate when possible |
+| Public | Product names | Standard handling |
+
+## PII Detection
+
+```typescript
+const PII_PATTERNS = [
+  { type: 'email', regex: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g },
+  { type: 'phone', regex: /\d{3}[-.]?\d{3}[-.]?\d{4}/g },
+  { type: 'ssn', regex: /\d{3}-\d{2}-\d{4}/g },
+  { type: 'credit_card', regex: /\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}/g },
+];
+
+function detectPII(text: string): { type: string; match: string }[] {
+  const findings: { type: string; match: string }[] = [];
+
+  for (const pattern of PII_PATTERNS) {
+    const matches = text.matchAll(pattern.regex);
+    for (const match of matches) {
+      findings.push({ type: pattern.type, match: match[0] });
+    }
+  }
+
+  return findings;
+}
+```
+
+## Data Redaction
+
+```typescript
+function redactPII(data: Record<string, any>): Record<string, any> {
+  const sensitiveFields = ['email', 'phone', 'ssn', 'password', 'apiKey'];
+  const redacted = { ...data };
+
+  for (const field of sensitiveFields) {
+    if (redacted[field]) {
+      redacted[field] = '[REDACTED]';
+    }
+  }
+
+  return redacted;
+}
+
+// Use in logging
+console.log('Vercel request:', redactPII(requestData));
+```
+
+## Data Retention Policy
+
+### Retention Periods
+
+| Data Type | Retention | Reason |
+|-----------|-----------|--------|
+| API logs | 30 days | Debugging |
+| Error logs | 90 days | Root cause analysis |
+| Audit logs | 7 years | Compliance |
+| PII | Until deletion request | GDPR/CCPA |
+
+### Automatic Cleanup
+
+```typescript
+async function cleanupVercelData(retentionDays: number): Promise<void> {
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - retentionDays);
+
+  await db.vercelLogs.deleteMany({
+    createdAt: { $lt: cutoff },
+    type: { $nin: ['audit', 'compliance'] },
+  });
+}
+
+// Schedule daily cleanup
+cron.schedule('0 3 * * *', () => cleanupVercelData(30));
+```
+
+## GDPR/CCPA Compliance
+
+### Data Subject Access Request (DSAR)
+
+```typescript
+async function exportUserData(userId: string): Promise<DataExport> {
+  const vercelData = await vercelClient.getUserData(userId);
+
+  return {
+    source: 'Vercel',
+    exportedAt: new Date().toISOString(),
+    data: {
+      profile: vercelData.profile,
+      activities: vercelData.activities,
+      // Include all user-related data
+    },
+  };
+}
+```
+
+### Right to Deletion
+
+```typescript
+async function deleteUserData(userId: string): Promise<DeletionResult> {
+  // 1. Delete from Vercel
+  await vercelClient.deleteUser(userId);
+
+  // 2. Delete local copies
+  await db.vercelUserCache.deleteMany({ userId });
+
+  // 3. Audit log (required to keep)
+  await auditLog.record({
+    action: 'GDPR_DELETION',
+    userId,
+    service: 'vercel',
+    timestamp: new Date(),
+  });
+
+  return { success: true, deletedAt: new Date() };
+}
+```
+
+## Data Minimization
+
+```typescript
+// Only request needed fields
+const user = await vercelClient.getUser(userId, {
+  fields: ['id', 'name'], // Not email, phone, address
+});
+
+// Don't store unnecessary data
+const cacheData = {
+  id: user.id,
+  name: user.name,
+  // Omit sensitive fields
+};
+```
+
+## Instructions
+
+### Step 1: Classify Data
+
+Categorize all Vercel data by sensitivity level.
+
+### Step 2: Implement PII Detection
+
+Add regex patterns to detect sensitive data in logs.
+
+### Step 3: Configure Redaction
+
+Apply redaction to sensitive fields before logging.
+
+### Step 4: Set Up Retention
+
+Configure automatic cleanup with appropriate retention periods.
+
+## Output
+
+- Data classification documented
+- PII detection implemented
+- Redaction in logging active
+- Retention policy enforced
+
+## Error Handling
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| PII in logs | Missing redaction | Wrap logging with redact |
+| Deletion failed | Data locked | Check dependencies |
+| Export incomplete | Timeout | Increase batch size |
+| Audit gap | Missing entries | Review log pipeline |
+
+## Examples
+
+### Quick PII Scan
+
+```typescript
+const findings = detectPII(JSON.stringify(userData));
+if (findings.length > 0) {
+  console.warn(`PII detected: ${findings.map(f => f.type).join(', ')}`);
+}
+```
+
+### Redact Before Logging
+
+```typescript
+const safeData = redactPII(apiResponse);
+logger.info('Vercel response:', safeData);
+```
+
+### GDPR Data Export
+
+```typescript
+const userExport = await exportUserData('user-123');
+await sendToUser(userExport);
+```
+
+## Resources
+
+- GDPR Developer Guide
+- [CCPA Compliance Guide](https://oag.ca.gov/privacy/ccpa)
+- Vercel Privacy Guide
+
+## Next Steps
+
+For enterprise access control, see `vercel-enterprise-rbac`.
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

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

@@ -1,111 +1,207 @@
 ---
 name: vercel-debug-bundle
-description: |
-  Collect Vercel debug evidence for support tickets and troubleshooting.
+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
+
+  '
+allowed-tools: Read, Bash(vercel:*), Bash(curl:*), Bash(tar:*), Bash(jq:*), Grep
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- debugging
+- support
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Vercel Debug Bundle
 
 ## Overview
-Collect all necessary diagnostic information for Vercel support tickets.
+
+Collect a comprehensive debug bundle containing deployment state, function logs, environment configuration, and build output for Vercel support escalation or team troubleshooting.
+
+## Current State
+
+!`vercel --version 2>/dev/null || echo 'Vercel CLI not installed'`
+!`node --version 2>/dev/null || echo 'Node.js N/A'`
 
 ## Prerequisites
-- Vercel SDK installed
-- Access to application logs
-- Permission to collect environment info
+
+- Vercel CLI installed and authenticated
+- Access to the affected deployment
+- `jq` for JSON processing (recommended)
 
 ## Instructions
 
-### Step 1: Create Debug Bundle Script
+### Step 1: Collect Deployment Information
+
 ```bash
-#!/bin/bash
-# vercel-debug-bundle.sh
+#!/usr/bin/env bash
+set -euo pipefail
 
+DEPLOY_URL="${1:-$(vercel ls --json 2>/dev/null | jq -r '.[0].url')}"
 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"
+echo "=== Collecting debug bundle for: $DEPLOY_URL ==="
+
+# Deployment inspection
+vercel inspect "$DEPLOY_URL" > "$BUNDLE_DIR/inspect.txt" 2>&1 || true
+
+# Deployment details via API
+curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
+  "https://api.vercel.com/v13/deployments/$DEPLOY_URL" \
+  | jq '{uid, name, state, target, readyState, errorMessage, meta, regions}' \
+  > "$BUNDLE_DIR/deployment.json" 2>/dev/null || true
 ```
 
-### Step 2: Collect Environment Info
+### Step 2: Collect Function Logs
+
 ```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"
+# Recent function logs (last 100 entries)
+vercel logs "$DEPLOY_URL" --output=short --limit=100 \
+  > "$BUNDLE_DIR/function-logs.txt" 2>&1 || true
+
+# Function logs via API with filtering
+curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
+  "https://api.vercel.com/v2/deployments/$DEPLOY_URL/events?limit=100&direction=backward" \
+  | jq '.[] | {timestamp: .created, type, text}' \
+  > "$BUNDLE_DIR/events.json" 2>/dev/null || true
 ```
 
-### Step 3: Gather SDK and Logs
+### Step 3: Collect Build Output
+
 ```bash
-# SDK version
-npm list vercel 2>/dev/null >> "$BUNDLE_DIR/summary.txt"
+# Build logs
+curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
+  "https://api.vercel.com/v13/deployments/$DEPLOY_URL" \
+  | jq '.build' > "$BUNDLE_DIR/build-info.json" 2>/dev/null || true
+
+# List all functions in the deployment
+curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
+  "https://api.vercel.com/v13/deployments/$DEPLOY_URL" \
+  | jq '.routes, .functions' > "$BUNDLE_DIR/routes-functions.json" 2>/dev/null || true
+```
 
-# Recent logs (redacted)
-grep -i "vercel" ~/.npm/_logs/*.log 2>/dev/null | tail -50 >> "$BUNDLE_DIR/logs.txt"
+### Step 4: Collect Environment State (Redacted)
+
+```bash
+# Environment variable names only (no values)
+vercel env ls > "$BUNDLE_DIR/env-vars-list.txt" 2>&1 || true
+
+# Project configuration (redacted)
+if [ -f "vercel.json" ]; then
+  cp vercel.json "$BUNDLE_DIR/vercel.json"
+fi
+
+# Package versions
+if [ -f "package.json" ]; then
+  jq '{name, version, dependencies, devDependencies, engines}' package.json \
+    > "$BUNDLE_DIR/package-summary.json" 2>/dev/null || true
+fi
+
+# Node.js and CLI versions
+{
+  echo "node: $(node --version 2>/dev/null || echo 'N/A')"
+  echo "npm: $(npm --version 2>/dev/null || echo 'N/A')"
+  echo "vercel: $(vercel --version 2>/dev/null || echo 'N/A')"
+  echo "os: $(uname -a)"
+  echo "date: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+} > "$BUNDLE_DIR/environment.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"
+### Step 5: Check Vercel Status Page
 
-# 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"
+```bash
+# Vercel platform status
+curl -s "https://www.vercel-status.com/api/v2/summary.json" \
+  | jq '{status: .status.description, components: [.components[] | {name, status}]}' \
+  > "$BUNDLE_DIR/platform-status.json" 2>/dev/null || true
 ```
 
-### Step 4: Package Bundle
+### Step 6: Package the Bundle
+
 ```bash
-tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
-echo "Bundle created: $BUNDLE_DIR.tar.gz"
+# Create archive — excludes secrets
+tar czf "${BUNDLE_DIR}.tar.gz" "$BUNDLE_DIR"
+echo "Debug bundle created: ${BUNDLE_DIR}.tar.gz"
+echo "Contents:"
+ls -la "$BUNDLE_DIR"/
+```
+
+## Bundle Contents Reference
+
+| File | Contents |
+|------|----------|
+| `inspect.txt` | Deployment inspection output |
+| `deployment.json` | Deployment state, target, errors |
+| `function-logs.txt` | Recent function invocation logs |
+| `events.json` | Deployment event timeline |
+| `build-info.json` | Build configuration and output |
+| `routes-functions.json` | Route and function mapping |
+| `env-vars-list.txt` | Environment variable names (no values) |
+| `vercel.json` | Project configuration |
+| `package-summary.json` | Dependencies and versions |
+| `environment.txt` | System info (Node, CLI, OS) |
+| `platform-status.json` | Vercel platform status at time of capture |
+
+## Support Ticket Template
+
+```
+Subject: [Project: my-app] FUNCTION_INVOCATION_TIMEOUT on /api/endpoint
+
+Environment:
+- Plan: Pro
+- Framework: Next.js 14
+- Region: iad1
+- Node.js: 18.x
+
+Issue:
+[Describe the error, when it started, and the user impact]
+
+Steps to Reproduce:
+1. Deploy commit abc123
+2. Send POST to /api/endpoint with body > 1MB
+3. Function times out after 60s
+
+Expected: 200 response within 5s
+Actual: 504 after 60s
+
+Deployment URL: https://my-app-xxx.vercel.app
+Debug bundle: [attached]
 ```
 
 ## 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)
+
+- `vercel-debug-YYYYMMDD-HHMMSS.tar.gz` archive
+- All secrets redacted (env var values never captured)
+- Platform status snapshot included
+- Ready to attach to Vercel support ticket
 
 ## 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
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `vercel inspect` fails | Deployment deleted or token expired | Use API directly with curl |
+| `jq: command not found` | jq not installed | `apt install jq` or `brew install jq` |
+| Empty function logs | Function not invoked or log retention expired | Check Observability tab in dashboard |
+| VERCEL_TOKEN not set | Not authenticated for API calls | Export token or run `vercel login` |
 
 ## Resources
-- [Vercel Support](https://vercel.com/docs/support)
-- [Vercel Status](https://www.vercel-status.com)
+
+- [Vercel Support Portal](https://vercel.com/support)
+- [Vercel Logs CLI](https://vercel.com/docs/cli/logs)
+- [Vercel Inspect CLI](https://vercel.com/docs/cli/inspect)
+- [Vercel Status Page](https://www.vercel-status.com)
 
 ## Next Steps
-For rate limit issues, see `vercel-rate-limits`.
+
+For rate limit issues, see `vercel-rate-limits`.

package/skills/vercel-debug-bundle/references/errors.md

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

package/skills/vercel-debug-bundle/references/examples.md

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

package/skills/vercel-debug-bundle/references/implementation.md

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