cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skill-library/stack/search/meilisearch/SKILL.md

@@ -0,0 +1,385 @@
+---
+name: meilisearch
+description: Integrate Meilisearch for fast, typo-tolerant full-text search including index management, filtering, faceting, geo search, and relevancy tuning. Use when adding search functionality to applications that need instant, typo-tolerant results.
+version: 1.0.0
+---
+
+# Meilisearch
+
+Integrate Meilisearch for fast, typo-tolerant full-text search. Meilisearch is an open-source search engine designed for instant search experiences with minimal configuration.
+
+## When to Use This Skill
+
+- Adding search functionality to web applications
+- Implementing faceted search (filter by category, price range, etc.)
+- Building autocomplete / search-as-you-type experiences
+- Searching content that needs typo tolerance and relevancy ranking
+- Implementing geo-based search (find nearby locations)
+- Multi-tenant search with secure tenant tokens
+
+## Setup
+
+```bash
+# Install JavaScript client
+pnpm add meilisearch
+
+# Run Meilisearch locally (Docker)
+docker run -d -p 7700:7700 \
+  -v $(pwd)/meili_data:/meili_data \
+  -e MEILI_MASTER_KEY='your-master-key' \
+  getmeili/meilisearch:latest
+```
+
+### Client Initialization
+
+```typescript
+// src/lib/search/meilisearch.ts
+import { MeiliSearch } from 'meilisearch';
+
+export const meili = new MeiliSearch({
+  host: process.env.MEILISEARCH_HOST ?? 'http://localhost:7700',
+  apiKey: process.env.MEILISEARCH_ADMIN_KEY, // Admin key for server-side operations
+});
+
+// For client-side search, use a search-only API key
+export const meiliSearch = new MeiliSearch({
+  host: process.env.MEILISEARCH_HOST ?? 'http://localhost:7700',
+  apiKey: process.env.MEILISEARCH_SEARCH_KEY, // Read-only key
+});
+```
+
+## Index Management
+
+### Creating and Configuring an Index
+
+```typescript
+// Create index with primary key
+const index = await meili.createIndex('products', { primaryKey: 'id' });
+
+// Configure searchable attributes (order defines relevancy weight)
+await meili.index('products').updateSearchableAttributes([
+  'name',        // Highest weight
+  'description',
+  'category',
+  'brand',       // Lowest weight
+]);
+
+// Configure filterable attributes (for filtering and faceting)
+await meili.index('products').updateFilterableAttributes([
+  'category',
+  'brand',
+  'price',
+  'inStock',
+  'rating',
+  'tags',
+  '_geo', // Required for geo search
+]);
+
+// Configure sortable attributes
+await meili.index('products').updateSortableAttributes([
+  'price',
+  'rating',
+  'createdAt',
+]);
+
+// Configure displayed attributes (what is returned in results)
+await meili.index('products').updateDisplayedAttributes([
+  'id', 'name', 'description', 'price', 'category',
+  'brand', 'imageUrl', 'rating', 'slug',
+]);
+
+// Configure ranking rules (order matters)
+await meili.index('products').updateRankingRules([
+  'words',        // Number of matched query words
+  'typo',         // Number of typos
+  'proximity',    // Distance between matched words
+  'attribute',    // Position in searchableAttributes list
+  'sort',         // User-defined sort
+  'exactness',    // Exact vs prefix match
+  'rating:desc',  // Custom ranking: higher rating first
+]);
+```
+
+### Typo Tolerance
+
+```typescript
+await meili.index('products').updateTypoTolerance({
+  enabled: true,
+  minWordSizeForTypos: {
+    oneTypo: 4,   // Allow 1 typo for words >= 4 chars
+    twoTypos: 8,  // Allow 2 typos for words >= 8 chars
+  },
+  disableOnAttributes: ['sku', 'barcode'], // Exact match only for these
+  disableOnWords: ['iPhone', 'MacBook'],   // Exact match for specific terms
+});
+```
+
+### Synonyms
+
+```typescript
+await meili.index('products').updateSynonyms({
+  'phone': ['smartphone', 'mobile', 'cellphone'],
+  'laptop': ['notebook', 'portable computer'],
+  'tv': ['television', 'monitor', 'screen'],
+  // One-way synonym
+  'iphone': ['phone'],
+});
+```
+
+### Stop Words
+
+```typescript
+await meili.index('products').updateStopWords([
+  'the', 'a', 'an', 'is', 'are', 'was', 'were', 'of', 'for', 'in',
+]);
+```
+
+## Document Operations
+
+### Adding Documents
+
+```typescript
+const products = [
+  {
+    id: 'prod_1',
+    name: 'Wireless Noise-Canceling Headphones',
+    description: 'Premium wireless headphones with active noise cancellation',
+    category: 'Electronics',
+    brand: 'AudioTech',
+    price: 299.99,
+    rating: 4.7,
+    inStock: true,
+    tags: ['wireless', 'noise-canceling', 'bluetooth'],
+    slug: 'wireless-noise-canceling-headphones',
+    _geo: { lat: 40.7128, lng: -74.0060 },
+  },
+  // ... more products
+];
+
+// Add or replace documents
+const task = await meili.index('products').addDocuments(products);
+
+// Wait for indexing to complete
+await meili.waitForTask(task.taskUid);
+
+// Update specific documents (partial update)
+await meili.index('products').updateDocuments([
+  { id: 'prod_1', price: 249.99, inStock: false },
+]);
+
+// Delete documents
+await meili.index('products').deleteDocument('prod_1');
+await meili.index('products').deleteDocuments(['prod_1', 'prod_2']);
+await meili.index('products').deleteAllDocuments();
+```
+
+### Batch Indexing
+
+```typescript
+// For large datasets, batch in chunks
+async function indexAllProducts(products: Product[]) {
+  const BATCH_SIZE = 1000;
+  const tasks: number[] = [];
+
+  for (let i = 0; i < products.length; i += BATCH_SIZE) {
+    const batch = products.slice(i, i + BATCH_SIZE);
+    const task = await meili.index('products').addDocuments(batch);
+    tasks.push(task.taskUid);
+  }
+
+  // Wait for all batches to finish
+  for (const taskUid of tasks) {
+    await meili.waitForTask(taskUid);
+  }
+}
+```
+
+## Searching
+
+### Basic Search
+
+```typescript
+const results = await meili.index('products').search('wireless headphones');
+
+// results shape:
+// {
+//   hits: [...],           // Matching documents
+//   query: 'wireless headphones',
+//   processingTimeMs: 2,
+//   limit: 20,
+//   offset: 0,
+//   estimatedTotalHits: 42,
+// }
+```
+
+### Search with Filters
+
+```typescript
+const results = await meili.index('products').search('headphones', {
+  filter: [
+    'category = "Electronics"',
+    'price >= 50 AND price <= 300',
+    'inStock = true',
+    'rating >= 4.0',
+  ],
+  sort: ['price:asc'],
+  limit: 20,
+  offset: 0,
+});
+
+// Array of filter strings are ANDed together
+// Use OR within a string: 'category = "Electronics" OR category = "Audio"'
+// Use arrays for AND between groups, strings for OR within groups:
+// filter: [['category = "Electronics"', 'category = "Audio"'], 'inStock = true']
+// = (Electronics OR Audio) AND inStock
+```
+
+### Search with Facets
+
+```typescript
+const results = await meili.index('products').search('headphones', {
+  facets: ['category', 'brand', 'tags'],
+  filter: ['inStock = true'],
+});
+
+// results.facetDistribution:
+// {
+//   category: { Electronics: 15, Audio: 8, Accessories: 3 },
+//   brand: { AudioTech: 10, SoundMax: 8, BassKing: 5 },
+//   tags: { wireless: 18, bluetooth: 15, 'noise-canceling': 12 },
+// }
+```
+
+### Search with Highlighting
+
+```typescript
+const results = await meili.index('products').search('wireless headphones', {
+  attributesToHighlight: ['name', 'description'],
+  highlightPreTag: '<mark>',
+  highlightPostTag: '</mark>',
+  attributesToCrop: ['description'],
+  cropLength: 30,
+});
+
+// Each hit includes _formatted with highlighted matches:
+// hit._formatted.name = '<mark>Wireless</mark> Noise-Canceling <mark>Headphones</mark>'
+```
+
+### Geo Search
+
+```typescript
+// Find products within 10km of a location
+const results = await meili.index('products').search('coffee shop', {
+  filter: ['_geoRadius(40.7128, -74.0060, 10000)'], // lat, lng, radius in meters
+  sort: ['_geoPoint(40.7128, -74.0060):asc'], // Sort by distance
+});
+
+// Bounding box filter
+const results2 = await meili.index('products').search('', {
+  filter: ['_geoBoundingBox([40.82, -74.02], [40.70, -73.95])'], // top-left, bottom-right
+});
+```
+
+### Multi-Index Search
+
+```typescript
+const results = await meili.multiSearch({
+  queries: [
+    { indexUid: 'products', q: 'wireless', limit: 5 },
+    { indexUid: 'articles', q: 'wireless', limit: 5 },
+    { indexUid: 'categories', q: 'wireless', limit: 3 },
+  ],
+});
+
+// results.results is an array of search results, one per query
+```
+
+## Tenant Tokens (Multi-Tenancy)
+
+Tenant tokens restrict search to specific filter rules. Generate them server-side, use them client-side.
+
+```typescript
+// Server: Generate a tenant token
+import { MeiliSearch } from 'meilisearch';
+
+const client = new MeiliSearch({
+  host: process.env.MEILISEARCH_HOST!,
+  apiKey: process.env.MEILISEARCH_ADMIN_KEY!,
+});
+
+function generateTenantToken(tenantId: string): string {
+  return client.generateTenantToken(
+    process.env.MEILISEARCH_SEARCH_KEY_UID!, // UID of the search key
+    {
+      products: {
+        filter: `tenantId = "${tenantId}"`, // Enforced filter
+      },
+    },
+    {
+      expiresAt: new Date(Date.now() + 3600 * 1000), // 1 hour
+    },
+  );
+}
+```
+
+```typescript
+// Client: Use the tenant token
+const tenantClient = new MeiliSearch({
+  host: 'https://search.example.com',
+  apiKey: tenantToken, // Token from server
+});
+
+// All searches are automatically scoped to the tenant
+const results = await tenantClient.index('products').search('headphones');
+// Only returns products where tenantId matches
+```
+
+## Syncing Data
+
+```typescript
+// Pattern: Sync database changes to Meilisearch
+// Call this from your database hooks/triggers
+
+async function syncProductToSearch(product: Product, action: 'upsert' | 'delete') {
+  const index = meili.index('products');
+
+  if (action === 'delete') {
+    await index.deleteDocument(product.id);
+    return;
+  }
+
+  await index.addDocuments([{
+    id: product.id,
+    name: product.name,
+    description: product.description,
+    category: product.category,
+    brand: product.brand,
+    price: product.price,
+    rating: product.rating,
+    inStock: product.inStock,
+    tags: product.tags,
+    slug: product.slug,
+    updatedAt: product.updatedAt,
+  }]);
+}
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Approach |
+|-------------|-----------------|
+| Using the admin key on the client | Use search-only keys or tenant tokens client-side |
+| Not configuring searchableAttributes | Without it, all fields are searchable (slow, noisy results) |
+| Indexing raw database rows with all columns | Index only fields needed for search, display, and filtering |
+| Calling `waitForTask` in request handlers | Indexing is async -- return immediately, let it process in background |
+| Re-indexing entire dataset on every change | Use incremental `addDocuments` (upserts by primary key) |
+| Using Meilisearch as a primary database | It is a search index -- your database is the source of truth |
+
+## Environment Variables
+
+```env
+MEILISEARCH_HOST=http://localhost:7700
+MEILISEARCH_ADMIN_KEY=         # Admin key -- server-side only
+MEILISEARCH_SEARCH_KEY=        # Search-only key -- safe for client
+MEILISEARCH_SEARCH_KEY_UID=    # UID of search key (for tenant tokens)
+```

package/template/.codex/skill-library/stack/search/typesense/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: typesense
+description: "Typesense search patterns covering collection schemas, indexing, search queries, faceting, geo-search, curation, and InstantSearch adapter. Use when implementing search with Typesense."
+version: 1.0.0
+source: self
+date_added: "2026-03-14"
+---
+
+# Typesense
+
+Open-source, typo-tolerant search engine built in C++. Self-hosted or Typesense Cloud. Sub-50ms latency with schema-enforced collections.
+
+## When to Use
+
+- Need fast full-text search with a schema-first approach
+- Want a self-hosted, open-source alternative to Algolia
+- Need geo-search, faceted filtering, or curation rules
+- Building e-commerce or content search
+
+## When NOT to Use
+
+- Need complex aggregations or analytics on search data (use Elasticsearch)
+- Search is simple enough for DB `LIKE` queries
+- Need document-level security per user (Typesense has collection-level API keys)
+
+## Setup
+
+### Installation
+
+```bash
+npm install typesense                       # Backend client
+npm install typesense-instantsearch-adapter # For InstantSearch UI
+```
+
+### Client Initialization
+
+```typescript
+import Typesense from 'typesense';
+
+const client = new Typesense.Client({
+  nodes: [{ host: 'localhost', port: 8108, protocol: 'http' }],
+  apiKey: 'your-admin-api-key',
+  connectionTimeoutSeconds: 2,
+});
+```
+
+## Collections (Schema Definition)
+
+```typescript
+await client.collections().create({
+  name: 'products',
+  fields: [
+    { name: 'name', type: 'string' },
+    { name: 'description', type: 'string' },
+    { name: 'price', type: 'float', facet: true },
+    { name: 'brand', type: 'string', facet: true },
+    { name: 'category', type: 'string', facet: true },
+    { name: 'rating', type: 'float', facet: true },
+    { name: 'in_stock', type: 'bool', facet: true },
+    { name: 'tags', type: 'string[]', facet: true },
+    { name: 'location', type: 'geopoint', optional: true }, // [lat, lng]
+  ],
+  default_sorting_field: 'rating',
+});
+```
+
+## Indexing
+
+```typescript
+// Single document
+await client.collections('products').documents().upsert({
+  id: 'product-123',
+  name: 'iPhone 15 Pro',
+  description: 'Latest iPhone with titanium design',
+  price: 999,
+  brand: 'Apple',
+  category: 'Electronics',
+  rating: 4.8,
+  in_stock: true,
+  tags: ['smartphone', 'apple', 'premium'],
+});
+
+// Batch import (JSONL format, up to 40MB per batch)
+await client.collections('products').documents().import(products, { action: 'upsert' });
+
+// Delete
+await client.collections('products').documents('product-123').delete();
+```
+
+## Search Queries
+
+```typescript
+const results = await client.collections('products').documents().search({
+  q: 'iphone pro',
+  query_by: 'name,description,brand',
+  filter_by: 'in_stock:true && price:<1200',
+  sort_by: 'rating:desc',
+  facet_by: 'brand,category,price',
+  max_facet_values: 10,
+  page: 1,
+  per_page: 20,
+  highlight_full_fields: 'name',
+});
+
+results.hits?.forEach(hit => {
+  const doc = hit.document;
+  console.log(`${doc.name} — $${doc.price}`);
+  console.log(`Highlight: ${hit.highlights?.[0]?.snippet}`);
+});
+
+// Facet counts
+results.facet_counts?.forEach(facet => {
+  console.log(`${facet.field_name}:`, facet.counts);
+});
+```
+
+### Geo-Search
+
+```typescript
+const results = await client.collections('stores').documents().search({
+  q: '*',
+  query_by: 'name',
+  filter_by: 'location:(37.7749, -122.4194, 10 km)', // Within 10km of SF
+  sort_by: 'location(37.7749, -122.4194):asc',        // Nearest first
+});
+```
+
+## Scoped API Keys (Multi-Tenant)
+
+```typescript
+// Generate a search key scoped to specific tenant
+const scopedKey = client.keys().generateScopedSearchKey(
+  'base-search-api-key',
+  {
+    filter_by: 'tenant_id:tenant-123',
+    expires_at: Math.floor(Date.now() / 1000) + 3600,
+  }
+);
+// Give this key to the frontend — it can only search tenant-123's data
+```
+
+## InstantSearch Adapter
+
+```tsx
+import TypesenseInstantsearchAdapter from 'typesense-instantsearch-adapter';
+import { InstantSearch, SearchBox, Hits, RefinementList } from 'react-instantsearch';
+
+const adapter = new TypesenseInstantsearchAdapter({
+  server: {
+    apiKey: 'search-only-key',
+    nodes: [{ host: 'search.example.com', port: 443, protocol: 'https' }],
+  },
+  additionalSearchParameters: { query_by: 'name,description,brand' },
+});
+
+function SearchPage() {
+  return (
+    <InstantSearch searchClient={adapter.searchClient} indexName="products">
+      <SearchBox />
+      <RefinementList attribute="brand" />
+      <Hits hitComponent={ProductHit} />
+    </InstantSearch>
+  );
+}
+```
+
+## Key Limits
+
+| Limit | Value |
+|-------|-------|
+| Max document size | 10 KB (default, configurable) |
+| Max import batch size | 40 MB |
+| Max `query_by` fields | 100 |
+| Max facet values returned | 250 |
+| Max results per search | 250 (use pagination for more) |
+| API key scoping | Collection-level (not document-level) |
+
+## Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| Expose admin API key to client | Generate scoped search keys for frontend |
+| Skip schema definition | Define explicit schemas — Typesense enforces types |
+| Use `*` for `query_by` | List specific fields ordered by relevance priority |
+| Import one document at a time | Batch import with `documents().import()` |
+| Filter by high-cardinality fields without facet:true | Mark filterable fields as `facet: true` in schema |
+| Use `default_sorting_field` for non-numeric fields | Only numeric fields (int32, float) work as default sort |
+| Skip `upsert` action on re-import | Use `{ action: 'upsert' }` to avoid duplicate errors |
+| Store large blobs as document fields | Store file content externally, index metadata only |