proagents 1.6.17 → 1.6.19

package/.proagents/i18n/validation.md

@@ -1,355 +0,0 @@
-# Translation Validation
-
-Quality checks and validation rules for translations.
-
----
-
-## Validation Overview
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                  Validation Pipeline                         │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  Source String          Translation                         │
-│  ┌─────────────┐        ┌─────────────┐                    │
-│  │ "Hello,     │        │ "Hola,      │                    │
-│  │  {{name}}!" │   →    │  {{name}}!" │                    │
-│  └──────┬──────┘        └──────┬──────┘                    │
-│         │                      │                            │
-│         └──────────┬───────────┘                            │
-│                    │                                        │
-│                    ▼                                        │
-│         ┌─────────────────────┐                            │
-│         │     Validators      │                            │
-│         ├─────────────────────┤                            │
-│         │ ✓ Placeholders      │                            │
-│         │ ✓ Formatting        │                            │
-│         │ ✓ Length            │                            │
-│         │ ✓ Glossary          │                            │
-│         │ ✓ Plurals           │                            │
-│         └─────────────────────┘                            │
-│                    │                                        │
-│              [PASS/FAIL]                                   │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Validation Rules
-
-### Placeholder Validation
-
-```yaml
-i18n:
-  validation:
-    placeholders:
-      enabled: true
-      severity: "error"
-
-      rules:
-        # All source placeholders must exist in translation
-        missing: "error"
-
-        # Extra placeholders not in source
-        extra: "warning"
-
-        # Placeholder format must match
-        format_mismatch: "error"
-
-      # Placeholder patterns
-      patterns:
-        - "{{\\w+}}"           # {{name}}
-        - "%[sd]"              # %s, %d
-        - "\\{\\d+\\}"         # {0}, {1}
-```
-
-### Length Validation
-
-```yaml
-i18n:
-  validation:
-    length:
-      enabled: true
-      severity: "warning"
-
-      rules:
-        # Maximum expansion allowed
-        max_expansion: 1.5  # Translation can be 50% longer
-
-        # Minimum length (catch empty translations)
-        min_length: 1
-
-        # Per-context limits
-        contexts:
-          button:
-            max_chars: 20
-          title:
-            max_chars: 50
-          description:
-            max_chars: 200
-```
-
-### Formatting Validation
-
-```yaml
-i18n:
-  validation:
-    formatting:
-      enabled: true
-
-      rules:
-        # HTML tags must match
-        html_tags:
-          enabled: true
-          severity: "error"
-
-        # Markdown must be preserved
-        markdown:
-          enabled: true
-          severity: "warning"
-
-        # Line breaks
-        line_breaks:
-          preserve: true
-          severity: "warning"
-
-        # Leading/trailing whitespace
-        whitespace:
-          check: true
-          severity: "info"
-```
-
-### Glossary Validation
-
-```yaml
-i18n:
-  validation:
-    glossary:
-      enabled: true
-      severity: "warning"
-
-      # Glossary file
-      file: "i18n/glossary.csv"
-
-      rules:
-        # Terms must be translated consistently
-        consistency: true
-
-        # Terms must not be translated (brand names)
-        do_not_translate:
-          - "ProAgents"
-          - "GitHub"
-          - "API"
-```
-
-### Plural Validation
-
-```yaml
-i18n:
-  validation:
-    plurals:
-      enabled: true
-      severity: "error"
-
-      rules:
-        # All plural forms required
-        all_forms_required: true
-
-        # Forms per language
-        forms:
-          en: ["one", "other"]
-          ru: ["one", "few", "many", "other"]
-          ar: ["zero", "one", "two", "few", "many", "other"]
-          zh: ["other"]  # No plurals
-```
-
----
-
-## Running Validation
-
-### Command Line
-
-```bash
-# Validate all translations
-proagents i18n validate
-
-# Validate specific language
-proagents i18n validate --lang es
-
-# Validate specific file
-proagents i18n validate --file src/locales/es/common.json
-
-# Output format
-proagents i18n validate --format json
-```
-
-### Validation Output
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ Translation Validation Results                              │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│ Validated: 5 languages, 450 keys                           │
-│                                                             │
-│ Errors (3):                                                 │
-│ ┌─────────────────────────────────────────────────────────┐│
-│ │ es/common.json:greeting                                 ││
-│ │ Missing placeholder: {{name}}                           ││
-│ │ Source: "Hello, {{name}}!"                              ││
-│ │ Translation: "¡Hola!"                                   ││
-│ └─────────────────────────────────────────────────────────┘│
-│ ┌─────────────────────────────────────────────────────────┐│
-│ │ fr/errors.json:validation_error                         ││
-│ │ Mismatched HTML tags                                    ││
-│ │ Source: "<strong>Error:</strong> {{message}}"           ││
-│ │ Translation: "<b>Erreur:</b> {{message}}"               ││
-│ └─────────────────────────────────────────────────────────┘│
-│                                                             │
-│ Warnings (5):                                               │
-│ • de/common.json:long_text - exceeds 150% expansion        │
-│ • ja/ui.json:button_submit - exceeds 20 char limit         │
-│ • ... 3 more                                               │
-│                                                             │
-│ Result: FAILED (3 errors, 5 warnings)                      │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## CI Integration
-
-### Pre-Commit Hook
-
-```yaml
-# .proagents/hooks/pre-commit
-i18n:
-  validation:
-    hooks:
-      pre_commit:
-        enabled: true
-        fail_on: "error"
-        languages: "all"
-```
-
-### CI Pipeline
-
-```yaml
-# GitHub Actions
-name: i18n Validation
-
-on:
-  pull_request:
-    paths:
-      - 'src/locales/**'
-
-jobs:
-  validate:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Validate translations
-        run: proagents i18n validate --ci --fail-on error
-
-      - name: Upload report
-        uses: actions/upload-artifact@v3
-        with:
-          name: i18n-validation-report
-          path: i18n-validation.json
-```
-
-### Block Merge
-
-```yaml
-i18n:
-  validation:
-    ci:
-      # Block PR merge on
-      block_on:
-        errors: true
-        warnings: false
-
-      # Required checks
-      required_checks:
-        - "placeholder_validation"
-        - "plural_validation"
-```
-
----
-
-## Custom Validators
-
-### Define Custom Rule
-
-```yaml
-i18n:
-  validation:
-    custom:
-      # No profanity
-      - name: "no_profanity"
-        type: "regex"
-        pattern: "\\b(badword1|badword2)\\b"
-        severity: "error"
-        message: "Translation contains inappropriate language"
-
-      # Brand name capitalization
-      - name: "brand_caps"
-        type: "regex"
-        pattern: "proagents"
-        severity: "warning"
-        message: "Brand name should be 'ProAgents'"
-
-      # Custom script
-      - name: "custom_check"
-        type: "script"
-        script: "scripts/validate-i18n.js"
-        severity: "error"
-```
-
----
-
-## Auto-Fix
-
-### Fixable Issues
-
-```yaml
-i18n:
-  validation:
-    auto_fix:
-      enabled: true
-
-      # What can be auto-fixed
-      fixable:
-        - "trailing_whitespace"
-        - "leading_whitespace"
-        - "double_spaces"
-        - "smart_quotes"  # Convert to standard quotes
-
-      # Confirmation
-      confirm: true
-```
-
-### Fix Command
-
-```bash
-# Auto-fix issues
-proagents i18n validate --fix
-
-# Preview fixes
-proagents i18n validate --fix --dry-run
-```
-
----
-
-## Best Practices
-
-1. **Run in CI**: Validate on every PR
-2. **Block on Errors**: Don't merge with validation errors
-3. **Use Glossary**: Ensure consistent terminology
-4. **Check Plurals**: Verify all plural forms
-5. **Test UI**: Visual testing catches length issues
-6. **Review Warnings**: Don't ignore warnings

package/.proagents/logging/README.md

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