@open-mercato/cli 0.6.7 → 0.6.8-canary.320.1.bf889f49e4

package/dist/agentic/guides/events.md

@@ -1,117 +0,0 @@
-# Events Package — Standalone Developer Guide
-
-`@open-mercato/events` provides event-driven communication between modules. Use events for side effects — never direct module-to-module function calls.
-
-## Declaring Events
-
-Every module that emits events MUST declare them in `events.ts`:
-
-```typescript
-import { createModuleEvents } from '@open-mercato/shared/modules/events'
-
-const events = [
-  { id: 'my_mod.item.created', label: 'Item Created', entity: 'item', category: 'crud' },
-  { id: 'my_mod.item.updated', label: 'Item Updated', entity: 'item', category: 'crud' },
-  { id: 'my_mod.item.deleted', label: 'Item Deleted', entity: 'item', category: 'crud' },
-] as const
-
-export const eventsConfig = createModuleEvents({ moduleId: 'my_mod', events })
-export const emitMyModEvent = eventsConfig.emit
-export default eventsConfig
-```
-
-MUST use `as const` — provides compile-time safety. Run `yarn generate` after adding.
-
-### Event ID Convention
-
-Format: `module.entity.action` (singular entity, past tense action, dots as separators).
-
-## Adding Subscribers
-
-Create subscriber files in `src/modules/<module>/subscribers/`:
-
-```typescript
-// subscribers/item-created-notify.ts
-export const metadata = {
-  event: 'my_mod.item.created',
-  persistent: true,    // survives restarts, retried on failure
-  id: 'item-created-notify',
-}
-
-export default async function handler(payload, ctx) {
-  // One side effect per subscriber
-}
-```
-
-Run `yarn generate` after adding.
-
-## Subscription Types
-
-| Type | Use for | Behavior |
-|------|---------|----------|
-| Ephemeral (`persistent: false`) | Real-time UI updates, cache invalidation | In-memory, no retry, lost on restart |
-| Persistent (`persistent: true`) | Notifications, indexing, audit logging | Queue-backed, retried on failure |
-
-Persistent subscribers MUST be idempotent — they may be retried.
-
-## DOM Event Bridge (Browser Events via SSE)
-
-Stream server-side events to the browser for real-time UI updates.
-
-### Enable on Events
-
-Add `clientBroadcast: true` to event declarations:
-
-```typescript
-const events = [
-  { id: 'my_mod.item.created', label: 'Created', category: 'crud', clientBroadcast: true },
-] as const
-```
-
-### Consume in Components
-
-```typescript
-import { useAppEvent } from '@open-mercato/ui/backend/injection/useAppEvent'
-
-// Wildcard: all events from a module
-useAppEvent('my_mod.*', (event) => {
-  // event.id, event.payload — refresh data, show notification
-}, [])
-
-// Exact match
-useAppEvent('my_mod.item.created', (event) => {
-  reloadItems()
-}, [reloadItems])
-```
-
-### Track Long-Running Operations
-
-```typescript
-import { useOperationProgress } from '@open-mercato/ui/backend/injection/useOperationProgress'
-
-const progress = useOperationProgress('my_mod.import.*')
-// progress.status: 'idle' | 'running' | 'completed' | 'failed'
-// progress.progress: 0-100
-```
-
-### SSE Audience Filtering
-
-Events are server-filtered before SSE delivery by:
-- `tenantId` (must match)
-- `organizationId` / `organizationIds` (must match selected org)
-- `recipientUserId` / `recipientUserIds` (must include user)
-- `recipientRoleId` / `recipientRoleIds` (must intersect roles)
-
-Missing `tenantId` in payload = no delivery.
-
-## Queue Integration
-
-| Queue strategy | Ephemeral | Persistent |
-|----------------|-----------|------------|
-| `local` (dev) | In-process | `.mercato/queue/` filesystem |
-| `async` (prod) | In-process | BullMQ (Redis-backed) |
-
-For production, start the event worker:
-```bash
-yarn mercato events worker event-processing --concurrency=5
-```

package/dist/agentic/guides/queue.md

@@ -1,53 +0,0 @@
-# Queue Package — Standalone Developer Guide
-
-`@open-mercato/queue` provides background job processing. MUST NOT implement custom job queues or polling loops.
-
-## Strategy Selection
-
-| Strategy | When | Config |
-|----------|------|--------|
-| Local | Development — processes from `.mercato/queue/` | `QUEUE_STRATEGY=local` |
-| BullMQ | Production — Redis-backed with retries | `QUEUE_STRATEGY=async` |
-
-## Adding a Worker
-
-Create `src/modules/<module>/workers/<name>.ts`:
-
-```typescript
-export const metadata = {
-  queue: 'my-queue',
-  id: 'my-worker',
-  concurrency: 5,
-}
-
-export default async function handler(job) {
-  // MUST be idempotent — jobs may be retried on failure
-  // Check state before mutating
-}
-```
-
-Run `yarn generate` after adding.
-
-## Concurrency Guidelines
-
-| Worker type | Concurrency | Rationale |
-|-------------|-------------|-----------|
-| I/O-bound (API calls, email) | 5–10 | Network latency allows parallelism |
-| CPU-bound (calculations) | 1–2 | Avoid blocking event loop |
-| Database-heavy (bulk writes) | 3–5 | Balance with connection pool |
-
-Max concurrency: 20.
-
-## MUST Rules
-
-1. **MUST make workers idempotent** — duplicate execution MUST NOT corrupt data
-2. **MUST export `metadata`** with `{ queue, id?, concurrency? }`
-3. **MUST test with both strategies** (`local` and `async`)
-
-## Running Workers (Production)
-
-```bash
-yarn mercato <module> worker <queue-name> --concurrency=5
-```
-
-Development: local strategy auto-processes from `.mercato/queue/`.

package/dist/agentic/guides/search.md

@@ -1,115 +0,0 @@
-# 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/dist/agentic/guides/shared.md

@@ -1,108 +0,0 @@
-# Shared Package — Standalone Developer Guide
-
-`@open-mercato/shared` provides cross-cutting utilities, types, and DSL helpers. Import from here for infrastructure concerns — never from `@open-mercato/core`.
-
-## Import Map
-
-| Need | Import |
-|------|--------|
-| Client-side translations | `import { useT } from '@open-mercato/shared/lib/i18n/context'` |
-| Server-side translations | `import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'` |
-| Encrypted queries | `import { findWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'` |
-| Boolean parsing | `import { parseBooleanToken, parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'` |
-| Command pattern | `import { registerCommand } from '@open-mercato/shared/lib/commands'` |
-| Safe entity flush | `import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'` |
-| Data/Query engine types | `import type { DataEngine, QueryEngine } from '@open-mercato/shared/lib/data/engine'` |
-| CRUD multi-ID filtering | `import { parseIdsParam, mergeIdFilter } from '@open-mercato/shared/lib/crud/ids'` |
-| CRUD OpenAPI factory | `import { createCrudOpenApiFactory } from '@open-mercato/shared/lib/openapi/crud'` |
-| Scoped API payloads | `import { withScopedPayload } from '@open-mercato/shared/lib/api/scoped'` |
-| DI setup (Awilix) | `import { ... } from '@open-mercato/shared/lib/di'` |
-| Custom field helpers | `import { splitCustomFieldPayload, normalizeCustomFieldValues } from '@open-mercato/shared/lib/custom-fields'` |
-| DSL helpers | `import { defineLink, entityId, cf } from '@open-mercato/shared/modules/dsl'` |
-| Event declarations | `import { createModuleEvents } from '@open-mercato/shared/modules/events'` |
-| Module setup types | `import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'` |
-| Search config types | `import type { SearchModuleConfig } from '@open-mercato/shared/modules/search'` |
-| Widget injection position | `import { InjectionPosition } from '@open-mercato/shared/modules/widgets/injection-position'` |
-| API interceptor types | `import type { ApiInterceptor } from '@open-mercato/shared/lib/crud/api-interceptor'` |
-| Response enricher types | `import type { ResponseEnricher } from '@open-mercato/shared/lib/crud/response-enricher'` |
-| Broadcast event check | `import { isBroadcastEvent } from '@open-mercato/shared/modules/events'` |
-
-## i18n — All User-Facing Strings
-
-Never hard-code user-facing text. Use locale files and translation helpers.
-
-```typescript
-// Client-side (React components)
-const t = useT()
-return <span>{t('my_module.labels.title')}</span>
-
-// Server-side (API routes, commands)
-const { t } = await resolveTranslations()
-const label = t('my_module.labels.title')
-```
-
-Add translations to `i18n/<locale>.json` files in your module.
-
-## Encryption — Query Encrypted Entities
-
-MUST use these instead of raw `em.find`/`em.findOne` when the entity may contain encrypted fields:
-
-```typescript
-const results = await findWithDecryption(em, 'Entity', filter, { tenantId, organizationId })
-const record = await findOneWithDecryption(em, 'Entity', filter, { tenantId, organizationId })
-```
-
-## Boolean Parsing
-
-For env vars and query params, never use `=== 'true'`:
-
-```typescript
-const isEnabled = parseBooleanToken(process.env.MY_FLAG) // true | false | undefined
-const withDefault = parseBooleanWithDefault(query.active, true) // defaults to true
-```
-
-## Safe Entity Flush
-
-When a command mutates entities across phases that include queries on the same `EntityManager`, use `withAtomicFlush` to prevent silent data loss:
-
-```typescript
-import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
-
-await withAtomicFlush(em, [
-  () => { record.name = 'New'; record.status = 'active' },
-  () => syncEntityTags(em, record, tags), // internal em.find() won't lose changes
-], { transaction: true })
-
-// Side effects AFTER the atomic flush
-await emitCrudSideEffects({ ... })
-```
-
-**Never** run `em.find`/`em.findOne` between scalar mutations and `em.flush()` without `withAtomicFlush`.
-
-## CRUD Multi-ID Filtering
-
-Filter list APIs by multiple IDs using `?ids=uuid1,uuid2`:
-
-```typescript
-import { parseIdsParam, mergeIdFilter } from '@open-mercato/shared/lib/crud/ids'
-const ids = parseIdsParam(query.ids) // string[] | undefined
-const filter = mergeIdFilter(existingFilter, ids) // intersects with existing id filter
-```
-
-## Custom Field Helpers
-
-When your entity uses custom fields:
-
-```typescript
-import { splitCustomFieldPayload, normalizeCustomFieldValues, normalizeCustomFieldResponse }
-  from '@open-mercato/shared/lib/custom-fields'
-
-// In create/update: split cf:* fields from standard fields
-const { standard, custom } = splitCustomFieldPayload(body)
-
-// Normalize for storage
-const normalized = normalizeCustomFieldValues(custom, fieldDefinitions)
-
-// Normalize for API response
-const response = normalizeCustomFieldResponse(record, customFields)
-```