proagents 1.0.0

package/proagents/webhooks/endpoints.md

@@ -0,0 +1,298 @@
+# Webhook Endpoint Configuration
+
+Configure and manage webhook endpoints.
+
+---
+
+## Basic Configuration
+
+### Single Endpoint
+
+```yaml
+webhooks:
+  endpoints:
+    - name: "my-webhook"
+      url: "https://api.example.com/webhooks"
+      events: ["feature.completed", "deploy.success"]
+```
+
+### Multiple Endpoints
+
+```yaml
+webhooks:
+  endpoints:
+    # Slack for notifications
+    - name: "slack-dev"
+      url: "https://hooks.slack.com/services/xxx"
+      events: ["feature.*", "test.failed"]
+
+    # Discord for team updates
+    - name: "discord-team"
+      url: "https://discord.com/api/webhooks/xxx"
+      events: ["deploy.*"]
+
+    # Custom API for all events
+    - name: "analytics-api"
+      url: "https://analytics.company.com/events"
+      events: ["*"]
+```
+
+---
+
+## Authentication
+
+### Bearer Token
+
+```yaml
+webhooks:
+  endpoints:
+    - name: "secure-api"
+      url: "https://api.example.com/webhooks"
+      auth:
+        type: "bearer"
+        token_env: "WEBHOOK_API_TOKEN"
+```
+
+### Basic Auth
+
+```yaml
+webhooks:
+  endpoints:
+    - name: "basic-auth-api"
+      url: "https://api.example.com/webhooks"
+      auth:
+        type: "basic"
+        username_env: "WEBHOOK_USER"
+        password_env: "WEBHOOK_PASS"
+```
+
+### Custom Headers
+
+```yaml
+webhooks:
+  endpoints:
+    - name: "custom-header-api"
+      url: "https://api.example.com/webhooks"
+      headers:
+        X-API-Key: "${WEBHOOK_API_KEY}"
+        X-Custom-Header: "proagents"
+```
+
+### HMAC Signature
+
+```yaml
+webhooks:
+  endpoints:
+    - name: "signed-webhook"
+      url: "https://api.example.com/webhooks"
+      signature:
+        enabled: true
+        algorithm: "sha256"
+        secret_env: "WEBHOOK_SECRET"
+        header: "X-ProAgents-Signature"
+```
+
+---
+
+## Event Filtering
+
+### Wildcard Patterns
+
+```yaml
+webhooks:
+  endpoints:
+    - name: "all-events"
+      events: ["*"]                    # All events
+
+    - name: "feature-events"
+      events: ["feature.*"]            # All feature events
+
+    - name: "specific-events"
+      events:
+        - "feature.completed"
+        - "deploy.success"
+        - "test.failed"
+```
+
+### Conditional Filtering
+
+```yaml
+webhooks:
+  endpoints:
+    - name: "production-only"
+      url: "https://api.example.com/webhooks"
+      events: ["deploy.*"]
+      filters:
+        environment: "production"
+
+    - name: "critical-only"
+      url: "https://alerts.example.com/webhooks"
+      events: ["*"]
+      filters:
+        severity: ["critical", "high"]
+```
+
+### Branch Filtering
+
+```yaml
+webhooks:
+  endpoints:
+    - name: "main-branch-only"
+      url: "https://api.example.com/webhooks"
+      events: ["deploy.*", "pr.merged"]
+      filters:
+        branches:
+          - "main"
+          - "release/*"
+```
+
+---
+
+## Request Configuration
+
+### Timeout & Retries
+
+```yaml
+webhooks:
+  endpoints:
+    - name: "reliable-webhook"
+      url: "https://api.example.com/webhooks"
+      events: ["*"]
+      request:
+        timeout: 30000          # 30 seconds
+        retries: 3
+        retry_delay: 5000       # 5 seconds between retries
+        retry_backoff: "exponential"
+```
+
+### Custom Payload
+
+```yaml
+webhooks:
+  endpoints:
+    - name: "custom-format"
+      url: "https://api.example.com/webhooks"
+      events: ["feature.completed"]
+      transform:
+        template: |
+          {
+            "type": "proagents_event",
+            "event_name": "{{event}}",
+            "feature": "{{data.feature_name}}",
+            "timestamp": "{{timestamp}}"
+          }
+```
+
+### Batch Delivery
+
+```yaml
+webhooks:
+  endpoints:
+    - name: "batched-webhook"
+      url: "https://api.example.com/webhooks/batch"
+      events: ["*"]
+      batching:
+        enabled: true
+        max_size: 100           # Max events per batch
+        max_wait: 10000         # Max wait time (ms)
+```
+
+---
+
+## Environment-Specific
+
+### Per-Environment Webhooks
+
+```yaml
+webhooks:
+  environments:
+    development:
+      endpoints:
+        - name: "dev-slack"
+          url: "${DEV_SLACK_WEBHOOK}"
+          events: ["*"]
+
+    staging:
+      endpoints:
+        - name: "staging-slack"
+          url: "${STAGING_SLACK_WEBHOOK}"
+          events: ["deploy.*", "test.failed"]
+
+    production:
+      endpoints:
+        - name: "prod-slack"
+          url: "${PROD_SLACK_WEBHOOK}"
+          events: ["deploy.*", "security.*"]
+
+        - name: "pagerduty"
+          url: "https://events.pagerduty.com/v2/enqueue"
+          events: ["deploy.failed", "security.vulnerability.critical"]
+```
+
+---
+
+## Endpoint Management
+
+### Enable/Disable
+
+```yaml
+webhooks:
+  endpoints:
+    - name: "maintenance-mode"
+      url: "https://api.example.com/webhooks"
+      enabled: false              # Temporarily disabled
+      events: ["*"]
+```
+
+### Maintenance Windows
+
+```yaml
+webhooks:
+  endpoints:
+    - name: "business-hours-only"
+      url: "https://api.example.com/webhooks"
+      events: ["*"]
+      schedule:
+        enabled_hours: "09:00-18:00"
+        enabled_days: ["mon", "tue", "wed", "thu", "fri"]
+        timezone: "America/New_York"
+```
+
+---
+
+## Commands
+
+```bash
+# List all endpoints
+proagents webhooks list
+
+# Add endpoint
+proagents webhooks add \
+  --name "new-webhook" \
+  --url "https://api.example.com/webhooks" \
+  --events "feature.*,deploy.*"
+
+# Update endpoint
+proagents webhooks update new-webhook --events "*"
+
+# Remove endpoint
+proagents webhooks remove new-webhook
+
+# Enable/disable
+proagents webhooks enable new-webhook
+proagents webhooks disable new-webhook
+
+# Test endpoint
+proagents webhooks test new-webhook --event feature.completed
+```
+
+---
+
+## Best Practices
+
+1. **Use Environment Variables**: Never hardcode URLs or secrets
+2. **Filter Events**: Only subscribe to events you need
+3. **Set Timeouts**: Prevent hanging connections
+4. **Enable Retries**: Handle transient failures
+5. **Use Signatures**: Verify webhook authenticity
+6. **Monitor Health**: Track delivery success rates

package/proagents/webhooks/events.md

@@ -0,0 +1,316 @@
+# Webhook Events Reference
+
+Complete reference of all webhook events.
+
+---
+
+## Event Categories
+
+### Feature Events
+
+| Event | Description | Trigger |
+|-------|-------------|---------|
+| `feature.started` | New feature started | `/feature start` |
+| `feature.paused` | Feature paused | `/feature pause` |
+| `feature.resumed` | Feature resumed | `/feature resume` |
+| `feature.completed` | Feature completed | All phases done |
+| `feature.abandoned` | Feature abandoned | Manual cancellation |
+
+**Example Payload:**
+```json
+{
+  "event": "feature.completed",
+  "timestamp": "2024-01-15T14:30:00Z",
+  "data": {
+    "feature_id": "feat-123",
+    "feature_name": "User Authentication",
+    "branch": "feature/user-auth",
+    "duration_minutes": 240,
+    "phases_completed": 9,
+    "files_changed": 15,
+    "lines_added": 450,
+    "lines_removed": 20
+  }
+}
+```
+
+---
+
+### Phase Events
+
+| Event | Description | Trigger |
+|-------|-------------|---------|
+| `phase.started` | Phase began | Phase transition |
+| `phase.completed` | Phase finished | Phase completion |
+| `phase.skipped` | Phase skipped | Manual skip or config |
+| `phase.failed` | Phase failed | Error during phase |
+
+**Example Payload:**
+```json
+{
+  "event": "phase.completed",
+  "timestamp": "2024-01-15T14:30:00Z",
+  "data": {
+    "feature_id": "feat-123",
+    "phase": "testing",
+    "phase_number": 6,
+    "duration_minutes": 45,
+    "status": "success",
+    "details": {
+      "tests_run": 150,
+      "tests_passed": 148,
+      "tests_failed": 2,
+      "coverage": 85.5
+    }
+  }
+}
+```
+
+---
+
+### Analysis Events
+
+| Event | Description | Trigger |
+|-------|-------------|---------|
+| `analysis.started` | Codebase analysis began | Phase 1 start |
+| `analysis.completed` | Analysis finished | Phase 1 complete |
+| `analysis.cached` | Using cached analysis | Cache hit |
+| `analysis.invalidated` | Cache invalidated | Code changes |
+
+**Example Payload:**
+```json
+{
+  "event": "analysis.completed",
+  "timestamp": "2024-01-15T14:30:00Z",
+  "data": {
+    "feature_id": "feat-123",
+    "duration_seconds": 45,
+    "files_analyzed": 234,
+    "patterns_detected": 18,
+    "dependencies_mapped": 45,
+    "cached": false
+  }
+}
+```
+
+---
+
+### Testing Events
+
+| Event | Description | Trigger |
+|-------|-------------|---------|
+| `test.started` | Test suite began | Test phase start |
+| `test.passed` | All tests passed | Test success |
+| `test.failed` | Tests failed | Test failures |
+| `test.skipped` | Tests skipped | Manual skip |
+| `coverage.changed` | Coverage changed | Coverage delta |
+| `coverage.below_threshold` | Coverage too low | Below minimum |
+
+**Example Payload:**
+```json
+{
+  "event": "test.failed",
+  "timestamp": "2024-01-15T14:30:00Z",
+  "data": {
+    "feature_id": "feat-123",
+    "test_type": "unit",
+    "total_tests": 150,
+    "passed": 145,
+    "failed": 5,
+    "skipped": 0,
+    "coverage": 82.5,
+    "failures": [
+      {
+        "test": "UserService.login.should_validate_email",
+        "file": "src/services/__tests__/UserService.test.ts",
+        "line": 45,
+        "error": "Expected validation error, received success"
+      }
+    ]
+  }
+}
+```
+
+---
+
+### Review Events
+
+| Event | Description | Trigger |
+|-------|-------------|---------|
+| `review.requested` | Review requested | PR created |
+| `review.approved` | Review approved | Reviewer approval |
+| `review.rejected` | Changes requested | Reviewer rejection |
+| `review.comment` | Review comment added | Comment posted |
+
+**Example Payload:**
+```json
+{
+  "event": "review.approved",
+  "timestamp": "2024-01-15T14:30:00Z",
+  "data": {
+    "feature_id": "feat-123",
+    "pr_number": 456,
+    "reviewer": "john.doe",
+    "review_type": "code_review",
+    "comments_count": 3,
+    "approved_at": "2024-01-15T14:30:00Z"
+  }
+}
+```
+
+---
+
+### Deployment Events
+
+| Event | Description | Trigger |
+|-------|-------------|---------|
+| `deploy.started` | Deployment began | Deploy start |
+| `deploy.success` | Deployment successful | Deploy complete |
+| `deploy.failed` | Deployment failed | Deploy error |
+| `deploy.cancelled` | Deployment cancelled | Manual cancel |
+| `rollback.triggered` | Rollback initiated | Auto or manual |
+| `rollback.completed` | Rollback finished | Rollback done |
+
+**Example Payload:**
+```json
+{
+  "event": "deploy.success",
+  "timestamp": "2024-01-15T14:30:00Z",
+  "data": {
+    "feature_id": "feat-123",
+    "environment": "production",
+    "version": "1.5.0",
+    "commit": "abc123def",
+    "duration_seconds": 180,
+    "artifacts": [
+      "web-app:1.5.0",
+      "api-server:1.5.0"
+    ]
+  }
+}
+```
+
+---
+
+### Git Events
+
+| Event | Description | Trigger |
+|-------|-------------|---------|
+| `branch.created` | Branch created | New branch |
+| `branch.deleted` | Branch deleted | Branch cleanup |
+| `commit.pushed` | Commits pushed | Git push |
+| `pr.created` | PR created | New PR |
+| `pr.updated` | PR updated | PR changes |
+| `pr.merged` | PR merged | Merge complete |
+| `pr.closed` | PR closed | PR closed without merge |
+
+**Example Payload:**
+```json
+{
+  "event": "pr.created",
+  "timestamp": "2024-01-15T14:30:00Z",
+  "data": {
+    "feature_id": "feat-123",
+    "pr_number": 456,
+    "title": "feat(auth): add user authentication",
+    "branch": "feature/user-auth",
+    "base_branch": "develop",
+    "author": "jane.smith",
+    "url": "https://github.com/org/repo/pull/456",
+    "files_changed": 15,
+    "additions": 450,
+    "deletions": 20
+  }
+}
+```
+
+---
+
+### Security Events
+
+| Event | Description | Trigger |
+|-------|-------------|---------|
+| `security.scan.started` | Security scan began | Scan start |
+| `security.scan.completed` | Security scan done | Scan complete |
+| `vulnerability.found` | Vulnerability detected | New vulnerability |
+| `vulnerability.fixed` | Vulnerability fixed | Fix applied |
+| `dependency.vulnerable` | Vulnerable dependency | Dependency scan |
+
+**Example Payload:**
+```json
+{
+  "event": "vulnerability.found",
+  "timestamp": "2024-01-15T14:30:00Z",
+  "data": {
+    "feature_id": "feat-123",
+    "severity": "high",
+    "type": "dependency",
+    "package": "lodash",
+    "version": "4.17.20",
+    "cve": "CVE-2021-23337",
+    "description": "Command injection vulnerability",
+    "fix_available": true,
+    "fixed_version": "4.17.21"
+  }
+}
+```
+
+---
+
+### Approval Events
+
+| Event | Description | Trigger |
+|-------|-------------|---------|
+| `approval.requested` | Approval requested | Approval needed |
+| `approval.granted` | Approval granted | Approver approved |
+| `approval.denied` | Approval denied | Approver rejected |
+| `approval.expired` | Approval expired | Timeout |
+| `approval.bypassed` | Emergency bypass | Emergency procedure |
+
+**Example Payload:**
+```json
+{
+  "event": "approval.granted",
+  "timestamp": "2024-01-15T14:30:00Z",
+  "data": {
+    "feature_id": "feat-123",
+    "approval_type": "deployment",
+    "environment": "production",
+    "approver": "tech-lead",
+    "approver_email": "lead@company.com",
+    "requested_at": "2024-01-15T14:00:00Z",
+    "granted_at": "2024-01-15T14:30:00Z"
+  }
+}
+```
+
+---
+
+## Event Filtering Patterns
+
+### Subscribe to Specific Events
+
+```yaml
+events: ["feature.completed", "deploy.success"]
+```
+
+### Subscribe to Category
+
+```yaml
+events: ["feature.*"]   # All feature events
+events: ["deploy.*"]    # All deployment events
+events: ["security.*"]  # All security events
+```
+
+### Subscribe to All
+
+```yaml
+events: ["*"]
+```
+
+### Exclude Events
+
+```yaml
+events: ["*"]
+exclude_events: ["phase.started", "phase.completed"]
+```