proagents 1.6.17 → 1.6.18

package/.proagents/config-versioning/versioning.md

@@ -1,330 +0,0 @@
-# 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

@@ -1,223 +0,0 @@
-# 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
-pa:contract test consumer
-
-# Run provider tests
-pa:contract test provider
-
-# Publish contracts
-pa:contract publish
-
-# Verify contracts
-pa:contract verify
-
-# Generate contract documentation
-pa: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