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

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

@@ -0,0 +1,18 @@
+# Extension Branches
+
+Load only the selected branch.
+
+- **Enricher/query enricher:** use the dotted runtime entity ID in `targetEntity` (for example `customers.person`), never the colon-form CRUD/widget host ID; add a namespaced result, scoped batched `enrichMany`, ACL, timeout/fallback, and conservative cache behavior; set `queryEngine.enabled` only for query lifecycle participation.
+- **Interceptor:** exact route/method, schema-compatible request rewrite, additive response, timeout/fail posture, no auth/scope weakening.
+- **Command interceptor:** `commands/interceptors.ts`; stable `id` + exact `targetCommand`; choose `beforeExecute`/`afterExecute` and `beforeUndo`/`afterUndo` deliberately; wildcard-aware features and trusted scope; block or shallow-rewrite only through documented results; never bypass the command, locking, audit, or undo.
+- **Mutation guard:** operation mapping, wildcard features, explicit block/validated rewrite, post-commit callbacks, command/lock preservation.
+- **Widget/menu/client handler:** stable widget/item IDs, exact spot, deterministic placement, headless declaration when possible, display plus execution authorization; constrain client reactions with `eventHandlers.filter.operations`.
+- **Extension entity:** app-owned scoped table, scalar host ID, scoped uniqueness, orphan/delete behavior, no cross-module ORM relation.
+- **Subscriber:** declared event ID, persistent/idempotent decision, optional-host safe resolve, scoped command write, retry test; sync lifecycle work declares `metadata.sync`/`priority`, including `*.querying`/`*.queried` when applicable.
+- **Browser reaction:** reactive notifications use `notifications.handlers.ts`/`useNotificationEffect` and keep the visible reaction idempotent (`idempotent-client-side-effect`); general typed real-time events use `clientBroadcast`, `useAppEvent`, or `useOperationProgress` with authorization on the emitting API.
+- **Integration UI:** typed definition, wizard, health/status renderer, provider-scoped detail `widgetSpotId`, and deterministic tab/group/stack placement; add the integration and UI skills.
+- **Search/vector/AI/domain registry:** use `search.ts`/`vector.ts`, `<AiChat>`, or the typed payment/shipping/currency/workflow contract and route to its specialist procedure.
+- **Component override:** stable handle, preserve props/accessibility; prefer transform/wrapper.
+- **Module override:** supported domain/key, key/value identity, `null` disable semantics, generation/cache/nav cleanup.
+
+Run `yarn generate` for every discovered branch and verify generated registration selects the intended host exactly once.

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

@@ -0,0 +1,27 @@
+# Extension Mechanism Selector
+
+Load this reference before choosing files.
+
+| Requirement | Smallest mechanism |
+|---|---|
+| Add computed/list/detail fields | Response enricher; add a widget only when UI is also needed. |
+| Enrich query-engine reads | Enricher with `queryEngine.enabled`; preserve `*.querying`/`*.queried` lifecycle contracts. |
+| Validate/rewrite host request or add response data | API interceptor. |
+| Add behavior before/after command execute or undo | `commands/interceptors.ts` command interceptor with stable `id`/`targetCommand`. |
+| Block/rewrite host mutation with post-success work | Mutation guard contract. |
+| Add form/table/menu/page content | Headless/rendered widget injection. |
+| Filter a client widget reaction | Widget `eventHandlers.filter.operations`. |
+| Persist app-owned data against host record | Extension entity with scalar host ID. |
+| React synchronously or asynchronously | Typed subscriber; use `metadata.sync`/`priority` only for in-pipeline lifecycle work. |
+| React to a browser event | Reactive notification handler, or `clientBroadcast` plus `useAppEvent`/`useOperationProgress`. |
+| Add provider setup/status/detail UI | Typed integration definition plus integration wizard/status/detail widget injection. |
+| Add vector, embedded AI, or provider/domain behavior | `vector.ts`, `<AiChat>`, or the typed payment/shipping/currency/workflow registry; add the owning specialist skill. |
+| Adjust component behavior | Props transform, wrapper, then replacement. |
+| Hide/replace supported route/page/agent/tool/etc. | `src/modules.ts` unified override. |
+| Change unsupported internals | Eject only after explicit approval. |
+
+Resolve exact targets from the named module sheet's `UMES hosts` and `UMES contributions` first. Use `.ai/guides/framework-extension-points.md` for framework-owned menus, dashboard, notification, integration, and shell targets. Follow `fact-ref` and `specialistRoute` provenance instead of inventing a generic target; use exact installed context only for one named fact gap. `optional-external` degrades when its package is absent, while an `unresolved` first-party target blocks implementation.
+
+If multiple mechanisms are required (for example editable field = widget + enricher + interceptor), follow the shared `roundTripId`, name one owner for each read/write/UI leg, and test them as one round trip. Select only facts marked bound: DataTable's rendered header/footer/toolbar/search-trailing, headless columns/row-actions/bulk-actions/filters, and component handle; CrudForm's base/header/fields, component handle, and declared lifecycle/operation-filter pipeline. Base prefixes and helper-only/unbound IDs are not mountable. Reactive notifications, messages/inbox, query/vector, integrations, and AI/workflow work also select their owning task route; UMES does not replace that specialist context.
+
+Prefer additive composition before replacement (`additive-before-replacement`). Ejection is the last resort after supported seams are proven insufficient and explicit approval is granted (`eject-last`).

package/dist/agentic/shared/ai/skills/om-system-extension/references/read-write-roundtrip.md

@@ -0,0 +1,13 @@
+# Editable Extension Round Trip
+
+Load this reference for app fields/actions added to installed UI/data.
+
+1. Define app-owned storage or an existing host-supported custom field; keep full scope and locking.
+2. Add an enricher/detail read that returns a stable typed value, including explicit null.
+3. Inject a typed field/control into the exact CrudForm/DataTable host.
+4. Intercept/guard/dispatch the write through a command; validate scope/features/version and support clear-to-null.
+5. Invalidate the owning data/cache/search projections after commit.
+6. Map response data into initial values without truthy defaults.
+7. Test create or first save, reload, edit, clear, stale version, denied/wildcard ACL, and host absence.
+
+Do not stop after rendering the field. A visible input without read and durable write paths is incomplete.

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

@@ -0,0 +1,41 @@
+# Unified Override Domains
+
+Load this reference when `src/modules.ts` must disable or replace an installed contribution. `entry.overrides` is the only canonical app-level override umbrella. Resolve the exact key from the named module sheet's generated `overrideTargets` facts first: each target carries the exact top-level `domain`, the complete `path` segments, the terminal `key` for keyed-record domains, the supported `modes`, a `factRef` to the module-owned fact being overridden, and a portable `source`. Follow `factRef` provenance to the underlying route/page/event/worker/widget/agent/tool/setup/ACL/DI/encryption fact. When the module sheet reports an `overrideTargetDiagnostics` entry (`missing-owned-fact`, `missing-source`, `unsupported-dynamic-key`, `unknown-framework-domain`) for the domain you need, treat it as a blocker and escalate to the named source for one missing detail — never guess a key. Framework-only settings such as `nav.groupOrder` live in `framework-extension-points.md`, not in a module's `overrideTargets`. For keyed override maps, `null` disables a supported contribution and a typed value replaces it; AI extensions and setup hooks have the special shapes below.
+
+| Domain | Shape/key |
+|---|---|
+| AI agents/tools | `overrides.ai.agents`, `overrides.ai.tools` — agent ID/tool name |
+| Additive AI extensions | `overrides.ai.extensions` — ordered `AiAgentExtension[]`; additive array, not a key-to-`null` replacement map |
+| API routes | `overrides.routes.api` — `METHOD /api/path` |
+| Backend/frontend pages | `overrides.routes.pages` — `/backend/...` or `/frontend/...` |
+| Event subscribers | `overrides.events.subscribers` — subscriber ID |
+| Workers | `overrides.workers` — resolved `ModuleWorker.id`; explicit `metadata.id` wins, otherwise generated fallback `<module>:workers:<path>` |
+| Injection widgets | `overrides.widgets.injection` — generated registry `entry.key` |
+| Component overrides | `overrides.widgets.components` — component handle |
+| Dashboard widgets | `overrides.widgets.dashboard` — generated registry `entry.key` |
+| Notification types/handlers | `overrides.notifications.types`, `.handlers` — stable ID |
+| API interceptors | `overrides.interceptors` — interceptor ID |
+| Command interceptors | `overrides.commandInterceptors` — interceptor ID |
+| Response enrichers | `overrides.enrichers` — enricher ID |
+| Page guards/middleware | `overrides.guards` — middleware ID |
+| CLI commands | `overrides.cli` — command string |
+| Setup hooks | `overrides.setup` — entry-scoped `defaultRoleFeatures`, `defaultCustomerRoleFeatures`, `seedDefaults`, `seedExamples`, `onTenantCreated`; hook booleans use `false` to disable |
+| ACL features | `overrides.acl.features` — feature ID |
+| DI bindings | `overrides.di` — container key |
+| Encryption maps | `overrides.encryption.maps` — entity ID |
+
+## Rules
+
+- A global override map may be declared on an app override entry; it need not impersonate the module that originally contributed the keyed contract. Setup is entry-scoped. Do not add a competing route/widget/worker and hope load order wins.
+- API route methods are case-insensitive and paths normalize a leading/trailing slash; use the canonical displayed key. Disabling all methods removes the route entry.
+- Page keys name generated frontend/backend URL paths, not filesystem paths. After hiding a landing page, provide a safe accessible redirect.
+- Injection/dashboard keys are generated entry keys and may differ from widget metadata IDs. Worker keys are resolved descriptor IDs; inspect generated facts/source instead of constructing them from memory.
+- Require the generated `overrideTargets` entry's exact `domain`, `path`/`key`, and `modes` (`disable-replace`, `replace`, or `additive`). A stale or `unresolved` first-party correlation, or an `overrideTargetDiagnostics` row for that domain, is a blocker; it is not a fallback to a guessed key. Copy the `path` verbatim — do not flatten nested widget/AI segments.
+- `overrides.guards` targets backend/frontend page route middleware only (the `page-middleware` owned fact). A `data/guards.ts` mutation guard is a different contract with no override domain; it surfaces as an extension activation, never under `overrides.guards`. The target's `page-middleware-not-mutation-guard` note flags this.
+- Before adding a contribution, check the target module sheet's `incoming` index for an already-installed contributor of the same kind/target, and require a `bound` `activation` (not a broad capability host) before assuming a route/entity extension actually runs. A `capability-only` host is available but unproven; do not claim runtime invocation from it.
+- Keep AI extensions additive and ordered. Use agent/tool maps only for replacement or disable; do not encode an extension as a `null`-capable map entry.
+- Preserve replacement type/signature, auth/features, scope, stable ID, and observable side effects. A replacement may strengthen safety but never silently narrow a public contract.
+- Treat unknown/stale override diagnostics as failures. Run `yarn generate`, clear structural nav/module caches with the app's documented command, and verify the old contribution is absent in every bootstrap.
+- Verify host present/absent, wildcard ACL, direct URL/API access, registry uniqueness, cache/navigation cleanup, and rollback to the base contribution.
+
+For additive behavior use an enricher, interceptor, guard, widget/menu, extension entity, event subscriber, or component wrapper instead of replacing the whole contribution.

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

@@ -0,0 +1,11 @@
+# Extension Verification
+
+Load this reference after implementing the selected mechanism.
+
+- Confirm no installed/generated file changed and app module ownership is clear.
+- Confirm resolved host tokens match the installed version and generated facts.
+- Test host present and absent, authorized/denied/wildcard users, two scopes, and direct API access without UI.
+- Test list/detail/create/update/delete/action legs that the extension touches.
+- Test timeout/failure fallback, retry/idempotency, cache hit/miss, and search/index behavior where relevant.
+- Run `yarn generate`, focused tests, typecheck, and affected integration flow.
+- Disable/replace branches must remove stale navigation/cache/registry behavior and retain a safe backend landing route.

package/dist/agentic/shared/ai/skills/om-trim-unused-modules/SKILL.md

@@ -1,73 +1,25 @@
 ---
 name: om-trim-unused-modules
-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.
+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".
 ---
 
-# Trim Unused Modules
+# Trim Built-Ins Safely
 
-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).
+Propose a dependency-aware set first; edit `src/modules.ts` only after the user accepts the set.
 
 ## Workflow
 
-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.
+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.
 
-## When NOT to run this skill
+## Rules
 
-- 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.
+- 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.

package/dist/agentic/shared/ai/skills/om-trim-unused-modules/references/dependency-and-redirect.md

@@ -0,0 +1,15 @@
+# Module Dependency and Redirect Audit
+
+Load before disabling modules.
+
+For each enabled module, inspect:
+
+- declared/soft dependencies and `src/modules.ts` overrides;
+- app imports, pages, widgets, events/subscribers, DI resolves, setup, CLI, workers, AI/workflows;
+- provider/integration hosts and generated module facts;
+- backend navigation and landing destination;
+- auth, configs, entities, query index, and other bootstrap infrastructure.
+
+Classify uncertainty as keep until resolved. When dashboards is disabled, replace its backend landing render/import with a role/ACL-aware redirect to the first enabled main destination; use `/backend/profile` only when no accessible business page exists.
+
+After changes run generation, login/setup, backend root/sidebar/settings/profile, CLI/worker bootstrap, typecheck/build, and affected tests. Confirm no generated import still targets a disabled package/module.