@raftlabs/raftstack 1.7.0 → 1.7.2

package/.claude/skills/backend/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: backend
-description: Use when writing serverless functions, API handlers, backend services, or when code has tight coupling to infrastructure, no dependency injection, or mixed concerns
+description: Use when writing Lambda functions, API routes, Hono handlers, Express routes, serverless endpoints, or backend services. Use when creating API validation with Zod, implementing service layers, or structuring handler code.
 ---
 
 # Backend Development
@@ -578,6 +578,135 @@ export const handler = compose(
 )(baseHandler);
 ```
 
+## Hono.js Patterns
+
+Hono is a fast, lightweight framework for serverless and edge. Same patterns apply - layer separation, DI, Zod validation.
+
+### Basic Hono Handler with Zod
+
+```typescript
+import { Hono } from 'hono';
+import { zValidator } from '@hono/zod-validator';
+import { z } from 'zod';
+
+const app = new Hono();
+
+const CreateUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1),
+});
+
+// ✅ GOOD: Validation middleware + typed body
+app.post(
+  '/users',
+  zValidator('json', CreateUserSchema),
+  async (c) => {
+    const body = c.req.valid('json'); // Typed as { email: string; name: string }
+    const user = await userService.createUser(body);
+    return c.json(user, 201);
+  }
+);
+```
+
+### Hono with Dependency Injection
+
+```typescript
+// ✅ GOOD: Factory pattern for testable Hono apps
+import { Hono } from 'hono';
+
+export function createApp(deps: {
+  userService: UserService;
+  authService: AuthService;
+}) {
+  const app = new Hono();
+
+  app.post('/users', async (c) => {
+    const body = await c.req.json();
+    const user = await deps.userService.createUser(body);
+    return c.json(user, 201);
+  });
+
+  app.post('/login', async (c) => {
+    const { email, password } = await c.req.json();
+    const token = await deps.authService.login(email, password);
+    return c.json({ token });
+  });
+
+  return app;
+}
+
+// Production: inject real services
+const app = createApp({
+  userService: createUserService(db),
+  authService: createAuthService(db),
+});
+
+export default app;
+
+// Test: inject mocks
+const testApp = createApp({
+  userService: { createUser: vi.fn() },
+  authService: { login: vi.fn() },
+});
+```
+
+### Hono Error Handling Middleware
+
+```typescript
+import { Hono } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+
+const app = new Hono();
+
+// Global error handler
+app.onError((err, c) => {
+  if (err instanceof AppError) {
+    return c.json(
+      { error: err.message, code: err.code },
+      err.statusCode
+    );
+  }
+
+  if (err instanceof HTTPException) {
+    return c.json({ error: err.message }, err.status);
+  }
+
+  console.error('Unexpected error:', err);
+  return c.json({ error: 'Internal server error' }, 500);
+});
+
+// Route handlers throw AppError
+app.get('/users/:id', async (c) => {
+  const user = await userService.getUser(c.req.param('id'));
+  if (!user) {
+    throw new NotFoundError('User not found');
+  }
+  return c.json(user);
+});
+```
+
+### Hono Middleware Composition
+
+```typescript
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { logger } from 'hono/logger';
+import { jwt } from 'hono/jwt';
+
+const app = new Hono();
+
+// Apply middleware in order
+app.use('*', logger());
+app.use('*', cors());
+app.use('/api/*', jwt({ secret: process.env.JWT_SECRET }));
+
+// Protected routes
+app.get('/api/me', (c) => {
+  const payload = c.get('jwtPayload');
+  return c.json({ userId: payload.sub });
+});
+```
+
 ## Testing Strategy
 
 | What to Test | How |
@@ -735,6 +864,7 @@ describe('Handler', () => {
 ## References
 
 - [Zod Documentation](https://zod.dev) - Validation, transforms, error formatting, branded types
+- [Hono Documentation](https://hono.dev) - Lightweight framework for serverless and edge
 - [Vitest Documentation](https://vitest.dev) - Testing, mocking, vi.fn(), vi.spyOn()
 - [AWS Lambda Cold Starts](https://aws.amazon.com/blogs/compute/understanding-and-remediating-cold-starts-an-aws-lambda-perspective/) - Official optimization guide
 - [AWS Lambda Performance](https://aws.amazon.com/blogs/compute/operating-lambda-performance-optimization-part-1/) - Best practices
@@ -742,6 +872,7 @@ describe('Handler', () => {
 **Version Notes:**
 - Zod v3.24+: Improved error formatting, discriminated unions, branded types
 - Zod v4.0+: prefault(), enhanced pipe(), performance improvements
+- Hono v4+: Stable, edge-ready, built-in middleware
 - Vitest v3+: mockResolvedValue, mockRejectedValue patterns
 - AWS Lambda: Node.js 20.x has faster cold starts than 18.x
 

package/.claude/skills/code-quality/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-quality
-description: Use when writing or reviewing code, creating functions, naming variables, structuring files, or when code feels messy, hard to read, or overly complex
+description: Use when refactoring functions, extracting helpers, splitting large files, improving naming conventions, or reducing complexity. Use when functions exceed 30 lines, have too many parameters, or contain magic numbers. NOT for React/backend/database-specific patterns.
 ---
 
 # Code Quality
@@ -141,46 +141,59 @@ if (user.role === 'admin') { }
 
 ## Automated Enforcement
 
-### ESLint Configuration
+### ESLint Configuration (Flat Config - v9+)
 
-Enforce code quality with automated tools:
+ESLint 9+ uses flat config (`eslint.config.js`). Enforce code quality automatically:
 
 ```javascript
-// .eslintrc.js
-module.exports = {
-  rules: {
-    // Max function length
-    'max-lines-per-function': ['error', {
-      max: 30,
-      skipBlankLines: true,
-      skipComments: true,
-    }],
-
-    // Cyclomatic complexity
-    'complexity': ['error', { max: 10 }],
-
-    // Max file length
-    'max-lines': ['error', {
-      max: 300,
-      skipBlankLines: true,
-      skipComments: true,
-    }],
-
-    // Max function params
-    'max-params': ['error', 3],
-
-    // Max nested callbacks
-    'max-nested-callbacks': ['error', 2],
-
-    // No magic numbers
-    'no-magic-numbers': ['error', {
-      ignore: [0, 1, -1],
-      ignoreArrayIndexes: true,
-    }],
+// eslint.config.js (ESLint v9+ flat config)
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    rules: {
+      // Max function length
+      'max-lines-per-function': ['error', {
+        max: 30,
+        skipBlankLines: true,
+        skipComments: true,
+      }],
+
+      // Cyclomatic complexity
+      'complexity': ['error', { max: 10 }],
+
+      // Max file length
+      'max-lines': ['error', {
+        max: 300,
+        skipBlankLines: true,
+        skipComments: true,
+      }],
+
+      // Max function params
+      'max-params': ['error', 3],
+
+      // Max nested callbacks
+      'max-nested-callbacks': ['error', 2],
+
+      // No magic numbers
+      'no-magic-numbers': ['error', {
+        ignore: [0, 1, -1],
+        ignoreArrayIndexes: true,
+      }],
+    },
   },
-};
+  {
+    // Ignore patterns (replaces .eslintignore)
+    ignores: ['node_modules/', 'dist/', '*.config.js'],
+  }
+);
 ```
 
+**Legacy config?** ESLint 9+ still supports `.eslintrc.js` via `ESLINT_USE_FLAT_CONFIG=false`, but flat config is the future.
+
 ### TypeScript-Specific Patterns
 
 ```typescript
@@ -294,14 +307,16 @@ When someone says "just make it work fast":
 
 ## References
 
+- [ESLint Flat Config](https://eslint.org/docs/latest/use/configure/configuration-files-new) - ESLint 9+ configuration
 - [ESLint Complexity Rule](https://eslint.org/docs/latest/rules/complexity) - Cyclomatic complexity enforcement
-- [ESLintCC](https://eslintcc.github.io/) - Complexity measurement tool
+- [typescript-eslint](https://typescript-eslint.io/) - TypeScript ESLint integration
 - [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/) - Advanced type patterns
 - [Clean Code (Martin)](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882) - Function length rationale
 
 **Version Notes:**
-- ESLint 9+: Flat config format, enhanced rule options
-- TypeScript 5+: Improved discriminated union narrowing
+- ESLint 9+: Flat config (`eslint.config.js`), replaces `.eslintrc.*`
+- TypeScript 5+: Improved discriminated union narrowing, const type parameters
+- typescript-eslint 8+: Native flat config support
 - Cyclomatic complexity: Default threshold 20, recommended 10
 
 ## Common Mistakes

package/.claude/skills/database/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: database
-description: Use when designing database schemas, writing Drizzle ORM code, creating tables, choosing indexes, or when queries are slow and indexes might be missing
+description: Use when writing Drizzle ORM schemas, creating database tables, adding indexes, writing SQL migrations, defining relations, or optimizing PostgreSQL queries. Use for foreign key indexes, JSONB columns, composite indexes, or prepared statements.
 ---
 
 # Database Development
@@ -125,20 +125,66 @@ export const users = pgTable("users", {
 | Strategy | Use When | Pros | Cons |
 |----------|----------|------|------|
 | **UUID** | Distributed systems, public IDs | No collisions, hide growth | Larger, slower indexes |
-| **Serial/bigserial** | Single DB, internal IDs | Compact, fast | Exposes growth, sequence issues |
+| **Identity** | Single DB, internal IDs (2025+) | Compact, fast, SQL standard | Exposes growth |
 | **ULID/NanoID** | Need sortability + randomness | Sortable, compact | Custom generation |
 
 ```typescript
-// UUID (default recommendation)
+// UUID (default for distributed/public IDs)
 id: uuid("id").defaultRandom().primaryKey(),
 
-// Serial for internal/analytics tables
-id: serial("id").primaryKey(),
+// ✅ GOOD: Identity columns (PostgreSQL 10+, preferred over serial)
+id: integer("id").primaryKey().generatedAlwaysAsIdentity(),
+
+// For bigint IDs
+id: bigint("id", { mode: "number" }).primaryKey().generatedAlwaysAsIdentity(),
+
+// ❌ AVOID: Serial (legacy, has sequence ownership issues)
+id: serial("id").primaryKey(), // Use identity instead
 
 // ULID for sortable + random
 id: varchar("id", { length: 26 }).primaryKey().$default(() => ulid()),
 ```
 
+**Why Identity over Serial:**
+- SQL standard (serial is PostgreSQL-specific)
+- No sequence ownership issues during migrations
+- Better `COPY` and `pg_dump` behavior
+- Cannot be overwritten accidentally (`GENERATED ALWAYS`)
+
+### 7. Full-Text Search with GIN
+
+For searchable text columns, use PostgreSQL's built-in full-text search:
+
+```typescript
+import { sql } from "drizzle-orm";
+import { index, pgTable, text, tsvector } from "drizzle-orm/pg-core";
+
+export const products = pgTable("products", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  name: varchar("name", { length: 255 }).notNull(),
+  description: text("description"),
+  // Generated tsvector column for search
+  searchVector: tsvector("search_vector").generatedAlwaysAs(
+    sql`to_tsvector('english', coalesce(${products.name}, '') || ' ' || coalesce(${products.description}, ''))`
+  ),
+}, (table) => ({
+  // GIN index for fast full-text search
+  searchIdx: index("products_search_idx").using("gin", table.searchVector),
+}));
+
+// Query with full-text search
+const results = await db
+  .select()
+  .from(products)
+  .where(sql`${products.searchVector} @@ plainto_tsquery('english', ${query})`);
+```
+
+**Key patterns:**
+- Use `tsvector` for searchable content
+- `generatedAlwaysAs` auto-updates on row changes
+- GIN index makes searches fast (vs sequential scan)
+- `plainto_tsquery` for simple user queries
+
 ## Migration Strategy
 
 ### Generate vs Push
@@ -429,11 +475,14 @@ if (duration > 100) {
 
 - [Drizzle ORM Documentation](https://orm.drizzle.team/docs/overview) - Relations, prepared statements, migrations
 - [PostgreSQL Indexes](https://www.postgresql.org/docs/current/indexes.html) - Index types and usage
+- [PostgreSQL Full-Text Search](https://www.postgresql.org/docs/current/textsearch.html) - tsvector, GIN indexes
 - [Drizzle Kit](https://orm.drizzle.team/docs/kit-overview) - Migration management
 
 **Version Notes:**
-- Drizzle ORM 0.30+: Improved relations API
+- Drizzle ORM 0.30+: Improved relations API, identity column support
 - Drizzle Kit 0.20+: Enhanced migration generation
+- PostgreSQL 10+: Identity columns (prefer over serial)
+- PostgreSQL 15+: Improved JSON and full-text performance
 
 ## Red Flags - STOP and Add Indexes
 

package/.claude/skills/react/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: react
-description: Use when writing React components, using hooks, handling state, working with Next.js/Remix/Vite/Astro, or when components feel bloated, have unnecessary re-renders, or violate single responsibility
+description: Use when writing React components, creating hooks, using useState/useEffect/useReducer, building Next.js pages, implementing Server Components or Client Components, working with Remix loaders, Astro islands, or Vite SPA. Use for React performance issues, re-render problems, or component refactoring.
 ---
 
 # React Development
@@ -229,6 +229,60 @@ export function SignupForm() {
 
 ## React 19 Features
 
+### React Compiler (Auto-Memoization)
+
+React Compiler automatically adds memoization - no more manual `useMemo`, `useCallback`, or `React.memo`.
+
+```typescript
+// ❌ OLD: Manual memoization everywhere
+const MemoizedComponent = React.memo(({ user }) => {
+  const formattedName = useMemo(() => formatName(user), [user]);
+  const handleClick = useCallback(() => saveUser(user), [user]);
+  return <button onClick={handleClick}>{formattedName}</button>;
+});
+
+// ✅ NEW: React Compiler handles it automatically
+function UserButton({ user }) {
+  const formattedName = formatName(user);
+  const handleClick = () => saveUser(user);
+  return <button onClick={handleClick}>{formattedName}</button>;
+}
+// Compiler adds memoization during build - 25-40% fewer re-renders
+```
+
+**Key benefits:**
+- No manual memoization needed
+- Reduces bundle size (no memo wrappers)
+- 25-40% fewer re-renders in typical apps
+- Works with existing React 19 codebases
+
+**Enable in Next.js 15+:**
+```javascript
+// next.config.js
+module.exports = {
+  experimental: {
+    reactCompiler: true,
+  },
+};
+```
+
+### Server/Client Component Decision Tree
+
+```
+Need this in the component?
+├── Event handlers (onClick, onChange) → 'use client'
+├── useState, useEffect, useReducer → 'use client'
+├── Browser APIs (localStorage, window) → 'use client'
+├── Third-party client libs (charts, maps) → 'use client'
+│
+├── Data fetching from DB/API → Server Component ✅
+├── Access backend resources → Server Component ✅
+├── Keep sensitive data (tokens, keys) → Server Component ✅
+└── Reduce client bundle → Server Component ✅
+```
+
+**Rule of thumb:** Start with Server Components. Only add 'use client' when you hit a boundary that requires it.
+
 ### use() Hook - Read Promises/Context
 
 ```typescript
@@ -279,6 +333,59 @@ function TodoList({ todos }: { todos: Todo[] }) {
 
 **Auto-reverts on error** - no manual rollback needed.
 
+### Partial Pre-rendering (PPR) - Next.js 15+
+
+Combine static shell with dynamic content in a single request:
+
+```typescript
+// app/products/[id]/page.tsx
+import { Suspense } from 'react';
+
+// Static shell - pre-rendered at build time
+export default async function ProductPage({ params }) {
+  const product = await getProduct(params.id); // Cached/static
+
+  return (
+    <div>
+      {/* Static content - instant load */}
+      <h1>{product.name}</h1>
+      <p>{product.description}</p>
+
+      {/* Dynamic content - streams in */}
+      <Suspense fallback={<PriceSkeleton />}>
+        <DynamicPrice productId={params.id} />
+      </Suspense>
+
+      <Suspense fallback={<InventorySkeleton />}>
+        <InventoryStatus productId={params.id} />
+      </Suspense>
+    </div>
+  );
+}
+
+// Dynamic component - fetches real-time data
+async function DynamicPrice({ productId }) {
+  const price = await getCurrentPrice(productId); // Always fresh
+  return <span className="price">${price}</span>;
+}
+```
+
+**Enable PPR:**
+```javascript
+// next.config.js
+module.exports = {
+  experimental: {
+    ppr: true,
+  },
+};
+```
+
+**Benefits:**
+- Static shell loads instantly (like SSG)
+- Dynamic parts stream in (like SSR)
+- Best of both worlds in one request
+- No full-page waterfall
+
 ## Streaming & Suspense
 
 ### Full Page Streaming with loading.tsx
@@ -384,12 +491,15 @@ test('shows fallback then content', async () => {
 
 - [Next.js Documentation](https://nextjs.org/docs) - App Router, Server Components, Server Actions
 - [React 19 Release](https://react.dev/blog/2024/12/05/react-19) - use(), useActionState, useOptimistic
+- [React Compiler](https://react.dev/learn/react-compiler) - Auto-memoization setup and usage
 - [React Server Components](https://react.dev/reference/rsc/server-components) - Official RSC guide
 
 **Version Notes:**
 - Next.js 14+: App Router stable, Server Actions stable
-- Next.js 15: Enhanced caching, Turbopack, React 19 support
+- Next.js 15: Turbopack stable, React Compiler support, PPR experimental
 - React 19: use(), Actions, useOptimistic, useActionState
+- React 19.2+: Partial Pre-rendering (PPR), enhanced Suspense
+- React Compiler: Auto-memoization, 25-40% fewer re-renders
 
 ## Red Flags - STOP and Restructure
 

package/.claude/skills/seo/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: seo
-description: Use when creating web pages, adding metadata, optimizing Core Web Vitals, implementing structured data, or when pages aren't ranking or showing rich snippets in Google
+description: Use when adding page metadata, implementing OpenGraph tags, creating JSON-LD structured data, generating sitemaps, optimizing LCP/INP/CLS, or configuring robots.txt. Use for Next.js Metadata API, Article/Product/FAQ schemas, or image optimization with next/image.
 ---
 
 # SEO Optimization
@@ -128,6 +128,35 @@ input.addEventListener('input', (e) => {
 
 ### 2. Use Next.js Metadata API Correctly
 
+#### Root Layout: metadataBase + title.template
+
+**Critical:** Set `metadataBase` in your root layout. Without it, relative OG image URLs break.
+
+```typescript
+// app/layout.tsx
+import { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  metadataBase: new URL('https://site.com'), // REQUIRED for OG images
+  title: {
+    default: 'Brand Name',
+    template: '%s | Brand Name', // Auto-appends to all pages
+  },
+  description: 'Default site description',
+  openGraph: {
+    siteName: 'Brand Name',
+    locale: 'en_US',
+    type: 'website',
+  },
+};
+```
+
+**Why metadataBase matters:**
+- Without it: `images: ['/og.png']` → broken URL
+- With it: `images: ['/og.png']` → `https://site.com/og.png`
+
+#### Page-Level Metadata
+
 ```typescript
 // app/products/[slug]/page.tsx
 import { Metadata } from 'next';
@@ -136,11 +165,11 @@ export async function generateMetadata({ params }): Promise<Metadata> {
   const product = await getProduct(params.slug);
 
   return {
-    title: `${product.name} | Brand - $${product.price}`,
+    title: product.name, // Becomes "Product Name | Brand Name" via template
     description: truncate(product.description, 155), // Max 155 chars
 
     alternates: {
-      canonical: `https://site.com/products/${product.slug}`,
+      canonical: `/products/${product.slug}`, // Relative OK with metadataBase
     },
 
     // OpenGraph - use 'product' for e-commerce
@@ -278,6 +307,87 @@ const faqJsonLd = {
 };
 ```
 
+#### BreadcrumbList Schema
+
+Shows breadcrumb trail in search results:
+
+```typescript
+const breadcrumbJsonLd = {
+  '@context': 'https://schema.org',
+  '@type': 'BreadcrumbList',
+  itemListElement: [
+    {
+      '@type': 'ListItem',
+      position: 1,
+      name: 'Home',
+      item: 'https://site.com',
+    },
+    {
+      '@type': 'ListItem',
+      position: 2,
+      name: 'Products',
+      item: 'https://site.com/products',
+    },
+    {
+      '@type': 'ListItem',
+      position: 3,
+      name: product.name,
+      item: `https://site.com/products/${product.slug}`,
+    },
+  ],
+};
+```
+
+### 6. Answer Engine Optimization (AEO)
+
+AI search engines (ChatGPT, Perplexity, Claude) are becoming traffic sources. Optimize for them:
+
+**Key AEO strategies:**
+
+| Strategy | Implementation |
+|----------|----------------|
+| **FAQ sections** | Add FAQPage schema - AI pulls from structured Q&A |
+| **Direct answers** | Start content with clear, factual statements |
+| **Structured data** | Schema.org markup helps AI understand content |
+| **Topic authority** | Comprehensive coverage on topic clusters |
+| **Citation-friendly** | Include stats, dates, sources that AI can cite |
+
+```typescript
+// ✅ GOOD: Content structure for AI search
+function ProductPage({ product }) {
+  return (
+    <>
+      {/* Direct answer for AI to extract */}
+      <p className="lead">
+        The {product.name} is a {product.category} that {product.keyBenefit}.
+        Priced at ${product.price}, it's ideal for {product.targetAudience}.
+      </p>
+
+      {/* FAQ section with schema */}
+      <section>
+        <h2>Frequently Asked Questions</h2>
+        {product.faqs.map(faq => (
+          <details key={faq.id}>
+            <summary>{faq.question}</summary>
+            <p>{faq.answer}</p>
+          </details>
+        ))}
+      </section>
+
+      {/* Structured data for both Google and AI */}
+      <JsonLd data={productJsonLd} />
+      <JsonLd data={faqJsonLd} />
+    </>
+  );
+}
+```
+
+**Why AEO matters:**
+- 40% of Gen Z uses TikTok/AI for search over Google
+- AI search engines cite well-structured content
+- FAQ sections appear in AI answers
+- Structured data = machine-readable = AI-friendly
+
 ## Sitemap & Robots
 
 ### Dynamic Sitemap Generation
@@ -408,13 +518,15 @@ new PerformanceObserver((list) => {
 - [Core Web Vitals INP Guide](https://web.dev/articles/inp) - Official INP optimization patterns
 - [Optimize INP](https://web.dev/articles/optimize-inp) - Three-phase optimization approach
 - [Next.js Image Component](https://nextjs.org/docs/app/api-reference/components/image) - priority, placeholder, sizes
-- [Next.js Metadata API](https://nextjs.org/docs/app/api-reference/functions/generate-metadata) - generateMetadata patterns
+- [Next.js Metadata API](https://nextjs.org/docs/app/api-reference/functions/generate-metadata) - generateMetadata, metadataBase
 - [Schema.org](https://schema.org/) - Structured data vocabulary
+- [Rich Results Test](https://search.google.com/test/rich-results) - Validate structured data
 
 **Version Notes:**
 - INP replaced FID as Core Web Vital (March 2024)
-- Next.js 15: Enhanced Image component with automatic blur
+- Next.js 15: Enhanced Image component, metadataBase required for OG
 - Good INP: < 200ms (improving from 500ms → 200ms = 22% engagement boost)
+- AEO emerging: AI search engines (ChatGPT, Perplexity) use structured data
 
 ## Red Flags - STOP and Fix