proagents 1.0.0

package/proagents/config-versioning/versioning.md

@@ -0,0 +1,330 @@
+# Configuration Versioning
+
+Track all configuration changes with full history.
+
+---
+
+## Version Structure
+
+### Version Format
+
+```
+v{major}.{minor}.{patch}
+
+Examples:
+v1.0.0  - Initial configuration
+v1.1.0  - Added new checkpoint
+v1.1.1  - Fixed typo in rule
+v2.0.0  - Breaking change to standards
+```
+
+### Version Metadata
+
+```json
+{
+  "version": "v1.5.0",
+  "timestamp": "2024-01-15T10:30:00Z",
+  "author": "developer@company.com",
+  "reason": "Added stricter security rules",
+  "files_changed": [
+    "proagents.config.yaml",
+    "rules/security-rules.yaml"
+  ],
+  "checksum": "sha256:abc123..."
+}
+```
+
+---
+
+## Creating Versions
+
+### Automatic Versioning
+
+Changes are automatically versioned when using CLI:
+
+```bash
+# Set config value (creates version)
+proagents config set checkpoints.before_deployment true
+
+# Output:
+Configuration updated.
+Version: v1.5.1
+Reason: Updated checkpoints.before_deployment
+```
+
+### Manual Versioning
+
+```bash
+# Create version with message
+proagents config commit --message "Added new security rules"
+
+# Create version with specific version number
+proagents config commit --version v2.0.0 --message "Breaking changes"
+```
+
+### Version on Edit
+
+```yaml
+config_versioning:
+  auto_version:
+    enabled: true
+    on_save: true
+    version_bump: "patch"  # auto, major, minor, patch
+```
+
+---
+
+## Version History
+
+### View History
+
+```bash
+# Show recent versions
+proagents config history
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Configuration History                                       │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ v1.5.1 (current)                                           │
+│ ├── Date: Jan 15, 2024 10:30                              │
+│ ├── Author: developer@company.com                         │
+│ └── Reason: Updated checkpoint settings                   │
+│                                                             │
+│ v1.5.0                                                     │
+│ ├── Date: Jan 14, 2024 15:45                              │
+│ ├── Author: lead@company.com                              │
+│ └── Reason: Added stricter security rules                 │
+│                                                             │
+│ v1.4.0                                                     │
+│ ├── Date: Jan 10, 2024 09:00                              │
+│ ├── Author: developer@company.com                         │
+│ └── Reason: Configured test coverage targets              │
+│                                                             │
+│ Showing 3 of 15 versions. Use --all to see all.          │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Filter History
+
+```bash
+# By date range
+proagents config history --from 2024-01-01 --to 2024-01-31
+
+# By author
+proagents config history --author developer@company.com
+
+# By file
+proagents config history --file rules/security-rules.yaml
+```
+
+---
+
+## Comparing Versions
+
+### Diff Versions
+
+```bash
+# Compare with previous
+proagents config diff
+
+# Compare specific versions
+proagents config diff v1.4.0 v1.5.0
+
+# Compare with current
+proagents config diff v1.4.0
+```
+
+### Diff Output
+
+```diff
+--- v1.4.0
++++ v1.5.0
+
+proagents.config.yaml:
+@@ -15,6 +15,9 @@
+ checkpoints:
+   after_analysis: true
+-  before_deployment: false
++  before_deployment: true
++
++security:
++  require_review: true
++  scan_dependencies: true
+
+rules/security-rules.yaml:
+@@ -1,4 +1,8 @@
+ rules:
+   - id: no-secrets
+     severity: error
++
++  - id: dependency-check
++    severity: warning
++    scan_on: commit
+```
+
+---
+
+## Version Storage
+
+### Storage Structure
+
+```
+.proagents/config-history/
+├── index.json                    # Version index
+├── versions/
+│   ├── v1.5.1/
+│   │   ├── metadata.json        # Version metadata
+│   │   ├── proagents.config.yaml
+│   │   └── rules/
+│   │       └── security-rules.yaml
+│   ├── v1.5.0/
+│   │   └── ...
+│   └── v1.4.0/
+│       └── ...
+└── changelog.md                  # Human-readable changelog
+```
+
+### Index File
+
+```json
+{
+  "current_version": "v1.5.1",
+  "versions": [
+    {
+      "version": "v1.5.1",
+      "timestamp": "2024-01-15T10:30:00Z",
+      "author": "developer@company.com",
+      "path": "versions/v1.5.1"
+    },
+    {
+      "version": "v1.5.0",
+      "timestamp": "2024-01-14T15:45:00Z",
+      "author": "lead@company.com",
+      "path": "versions/v1.5.0"
+    }
+  ]
+}
+```
+
+---
+
+## Validation
+
+### Pre-Apply Validation
+
+```bash
+# Validate current config
+proagents config validate
+
+# Validate specific version
+proagents config validate --version v1.5.0
+
+# Output:
+┌─────────────────────────────────────────────────────────────┐
+│ Configuration Validation                                    │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ ✅ Syntax: Valid YAML                                      │
+│ ✅ Schema: Matches expected structure                      │
+│ ✅ Rules: All rules have valid syntax                      │
+│ ✅ References: All file references exist                   │
+│ ⚠️ Warning: Deprecated option 'old_setting' used          │
+│                                                             │
+│ Validation: PASSED (with warnings)                         │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Validation Rules
+
+```yaml
+config_versioning:
+  validation:
+    # Schema validation
+    schema: true
+
+    # Syntax check
+    syntax: true
+
+    # Check file references
+    references: true
+
+    # Check for deprecated options
+    deprecation_warnings: true
+
+    # Custom validators
+    custom:
+      - "validate_rule_ids_unique"
+      - "validate_paths_exist"
+```
+
+---
+
+## Export/Import
+
+### Export Configuration
+
+```bash
+# Export current config
+proagents config export > config-backup.yaml
+
+# Export specific version
+proagents config export --version v1.5.0 > config-v1.5.0.yaml
+
+# Export with history
+proagents config export --include-history > config-full.tar.gz
+```
+
+### Import Configuration
+
+```bash
+# Import and apply
+proagents config import config-backup.yaml
+
+# Import as new version
+proagents config import config-backup.yaml --as-version v2.0.0
+
+# Import and validate only
+proagents config import config-backup.yaml --dry-run
+```
+
+---
+
+## Hooks
+
+### Pre-Change Hooks
+
+```yaml
+config_versioning:
+  hooks:
+    pre_change:
+      - script: "validate-config.sh"
+        blocking: true
+
+      - script: "notify-team.sh"
+        blocking: false
+```
+
+### Post-Change Hooks
+
+```yaml
+config_versioning:
+  hooks:
+    post_change:
+      - script: "sync-to-remote.sh"
+      - script: "update-documentation.sh"
+```
+
+---
+
+## Best Practices
+
+1. **Always Add Reason**: Document why changes were made
+2. **Review Diffs**: Before applying, review changes
+3. **Test First**: Validate in staging before production
+4. **Backup Regularly**: Export config periodically
+5. **Use Semantic Versioning**: Major for breaking changes
+6. **Keep History Clean**: Remove very old versions

package/proagents/contract-testing/README.md

@@ -0,0 +1,223 @@
+# Contract Testing
+
+Ensure API contracts between services remain compatible.
+
+---
+
+## Overview
+
+Contract testing verifies that API interactions between services conform to agreed-upon contracts, catching integration issues early without requiring full end-to-end testing.
+
+---
+
+## What is Contract Testing?
+
+Contract testing validates that:
+- **Consumers** correctly call providers
+- **Providers** return expected responses
+- **Both sides** agree on the contract
+
+```
+┌──────────────┐                    ┌──────────────┐
+│   Consumer   │ ←── Contract ───→ │   Provider   │
+│  (Frontend)  │                    │  (Backend)   │
+└──────────────┘                    └──────────────┘
+       │                                   │
+       ▼                                   ▼
+   Consumer Tests                   Provider Tests
+   verify request                   verify response
+   matches contract                 matches contract
+```
+
+---
+
+## Quick Start
+
+### Install Pact
+
+```bash
+# Node.js
+npm install --save-dev @pact-foundation/pact
+
+# Or use Pact standalone
+curl -LO https://github.com/pact-foundation/pact-ruby-standalone/releases/latest/download/pact-2.0.0-osx.tar.gz
+```
+
+### Consumer Test
+
+```typescript
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+
+const provider = new PactV3({
+  consumer: 'Frontend',
+  provider: 'UserService',
+});
+
+describe('User API', () => {
+  it('gets user by ID', async () => {
+    await provider
+      .given('user exists')
+      .uponReceiving('a request for user')
+      .withRequest({
+        method: 'GET',
+        path: '/users/123',
+      })
+      .willRespondWith({
+        status: 200,
+        body: {
+          id: MatchersV3.string('123'),
+          name: MatchersV3.string('John'),
+          email: MatchersV3.email(),
+        },
+      })
+      .executeTest(async (mockServer) => {
+        const response = await fetch(`${mockServer.url}/users/123`);
+        const user = await response.json();
+        expect(user.name).toBe('John');
+      });
+  });
+});
+```
+
+### Provider Test
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+
+describe('User Service Provider', () => {
+  it('validates the contract', async () => {
+    await new Verifier({
+      providerBaseUrl: 'http://localhost:3000',
+      pactUrls: ['./pacts/frontend-userservice.json'],
+      stateHandlers: {
+        'user exists': async () => {
+          await db.users.create({ id: '123', name: 'John' });
+        },
+      },
+    }).verifyProvider();
+  });
+});
+```
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Contract Testing Guide](./contract-testing.md) | Complete contract testing guide |
+| [Pact Integration](./pact-integration.md) | Using Pact for contract testing |
+| [Schema Validation](./schema-validation.md) | JSON Schema and OpenAPI validation |
+
+---
+
+## Contract Testing vs Other Testing
+
+| Type | Purpose | When to Use |
+|------|---------|-------------|
+| **Unit Tests** | Test individual components | Always |
+| **Contract Tests** | Test API agreements | Service boundaries |
+| **Integration Tests** | Test real interactions | Critical paths |
+| **E2E Tests** | Test full workflows | Key user journeys |
+
+---
+
+## Benefits
+
+- **Catch breaking changes early** - Before deployment
+- **Decouple teams** - Test independently
+- **Faster feedback** - No need for running all services
+- **Living documentation** - Contracts serve as specs
+- **Prevent regression** - Automated verification
+
+---
+
+## Commands
+
+```bash
+# Run consumer tests
+/contract test consumer
+
+# Run provider tests
+/contract test provider
+
+# Publish contracts
+/contract publish
+
+# Verify contracts
+/contract verify
+
+# Generate contract documentation
+/contract docs
+```
+
+---
+
+## Configuration
+
+```yaml
+# proagents.config.yaml
+contract_testing:
+  enabled: true
+  tool: "pact"
+
+  broker:
+    url: "${PACT_BROKER_URL}"
+    token: "${PACT_BROKER_TOKEN}"
+
+  consumer:
+    output_dir: "./pacts"
+
+  provider:
+    pact_urls:
+      - "${PACT_BROKER_URL}/pacts/provider/UserService/latest"
+
+  ci:
+    can_i_deploy: true
+    publish_on_success: true
+```
+
+---
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/contract.yml
+name: Contract Tests
+
+on: [push, pull_request]
+
+jobs:
+  consumer:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: npm ci
+      - run: npm run test:contract:consumer
+      - run: npm run pact:publish
+
+  provider:
+    runs-on: ubuntu-latest
+    needs: consumer
+    steps:
+      - uses: actions/checkout@v3
+      - run: npm ci
+      - run: npm run test:contract:provider
+
+  can-i-deploy:
+    runs-on: ubuntu-latest
+    needs: [consumer, provider]
+    steps:
+      - run: pact-broker can-i-deploy --pacticipant Frontend --latest
+```
+
+---
+
+## Best Practices
+
+1. **Consumer-driven** - Consumers define what they need
+2. **Minimal contracts** - Only include what's used
+3. **Use matchers** - Don't hardcode values
+4. **Version contracts** - Track changes over time
+5. **Automate publishing** - Integrate with CI/CD
+6. **Can-I-Deploy** - Block deployments on failures