@rune-kit/rune 2.8.0 → 2.11.0

package/extensions/saas/skills/feature-flags.md

@@ -1,130 +1,130 @@
----
-name: "feature-flags"
-pack: "@rune/saas"
-description: "Feature flag management — gradual rollouts, kill switches, A/B testing, user-segment targeting, and stale flag cleanup. Supports self-hosted (Unleash, custom Redis) and managed (LaunchDarkly, Statsig, Flagsmith)."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# feature-flags
-
-Feature flag management — gradual rollouts, kill switches, A/B testing, user-segment targeting, and stale flag cleanup. Supports self-hosted (Unleash, custom Redis) and managed (LaunchDarkly, Statsig, Flagsmith).
-
-#### Flag Types
-
-| Type | Use Case | Example |
-|---|---|---|
-| Boolean | Simple on/off for a feature | `new_dashboard_ui` |
-| Percentage rollout | Gradual release 1% → 100% | `redesigned_editor: 25%` |
-| User segment | Specific users/orgs first | `beta_users`, `enterprise_plan` |
-| A/B test | Compare variants with metrics | `checkout_flow: variant_a / variant_b` |
-| Kill switch | Instant disable on failure | `payment_processor_v2` |
-| Environment | Dev/staging/prod separation | Auto by `NODE_ENV` |
-
-#### Rollout Pattern: Canary → Gradual → GA
-
-```
-1% (internal + beta users) → 10% → 25% → 50% → 100% → cleanup flag after 30 days at 100%
-```
-
-#### Workflow
-
-**Step 1 — Identify feature boundary**
-Before writing code, define the flag: name (kebab-case, descriptive), default value (false = safe default), targeting rules (who sees it first), and planned cleanup date. Document in your flag provider dashboard.
-
-**Step 2 — Create flag with targeting rules**
-In Unleash/LaunchDarkly/Flagsmith: create flag with gradual rollout strategy. Start at 0%. Add a "beta users" segment for internal testing before any percentage rollout. Set environment-specific defaults: always-on in dev, gradual in staging, starts at 0% in prod.
-
-**Step 3 — Implement client/server evaluation**
-Client: evaluate flag in a React hook, never inline. Server: evaluate in middleware or at request start, attach result to request context. Never evaluate flags inside hot loops — cache the result for the request lifetime.
-
-**Step 4 — Add analytics event tracking**
-Every flag evaluation on a user-facing feature should fire an analytics event: `feature_flag_evaluated` with `{ flag, variant, userId, tenantId }`. This enables funnel analysis by variant and measures the rollout's impact on key metrics.
-
-**Step 5 — Schedule flag cleanup**
-Flags that have been at 100% for >30 days are stale. Run a weekly lint job: grep all flag keys used in code, compare against provider's flag list, flag mismatches (code uses a flag that was deleted → runtime error, or flag exists but never referenced → cleanup candidate). Remove stale flags from both code and provider in the same PR.
-
-#### Example
-
-```typescript
-// Custom Redis-based flag evaluation (self-hosted, zero SaaS dependency)
-import { Redis } from 'ioredis';
-const redis = new Redis(process.env.REDIS_URL!);
-
-interface FlagConfig {
-  enabled: boolean;
-  percentage?: number;          // 0-100 for gradual rollout
-  allowedUsers?: string[];      // canary user IDs
-  allowedPlans?: string[];      // plan-based targeting
-}
-
-const evaluateFlag = async (
-  flagKey: string,
-  ctx: { userId: string; tenantId: string; plan: string }
-): Promise<boolean> => {
-  const raw = await redis.get(`flag:${flagKey}`);
-  if (!raw) return false; // default off = safe
-  const config: FlagConfig = JSON.parse(raw);
-  if (!config.enabled) return false;
-  if (config.allowedUsers?.includes(ctx.userId)) return true;
-  if (config.allowedPlans?.includes(ctx.plan)) return true;
-  if (config.percentage !== undefined) {
-    // Deterministic: same user always gets same bucket
-    const hash = parseInt(ctx.userId.slice(-8), 16) % 100;
-    return hash < config.percentage;
-  }
-  return config.enabled;
-};
-
-// React hook — evaluate once per render cycle, never in loops
-function useFlag(flagKey: string): boolean {
-  const { user } = useAuth();
-  const { data: enabled = false } = useQuery({
-    queryKey: ['flag', flagKey, user?.id],
-    queryFn: () => fetchFlag(flagKey),
-    staleTime: 30_000, // cache 30s — flags don't change every millisecond
-  });
-  return enabled;
-}
-
-// Server middleware — evaluate at request boundary, attach to context
-const flagMiddleware = (flagKey: string) => async (req: Request, res: Response, next: NextFunction) => {
-  req.flags = req.flags ?? {};
-  req.flags[flagKey] = await evaluateFlag(flagKey, {
-    userId: req.user!.id,
-    tenantId: req.tenantId!,
-    plan: req.user!.plan,
-  });
-  next();
-};
-
-// Usage in route — flag already evaluated, no async needed
-app.get('/api/checkout', flagMiddleware('new_checkout_v2'), (req, res) => {
-  if (req.flags['new_checkout_v2']) {
-    return checkoutV2Handler(req, res);
-  }
-  return checkoutV1Handler(req, res);
-});
-
-// Stale flag detection — run weekly in CI
-import { execSync } from 'child_process';
-
-const findStaleFlags = async () => {
-  const flagsInCode = execSync('grep -r "useFlag\\|evaluateFlag" src/ --include="*.ts" -h')
-    .toString()
-    .match(/(?:useFlag|evaluateFlag)\(['"]([^'"]+)['"]/g)
-    ?.map(m => m.match(/['"]([^'"]+)['"]/)?.[1])
-    .filter(Boolean) ?? [];
-
-  const flagsInProvider = await redis.keys('flag:*').then(keys => keys.map(k => k.replace('flag:', '')));
-  const stale = flagsInProvider.filter(f => !flagsInCode.includes(f));
-  const missing = flagsInCode.filter(f => !flagsInProvider.includes(f));
-  return { stale, missing };
-};
-```
-
-**Sharp edges for flags:**
-- Never evaluate flags on hot paths (e.g., inside `Array.map` over 1000 items) — cache the flag state at the top of the function.
-- In tests: mock flag evaluation at the provider level, not by conditionally skipping flag checks. Every code path should be testable with flags on and off.
-- Flag dependency chains (flag A enables flag B) — avoid. If you need compound logic, evaluate both flags independently and combine in application code. Provider-level dependencies are invisible in code review.
-- Percentage rollout is not the same as A/B test — percentage rollout has no control group. For A/B tests, always keep a 50/50 split or a defined control group.
+---
+name: "feature-flags"
+pack: "@rune/saas"
+description: "Feature flag management — gradual rollouts, kill switches, A/B testing, user-segment targeting, and stale flag cleanup. Supports self-hosted (Unleash, custom Redis) and managed (LaunchDarkly, Statsig, Flagsmith)."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# feature-flags
+
+Feature flag management — gradual rollouts, kill switches, A/B testing, user-segment targeting, and stale flag cleanup. Supports self-hosted (Unleash, custom Redis) and managed (LaunchDarkly, Statsig, Flagsmith).
+
+#### Flag Types
+
+| Type | Use Case | Example |
+|---|---|---|
+| Boolean | Simple on/off for a feature | `new_dashboard_ui` |
+| Percentage rollout | Gradual release 1% → 100% | `redesigned_editor: 25%` |
+| User segment | Specific users/orgs first | `beta_users`, `enterprise_plan` |
+| A/B test | Compare variants with metrics | `checkout_flow: variant_a / variant_b` |
+| Kill switch | Instant disable on failure | `payment_processor_v2` |
+| Environment | Dev/staging/prod separation | Auto by `NODE_ENV` |
+
+#### Rollout Pattern: Canary → Gradual → GA
+
+```
+1% (internal + beta users) → 10% → 25% → 50% → 100% → cleanup flag after 30 days at 100%
+```
+
+#### Workflow
+
+**Step 1 — Identify feature boundary**
+Before writing code, define the flag: name (kebab-case, descriptive), default value (false = safe default), targeting rules (who sees it first), and planned cleanup date. Document in your flag provider dashboard.
+
+**Step 2 — Create flag with targeting rules**
+In Unleash/LaunchDarkly/Flagsmith: create flag with gradual rollout strategy. Start at 0%. Add a "beta users" segment for internal testing before any percentage rollout. Set environment-specific defaults: always-on in dev, gradual in staging, starts at 0% in prod.
+
+**Step 3 — Implement client/server evaluation**
+Client: evaluate flag in a React hook, never inline. Server: evaluate in middleware or at request start, attach result to request context. Never evaluate flags inside hot loops — cache the result for the request lifetime.
+
+**Step 4 — Add analytics event tracking**
+Every flag evaluation on a user-facing feature should fire an analytics event: `feature_flag_evaluated` with `{ flag, variant, userId, tenantId }`. This enables funnel analysis by variant and measures the rollout's impact on key metrics.
+
+**Step 5 — Schedule flag cleanup**
+Flags that have been at 100% for >30 days are stale. Run a weekly lint job: grep all flag keys used in code, compare against provider's flag list, flag mismatches (code uses a flag that was deleted → runtime error, or flag exists but never referenced → cleanup candidate). Remove stale flags from both code and provider in the same PR.
+
+#### Example
+
+```typescript
+// Custom Redis-based flag evaluation (self-hosted, zero SaaS dependency)
+import { Redis } from 'ioredis';
+const redis = new Redis(process.env.REDIS_URL!);
+
+interface FlagConfig {
+  enabled: boolean;
+  percentage?: number;          // 0-100 for gradual rollout
+  allowedUsers?: string[];      // canary user IDs
+  allowedPlans?: string[];      // plan-based targeting
+}
+
+const evaluateFlag = async (
+  flagKey: string,
+  ctx: { userId: string; tenantId: string; plan: string }
+): Promise<boolean> => {
+  const raw = await redis.get(`flag:${flagKey}`);
+  if (!raw) return false; // default off = safe
+  const config: FlagConfig = JSON.parse(raw);
+  if (!config.enabled) return false;
+  if (config.allowedUsers?.includes(ctx.userId)) return true;
+  if (config.allowedPlans?.includes(ctx.plan)) return true;
+  if (config.percentage !== undefined) {
+    // Deterministic: same user always gets same bucket
+    const hash = parseInt(ctx.userId.slice(-8), 16) % 100;
+    return hash < config.percentage;
+  }
+  return config.enabled;
+};
+
+// React hook — evaluate once per render cycle, never in loops
+function useFlag(flagKey: string): boolean {
+  const { user } = useAuth();
+  const { data: enabled = false } = useQuery({
+    queryKey: ['flag', flagKey, user?.id],
+    queryFn: () => fetchFlag(flagKey),
+    staleTime: 30_000, // cache 30s — flags don't change every millisecond
+  });
+  return enabled;
+}
+
+// Server middleware — evaluate at request boundary, attach to context
+const flagMiddleware = (flagKey: string) => async (req: Request, res: Response, next: NextFunction) => {
+  req.flags = req.flags ?? {};
+  req.flags[flagKey] = await evaluateFlag(flagKey, {
+    userId: req.user!.id,
+    tenantId: req.tenantId!,
+    plan: req.user!.plan,
+  });
+  next();
+};
+
+// Usage in route — flag already evaluated, no async needed
+app.get('/api/checkout', flagMiddleware('new_checkout_v2'), (req, res) => {
+  if (req.flags['new_checkout_v2']) {
+    return checkoutV2Handler(req, res);
+  }
+  return checkoutV1Handler(req, res);
+});
+
+// Stale flag detection — run weekly in CI
+import { execSync } from 'child_process';
+
+const findStaleFlags = async () => {
+  const flagsInCode = execSync('grep -r "useFlag\\|evaluateFlag" src/ --include="*.ts" -h')
+    .toString()
+    .match(/(?:useFlag|evaluateFlag)\(['"]([^'"]+)['"]/g)
+    ?.map(m => m.match(/['"]([^'"]+)['"]/)?.[1])
+    .filter(Boolean) ?? [];
+
+  const flagsInProvider = await redis.keys('flag:*').then(keys => keys.map(k => k.replace('flag:', '')));
+  const stale = flagsInProvider.filter(f => !flagsInCode.includes(f));
+  const missing = flagsInCode.filter(f => !flagsInProvider.includes(f));
+  return { stale, missing };
+};
+```
+
+**Sharp edges for flags:**
+- Never evaluate flags on hot paths (e.g., inside `Array.map` over 1000 items) — cache the flag state at the top of the function.
+- In tests: mock flag evaluation at the provider level, not by conditionally skipping flag checks. Every code path should be testable with flags on and off.
+- Flag dependency chains (flag A enables flag B) — avoid. If you need compound logic, evaluate both flags independently and combine in application code. Provider-level dependencies are invisible in code review.
+- Percentage rollout is not the same as A/B test — percentage rollout has no control group. For A/B tests, always keep a 50/50 split or a defined control group.

package/extensions/saas/skills/multi-tenant.md

@@ -1,103 +1,103 @@
----
-name: "multi-tenant"
-pack: "@rune/saas"
-description: "Multi-tenancy patterns — database isolation strategies, tenant context middleware, data partitioning, cross-tenant query prevention, tenant-aware background jobs, and GDPR data export."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# multi-tenant
-
-Multi-tenancy patterns — database isolation strategies, tenant context middleware, data partitioning, cross-tenant query prevention, tenant-aware background jobs, and GDPR data export.
-
-#### Isolation Strategy Comparison
-
-| Strategy | Cost | Isolation | Migration Difficulty | When to Use |
-|---|---|---|---|---|
-| Shared DB, tenant column | Low | Weak (app-enforced) | Easy | Early-stage, <1000 tenants |
-| Shared DB + PostgreSQL RLS | Low | Strong (DB-enforced) | Easy | Best default for most SaaS |
-| Schema-per-tenant | Medium | Strong | Medium | When tenants need schema customization |
-| DB-per-tenant | High | Perfect | Hard | Enterprise, compliance (HIPAA, SOC2) |
-
-#### Workflow
-
-**Step 1 — Detect current isolation strategy**
-Use Grep to find tenant-related code: `tenantId`, `organizationId`, `workspaceId`, `x-tenant-id` header, RLS policies, schema-per-tenant patterns, database switching logic. Read the database schema and middleware to classify the isolation strategy in use.
-
-**Step 2 — Audit isolation boundaries**
-Check for: queries without tenant filter (data leak risk), missing tenant context in middleware, no RLS policies on shared tables, admin endpoints that bypass tenant isolation, background jobs processing cross-tenant data without scoping. Flag each with severity.
-
-**Step 3 — Emit tenant-safe patterns**
-Based on detected strategy, emit: tenant middleware (extract from JWT/header, set on request context), RLS policies for shared-schema approach, scoped repository pattern that injects tenant filter on every query, and tenant-aware test fixtures.
-
-**Step 4 — Tenant-aware background jobs**
-Every background job MUST carry `tenantId`. Use BullMQ job data to pass tenant context, then initialize a scoped repository inside the job processor. Never process tenant data in a job without an explicit `tenantId` guard.
-
-**Step 5 — Tenant data export (GDPR portability)**
-Implement `/api/tenants/:id/export` that collects all data rows belonging to a tenant across all tables, serializes to JSON or CSV, and streams the result as a download. Log the export event in the audit trail with timestamp and requesting user.
-
-#### Example
-
-```typescript
-// Tenant middleware — extract from JWT, inject into request context
-const tenantMiddleware = async (req: Request, res: Response, next: NextFunction) => {
-  const tenantId = req.user?.tenantId ?? req.headers['x-tenant-id'] as string;
-  if (!tenantId) return res.status(403).json({ error: { code: 'TENANT_REQUIRED', message: 'Tenant context missing' } });
-  req.tenantId = tenantId;
-  next();
-};
-
-// Scoped repository — every query automatically filtered by tenant
-class ScopedRepository<T extends { tenantId: string }> {
-  constructor(private model: PrismaModel<T>, private tenantId: string) {}
-
-  async findMany(where: Partial<Omit<T, 'tenantId'>> = {}) {
-    return this.model.findMany({ where: { ...where, tenantId: this.tenantId } });
-  }
-
-  async create(data: Omit<T, 'tenantId' | 'id' | 'createdAt' | 'updatedAt'>) {
-    return this.model.create({ data: { ...data, tenantId: this.tenantId } as any });
-  }
-}
-
-// PostgreSQL RLS — DB-enforced isolation, safest approach
--- Enable RLS on every shared table
-ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
-
--- Set tenant context before query (from app middleware)
-SET LOCAL app.tenant_id = '550e8400-e29b-41d4-a716-446655440000';
-
--- Policy reads from session variable — automatic for all queries
-CREATE POLICY tenant_isolation ON projects
-  USING (tenant_id = current_setting('app.tenant_id')::uuid);
-
--- Set in Prisma $executeRaw before each query block:
--- await prisma.$executeRaw`SELECT set_config('app.tenant_id', ${tenantId}, true)`;
-
-// BullMQ — tenant-aware background job
-const emailQueue = new Queue('emails');
-
-// Producer: always pass tenantId in job data
-await emailQueue.add('send-invoice', { tenantId, invoiceId, recipientEmail });
-
-// Consumer: initialize scoped context from job data
-const worker = new Worker('emails', async (job) => {
-  const { tenantId, invoiceId } = job.data;
-  const invoices = new ScopedRepository(prisma.invoice, tenantId);
-  const invoice = await invoices.findMany({ id: invoiceId });
-  // process...
-});
-
-// GDPR export — stream all tenant data
-app.get('/api/tenants/:id/export', requireOwner, async (req, res) => {
-  const { id: tenantId } = req.params;
-  const [projects, members, invoices] = await Promise.all([
-    prisma.project.findMany({ where: { tenantId } }),
-    prisma.member.findMany({ where: { tenantId } }),
-    prisma.invoice.findMany({ where: { tenantId } }),
-  ]);
-  await prisma.auditLog.create({ data: { tenantId, action: 'DATA_EXPORT', actorId: req.user.id } });
-  res.setHeader('Content-Disposition', `attachment; filename="export-${tenantId}.json"`);
-  res.json({ exportedAt: new Date(), projects, members, invoices });
-});
-```
+---
+name: "multi-tenant"
+pack: "@rune/saas"
+description: "Multi-tenancy patterns — database isolation strategies, tenant context middleware, data partitioning, cross-tenant query prevention, tenant-aware background jobs, and GDPR data export."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# multi-tenant
+
+Multi-tenancy patterns — database isolation strategies, tenant context middleware, data partitioning, cross-tenant query prevention, tenant-aware background jobs, and GDPR data export.
+
+#### Isolation Strategy Comparison
+
+| Strategy | Cost | Isolation | Migration Difficulty | When to Use |
+|---|---|---|---|---|
+| Shared DB, tenant column | Low | Weak (app-enforced) | Easy | Early-stage, <1000 tenants |
+| Shared DB + PostgreSQL RLS | Low | Strong (DB-enforced) | Easy | Best default for most SaaS |
+| Schema-per-tenant | Medium | Strong | Medium | When tenants need schema customization |
+| DB-per-tenant | High | Perfect | Hard | Enterprise, compliance (HIPAA, SOC2) |
+
+#### Workflow
+
+**Step 1 — Detect current isolation strategy**
+Use Grep to find tenant-related code: `tenantId`, `organizationId`, `workspaceId`, `x-tenant-id` header, RLS policies, schema-per-tenant patterns, database switching logic. Read the database schema and middleware to classify the isolation strategy in use.
+
+**Step 2 — Audit isolation boundaries**
+Check for: queries without tenant filter (data leak risk), missing tenant context in middleware, no RLS policies on shared tables, admin endpoints that bypass tenant isolation, background jobs processing cross-tenant data without scoping. Flag each with severity.
+
+**Step 3 — Emit tenant-safe patterns**
+Based on detected strategy, emit: tenant middleware (extract from JWT/header, set on request context), RLS policies for shared-schema approach, scoped repository pattern that injects tenant filter on every query, and tenant-aware test fixtures.
+
+**Step 4 — Tenant-aware background jobs**
+Every background job MUST carry `tenantId`. Use BullMQ job data to pass tenant context, then initialize a scoped repository inside the job processor. Never process tenant data in a job without an explicit `tenantId` guard.
+
+**Step 5 — Tenant data export (GDPR portability)**
+Implement `/api/tenants/:id/export` that collects all data rows belonging to a tenant across all tables, serializes to JSON or CSV, and streams the result as a download. Log the export event in the audit trail with timestamp and requesting user.
+
+#### Example
+
+```typescript
+// Tenant middleware — extract from JWT, inject into request context
+const tenantMiddleware = async (req: Request, res: Response, next: NextFunction) => {
+  const tenantId = req.user?.tenantId ?? req.headers['x-tenant-id'] as string;
+  if (!tenantId) return res.status(403).json({ error: { code: 'TENANT_REQUIRED', message: 'Tenant context missing' } });
+  req.tenantId = tenantId;
+  next();
+};
+
+// Scoped repository — every query automatically filtered by tenant
+class ScopedRepository<T extends { tenantId: string }> {
+  constructor(private model: PrismaModel<T>, private tenantId: string) {}
+
+  async findMany(where: Partial<Omit<T, 'tenantId'>> = {}) {
+    return this.model.findMany({ where: { ...where, tenantId: this.tenantId } });
+  }
+
+  async create(data: Omit<T, 'tenantId' | 'id' | 'createdAt' | 'updatedAt'>) {
+    return this.model.create({ data: { ...data, tenantId: this.tenantId } as any });
+  }
+}
+
+// PostgreSQL RLS — DB-enforced isolation, safest approach
+-- Enable RLS on every shared table
+ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
+
+-- Set tenant context before query (from app middleware)
+SET LOCAL app.tenant_id = '550e8400-e29b-41d4-a716-446655440000';
+
+-- Policy reads from session variable — automatic for all queries
+CREATE POLICY tenant_isolation ON projects
+  USING (tenant_id = current_setting('app.tenant_id')::uuid);
+
+-- Set in Prisma $executeRaw before each query block:
+-- await prisma.$executeRaw`SELECT set_config('app.tenant_id', ${tenantId}, true)`;
+
+// BullMQ — tenant-aware background job
+const emailQueue = new Queue('emails');
+
+// Producer: always pass tenantId in job data
+await emailQueue.add('send-invoice', { tenantId, invoiceId, recipientEmail });
+
+// Consumer: initialize scoped context from job data
+const worker = new Worker('emails', async (job) => {
+  const { tenantId, invoiceId } = job.data;
+  const invoices = new ScopedRepository(prisma.invoice, tenantId);
+  const invoice = await invoices.findMany({ id: invoiceId });
+  // process...
+});
+
+// GDPR export — stream all tenant data
+app.get('/api/tenants/:id/export', requireOwner, async (req, res) => {
+  const { id: tenantId } = req.params;
+  const [projects, members, invoices] = await Promise.all([
+    prisma.project.findMany({ where: { tenantId } }),
+    prisma.member.findMany({ where: { tenantId } }),
+    prisma.invoice.findMany({ where: { tenantId } }),
+  ]);
+  await prisma.auditLog.create({ data: { tenantId, action: 'DATA_EXPORT', actorId: req.user.id } });
+  res.setHeader('Content-Disposition', `attachment; filename="export-${tenantId}.json"`);
+  res.json({ exportedAt: new Date(), projects, members, invoices });
+});
+```