@intentsolutionsio/vercel-pack 1.0.0 → 1.0.3

package/skills/vercel-architecture-variants/references/variant-a-monolith-(simple).md

@@ -0,0 +1,44 @@
+# Variant A: Monolith (Simple)
+
+## Variant A: Monolith (Simple)
+
+**Best for:** MVPs, small teams, < 10K daily active users
+
+```
+my-app/
+├── src/
+│   ├── vercel/
+│   │   ├── client.ts          # Singleton client
+│   │   ├── types.ts           # Types
+│   │   └── middleware.ts      # Express middleware
+│   ├── routes/
+│   │   └── api/
+│   │       └── vercel.ts    # API routes
+│   └── index.ts
+├── tests/
+│   └── vercel.test.ts
+└── package.json
+```
+
+### Key Characteristics
+
+- Single deployment unit
+- Synchronous Vercel calls in request path
+- In-memory caching
+- Simple error handling
+
+### Code Pattern
+
+```typescript
+// Direct integration in route handler
+app.post('/api/create', async (req, res) => {
+  try {
+    const result = await vercelClient.create(req.body);
+    res.json(result);
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+```
+
+---

package/skills/vercel-architecture-variants/references/variant-b-service-layer-(moderate).md

@@ -0,0 +1,72 @@
+# Variant B: Service Layer (Moderate)
+
+## Variant B: Service Layer (Moderate)
+
+**Best for:** Growing startups, 10K-100K DAU, multiple integrations
+
+```
+my-app/
+├── src/
+│   ├── services/
+│   │   ├── vercel/
+│   │   │   ├── client.ts      # Client wrapper
+│   │   │   ├── service.ts     # Business logic
+│   │   │   ├── repository.ts  # Data access
+│   │   │   └── types.ts
+│   │   └── index.ts           # Service exports
+│   ├── controllers/
+│   │   └── vercel.ts
+│   ├── routes/
+│   ├── middleware/
+│   ├── queue/
+│   │   └── vercel-processor.ts  # Async processing
+│   └── index.ts
+├── config/
+│   └── vercel/
+└── package.json
+```
+
+### Key Characteristics
+
+- Separation of concerns
+- Background job processing
+- Redis caching
+- Circuit breaker pattern
+- Structured error handling
+
+### Code Pattern
+
+```typescript
+// Service layer abstraction
+class VercelService {
+  constructor(
+    private client: VercelClient,
+    private cache: CacheService,
+    private queue: QueueService
+  ) {}
+
+  async createResource(data: CreateInput): Promise<Resource> {
+    // Business logic before API call
+    const validated = this.validate(data);
+
+    // Check cache
+    const cached = await this.cache.get(cacheKey);
+    if (cached) return cached;
+
+    // API call with retry
+    const result = await this.withRetry(() =>
+      this.client.create(validated)
+    );
+
+    // Cache result
+    await this.cache.set(cacheKey, result, 300);
+
+    // Async follow-up
+    await this.queue.enqueue('vercel.post-create', result);
+
+    return result;
+  }
+}
+```
+
+---

package/skills/vercel-architecture-variants/references/variant-c-microservice-(complex).md

@@ -0,0 +1,81 @@
+# Variant C: Microservice (Complex)
+
+## Variant C: Microservice (Complex)
+
+**Best for:** Enterprise, 100K+ DAU, strict SLAs
+
+```
+vercel-service/              # Dedicated microservice
+├── src/
+│   ├── api/
+│   │   ├── grpc/
+│   │   │   └── vercel.proto
+│   │   └── rest/
+│   │       └── routes.ts
+│   ├── domain/
+│   │   ├── entities/
+│   │   ├── events/
+│   │   └── services/
+│   ├── infrastructure/
+│   │   ├── vercel/
+│   │   │   ├── client.ts
+│   │   │   ├── mapper.ts
+│   │   │   └── circuit-breaker.ts
+│   │   ├── cache/
+│   │   ├── queue/
+│   │   └── database/
+│   └── index.ts
+├── config/
+├── k8s/
+│   ├── deployment.yaml
+│   ├── service.yaml
+│   └── hpa.yaml
+└── package.json
+
+other-services/
+├── order-service/       # Calls vercel-service
+├── payment-service/
+└── notification-service/
+```
+
+### Key Characteristics
+
+- Dedicated Vercel microservice
+- gRPC for internal communication
+- Event-driven architecture
+- Database per service
+- Kubernetes autoscaling
+- Distributed tracing
+- Circuit breaker per service
+
+### Code Pattern
+
+```typescript
+// Event-driven with domain isolation
+class VercelAggregate {
+  private events: DomainEvent[] = [];
+
+  process(command: VercelCommand): void {
+    // Domain logic
+    const result = this.execute(command);
+
+    // Emit domain event
+    this.events.push(new VercelProcessedEvent(result));
+  }
+
+  getUncommittedEvents(): DomainEvent[] {
+    return [...this.events];
+  }
+}
+
+// Event handler
+@EventHandler(VercelProcessedEvent)
+class VercelEventHandler {
+  async handle(event: VercelProcessedEvent): Promise<void> {
+    // Saga orchestration
+    await this.sagaOrchestrator.continue(event);
+  }
+}
+```
+
+---

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

@@ -1,124 +1,234 @@
 ---
 name: vercel-ci-integration
-description: |
-  Configure Vercel CI/CD integration with GitHub Actions and testing.
-  Use when setting up automated testing, configuring CI pipelines,
-  or integrating Vercel tests into your build process.
+description: 'Configure Vercel CI/CD with GitHub Actions, preview deployments, and
+  automated testing.
+
+  Use when setting up automated deployments, configuring preview bots,
+
+  or integrating Vercel into your CI pipeline.
+
   Trigger with phrases like "vercel CI", "vercel GitHub Actions",
-  "vercel automated tests", "CI vercel".
-allowed-tools: Read, Write, Edit, Bash(gh:*)
+
+  "vercel automated deploy", "CI vercel", "vercel pipeline".
+
+  '
+allowed-tools: Read, Write, Edit, Bash(gh:*), Bash(vercel:*)
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- ci-cd
+- github-actions
+- automation
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Vercel CI Integration
 
 ## Overview
-Set up CI/CD pipelines for Vercel integrations with automated testing.
+
+Set up automated Vercel deployments in GitHub Actions with preview deployments on PRs, production deploys on merge to main, and optional test gating. Covers both Vercel's built-in Git integration and custom CI pipelines using the Vercel CLI.
 
 ## Prerequisites
+
 - GitHub repository with Actions enabled
-- Vercel test API key
-- npm/pnpm project configured
+- Vercel project linked to the repo
+- `VERCEL_TOKEN` stored as GitHub Secret
+- `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` from `.vercel/project.json`
 
 ## Instructions
 
-### Step 1: Create GitHub Actions Workflow
-Create `.github/workflows/vercel-integration.yml`:
+### Step 1: Store CI Secrets in GitHub
 
-```yaml
-name: Vercel Integration Tests
+```bash
+# Get project and org IDs
+cat .vercel/project.json
+# {"orgId":"team_xxx","projectId":"prj_xxx"}
+
+# Add secrets to GitHub repo
+gh secret set VERCEL_TOKEN --body "your-vercel-token"
+gh secret set VERCEL_ORG_ID --body "team_xxx"
+gh secret set VERCEL_PROJECT_ID --body "prj_xxx"
+```
+
+### Step 2: GitHub Actions — Preview on PR
 
+```yaml
+# .github/workflows/vercel-preview.yml
+name: Vercel Preview Deployment
 on:
-  push:
-    branches: [main]
   pull_request:
     branches: [main]
 
-env:
-  VERCEL_API_KEY: ${{ secrets.VERCEL_API_KEY }}
-
 jobs:
-  test:
+  deploy-preview:
     runs-on: ubuntu-latest
-    env:
-      VERCEL_API_KEY: ${{ secrets.VERCEL_API_KEY }}
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+
+      - name: Install Vercel CLI
+        run: npm install -g vercel@latest
+
+      - name: Pull Vercel Environment
+        run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
+        env:
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+
+      - name: Build Project
+        run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
+        env:
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+
+      - name: Deploy Preview
+        id: deploy
+        run: |
+          url=$(vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }})
+          echo "preview_url=$url" >> $GITHUB_OUTPUT
+        env:
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+
+      - name: Comment PR with Preview URL
+        uses: actions/github-script@v7
         with:
-          node-version: '20'
-          cache: 'npm'
-      - run: npm ci
-      - run: npm test -- --coverage
-      - run: npm run test:integration
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `Preview deployed: ${{ steps.deploy.outputs.preview_url }}`
+            })
 ```
 
-### Step 2: Configure Secrets
-```bash
-gh secret set VERCEL_API_KEY --body "sk_test_***"
-```
+### Step 3: GitHub Actions — Production on Merge
 
-### Step 3: Add Integration Tests
-```typescript
-describe('Vercel Integration', () => {
-  it.skipIf(!process.env.VERCEL_API_KEY)('should connect', async () => {
-    const client = getVercelClient();
-    const result = await client.healthCheck();
-    expect(result.status).toBe('ok');
-  });
-});
-```
+```yaml
+# .github/workflows/vercel-production.yml
+name: Vercel Production Deployment
+on:
+  push:
+    branches: [main]
 
-## Output
-- Automated test pipeline
-- PR checks configured
-- Coverage reports uploaded
-- Release workflow ready
+jobs:
+  deploy-production:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
 
-## Error Handling
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| Secret not found | Missing configuration | Add secret via `gh secret set` |
-| Tests timeout | Network issues | Increase timeout or mock |
-| Auth failures | Invalid key | Check secret value |
+      - name: Install Vercel CLI
+        run: npm install -g vercel@latest
+
+      - name: Pull Vercel Environment
+        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
+        env:
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+
+      - name: Build Project
+        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
+        env:
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+
+      - name: Deploy Production
+        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
+        env:
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+```
 
-## Examples
+### Step 4: Test Gating — Run Tests Before Deploy
 
-### Release Workflow
 ```yaml
+# .github/workflows/vercel-gated.yml
+name: Gated Vercel Deploy
 on:
   push:
-    tags: ['v*']
+    branches: [main]
 
 jobs:
-  release:
+  test:
     runs-on: ubuntu-latest
-    env:
-      VERCEL_API_KEY: ${{ secrets.VERCEL_API_KEY_PROD }}
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
+        with: { node-version: 20 }
       - run: npm ci
-      - name: Verify Vercel production readiness
-        run: npm run test:integration
-      - run: npm run build
-      - run: npm publish
+      - run: npm test
+      - run: npm run lint
+      - run: npx tsc --noEmit
+
+  deploy:
+    needs: test  # Only deploy if tests pass
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm install -g vercel@latest
+      - run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
+        env:
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+      - run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
+        env:
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+      - run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}
+        env:
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
 ```
 
-### Branch Protection
-```yaml
-required_status_checks:
-  - "test"
-  - "vercel-integration"
+### Step 5: Skip Builds for Non-Code Changes
+
+```json
+// vercel.json — skip build when only docs change
+{
+  "ignoreCommand": "git diff HEAD^ HEAD --quiet -- . ':!docs' ':!*.md' ':!.github'"
+}
 ```
 
+Or in the dashboard: **Settings > Git > Ignored Build Step**
+
+### Step 6: Vercel's Built-In Git Integration (Alternative)
+
+If you prefer Vercel's automatic deployments over custom CI:
+
+1. Connect your GitHub repo in the Vercel dashboard
+2. Vercel auto-deploys: preview on every push, production on merge to main
+3. Configure in **Settings > Git**:
+   - Production branch: `main`
+   - Preview branches: all other branches
+   - Auto-assign custom domains to production
+
+This approach requires zero CI configuration but gives less control over test gating.
+
+## Output
+
+- Preview deployments on every PR with URL comment
+- Production deployments on merge to main (after tests pass)
+- Test gating preventing broken code from reaching production
+- Build skip rules for documentation-only changes
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Error: VERCEL_TOKEN is not set` | Secret not configured | Add `VERCEL_TOKEN` as GitHub repo secret |
+| `Error: Could not find project` | Wrong ORG_ID or PROJECT_ID | Check `.vercel/project.json` values |
+| `vercel pull` fails | Token lacks project access | Regenerate token with correct scope |
+| Preview not commenting on PR | Missing `actions/github-script` | Add the comment step with correct permissions |
+| Build cache not working | CI runs on fresh runner | Use `actions/cache` for `node_modules` and `.vercel/output` |
+
 ## Resources
-- [GitHub Actions Documentation](https://docs.github.com/en/actions)
-- [Vercel CI Guide](https://vercel.com/docs/ci)
+
+- [Vercel CLI in CI](https://vercel.com/docs/cli/deploying-from-cli)
+- [GitHub Actions](https://docs.github.com/en/actions)
+- [Vercel Git Integration](https://vercel.com/docs/deployments/git)
+- [Ignored Build Step](https://vercel.com/docs/project-configuration#ignorecommand)
 
 ## Next Steps
-For deployment patterns, see `vercel-deploy-integration`.
+
+For deployment orchestration, see `vercel-deploy-integration`.

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

@@ -0,0 +1,10 @@
+# Error Handling Reference
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Secret not found | Missing configuration | Add secret via `gh secret set` |
+| Tests timeout | Network issues | Increase timeout or mock |
+| Auth failures | Invalid key | Check secret value |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

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

@@ -0,0 +1,36 @@
+## Examples
+
+### Release Workflow
+
+```yaml
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      VERCEL_API_KEY: ${{ secrets.VERCEL_API_KEY_PROD }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - name: Verify Vercel production readiness
+        run: npm run test:integration
+      - run: npm run build
+      - run: npm publish
+```
+
+### Branch Protection
+
+```yaml
+required_status_checks:
+  - "test"
+  - "vercel-integration"
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-ci-integration/references/implementation.md

@@ -0,0 +1,54 @@
+## Implementation Guide
+
+### Step 1: Create GitHub Actions Workflow
+
+Create `.github/workflows/vercel-integration.yml`:
+
+```yaml
+name: Vercel Integration Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  VERCEL_API_KEY: ${{ secrets.VERCEL_API_KEY }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      VERCEL_API_KEY: ${{ secrets.VERCEL_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm test -- --coverage
+      - run: npm run test:integration
+```
+
+### Step 2: Configure Secrets
+
+```bash
+gh secret set VERCEL_API_KEY --body "sk_test_***"
+```
+
+### Step 3: Add Integration Tests
+
+```typescript
+describe('Vercel Integration', () => {
+  it.skipIf(!process.env.VERCEL_API_KEY)('should connect', async () => {
+    const client = getVercelClient();
+    const result = await client.healthCheck();
+    expect(result.status).toBe('ok');
+  });
+});
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*