proagents 1.6.17 → 1.6.19

package/.proagents/monitoring/metrics.md

@@ -1,434 +0,0 @@
-# Metrics Collection
-
-Application and infrastructure metrics for observability.
-
----
-
-## Metric Types
-
-| Type | Description | Example |
-|------|-------------|---------|
-| **Counter** | Cumulative value (only increases) | Total requests |
-| **Gauge** | Current value (can go up/down) | Active connections |
-| **Histogram** | Distribution of values | Request latency |
-| **Summary** | Similar to histogram with percentiles | Response times |
-
----
-
-## Configuration
-
-### Basic Setup
-
-```yaml
-# proagents.config.yaml
-monitoring:
-  metrics:
-    enabled: true
-
-    # Metrics endpoint
-    endpoint:
-      path: "/metrics"
-      port: 9090
-      format: "prometheus"
-
-    # Collection interval
-    interval: "15s"
-
-    # Labels applied to all metrics
-    global_labels:
-      service: "${SERVICE_NAME}"
-      environment: "${NODE_ENV}"
-      version: "${VERSION}"
-```
-
-### Metric Definitions
-
-```yaml
-monitoring:
-  metrics:
-    definitions:
-      # HTTP metrics
-      http:
-        requests_total:
-          type: "counter"
-          description: "Total HTTP requests"
-          labels: ["method", "path", "status"]
-
-        request_duration_seconds:
-          type: "histogram"
-          description: "HTTP request duration"
-          labels: ["method", "path"]
-          buckets: [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
-
-        requests_in_flight:
-          type: "gauge"
-          description: "Current in-flight requests"
-
-      # Business metrics
-      business:
-        orders_total:
-          type: "counter"
-          description: "Total orders placed"
-          labels: ["status", "payment_method"]
-
-        order_value:
-          type: "histogram"
-          description: "Order value distribution"
-          buckets: [10, 25, 50, 100, 250, 500, 1000]
-
-        active_users:
-          type: "gauge"
-          description: "Currently active users"
-```
-
----
-
-## Standard Metrics
-
-### RED Metrics (Request, Error, Duration)
-
-```yaml
-monitoring:
-  metrics:
-    red:
-      enabled: true
-
-      request:
-        name: "http_requests_total"
-        labels: ["method", "endpoint", "status"]
-
-      error:
-        name: "http_errors_total"
-        labels: ["method", "endpoint", "error_type"]
-
-      duration:
-        name: "http_request_duration_seconds"
-        labels: ["method", "endpoint"]
-        percentiles: [0.5, 0.9, 0.95, 0.99]
-```
-
-### USE Metrics (Utilization, Saturation, Errors)
-
-```yaml
-monitoring:
-  metrics:
-    use:
-      enabled: true
-
-      # CPU
-      cpu:
-        utilization: "process_cpu_seconds_total"
-        saturation: "process_runnable_tasks"
-
-      # Memory
-      memory:
-        utilization: "process_resident_memory_bytes"
-        saturation: "process_heap_bytes"
-
-      # Connections
-      connections:
-        utilization: "db_connections_active"
-        saturation: "db_connections_waiting"
-        errors: "db_connection_errors_total"
-```
-
-### Four Golden Signals
-
-```yaml
-monitoring:
-  metrics:
-    golden_signals:
-      latency:
-        metric: "http_request_duration_seconds"
-        targets:
-          p50: 0.1
-          p95: 0.5
-          p99: 1.0
-
-      traffic:
-        metric: "http_requests_total"
-        rate_window: "1m"
-
-      errors:
-        metric: "http_errors_total"
-        ratio: "http_errors_total / http_requests_total"
-        target: "< 0.01"
-
-      saturation:
-        metrics:
-          - "cpu_utilization"
-          - "memory_utilization"
-          - "connection_pool_utilization"
-        target: "< 0.8"
-```
-
----
-
-## Code Integration
-
-### JavaScript/TypeScript
-
-```typescript
-import { Metrics } from '@proagents/monitoring';
-
-const metrics = new Metrics({
-  prefix: 'myapp',
-  defaultLabels: {
-    service: 'api',
-    environment: process.env.NODE_ENV,
-  },
-});
-
-// Counter
-const requestCounter = metrics.counter({
-  name: 'http_requests_total',
-  help: 'Total HTTP requests',
-  labels: ['method', 'path', 'status'],
-});
-
-// Histogram
-const requestDuration = metrics.histogram({
-  name: 'http_request_duration_seconds',
-  help: 'Request duration in seconds',
-  labels: ['method', 'path'],
-  buckets: [0.01, 0.05, 0.1, 0.5, 1, 5],
-});
-
-// Gauge
-const activeConnections = metrics.gauge({
-  name: 'active_connections',
-  help: 'Current active connections',
-});
-
-// Usage
-app.use((req, res, next) => {
-  const timer = requestDuration.startTimer({ method: req.method, path: req.path });
-
-  res.on('finish', () => {
-    timer();
-    requestCounter.inc({ method: req.method, path: req.path, status: res.statusCode });
-  });
-
-  next();
-});
-```
-
-### Express Middleware
-
-```typescript
-import { metricsMiddleware, metricsEndpoint } from '@proagents/monitoring/express';
-
-// Auto-instrument all routes
-app.use(metricsMiddleware({
-  // Normalize paths
-  normalizePath: (path) => path.replace(/\/\d+/g, '/:id'),
-
-  // Skip certain paths
-  skip: ['/health', '/metrics'],
-
-  // Custom labels
-  customLabels: (req, res) => ({
-    user_type: req.user?.type || 'anonymous',
-  }),
-}));
-
-// Expose metrics endpoint
-app.get('/metrics', metricsEndpoint());
-```
-
----
-
-## Custom Metrics
-
-### Business Metrics
-
-```yaml
-monitoring:
-  metrics:
-    custom:
-      # Revenue tracking
-      revenue_total:
-        type: "counter"
-        description: "Total revenue in cents"
-        labels: ["currency", "product_category"]
-
-      # User engagement
-      feature_usage:
-        type: "counter"
-        description: "Feature usage count"
-        labels: ["feature", "user_tier"]
-
-      # SLA metrics
-      sla_compliance:
-        type: "gauge"
-        description: "SLA compliance percentage"
-        labels: ["service", "metric"]
-```
-
-### Application-Specific Metrics
-
-```typescript
-// Order processing metrics
-const orderMetrics = {
-  ordersCreated: metrics.counter({
-    name: 'orders_created_total',
-    labels: ['payment_method', 'shipping_type'],
-  }),
-
-  orderValue: metrics.histogram({
-    name: 'order_value_dollars',
-    buckets: [10, 50, 100, 500, 1000, 5000],
-  }),
-
-  orderProcessingTime: metrics.histogram({
-    name: 'order_processing_seconds',
-    buckets: [1, 5, 10, 30, 60, 120],
-  }),
-
-  pendingOrders: metrics.gauge({
-    name: 'pending_orders',
-  }),
-};
-
-// Usage
-async function processOrder(order) {
-  const timer = orderMetrics.orderProcessingTime.startTimer();
-
-  try {
-    await fulfillOrder(order);
-    orderMetrics.ordersCreated.inc({
-      payment_method: order.paymentMethod,
-      shipping_type: order.shippingType,
-    });
-    orderMetrics.orderValue.observe(order.total);
-  } finally {
-    timer();
-    orderMetrics.pendingOrders.dec();
-  }
-}
-```
-
----
-
-## Metric Backends
-
-### Prometheus
-
-```yaml
-monitoring:
-  metrics:
-    backend: "prometheus"
-
-    prometheus:
-      # Push gateway (optional)
-      push_gateway:
-        url: "http://pushgateway:9091"
-        job: "myapp"
-        push_interval: "15s"
-
-      # Scrape config (for reference)
-      scrape_config:
-        scrape_interval: "15s"
-        scrape_timeout: "10s"
-```
-
-### Datadog
-
-```yaml
-monitoring:
-  metrics:
-    backend: "datadog"
-
-    datadog:
-      api_key_env: "DD_API_KEY"
-      app_key_env: "DD_APP_KEY"
-
-      # Default tags
-      tags:
-        - "env:production"
-        - "service:api"
-
-      # Histogram aggregations
-      histogram:
-        aggregates: ["avg", "count", "max", "min", "sum"]
-        percentiles: [0.5, 0.75, 0.95, 0.99]
-```
-
-### CloudWatch
-
-```yaml
-monitoring:
-  metrics:
-    backend: "cloudwatch"
-
-    cloudwatch:
-      region: "us-east-1"
-      namespace: "MyApp"
-
-      # Dimensions
-      dimensions:
-        Environment: "production"
-        Service: "api"
-
-      # Resolution
-      storage_resolution: 60  # 1 minute
-```
-
----
-
-## Aggregation & Queries
-
-### Common Queries
-
-```yaml
-monitoring:
-  metrics:
-    queries:
-      # Request rate
-      request_rate: |
-        rate(http_requests_total[5m])
-
-      # Error rate
-      error_rate: |
-        rate(http_errors_total[5m]) / rate(http_requests_total[5m])
-
-      # P99 latency
-      p99_latency: |
-        histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))
-
-      # Active users (cardinality)
-      active_users: |
-        count(count by (user_id) (http_requests_total[1h]))
-```
-
----
-
-## Commands
-
-```bash
-# View current metrics
-proagents metrics list
-
-# Query specific metric
-proagents metrics query http_requests_total
-
-# Export metrics
-proagents metrics export --format prometheus > metrics.txt
-
-# Test metrics endpoint
-proagents metrics test
-
-# Generate metric documentation
-proagents metrics docs
-```
-
----
-
-## Best Practices
-
-1. **Use Standard Names**: Follow naming conventions (e.g., Prometheus)
-2. **Label Carefully**: High cardinality labels are expensive
-3. **Histogram Over Summary**: Histograms are more flexible
-4. **Include Units**: Add units to metric names (e.g., `_seconds`, `_bytes`)
-5. **Document Metrics**: Add descriptions and usage examples
-6. **Alert on Symptoms**: Alert on user-facing metrics first

package/.proagents/multi-project/README.md

@@ -1,170 +0,0 @@
-# Multi-Project & Monorepo Support
-
-Manage multiple related projects and monorepos with unified workflows.
-
----
-
-## Overview
-
-ProAgents supports managing multiple projects together, whether in a monorepo or as separate related projects.
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Multi-Project Architecture                │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  Workspace                                                  │
-│  ├── Shared Config ──────────────────────────────────────  │
-│  │   └── Common standards, rules, and templates            │
-│  │                                                          │
-│  ├── Projects ───────────────────────────────────────────  │
-│  │   ├── frontend/      (React web app)                    │
-│  │   ├── backend/       (Node.js API)                      │
-│  │   ├── mobile/        (React Native)                     │
-│  │   └── shared/        (Common libraries)                 │
-│  │                                                          │
-│  └── Cross-Project Features ─────────────────────────────  │
-│      ├── Dependency tracking                               │
-│      ├── Unified changelog                                 │
-│      └── Coordinated deployments                           │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Quick Start
-
-### Initialize Workspace
-
-```bash
-# Create workspace configuration
-proagents workspace init
-
-# Add existing projects
-proagents workspace add ./frontend --type web-frontend
-proagents workspace add ./backend --type nodejs
-proagents workspace add ./mobile --type react-native
-```
-
-### Configure Workspace
-
-```yaml
-# proagents.workspace.yaml
-
-workspace:
-  name: "My Platform"
-
-  projects:
-    - name: frontend
-      path: ./frontend
-      type: web-frontend
-
-    - name: backend
-      path: ./backend
-      type: nodejs
-
-    - name: mobile
-      path: ./mobile
-      type: react-native
-
-  shared:
-    standards: ./shared/.proagents/standards/
-    rules: ./shared/.proagents/rules/
-```
-
----
-
-## Use Cases
-
-| Scenario | Solution |
-|----------|----------|
-| Monorepo with multiple apps | Single workspace, multiple projects |
-| Microservices architecture | Linked workspaces with dependencies |
-| Frontend + Backend | Two projects with API contract sync |
-| Multi-platform app | Web, mobile, desktop as linked projects |
-
----
-
-## Features
-
-| Feature | Description |
-|---------|-------------|
-| **Unified Config** | Share standards and rules across projects |
-| **Cross-Project Dependencies** | Track dependencies between projects |
-| **Coordinated Deployments** | Deploy in correct order |
-| **Unified Changelog** | Single changelog for all projects |
-| **Shared Analysis** | Reuse codebase analysis |
-
----
-
-## Documentation Files
-
-| File | Description |
-|------|-------------|
-| [workspace-config.md](./workspace-config.md) | Workspace configuration |
-| [cross-project-deps.md](./cross-project-deps.md) | Cross-project dependencies |
-| [unified-changelog.md](./unified-changelog.md) | Unified changelog management |
-| [coordinated-deploy.md](./coordinated-deploy.md) | Coordinated deployments |
-
-## Walkthroughs
-
-| Walkthrough | Description |
-|-------------|-------------|
-| [Monorepo Setup](./walkthroughs/monorepo-setup.md) | Complete step-by-step monorepo setup guide |
-
----
-
-## Workspace Structure
-
-### Monorepo Layout
-
-```
-/workspace/
-├── proagents.workspace.yaml     # Workspace configuration
-├── shared/
-│   ├── .proagents/               # Shared ProAgents config
-│   │   ├── standards/
-│   │   ├── rules/
-│   │   └── templates/
-│   └── packages/                # Shared code packages
-│       ├── ui-components/
-│       └── utils/
-├── apps/
-│   ├── web/
-│   │   └── .proagents/           # Project-specific config
-│   ├── api/
-│   │   └── .proagents/
-│   └── mobile/
-│       └── .proagents/
-└── .proagents/                  # Workspace-level data
-    ├── cross-project-deps.json
-    ├── unified-changelog/
-    └── workspace-state.json
-```
-
-### Separate Repos Layout
-
-```
-/company-projects/
-├── proagents.workspace.yaml     # Links all repos
-├── frontend-repo/               # Separate git repo
-│   └── .proagents/
-├── backend-repo/                # Separate git repo
-│   └── .proagents/
-└── mobile-repo/                 # Separate git repo
-    └── .proagents/
-```
-
----
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `proagents workspace init` | Initialize workspace |
-| `proagents workspace add` | Add project to workspace |
-| `proagents workspace status` | Show workspace status |
-| `proagents workspace deps` | Show dependencies |
-| `proagents workspace sync` | Sync shared config |
-| `proagents workspace deploy` | Coordinated deploy |