proagents 1.0.0

package/proagents/learning/reports.md

@@ -0,0 +1,306 @@
+# Learning Reports
+
+Progress reports showing how ProAgents has improved over time.
+
+---
+
+## Report Types
+
+### 1. Weekly Learning Report
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ ProAgents Learning Report - Week of Jan 15, 2024                │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ SUMMARY                                                         │
+│ ───────                                                         │
+│ Features Completed: 5                                           │
+│ Total Development Time: 18 hours                                │
+│ Time Saved by Learning: ~2.5 hours (estimated)                 │
+│                                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ NEW PATTERNS LEARNED                                            │
+│ ────────────────────                                            │
+│ • Component structure pattern (confidence: 95%)                │
+│ • API error handling pattern (confidence: 88%)                 │
+│ • Test file organization (confidence: 92%)                     │
+│                                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ AUTO-CORRECTIONS APPLIED                                        │
+│ ────────────────────────                                        │
+│ • "Use Zustand" applied 8 times                                │
+│ • "Functional components" applied 12 times                     │
+│ • "Colocate tests" applied 6 times                             │
+│                                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ CHECKPOINT OPTIMIZATIONS                                        │
+│ ────────────────────────                                        │
+│ • Skipped 15 unnecessary checkpoints                           │
+│ • Estimated time saved: 45 minutes                             │
+│                                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ DECISION ACCURACY                                               │
+│ ─────────────────                                               │
+│ Auto-decisions made: 45                                         │
+│ ├── Accepted without change: 42 (93%)                          │
+│ ├── Minor adjustments: 2 (4%)                                  │
+│ └── Required correction: 1 (3%)                                │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### 2. Monthly Progress Report
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ ProAgents Monthly Progress - January 2024                       │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ PRODUCTIVITY METRICS                                            │
+│ ────────────────────                                            │
+│                                                                 │
+│ Features Completed     ████████████████████ 20                 │
+│ Bugs Fixed             ████████████ 12                          │
+│ Quick Changes          ██████████████████████████ 35           │
+│                                                                 │
+│ Average Feature Time: 3.2 hours (↓ 25% from first month)       │
+│ Average Bug Fix Time: 35 minutes (↓ 30% from first month)      │
+│                                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ LEARNING GROWTH                                                 │
+│ ───────────────                                                 │
+│                                                                 │
+│ Patterns Learned:                                               │
+│ Week 1  ████████ 8                                              │
+│ Week 2  ████████████ 12                                         │
+│ Week 3  ██████████ 10                                           │
+│ Week 4  ██████ 6 (stabilizing)                                  │
+│                                                                 │
+│ Total Active Patterns: 36                                       │
+│ Pattern Confidence: 89% average                                │
+│                                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ TIME SAVINGS                                                    │
+│ ────────────                                                    │
+│                                                                 │
+│ Auto-corrections saved:     ~4 hours                           │
+│ Checkpoint skips saved:     ~3 hours                           │
+│ Pattern following saved:    ~5 hours                           │
+│ Decision automation saved:  ~2 hours                           │
+│ ─────────────────────────────────────                          │
+│ Total Estimated Savings:    ~14 hours                          │
+│                                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ CORRECTION TRENDS                                               │
+│ ─────────────────                                               │
+│                                                                 │
+│ Corrections Needed:                                             │
+│ Week 1  ████████████████ 16                                     │
+│ Week 2  ████████████ 12                                         │
+│ Week 3  ████████ 8                                              │
+│ Week 4  ████ 4                                                  │
+│                                                                 │
+│ Trend: ↓ 75% reduction in corrections needed                   │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### 3. Pattern Confidence Report
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Pattern Confidence Report                                       │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ HIGH CONFIDENCE (90%+) - Auto-applied                          │
+│ ─────────────────────────────────────                          │
+│ • Component style: functional          ████████████████ 98%    │
+│ • State management: zustand            ████████████████ 96%    │
+│ • File structure: feature-based        ███████████████ 95%     │
+│ • Styling: tailwind                    ███████████████ 94%     │
+│ • Testing: vitest + testing-library    ███████████████ 93%     │
+│                                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ MEDIUM CONFIDENCE (70-89%) - Suggested                         │
+│ ──────────────────────────────────────                         │
+│ • Error handling: error boundaries     ██████████████ 85%      │
+│ • API calls: react-query hooks         █████████████ 82%       │
+│ • Form handling: react-hook-form       ████████████ 78%        │
+│ • Animation: framer-motion             ███████████ 72%         │
+│                                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ LEARNING (Below 70%) - Still gathering data                    │
+│ ───────────────────────────────────────────                    │
+│ • Caching strategy                     ████████ 55%            │
+│ • WebSocket patterns                   ██████ 45%              │
+│ • Pagination approach                  █████ 40%               │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### 4. Decision Accuracy Report
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Decision Accuracy Report - Last 30 Days                         │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ OVERALL ACCURACY: 94%                                           │
+│                                                                 │
+│ BY CATEGORY                                                     │
+│ ───────────                                                     │
+│                                                                 │
+│ Architecture Decisions                                          │
+│ ├── Total: 25                                                  │
+│ ├── Correct: 24 (96%)                                          │
+│ └── Corrected: 1 (4%)                                          │
+│                                                                 │
+│ Code Style Decisions                                            │
+│ ├── Total: 120                                                 │
+│ ├── Correct: 115 (96%)                                         │
+│ └── Corrected: 5 (4%)                                          │
+│                                                                 │
+│ File Location Decisions                                         │
+│ ├── Total: 45                                                  │
+│ ├── Correct: 42 (93%)                                          │
+│ └── Corrected: 3 (7%)                                          │
+│                                                                 │
+│ Implementation Approach                                         │
+│ ├── Total: 30                                                  │
+│ ├── Correct: 27 (90%)                                          │
+│ └── Corrected: 3 (10%)                                         │
+│                                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ IMPROVEMENT TREND                                               │
+│ ─────────────────                                               │
+│                                                                 │
+│ Month 1: 78% accuracy                                          │
+│ Month 2: 87% accuracy (+9%)                                    │
+│ Month 3: 94% accuracy (+7%)                                    │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Report Generation
+
+### Automatic Reports
+
+```yaml
+reports:
+  automatic:
+    weekly:
+      enabled: true
+      day: "monday"
+      notify: true
+
+    monthly:
+      enabled: true
+      day: 1
+      notify: true
+
+  location: ".proagents/reports/"
+  format: "markdown"  # markdown | html | json
+```
+
+### On-Demand Reports
+
+```bash
+# Generate reports via slash commands
+/report-learning weekly
+/report-learning monthly
+/report-learning patterns
+/report-learning decisions
+/report-learning all
+```
+
+---
+
+## Report Export
+
+```yaml
+export:
+  formats:
+    - markdown
+    - html
+    - pdf
+    - json
+
+  destinations:
+    - local: ".proagents/reports/"
+    - notion: false  # If Notion integration enabled
+    - slack: false   # If Slack integration enabled
+```
+
+---
+
+## Insights & Recommendations
+
+Reports include actionable insights:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ INSIGHTS & RECOMMENDATIONS                                      │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ 💡 INSIGHTS                                                     │
+│                                                                 │
+│ 1. Your component patterns are highly consistent (98%)         │
+│    → ProAgents can now auto-generate components with           │
+│      high confidence                                           │
+│                                                                 │
+│ 2. Test file organization varies between features              │
+│    → Consider standardizing to improve pattern learning        │
+│                                                                 │
+│ 3. API error handling has 3 different patterns                 │
+│    → Consolidating would improve auto-decisions                │
+│                                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ 📋 RECOMMENDATIONS                                              │
+│                                                                 │
+│ 1. Consider disabling "after_testing" checkpoint               │
+│    → You've skipped it 95% of the time                        │
+│    → Run: /config set checkpoints.after_testing false         │
+│                                                                 │
+│ 2. Document your preferred caching strategy                    │
+│    → Only 45% confidence, frequently corrected                │
+│    → Add to: proagents/standards/architecture-rules.md        │
+│                                                                 │
+│ 3. Your features are getting faster to complete!               │
+│    → Average time down 25% from first month                   │
+│    → Keep using consistent patterns                           │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/report-learning` | Show learning summary |
+| `/report-learning weekly` | Generate weekly report |
+| `/report-learning monthly` | Generate monthly report |
+| `/report-patterns` | Pattern confidence report |
+| `/report-decisions` | Decision accuracy report |
+| `/report-export [format]` | Export reports |

package/proagents/logging/README.md

@@ -0,0 +1,276 @@
+# Logging Best Practices
+
+Structured logging for debugging, monitoring, and compliance.
+
+---
+
+## Overview
+
+Consistent, structured logging that supports debugging, monitoring, and audit requirements.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Log Levels](./log-levels.md) | When to use each level |
+| [Structured Logging](./structured-logging.md) | JSON log format |
+| [Log Aggregation](./aggregation.md) | Centralized logging |
+| [Sensitive Data](./sensitive-data.md) | Protecting PII in logs |
+
+---
+
+## Log Levels
+
+| Level | When to Use | Example |
+|-------|-------------|---------|
+| `error` | Application errors requiring attention | Database connection failed |
+| `warn` | Unexpected but handled situations | Retry attempt, deprecation |
+| `info` | Normal operations, milestones | Request completed, user logged in |
+| `debug` | Detailed debugging information | Variable values, flow tracking |
+| `trace` | Very detailed tracing | Function entry/exit |
+
+---
+
+## Structured Logging
+
+### JSON Log Format
+
+```typescript
+// src/utils/logger.ts
+import pino from 'pino';
+
+export const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  formatters: {
+    level: (label) => ({ level: label }),
+  },
+  timestamp: () => `,"timestamp":"${new Date().toISOString()}"`,
+});
+
+// Usage
+logger.info({
+  event: 'user_login',
+  userId: user.id,
+  ip: req.ip,
+  userAgent: req.headers['user-agent'],
+});
+```
+
+### Log Output
+
+```json
+{
+  "level": "info",
+  "timestamp": "2024-01-15T10:30:00.000Z",
+  "event": "user_login",
+  "userId": "user-123",
+  "ip": "192.168.1.1",
+  "userAgent": "Mozilla/5.0..."
+}
+```
+
+---
+
+## Request Logging
+
+### HTTP Request Logger
+
+```typescript
+// src/middleware/request-logger.ts
+export function requestLogger(req, res, next) {
+  const start = Date.now();
+
+  res.on('finish', () => {
+    const duration = Date.now() - start;
+
+    logger.info({
+      event: 'http_request',
+      method: req.method,
+      path: req.path,
+      statusCode: res.statusCode,
+      duration,
+      requestId: req.id,
+      userId: req.user?.id,
+    });
+  });
+
+  next();
+}
+```
+
+### Request ID Tracking
+
+```typescript
+// Add unique ID to each request
+import { v4 as uuid } from 'uuid';
+
+app.use((req, res, next) => {
+  req.id = req.headers['x-request-id'] || uuid();
+  res.setHeader('x-request-id', req.id);
+  next();
+});
+```
+
+---
+
+## Configuration
+
+```yaml
+# proagents.config.yaml
+logging:
+  level: "info"  # error, warn, info, debug, trace
+
+  format: "json"  # json, pretty
+
+  # Include in all logs
+  default_fields:
+    service: "my-app"
+    version: "${APP_VERSION}"
+    environment: "${NODE_ENV}"
+
+  # Output destinations
+  outputs:
+    - type: "stdout"
+    - type: "file"
+      path: "logs/app.log"
+      rotate: "daily"
+
+  # Aggregation
+  aggregation:
+    provider: "datadog"  # datadog, cloudwatch, elasticsearch
+```
+
+---
+
+## Log Aggregation
+
+### Send to Aggregator
+
+```typescript
+// DataDog example
+import { createLogger, format, transports } from 'winston';
+
+const logger = createLogger({
+  transports: [
+    new transports.Console(),
+    new transports.Http({
+      host: 'http-intake.logs.datadoghq.com',
+      path: `/api/v2/logs?dd-api-key=${process.env.DD_API_KEY}`,
+      ssl: true,
+    }),
+  ],
+});
+```
+
+### Log Search
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Log Search: service:my-app level:error                      │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│ 10:30:15 ERROR Database connection failed                   │
+│          requestId: abc-123                                 │
+│          error: ECONNREFUSED                                │
+│          host: db.example.com                               │
+│                                                             │
+│ 10:28:42 ERROR Payment processing failed                    │
+│          requestId: def-456                                 │
+│          userId: user-789                                   │
+│          error: Card declined                               │
+│                                                             │
+│ 10:25:10 ERROR API rate limit exceeded                      │
+│          requestId: ghi-789                                 │
+│          endpoint: /api/users                               │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Sensitive Data Protection
+
+### What NOT to Log
+
+```typescript
+// ❌ Never log these
+logger.info({ password: user.password });  // Credentials
+logger.info({ ssn: user.ssn });            // PII
+logger.info({ creditCard: payment.card }); // Financial
+logger.info({ token: auth.token });        // Secrets
+
+// ✅ Safe alternatives
+logger.info({ userId: user.id });
+logger.info({ last4: payment.card.slice(-4) });
+```
+
+### Automatic Redaction
+
+```typescript
+const logger = pino({
+  redact: {
+    paths: [
+      'password',
+      'secret',
+      'token',
+      '*.password',
+      'user.email',
+      'creditCard',
+    ],
+    censor: '[REDACTED]',
+  },
+});
+
+// Input
+logger.info({ user: { email: 'user@example.com', password: 'secret123' } });
+
+// Output
+{ "user": { "email": "[REDACTED]", "password": "[REDACTED]" } }
+```
+
+---
+
+## Performance Logging
+
+### Timing Operations
+
+```typescript
+// Track operation duration
+async function processOrder(orderId: string) {
+  const start = Date.now();
+
+  try {
+    const result = await doProcessing(orderId);
+
+    logger.info({
+      event: 'order_processed',
+      orderId,
+      duration: Date.now() - start,
+      status: 'success',
+    });
+
+    return result;
+  } catch (error) {
+    logger.error({
+      event: 'order_processing_failed',
+      orderId,
+      duration: Date.now() - start,
+      error: error.message,
+    });
+    throw error;
+  }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Use Structured Logs**: JSON format for machine parsing
+2. **Include Request IDs**: Trace requests across services
+3. **Log at Right Level**: Don't overuse error/debug
+4. **Add Context**: Include relevant business context
+5. **Protect Sensitive Data**: Redact PII and secrets
+6. **Aggregate Logs**: Use centralized logging
+7. **Monitor Log Volume**: High volume may indicate issues
+8. **Rotate Log Files**: Prevent disk exhaustion