devstack 0.1.0

package/vendor/skills/skills/stripe-webhooks/references/verification.md

@@ -0,0 +1,154 @@
+# Stripe Signature Verification
+
+## How It Works
+
+Stripe signs every webhook request using HMAC SHA-256. The signature is included in the `Stripe-Signature` header and contains:
+
+1. A timestamp (`t`) - When Stripe sent the request
+2. A signature (`v1`) - HMAC SHA-256 of `timestamp.payload` using your webhook secret
+
+Example header:
+
+```
+Stripe-Signature: t=1614556800,v1=abc123...,v0=def456...
+```
+
+The `v1` signature is the current version. Ignore `v0` (legacy).
+
+## Implementation
+
+### Using the Stripe SDK (Recommended)
+
+The official Stripe SDK handles signature verification automatically:
+
+**Node.js:**
+
+```javascript
+const stripe = require("stripe")(process.env.STRIPE_SECRET_KEY);
+
+// IMPORTANT: Use raw body, not parsed JSON
+const event = stripe.webhooks.constructEvent(
+  rawBody, // Raw request body as Buffer or string
+  request.headers["stripe-signature"], // Stripe-Signature header
+  process.env.STRIPE_WEBHOOK_SECRET // Your webhook signing secret
+);
+```
+
+**Python:**
+
+```python
+import stripe
+
+event = stripe.Webhook.construct_event(
+    payload=raw_body,                    # Raw request body as bytes
+    sig_header=request.headers['Stripe-Signature'],
+    secret=os.environ['STRIPE_WEBHOOK_SECRET']
+)
+```
+
+### Manual Verification
+
+If you need to verify manually (not recommended):
+
+```javascript
+const crypto = require("crypto");
+
+function verifyStripeSignature(payload, header, secret) {
+  const parts = header.split(",");
+  const timestamp = parts.find(p => p.startsWith("t=")).slice(2);
+  const signature = parts.find(p => p.startsWith("v1=")).slice(3);
+
+  const signedPayload = `${timestamp}.${payload}`;
+  const expectedSignature = crypto.createHmac("sha256", secret).update(signedPayload).digest("hex");
+
+  // Use timing-safe comparison
+  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
+}
+```
+
+## Common Gotchas
+
+### 1. Raw Body Requirement
+
+The most common cause of verification failures is using a parsed JSON body instead of the raw request body.
+
+**Express:**
+
+```javascript
+// WRONG - body is already parsed
+app.use(express.json());
+app.post('/webhooks/stripe', (req, res) => {
+  stripe.webhooks.constructEvent(req.body, ...); // Fails!
+});
+
+// CORRECT - use raw body for this route
+app.post('/webhooks/stripe',
+  express.raw({ type: 'application/json' }),
+  (req, res) => {
+    stripe.webhooks.constructEvent(req.body, ...); // Works!
+  }
+);
+```
+
+### 2. Middleware Ordering
+
+If you use a global JSON parser, configure the webhook route BEFORE the parser:
+
+```javascript
+// Webhook route with raw body (FIRST)
+app.post("/webhooks/stripe", express.raw({ type: "application/json" }), handleWebhook);
+
+// Global JSON parser (AFTER)
+app.use(express.json());
+```
+
+### 3. Timestamp Tolerance
+
+Stripe rejects requests older than 300 seconds (5 minutes) by default. This prevents replay attacks but can cause issues if:
+
+- Your server clock is significantly off
+- You're replaying old events for testing
+
+The SDK accepts a `tolerance` parameter to adjust this:
+
+```javascript
+stripe.webhooks.constructEvent(body, sig, secret, 600); // 10 minute tolerance
+```
+
+### 4. Multiple Signing Secrets
+
+When rotating secrets, Stripe may include signatures from both old and new secrets. The SDK handles this automatically by trying each `v1` signature.
+
+## Debugging Verification Failures
+
+### Error: "No signatures found matching the expected signature"
+
+1. **Check the raw body**: Log `typeof req.body` - it should be `Buffer` or `string`, not `object`
+2. **Check the secret**: Ensure you're using the correct `whsec_...` secret for this endpoint
+3. **Check test vs live**: Test mode endpoints need test mode secrets
+
+### Error: "Timestamp outside tolerance"
+
+1. **Check server time**: Run `date` and compare to actual time
+2. **Increase tolerance**: For testing only, increase the tolerance parameter
+
+### Logging for Debugging
+
+```javascript
+app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
+  console.log('Body type:', typeof req.body);
+  console.log('Body length:', req.body.length);
+  console.log('Signature header:', req.headers['stripe-signature']);
+
+  try {
+    const event = stripe.webhooks.constructEvent(...);
+  } catch (err) {
+    console.error('Verification failed:', err.message);
+    return res.status(400).send(`Webhook Error: ${err.message}`);
+  }
+});
+```
+
+## Full Documentation
+
+For complete signature verification details, see [Stripe's signature verification documentation](https://docs.stripe.com/webhooks/signatures).

package/vendor/skills/skills/sync-provider/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: sync-provider
+description: >
+  Sync provider changes from cloned repositories in the providers/ folder. Use when syncing upstream changes from external provider repositories (claude-code, gemini, codex) while preserving local customizations. Includes multi-step workflow: checking for new commits via GitHub CLI, generating diffs, deep analysis, Pal MCP refactor planning, and applying changes incrementally. Never use for opencode provider (created locally, not cloned).
+---
+
+# Sync Provider
+
+Sync changes from cloned provider repositories while preserving local customizations.
+
+## Overview
+
+Most providers (except `opencode`) are cloned from external repositories and need to be kept in sync with upstream changes. This skill guides the complete workflow from checking for updates to applying changes safely.
+
+## Prerequisites
+
+1. **GitHub CLI (`gh`)**: Must be installed and authenticated
+
+   ```bash
+   gh --version
+   gh auth login
+   gh auth status
+   ```
+
+2. **GitHub Token**: Add `GITHUB_TOKEN` to root `.env` file
+
+   ```bash
+   GITHUB_TOKEN=your_token_here
+   ```
+
+3. **Repository Info**: Each provider's `package.json` contains `repository.url` field (format: `https://github.com/owner/repo-name`)
+
+## Workflow
+
+### Step 1: Identify Provider and Repository
+
+Check the provider's `package.json` for repository URL:
+
+```bash
+cat providers/<provider>/package.json | grep -A 2 repository
+```
+
+Extract owner/repo format: `https://github.com/owner/repo-name` → `owner/repo-name`
+
+### Step 2: Check for New Commits
+
+Use `check-provider-commit.sh` to automatically check for new commits:
+
+```bash
+COMMIT_HASH=$(scripts/check-provider-commit.sh <provider> 2>/dev/null)
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -eq 0 ] && [ -n "$COMMIT_HASH" ]; then
+  echo "Proceeding with sync from commit: $COMMIT_HASH"
+elif [ $EXIT_CODE -eq 0 ]; then
+  echo "Already up to date - no sync needed"
+  exit 0
+else
+  echo "No state file found - need to determine initial commit hash manually"
+  exit 1
+fi
+```
+
+**Script Behavior:**
+
+- **Up to date**: Exits with code 0, shows "Already up to date"
+- **New commits**: Outputs commit hash (last synced), exits with code 0
+- **No state file**: Exits with code 1, shows latest commit (requires manual determination for first sync)
+
+**Important:** Redirect stderr (`2>/dev/null`) when capturing commit hash to avoid mixing informational messages.
+
+### Step 3: Run Git Diff Script
+
+Execute the sync script with appropriate parameters:
+
+```bash
+REPO=$(cat providers/<provider>/package.json | grep -A 2 repository | grep url | cut -d'"' -f4 | sed 's|https://github.com/||')
+
+pnpm exec tsx scripts/git-diff.ts \
+  -r $REPO \
+  -c "$COMMIT_HASH" \
+  -i "src/**/*" \
+  -i "docs/**/*" \
+  -i "examples/**/*" \
+  --state-file-path ./providers/<provider>/diff_last_commit.txt
+```
+
+**Parameters:**
+
+- `-r, --repo`: GitHub repository in `owner/repo` format (required)
+- `-c, --commit`: Commit hash to compare from (required) - use last synced commit from state file
+- `-i, --include`: Glob pattern(s) to filter files (can specify multiple times)
+  - **Always use these three default patterns:**
+    - `src/**/*` - All source files
+    - `docs/**/*` - Documentation files
+    - `examples/**/*` - Example files
+- `--state-file-path`: Path to store last synced commit hash
+
+### Step 4: Deep Research and Analysis
+
+**MANDATORY**: Before applying any changes, perform deep research:
+
+```bash
+# List all generated diff files
+ls -R .diffs/<commit_hash>/
+
+# Review all diffs to understand scope
+find .diffs/<commit_hash>/ -name "*.txt" -exec echo "=== {} ===" \; -exec cat {} \;
+
+# Get list of affected files
+find .diffs/<commit_hash>/ -name "*.txt" | sed "s|\.diffs/<commit_hash>/||" | sed 's|\.txt$||'
+```
+
+**Research Steps:**
+
+1. **Analyze All Diffs**: Review every diff file to understand:
+   - Files being modified, added, or removed
+   - Nature of changes (bug fixes, features, refactoring, breaking changes)
+   - Impact on existing local customizations
+   - Dependencies between changes
+
+2. **Check Local Customizations**: Review current local files to identify:
+   - Custom modifications that might conflict
+   - Local additions that should be preserved
+   - Configuration differences
+
+3. **Review Project Rules**: **MANDATORY STEP** - Check `.cursor/rules` to understand:
+   - Which rules apply to this provider (TypeScript, React, etc.)
+   - Project standards and patterns
+   - Best practices for the technologies involved
+
+### Step 5: Create Refactoring Plan Using Pal MCP
+
+**MANDATORY**: Use Pal MCP refactor tool with Gemini 3.0 Pro to create comprehensive plan.
+
+<critical>
+- **TASK INVALIDATION**: **THE TASK WILL BE INVALIDATED** if you make ANY edits to files before completing ALL steps of the Pal Refactor tool
+- **NO EXCEPTIONS**: You MUST complete the entire Pal Refactor workflow (all steps until `next_step_required: false`) before touching ANY files
+- **VERIFICATION**: Only proceed to Step 7 after receiving confirmation that all Pal Refactor steps are complete
+</critical>
+
+**Refactor Tool Usage:**
+
+1. **Identify Relevant Files**: Collect all files that will be affected:
+   - Files from `.diffs/<commit_hash>/` that have changes
+   - Current local files in `providers/<provider>/` that correspond to changed files
+   - Use **FULL absolute paths** for all files
+
+2. **Run Pal Refactor Analysis**:
+
+   ```typescript
+   // Use mcp_zen_refactor with:
+   // - model: "gemini-3.0-pro" or "anthropic/claude-opus-4.6"
+   // - relevant_files: Array of absolute paths to affected files
+   // - refactor_type: "modernize" or "organization" (as appropriate)
+   // - focus_areas: ["sync-upstream-changes", "preserve-local-customizations"]
+   ```
+
+3. **Complete ALL Steps**: **MANDATORY** - Finalize ALL steps until `next_step_required: false`
+   - Continue calling the refactor tool until you receive confirmation that all steps are complete
+   - Do NOT proceed to any file edits until this is confirmed
+   - **TASK WILL BE INVALIDATED** if you skip this step
+
+4. **Review Refactoring Recommendations**: The tool will provide:
+   - Best approach for applying changes
+   - How to preserve local customizations
+   - Potential conflicts and how to resolve them
+   - Code quality improvements
+   - Architecture considerations
+
+**Refactor Tool Requirements:**
+
+- **Model**: Must use `gemini-3.0-pro` or `anthropic/claude-opus-4.6`
+- **Multi-step**: Complete ALL steps until `next_step_required: false` - **NO EXCEPTIONS**
+- **File Paths**: Use FULL absolute paths (e.g., `/Users/pedronauck/Dev/compozy/compozy-code/providers/claude-code/src/index.ts`)
+- **Focus Areas**: Include context about syncing upstream changes while preserving local customizations
+- **Completion Verification**: Only proceed when the tool confirms all steps are complete
+
+### Step 6: Create Implementation Plan
+
+Based on the Pal refactor analysis, create detailed implementation plan:
+
+1. **Prioritize Changes**: Order by dependencies (apply dependencies first), risk level (low-risk first), impact (critical files first)
+
+2. **Identify Conflicts**: Document files with local customizations that conflict with upstream changes, strategy for resolving each conflict, decisions on what to preserve vs. update
+
+3. **Plan Testing Strategy**: Define which tests to run after each change, how to verify local customizations are preserved, integration points to test
+
+4. **Document Decisions**: Record why certain changes are applied or skipped, how local customizations are preserved, any architectural decisions made
+
+### Step 7: Apply Changes According to Plan
+
+<critical>
+- **VERIFICATION REQUIRED**: Before proceeding, verify that:
+  1. All Pal Refactor steps are complete (`next_step_required: false`)
+  2. You have received the complete refactoring analysis and recommendations
+  3. You have created a detailed implementation plan (Step 6)
+- **TASK INVALIDATION**: **THE TASK WILL BE INVALIDATED** if you start editing files before completing ALL Pal Refactor steps
+- **NO EXCEPTIONS**: Even if you think you understand the changes, you MUST complete the full Pal Refactor workflow first
+</critical>
+
+**Only after completing steps 4-6 AND verifying Pal Refactor completion**, apply changes:
+
+1. **For Modified Files**: Apply changes according to refactor plan, preserving local customizations
+2. **For Added Files**: Add new files following project standards
+3. **For Removed Files**: Evaluate if removal should be applied locally (may need to preserve)
+4. **For Renamed Files**: Handle rename and content changes according to plan
+
+**Best Practices:**
+
+- Apply changes incrementally, following the prioritized plan
+- Test after each significant change
+- Preserve local customizations as identified in the plan
+- Document any deviations from the plan
+
+### Step 8: Update State File
+
+After successfully applying changes, verify state file was updated:
+
+```bash
+cat providers/<provider>/diff_last_commit.txt
+# Should contain the latest commit hash that was synced
+```
+
+## Example Workflow
+
+### Syncing claude-code Provider
+
+```bash
+# 1. Check repository info
+cat providers/claude-code/package.json | grep repository
+
+# 2. Check for new commits
+COMMIT_HASH=$(scripts/check-provider-commit.sh claude-code 2>/dev/null)
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -ne 0 ]; then
+  echo "⚠️  No state file found - need to determine initial commit hash manually"
+  exit 1
+elif [ -z "$COMMIT_HASH" ]; then
+  echo "✅ Already up to date - no sync needed"
+  exit 0
+fi
+
+# 3. Extract repository name
+REPO=$(cat providers/claude-code/package.json | grep -A 2 repository | grep url | cut -d'"' -f4 | sed 's|https://github.com/||')
+
+# 4. Run sync script
+pnpm exec tsx scripts/git-diff.ts \
+  -r $REPO \
+  -c "$COMMIT_HASH" \
+  -i "src/**/*" \
+  -i "docs/**/*" \
+  -i "examples/**/*" \
+  --state-file-path ./providers/claude-code/diff_last_commit.txt
+
+# 5. Deep research and analysis
+find .diffs/$COMMIT_HASH/ -name "*.txt" -exec echo "=== {} ===" \; -exec cat {} \;
+
+# 6. Use Pal MCP refactor tool (complete all steps)
+# 7. Create implementation plan
+# 8. Apply changes according to plan
+# 9. Verify state file updated
+cat providers/claude-code/diff_last_commit.txt
+```
+
+## Available Providers
+
+| Provider      | Repository                               | Notes                                |
+| ------------- | ---------------------------------------- | ------------------------------------ |
+| `claude-code` | `ben-vargas/ai-sdk-provider-claude-code` | Cloned                               |
+| `gemini`      | `ben-vargas/ai-sdk-provider-gemini-cli`  | Cloned                               |
+| `codex`       | `ben-vargas/ai-sdk-provider-codex-cli`   | Cloned                               |
+| `opencode`    | N/A                                      | **Created locally** - no sync needed |
+
+## Critical Requirements
+
+<critical>
+- **YOU MUST** use `gh` CLI to automatically check for new commits before syncing
+- **YOU MUST** verify the repository URL from `package.json` before running the script
+- **YOU MUST** always use the three default include patterns: `src/**/*`, `docs/**/*`, `examples/**/*`
+- **YOU MUST** use the commit hash from the state file (last synced commit) as the `-c` parameter
+- **YOU MUST** perform deep research and analysis of all diffs before creating a plan
+- **YOU MUST** review `.cursor/rules` files to understand which rules apply (MANDATORY STEP)
+- **YOU MUST NEED** to use the Pal MCP refactor tool with Gemini 3.0 Pro to find out the best way to apply changes
+- **YOU MUST** complete ALL steps of the Pal refactor tool - don't stop the process in the middle
+- **YOU MUST** verify Pal Refactor completion (`next_step_required: false`) before proceeding to any file edits
+- **YOU MUST** create a detailed implementation plan based on the refactor analysis before applying changes
+- **YOU MUST** use FULL absolute paths when using Pal MCP tools (never relative paths)
+- **YOU MUST** preserve local customizations when applying upstream changes
+- **YOU MUST** test the provider after applying changes (`pnpm test` in provider directory)
+- **YOU MUST** run lint and typecheck after applying changes (`pnpm run lint && pnpm run typecheck`)
+- **YOU MUST** update the state file path to match the provider directory structure
+- **NEVER** sync `opencode` provider (it's created locally, not cloned)
+- **NEVER** apply changes directly without deep research and planning first
+- **NEVER** start editing files before completing ALL Pal Refactor steps
+- **NEVER** use workarounds - always prefer good and well-designed solutions
+- **ALWAYS** use the exact repository format: `owner/repo-name` (no `https://github.com/` prefix)
+- **ALWAYS** check `.diffs/<commit_hash>/` folder exists and contains expected files before planning
+- **ALWAYS** verify that `gh` CLI is authenticated (`gh auth status`)
+- **ALWAYS** follow greenfield approach - don't care about backwards compatibility, prioritize quality
+- **ALWAYS** double check which rules from `.cursor/rules` apply for the task before starting (MANDATORY STEP)
+</critical>
+
+## Troubleshooting
+
+### No files matching glob pattern
+
+- Check if the commit hash is correct
+- Verify the repository name format
+- Use broader patterns like `**/*` to see all changes
+
+### State file not found
+
+- **First sync**: Use the initial commit hash from when you cloned
+- **Subsequent syncs**: The script creates the state file automatically
+
+### Binary files detected
+
+Binary files are noted in `.diffs/<commit_hash>/<file-path>.txt` but not diffed. Handle these manually:
+
+- Images: Review in GitHub or download directly
+- Other binaries: Decide if update is needed
+
+### GitHub API rate limits
+
+- Wait before retrying
+- Use a GitHub token with higher rate limits
+- Consider syncing in smaller batches
+
+## After Syncing
+
+- **MUST TEST**: Run tests in the provider directory:
+
+  ```bash
+  cd providers/<provider>
+  pnpm test
+  pnpm run lint
+  pnpm run typecheck
+  ```
+
+- **MUST VERIFY**: Ensure all changes are correctly applied and no local customizations are lost
+
+- **MUST DOCUMENT**: Record any decisions made during the sync process, especially:
+  - Conflicts resolved
+  - Local customizations preserved
+  - Deviations from upstream changes
+  - Architectural decisions

package/vendor/skills/skills/systematic-debugging/CREATION-LOG.md

@@ -0,0 +1,133 @@
+# Creation Log: Systematic Debugging Skill
+
+Reference example of extracting, structuring, and bulletproofing a critical skill.
+
+## Source Material
+
+Extracted debugging framework from `/Users/jesse/.claude/CLAUDE.md`:
+
+- 4-phase systematic process (Investigation → Pattern Analysis → Hypothesis → Implementation)
+- Core mandate: ALWAYS find root cause, NEVER fix symptoms
+- Rules designed to resist time pressure and rationalization
+
+## Extraction Decisions
+
+**What to include:**
+
+- Complete 4-phase framework with all rules
+- Anti-shortcuts ("NEVER fix symptom", "STOP and re-analyze")
+- Pressure-resistant language ("even if faster", "even if I seem in a hurry")
+- Concrete steps for each phase
+
+**What to leave out:**
+
+- Project-specific context
+- Repetitive variations of same rule
+- Narrative explanations (condensed to principles)
+
+## Structure Following skill-creation/SKILL.md
+
+1. **Rich when_to_use** - Included symptoms and anti-patterns
+2. **Type: technique** - Concrete process with steps
+3. **Keywords** - "root cause", "symptom", "workaround", "debugging", "investigation"
+4. **Flowchart** - Decision point for "fix failed" → re-analyze vs add more fixes
+5. **Phase-by-phase breakdown** - Scannable checklist format
+6. **Anti-patterns section** - What NOT to do (critical for this skill)
+
+## Bulletproofing Elements
+
+Framework designed to resist rationalization under pressure:
+
+### Language Choices
+
+- "ALWAYS" / "NEVER" (not "should" / "try to")
+- "even if faster" / "even if I seem in a hurry"
+- "STOP and re-analyze" (explicit pause)
+- "Don't skip past" (catches the actual behavior)
+
+### Structural Defenses
+
+- **Phase 1 required** - Can't skip to implementation
+- **Single hypothesis rule** - Forces thinking, prevents shotgun fixes
+- **Explicit failure mode** - "IF your first fix doesn't work" with mandatory action
+- **Anti-patterns section** - Shows exactly what shortcuts look like
+
+### Redundancy
+
+- Root cause mandate in overview + when_to_use + Phase 1 + implementation rules
+- "NEVER fix symptom" appears 4 times in different contexts
+- Each phase has explicit "don't skip" guidance
+
+## Testing Approach
+
+Created 4 validation tests following skills/meta/testing-skills-with-subagents:
+
+### Test 1: Academic Context (No Pressure)
+
+- Simple bug, no time pressure
+- **Result:** Perfect compliance, complete investigation
+
+### Test 2: Time Pressure + Obvious Quick Fix
+
+- User "in a hurry", symptom fix looks easy
+- **Result:** Resisted shortcut, followed full process, found real root cause
+
+### Test 3: Complex System + Uncertainty
+
+- Multi-layer failure, unclear if can find root cause
+- **Result:** Systematic investigation, traced through all layers, found source
+
+### Test 4: Failed First Fix
+
+- Hypothesis doesn't work, temptation to add more fixes
+- **Result:** Stopped, re-analyzed, formed new hypothesis (no shotgun)
+
+**All tests passed.** No rationalizations found.
+
+## Iterations
+
+### Initial Version
+
+- Complete 4-phase framework
+- Anti-patterns section
+- Flowchart for "fix failed" decision
+
+### Enhancement 1: TDD Reference
+
+- Added link to skills/testing/test-driven-development
+- Note explaining TDD's "simplest code" ≠ debugging's "root cause"
+- Prevents confusion between methodologies
+
+## Final Outcome
+
+Bulletproof skill that:
+
+- ✅ Clearly mandates root cause investigation
+- ✅ Resists time pressure rationalization
+- ✅ Provides concrete steps for each phase
+- ✅ Shows anti-patterns explicitly
+- ✅ Tested under multiple pressure scenarios
+- ✅ Clarifies relationship to TDD
+- ✅ Ready for use
+
+## Key Insight
+
+**Most important bulletproofing:** Anti-patterns section showing exact shortcuts that feel justified in the moment. When Claude thinks "I'll just add this one quick fix", seeing that exact pattern listed as wrong creates cognitive friction.
+
+## Usage Example
+
+When encountering a bug:
+
+1. Load skill: skills/debugging/systematic-debugging
+2. Read overview (10 sec) - reminded of mandate
+3. Follow Phase 1 checklist - forced investigation
+4. If tempted to skip - see anti-pattern, stop
+5. Complete all phases - root cause found
+
+**Time investment:** 5-10 minutes
+**Time saved:** Hours of symptom-whack-a-mole
+
+---
+
+_Created: 2025-10-03_
+_Purpose: Reference example for skill extraction and bulletproofing_