@raftlabs/raftstack 1.6.3 → 1.7.1

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
 

package/dist/cli.js

@@ -1598,15 +1598,18 @@ function getPackageSkillsDir() {
   const packageRoot = join15(dirname2(currentFilePath), "..");
   return join15(packageRoot, ".claude", "skills");
 }
-async function copyDirectory(srcDir, destDir, result, baseDir) {
+async function copyDirectory(srcDir, destDir, result, baseDir, skipDirs) {
   await ensureDir(destDir);
   const entries = await readdir(srcDir, { withFileTypes: true });
   for (const entry of entries) {
+    if (skipDirs && entry.isDirectory() && skipDirs.includes(entry.name)) {
+      continue;
+    }
     const srcPath = join15(srcDir, entry.name);
     const destPath = join15(destDir, entry.name);
     const relativePath = destPath.replace(baseDir + "/", "");
     if (entry.isDirectory()) {
-      await copyDirectory(srcPath, destPath, result, baseDir);
+      await copyDirectory(srcPath, destPath, result, baseDir, skipDirs);
     } else {
       if (existsSync5(destPath)) {
         const backupPath = await backupFile(destPath);
@@ -1619,7 +1622,7 @@ async function copyDirectory(srcDir, destDir, result, baseDir) {
     }
   }
 }
-async function generateClaudeSkills(targetDir) {
+async function generateClaudeSkills(targetDir, options) {
   const result = {
     created: [],
     modified: [],
@@ -1635,7 +1638,11 @@ async function generateClaudeSkills(targetDir) {
     return result;
   }
   await ensureDir(join15(targetDir, ".claude"));
-  await copyDirectory(packageSkillsDir, targetSkillsDir, result, targetDir);
+  const skipDirs = [];
+  if (!options?.includeAsana) {
+    skipDirs.push("asana");
+  }
+  await copyDirectory(packageSkillsDir, targetSkillsDir, result, targetDir, skipDirs);
   return result;
 }
 
@@ -2201,7 +2208,9 @@ async function runInit(targetDir = process.cwd()) {
       await generateContributing(targetDir, !!config.asanaBaseUrl, config.packageManager)
     );
     results.push(await generateQuickReference(targetDir, config.packageManager));
-    results.push(await generateClaudeSkills(targetDir));
+    results.push(await generateClaudeSkills(targetDir, {
+      includeAsana: !!config.asanaBaseUrl
+    }));
     results.push(await updateProjectPackageJson(targetDir, config));
     spinner4.stop("Configuration files generated!");
   } catch (error) {
@@ -2662,7 +2671,7 @@ ${pc4.bold("Branches")}
 // package.json
 var package_default = {
   name: "@raftlabs/raftstack",
-  version: "1.6.3",
+  version: "1.7.1",
   description: "CLI tool for setting up Git hooks, commit conventions, and GitHub integration",
   type: "module",
   main: "./dist/index.js",