proagents 1.0.0

package/proagents/dependency-management/automation.md

@@ -0,0 +1,363 @@
+# Dependency Update Automation
+
+Automate dependency updates in CI/CD pipelines.
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/dependencies.yml
+name: Dependency Updates
+
+on:
+  schedule:
+    - cron: '0 6 * * 1'  # Weekly on Monday
+  workflow_dispatch:
+
+jobs:
+  update-dependencies:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Check for updates
+        id: check
+        run: |
+          proagents deps check --ci --output updates.json
+
+      - name: Run updates
+        if: steps.check.outputs.has_updates == 'true'
+        run: |
+          proagents deps update --ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Create PR
+        if: success()
+        run: |
+          proagents deps create-pr \
+            --title "chore(deps): weekly dependency updates" \
+            --body-file updates.json
+```
+
+### GitLab CI
+
+```yaml
+# .gitlab-ci.yml
+dependency-update:
+  stage: maintenance
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "schedule"
+  script:
+    - proagents deps check --ci
+    - proagents deps update --ci
+    - npm test
+  after_script:
+    - proagents deps create-mr
+```
+
+---
+
+## Automation Configuration
+
+### Update Schedule
+
+```yaml
+dependencies:
+  automation:
+    schedule:
+      # Check frequency
+      check: "0 6 * * *"  # Daily at 6 AM
+
+      # Update frequency by type
+      apply:
+        patch: "0 2 * * *"     # Daily at 2 AM
+        minor: "0 2 * * 1"     # Weekly Monday
+        major: "manual"        # Manual only
+
+    # Time windows
+    windows:
+      allowed:
+        - days: ["mon", "tue", "wed", "thu"]
+          hours: "02:00-06:00"
+      blocked:
+        - reason: "Release freeze"
+          dates: "2024-03-01 to 2024-03-15"
+```
+
+### Automated Actions
+
+```yaml
+dependencies:
+  automation:
+    actions:
+      # On update available
+      on_update_available:
+        - check_compatibility
+        - run_security_scan
+
+      # On patch update
+      on_patch:
+        - run_tests
+        - auto_merge_if_passing
+        - notify_on_failure
+
+      # On minor update
+      on_minor:
+        - run_tests
+        - create_pr
+        - request_review
+
+      # On major update
+      on_major:
+        - run_compatibility_check
+        - generate_migration_guide
+        - create_pr
+        - require_approval
+```
+
+---
+
+## PR Management
+
+### Auto-Create PRs
+
+```yaml
+dependencies:
+  automation:
+    pull_requests:
+      enabled: true
+
+      # Branch naming
+      branch_format: "deps/{{update_type}}-{{date}}"
+
+      # PR template
+      title: "chore(deps): {{summary}}"
+      body_template: |
+        ## Dependency Updates
+
+        This PR updates the following dependencies:
+
+        {{#each updates}}
+        ### {{this.name}}: {{this.from}} → {{this.to}}
+
+        - Type: {{this.type}}
+        - Changelog: {{this.changelog_url}}
+        {{#if this.breaking_changes}}
+        - ⚠️ Breaking changes detected
+        {{/if}}
+        {{/each}}
+
+        ## Checks
+        - [ ] Tests passing
+        - [ ] No breaking changes
+        - [ ] Security scan clean
+
+      # Labels
+      labels:
+        - "dependencies"
+        - "automated"
+
+      # Reviewers
+      reviewers:
+        - "@team/maintainers"
+```
+
+### Auto-Merge
+
+```yaml
+dependencies:
+  automation:
+    auto_merge:
+      enabled: true
+
+      # Conditions
+      conditions:
+        - all_checks_pass: true
+        - no_breaking_changes: true
+        - security_scan_clean: true
+
+      # Wait time
+      wait_before_merge: "1h"
+
+      # Merge method
+      method: "squash"
+
+      # Only for
+      types:
+        - "patch"
+```
+
+---
+
+## Testing Automation
+
+### Test Pipeline
+
+```yaml
+dependencies:
+  automation:
+    testing:
+      # Test stages
+      stages:
+        - name: "unit"
+          command: "npm test"
+          required: true
+
+        - name: "integration"
+          command: "npm run test:integration"
+          required: true
+          for_types: ["minor", "major"]
+
+        - name: "e2e"
+          command: "npm run test:e2e"
+          required: false
+          for_types: ["major"]
+
+      # Retry on failure
+      retry:
+        enabled: true
+        max_attempts: 3
+
+      # Timeout
+      timeout: "30m"
+```
+
+### Test Matrix
+
+```yaml
+dependencies:
+  automation:
+    testing:
+      matrix:
+        # Test across Node versions
+        node_versions:
+          - "18"
+          - "20"
+          - "22"
+
+        # Test across OS
+        os:
+          - "ubuntu-latest"
+          - "macos-latest"
+```
+
+---
+
+## Rollback Automation
+
+### Auto-Rollback
+
+```yaml
+dependencies:
+  automation:
+    rollback:
+      # Auto-rollback on failure
+      on_failure:
+        enabled: true
+        triggers:
+          - "tests_failed"
+          - "build_failed"
+          - "deploy_failed"
+
+      # Create rollback PR
+      create_pr: true
+
+      # Notify
+      notify:
+        - "slack:#dependencies"
+```
+
+### Rollback Commands
+
+```bash
+# Rollback last update
+proagents deps rollback
+
+# Rollback specific package
+proagents deps rollback axios
+
+# Rollback to specific version
+proagents deps rollback axios@1.5.0
+```
+
+---
+
+## Notifications
+
+### Notification Configuration
+
+```yaml
+dependencies:
+  automation:
+    notifications:
+      # On update available
+      on_available:
+        channels: ["slack:#deps"]
+        summary: true
+
+      # On PR created
+      on_pr_created:
+        channels: ["slack:#deps"]
+        mention_reviewers: true
+
+      # On auto-merge
+      on_auto_merge:
+        channels: ["slack:#deps"]
+
+      # On failure
+      on_failure:
+        channels: ["slack:#deps-alerts"]
+        priority: "high"
+```
+
+---
+
+## Monitoring
+
+### Update Metrics
+
+```bash
+proagents deps metrics
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Dependency Update Metrics - Last 30 Days                   │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Updates Processed: 45                                       │
+│ ├── Patches: 32 (auto-merged: 28)                         │
+│ ├── Minor: 10 (merged: 8, pending: 2)                     │
+│ └── Major: 3 (merged: 1, blocked: 2)                      │
+│                                                             │
+│ Success Rate: 93%                                           │
+│ Average PR Time: 4.2 hours                                 │
+│                                                             │
+│ Security Updates: 5 (all applied)                          │
+│                                                             │
+│ Blocked Updates:                                            │
+│ ├── react 19.0.0 - Breaking changes                       │
+│ └── webpack 6.0.0 - Requires migration                    │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Best Practices
+
+1. **Start Conservative**: Enable auto-merge for patches only
+2. **Test Thoroughly**: Run full test suite before merge
+3. **Monitor Metrics**: Track success rates and issues
+4. **Review Majors**: Always manually review major updates
+5. **Have Rollback Plan**: Auto-rollback on failures
+6. **Notify Team**: Keep team informed of updates

package/proagents/dependency-management/compatibility.md

@@ -0,0 +1,319 @@
+# Breaking Change Detection
+
+Detect and handle breaking changes in dependency updates.
+
+---
+
+## Detection Methods
+
+### Semantic Version Analysis
+
+```yaml
+dependencies:
+  compatibility:
+    semver:
+      # Major version = potential breaking changes
+      major_update:
+        assume_breaking: true
+        require_review: true
+
+      # Check actual changes
+      analyze_changelog: true
+      analyze_types: true
+```
+
+### Type Checking
+
+```yaml
+dependencies:
+  compatibility:
+    types:
+      enabled: true
+
+      # TypeScript type compatibility
+      typescript:
+        check_interfaces: true
+        check_exports: true
+        check_removed: true
+
+      # Report level
+      report:
+        removed_exports: "error"
+        changed_signatures: "warning"
+        new_required_params: "error"
+```
+
+### API Analysis
+
+```yaml
+dependencies:
+  compatibility:
+    api:
+      enabled: true
+
+      checks:
+        - removed_functions
+        - changed_signatures
+        - removed_exports
+        - changed_return_types
+        - new_required_parameters
+```
+
+---
+
+## Compatibility Report
+
+### Generate Report
+
+```bash
+proagents deps check-compatibility lodash@5.0.0
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Compatibility Report: lodash 4.17.21 → 5.0.0               │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Breaking Changes Detected: 3                                │
+│                                                             │
+│ ❌ Removed Functions:                                       │
+│ ├── _.pluck() - Use _.map() instead                        │
+│ └── _.where() - Use _.filter() instead                     │
+│                                                             │
+│ ⚠️ Changed Signatures:                                      │
+│ └── _.merge() - Now returns undefined for null inputs      │
+│                                                             │
+│ Your Usage:                                                 │
+│ ├── _.pluck() used in: src/utils/data.ts:45               │
+│ ├── _.where() used in: src/services/filter.ts:23          │
+│ └── _.merge() used in: 5 files                             │
+│                                                             │
+│ Migration Effort: Medium                                    │
+│ Estimated Changes: 8 files, ~20 lines                      │
+│                                                             │
+│ [View Migration Guide] [Skip Update] [Auto-Fix]            │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Impact Analysis
+
+### Code Impact
+
+```yaml
+dependencies:
+  compatibility:
+    impact_analysis:
+      enabled: true
+
+      # Scan codebase for usage
+      scan:
+        - imports
+        - function_calls
+        - type_usage
+
+      # Report affected files
+      report_affected: true
+
+      # Estimate effort
+      estimate_effort: true
+```
+
+### Impact Report
+
+```bash
+proagents deps impact axios@2.0.0
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Impact Analysis: axios 1.6.0 → 2.0.0                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Files Affected: 12                                          │
+│                                                             │
+│ High Impact (requires changes):                            │
+│ ├── src/services/api.ts                                    │
+│ │   └── axios.create() signature changed                   │
+│ ├── src/services/auth.ts                                   │
+│ │   └── Interceptor API changed                            │
+│ └── src/utils/http.ts                                      │
+│     └── Error handling changed                             │
+│                                                             │
+│ Medium Impact (may require changes):                       │
+│ ├── src/hooks/useApi.ts                                    │
+│ └── src/components/DataFetcher.tsx                         │
+│                                                             │
+│ Low Impact (likely compatible):                            │
+│ └── 7 files with basic usage                               │
+│                                                             │
+│ Total Effort: ~2-4 hours                                   │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Migration Guides
+
+### Auto-Generated Guide
+
+```yaml
+dependencies:
+  compatibility:
+    migration:
+      # Generate migration guide
+      auto_generate: true
+
+      # Include code examples
+      include_examples: true
+
+      # Fetch from package docs
+      fetch_official: true
+```
+
+### Migration Guide Output
+
+```markdown
+# Migration Guide: axios 1.x → 2.x
+
+## Breaking Changes
+
+### 1. Create Instance
+
+**Before:**
+```javascript
+const instance = axios.create({
+  baseURL: 'https://api.example.com'
+});
+```
+
+**After:**
+```javascript
+const instance = axios.create({
+  baseURL: 'https://api.example.com',
+  adapter: 'fetch'  // New required option
+});
+```
+
+### 2. Error Handling
+
+**Before:**
+```javascript
+try {
+  await axios.get('/api');
+} catch (error) {
+  console.log(error.response.data);
+}
+```
+
+**After:**
+```javascript
+try {
+  await axios.get('/api');
+} catch (error) {
+  console.log(error.data);  // Changed path
+}
+```
+
+## Affected Files in Your Project
+
+- `src/services/api.ts:15` - Update create() call
+- `src/services/auth.ts:42` - Update interceptor
+- `src/utils/http.ts:28` - Update error handling
+```
+
+---
+
+## Auto-Migration
+
+### Codemods
+
+```yaml
+dependencies:
+  compatibility:
+    codemods:
+      enabled: true
+
+      # Run official codemods
+      official:
+        enabled: true
+        packages:
+          - "react"
+          - "next"
+
+      # Custom codemods
+      custom:
+        - package: "lodash"
+          codemod: "scripts/codemods/lodash-5.js"
+```
+
+### Run Migration
+
+```bash
+# Run codemod for package
+proagents deps migrate lodash@5.0.0
+
+# Dry run
+proagents deps migrate lodash@5.0.0 --dry-run
+
+# Specific files
+proagents deps migrate lodash@5.0.0 --files "src/utils/**"
+```
+
+---
+
+## Compatibility Matrix
+
+### Track Compatibility
+
+```yaml
+dependencies:
+  compatibility:
+    matrix:
+      # Track tested combinations
+      track: true
+
+      # Required versions
+      required:
+        node: ">=18.0.0"
+        npm: ">=9.0.0"
+
+      # Known compatible versions
+      tested:
+        - react: "18.x"
+          react-dom: "18.x"
+          typescript: "5.x"
+```
+
+### View Matrix
+
+```bash
+proagents deps compatibility-matrix
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Compatibility Matrix                                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ Package        │ Current │ Latest │ Compatible │ Status    │
+│────────────────┼─────────┼────────┼────────────┼───────────│
+│ react          │ 18.2.0  │ 19.0.0 │ ❌         │ Breaking  │
+│ typescript     │ 5.2.0   │ 5.4.0  │ ✅         │ Safe      │
+│ axios          │ 1.6.0   │ 2.0.0  │ ⚠️         │ Review    │
+│ lodash         │ 4.17.21 │ 5.0.0  │ ❌         │ Breaking  │
+│ tailwindcss    │ 3.3.0   │ 3.4.0  │ ✅         │ Safe      │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Best Practices
+
+1. **Check Before Update**: Always run compatibility check
+2. **Read Changelogs**: Review official breaking changes
+3. **Test Thoroughly**: Run full test suite after updates
+4. **Use Codemods**: Leverage official migration tools
+5. **Staged Rollout**: Update in staging first
+6. **Document Changes**: Record migration steps taken