@rune-kit/rune 2.3.2 → 2.3.3

package/README.md

@@ -32,7 +32,7 @@ Mesh:      A ↔ B ↔ C             (B fails = A reaches C via D→E)
            D ↔ E ↔ F
 ```
 
-## What's New (v2.3.2)
+## What's New (v2.3.3)
 
 - **UI/UX Pro Max Integration** — 161 palettes, 84 styles, 73 font pairings, 161 reasoning rules from [UI/UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) (MIT, 42.8k★) meshed into `design` skill + `@rune/ui` pack
 - **11 Core Skill Enrichments** — deviation rules, repair operators, evidence quality gate, decision classification, debug knowledge base, CSO discipline, YAGNI pushback, formal pause/resume

package/docs/index.html

@@ -62,7 +62,7 @@
       <canvas id="mesh-canvas"></canvas>
     </div>
     <div class="hero-content">
-      <p class="hero-badge">v2.3.2 &mdash; 59 skills &bull; 8 platforms &bull; MIT</p>
+      <p class="hero-badge">v2.3.3 &mdash; 59 skills &bull; 8 platforms &bull; MIT</p>
       <h1>Less skills.<br><span class="accent">Deeper connections.</span></h1>
       <p class="hero-sub">A mesh ecosystem for AI coding assistants. Skills call each other bidirectionally, forming resilient workflows that adapt when things go wrong.</p>
       <div class="hero-actions">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.3.2",
+  "version": "2.3.3",
   "description": "59-skill mesh for AI coding assistants — 5-layer architecture, 200+ connections, 8 platforms (Claude Code, Cursor, Windsurf, Antigravity, Codex, OpenCode, OpenClaw, Generic)",
   "type": "module",
   "bin": {

package/skills/perf/SKILL.md

@@ -3,7 +3,7 @@ name: perf
 description: Performance regression gate. Detects N+1 queries, sync-in-async, missing indexes, memory leaks, and bundle bloat before they reach production.
 metadata:
   author: runedev
-  version: "0.1.0"
+  version: "0.2.0"
   layer: L2
   model: sonnet
   group: quality
@@ -38,6 +38,11 @@ Performance regression gate. Analyzes code changes for patterns that cause measu
 - `review` (L2): performance patterns detected in diff
 - `deploy` (L2): pre-deploy perf regression check
 
+## References
+
+- `references/cost-reference.md` — Cost priority hierarchy, quick wins checklist, instance right-sizing, data transfer traps, serverless optimization, observability cost control, managed vs self-hosted matrix, unit economics tracking. Load when cost analysis or FinOps context detected.
+- `references/scalability-reference.md` — Bottleneck identification flow, performance thresholds, API patterns (cursor pagination, rate limiting, circuit breaker, graceful shutdown), caching strategies, queue-based load leveling, concurrency patterns, K8s HPA, CDN headers, load testing. Load when scaling or infrastructure optimization context detected.
+
 ## Executable Steps
 
 ### Step 1 — Scope

package/skills/perf/references/cost-reference.md

@@ -0,0 +1,205 @@
+# Cost Optimization Reference
+
+> Loaded by `perf` skill when cost analysis, cloud spending, or FinOps context is detected.
+> Patterns: production-proven cost reduction strategies with dollar-impact estimates.
+
+---
+
+## Cost Priority Hierarchy
+
+Optimize in this order — higher tiers save 10x more than lower:
+
+```
+1. Architecture choices     (10x impact — monolith vs micro, serverless vs containers)
+2. Data transfer            (NAT Gateway, cross-region, CDN vs origin)
+3. Compute right-sizing     (instance types, spot/reserved, autoscaling)
+4. Database optimization    (query tuning, connection pooling, read replicas)
+5. Caching layer            (Redis, CDN, in-memory — ROI depends on hit rate)
+6. Storage tiering          (S3 lifecycle, cold storage, cleanup)
+7. Bundle/asset size        (tree-shaking, image optimization, compression)
+8. Observability costs      (log sampling, trace sampling, retention)
+```
+
+---
+
+## Quick Wins Checklist
+
+| Fix | Typical Savings | Effort |
+|-----|----------------|--------|
+| S3 Intelligent-Tiering on infrequent buckets | 40-70% storage | 5 min |
+| Fix N+1 queries (Prisma `include`) | 10-100x query reduction | 30 min |
+| WebP/AVIF images (Sharp pipeline) | 25-80% bandwidth | 1 hr |
+| Add CDN for static assets | 50-90% origin traffic | 1 hr |
+| NAT Gateway → VPC endpoints for AWS services | $30-100/mo per service | 30 min |
+| Log sampling (10% INFO, 100% ERROR) | 50-80% observability bill | 30 min |
+| Gzip/Brotli response compression | 70-90% transfer size | 15 min |
+| Lambda memory right-sizing (power tuning) | 10-40% Lambda cost | 1 hr |
+
+---
+
+## Instance Right-Sizing
+
+### AWS EC2 Strategy
+
+| Strategy | Savings | Commitment |
+|----------|---------|-----------|
+| On-Demand | Baseline | None |
+| Spot Instances | 60-90% | Can be interrupted |
+| Reserved (1-yr) | ~40% | 1 year |
+| Reserved (3-yr) | ~60% | 3 years |
+| Savings Plans | ~30-40% | Flexible commitment |
+
+### Kubernetes Right-Sizing
+
+```yaml
+# Set requests = actual P95 usage, limits = 2x requests
+resources:
+  requests:
+    cpu: "250m"      # Based on actual P95 CPU usage
+    memory: "256Mi"  # Based on actual P95 memory
+  limits:
+    cpu: "500m"
+    memory: "512Mi"
+```
+
+Check actual usage: `kubectl top pods --sort-by=cpu`
+
+---
+
+## Data Transfer Cost Traps
+
+### NAT Gateway Problem
+
+NAT Gateway: **$0.045/GB + $0.045/hr** — one of the most expensive AWS surprises.
+
+**Fix:** Replace with VPC endpoints for AWS services:
+```
+S3 Gateway Endpoint         → Free (gateway type)
+DynamoDB Gateway Endpoint   → Free (gateway type)
+SQS/SNS Interface Endpoint → $0.01/hr (still 4x cheaper than NAT)
+```
+
+### Cross-Region Transfer
+
+- Same region, same AZ: **Free**
+- Same region, different AZ: **$0.01/GB**
+- Cross-region: **$0.02/GB**
+- Internet egress: **$0.09/GB** (first 10TB)
+
+**Rule:** Keep services in the same AZ when possible. Use CloudFront for global distribution.
+
+---
+
+## Serverless Optimization
+
+### Lambda Memory Tuning
+
+Lambda CPU scales linearly with memory. Sometimes MORE memory = CHEAPER (faster execution):
+
+```
+128MB, 3000ms  = 375,000 GB-ms = $0.00000625
+512MB, 800ms   = 400,000 GB-ms = $0.00000667  (similar cost, 4x faster)
+1024MB, 400ms  = 400,000 GB-ms = $0.00000667  (same cost, 7.5x faster)
+```
+
+Use [AWS Lambda Power Tuning](https://github.com/alexcasalboni/aws-lambda-power-tuning) to find optimal memory.
+
+### Cold Start Reduction
+
+| Technique | Impact |
+|-----------|--------|
+| Smaller deployment package | -100-500ms |
+| Use Graviton (arm64) | -200ms + 20% cheaper |
+| Provisioned concurrency | Eliminates cold starts |
+| Lazy-load heavy SDKs | -200-1000ms |
+| Use ESM instead of CJS | -100-300ms (Node.js) |
+
+---
+
+## Observability Cost Control
+
+### Log Sampling
+
+```typescript
+// Sample 10% of INFO logs, keep 100% of errors
+const shouldLog = (level: string): boolean => {
+  if (level === 'error' || level === 'warn') return true;
+  return Math.random() < 0.1; // 10% sampling
+};
+```
+
+### Trace Sampling
+
+```typescript
+// 100% errors and slow requests, 10% normal
+const shouldTrace = (duration: number, isError: boolean): boolean => {
+  if (isError) return true;
+  if (duration > 1000) return true; // Slow requests
+  return Math.random() < 0.1;
+};
+```
+
+### High-Cardinality Metrics — NEVER DO
+
+```typescript
+// BAD: Creates millions of unique time series
+metrics.counter('requests', { userId: req.userId }); // ← kills Datadog bill
+
+// GOOD: Low-cardinality labels only
+metrics.counter('requests', { endpoint: '/api/users', method: 'GET', status: '200' });
+```
+
+### Retention Policies
+
+| Data Type | Recommended Retention |
+|-----------|----------------------|
+| Raw logs | 7-14 days |
+| Aggregated metrics | 90 days |
+| Error logs | 30-90 days |
+| Traces | 7 days |
+| Audit logs | 1-7 years (compliance) |
+
+---
+
+## Managed vs Self-Hosted Decision Matrix
+
+| Service | Self-Host When | Stay Managed When |
+|---------|---------------|-------------------|
+| Auth | >200K MAU ($4K+/mo managed) | <200K MAU or need compliance |
+| Search | >500K records or >$500/mo | <500K records, need instant setup |
+| Database | >$500/mo RDS bill | Need HA, backups, patching handled |
+| Email | Almost never | Always (deliverability is hard) |
+| Monitoring | >$1K/mo Datadog | Need APM + distributed tracing |
+
+---
+
+## Unit Economics Tracking
+
+```typescript
+// Track cost per unit to detect inefficiency trends
+interface UnitEconomics {
+  costPerRequest: number;   // Total infra / total requests
+  costPerUser: number;      // Total infra / MAU
+  costPerTransaction: number; // Total infra / transactions
+}
+
+// Alert if unit cost increases >20% month-over-month
+function checkCostTrend(current: number, previous: number): void {
+  const increase = (current - previous) / previous;
+  if (increase > 0.2) {
+    alert(`Unit cost increased ${(increase * 100).toFixed(0)}% — investigate`);
+  }
+}
+```
+
+---
+
+## Cost Optimization Priority Matrix
+
+| Effort | Low Savings (<$100/mo) | Med Savings ($100-500) | High Savings (>$500) |
+|--------|----------------------|----------------------|---------------------|
+| **Low** | Log retention | Image optimization | S3 tiering |
+| **Medium** | Bundle analysis | Caching layer | Instance right-sizing |
+| **High** | — | Query optimization | Architecture redesign |
+
+**Rule:** Start top-right (high savings, low effort), work diagonally down-left.

package/skills/perf/references/scalability-reference.md

@@ -0,0 +1,378 @@
+# Scalability Reference
+
+> Loaded by `perf` skill when scaling, load handling, or infrastructure optimization context is detected.
+> Patterns: production-proven scalability strategies for Node.js/TypeScript applications.
+
+---
+
+## Bottleneck Identification Flow
+
+Profile BEFORE optimizing. Follow this decision tree:
+
+```
+Is database the bottleneck (>50% of response time)?
+├── YES → Index optimization, connection pooling, read replicas, query caching
+│         See db/references/scaling-reference.md
+└── NO
+    Is external API the bottleneck?
+    ├── YES → Circuit breaker, caching, parallel requests, queue background
+    └── NO
+        Is it CPU-bound?
+        ├── YES → Worker threads, horizontal scaling, algorithm optimization
+        └── NO
+            Is it memory pressure?
+            ├── YES → Leak detection, streaming, pagination, bounded caches
+            └── NO → Measure again with better instrumentation
+```
+
+## Performance Thresholds
+
+| Metric | Healthy | Warning | Critical |
+|--------|---------|---------|----------|
+| p99 latency | <200ms | 200-500ms | >500ms |
+| DB cache hit ratio | >95% | 90-95% | <90% |
+| Connection pool utilization | <70% | 70-85% | >85% |
+| CPU utilization | <60% | 60-80% | >80% |
+| Memory utilization | <70% | 70-85% | >85% |
+| Error rate | <0.1% | 0.1-1% | >1% |
+| Queue depth | <100 | 100-1000 | >1000 |
+| Queue wait time | <1s | 1-10s | >10s |
+
+---
+
+## API Scalability Patterns
+
+### Cursor-Based Pagination
+
+Offset pagination breaks at scale (`OFFSET 100000` = scan 100K rows). Use cursor-based:
+
+```typescript
+// Cursor-based — consistent performance at any depth
+async function listOrders(cursor?: string, limit = 20) {
+  const where = cursor ? { id: { gt: cursor } } : {};
+  const items = await prisma.order.findMany({
+    where,
+    take: limit + 1, // Fetch one extra to detect hasMore
+    orderBy: { id: 'asc' },
+  });
+
+  const hasMore = items.length > limit;
+  const data = hasMore ? items.slice(0, -1) : items;
+
+  return {
+    data,
+    cursor: data.at(-1)?.id ?? null,
+    hasMore,
+  };
+}
+```
+
+### Rate Limiting (Tiered)
+
+```typescript
+const rateLimits = {
+  free:       { requests: 100,  window: '15m' },
+  pro:        { requests: 1000, window: '15m' },
+  enterprise: { requests: 10000, window: '15m' },
+};
+
+// Response headers (always include)
+// X-RateLimit-Limit: 1000
+// X-RateLimit-Remaining: 847
+// X-RateLimit-Reset: 1699234567
+// Retry-After: 30  (only on 429)
+```
+
+### Circuit Breaker
+
+```typescript
+import CircuitBreaker from 'opossum';
+
+const breaker = new CircuitBreaker(callExternalAPI, {
+  timeout: 3000,          // Fail if function takes > 3s
+  errorThresholdPercentage: 50,  // Open if 50% fail
+  resetTimeout: 30000,    // Try again after 30s
+  volumeThreshold: 10,    // Min calls before tripping
+});
+
+breaker.fallback(() => cachedResponse);
+breaker.on('open', () => logger.warn('Circuit breaker OPEN'));
+```
+
+### Graceful Shutdown
+
+```typescript
+async function shutdown(signal: string) {
+  logger.info(`${signal} received — starting graceful shutdown`);
+
+  // 1. Stop accepting new connections
+  server.close();
+
+  // 2. Finish in-flight requests (with timeout)
+  await Promise.race([
+    finishInflightRequests(),
+    new Promise(resolve => setTimeout(resolve, 30000)),
+  ]);
+
+  // 3. Close DB connections
+  await prisma.$disconnect();
+  await redis.quit();
+
+  process.exit(0);
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+```
+
+---
+
+## Caching Strategies
+
+### Strategy Selection
+
+| Strategy | When to Use | Trade-off |
+|----------|-------------|-----------|
+| **Cache-aside** | Most common. App checks cache, falls back to DB | May serve stale data |
+| **Write-through** | Cache updated on every write | Higher write latency |
+| **Write-behind** | Cache updated async after write | Risk of data loss |
+| **Read-through** | Cache auto-fetches on miss | Cache library dependency |
+
+### TTL Guidelines
+
+| Data Type | TTL | Rationale |
+|-----------|-----|-----------|
+| Static config | 1 hour | Rarely changes |
+| User profile | 5 min | Changes occasionally |
+| Product catalog | 15 min | Balance freshness vs load |
+| Session data | 30 min sliding | Security + UX |
+| Rate limit counters | Match window | Exact timing matters |
+| Search results | 60s | High-read, low-freshness need |
+
+### Cache Invalidation Patterns
+
+```typescript
+// 1. TTL-based (simplest, eventual consistency)
+await redis.setex(`user:${id}`, 300, JSON.stringify(user));
+
+// 2. Explicit invalidation (strongest consistency)
+await prisma.user.update({ where: { id }, data });
+await redis.del(`user:${id}`);
+
+// 3. Tag-based (invalidate groups)
+await redis.sadd('tag:users', `user:${id}`, `user:${id}:posts`);
+// On invalidate:
+const keys = await redis.smembers('tag:users');
+await redis.del(...keys);
+
+// 4. Versioned keys (zero-downtime cache migration)
+const version = 'v2';
+await redis.setex(`user:${version}:${id}`, 300, data);
+```
+
+---
+
+## Queue-Based Load Leveling
+
+### When to Use Queues
+
+- Request takes > 500ms to process
+- External API with rate limits
+- Spiky traffic patterns
+- Fire-and-forget operations (email, webhooks, analytics)
+
+### BullMQ Pattern
+
+```typescript
+import { Queue, Worker } from 'bullmq';
+
+const emailQueue = new Queue('emails', { connection: redis });
+
+// Producer — returns immediately
+await emailQueue.add('welcome', { userId, email }, {
+  attempts: 3,
+  backoff: { type: 'exponential', delay: 1000 },
+  removeOnComplete: 1000,  // Keep last 1000 completed
+  removeOnFail: 5000,      // Keep last 5000 failed
+});
+
+// Consumer — processes in background
+const worker = new Worker('emails', async (job) => {
+  await sendEmail(job.data.email, 'Welcome!');
+}, {
+  connection: redis,
+  concurrency: 5,          // Process 5 emails in parallel
+  limiter: { max: 10, duration: 1000 }, // Rate limit: 10/sec
+});
+```
+
+---
+
+## Concurrency Patterns
+
+### Worker Threads (CPU-intensive)
+
+```typescript
+import { Worker, isMainThread, parentPort, workerData } from 'worker_threads';
+
+if (isMainThread) {
+  const worker = new Worker(__filename, { workerData: { input } });
+  worker.on('message', (result) => resolve(result));
+  worker.on('error', reject);
+} else {
+  const result = heavyComputation(workerData.input);
+  parentPort?.postMessage(result);
+}
+```
+
+### Backpressure (prevent OOM)
+
+```typescript
+// Bounded queue — reject when full instead of consuming infinite memory
+class BoundedQueue<T> {
+  private queue: T[] = [];
+  constructor(private maxSize: number) {}
+
+  enqueue(item: T): boolean {
+    if (this.queue.length >= this.maxSize) return false; // Apply backpressure
+    this.queue.push(item);
+    return true;
+  }
+}
+```
+
+### Semaphore (limit concurrent operations)
+
+```typescript
+class Semaphore {
+  private current = 0;
+  private queue: (() => void)[] = [];
+
+  constructor(private max: number) {}
+
+  async acquire(): Promise<void> {
+    if (this.current < this.max) {
+      this.current++;
+      return;
+    }
+    return new Promise((resolve) => this.queue.push(resolve));
+  }
+
+  release(): void {
+    this.current--;
+    const next = this.queue.shift();
+    if (next) { this.current++; next(); }
+  }
+}
+
+// Usage: limit to 10 concurrent DB connections
+const sem = new Semaphore(10);
+await sem.acquire();
+try { await db.query(sql); }
+finally { sem.release(); }
+```
+
+---
+
+## Deployment Scalability
+
+### Kubernetes HPA
+
+```yaml
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: api-hpa
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: api
+  minReplicas: 2
+  maxReplicas: 20
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+  behavior:
+    scaleUp:
+      stabilizationWindowSeconds: 60
+    scaleDown:
+      stabilizationWindowSeconds: 300  # Slow scale-down prevents flapping
+```
+
+### CDN Cache-Control Headers
+
+```
+# Immutable assets (hashed filenames)
+Cache-Control: public, max-age=31536000, immutable
+
+# API responses (short cache + revalidation)
+Cache-Control: public, max-age=60, stale-while-revalidate=30
+
+# Private user data
+Cache-Control: private, no-store
+
+# HTML pages (revalidate every time)
+Cache-Control: no-cache
+```
+
+### Zero-Downtime Database Migrations
+
+3-phase safe migration pattern:
+
+```
+Phase 1: ADD new column (nullable) → deploy
+Phase 2: Deploy code that writes to BOTH old + new columns → backfill
+Phase 3: Drop old column → deploy
+
+NEVER in one step:
+- Rename column (breaks running code)
+- Change type (data loss risk)
+- Add NOT NULL without default (fails on existing rows)
+```
+
+---
+
+## Load Testing
+
+### k6 Quick Start
+
+```javascript
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  stages: [
+    { duration: '1m', target: 50 },   // Ramp up
+    { duration: '3m', target: 50 },   // Steady state
+    { duration: '1m', target: 0 },    // Ramp down
+  ],
+  thresholds: {
+    http_req_duration: ['p(99)<500'],  // 99th percentile < 500ms
+    http_req_failed: ['rate<0.01'],    // Error rate < 1%
+  },
+};
+
+export default function () {
+  const res = http.get('https://api.example.com/orders');
+  check(res, { 'status 200': (r) => r.status === 200 });
+  sleep(1);
+}
+```
+
+### What to Measure
+
+| Metric | Target | Why |
+|--------|--------|-----|
+| p50 latency | <100ms | Typical user experience |
+| p99 latency | <500ms | Worst-case user experience |
+| Throughput (RPS) | >baseline | Capacity headroom |
+| Error rate | <0.1% | Reliability |
+| CPU during load | <80% | Scaling headroom |
+| Memory during load | <70% | Leak detection |
+
+**Rule:** Always observe p99, not p50. Median latency hides tail latency that kills user experience.