@open-mercato/cli 0.6.7 → 0.6.8-develop.6875.1.871a4afc94

package/dist/agentic/shared/ai/skills/om-module-scaffold/references/naming-conventions.md

@@ -1,50 +0,0 @@
-# Naming Conventions Quick Reference
-
-> **Source of truth:** `AGENTS.md` (Naming Conventions / Conventions, Architecture Rules, Multi-tenant scoping) owns these rules. This file is an example-oriented cheat sheet for scaffolding — when it disagrees with `AGENTS.md`, `AGENTS.md` wins.
-
-## Module & Files
-
-| Element | Convention | Example |
-|---------|-----------|---------|
-| Module ID | plural, snake_case | `fleet_vehicles`, `loyalty_points` |
-| Module folder | same as module ID | `src/modules/fleet_vehicles/` |
-| Entity class | PascalCase, singular | `FleetVehicle`, `LoyaltyPoint` |
-| Entity file | single `data/entities.ts` (one class per entity) | `data/entities.ts` → `class FleetVehicle` |
-| Table name | plural, snake_case | `fleet_vehicles`, `loyalty_points` |
-| Column name | snake_case | `vehicle_type`, `point_balance` |
-
-## Identifiers
-
-| Element | Convention | Example |
-|---------|-----------|---------|
-| JS/TS fields | camelCase | `vehicleType`, `pointBalance` |
-| Event ID | `module.entity.action` (dots, singular entity, past tense) | `fleet_vehicles.vehicle.created` |
-| Feature ID | `module.entity.action` (per-entity; use `view` / `manage`) | `fleet_vehicles.vehicle.view`, `fleet_vehicles.vehicle.manage` |
-| Enricher ID | `module.enricher-name` | `fleet_vehicles.maintenance-stats` |
-| Widget ID | `module.injection.widget-name` | `fleet_vehicles.injection.status-column` |
-| Interceptor ID | `module.interceptor-name` | `fleet_vehicles.validate-vin` |
-| Guard ID | `module.guard-name` | `fleet_vehicles.mileage-limit` |
-
-## Standard Entity Columns
-
-Every tenant-scoped entity MUST carry the standard columns (`id`, `organization_id`, `tenant_id`, `is_active`, `created_at`, `updated_at`, `deleted_at`) with `organization_id`/`tenant_id` indexed. See `AGENTS.md` → Conventions / Multi-tenant scoping for the authoritative list and types.
-
-## API Routes
-
-All HTTP methods live in a **single** `api/<entities>/route.ts` that exports named handlers `{ GET, POST, PUT, DELETE }` + `metadata` + `openApi` (not separate `api/get/`, `api/post/` files).
-
-| File Path | Methods | URL |
-|-----------|---------|-----|
-| `api/<entities>/route.ts` | `GET` / `POST` / `PUT` / `DELETE` | `/api/<module>/<entities>` |
-
-## Backend Pages
-
-| File Path | URL |
-|----------|-----|
-| `backend/page.tsx` | `/backend/<module>` |
-| `backend/<entities>/new.tsx` | `/backend/<module>/<entities>/new` |
-| `backend/<entities>/[id].tsx` | `/backend/<module>/<entities>/<id>` |
-
-## Cross-Module References
-
-Store cross-module links as `uuid` FK fields (`customer_id`, `order_id`) and fetch related data via separate API calls or enrichers — never `@ManyToOne` / `@OneToMany` decorators across modules. See `AGENTS.md` → Architecture Rules for the authoritative rule.

package/dist/agentic/shared/ai/skills/om-module-scaffold/references/navigation-patterns.md

@@ -1,97 +0,0 @@
-# Navigation & Sidebar Patterns
-
-## page.meta.ts — Field Reference
-
-Every backend page needs a `page.meta.ts` file alongside its `page.tsx`. The metadata controls sidebar placement, access control, and display.
-
-| Field | Type | Default | Purpose |
-|-------|------|---------|---------|
-| `pageTitle` | string | — | Display title in sidebar and breadcrumb |
-| `pageTitleKey` | string | — | i18n key for title (preferred over `pageTitle`) |
-| `pageGroup` | string | — | **Sidebar section name** — items with same group appear together |
-| `pageGroupKey` | string | — | **i18n key for group** — used as the group identifier for matching |
-| `pageOrder` | number | 10000 | Sort position within group (lower = higher in sidebar) |
-| `icon` | ReactNode | — | Sidebar icon — MUST use `lucide-react` components |
-| `requireAuth` | boolean | false | Require authenticated user |
-| `requireFeatures` | string[] | — | Required ACL feature IDs (from `acl.ts`) |
-| `navHidden` | boolean | false | Hide from sidebar (page still accessible by URL) |
-| `pageContext` | `'main'` \| `'settings'` \| `'profile'` | `'main'` | Which navigation tier this page belongs to |
-| `breadcrumb` | `{ label, labelKey?, href? }[]` | — | Breadcrumb trail above page title |
-
-## Sidebar Group Configuration
-
-Items are grouped by `pageGroupKey` (falls back to `pageGroup` if no key). **All related pages in a module MUST share the same `pageGroupKey`** to appear in the same sidebar section.
-
-```typescript
-// page.meta.ts — List page (appears in sidebar)
-import { ShoppingCart } from 'lucide-react'
-
-export const metadata = {
-  requireAuth: true,
-  requireFeatures: ['order_items.view'],
-  pageTitle: 'Order Items',
-  pageTitleKey: 'order_items.nav.title',
-  pageGroup: 'Orders',                       // Display name for the sidebar section
-  pageGroupKey: 'order_items.nav.group',      // Matching key — all module pages use this
-  pageOrder: 100,                             // Position in the group
-  icon: <ShoppingCart className="size-4" />,
-  breadcrumb: [{ label: 'Order Items', labelKey: 'order_items.nav.title' }],
-}
-```
-
-**Group sorting**: Core module groups (Customers, Catalog, Sales) appear first in a hardcoded order. Custom module groups appear after, sorted by their lowest `pageOrder` value.
-
-## Settings Pages
-
-Settings pages appear in the Settings hub, not the main sidebar. They require two fields:
-
-```typescript
-// backend/config/page.meta.ts
-import { Settings } from 'lucide-react'
-
-export const metadata = {
-  requireAuth: true,
-  requireFeatures: ['order_items.settings.manage'],
-  pageTitle: 'Order Items Settings',
-  pageTitleKey: 'order_items.config.title',
-  pageGroup: 'Module Configs',
-  pageGroupKey: 'settings.sections.moduleConfigs',
-  pageOrder: 10,
-  icon: <Settings className="size-4" />,
-  pageContext: 'settings' as const,           // ← Places in Settings hub
-  navHidden: true,                            // ← MUST set — prevents duplicate in main sidebar
-}
-```
-
-**Standard settings section keys**: `settings.sections.system`, `settings.sections.auth`, `settings.sections.moduleConfigs`, `settings.sections.directory`.
-
-## Sub-Pages (Create / Edit / Detail)
-
-- **`[id]` pages**: Auto-excluded from sidebar (framework skips dynamic segments). Still need `pageGroupKey` for breadcrumb context.
-- **Create pages** (`new.tsx`): Set `navHidden: true` since they're accessed via the list page's create button.
-
-```typescript
-// backend/<entities>/new.meta.ts
-export const metadata = {
-  requireAuth: true,
-  requireFeatures: ['order_items.create'],
-  pageTitle: 'Create Order Item',
-  pageTitleKey: 'order_items.create.title',
-  pageGroup: 'Orders',
-  pageGroupKey: 'order_items.nav.group',      // ← Same key as list page
-  navHidden: true,                            // ← Not shown in sidebar
-}
-```
-
-## Anti-Patterns
-
-| Mistake | Symptom | Fix |
-|---------|---------|-----|
-| Missing `pageGroup` + `pageGroupKey` | Item creates orphan group or lands in "Uncategorized" | Add both fields matching your module's group |
-| Mismatched `pageGroupKey` across pages | Items from same module split into separate sidebar sections | Use identical `pageGroupKey` on all module pages |
-| Missing `icon` | Blank space in sidebar next to title | Add `lucide-react` icon component |
-| Inline SVG via `React.createElement` | Broken/wrong icon after `yarn generate` | Use `import { X } from 'lucide-react'` |
-| `pageContext: 'settings'` without `navHidden: true` | Page appears in both main sidebar AND settings hub | Always pair both fields |
-| Missing `as const` on `pageContext` | TypeScript error — type widened to `string` | Use `pageContext: 'settings' as const` |
-| Missing `pageOrder` | Unpredictable sort position (defaults to 10000) | Set explicit order value |
-| Missing `requireFeatures` | Page visible to users without permission | Add feature IDs from `acl.ts` |

package/dist/agentic/shared/ai/skills/om-system-extension/references/extension-contracts.md

@@ -1,271 +0,0 @@
-# UMES Extension Contracts — Type Reference
-
-Complete TypeScript type definitions for all extension mechanisms.
-
-## ResponseEnricher
-
-```typescript
-interface ResponseEnricher<TRecord = any, TEnriched = any> {
-  id: string
-  targetEntity: string
-  features?: string[]
-  priority?: number            // Higher = runs first. Default: 0
-  timeout?: number             // Max ms before skip. Default: 2000
-  fallback?: Record<string, unknown>
-  critical?: boolean           // Propagate errors? Default: false
-  disabledTenantIds?: string[]
-  cache?: {
-    strategy: 'read-through'
-    ttl: number
-    tags?: string[]
-    invalidateOn?: string[]
-  }
-  queryEngine?: {
-    enabled: boolean
-    engines?: Array<'basic' | 'hybrid'>
-    applyOn?: Array<'list' | 'detail'>
-  }
-
-  enrichOne(record: TRecord, context: EnricherContext): Promise<TRecord & TEnriched>
-  enrichMany?(records: TRecord[], context: EnricherContext): Promise<(TRecord & TEnriched)[]>
-}
-
-interface EnricherContext {
-  organizationId: string
-  tenantId: string
-  userId: string
-  em: EntityManager
-  container: AwilixContainer
-  requestedFields?: string[]
-  userFeatures?: string[]
-}
-```
-
-## ApiInterceptor
-
-```typescript
-type ApiInterceptorMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
-
-type InterceptorRequest = {
-  method: ApiInterceptorMethod
-  url: string
-  body?: Record<string, unknown>
-  query?: Record<string, unknown>
-  headers: Record<string, string>
-}
-
-type InterceptorResponse = {
-  statusCode: number
-  body: Record<string, unknown>
-  headers: Record<string, string>
-}
-
-type InterceptorContext = {
-  userId: string
-  organizationId: string
-  tenantId: string
-  em: EntityManager
-  container: AwilixContainer
-  userFeatures?: string[]
-  metadata?: Record<string, unknown>
-}
-
-type InterceptorBeforeResult = {
-  ok: boolean
-  body?: Record<string, unknown>
-  query?: Record<string, unknown>
-  headers?: Record<string, string>
-  message?: string
-  statusCode?: number
-  metadata?: Record<string, unknown>
-}
-
-type InterceptorAfterResult = {
-  merge?: Record<string, unknown>
-  replace?: Record<string, unknown>
-}
-
-type ApiInterceptor = {
-  id: string
-  targetRoute: string
-  methods: ApiInterceptorMethod[]
-  priority?: number          // Lower = earlier. Default: 50
-  features?: string[]
-  timeoutMs?: number         // Default: 5000
-  before?: (request: InterceptorRequest, context: InterceptorContext) => Promise<InterceptorBeforeResult>
-  after?: (request: InterceptorRequest, response: InterceptorResponse, context: InterceptorContext) => Promise<InterceptorAfterResult>
-}
-```
-
-## MutationGuard
-
-```typescript
-interface MutationGuard {
-  id: string
-  targetEntity: string | '*'
-  operations: ('create' | 'update' | 'delete')[]
-  priority?: number          // Lower = earlier. Default: 50
-  features?: string[]
-
-  validate(input: MutationGuardInput): Promise<MutationGuardResult>
-  afterSuccess?(input: MutationGuardAfterInput): Promise<void>
-}
-
-interface MutationGuardInput {
-  tenantId: string
-  organizationId: string | null
-  userId: string
-  resourceKind: string
-  resourceId: string | null    // null for create
-  operation: 'create' | 'update' | 'delete'
-  requestMethod: string
-  requestHeaders: Headers
-  mutationPayload?: Record<string, unknown> | null
-}
-
-interface MutationGuardResult {
-  ok: boolean
-  status?: number              // Default: 422
-  message?: string
-  body?: Record<string, unknown>
-  modifiedPayload?: Record<string, unknown>
-  shouldRunAfterSuccess?: boolean
-  metadata?: Record<string, unknown>
-}
-
-interface MutationGuardAfterInput {
-  tenantId: string
-  organizationId: string | null
-  userId: string
-  resourceKind: string
-  resourceId: string
-  operation: 'create' | 'update' | 'delete'
-  requestMethod: string
-  requestHeaders: Headers
-  metadata?: Record<string, unknown> | null
-}
-```
-
-## InjectionPosition
-
-```typescript
-enum InjectionPosition {
-  Before = 'before',
-  After = 'after',
-  First = 'first',
-  Last = 'last',
-}
-
-type InjectionPlacement = {
-  position?: InjectionPosition
-  relativeTo?: string
-}
-```
-
-## ComponentOverride
-
-```typescript
-type ComponentOverride<TProps = unknown> = {
-  target: { componentId: string }
-  priority: number
-  features?: string[]
-  metadata?: { module?: string }
-} & (
-  | { replacement: LazyExoticComponent<ComponentType<TProps>> | ComponentType<TProps>; propsSchema: ZodType<TProps> }
-  | { wrapper: (Original: ComponentType<TProps>) => ComponentType<TProps> }
-  | { propsTransform: (props: TProps) => TProps }
-)
-
-// Handle constructors
-ComponentReplacementHandles.page(path)         // → 'page:<path>'
-ComponentReplacementHandles.dataTable(tableId) // → 'data-table:<tableId>'
-ComponentReplacementHandles.crudForm(entityId) // → 'crud-form:<entityId>'
-ComponentReplacementHandles.section(scope, id) // → 'section:<scope>.<id>'
-```
-
-## Widget Event Handlers
-
-```typescript
-type WidgetInjectionEventHandlers<TContext = unknown, TData = unknown> = {
-  filter?: WidgetInjectionEventFilter
-  onLoad?: (context: TContext) => void | Promise<void>
-  onBeforeSave?: (data: TData, context: TContext) => WidgetBeforeSaveResult | Promise<WidgetBeforeSaveResult>
-  onSave?: (data: TData, context: TContext) => void | Promise<void>
-  onAfterSave?: (data: TData, context: TContext) => void | Promise<void>
-  onBeforeDelete?: (data: TData, context: TContext) => WidgetBeforeDeleteResult | Promise<WidgetBeforeDeleteResult>
-  onDelete?: (data: TData, context: TContext) => void | Promise<void>
-  onAfterDelete?: (data: TData, context: TContext) => void | Promise<void>
-  onFieldChange?: (fieldId: string, value: unknown, data: TData, context: TContext) => Promise<FieldChangeResult | void>
-  onBeforeNavigate?: (target: string, context: TContext) => Promise<NavigateGuardResult>
-  onVisibilityChange?: (visible: boolean, context: TContext) => Promise<void>
-  onAppEvent?: (event: AppEventPayload, context: TContext) => Promise<void>
-  transformFormData?: (data: TData, context: TContext) => Promise<TData | { data: TData; applyToForm: true }>
-  transformDisplayData?: (data: TData, context: TContext) => Promise<TData>
-  transformValidation?: (errors: Record<string, string>, data: TData, context: TContext) => Promise<Record<string, string>>
-}
-
-type FieldChangeResult = {
-  value?: unknown
-  sideEffects?: Record<string, unknown>
-  message?: { text: string; severity: 'info' | 'warning' | 'error' }
-}
-```
-
-## Widget Injection Spot IDs
-
-### CrudForm Spots
-
-```
-crud-form:<entityId>:fields
-```
-
-Examples: `crud-form:customers.person:fields`, `crud-form:catalog.product:fields`
-
-### DataTable Spots
-
-```
-data-table:<tableId>:columns
-data-table:<tableId>:row-actions
-data-table:<tableId>:bulk-actions
-data-table:<tableId>:filters
-```
-
-Examples: `data-table:customers.people:columns`, `data-table:sales.orders:row-actions`
-
-### Menu Spots
-
-```
-menu:sidebar:main
-menu:sidebar:settings
-menu:sidebar:profile
-menu:topbar:profile-dropdown
-menu:topbar:actions
-```
-
-### Detail Page Spots
-
-```
-<module>.<entity>:detail:tabs
-<module>.<entity>:detail:sections
-```
-
-## Execution Pipeline Order
-
-```
-Request arrives
-  ↓
-1. Zod schema validation
-2. API Interceptor before hooks
-3. Sync before-event subscribers (*.creating)
-4. CrudHooks.beforeCreate/Update/Delete (module-local)
-5. Mutation Guard Registry validate
-6. Entity mutation + ORM flush
-7. CrudHooks.afterCreate/Update/Delete
-8. Mutation Guard Registry afterSuccess
-9. Sync after-event subscribers (*.created)
-10. Async event subscribers (persistent, queued)
-11. Response Enrichers (list/detail endpoints only)
-12. API Interceptor after hooks
-  ↓
-Response returned
-```

package/dist/agentic/shared/ai/skills/om-troubleshooter/references/diagnostic-commands.md

@@ -1,101 +0,0 @@
-# Diagnostic Commands Reference
-
-## Health Check Sequence
-
-Run in this order — each step depends on the previous:
-
-```bash
-# 1. Are services running?
-docker compose ps
-
-# 2. Is the database reachable?
-yarn db:migrate --dry-run   # Lists pending migrations without applying
-
-# 3. Are generated files up to date?
-yarn generate
-
-# 4. Are types correct?
-yarn typecheck
-
-# 5. Do tests pass?
-yarn test
-
-# 6. Does it build?
-yarn build
-```
-
-## Module Discovery
-
-```bash
-# Check what modules are registered
-grep -n 'from:' src/modules.ts
-
-# Check what was auto-discovered
-ls .mercato/generated/
-
-# Check a specific module's files
-ls -la src/modules/<module_id>/
-```
-
-## Database State
-
-```bash
-# Check pending migrations
-yarn db:migrate --dry-run
-
-# Generate migration for entity changes
-yarn db:generate
-
-# Apply migrations (destructive — confirm first)
-yarn db:migrate
-
-# Full database reset (destructive — deletes all data)
-yarn initialize --force
-```
-
-## API Testing
-
-```bash
-# Test an API endpoint (requires auth token)
-curl -H "Authorization: Bearer <token>" http://localhost:3000/api/<module>/<entities>
-
-# Check API docs
-# Navigate to: http://localhost:3000/api/docs
-```
-
-## Extension Debugging
-
-```bash
-# Check if enrichers are registered
-grep 'enrichers' .mercato/generated/enrichers.generated.ts
-
-# Check if widgets are registered
-grep 'injection' .mercato/generated/injection-widgets.generated.ts
-
-# Check if interceptors are registered
-grep 'interceptors' .mercato/generated/interceptors.generated.ts
-```
-
-## Clean Reset
-
-When everything is broken and you need a fresh start:
-
-```bash
-# 1. Clean generated files
-rm -rf .mercato/generated/
-
-# 2. Clean node_modules cache
-rm -rf node_modules/.cache
-
-# 3. Reinstall dependencies
-yarn install
-
-# 4. Regenerate everything
-yarn generate
-
-# 5. Check for pending migrations
-yarn db:generate
-
-# 6. Restart dev server
-yarn dev
-```