@mars-stack/cli 0.2.0 → 1.0.2

package/template/.cursor/skills/configure-search/SKILL.md

@@ -0,0 +1,581 @@
+# Skill: Configure Search
+
+Set up search functionality in a MARS application using Postgres full-text search, Algolia, or Meilisearch.
+
+## When to Use
+
+Use this skill when the user asks to add search, full-text search, search bar, autocomplete, or indexing (e.g., "add search to the app", "let users search posts", "add Algolia").
+
+## Prerequisites
+
+- `appConfig.services.search.provider` set to `'postgres'`, `'algolia'`, or `'meilisearch'`
+- For Algolia/Meilisearch: an account with the respective provider
+- At least one Prisma model with searchable text fields
+
+## Provider Interface
+
+All providers implement a common interface:
+
+```typescript
+// src/features/search/types.ts
+export interface SearchResult<T = Record<string, unknown>> {
+  id: string;
+  score: number;
+  data: T;
+}
+
+export interface SearchOptions {
+  model: string;
+  page?: number;
+  limit?: number;
+}
+
+export interface SearchProvider {
+  search(query: string, options: SearchOptions): Promise<{
+    results: SearchResult[];
+    total: number;
+    page: number;
+    totalPages: number;
+  }>;
+  index(model: string, id: string, data: Record<string, unknown>): Promise<void>;
+  remove(model: string, id: string): Promise<void>;
+}
+```
+
+---
+
+## Option A: Postgres Full-Text Search
+
+No external dependencies. Uses PostgreSQL's built-in `tsvector` and `tsquery` capabilities.
+
+### Step 1: Add GIN Index to Prisma Schema
+
+Prisma does not natively support `tsvector` columns, so use a raw migration. First, add a standard index as a placeholder, then apply a raw SQL migration.
+
+```prisma
+// In your model's .prisma file, add a comment for reference:
+// Full-text search index applied via migration (see Step 2)
+```
+
+### Step 2: Create Raw SQL Migration
+
+```bash
+yarn prisma migrate dev --name add-search-index --create-only
+```
+
+Edit the generated migration SQL:
+
+```sql
+-- Add tsvector column and GIN index for full-text search
+ALTER TABLE "Post" ADD COLUMN IF NOT EXISTS search_vector tsvector
+  GENERATED ALWAYS AS (
+    setweight(to_tsvector('english', coalesce(title, '')), 'A') ||
+    setweight(to_tsvector('english', coalesce(body, '')), 'B')
+  ) STORED;
+
+CREATE INDEX IF NOT EXISTS "Post_search_vector_idx" ON "Post" USING GIN (search_vector);
+```
+
+Then apply: `yarn prisma migrate dev`
+
+### Step 3: Search Service
+
+```typescript
+// src/features/search/server/postgres.ts
+import 'server-only';
+
+import { prisma } from '@/lib/prisma';
+import { Prisma } from '@db';
+import type { SearchResult, SearchOptions } from '@/features/search/types';
+
+function sanitizeQuery(query: string): string {
+  return query
+    .replace(/[^\w\s]/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .join(' & ');
+}
+
+export async function searchPostgres(
+  query: string,
+  options: SearchOptions,
+): Promise<{ results: SearchResult[]; total: number; page: number; totalPages: number }> {
+  const { model, page = 1, limit = 20 } = options;
+  const sanitized = sanitizeQuery(query);
+
+  if (!sanitized) {
+    return { results: [], total: 0, page, totalPages: 0 };
+  }
+
+  const offset = (page - 1) * limit;
+  const tableName = Prisma.raw(`"${model}"`);
+
+  const results = await prisma.$queryRaw<Array<{ id: string; rank: number }>>`
+    SELECT id, ts_rank(search_vector, plainto_tsquery('english', ${sanitized})) AS rank
+    FROM ${tableName}
+    WHERE search_vector @@ plainto_tsquery('english', ${sanitized})
+    ORDER BY rank DESC
+    LIMIT ${limit}
+    OFFSET ${offset}
+  `;
+
+  const countResult = await prisma.$queryRaw<[{ count: bigint }]>`
+    SELECT COUNT(*) as count
+    FROM ${tableName}
+    WHERE search_vector @@ plainto_tsquery('english', ${sanitized})
+  `;
+
+  const total = Number(countResult[0].count);
+
+  return {
+    results: results.map((r) => ({ id: r.id, score: r.rank, data: r as Record<string, unknown> })),
+    total,
+    page,
+    totalPages: Math.ceil(total / limit),
+  };
+}
+```
+
+Key rules:
+- Always sanitize input to prevent SQL injection -- strip non-word characters and join with `&` for AND semantics.
+- Use `plainto_tsquery` for user-facing search (safer than `to_tsquery`).
+- Use `ts_rank` for relevance scoring.
+- Weighted columns: `'A'` weight for titles, `'B'` for body text.
+
+---
+
+## Option B: Algolia
+
+### Step 1: Install Algolia
+
+```bash
+yarn add algoliasearch
+```
+
+### Step 2: Environment Variables
+
+```bash
+# Server-side (secret -- never expose to client)
+ALGOLIA_APP_ID="your-app-id"
+ALGOLIA_API_KEY="your-admin-api-key"
+
+# Client-side (search-only key -- safe to expose)
+NEXT_PUBLIC_ALGOLIA_APP_ID="your-app-id"
+NEXT_PUBLIC_ALGOLIA_SEARCH_KEY="your-search-only-key"
+```
+
+### Step 3: Algolia Service
+
+```typescript
+// src/features/search/server/algolia.ts
+import 'server-only';
+
+import { algoliasearch } from 'algoliasearch';
+
+let _client: ReturnType<typeof algoliasearch> | null = null;
+
+function getAlgoliaClient() {
+  if (_client) return _client;
+
+  const appId = process.env.ALGOLIA_APP_ID;
+  const apiKey = process.env.ALGOLIA_API_KEY;
+
+  if (!appId || !apiKey) {
+    throw new Error(
+      'ALGOLIA_APP_ID and ALGOLIA_API_KEY are required.\n'
+      + '  → Get your keys from https://dashboard.algolia.com/account/api-keys\n'
+      + '  → Add them to your .env file',
+    );
+  }
+
+  _client = algoliasearch(appId, apiKey);
+  return _client;
+}
+
+function getIndexName(model: string): string {
+  const env = process.env.NODE_ENV || 'development';
+  const appName = process.env.APP_NAME || 'mars';
+  return `${appName}_${model}_${env}`;
+}
+
+export async function indexDocument(model: string, id: string, data: Record<string, unknown>) {
+  const client = getAlgoliaClient();
+  await client.saveObject({
+    indexName: getIndexName(model),
+    body: { objectID: id, ...data },
+  });
+}
+
+export async function removeDocument(model: string, id: string) {
+  const client = getAlgoliaClient();
+  await client.deleteObject({
+    indexName: getIndexName(model),
+    objectID: id,
+  });
+}
+
+export async function searchAlgolia(query: string, model: string, page: number = 0, hitsPerPage: number = 20) {
+  const client = getAlgoliaClient();
+  const result = await client.searchSingleIndex({
+    indexName: getIndexName(model),
+    searchParams: { query, page, hitsPerPage },
+  });
+
+  return {
+    results: (result.hits || []).map((hit: Record<string, unknown>) => ({
+      id: hit.objectID as string,
+      score: 1,
+      data: hit,
+    })),
+    total: result.nbHits ?? 0,
+    page: (result.page ?? 0) + 1,
+    totalPages: result.nbPages ?? 0,
+  };
+}
+```
+
+### Step 4: Sync on Create/Update/Delete
+
+Add indexing calls to your server mutations:
+
+```typescript
+// In your feature's server module
+import { indexDocument, removeDocument } from '@/features/search/server/algolia';
+
+export async function createPost(userId: string, data: CreatePostInput) {
+  const post = await prisma.post.create({ data: { ...data, userId } });
+
+  await indexDocument('Post', post.id, {
+    title: post.title,
+    body: post.body,
+    createdAt: post.createdAt.toISOString(),
+  });
+
+  return post;
+}
+
+export async function deletePost(userId: string, postId: string) {
+  await prisma.post.delete({ where: { id: postId, userId } });
+  await removeDocument('Post', postId);
+}
+```
+
+### Step 5: Client-Side Search Component
+
+```typescript
+// src/features/search/components/search-input.tsx
+'use client';
+
+import { useState, useCallback, useEffect, useRef } from 'react';
+import { algoliasearch } from 'algoliasearch/lite';
+
+const searchClient = algoliasearch(
+  process.env.NEXT_PUBLIC_ALGOLIA_APP_ID!,
+  process.env.NEXT_PUBLIC_ALGOLIA_SEARCH_KEY!,
+);
+
+interface SearchInputProps {
+  indexName: string;
+  onResults: (hits: Array<Record<string, unknown>>) => void;
+  placeholder?: string;
+  debounceMs?: number;
+}
+
+export function SearchInput({ indexName, onResults, placeholder = 'Search...', debounceMs = 300 }: SearchInputProps) {
+  const [query, setQuery] = useState('');
+  const timerRef = useRef<ReturnType<typeof setTimeout>>();
+
+  const performSearch = useCallback(async (q: string) => {
+    if (!q.trim()) {
+      onResults([]);
+      return;
+    }
+
+    const { hits } = await searchClient.searchSingleIndex({
+      indexName,
+      searchParams: { query: q },
+    });
+    onResults(hits as Array<Record<string, unknown>>);
+  }, [indexName, onResults]);
+
+  useEffect(() => {
+    clearTimeout(timerRef.current);
+    timerRef.current = setTimeout(() => performSearch(query), debounceMs);
+    return () => clearTimeout(timerRef.current);
+  }, [query, debounceMs, performSearch]);
+
+  return (
+    <input
+      type="search"
+      value={query}
+      onChange={(e) => setQuery(e.target.value)}
+      placeholder={placeholder}
+      className="w-full rounded-lg border border-border-primary bg-surface-primary px-4 py-2 text-sm text-text-primary placeholder:text-text-tertiary focus:outline-none focus:ring-2 focus:ring-brand-primary"
+    />
+  );
+}
+```
+
+---
+
+## Option C: Meilisearch
+
+### Step 1: Install Meilisearch Client
+
+```bash
+yarn add meilisearch
+```
+
+### Step 2: Environment Variables
+
+```bash
+# Server-side
+MEILISEARCH_HOST="http://localhost:7700"
+MEILISEARCH_MASTER_KEY="your-master-key"
+
+# Client-side (search-only)
+NEXT_PUBLIC_MEILISEARCH_HOST="http://localhost:7700"
+NEXT_PUBLIC_MEILISEARCH_SEARCH_KEY="your-search-api-key"
+```
+
+### Step 3: Meilisearch Service
+
+```typescript
+// src/features/search/server/meilisearch.ts
+import 'server-only';
+
+import { MeiliSearch } from 'meilisearch';
+
+let _client: MeiliSearch | null = null;
+
+function getMeilisearchClient(): MeiliSearch {
+  if (_client) return _client;
+
+  const host = process.env.MEILISEARCH_HOST;
+  const apiKey = process.env.MEILISEARCH_MASTER_KEY;
+
+  if (!host) {
+    throw new Error(
+      'MEILISEARCH_HOST is required.\n'
+      + '  → Run Meilisearch locally: docker run -p 7700:7700 getmeili/meilisearch\n'
+      + '  → Add MEILISEARCH_HOST to your .env file',
+    );
+  }
+
+  _client = new MeiliSearch({ host, apiKey });
+  return _client;
+}
+
+function getIndexName(model: string): string {
+  const env = process.env.NODE_ENV || 'development';
+  return `${model.toLowerCase()}_${env}`;
+}
+
+export async function configureIndex(model: string, searchableAttributes: string[]) {
+  const client = getMeilisearchClient();
+  const index = client.index(getIndexName(model));
+  await index.updateSearchableAttributes(searchableAttributes);
+  await index.updateFilterableAttributes(['userId', 'status', 'createdAt']);
+  await index.updateSortableAttributes(['createdAt']);
+}
+
+export async function indexDocument(model: string, id: string, data: Record<string, unknown>) {
+  const client = getMeilisearchClient();
+  await client.index(getIndexName(model)).addDocuments([{ id, ...data }]);
+}
+
+export async function removeDocument(model: string, id: string) {
+  const client = getMeilisearchClient();
+  await client.index(getIndexName(model)).deleteDocument(id);
+}
+
+export async function searchMeilisearch(
+  query: string,
+  model: string,
+  page: number = 1,
+  limit: number = 20,
+) {
+  const client = getMeilisearchClient();
+  const result = await client.index(getIndexName(model)).search(query, {
+    offset: (page - 1) * limit,
+    limit,
+  });
+
+  return {
+    results: result.hits.map((hit) => ({
+      id: hit.id as string,
+      score: 1,
+      data: hit as Record<string, unknown>,
+    })),
+    total: result.estimatedTotalHits ?? 0,
+    page,
+    totalPages: Math.ceil((result.estimatedTotalHits ?? 0) / limit),
+  };
+}
+```
+
+### Step 4: Index Configuration
+
+Run once on setup or in a seed script:
+
+```typescript
+import { configureIndex } from '@/features/search/server/meilisearch';
+
+await configureIndex('Post', ['title', 'body']);
+await configureIndex('User', ['name', 'email']);
+```
+
+---
+
+## Search API Route
+
+Regardless of provider, expose a unified search endpoint:
+
+```typescript
+// src/app/api/protected/search/route.ts
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+const searchSchema = z.object({
+  q: z.string().min(1).max(200),
+  model: z.string().min(1),
+  page: z.coerce.number().int().positive().default(1),
+  limit: z.coerce.number().int().positive().max(100).default(20),
+});
+
+export const GET = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const url = new URL(request.url);
+    const params = searchSchema.parse({
+      q: url.searchParams.get('q'),
+      model: url.searchParams.get('model'),
+      page: url.searchParams.get('page') ?? 1,
+      limit: url.searchParams.get('limit') ?? 20,
+    });
+
+    // Import the appropriate provider based on appConfig
+    // Example with Postgres:
+    const { searchPostgres } = await import('@/features/search/server/postgres');
+    const results = await searchPostgres(params.q, {
+      model: params.model,
+      page: params.page,
+      limit: params.limit,
+    });
+
+    return NextResponse.json(results);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/search' });
+  }
+});
+```
+
+## Debounced Search Hook
+
+A reusable hook for client-side search with debounce, usable with any provider:
+
+```typescript
+// src/features/search/hooks/use-search.ts
+'use client';
+
+import { useState, useCallback, useRef, useEffect } from 'react';
+
+interface UseSearchOptions {
+  model: string;
+  debounceMs?: number;
+  limit?: number;
+}
+
+export function useSearch<T = Record<string, unknown>>({ model, debounceMs = 300, limit = 20 }: UseSearchOptions) {
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState<T[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [total, setTotal] = useState(0);
+  const [page, setPage] = useState(1);
+  const timerRef = useRef<ReturnType<typeof setTimeout>>();
+
+  const performSearch = useCallback(async (q: string, p: number) => {
+    if (!q.trim()) {
+      setResults([]);
+      setTotal(0);
+      return;
+    }
+
+    setIsLoading(true);
+    try {
+      const params = new URLSearchParams({ q, model, page: String(p), limit: String(limit) });
+      const response = await fetch(`/api/protected/search?${params}`);
+      const data = await response.json();
+      setResults(data.results?.map((r: { data: T }) => r.data) ?? []);
+      setTotal(data.total ?? 0);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [model, limit]);
+
+  useEffect(() => {
+    clearTimeout(timerRef.current);
+    timerRef.current = setTimeout(() => performSearch(query, page), debounceMs);
+    return () => clearTimeout(timerRef.current);
+  }, [query, page, debounceMs, performSearch]);
+
+  return { query, setQuery, results, isLoading, total, page, setPage };
+}
+```
+
+## Config Integration
+
+Add to `src/config/app.config.ts`:
+
+```typescript
+export const appConfig = {
+  // ... existing config
+  services: {
+    // ... existing services
+    search: {
+      provider: 'postgres' as const, // 'postgres' | 'algolia' | 'meilisearch'
+    },
+  },
+};
+```
+
+## Testing
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+
+// Mock search service
+vi.mock('@/features/search/server/postgres', () => ({
+  searchPostgres: vi.fn().mockResolvedValue({
+    results: [{ id: '1', score: 0.9, data: { title: 'Test' } }],
+    total: 1,
+    page: 1,
+    totalPages: 1,
+  }),
+}));
+
+// For Algolia/Meilisearch, mock the client:
+vi.mock('algoliasearch', () => ({
+  algoliasearch: vi.fn(() => ({
+    searchSingleIndex: vi.fn().mockResolvedValue({ hits: [], nbHits: 0 }),
+    saveObject: vi.fn(),
+    deleteObject: vi.fn(),
+  })),
+}));
+```
+
+## Checklist
+
+- [ ] Provider chosen and configured in `app.config.ts`
+- [ ] Environment variables set for chosen provider
+- [ ] Search service module created with `import 'server-only'`
+- [ ] For Postgres: tsvector column and GIN index added via migration
+- [ ] For Algolia/Meilisearch: documents indexed on create/update/delete
+- [ ] Search API route created at `GET /api/protected/search`
+- [ ] Input sanitized to prevent injection (Postgres) or excessive queries
+- [ ] Zod validation on search parameters
+- [ ] Debounced search hook or component created for client-side use
+- [ ] Uses auth wrapper (`withAuthNoParams`) on API route
+- [ ] Design tokens used for search component styling (no raw color classes)
+- [ ] Tests written for search service and API route