proagents 1.6.20 → 1.6.21

package/.proagents/cost/estimation-framework.md

@@ -1,287 +0,0 @@
-# Cost Estimation Framework
-
-Estimate infrastructure and operational costs for new features.
-
----
-
-## Cost Categories
-
-### 1. Compute Costs
-
-**Serverless Functions:**
-```yaml
-compute:
-  serverless:
-    provider: "aws_lambda"  # aws_lambda | vercel | cloudflare_workers
-
-    estimate:
-      invocations_per_month: 1000000
-      avg_duration_ms: 200
-      memory_mb: 256
-
-    calculation:
-      # AWS Lambda pricing (example)
-      request_cost: "$0.20 per 1M requests"
-      duration_cost: "$0.0000166667 per GB-second"
-
-      monthly_estimate:
-        requests: "$0.20"
-        duration: "$0.83"  # 1M × 0.2s × 0.25GB × $0.0000166667
-        total: "$1.03"
-```
-
-**Container/Server:**
-```yaml
-compute:
-  containers:
-    provider: "aws_ecs"  # aws_ecs | gcp_cloud_run | azure_container
-
-    estimate:
-      instances: 2
-      vcpu: 0.5
-      memory_gb: 1
-      hours_per_month: 730
-
-    monthly_estimate: "$30"
-```
-
----
-
-### 2. Storage Costs
-
-**Database:**
-```yaml
-storage:
-  database:
-    provider: "aws_rds"  # aws_rds | planetscale | supabase
-
-    estimate:
-      storage_gb: 20
-      iops: 1000
-      backup_retention_days: 7
-
-    monthly_estimate:
-      storage: "$2.30"
-      iops: "$10.00"
-      backup: "$1.00"
-      total: "$13.30"
-```
-
-**File Storage:**
-```yaml
-storage:
-  files:
-    provider: "aws_s3"  # aws_s3 | cloudflare_r2 | gcp_storage
-
-    estimate:
-      storage_gb: 100
-      requests_per_month: 100000
-      bandwidth_gb: 50
-
-    monthly_estimate:
-      storage: "$2.30"
-      requests: "$0.04"
-      bandwidth: "$4.50"
-      total: "$6.84"
-```
-
----
-
-### 3. Network Costs
-
-```yaml
-network:
-  cdn:
-    provider: "cloudflare"  # cloudflare | aws_cloudfront | vercel
-
-    estimate:
-      bandwidth_gb: 100
-      requests_per_month: 10000000
-
-    monthly_estimate:
-      cloudflare_free: "$0"
-      cloudflare_pro: "$20"
-      aws_cloudfront: "$8.50"
-
-  api_gateway:
-    provider: "aws_api_gateway"
-
-    estimate:
-      requests_per_month: 1000000
-
-    monthly_estimate: "$3.50"
-```
-
----
-
-### 4. Third-Party Services
-
-```yaml
-third_party:
-  auth:
-    provider: "auth0"
-    estimate:
-      monthly_active_users: 1000
-    monthly_estimate: "$0 (free tier)"  # Up to 7000 MAU
-
-  email:
-    provider: "sendgrid"
-    estimate:
-      emails_per_month: 10000
-    monthly_estimate: "$0 (free tier)"  # Up to 100/day
-
-  monitoring:
-    provider: "datadog"
-    estimate:
-      hosts: 2
-      custom_metrics: 100
-    monthly_estimate: "$30"
-
-  search:
-    provider: "algolia"
-    estimate:
-      records: 10000
-      searches_per_month: 100000
-    monthly_estimate: "$0 (free tier)"
-```
-
----
-
-## Cost Estimation Template
-
-```markdown
-# Feature Cost Estimate
-
-## Feature: [Feature Name]
-## Date: [YYYY-MM-DD]
-## Estimated By: [Name]
-
----
-
-## Summary
-
-| Category | Monthly Cost | Annual Cost |
-|----------|-------------|-------------|
-| Compute | $XX | $XXX |
-| Storage | $XX | $XXX |
-| Network | $XX | $XXX |
-| Third-party | $XX | $XXX |
-| **Total** | **$XX** | **$XXX** |
-
----
-
-## Detailed Breakdown
-
-### Compute
-| Resource | Specs | Cost |
-|----------|-------|------|
-| Lambda functions | 1M invocations, 256MB | $1.03 |
-| ECS containers | 2 × 0.5 vCPU | $30.00 |
-| **Subtotal** | | **$31.03** |
-
-### Storage
-| Resource | Specs | Cost |
-|----------|-------|------|
-| RDS PostgreSQL | 20GB, db.t3.micro | $13.30 |
-| S3 bucket | 100GB, standard | $6.84 |
-| **Subtotal** | | **$20.14** |
-
-### Network
-| Resource | Specs | Cost |
-|----------|-------|------|
-| CloudFront | 100GB bandwidth | $8.50 |
-| API Gateway | 1M requests | $3.50 |
-| **Subtotal** | | **$12.00** |
-
-### Third-Party Services
-| Service | Tier | Cost |
-|---------|------|------|
-| Auth0 | Free | $0 |
-| SendGrid | Free | $0 |
-| Datadog | Pro | $30 |
-| **Subtotal** | | **$30.00** |
-
----
-
-## Assumptions
-- Traffic estimates based on [source]
-- Growth rate: [X]% monthly
-- Peak traffic: [X]× average
-
-## Scaling Projections
-
-| Users | Monthly Cost |
-|-------|-------------|
-| 1,000 | $93 |
-| 10,000 | $250 |
-| 100,000 | $1,200 |
-
-## Cost Optimization Recommendations
-1. Use reserved instances for predictable workloads
-2. Implement caching to reduce database calls
-3. Use CDN for static assets
-```
-
----
-
-## Approval Thresholds
-
-```yaml
-cost_approval:
-  thresholds:
-    - range: "$0-100"
-      approver: "auto_approved"
-
-    - range: "$100-500"
-      approver: "tech_lead"
-      requires: "cost_estimate_doc"
-
-    - range: "$500-2000"
-      approver: "engineering_manager"
-      requires:
-        - "cost_estimate_doc"
-        - "scaling_projections"
-
-    - range: "$2000+"
-      approver: "director"
-      requires:
-        - "cost_estimate_doc"
-        - "scaling_projections"
-        - "roi_analysis"
-```
-
----
-
-## Cost Monitoring
-
-```yaml
-monitoring:
-  alerts:
-    - threshold: "80% of budget"
-      action: "notify"
-      recipients: ["team-lead"]
-
-    - threshold: "100% of budget"
-      action: "notify_urgent"
-      recipients: ["team-lead", "manager"]
-
-    - threshold: "120% of budget"
-      action: "auto_scale_down"
-      notify: ["all"]
-
-  reports:
-    daily: true
-    weekly_summary: true
-    monthly_detailed: true
-```
-
----
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `pa:cost-estimate` | Generate cost estimate for feature |
-| `pa:cost-compare` | Compare costs across providers |
-| `pa:cost-report` | View current costs |
-| `pa:cost-optimize` | Get optimization suggestions |

package/.proagents/database/README.md

@@ -1,72 +0,0 @@
-# Database Management
-
-Schema migrations, safety checks, and rollback procedures.
-
----
-
-## Overview
-
-Safe database changes with version control, validation, and rollback capabilities.
-
-## Documentation
-
-| Document | Description |
-|----------|-------------|
-| [Migration Workflow](./migration-workflow.md) | Creating and running migrations |
-| [Safety Checks](./safety-checks.md) | Pre-migration validation |
-| [Rollback Scripts](./rollback-scripts.md) | Reverting database changes |
-| [Examples](./examples/) | Concrete migration examples |
-
-## Examples
-
-Ready-to-use migration templates:
-
-| Example | Description | Risk |
-|---------|-------------|------|
-| [001-create-users](./examples/001-create-users.sql) | Create table with indexes | Low |
-| [002-add-preferences](./examples/002-add-preferences.sql) | Add JSONB column | Low |
-| [003-add-index](./examples/003-add-index.sql) | Add performance index | Medium |
-| [004-rename-column](./examples/004-rename-column.sql) | Rename column safely | Medium |
-| [005-add-foreign-key](./examples/005-add-foreign-key.sql) | Add relationships | Medium |
-| [006-data-migration](./examples/006-data-migration.sql) | Transform data | High |
-| [007-drop-column](./examples/007-drop-column.sql) | Remove column | High |
-
-## Quick Start
-
-```bash
-# Create a new migration
-proagents db migration create "add_user_preferences"
-
-# Run pending migrations
-proagents db migrate
-
-# Rollback last migration
-proagents db rollback
-
-# Check migration status
-proagents db status
-```
-
-## Safety Features
-
-- **Dry Run**: Preview changes before applying
-- **Backup**: Automatic backup before migrations
-- **Validation**: Check for breaking changes
-- **Rollback Scripts**: Every migration has a rollback
-
-## Configuration
-
-```yaml
-# proagents.config.yaml
-database:
-  migrations:
-    directory: "./migrations"
-    backup_before: true
-    require_rollback: true
-
-  safety:
-    block_destructive: true
-    require_approval_for:
-      - "drop_table"
-      - "drop_column"
-```

package/.proagents/database/examples/001-create-users.sql

@@ -1,129 +0,0 @@
--- Migration: Create users table
--- Author: ProAgents
--- Date: 2024-01-15
--- Risk Level: Low
--- Requires Approval: No
--- Estimated Duration: < 1 second
-
--- Description:
--- Creates the core users table with essential fields for authentication
--- and profile information. This is typically one of the first migrations
--- in a new project.
-
--- ============================================
--- UP MIGRATION
--- ============================================
-
--- Create enum for user status
-CREATE TYPE user_status AS ENUM ('active', 'inactive', 'suspended', 'pending');
-
--- Create enum for user role
-CREATE TYPE user_role AS ENUM ('admin', 'developer', 'viewer', 'guest');
-
--- Create users table
-CREATE TABLE users (
-    -- Primary key
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-
-    -- Authentication fields
-    email VARCHAR(255) NOT NULL,
-    password_hash VARCHAR(255) NOT NULL,
-
-    -- Profile fields
-    first_name VARCHAR(100),
-    last_name VARCHAR(100),
-    display_name VARCHAR(100),
-    avatar_url TEXT,
-
-    -- Status and role
-    status user_status NOT NULL DEFAULT 'pending',
-    role user_role NOT NULL DEFAULT 'viewer',
-
-    -- Email verification
-    email_verified BOOLEAN NOT NULL DEFAULT FALSE,
-    email_verified_at TIMESTAMP WITH TIME ZONE,
-
-    -- Timestamps
-    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    last_login_at TIMESTAMP WITH TIME ZONE,
-
-    -- Soft delete
-    deleted_at TIMESTAMP WITH TIME ZONE
-);
-
--- Create unique index on email (excluding soft-deleted users)
-CREATE UNIQUE INDEX idx_users_email_unique
-    ON users (email)
-    WHERE deleted_at IS NULL;
-
--- Create index for common queries
-CREATE INDEX idx_users_status ON users (status) WHERE deleted_at IS NULL;
-CREATE INDEX idx_users_role ON users (role) WHERE deleted_at IS NULL;
-CREATE INDEX idx_users_created_at ON users (created_at);
-
--- Create updated_at trigger function (reusable)
-CREATE OR REPLACE FUNCTION update_updated_at_column()
-RETURNS TRIGGER AS $$
-BEGIN
-    NEW.updated_at = NOW();
-    RETURN NEW;
-END;
-$$ LANGUAGE plpgsql;
-
--- Apply trigger to users table
-CREATE TRIGGER trigger_users_updated_at
-    BEFORE UPDATE ON users
-    FOR EACH ROW
-    EXECUTE FUNCTION update_updated_at_column();
-
--- Add table comment
-COMMENT ON TABLE users IS 'Core user accounts for authentication and authorization';
-
--- ============================================
--- DOWN MIGRATION (Rollback)
--- ============================================
-
--- WARNING: This will delete all user data!
--- Ensure you have a backup before running rollback.
-
--- Drop trigger
-DROP TRIGGER IF EXISTS trigger_users_updated_at ON users;
-
--- Drop function (only if not used by other tables)
--- DROP FUNCTION IF EXISTS update_updated_at_column();
-
--- Drop table
-DROP TABLE IF EXISTS users;
-
--- Drop enums
-DROP TYPE IF EXISTS user_role;
-DROP TYPE IF EXISTS user_status;
-
--- ============================================
--- VERIFICATION
--- ============================================
-
--- Run these queries to verify the migration succeeded:
-
--- Check table exists
-SELECT EXISTS (
-    SELECT FROM information_schema.tables
-    WHERE table_name = 'users'
-);
-
--- Check columns
-SELECT column_name, data_type, is_nullable
-FROM information_schema.columns
-WHERE table_name = 'users'
-ORDER BY ordinal_position;
-
--- Check indexes
-SELECT indexname, indexdef
-FROM pg_indexes
-WHERE tablename = 'users';
-
--- Check trigger
-SELECT trigger_name
-FROM information_schema.triggers
-WHERE event_object_table = 'users';

package/.proagents/database/examples/002-add-preferences.sql

@@ -1,94 +0,0 @@
--- Migration: Add user preferences column
--- Author: ProAgents
--- Date: 2024-01-16
--- Risk Level: Low
--- Requires Approval: No
--- Estimated Duration: < 1 second
-
--- Description:
--- Adds a JSONB column to store user preferences like theme, language,
--- notification settings, etc. Using JSONB allows flexible schema-less
--- storage with indexing capabilities.
-
--- ============================================
--- UP MIGRATION
--- ============================================
-
--- Add preferences column with default empty object
-ALTER TABLE users
-ADD COLUMN preferences JSONB NOT NULL DEFAULT '{}'::jsonb;
-
--- Add GIN index for JSONB queries
--- This enables fast queries like: WHERE preferences @> '{"theme": "dark"}'
-CREATE INDEX idx_users_preferences
-    ON users USING GIN (preferences);
-
--- Add specific index for common preference queries
-CREATE INDEX idx_users_preferences_theme
-    ON users ((preferences->>'theme'))
-    WHERE preferences->>'theme' IS NOT NULL;
-
--- Add column comment
-COMMENT ON COLUMN users.preferences IS 'User preferences stored as JSONB. Keys: theme, language, notifications, timezone, etc.';
-
--- Optionally set default preferences for existing users
-UPDATE users
-SET preferences = jsonb_build_object(
-    'theme', 'light',
-    'language', 'en',
-    'notifications', jsonb_build_object(
-        'email', true,
-        'push', true,
-        'weekly_digest', false
-    ),
-    'timezone', 'UTC'
-)
-WHERE preferences = '{}'::jsonb;
-
--- ============================================
--- DOWN MIGRATION (Rollback)
--- ============================================
-
--- Drop indexes first
-DROP INDEX IF EXISTS idx_users_preferences_theme;
-DROP INDEX IF EXISTS idx_users_preferences;
-
--- Remove column
-ALTER TABLE users DROP COLUMN IF EXISTS preferences;
-
--- ============================================
--- VERIFICATION
--- ============================================
-
--- Check column exists
-SELECT column_name, data_type, column_default
-FROM information_schema.columns
-WHERE table_name = 'users' AND column_name = 'preferences';
-
--- Check indexes exist
-SELECT indexname
-FROM pg_indexes
-WHERE tablename = 'users' AND indexname LIKE '%preferences%';
-
--- Test JSONB query performance
-EXPLAIN ANALYZE
-SELECT id, email, preferences->>'theme' as theme
-FROM users
-WHERE preferences @> '{"theme": "dark"}';
-
--- ============================================
--- EXAMPLE USAGE
--- ============================================
-
--- Query users by preference
--- SELECT * FROM users WHERE preferences->>'theme' = 'dark';
-
--- Update a single preference
--- UPDATE users
--- SET preferences = jsonb_set(preferences, '{theme}', '"dark"')
--- WHERE id = '...';
-
--- Add new preference key
--- UPDATE users
--- SET preferences = preferences || '{"sidebar_collapsed": true}'::jsonb
--- WHERE id = '...';

package/.proagents/database/examples/003-add-index.sql

@@ -1,105 +0,0 @@
--- Migration: Add performance index on users.email
--- Author: ProAgents
--- Date: 2024-01-17
--- Risk Level: Medium
--- Requires Approval: Team Lead
--- Estimated Duration: Depends on table size (1-5 minutes for large tables)
-
--- Description:
--- Adds a B-tree index on the email column to improve login query performance.
--- Uses CONCURRENTLY to avoid locking the table during index creation.
---
--- IMPORTANT: CONCURRENTLY cannot be used inside a transaction block.
--- Run this migration outside of a transaction.
-
--- ============================================
--- PRE-FLIGHT CHECKS
--- ============================================
-
--- Check table size before creating index
-SELECT
-    pg_size_pretty(pg_total_relation_size('users')) as table_size,
-    (SELECT count(*) FROM users) as row_count;
-
--- Estimate index creation time (rough)
--- Rule of thumb: ~1 minute per 10 million rows
-
--- ============================================
--- UP MIGRATION
--- ============================================
-
--- Create index concurrently (non-blocking)
--- NOTE: Cannot run inside transaction
-CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_email_lookup
-    ON users (LOWER(email))
-    WHERE deleted_at IS NULL;
-
--- Create composite index for common queries
-CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_status_created
-    ON users (status, created_at DESC)
-    WHERE deleted_at IS NULL;
-
--- Create partial index for active users only
-CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_active
-    ON users (last_login_at DESC)
-    WHERE status = 'active' AND deleted_at IS NULL;
-
--- ============================================
--- DOWN MIGRATION (Rollback)
--- ============================================
-
--- Drop indexes (also use CONCURRENTLY for safety)
-DROP INDEX CONCURRENTLY IF EXISTS idx_users_active;
-DROP INDEX CONCURRENTLY IF EXISTS idx_users_status_created;
-DROP INDEX CONCURRENTLY IF EXISTS idx_users_email_lookup;
-
--- ============================================
--- VERIFICATION
--- ============================================
-
--- Check indexes were created
-SELECT
-    indexname,
-    indexdef,
-    pg_size_pretty(pg_relation_size(indexname::regclass)) as index_size
-FROM pg_indexes
-WHERE tablename = 'users'
-ORDER BY indexname;
-
--- Verify index is being used
-EXPLAIN ANALYZE
-SELECT id, email
-FROM users
-WHERE LOWER(email) = 'test@example.com'
-  AND deleted_at IS NULL;
-
--- Check for invalid indexes (failed CONCURRENTLY)
-SELECT indexrelid::regclass as index_name, indisvalid
-FROM pg_index
-WHERE NOT indisvalid;
-
--- ============================================
--- TROUBLESHOOTING
--- ============================================
-
--- If CONCURRENTLY fails, the index may be in invalid state.
--- Check and drop invalid indexes:
---
--- SELECT indexrelid::regclass
--- FROM pg_index
--- WHERE NOT indisvalid;
---
--- DROP INDEX CONCURRENTLY idx_users_email_lookup;
--- Then retry the CREATE INDEX CONCURRENTLY.
-
--- ============================================
--- PERFORMANCE COMPARISON
--- ============================================
-
--- Before index (sequential scan):
--- Seq Scan on users  (cost=0.00..1234.00 rows=1 width=36)
---   Filter: (lower((email)::text) = 'test@example.com'::text)
-
--- After index (index scan):
--- Index Scan using idx_users_email_lookup on users  (cost=0.42..8.44 rows=1 width=36)
---   Index Cond: (lower((email)::text) = 'test@example.com'::text)