proagents 1.6.20 → 1.6.22

package/.proagents/api-versioning/README.md

@@ -1,257 +0,0 @@
-# API Versioning
-
-Manage API versions, deprecation, and backward compatibility.
-
----
-
-## Overview
-
-API versioning ensures smooth evolution of your APIs while maintaining backward compatibility for existing clients. ProAgents helps you manage API versions throughout the development lifecycle.
-
----
-
-## Documentation
-
-| Document | Description |
-|----------|-------------|
-| [Versioning Strategy](./versioning-strategy.md) | URL vs header versioning, semantic versioning |
-| [Deprecation Workflow](./deprecation-workflow.md) | Deprecation timeline, migration guides |
-| [Changelog Template](./changelog-template.md) | API changelog format and automation |
-
----
-
-## Versioning Strategies
-
-### 1. URL-Based Versioning (Recommended)
-
-```
-https://api.example.com/v1/users
-https://api.example.com/v2/users
-```
-
-**Pros:**
-- Clear and explicit
-- Easy to understand
-- Cache-friendly
-- Easy to test
-
-**Cons:**
-- URL changes between versions
-- Multiple endpoints to maintain
-
-### 2. Header-Based Versioning
-
-```http
-GET /users HTTP/1.1
-Accept: application/vnd.api+json;version=2
-```
-
-**Pros:**
-- Clean URLs
-- Same resource URL across versions
-
-**Cons:**
-- Less visible
-- Harder to test in browser
-- Cache configuration needed
-
-### 3. Query Parameter Versioning
-
-```
-https://api.example.com/users?version=2
-```
-
-**Pros:**
-- Simple to implement
-- Easy to test
-
-**Cons:**
-- Not RESTful
-- Caching issues
-
----
-
-## Quick Start
-
-```yaml
-# proagents.config.yaml
-api_versioning:
-  strategy: "url"              # url | header | query
-  current_version: "v2"
-  supported_versions: ["v1", "v2"]
-  deprecation_notice: "6 months"
-
-  # Version lifecycle
-  lifecycle:
-    alpha: "unstable, may change"
-    beta: "stable, may have bugs"
-    stable: "production ready"
-    deprecated: "will be removed"
-    sunset: "no longer available"
-```
-
----
-
-## Version Lifecycle
-
-```
-Alpha → Beta → Stable → Deprecated → Sunset
-  ↓       ↓       ↓          ↓          ↓
-Unstable  Testing  Current    Notice     Removed
-```
-
-### Timeline Example
-
-| Version | Status | Date | Notes |
-|---------|--------|------|-------|
-| v1 | Deprecated | 2024-01 | Migration notice sent |
-| v1 | Sunset | 2024-07 | No longer available |
-| v2 | Stable | 2024-01 | Current version |
-| v3 | Beta | 2024-06 | Testing phase |
-
----
-
-## Commands
-
-```bash
-# Check API compatibility between versions
-proagents api check-compatibility v1 v2
-
-# Generate API changelog
-proagents api changelog
-
-# Generate migration guide
-proagents api migration-guide v1 v2
-
-# Mark version deprecated
-proagents api deprecate v1 --sunset "2024-06-01"
-
-# Check for breaking changes
-proagents api breaking-changes v1 v2
-
-# Validate API schema
-proagents api validate-schema
-```
-
----
-
-## Breaking vs Non-Breaking Changes
-
-### Breaking Changes (Require New Version)
-
-| Change Type | Example |
-|-------------|---------|
-| Remove endpoint | DELETE /api/v1/legacy |
-| Remove field | Remove `user.username` |
-| Rename field | `user_id` → `userId` |
-| Change field type | `id: number` → `id: string` |
-| Add required field | Add required `email` |
-| Change HTTP method | GET → POST |
-| Change authentication | API key → OAuth |
-
-### Non-Breaking Changes (Same Version)
-
-| Change Type | Example |
-|-------------|---------|
-| Add endpoint | New POST /api/v1/preferences |
-| Add optional field | Add `user.nickname` |
-| Add enum value | Status: `active` → `active, pending` |
-| Widen type | `int` → `number` |
-| Deprecate (not remove) | Mark field deprecated |
-| Add optional parameter | Add `?limit=10` |
-
----
-
-## Deprecation Process
-
-### Phase 1: Announcement (T-6 months)
-- Add deprecation warnings to responses
-- Update documentation
-- Notify API consumers
-
-### Phase 2: Migration Support (T-3 months)
-- Provide migration guides
-- Offer migration tools/scripts
-- Support both versions
-
-### Phase 3: Final Notice (T-1 month)
-- Send final reminders
-- Reduce support for deprecated version
-- Track remaining usage
-
-### Phase 4: Sunset (T-0)
-- Remove deprecated version
-- Return 410 Gone for old endpoints
-- Archive documentation
-
----
-
-## Response Headers
-
-```http
-HTTP/1.1 200 OK
-X-API-Version: 2
-X-API-Deprecated: true
-X-API-Sunset: 2024-06-01
-Link: <https://api.example.com/v2/users>; rel="successor-version"
-```
-
----
-
-## Changelog Format
-
-```markdown
-# API Changelog
-
-## [v2.1.0] - 2024-01-15
-
-### Added
-- `GET /users/{id}/preferences` - Fetch user preferences
-- `POST /users/{id}/avatar` - Upload user avatar
-
-### Changed
-- `GET /users` now supports pagination (breaking: removed `all` parameter)
-
-### Deprecated
-- `GET /users/{id}/settings` - Use `/preferences` instead
-
-### Removed
-- None
-
-### Fixed
-- Fixed rate limit calculation for authenticated requests
-
-### Security
-- Added input validation for user search endpoint
-```
-
----
-
-## Integration with Development
-
-### During Implementation
-- Check for breaking changes before implementation
-- Generate version comparison reports
-- Suggest migration strategies
-
-### During Testing
-- Test against multiple API versions
-- Verify backward compatibility
-- Check deprecation warnings
-
-### During Documentation
-- Generate version-specific docs
-- Create migration guides
-- Update changelog automatically
-
----
-
-## Best Practices
-
-1. **Version early** - Add versioning from the start
-2. **Document changes** - Keep detailed changelogs
-3. **Communicate** - Give advance notice of breaking changes
-4. **Support transitions** - Maintain deprecated versions during migration
-5. **Monitor usage** - Track version usage to guide sunset decisions
-6. **Test thoroughly** - Test both old and new versions
-7. **Use semantic versioning** - Major.Minor.Patch for clear communication

package/.proagents/api-versioning/changelog-template.md

@@ -1,225 +0,0 @@
-# API Changelog Template
-
-Document API changes for each version.
-
----
-
-## Changelog Format
-
-```markdown
-# API Changelog
-
-All notable changes to the API are documented here.
-
-## [v2.1.0] - 2024-01-15
-
-### Added
-- `GET /users/{id}/preferences` - Fetch user preferences
-- `PUT /users/{id}/preferences` - Update user preferences
-- `avatar_url` field to user response
-
-### Changed
-- `POST /auth/login` now returns refresh token in response body
-- Rate limit increased from 100 to 200 requests/minute
-
-### Deprecated
-- `GET /users/{id}/settings` - Use `/preferences` instead (removal: v3.0.0)
-
-### Fixed
-- Fixed pagination returning duplicate items
-- Fixed date format inconsistency in responses
-
-### Security
-- Added rate limiting to password reset endpoint
-
----
-
-## [v2.0.0] - 2024-01-01
-
-### Breaking Changes
-- Response wrapper: All responses now wrapped in `{ data: ... }`
-- Authentication: Moved from query parameter to Bearer token
-- User ID: Changed from integer to UUID
-
-### Added
-- `POST /auth/refresh` - Refresh access token
-- `DELETE /users/{id}` - Delete user account
-- Pagination metadata in list responses
-
-### Changed
-- Error response format standardized
-- All timestamps now in ISO 8601 format
-
-### Removed
-- `GET /users/search` - Use query parameters on `GET /users` instead
-- `api_key` query parameter authentication
-
-### Migration
-See [v1 to v2 Migration Guide](./migration/v1-to-v2.md)
-```
-
----
-
-## Entry Types
-
-### Added
-New endpoints, fields, or features.
-
-```markdown
-### Added
-- `GET /products/{id}/reviews` - List product reviews
-- `rating` field added to product response
-- Support for `sort` query parameter on list endpoints
-```
-
-### Changed
-Modifications to existing behavior.
-
-```markdown
-### Changed
-- `POST /orders` now requires `shipping_address` field
-- Default page size changed from 10 to 20
-- Error messages now include request ID
-```
-
-### Deprecated
-Features marked for future removal.
-
-```markdown
-### Deprecated
-- `GET /legacy/users` - Use `GET /users` instead
-  - Deprecation date: 2024-03-01
-  - Removal date: 2024-09-01
-  - Migration guide: [link]
-```
-
-### Removed
-Features that have been removed.
-
-```markdown
-### Removed
-- `GET /v1/users` - Sunset completed
-- `api_key` authentication method
-- `legacy_id` field from user response
-```
-
-### Fixed
-Bug fixes.
-
-```markdown
-### Fixed
-- Fixed 500 error when email contains special characters
-- Fixed incorrect count in pagination response
-- Fixed timezone handling in date filters
-```
-
-### Security
-Security-related changes.
-
-```markdown
-### Security
-- Added CSRF protection to all state-changing endpoints
-- Implemented rate limiting on authentication endpoints
-- Fixed XSS vulnerability in user bio field
-```
-
----
-
-## Version Entry Template
-
-```markdown
-## [vX.Y.Z] - YYYY-MM-DD
-
-### Summary
-Brief description of this release.
-
-### Breaking Changes
-- [List breaking changes with migration instructions]
-
-### Added
-- [New endpoint/feature] - [Description]
-
-### Changed
-- [Modified behavior] - [What changed]
-
-### Deprecated
-- [Feature] - [Replacement and timeline]
-
-### Removed
-- [Feature] - [Reason]
-
-### Fixed
-- [Bug] - [What was fixed]
-
-### Security
-- [Security improvement]
-
-### Documentation
-- [Documentation updates]
-
-### Internal
-- [Internal changes not affecting API consumers]
-```
-
----
-
-## Automation
-
-### Auto-Generate Changelog Entry
-
-```yaml
-# When creating PR for API changes
-api_changelog:
-  auto_generate: true
-
-  detect_from:
-    - route_changes
-    - schema_changes
-    - middleware_changes
-
-  require_entry_for:
-    - breaking_changes
-    - new_endpoints
-    - deprecated_features
-```
-
-### PR Template for API Changes
-
-```markdown
-## API Change Description
-
-### Type of Change
-- [ ] New endpoint
-- [ ] Modified endpoint
-- [ ] Deprecated endpoint
-- [ ] Breaking change
-- [ ] Bug fix
-- [ ] Security fix
-
-### Changelog Entry
-```
-### Added/Changed/Deprecated/Fixed
-- [Your changelog entry here]
-```
-
-### Breaking Change Details
-If breaking change, describe:
-- What breaks
-- Migration steps
-- Timeline
-
-### Documentation
-- [ ] API docs updated
-- [ ] Changelog updated
-- [ ] Migration guide created (if breaking)
-```
-
----
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `pa:api-changelog add` | Add changelog entry |
-| `pa:api-changelog view` | View API changelog |
-| `pa:api-changelog generate` | Auto-generate from changes |