everything-gemini 1.2.0 → 1.8.0

package/skills/redis-cache-patterns/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: redis-cache-patterns
+description: >-
+  Implements enterprise Redis caching strategies (cache-aside, write-through, stale-while-revalidate), distributed locking (Redlock), sliding-window rate limiting, and pub/sub streams.
+---
+
+# Redis Cache Patterns & Distributed Primitives
+
+This skill provides production-tested patterns for high-throughput Redis caching, concurrency coordination, and resilient distributed systems.
+
+---
+
+## 🚀 Key Patterns
+
+### 1. Cache-Aside with Jitter (Preventing Cache Stampedes)
+
+When calculating TTLs, always inject jitter (random variance) to prevent simultaneous mass-expiration of keys:
+
+```typescript
+import { Redis } from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL!);
+
+export async function getCachedEntity<T>(
+  key: string,
+  fetchFn: () => Promise<T>,
+  baseTtlSeconds: number = 3600
+): Promise<T> {
+  const cached = await redis.get(key);
+  if (cached) {
+    return JSON.parse(cached) as T;
+  }
+
+  const freshData = await fetchFn();
+  
+  // Inject 10-15% random jitter to distribute TTL expiration spikes
+  const jitter = Math.floor(Math.random() * (baseTtlSeconds * 0.15));
+  const ttl = baseTtlSeconds + jitter;
+
+  await redis.set(key, JSON.stringify(freshData), 'EX', ttl);
+  return freshData;
+}
+```
+
+---
+
+### 2. Distributed Locking with Safe Lua Release
+
+Never release a Redis lock with a plain `DEL` command, as doing so can accidentally delete a lock held by another process if the operation took longer than the TTL. Use atomic Lua verification:
+
+```typescript
+import { randomUUID } from 'crypto';
+
+const RELEASE_LOCK_SCRIPT = `
+  if redis.call("get", KEYS[1]) == ARGV[1] then
+    return redis.call("del", KEYS[1])
+  else
+    return 0
+  end
+`;
+
+export async function withDistributedLock<T>(
+  lockKey: string,
+  ttlMs: number,
+  task: () => Promise<T>
+): Promise<T> {
+  const lockToken = randomUUID();
+  const acquired = await redis.set(lockKey, lockToken, 'PX', ttlMs, 'NX');
+
+  if (!acquired) {
+    throw new Error(`Failed to acquire distributed lock for key: ${lockKey}`);
+  }
+
+  try {
+    return await task();
+  } finally {
+    // Atomically release only if the token matches
+    await redis.eval(RELEASE_LOCK_SCRIPT, 1, lockKey, lockToken);
+  }
+}
+```
+
+---
+
+### 3. Sliding-Window Rate Limiting (Sorted Sets)
+
+Sliding-window rate limiters prevent burst exploitation around window boundaries:
+
+```typescript
+export async function isRateLimited(
+  identifier: string,
+  limit: number,
+  windowSeconds: number
+): Promise<{ allowed: boolean; remaining: number }> {
+  const now = Date.now();
+  const clearBefore = now - windowSeconds * 1000;
+  const key = `ratelimit:${identifier}`;
+
+  const pipeline = redis.pipeline();
+  pipeline.zremrangebyscore(key, 0, clearBefore);
+  pipeline.zadd(key, now, `${now}-${Math.random()}`);
+  pipeline.zcard(key);
+  pipeline.expire(key, windowSeconds);
+
+  const results = await pipeline.exec();
+  const count = (results?.[2]?.[1] as number) || 0;
+
+  return {
+    allowed: count <= limit,
+    remaining: Math.max(0, limit - count),
+  };
+}
+```
+
+---
+
+### 4. Redis Streams with Consumer Groups
+
+For reliable, decoupled background tasks without message loss:
+
+```typescript
+// Producer: Append event to stream
+export async function publishEvent(streamName: string, event: Record<string, string>) {
+  return await redis.xadd(streamName, '*', ...Object.entries(event).flat());
+}
+
+// Consumer: Read events with acknowledgments
+export async function consumeEvents(
+  streamName: string,
+  groupName: string,
+  consumerName: string,
+  handler: (id: string, fields: string[]) => Promise<void>
+) {
+  const response = await redis.xreadgroup(
+    'GROUP', groupName, consumerName,
+    'COUNT', 10,
+    'BLOCK', 2000,
+    'STREAMS', streamName, '>'
+  );
+
+  if (!response) return;
+
+  for (const [, messages] of response as any[]) {
+    for (const [id, fields] of messages) {
+      await handler(id, fields);
+      // Acknowledge processed message
+      await redis.xack(streamName, groupName, id);
+    }
+  }
+}
+```
+
+---
+
+### 5. Memory & Performance Best Practices
+
+- **Structured Namespaces**: Use colons for domain hierarchy (e.g., `user:1042:profile`, `session:tok_9918`).
+- **Use Hashes for Objects**: Storing small objects in Redis `HSET` saves ~40% memory compared to JSON strings due to memory-efficient `ziplist`/`listpack` encodings.
+- **Always Configure Eviction Policy**: In `redis.conf`, set `maxmemory-policy volatile-lru` or `allkeys-lru` to avoid hard out-of-memory errors.

package/skills/svelte-kit-architect/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: svelte-kit-architect
+description: >-
+  Architects, builds, and optimizes modern SvelteKit web applications using Svelte 5 runes ($state, $derived, $effect), SSR/prerendering, form actions, and type-safe server load functions.
+---
+
+# SvelteKit Architect & Svelte 5 Mastery
+
+This skill guides the design, structure, and implementation of production SvelteKit applications utilizing modern Svelte 5 Runes, progressive enhancement, and robust server-side routing.
+
+---
+
+## ⚡ Svelte 5 Runes Modernization
+
+Svelte 5 replaces legacy `export let` and `$:` syntax with explicit, fine-grained reactivity runes:
+
+### 1. State, Derived & Props
+
+```svelte
+<script lang="ts">
+  interface Props {
+    title: string;
+    initialCount?: number;
+    onUpdate?: (val: number) => void;
+  }
+
+  // Props declaration with defaults
+  let { title, initialCount = 0, onUpdate }: Props = $props();
+
+  // Reactive state
+  let count = $state(initialCount);
+
+  // Derived computed values
+  let doubled = $derived(count * 2);
+
+  function increment() {
+    count += 1;
+    onUpdate?.(count);
+  }
+
+  // Side-effect cleanup
+  $effect(() => {
+    console.log(`Current count: ${count}`);
+    return () => console.log('Cleaning up effect');
+  });
+</script>
+
+<button onclick={increment}>
+  {title}: {count} (Doubled: {doubled})
+</button>
+```
+
+---
+
+## 📁 SvelteKit Routing & Data Loading
+
+### 1. Type-Safe Server Load Function (`+page.server.ts`)
+
+```typescript
+import type { PageServerLoad } from './$types';
+import { error } from '@sveltejs/kit';
+import { db } from '$lib/server/db';
+
+export const load: PageServerLoad = async ({ params, locals }) => {
+  const item = await db.item.findUnique({
+    where: { id: params.id },
+  });
+
+  if (!item) {
+    throw error(404, { message: 'Item not found' });
+  }
+
+  return {
+    item,
+    user: locals.user,
+  };
+};
+```
+
+### 2. Rendering Data in Component (`+page.svelte`)
+
+```svelte
+<script lang="ts">
+  import type { PageData } from './$types';
+
+  let { data }: { data: PageData } = $props();
+</script>
+
+<h1>{data.item.title}</h1>
+<p>Author: {data.user?.name ?? 'Anonymous'}</p>
+```
+
+---
+
+## 📝 Form Actions & Progressive Enhancement
+
+Handle mutations without client-side JavaScript dependency while maintaining smooth client transitions using `use:enhance`:
+
+### Server Action (`+page.server.ts`)
+
+```typescript
+import type { Actions } from './$types';
+import { fail } from '@sveltejs/kit';
+import { z } from 'zod';
+
+const schema = z.object({
+  email: z.string().email(),
+  comment: z.string().min(3),
+});
+
+export const actions: Actions = {
+  createComment: async ({ request }) => {
+    const formData = await request.formData();
+    const parsed = schema.safeParse(Object.fromEntries(formData));
+
+    if (!parsed.success) {
+      return fail(400, {
+        errors: parsed.error.flatten().fieldErrors,
+        values: Object.fromEntries(formData),
+      });
+    }
+
+    // Process mutation in database
+    return { success: true };
+  },
+};
+```
+
+### Form in Svelte Component (`+page.svelte`)
+
+```svelte
+<script lang="ts">
+  import { enhance } from '$app/forms';
+  import type { ActionData } from './$types';
+
+  let { form }: { form: ActionData } = $props();
+  let isSubmitting = $state(false);
+</script>
+
+<form
+  method="POST"
+  action="?/createComment"
+  use:enhance={() => {
+    isSubmitting = true;
+    return async ({ update }) => {
+      isSubmitting = false;
+      await update();
+    };
+  }}
+>
+  <input name="email" type="email" value={form?.values?.email ?? ''} required />
+  {#if form?.errors?.email}
+    <span class="error">{form.errors.email[0]}</span>
+  {/if}
+
+  <textarea name="comment" required></textarea>
+
+  <button type="submit" disabled={isSubmitting}>
+    {isSubmitting ? 'Submitting...' : 'Post Comment'}
+  </button>
+</form>
+```
+
+---
+
+## 🌐 Global Shared State with Rune Classes
+
+Use universal classes with `$state` for application-wide stores without legacy Svelte `writable`:
+
+```typescript
+// src/lib/stores/cart.svelte.ts
+export class CartStore {
+  items = $state<Array<{ id: string; qty: number }>>([]);
+
+  get totalItems() {
+    return this.items.reduce((sum, item) => sum + item.qty, 0);
+  }
+
+  addItem(id: string) {
+    const existing = this.items.find((i) => i.id === id);
+    if (existing) {
+      existing.qty += 1;
+    } else {
+      this.items.push({ id, qty: 1 });
+    }
+  }
+}
+
+export const cart = new CartStore();
+```

package/skills/temporal-workflows/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: temporal-workflows
+description: >-
+  Architects and implements fault-tolerant distributed workflows, retry policies, async activities, saga compensations, and child workflows using the Temporal TypeScript/Python SDK.
+---
+
+# Temporal Workflows & Resilient Distributed Orchestration
+
+This skill guides the design and implementation of bulletproof distributed workflows with Temporal, ensuring zero state loss during worker crashes, network partitions, or transient external API failures.
+
+---
+
+## ⚡ The Cardinal Rule: Workflow Determinism
+
+Workflows in Temporal are replayed from event history. Therefore, **workflow functions must be 100% deterministic**:
+
+| ❌ NEVER in Workflow Functions | ✅ ALWAYS in Activities or SDK Wrappers |
+| :--- | :--- |
+| `Date.now()`, `new Date()` | `workflow.currentTime()` |
+| `Math.random()`, `crypto.randomUUID()` | Pass random values as input or generate in Activities |
+| `fetch()`, database queries, file I/O | Isolate all network, disk, and DB calls inside Activities |
+| Mutable global variables, timers (`setTimeout`) | Use `workflow.sleep()` or `workflow.condition()` |
+
+---
+
+## 🏗️ Architecture: Workflows & Activities (TypeScript)
+
+### 1. Activities Definition (`activities.ts`)
+Activities handle all non-deterministic side effects and I/O:
+
+```typescript
+import { Context } from '@temporalio/activity';
+
+export async function chargePayment(customerId: string, amountCents: number): Promise<string> {
+  const { heartbeat } = Context.current();
+  heartbeat('Connecting to payment gateway');
+  
+  // Call external Stripe or payment API
+  const chargeId = await stripeClient.charges.create({ customer: customerId, amount: amountCents });
+  return chargeId;
+}
+
+export async function refundPayment(chargeId: string): Promise<void> {
+  await stripeClient.refunds.create({ charge: chargeId });
+}
+
+export async function provisionResource(tenantId: string): Promise<string> {
+  return await cloudProvider.provision(tenantId);
+}
+```
+
+---
+
+### 2. Workflow Orchestration with Saga Compensations (`workflows.ts`)
+
+```typescript
+import { proxyActivities, sleep, defineSignal, setHandler, condition } from '@temporalio/workflow';
+import type * as activities from './activities';
+
+// Configure activity timeouts and retry policies
+const { chargePayment, refundPayment, provisionResource } = proxyActivities<typeof activities>({
+  startToCloseTimeout: '1 minute',
+  retry: {
+    initialInterval: '2 seconds',
+    backoffCoefficient: 2,
+    maximumInterval: '1 minute',
+    maximumAttempts: 5,
+    nonRetryableErrorTypes: ['InvalidCardError', 'CustomerNotFoundError'],
+  },
+});
+
+export const cancelOrderSignal = defineSignal('cancelOrder');
+
+export async function orderFulfillmentWorkflow(order: { customerId: string; amount: number; tenantId: string }): Promise<string> {
+  const compensations: Array<() => Promise<void>> = [];
+  let isCancelled = false;
+
+  // Listen for external user cancellation signal
+  setHandler(cancelOrderSignal, () => {
+    isCancelled = true;
+  });
+
+  try {
+    // Step 1: Charge payment
+    const chargeId = await chargePayment(order.customerId, order.amount);
+    compensations.push(async () => await refundPayment(chargeId));
+
+    if (isCancelled) {
+      throw new Error('Order cancelled by user before provisioning');
+    }
+
+    // Step 2: Provision cloud resources
+    const resourceId = await provisionResource(order.tenantId);
+    return resourceId;
+
+  } catch (error) {
+    // SAGA Pattern: Execute compensations in reverse order
+    for (const compensate of compensations.reverse()) {
+      try {
+        await compensate();
+      } catch (compErr) {
+        // Log critical compensation failure for manual intervention
+      }
+    }
+    throw error;
+  }
+}
+```
+
+---
+
+## 🧪 Testing Workflows (`workflow.test.ts`)
+
+Test workflows without connecting to a remote Temporal server using `TestWorkflowEnvironment`:
+
+```typescript
+import { TestWorkflowEnvironment } from '@temporalio/testing';
+import { Worker } from '@temporalio/worker';
+import { orderFulfillmentWorkflow } from './workflows';
+
+describe('orderFulfillmentWorkflow', () => {
+  let testEnv: TestWorkflowEnvironment;
+
+  beforeAll(async () => {
+    testEnv = await TestWorkflowEnvironment.createTimeSkipping();
+  });
+
+  afterAll(async () => {
+    await testEnv?.teardown();
+  });
+
+  it('successfully completes workflow with mocked activities', async () => {
+    const { client, nativeConnection } = testEnv;
+    const taskQueue = 'test-queue';
+
+    const worker = await Worker.create({
+      connection: nativeConnection,
+      taskQueue,
+      workflowsPath: require.resolve('./workflows'),
+      activities: {
+        chargePayment: async () => 'ch_test_123',
+        refundPayment: async () => {},
+        provisionResource: async () => 'res_prod_999',
+      },
+    });
+
+    await worker.runUntil(async () => {
+      const handle = await client.workflow.start(orderFulfillmentWorkflow, {
+        args: [{ customerId: 'cust_1', amount: 5000, tenantId: 'ten_abc' }],
+        taskQueue,
+        workflowId: 'test-order-1',
+      });
+      const result = await handle.result();
+      expect(result).toBe('res_prod_999');
+    });
+  });
+});
+```

package/skills/trpc-react-query/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: trpc-react-query
+description: >-
+  Architects end-to-end type-safe APIs with tRPC v11 and TanStack React Query v5, implementing routers, context middlewares, mutations, and optimistic cache updates.
+---
+
+# tRPC v11 & TanStack React Query v5 Architecture
+
+This skill guides building end-to-end type-safe fullstack applications where frontend components get compile-time autocomplete and validation for backend routes without generating client SDKs.
+
+---
+
+## ⚡ Server-Side Router Architecture
+
+### 1. Initialization & Context (`trpc.ts`)
+
+```typescript
+import { initTRPC, TRPCError } from '@trpc/server';
+import superjson from 'superjson';
+import { type CreateNextContextOptions } from '@trpc/server/adapters/next';
+import { getAuthSession } from '$lib/auth';
+
+export async function createContext(opts?: CreateNextContextOptions) {
+  const session = await getAuthSession(opts?.req, opts?.res);
+  return { session, db };
+}
+
+type Context = Awaited<ReturnType<typeof createContext>>;
+
+const t = initTRPC.context<Context>().create({
+  transformer: superjson,
+  errorFormatter({ shape, error }) {
+    return {
+      ...shape,
+      data: {
+        ...shape.data,
+        zodError: error.cause instanceof ZodError ? error.cause.flatten() : null,
+      },
+    };
+  },
+});
+
+export const router = t.router;
+export const publicProcedure = t.procedure;
+
+// Protected Procedure Middleware
+export const protectedProcedure = t.procedure.use(async ({ ctx, next }) => {
+  if (!ctx.session?.user) {
+    throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Authentication required' });
+  }
+  return next({
+    ctx: {
+      ...ctx,
+      user: ctx.session.user,
+    },
+  });
+});
+```
+
+---
+
+### 2. Feature Subrouter with Input Validation (`routers/tasks.ts`)
+
+```typescript
+import { z } from 'zod';
+import { router, protectedProcedure } from '../trpc';
+
+export const taskRouter = router({
+  list: protectedProcedure
+    .input(
+      z.object({
+        status: z.enum(['pending', 'completed']).optional(),
+        limit: z.number().min(1).max(100).default(20),
+      })
+    )
+    .query(async ({ ctx, input }) => {
+      return await ctx.db.task.findMany({
+        where: { userId: ctx.user.id, ...(input.status && { status: input.status }) },
+        take: input.limit,
+        orderBy: { createdAt: 'desc' },
+      });
+    }),
+
+  toggleStatus: protectedProcedure
+    .input(z.object({ id: z.string().uuid(), completed: z.boolean() }))
+    .mutation(async ({ ctx, input }) => {
+      return await ctx.db.task.update({
+        where: { id: input.id, userId: ctx.user.id },
+        data: { completed: input.completed },
+      });
+    }),
+});
+```
+
+---
+
+## 🌐 Client-Side React Query Integration
+
+### 1. Optimistic UI Updates (`TaskList.tsx`)
+
+Render instant UI updates while the network request is inflight, reverting cleanly if an error occurs:
+
+```tsx
+import { trpc } from '@/utils/trpc';
+
+export function TaskItem({ task }: { task: Task }) {
+  const utils = trpc.useUtils();
+
+  const toggleMutation = trpc.task.toggleStatus.useMutation({
+    onMutate: async (variables) => {
+      // 1. Cancel ongoing queries for list
+      await utils.task.list.cancel();
+
+      // 2. Snapshot previous cache value
+      const previousTasks = utils.task.list.getData();
+
+      // 3. Optimistically update client cache
+      utils.task.list.setData(undefined, (old) =>
+        old?.map((t) => (t.id === variables.id ? { ...t, completed: variables.completed } : t))
+      );
+
+      return { previousTasks };
+    },
+    onError: (err, variables, context) => {
+      // 4. Rollback cache upon mutation failure
+      if (context?.previousTasks) {
+        utils.task.list.setData(undefined, context.previousTasks);
+      }
+    },
+    onSettled: () => {
+      // 5. Invalidate and synchronize with source of truth
+      utils.task.list.invalidate();
+    },
+  });
+
+  return (
+    <div>
+      <input
+        type="checkbox"
+        checked={task.completed}
+        onChange={(e) => toggleMutation.mutate({ id: task.id, completed: e.target.checked })}
+      />
+      <span>{task.title}</span>
+    </div>
+  );
+}
+```
+
+---
+
+## 🚀 Server-Side Prefetching (Next.js App Router / SSR)
+
+```typescript
+import { createServerSideHelpers } from '@trpc/react-query/server';
+import { appRouter } from '@/server/routers/_app';
+import { createContext } from '@/server/trpc';
+import SuperJSON from 'superjson';
+
+export async function prefetchTasks() {
+  const helpers = createServerSideHelpers({
+    router: appRouter,
+    ctx: await createContext(),
+    transformer: SuperJSON,
+  });
+
+  await helpers.task.list.prefetch({ limit: 20 });
+  return helpers.dehydrate();
+}
+```