@open-mercato/cli 0.6.7-develop.6862.1.c11a64ce0a → 0.6.7

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

@@ -0,0 +1,271 @@
+# 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-trim-unused-modules/SKILL.md

@@ -1,25 +1,73 @@
 ---
 name: om-trim-unused-modules
-description: Analyze and disable unused built-in modules in a standalone app without breaking dependencies, navigation, backend landing, bootstrap, or generation. Use for "trim classic mode", "remove unused modules", "slim app", "disable built-ins", or "wyłącz moduły".
+description: Propose disabling modules in src/modules.ts that the current standalone project does not actually use. Intended to be offered after the user adds a new custom module, because a fresh create-mercato-app scaffold enables every built-in module (classic mode) and that is rarely what the project actually needs in production.
 ---
 
-# Trim Built-Ins Safely
+# Trim Unused Modules
 
-Propose a dependency-aware set first; edit `src/modules.ts` only after the user accepts the set.
+A fresh `create-mercato-app` scaffold enables every built-in Open Mercato module by default (classic mode) so that the app "just works" on day one. Once the user has added a new custom module and knows what they actually want to build, many of those defaults are dead weight — they slow down `yarn dev`, pollute the navigation sidebar, pull in unnecessary dependencies, and show the user features that will confuse their end users.
+
+Invoke this skill when:
+
+- The user just added a new module to `src/modules.ts` via `yarn mercato module add …` or by hand-creating `src/modules/<name>/`.
+- The user asks "which modules do I really need?" or "how do I slim down the app?"
+- You notice during another task that `src/modules.ts` still has every built-in module enabled AND the user's business domain clearly does not need some of them (e.g. a blog-only app with `sales`, `catalog`, `currencies`, `workflows`, `integrations`, `data_sync` all active).
 
 ## Workflow
 
-1. Read `references/dependency-and-redirect.md`, `src/modules.ts`, package dependencies, generated module facts, and app imports/overrides.
-2. Classify each module as required, optional-used, optional-unused, or uncertain. Keep dependencies, auth/setup, and host modules for active extensions/providers.
-3. Present the proposed disabled set and effects; ask for confirmation when the request did not name exact modules.
-4. Disable through `src/modules.ts`/supported configuration. Remove only app-owned references made invalid by the decision.
-5. If dashboards is disabled, update the backend landing route to the first accessible enabled page with profile as last fallback.
-6. Run `yarn generate`, structural cache purge if available, typecheck/build, login/backend navigation, setup, CLI, worker, and affected module tests.
+1. **Never disable modules silently.** Always confirm with the user via `AskUserQuestion` before editing `src/modules.ts`.
+
+2. **Read the current module list.** Parse `src/modules.ts`. For each entry:
+   - Record the module `id` and its source (`@open-mercato/core`, `@open-mercato/<package>`, `@app`).
+   - Flag entries with `from: '@app'` as **user modules** — never propose disabling these.
+   - Flag entries with `from: '@open-mercato/…'` as **built-in modules** — eligible for review.
+
+3. **Gather usage signals.** For each built-in module, check:
+   - Is the module's feature ID referenced in `src/modules/**/acl.ts` or `src/modules/**/setup.ts`?
+   - Is a type/name from the module imported anywhere in `src/**`?
+   - Does any subscriber/worker declaration in `src/modules/**` reference an event ID the module owns?
+   - Does the backend sidebar config reference routes from the module?
+   - Is the module listed as a hard dependency in any enabled integration provider's manifest?
+   Record yes/no per signal. If ALL signals return "no", mark the module as a **removal candidate**.
+
+4. **Mark hard-required modules.** Never propose disabling modules that other parts of the framework rely on by convention. The baseline set that should stay enabled in almost every project:
+   - `auth`, `customer_accounts`, `entities`, `configs`, `organizations`, `tenants`, `users`
+   Include any module that another enabled module's `setup.ts` declares as a dependency.
+
+5. **Present the proposal.** Use `AskUserQuestion` with a multi-select list of removal candidates. Include:
+   - The module ID and a one-line description of what it does.
+   - Which usage signals came back negative.
+   - Whether disabling it will require running DB operations (e.g. dropping its tables — NOT something this skill performs; flag it so the user knows).
+
+6. **Apply the user's choices.** For each module the user confirms:
+   - Remove the entry from `src/modules.ts`.
+   - Do NOT delete files from `node_modules/@open-mercato/*` (packages stay installed — disabling just means the app no longer loads them).
+   - Do NOT drop the module's database tables. Data removal is a separate, destructive operation that the user must request explicitly.
+   - **If `dashboards` is one of the disabled modules, you MUST also update `src/app/(backend)/backend/page.tsx`** so it no longer renders `<DashboardScreen />`. Replace the body with a `redirect(...)` to the first backend page the user can reach — prefer the main sidebar group (e.g. `/backend/customers/people`) and fall back to `/backend/profile` if nothing else is enabled. Without this edit, `/backend` will crash at build or request time because the removed module no longer ships `DashboardScreen`. Commit this edit in the same change as the `src/modules.ts` edit.
+
+7. **Re-run the generator.** After the edit:
+
+   ```bash
+   yarn generate
+   ```
+
+   This regenerates `.mercato/generated/*` without the disabled modules and triggers the best-effort structural cache purge.
+
+8. **Report.** Print a short summary:
+   - Which modules were disabled.
+   - Which modules were kept (and the signal that kept each).
+   - Reminder that package dependencies are still installed and module tables still exist; if the user wants to fully remove a module, they must uninstall the package and manually drop its tables.
+
+## Constraints
+
+- NEVER remove a `from: '@app'` entry.
+- NEVER remove `auth`, `customer_accounts`, `entities`, `configs`, `organizations`, `tenants`, or `users`.
+- NEVER delete files from `node_modules/` or from `src/modules/<mod>/` on behalf of the user — only edit `src/modules.ts`.
+- NEVER drop database tables.
+- If the user answers "no" to every removal candidate, exit quietly and note that classic mode is preserved.
 
-## Rules
+## When NOT to run this skill
 
-- Never delete installed package files, migrations, or generated registries.
-- Never disable a module required by an enabled module, extension host, override, bootstrap, or provider.
-- Preserve user-authored app modules and behavior unless explicitly included.
-- Treat module metadata/source as read-only evidence and report uncertainty rather than guessing.
-- Disabling a registry entry does not modify a framework public contract; do not load `BACKWARD_COMPATIBILITY.md` unless the requested work also changes a stable ID, route, type, signature, or other contract surface.
+- In a monorepo development environment (`apps/mercato/src/modules.ts`) — the monorepo deliberately keeps every module enabled for framework development.
+- On an imported ready app (`--app` or `--app-url`) — those snapshots are curated by their authors.
+- During a `yarn dev` run — disabling modules while the server is live can cause transient errors. Ask the user to stop `yarn dev`, run the skill, then restart.