code-ai-installer 1.3.0 → 1.4.0

package/locales/en/.agents/skills/observability_plan/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: observability_plan
+description: Observability plan — what logs/metrics/traces to collect, request correlation, log levels, alerts. Without leaking PII/secrets.
+---
+
+# Skill: Observability Plan
+
+Architectural observability plan: what to log, what to measure, when to alert.
+
+**Sections:**
+1. [Logging Plan](#1-logging)
+2. [Metrics Plan](#2-metrics)
+3. [Alerting Plan](#3-alerting)
+4. [Tracing](#4-tracing)
+5. [UX Error Mapping](#5-ux-mapping)
+6. [Dashboard Layout](#6-dashboard)
+7. [Example](#7-example)
+8. [Output Template](#8-output)
+
+---
+
+## 1. Logging Plan
+
+### Log Events Registry
+
+| Event | Level | When | Fields | Example message |
+|-------|-------|------|--------|----------------|
+| `server_started` | info | App startup | port, env, version | "Server started" |
+| `server_shutdown` | info | Graceful shutdown | reason, uptime | "Server shutting down" |
+| `http_request` | info | Every request (finish) | method, url, status, durationMs, requestId | "HTTP request" |
+| `slow_request` | warn | durationMs > 2000 | method, url, durationMs | "Slow request detected" |
+| `item_created` | info | POST /items success | itemId, ownerId | "Item created" |
+| `item_duplicate` | warn | POST /items 409 | name, ownerId | "Duplicate item" |
+| `settings_updated` | info | PUT /settings success | ownerId, changedFields | "Settings updated" |
+| `webhook_received` | info | Webhook received | eventType, sourceId | "Processing webhook" |
+| `content_served` | info | Public content served | contentId, durationMs | "Content served" |
+| `content_not_found` | warn | GET /content/:id 404 | contentId | "Content not found" |
+| `validation_error` | warn | Input validation failed | endpoint, fields, requestId | "Validation failed" |
+| `auth_failed` | warn | Auth check failed | endpoint, reason, ip | "Authentication failed" |
+| `db_error` | error | DB operation failed | operation, err | "Database error" |
+| `db_connected` | info | DB connection established | host, dbName | "MongoDB connected" |
+| `db_disconnected` | warn | DB connection lost | — | "MongoDB disconnected" |
+| `unhandled_error` | error | Uncaught exception | err, requestId | "Unhandled error" |
+
+### Correlation
+
+```
+Every request gets:
+  requestId: UUID (from X-Request-ID header or generated)
+  → Attached to child logger: req.log = logger.child({ requestId })
+  → All logs in request chain include requestId automatically
+  → Propagated to external calls via X-Request-ID header
+```
+
+### Log levels by environment
+
+| Env | Level | Reason |
+|-----|-------|--------|
+| Production | `info` | Business events + errors |
+| Staging | `debug` | Debugging without overload |
+| Development | `debug` | Full visibility |
+| Test | `silent` | Don't clutter test output |
+
+### PII/Secrets — never log
+
+| Field | Rule |
+|-------|------|
+| `password` | pino redact |
+| `token` / `secret` / `apiKey` | pino redact |
+| `authorization` header | pino redact |
+| `cookie` header | pino redact |
+| `email` | mask: `a****@example.com` |
+| `creditCard` | pino redact |
+| Connection string | pino redact `DATABASE_URL` |
+
+---
+
+## 2. Metrics Plan
+
+### Key Metrics
+
+| Metric | Type | Labels | Purpose |
+|--------|------|--------|---------|
+| `http_requests_total` | Counter | method, route, status | Request volume |
+| `http_request_duration_seconds` | Histogram | method, route, status | Latency (p50/p95/p99) |
+| `http_errors_total` | Counter | method, route, status | Error rate |
+| `db_query_duration_seconds` | Histogram | operation, collection | DB performance |
+| `db_connections_active` | Gauge | — | Connection pool usage |
+| `content_requests_total` | Counter | status | Public content traffic |
+| `webhook_processed_total` | Counter | type, status | Webhook processing |
+
+### Latency targets
+
+| Endpoint | p50 | p95 | p99 | Alert threshold (p95) |
+|----------|-----|-----|-----|-----------------------|
+| GET /content/:id | 10ms | 50ms | 100ms | > 200ms |
+| PUT /settings | 20ms | 100ms | 500ms | > 1000ms |
+| POST /items | 20ms | 100ms | 500ms | > 1000ms |
+| POST /webhooks | 50ms | 500ms | 2000ms | > 5000ms |
+
+---
+
+## 3. Alerting Plan
+
+### Alert Rules
+
+| Alert | Condition | Severity | Channel | Response |
+|-------|-----------|----------|---------|----------|
+| **High error rate** | 5xx > 5% of requests (5 min window) | 🔴 Critical | Slack/PagerDuty | Check logs, identify failing endpoint |
+| **Latency spike** | p95 > 2x target (5 min window) | 🟠 Warning | Slack | Check DB performance, slow queries |
+| **DB down** | Health check /ready fails 3 consecutive | 🔴 Critical | Slack/PagerDuty | Check MongoDB, restart if needed |
+| **Webhook failures** | Webhook processing fail > 3/hour | 🟠 Warning | Slack | Check external API, retry manually |
+| **Disk space** | > 85% used | 🟠 Warning | Slack | Clean logs, expand volume |
+| **No traffic** | 0 requests for 10 min (production) | 🟠 Warning | Slack | Check gateway, DNS, upstream services |
+
+### Silence rules
+
+| Condition | Silence |
+|-----------|---------|
+| Deployment in progress | 10 min after deploy |
+| Planned maintenance | Duration of maintenance window |
+| Known upstream outage | Until resolved |
+
+---
+
+## 4. Tracing
+
+### Span structure (if implementing distributed tracing)
+
+```
+[HTTP Request] ← parent span
+  ├── [Auth Check]
+  ├── [Validation]
+  ├── [Service Call]
+  │   ├── [DB Query: findOne]
+  │   └── [DB Query: updateOne]
+  └── [Response Serialization]
+```
+
+### MVP approach (without full tracing infra)
+
+For MVP, structured logs with `requestId` correlation provide 80% of tracing value:
+
+```
+# Find all logs for a specific request:
+grep "requestId":"abc-123" app.log
+
+# Trace request flow:
+13:00:01 INFO  requestId=abc-123 msg="HTTP request started" method=PUT url=/api/v1/settings/app-1
+13:00:01 DEBUG requestId=abc-123 msg="Validation passed"
+13:00:01 DEBUG requestId=abc-123 msg="DB query" operation=updateOne durationMs=5
+13:00:01 INFO  requestId=abc-123 msg="HTTP request" status=200 durationMs=12
+```
+
+---
+
+## 5. UX Error Mapping
+
+### API errors → UI states
+
+| API Error | HTTP | UI State | User sees |
+|-----------|------|----------|-----------|
+| Validation | 400 | Form error | Red field borders + messages |
+| Not Found | 404 | Empty state | "Not found" illustration |
+| Duplicate | 409 | Form error | "Code already exists" |
+| Auth | 401 | Redirect | Login page / re-auth |
+| Forbidden | 403 | Error state | "Access denied" |
+| Rate limit | 429 | Toast | "Too many requests, try later" |
+| Server error | 500 | Error state | "Something went wrong" + retry button |
+| Widget 404 | 404 | No render | Embedded script silently fails (no popup) |
+| Widget 500 | 500 | No render | Embedded script silently fails |
+
+### Rule: Embedded script NEVER shows errors to visitors
+
+```
+Widget errors → console.error('[App] ...') → no UI
+Dashboard errors → toast or inline error → clear user message
+```
+
+---
+
+## 6. Dashboard Layout
+
+### Recommended observability dashboard sections
+
+```
+┌─────────────────────────────────────────────┐
+│               OVERVIEW                       │
+│  Request Rate ▏ Error Rate ▏ p95 Latency    │
+│  [sparkline]  ▏ [sparkline]▏ [sparkline]    │
+├─────────────────────────────────────────────┤
+│               ENDPOINTS                      │
+│  Table: route, requests, errors, p95, p99   │
+├─────────────────────────────────────────────┤
+│               ERRORS                         │
+│  Top errors by: code, endpoint, message     │
+├─────────────────────────────────────────────┤
+│               DATABASE                       │
+│  Query duration ▏ Connections ▏ Slow queries │
+├─────────────────────────────────────────────┤
+│               INTEGRATIONS                   │
+│  External API: success/fail │ Webhook: rate   │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## 7. Example
+
+```markdown
+# Observability Plan: SaaS Admin Panel
+
+## Logging
+- Structured JSON (pino), level: info (prod), debug (dev)
+- requestId correlation on all requests
+- Redact: authorization, password, token, cookie, DATABASE_URL
+
+## Key Metrics
+- http_requests_total (method, route, status)
+- http_request_duration_seconds (p50, p95, p99)
+- Public content serve rate + latency
+- Webhook processing rate + success/fail
+
+## Alerts
+- 🔴 Error rate > 5% → immediate
+- 🔴 DB health check fail → immediate
+- 🟠 p95 latency > 2x target → investigation
+- 🟠 Webhook fail > 3/hour → manual retry
+
+## UX Error Mapping
+- Dashboard: toast/inline errors with clear messages
+- Public content: graceful fallback (no error UI)
+```
+
+---
+
+## 8. Output Template
+
+```markdown
+# Observability Plan: <project-name>
+
+**Date:** YYYY-MM-DD
+
+## Logging
+### Events Registry
+<section 1 event table>
+
+### Correlation
+<requestId strategy>
+
+### Redaction
+<PII/secrets list>
+
+## Metrics
+<section 2 metrics table + latency targets>
+
+## Alerting
+<section 3 alert rules>
+
+## Tracing
+<section 4 strategy>
+
+## UX Error Mapping
+<section 5 table>
+
+## Dashboard
+<section 6 layout>
+```
+
+---
+
+## See also
+- `$observability_logging` — implementation (pino setup, middleware, redaction code)
+- `$architecture_doc` — Architecture Document (observability section)
+- `$api_contracts` — error codes (map to UI states)
+- `$threat_model_baseline` — audit logging requirements

package/locales/en/.agents/skills/observability_plan/agents/claude.json

@@ -0,0 +1,17 @@
+{
+  "name": "observability_plan",
+  "display_name": "Observability Plan",
+  "description": "Create an observability plan - logs, metrics, traces, request correlation, log levels, alerts, and no PII or secret leakage.",
+  "default_prompt": "Use $observability_plan when the task matches the \"Observability Plan\" skill.",
+  "triggers": [
+    "observability_plan",
+    "observability plan",
+    "Create an observability plan - logs, metrics, traces, request correlation, log levels, alerts, and no PII or secret leakage"
+  ],
+  "capabilities": [
+    "observability",
+    "plan"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/locales/en/.agents/skills/observability_plan/agents/copilot.json

@@ -0,0 +1,17 @@
+{
+  "name": "observability_plan",
+  "display_name": "Observability Plan",
+  "description": "Create an observability plan - logs, metrics, traces, request correlation, log levels, alerts, and no PII or secret leakage.",
+  "default_prompt": "Use $observability_plan when the task matches the \"Observability Plan\" skill.",
+  "triggers": [
+    "observability_plan",
+    "observability plan",
+    "Create an observability plan - logs, metrics, traces, request correlation, log levels, alerts, and no PII or secret leakage"
+  ],
+  "capabilities": [
+    "observability",
+    "plan"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/locales/en/.agents/skills/observability_plan/agents/gemini.json

@@ -0,0 +1,17 @@
+{
+  "name": "observability_plan",
+  "display_name": "Observability Plan",
+  "description": "Create an observability plan - logs, metrics, traces, request correlation, log levels, alerts, and no PII or secret leakage.",
+  "default_prompt": "Use $observability_plan when the task matches the \"Observability Plan\" skill.",
+  "triggers": [
+    "observability_plan",
+    "observability plan",
+    "Create an observability plan - logs, metrics, traces, request correlation, log levels, alerts, and no PII or secret leakage"
+  ],
+  "capabilities": [
+    "observability",
+    "plan"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/locales/en/.agents/skills/observability_plan/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Observability Plan"
+  short_description: "Create an observability plan - logs, metrics, traces, request correlation, log levels, alerts,…"
+  default_prompt: "Use $observability_plan when the task matches the \"Observability Plan\" skill."
+dependencies:
+  tools: []
+policy:
+  allow_implicit_invocation: true

package/locales/en/.agents/skills/observability_plan/agents/qwen.json

@@ -0,0 +1,17 @@
+{
+  "name": "observability_plan",
+  "display_name": "Observability Plan",
+  "description": "Create an observability plan - logs, metrics, traces, request correlation, log levels, alerts, and no PII or secret leakage.",
+  "default_prompt": "Use $observability_plan when the task matches the \"Observability Plan\" skill.",
+  "triggers": [
+    "observability_plan",
+    "observability plan",
+    "Create an observability plan - logs, metrics, traces, request correlation, log levels, alerts, and no PII or secret leakage"
+  ],
+  "capabilities": [
+    "observability",
+    "plan"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/locales/en/.agents/skills/observability_plan/agents/skill.yaml

@@ -0,0 +1,21 @@
+version: 1
+name: "observability_plan"
+display_name: "Observability Plan"
+description: "Create an observability plan - logs, metrics, traces, request correlation, log levels, alerts, and no PII or secret leakage."
+default_prompt: "Use $observability_plan when the task matches the \"Observability Plan\" skill."
+triggers:
+  - "observability_plan"
+  - "observability plan"
+  - "Create an observability plan - logs, metrics, traces, request correlation, log levels, alerts, and no PII or secret leakage"
+capabilities:
+  - "observability"
+  - "plan"
+tools: []
+invocation:
+  explicit: true
+  implicit: true
+localization:
+  default_locale: "en"
+  available_locales:
+    - "ru"
+    - "en"

package/locales/en/.agents/skills/performance_review_baseline/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: performance_review_baseline
+description: Basic perf review — N+1, pagination, batches, redundant queries, cache by architecture, heavy operations in the request path.
+---
+
+# Skill: Performance Review Baseline
+
+Performance review without premature optimization — focus on real bottlenecks.
+
+**Sections:**
+1. [Checklist](#1-checklist)
+2. [DO / DON'T Examples](#2-examples)
+3. [Latency Targets](#3-latency)
+4. [Automated Detection](#4-detection)
+5. [Output Template](#5-output)
+
+---
+
+## 1. Checklist
+
+### 1.1 Database Queries
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| PERF-01 | No N+1 queries (loop of individual DB calls) | 🔴 P0 | ☐ |
+| PERF-02 | Indexes exist for all query patterns | 🟠 P1 | ☐ |
+| PERF-03 | `.select()` used — don't fetch unnecessary fields | 🟠 P1 | ☐ |
+| PERF-04 | `.lean()` used for read-only queries (Mongoose) | 🟡 P2 | ☐ |
+| PERF-05 | No unbounded queries (always limit/paginate) | 🔴 P0 | ☐ |
+| PERF-06 | Aggregation pipelines optimized (`$match` before `$lookup`) | 🟠 P1 | ☐ |
+
+### 1.2 API & Network
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| PERF-07 | No redundant round-trips (batch where possible) | 🟠 P1 | ☐ |
+| PERF-08 | Pagination on list endpoints | 🔴 P0 | ☐ |
+| PERF-09 | Response payload minimal (no over-fetching) | 🟠 P1 | ☐ |
+| PERF-10 | Heavy operations offloaded to async (queue/worker) | 🟠 P1 | ☐ |
+| PERF-11 | Compression enabled (gzip/brotli) for API responses | 🟡 P2 | ☐ |
+
+### 1.3 Frontend
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| PERF-12 | No unnecessary re-renders (React.memo, useMemo, useCallback where appropriate) | 🟠 P1 | ☐ |
+| PERF-13 | Images optimized (WebP, lazy loading, proper dimensions) | 🟠 P1 | ☐ |
+| PERF-14 | Bundle size reasonable (no giant imports like full lodash) | 🟠 P1 | ☐ |
+| PERF-15 | Code splitting / lazy routes for large apps | 🟡 P2 | ☐ |
+
+### 1.4 Caching
+
+| # | Check | Severity | Status |
+|---|-------|----------|--------|
+| PERF-16 | Cache applied where architecture allows (read-heavy, rarely changing) | 🟡 P2 | ☐ |
+| PERF-17 | Cache invalidation strategy defined | 🟠 P1 | ☐ |
+| PERF-18 | HTTP cache headers for static assets (Cache-Control, ETag) | 🟡 P2 | ☐ |
+
+---
+
+## 2. DO / DON'T Examples
+
+### N+1 Query Problem
+
+```javascript
+// ❌ DON'T: N+1 — one query per item in loop
+const coupons = await Coupon.find({ appInstanceId });
+for (const coupon of coupons) {
+  coupon.settings = await Settings.findOne({ couponId: coupon._id }); // N queries!
+}
+
+// ✅ DO: Single query with $in or $lookup
+const coupons = await Coupon.find({ appInstanceId });
+const couponIds = coupons.map(c => c._id);
+const settings = await Settings.find({ couponId: { $in: couponIds } }); // 1 query
+// Map settings to coupons in memory
+```
+
+### Unbounded Query
+
+```javascript
+// ❌ DON'T: Fetch ALL records
+const allCoupons = await Coupon.find({}); // Could be 100K records!
+
+// ✅ DO: Paginate
+const coupons = await Coupon.find({})
+  .sort({ createdAt: -1 })
+  .skip(page * limit)
+  .limit(limit)
+  .lean();
+```
+
+### Over-fetching
+
+```javascript
+// ❌ DON'T: Return entire document
+const settings = await Settings.findOne({ appInstanceId });
+res.json(settings); // Includes all internal fields
+
+// ✅ DO: Select only needed fields
+const settings = await Settings.findOne({ appInstanceId })
+  .select('templateId colors fonts timer coupon')
+  .lean();
+res.json({ data: settings });
+```
+
+### Sync Heavy Operation
+
+```javascript
+// ❌ DON'T: Heavy operation in request path
+router.post('/export', async (req, res) => {
+  const report = await generatePDFReport(allData); // 30 seconds!
+  res.json({ report });
+});
+
+// ✅ DO: Offload to async
+router.post('/export', async (req, res) => {
+  const jobId = await queue.add('generate-report', { userId: req.userId });
+  res.status(202).json({ jobId, status: 'processing' }); // Return immediately
+});
+```
+
+### React Re-renders
+
+```jsx
+// ❌ DON'T: New object/function on every render
+function ParentComponent() {
+  return <Child style={{ color: 'red' }} onClick={() => doSomething()} />;
+  //            ^^ new object every render  ^^ new function every render
+}
+
+// ✅ DO: Stable references
+const style = useMemo(() => ({ color: 'red' }), []);
+const handleClick = useCallback(() => doSomething(), []);
+return <Child style={style} onClick={handleClick} />;
+```
+
+---
+
+## 3. Latency Targets
+
+### API endpoints
+
+| Endpoint Type | p50 | p95 | p99 | Alert threshold (p95) |
+|--------------|-----|-----|-----|-----------------------|
+| Widget (public, read) | 10ms | 50ms | 100ms | > 200ms |
+| Dashboard (CRUD) | 20ms | 100ms | 500ms | > 1000ms |
+| List with pagination | 30ms | 150ms | 500ms | > 1000ms |
+| Webhooks (async OK) | 50ms | 500ms | 2000ms | > 5000ms |
+| File/image upload | 100ms | 1000ms | 5000ms | > 10000ms |
+
+### Frontend
+
+| Metric | Target | P0 if exceeds |
+|--------|--------|:---:|
+| FCP (First Contentful Paint) | < 1.5s | > 3s |
+| LCP (Largest Contentful Paint) | < 2.5s | > 4s |
+| CLS (Cumulative Layout Shift) | < 0.1 | > 0.25 |
+| TTI (Time to Interactive) | < 3.5s | > 7s |
+| JS Bundle (gzipped) | < 200KB | > 500KB |
+
+---
+
+## 4. Automated Detection
+
+### Grep patterns
+
+```bash
+# N+1 indicators
+grep_search: Query="await.*find"  Includes=["*.js"]  → check if inside loop (for/forEach/map)
+grep_search: Query="for.*await"   Includes=["*.js"]  → sequential async in loop
+
+# Unbounded queries
+grep_search: Query=".find({" Includes=["*.js"]  → check: has .limit() ?
+grep_search: Query=".find()" Includes=["*.js"]  → no filter at all
+
+# Over-fetching
+grep_search: Query=".findOne(" Includes=["*.js"]  → check: has .select() ?
+
+# Heavy sync operations
+grep_search: Query="readFileSync"  → P1: blocking I/O
+grep_search: Query="JSON.parse"    → check: large payloads?
+
+# React performance
+grep_search: Query="style={{" Includes=["*.jsx","*.tsx"]  → inline object → re-render
+grep_search: Query="() =>" Includes=["*.jsx","*.tsx"]     → inline function in JSX props
+```
+
+### Mongoose explain
+
+```javascript
+// Check query plan for slow queries
+const explain = await Model.find(query).explain('executionStats');
+// Look for: COLLSCAN (no index), nReturned vs totalDocsExamined
+```
+
+---
+
+## 5. Output Template
+
+```markdown
+# Performance Review Report
+
+**Scope:** <PR/module>
+**Reviewer:** Reviewer Agent
+**Date:** YYYY-MM-DD
+
+## Findings
+
+| # | Severity | Category | File:Line | Finding | Impact | Fix |
+|---|----------|----------|-----------|---------|--------|-----|
+| 1 | 🔴 P0 | N+1 | `services/coupon.js:45` | DB query inside for loop | 100 coupons = 100 queries | Use `$in` batch query |
+| 2 | 🔴 P0 | Unbounded | `routes/coupons.js:12` | `Coupon.find({})` without limit | Memory spike on large datasets | Add pagination |
+| 3 | 🟠 P1 | Over-fetch | `controllers/settings.js:8` | No `.select()` | 40 fields returned, 5 needed | Add `.select().lean()` |
+
+## Latency Check
+| Endpoint | Current p95 | Target p95 | Status |
+|----------|:-----------:|:----------:|:------:|
+| GET /widget/:id | ~30ms | 50ms | ✅ |
+| GET /coupons | ~800ms | 100ms | ❌ PERF-01 |
+
+## Checklist Summary
+- P0: X findings (blocking SLA/UX)
+- P1: Y findings (should fix)
+- P2: Z findings (optimization opportunities)
+
+## Verdict
+- ✅ PASS — no bottlenecks
+- ⚠️ OPTIMIZATION NEEDED — P0/P1 findings
+- ❌ BLOCKED — critical performance issue breaking SLA
+```
+
+---
+
+## See also
+- `$observability_plan` — latency targets, metrics
+- `$observability_review` — logging/metrics compliance
+- `$data_model` — index strategy
+- `$review_reference_snippets` — general DO/DON'T examples