vibes-plug 1.0.0

package/skills/data-telemetry-expert/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: data-telemetry-expert
+description: "Expert guide for observability, analytics, telemetry, and data pipelines (OpenTelemetry, PostHog, Mixpanel) / Panduan ahli untuk observabilitas, telemetri, dan analitik."
+author: "Roedy Rustam"
+---
+
+# Data & Telemetry Expert (OpenTelemetry 1.x / ClickHouse Edition)
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Description
+Expert guide for production observability, product analytics, and data pipelines. Covers **OpenTelemetry 1.x** (stable, vendor-neutral traces/metrics/logs), **PostHog** (open-source product analytics), **ClickHouse** (OLAP analytics database), Grafana stack, and AI agent observability patterns.
+
+### Trigger Conditions
+- Adding distributed tracing to a microservice or Next.js application.
+- Setting up structured logging and metrics collection.
+- Implementing product analytics (funnel analysis, feature flags, session replay).
+- Building a high-performance analytics pipeline with ClickHouse.
+- Monitoring AI agent runs, LLM token costs, and response quality.
+
+### OpenTelemetry 1.x — Vendor-Neutral Observability
+
+OpenTelemetry (OTel) is the CNCF standard for generating traces, metrics, and logs from any application.
+
+#### Three Pillars of OTel
+
+| Signal | What It Captures | Example |
+|---|---|---|
+| **Traces** | Request flow across services | `GET /api/users` → DB query → cache |
+| **Metrics** | Numeric measurements over time | `http_requests_total`, `db_query_duration` |
+| **Logs** | Structured event records | `{"level":"error","msg":"DB timeout"}` |
+
+#### Next.js 15 + OTel Instrumentation
+```typescript
+// instrumentation.ts (Next.js built-in OTel support)
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    const { NodeSDK } = await import('@opentelemetry/sdk-node');
+    const { OTLPTraceExporter } = await import('@opentelemetry/exporter-trace-otlp-http');
+    const { OTLPMetricExporter } = await import('@opentelemetry/exporter-metrics-otlp-http');
+    const { PeriodicExportingMetricReader } = await import('@opentelemetry/sdk-metrics');
+    const { Resource } = await import('@opentelemetry/resources');
+    const { SEMRESATTRS_SERVICE_NAME } = await import('@opentelemetry/semantic-conventions');
+
+    const sdk = new NodeSDK({
+      resource: new Resource({
+        [SEMRESATTRS_SERVICE_NAME]: 'my-saas-app',
+      }),
+      traceExporter: new OTLPTraceExporter({
+        url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+      }),
+      metricReader: new PeriodicExportingMetricReader({
+        exporter: new OTLPMetricExporter(),
+        exportIntervalMillis: 30_000,
+      }),
+    });
+
+    sdk.start();
+  }
+}
+```
+
+#### Custom Spans for Business Logic
+```typescript
+import { trace, SpanStatusCode } from '@opentelemetry/api';
+
+const tracer = trace.getTracer('my-service', '1.0.0');
+
+async function processOrder(orderId: string) {
+  return tracer.startActiveSpan('processOrder', async (span) => {
+    span.setAttribute('order.id', orderId);
+    span.setAttribute('order.source', 'api');
+    
+    try {
+      const order = await db.order.findUnique({ where: { id: orderId } });
+      span.setAttribute('order.amount', order.amount);
+      
+      const result = await chargeCustomer(order);
+      span.setStatus({ code: SpanStatusCode.OK });
+      return result;
+    } catch (error) {
+      span.recordException(error as Error);
+      span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+```
+
+### ClickHouse — High-Performance Analytics Database
+ClickHouse is the 2026 standard for analytical workloads — ingests billions of events and queries them in milliseconds:
+
+```sql
+-- Create an events table optimized for time-series analytics
+CREATE TABLE events (
+    event_id     UUID DEFAULT generateUUIDv4(),
+    workspace_id String,
+    user_id      String,
+    event_name   LowCardinality(String),
+    properties   JSON,
+    timestamp    DateTime64(3, 'UTC'),
+    date         Date DEFAULT toDate(timestamp)
+)
+ENGINE = MergeTree()
+PARTITION BY toYYYYMM(date)
+ORDER BY (workspace_id, event_name, timestamp)
+TTL date + INTERVAL 1 YEAR;
+
+-- Query: Funnel analysis — users who signed up then upgraded
+SELECT
+    countIf(event_name = 'signup') AS signups,
+    countIf(event_name = 'plan_upgraded') AS upgrades,
+    round(countIf(event_name = 'plan_upgraded') / countIf(event_name = 'signup') * 100, 2) AS conversion_rate
+FROM events
+WHERE workspace_id = 'ws_abc'
+  AND timestamp >= now() - INTERVAL 30 DAY;
+```
+
+```typescript
+// Node.js ClickHouse client
+import { createClient } from '@clickhouse/client';
+
+const client = createClient({ url: process.env.CLICKHOUSE_URL });
+
+await client.insert({
+  table: 'events',
+  values: [{
+    workspace_id: 'ws_abc',
+    user_id: 'user_123',
+    event_name: 'page_view',
+    properties: { path: '/dashboard', referrer: 'google.com' },
+    timestamp: new Date().toISOString(),
+  }],
+  format: 'JSONEachRow',
+});
+```
+
+### PostHog — Open-Source Product Analytics
+```typescript
+// Next.js + PostHog (client-side)
+import posthog from 'posthog-js';
+
+posthog.init(process.env.NEXT_PUBLIC_POSTHOG_KEY!, {
+  api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST ?? 'https://app.posthog.com',
+  capture_pageview: false, // Manual with App Router
+});
+
+// Track custom events
+posthog.capture('feature_used', {
+  feature: 'ai_assistant',
+  plan: user.plan,
+  workspace_id: workspace.id,
+});
+
+// Feature flags
+if (posthog.isFeatureEnabled('new-dashboard')) {
+  return <NewDashboard />;
+}
+```
+
+### AI Agent Observability
+Track LLM costs, latency, and quality for production AI applications:
+```typescript
+// Custom OTel attributes for LLM calls
+span.setAttribute('llm.model', 'claude-4-sonnet');
+span.setAttribute('llm.input_tokens', response.usage.input_tokens);
+span.setAttribute('llm.output_tokens', response.usage.output_tokens);
+span.setAttribute('llm.cost_usd', calculateCost(response.usage));
+span.setAttribute('llm.latency_ms', Date.now() - startTime);
+span.setAttribute('llm.cached', response.usage.cache_read_input_tokens > 0);
+```
+
+Backend tracing tools for LLM: **LangSmith** (LangChain/LangGraph), **OpenAI Tracing** (Agents SDK), **Langfuse** (open-source, any LLM).
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Deskripsi
+Panduan ahli untuk observabilitas produksi, analitik produk, dan pipeline data. Mencakup **OpenTelemetry 1.x** (stabil, vendor-neutral traces/metrics/logs), **PostHog** (analitik produk open-source), **ClickHouse** (database analitik OLAP), dan pola observabilitas agen AI.
+
+### Kondisi Pemicu
+- Menambahkan distributed tracing ke microservice atau aplikasi Next.js.
+- Menyiapkan structured logging dan pengumpulan metrik.
+- Mengimplementasikan analitik produk (analisis funnel, feature flags, session replay).
+- Membangun pipeline analitik berkinerja tinggi dengan ClickHouse.
+- Memantau run agen AI, biaya token LLM, dan kualitas respons.
+
+### OpenTelemetry 1.x — Observabilitas Vendor-Neutral
+
+Tiga pilar OTel:
+- **Traces**: Aliran permintaan antar layanan.
+- **Metrics**: Pengukuran numerik dari waktu ke waktu.
+- **Logs**: Catatan peristiwa terstruktur.
+
+Integrasikan dengan Next.js 15 melalui file `instrumentation.ts` bawaan — OTel SDK otomatis mendistribusikan trace ke backend pilihan (Grafana Tempo, Jaeger, Honeycomb, Datadog, dll.).
+
+### ClickHouse — Database Analitik Berkinerja Tinggi
+ClickHouse adalah standar 2026 untuk workload analitik — menyerap miliaran event dan melakukan query dalam milidetik. Gunakan engine `MergeTree` dengan partisi per bulan dan pengurutan berdasarkan kolom yang sering di-filter.
+
+### PostHog — Analitik Produk Open-Source
+PostHog menyediakan analisis funnel, feature flags, session replay, dan A/B testing dalam satu platform yang dapat di-self-host. Integrasikan dengan Next.js App Router menggunakan `posthog-js`.
+
+### Observabilitas Agen AI
+Lacak biaya LLM, latensi, dan kualitas untuk aplikasi AI produksi menggunakan custom OTel attributes. Gunakan LangSmith, OpenAI Tracing, atau Langfuse (open-source) sebagai backend tracing LLM.

package/skills/database-orm-expert/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: database-orm-expert
+description: "Expert guide for database schema design, ORM tools (Prisma 6, Drizzle ORM, TypeORM), migrations, query optimization, and type-safe SQL patterns in TypeScript / Panduan ahli untuk desain skema database, ORM tools (Prisma 6, Drizzle ORM, TypeORM), migrasi, optimasi query, dan pola SQL type-safe di TypeScript."
+author: "Roedy Rustam"
+---
+
+# Database ORM Expert (Prisma 6 + Drizzle ORM Edition)
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Description
+Expert-level database development covering schema design, ORM selection, migrations, query optimization, and type-safe SQL patterns. Focuses on **Prisma 6** and **Drizzle ORM** as primary modern ORMs, with coverage of TypeORM, raw SQL via `postgres.js`, and connection pooling strategies for production workloads.
+
+### Trigger Conditions
+- Designing or migrating a database schema.
+- Choosing between Prisma, Drizzle ORM, or TypeORM.
+- Writing complex queries with joins, aggregations, or pagination.
+- Optimizing slow queries or N+1 problems.
+- Setting up database migrations in CI/CD pipelines.
+- Implementing Row Level Security (RLS) patterns.
+- Working with PostgreSQL, MySQL, SQLite, or PlanetScale.
+
+---
+
+### ORM Selection Guide
+
+| Criteria | Prisma 6 | Drizzle ORM | TypeORM |
+|---|---|---|---|
+| **Type Safety** | Schema-generated types | SQL-like, inferred types | Decorator-based |
+| **Bundle Size** | Heavy (binary client) | Lightweight (<35KB) | Medium |
+| **Query Style** | Fluent ORM API | SQL-first, composable | ActiveRecord / QueryBuilder |
+| **Edge Runtime** | Prisma Accelerate needed | Native edge support | No |
+| **Migrations** | `prisma migrate dev` | `drizzle-kit push/migrate` | `synchronize` (dev only) |
+| **Best For** | Rapid prototyping, teams | Production edge, monorepos | Legacy NestJS projects |
+
+**Recommendation**: Use **Drizzle ORM** for edge-compatible apps and performance-critical systems. Use **Prisma 6** for teams that prefer a schema-first DX and rich Studio tooling.
+
+---
+
+### Prisma 6 — Best Practices
+
+#### Schema Design
+```prisma
+// schema.prisma
+generator client {
+  provider        = "prisma-client-js"
+  previewFeatures = ["relationJoins", "nativeDistinct"]
+}
+
+datasource db {
+  provider  = "postgresql"
+  url       = env("DATABASE_URL")
+  directUrl = env("DIRECT_URL") // for Supabase Pooler
+}
+
+model User {
+  id        String    @id @default(cuid())
+  email     String    @unique
+  name      String?
+  role      Role      @default(USER)
+  posts     Post[]
+  createdAt DateTime  @default(now())
+  updatedAt DateTime  @updatedAt
+
+  @@index([email])
+  @@map("users")
+}
+
+model Post {
+  id          String   @id @default(cuid())
+  title       String
+  content     String?
+  published   Boolean  @default(false)
+  authorId    String
+  author      User     @relation(fields: [authorId], references: [id], onDelete: Cascade)
+  publishedAt DateTime?
+
+  @@index([authorId, published])
+  @@map("posts")
+}
+
+enum Role {
+  USER
+  ADMIN
+  SUPER_ADMIN
+}
+```
+
+#### Avoiding N+1 with `include` vs `select`
+```typescript
+// BAD: triggers N+1 queries
+const users = await prisma.user.findMany();
+for (const user of users) {
+  const posts = await prisma.post.findMany({ where: { authorId: user.id } });
+}
+
+// GOOD: single query with JOIN (Prisma 5.7+ relationJoins preview)
+const users = await prisma.user.findMany({
+  select: {
+    id: true,
+    name: true,
+    email: true,
+    _count: { select: { posts: true } },
+    posts: {
+      where: { published: true },
+      select: { id: true, title: true },
+      take: 5,
+      orderBy: { publishedAt: 'desc' },
+    },
+  },
+});
+```
+
+#### Optimistic Transactions
+```typescript
+// Use $transaction for atomic operations
+const [updatedUser, newPost] = await prisma.$transaction([
+  prisma.user.update({ where: { id }, data: { name } }),
+  prisma.post.create({ data: { title, authorId: id } }),
+]);
+
+// Interactive transaction for complex logic
+const result = await prisma.$transaction(async (tx) => {
+  const user = await tx.user.findUniqueOrThrow({ where: { id } });
+  if (user.role !== 'ADMIN') throw new Error('Unauthorized');
+  return tx.post.updateMany({ where: { authorId: id }, data: { published: true } });
+});
+```
+
+---
+
+### Drizzle ORM — Best Practices
+
+#### Schema Definition (PostgreSQL)
+```typescript
+// src/db/schema.ts
+import { pgTable, text, boolean, timestamp, pgEnum, index } from 'drizzle-orm/pg-core';
+import { createId } from '@paralleldrive/cuid2';
+import { relations } from 'drizzle-orm';
+
+export const roleEnum = pgEnum('role', ['USER', 'ADMIN', 'SUPER_ADMIN']);
+
+export const users = pgTable('users', {
+  id: text('id').primaryKey().$defaultFn(() => createId()),
+  email: text('email').notNull().unique(),
+  name: text('name'),
+  role: roleEnum('role').default('USER').notNull(),
+  createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull().$onUpdateFn(() => new Date()),
+}, (t) => [
+  index('users_email_idx').on(t.email),
+]);
+
+export const posts = pgTable('posts', {
+  id: text('id').primaryKey().$defaultFn(() => createId()),
+  title: text('title').notNull(),
+  content: text('content'),
+  published: boolean('published').default(false).notNull(),
+  authorId: text('author_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
+  publishedAt: timestamp('published_at', { withTimezone: true }),
+}, (t) => [
+  index('posts_author_published_idx').on(t.authorId, t.published),
+]);
+
+export const usersRelations = relations(users, ({ many }) => ({
+  posts: many(posts),
+}));
+
+export const postsRelations = relations(posts, ({ one }) => ({
+  author: one(users, { fields: [posts.authorId], references: [users.id] }),
+}));
+```
+
+#### Type-safe Queries with Drizzle
+```typescript
+// src/db/index.ts
+import { drizzle } from 'drizzle-orm/postgres-js';
+import postgres from 'postgres';
+import * as schema from './schema';
+
+const client = postgres(process.env.DATABASE_URL!);
+export const db = drizzle(client, { schema });
+
+// Type-safe query with joins
+import { eq, and, desc, count } from 'drizzle-orm';
+
+const usersWithPosts = await db.query.users.findMany({
+  with: {
+    posts: {
+      where: eq(posts.published, true),
+      orderBy: desc(posts.publishedAt),
+      limit: 5,
+    },
+  },
+  extras: {
+    postCount: db.$count(posts, eq(posts.authorId, users.id)).as('post_count'),
+  },
+});
+
+// Paginated query
+async function getPaginatedPosts(page: number, pageSize = 20) {
+  const offset = (page - 1) * pageSize;
+  const [items, [{ total }]] = await Promise.all([
+    db.select().from(posts).where(eq(posts.published, true))
+      .orderBy(desc(posts.publishedAt))
+      .limit(pageSize)
+      .offset(offset),
+    db.select({ total: count() }).from(posts).where(eq(posts.published, true)),
+  ]);
+  return { items, total, pages: Math.ceil(total / pageSize) };
+}
+```
+
+#### Drizzle Migration Workflow
+```bash
+# drizzle.config.ts defines connection + schema path
+npx drizzle-kit generate   # generate migration SQL files
+npx drizzle-kit migrate    # apply migrations to database
+npx drizzle-kit push       # push schema directly (dev only)
+npx drizzle-kit studio     # open Drizzle Studio GUI
+```
+
+---
+
+### Query Optimization Principles
+
+1. **Always index foreign keys** and columns used in `WHERE`, `ORDER BY`, and `JOIN`.
+2. **Use `EXPLAIN ANALYZE`** to detect sequential scans and missing indexes.
+3. **Cursor-based pagination** over offset for large datasets:
+   ```typescript
+   // Cursor pagination with Drizzle
+   const items = await db.select().from(posts)
+     .where(cursor ? lt(posts.createdAt, cursor) : undefined)
+     .orderBy(desc(posts.createdAt))
+     .limit(pageSize);
+   ```
+4. **Connection pooling**: Use PgBouncer or Supabase's built-in pooler. Set `DIRECT_URL` for migrations and `DATABASE_URL` for pooled reads/writes.
+5. **Avoid `SELECT *`**: Always select only the columns you need.
+6. **Batch inserts**: Use `db.insert(table).values([...items])` instead of looping.
+
+---
+
+### Migration Best Practices
+
+- **Never use `synchronize: true`** in production (TypeORM).
+- **Never run `prisma db push`** in production — always use `prisma migrate deploy`.
+- Store migration files in version control.
+- Run migrations as a separate step before deploying new app versions.
+- Use **advisory locks** or migration tools to prevent concurrent migration runs.
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Deskripsi
+Panduan pengembangan database level ahli mencakup desain skema, pemilihan ORM, migrasi, optimasi query, dan pola SQL type-safe. Berfokus pada **Prisma 6** dan **Drizzle ORM** sebagai ORM modern utama, dengan cakupan TypeORM, SQL mentah via `postgres.js`, dan strategi connection pooling untuk beban kerja produksi.
+
+### Kondisi Pemicu
+- Merancang atau memigrasikan skema database.
+- Memilih antara Prisma, Drizzle ORM, atau TypeORM.
+- Menulis query kompleks dengan join, agregasi, atau paginasi.
+- Mengoptimalkan query lambat atau masalah N+1.
+- Menyiapkan migrasi database dalam pipeline CI/CD.
+- Mengimplementasikan pola Row Level Security (RLS).
+- Bekerja dengan PostgreSQL, MySQL, SQLite, atau PlanetScale.
+
+### Panduan Pemilihan ORM
+
+Gunakan tabel di atas (lihat bagian English) sebagai referensi pemilihan ORM. Rekomendasi singkat:
+- **Drizzle ORM**: Untuk aplikasi edge-compatible dan sistem kritis performa.
+- **Prisma 6**: Untuk tim yang lebih menyukai DX schema-first dan tooling Studio yang kaya.
+- **TypeORM**: Hanya untuk proyek lama (legacy) berbasis NestJS.
+
+### Prinsip Utama
+
+1. **Selalu index foreign key** dan kolom yang digunakan di `WHERE`, `ORDER BY`, dan `JOIN`.
+2. **Gunakan `EXPLAIN ANALYZE`** untuk mendeteksi sequential scan dan index yang hilang.
+3. **Cursor-based pagination** lebih baik dari offset untuk dataset besar.
+4. **Connection pooling**: Gunakan PgBouncer atau Supabase pooler bawaan.
+5. **Hindari `SELECT *`**: Selalu pilih hanya kolom yang dibutuhkan.
+6. **Batch insert**: Gunakan insert massal, bukan looping satu per satu.
+
+### Prinsip Migrasi
+
+- Jangan gunakan `synchronize: true` di produksi (TypeORM).
+- Jangan jalankan `prisma db push` di produksi — selalu gunakan `prisma migrate deploy`.
+- Simpan file migrasi di version control.
+- Jalankan migrasi sebagai langkah terpisah sebelum deploy versi aplikasi baru.