@open-mercato/search 0.4.7-develop-74069040de → 0.4.7-develop-bdeaa0fc10

package/agentic/standalone-guide.md

@@ -0,0 +1,115 @@
+# Search Package — Standalone Developer Guide
+
+`@open-mercato/search` provides fulltext, vector, and token-based search. Configure search for your entities via `search.ts` in your module.
+
+## Strategy Overview
+
+| Strategy | Backend | Use when |
+|----------|---------|----------|
+| **Fulltext** | Meilisearch | Fast, typo-tolerant search (names, titles, descriptions) |
+| **Vector** | OpenAI / Ollama | Semantic, meaning-based search ("find customers interested in X") |
+| **Tokens** | PostgreSQL | Baseline keyword search, always available, no external services |
+
+Strategies auto-degrade when their backend is not configured.
+
+## Adding Search to a Module
+
+Create `src/modules/<module>/search.ts`:
+
+```typescript
+import type { SearchModuleConfig, SearchBuildContext } from '@open-mercato/shared/modules/search'
+
+export const searchConfig: SearchModuleConfig = {
+  entities: [{
+    entityId: 'my_module:my_entity',  // MUST match entity registry
+    priority: 10,
+
+    // Fulltext: control field indexing
+    fieldPolicy: {
+      searchable: ['name', 'description'],
+      hashOnly: ['email', 'phone'],      // exact match only
+      excluded: ['password', 'api_key'],  // never indexed
+    },
+
+    // Vector: generate text for embeddings
+    buildSource: async (ctx: SearchBuildContext) => ({
+      text: [`Name: ${ctx.record.name}`, `Description: ${ctx.record.description}`],
+      presenter: { title: ctx.record.name, subtitle: ctx.record.status, icon: 'lucide:file', badge: 'Item' },
+      links: [{ href: `/backend/my-module/${ctx.record.id}`, label: 'View', kind: 'primary' }],
+      checksumSource: { record: ctx.record, customFields: ctx.customFields },
+    }),
+
+    // Tokens: format at search time
+    formatResult: async (ctx: SearchBuildContext) => ({
+      title: ctx.record.name ?? 'Unknown',
+      subtitle: ctx.record.status,
+      icon: 'lucide:file',
+      badge: 'Item',
+    }),
+
+    resolveUrl: async (ctx) => `/backend/my-module/${ctx.record.id}`,
+  }],
+}
+export default searchConfig
+```
+
+Run `yarn generate` after creating the file.
+
+## MUST Rules
+
+1. **MUST create `search.ts`** for every module with searchable entities
+2. **MUST define `fieldPolicy.excluded`** for sensitive fields (passwords, tokens, SSNs)
+3. **MUST define `formatResult`** for every entity using the tokens strategy
+4. **MUST include `checksumSource`** in every `buildSource` return value
+5. **MUST NOT** include encrypted/sensitive fields in `buildSource` text
+6. **MUST NOT** use raw `fetch` against search API — use `apiCall`/`apiCallOrThrow`
+
+## Auto-Indexing
+
+When CRUD routes have `indexer: { entityType }`, the search module automatically subscribes to entity CRUD events and indexes/removes records. No manual indexing code needed.
+
+## CLI Commands
+
+```bash
+yarn mercato search status                           # Check strategies and connectivity
+yarn mercato search query -q "term" --tenant <id>    # Run a search
+yarn mercato search reindex --tenant <id>             # Reindex all entities
+yarn mercato search reindex --entity my_module:my_entity --tenant <id>  # Reindex specific entity
+yarn mercato search test-meilisearch                  # Test Meilisearch connection
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `MEILISEARCH_HOST` | Meilisearch URL (enables fulltext) |
+| `MEILISEARCH_API_KEY` | Meilisearch auth key |
+| `OPENAI_API_KEY` | OpenAI API key (enables vector search) |
+| `OM_SEARCH_DEBUG` | Enable verbose debug logging |
+
+## Programmatic Search via DI
+
+```typescript
+const searchService = container.resolve('searchService')
+const results = await searchService.search('query', {
+  tenantId: 'tenant-123',
+  limit: 20,
+  strategies: ['fulltext', 'vector'],
+})
+```
+
+## SearchBuildContext
+
+Both `buildSource` and `formatResult` receive this context:
+
+```typescript
+interface SearchBuildContext {
+  record: Record<string, unknown>       // The database record
+  customFields: Record<string, unknown> // Custom fields (without cf: prefix)
+  tenantId?: string | null
+  organizationId?: string | null
+  queryEngine?: QueryEngine             // For loading related entities
+}
+```
+
+Use `queryEngine` to load parent/related entities for richer presenter data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/search",
-  "version": "0.4.7-develop-74069040de",
+  "version": "0.4.7-develop-bdeaa0fc10",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -126,9 +126,9 @@
     "zod": "^4.0.0"
   },
   "peerDependencies": {
-    "@open-mercato/core": "0.4.7-develop-74069040de",
-    "@open-mercato/queue": "0.4.7-develop-74069040de",
-    "@open-mercato/shared": "0.4.7-develop-74069040de"
+    "@open-mercato/core": "0.4.7-develop-bdeaa0fc10",
+    "@open-mercato/queue": "0.4.7-develop-bdeaa0fc10",
+    "@open-mercato/shared": "0.4.7-develop-bdeaa0fc10"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",