create-mercato-app 0.6.7 → 0.6.8-develop.6874.1.982d6097d8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +72 -0
- package/agentic/claude-code/hooks/entity-migration-check.ts +32 -88
- package/agentic/codex/enforcement-rules.md +2 -16
- package/agentic/cursor/hooks/entity-migration-check.mjs +19 -50
- package/agentic/cursor/rules/entity-guard.mdc +9 -21
- package/agentic/cursor/rules/generated-guard.mdc +3 -5
- package/agentic/cursor/rules/open-mercato.mdc +3 -29
- package/agentic/guides/ai-workflows.md +76 -0
- package/agentic/guides/architecture.md +107 -0
- package/agentic/guides/backend-ui.md +80 -0
- package/agentic/guides/contracts.md +92 -0
- package/agentic/guides/extensions.md +121 -0
- package/agentic/guides/integrations.md +81 -0
- package/agentic/guides/module-system.md +12 -127
- package/agentic/guides/spec-delivery.md +22 -0
- package/agentic/guides/testing-debugging.md +80 -0
- package/agentic/shared/AGENTS.md.template +124 -311
- package/agentic/shared/ai/agentic.config.json +2 -0
- package/agentic/shared/ai/harness/README.md +50 -0
- package/agentic/shared/ai/harness/RELEASE.md +57 -0
- package/agentic/shared/ai/harness/cases.json +13680 -0
- package/agentic/shared/ai/harness/cases.schema.json +133 -0
- package/agentic/shared/ai/harness/fixtures/index.json +49 -0
- package/agentic/shared/ai/harness/fixtures/seeds.json +162 -0
- package/agentic/shared/ai/harness/generated-code-review-policy.md +21 -0
- package/agentic/shared/ai/harness/generated-code-review-response.schema.json +96 -0
- package/agentic/shared/ai/harness/generated-code-review-result.schema.json +172 -0
- package/agentic/shared/ai/harness/release-matrix.json +158 -0
- package/agentic/shared/ai/harness/release-result.schema.json +219 -0
- package/agentic/shared/ai/harness/result.schema.json +76 -0
- package/agentic/shared/ai/harness/routing-response.schema.json +12 -0
- package/agentic/shared/ai/harness/target-validation-result.schema.json +73 -0
- package/agentic/shared/ai/harness/validators.json +78 -0
- package/agentic/shared/ai/harness/writable-ast-oracles.mjs +2121 -0
- package/agentic/shared/ai/harness/writable-behavior-oracles.mjs +1096 -0
- package/agentic/shared/ai/lessons/_template.md +16 -0
- package/agentic/shared/ai/lessons.md +26 -3
- package/agentic/shared/ai/review-checklist.md +36 -0
- package/agentic/shared/ai/skills/om-auto-implement-spec/SKILL.md +21 -0
- package/agentic/shared/ai/skills/om-auto-review-pr/SKILL.md +4 -0
- package/agentic/shared/ai/skills/om-auto-upgrade-0.6.6-to-0.6.7/SKILL.md +98 -0
- package/agentic/shared/ai/skills/om-backend-ui-design/SKILL.md +20 -241
- package/agentic/shared/ai/skills/om-backend-ui-design/references/crud-surfaces.md +16 -0
- package/agentic/shared/ai/skills/om-backend-ui-design/references/frontend-and-design-system.md +53 -0
- package/agentic/shared/ai/skills/om-backend-ui-design/references/page-and-navigation.md +13 -0
- package/agentic/shared/ai/skills/om-backend-ui-design/references/quality-states.md +11 -0
- package/agentic/shared/ai/skills/om-build-workflow/SKILL.md +30 -0
- package/agentic/shared/ai/skills/om-build-workflow/references/activity-contracts.md +12 -0
- package/agentic/shared/ai/skills/om-build-workflow/references/durability-and-progress.md +13 -0
- package/agentic/shared/ai/skills/om-build-workflow/references/workflow-design.md +14 -0
- package/agentic/shared/ai/skills/om-create-ai-agent/SKILL.md +28 -0
- package/agentic/shared/ai/skills/om-create-ai-agent/references/attachments-and-overrides.md +12 -0
- package/agentic/shared/ai/skills/om-create-ai-agent/references/module-agents-and-tools.md +22 -0
- package/agentic/shared/ai/skills/om-create-ai-agent/references/orchestrator-agents.md +12 -0
- package/agentic/shared/ai/skills/om-create-ai-agent/references/surface-selector.md +19 -0
- package/agentic/shared/ai/skills/om-data-model-design/SKILL.md +16 -601
- package/agentic/shared/ai/skills/om-data-model-design/references/integrity-and-concurrency.md +19 -0
- package/agentic/shared/ai/skills/om-data-model-design/references/migration-workflow.md +13 -0
- package/agentic/shared/ai/skills/om-data-model-design/references/schema-design.md +14 -0
- package/agentic/shared/ai/skills/om-data-model-design/references/sensitive-data.md +10 -0
- package/agentic/shared/ai/skills/om-eject-and-customize/SKILL.md +14 -310
- package/agentic/shared/ai/skills/om-eject-and-customize/references/decision-and-procedure.md +17 -0
- package/agentic/shared/ai/skills/om-evolve-harness/SKILL.md +29 -0
- package/agentic/shared/ai/skills/om-evolve-harness/references/case-template.md +100 -0
- package/agentic/shared/ai/skills/om-evolve-harness/references/case-workflow.md +16 -0
- package/agentic/shared/ai/skills/om-evolve-harness/references/owner-selection.md +17 -0
- package/agentic/shared/ai/skills/om-framework-context/SKILL.md +25 -0
- package/agentic/shared/ai/skills/om-framework-context/references/resolver-procedure.md +11 -0
- package/agentic/shared/ai/skills/om-framework-context/references/skew-and-escalation.md +13 -0
- package/agentic/shared/ai/skills/om-help/SKILL.md +15 -97
- package/agentic/shared/ai/skills/om-help/references/delivery-workflows.md +18 -0
- package/agentic/shared/ai/skills/om-help/references/task-families.md +20 -0
- package/agentic/shared/ai/skills/om-implement-spec/SKILL.md +33 -152
- package/agentic/shared/ai/skills/om-implement-spec/references/phases-and-gates.md +33 -0
- package/agentic/shared/ai/skills/om-implement-spec/references/planning-and-progress.md +40 -0
- package/agentic/shared/ai/skills/om-implement-spec/references/report-templates.md +27 -0
- package/agentic/shared/ai/skills/om-implement-spec/references/spec-resolution.md +24 -0
- package/agentic/shared/ai/skills/om-integration-builder/SKILL.md +24 -708
- package/agentic/shared/ai/skills/om-integration-builder/references/package-and-activation.md +16 -0
- package/agentic/shared/ai/skills/om-integration-builder/references/provider-families.md +14 -0
- package/agentic/shared/ai/skills/om-integration-builder/references/security-and-reliability.md +15 -0
- package/agentic/shared/ai/skills/om-integration-builder/references/sync-and-files.md +12 -0
- package/agentic/shared/ai/skills/om-judge-agent-session/SKILL.md +34 -0
- package/agentic/shared/ai/skills/om-judge-agent-session/agents/openai.yaml +4 -0
- package/agentic/shared/ai/skills/om-judge-agent-session/references/agentic-setup.md +11 -0
- package/agentic/shared/ai/skills/om-judge-agent-session/references/input-normalization.md +31 -0
- package/agentic/shared/ai/skills/om-judge-agent-session/references/judge-workflow.md +39 -0
- package/agentic/shared/ai/skills/om-judge-agent-session/references/report-template.md +43 -0
- package/agentic/shared/ai/skills/om-judge-agent-session/references/rules.md +11 -0
- package/agentic/shared/ai/skills/om-module-scaffold/SKILL.md +20 -820
- package/agentic/shared/ai/skills/om-module-scaffold/references/api-and-domain.md +19 -0
- package/agentic/shared/ai/skills/om-module-scaffold/references/business-one-shot-blueprints.md +172 -0
- package/agentic/shared/ai/skills/om-module-scaffold/references/data-and-migrations.md +12 -0
- package/agentic/shared/ai/skills/om-module-scaffold/references/discovery-surface-catalog.md +83 -0
- package/agentic/shared/ai/skills/om-module-scaffold/references/module-surfaces.md +21 -0
- package/agentic/shared/ai/skills/om-module-scaffold/references/planning.md +11 -0
- package/agentic/shared/ai/skills/om-module-scaffold/references/runtime-cache-and-queues.md +22 -0
- package/agentic/shared/ai/skills/om-module-scaffold/references/verification.md +13 -0
- package/agentic/shared/ai/skills/om-share-this-session/SKILL.md +41 -0
- package/agentic/shared/ai/skills/om-share-this-session/references/agentic-setup.md +19 -0
- package/agentic/shared/ai/skills/om-share-this-session/references/bundle-preparation.md +44 -0
- package/agentic/shared/ai/skills/om-share-this-session/references/consent-and-review.md +39 -0
- package/agentic/shared/ai/skills/om-share-this-session/references/publication.md +20 -0
- package/agentic/shared/ai/skills/om-share-this-session/references/report-templates.md +57 -0
- package/agentic/shared/ai/skills/om-share-this-session/references/rules.md +11 -0
- package/agentic/shared/ai/skills/om-share-this-session/scripts/prepare-share-bundle.mjs +486 -0
- package/agentic/shared/ai/skills/om-system-extension/SKILL.md +19 -843
- package/agentic/shared/ai/skills/om-system-extension/references/extension-branches.md +18 -0
- package/agentic/shared/ai/skills/om-system-extension/references/mechanism-selector.md +27 -0
- package/agentic/shared/ai/skills/om-system-extension/references/read-write-roundtrip.md +13 -0
- package/agentic/shared/ai/skills/om-system-extension/references/unified-overrides.md +41 -0
- package/agentic/shared/ai/skills/om-system-extension/references/verification.md +11 -0
- package/agentic/shared/ai/skills/om-trim-unused-modules/SKILL.md +15 -63
- package/agentic/shared/ai/skills/om-trim-unused-modules/references/dependency-and-redirect.md +15 -0
- package/agentic/shared/ai/skills/om-troubleshooter/SKILL.md +16 -467
- package/agentic/shared/ai/skills/om-troubleshooter/references/diagnosis-map.md +16 -0
- package/agentic/shared/ai/skills/om-troubleshooter/references/regression-oracles.md +14 -0
- package/agentic/shared/ai/skills/tiers.json +143 -21
- package/agentic/shared/ai/skills/tiers.schema.json +52 -40
- package/agentic/shared/ai/specs/README.md +4 -3
- package/agentic/shared/ai/specs/SPEC-000-template.md +226 -10
- package/agentic/shared/ai/trackers/github.md +108 -4
- package/agentic/shared/scripts/agent-harness-tool-server.mjs +187 -0
- package/agentic/shared/scripts/check-lessons.mjs +178 -0
- package/agentic/shared/scripts/evaluate-agent-harness.mjs +2958 -0
- package/agentic/shared/scripts/execution-sandbox.mjs +329 -0
- package/agentic/shared/scripts/framework-context.mjs +888 -0
- package/agentic/shared/scripts/install-skills.mjs +1029 -0
- package/agentic/shared/scripts/install-skills.sh +4 -694
- package/agentic/shared/scripts/prepare-agent-harness-fixture.mjs +222 -0
- package/agentic/shared/scripts/run-agent-harness-release.mjs +1774 -0
- package/dist/agentic/claude-code/hooks/entity-migration-check.ts +32 -88
- package/dist/agentic/codex/enforcement-rules.md +2 -16
- package/dist/agentic/cursor/hooks/entity-migration-check.mjs +19 -50
- package/dist/agentic/cursor/rules/entity-guard.mdc +9 -21
- package/dist/agentic/cursor/rules/generated-guard.mdc +3 -5
- package/dist/agentic/cursor/rules/open-mercato.mdc +3 -29
- package/dist/agentic/guides/ai-workflows.md +76 -0
- package/dist/agentic/guides/architecture.md +107 -0
- package/dist/agentic/guides/backend-ui.md +80 -0
- package/dist/agentic/guides/contracts.md +92 -0
- package/dist/agentic/guides/extensions.md +121 -0
- package/dist/agentic/guides/framework-extension-points.md +36 -0
- package/dist/agentic/guides/integrations.md +81 -0
- package/dist/agentic/guides/module-facts.json +115537 -3951
- package/dist/agentic/guides/module-system.md +12 -127
- package/dist/agentic/guides/modules/ai_assistant.md +227 -28
- package/dist/agentic/guides/modules/api_docs.md +58 -2
- package/dist/agentic/guides/modules/api_keys.md +92 -7
- package/dist/agentic/guides/modules/attachments.md +119 -14
- package/dist/agentic/guides/modules/audit_logs.md +131 -10
- package/dist/agentic/guides/modules/auth.md +276 -33
- package/dist/agentic/guides/modules/business_rules.md +149 -14
- package/dist/agentic/guides/modules/catalog.md +475 -43
- package/dist/agentic/guides/modules/channel_gmail.md +82 -3
- package/dist/agentic/guides/modules/channel_imap.md +82 -3
- package/dist/agentic/guides/modules/checkout.md +299 -27
- package/dist/agentic/guides/modules/communication_channels.md +315 -33
- package/dist/agentic/guides/modules/configs.md +104 -8
- package/dist/agentic/guides/modules/content.md +57 -2
- package/dist/agentic/guides/modules/currencies.md +152 -17
- package/dist/agentic/guides/modules/customer_accounts.md +387 -45
- package/dist/agentic/guides/modules/customers.md +746 -85
- package/dist/agentic/guides/modules/dashboards.md +155 -10
- package/dist/agentic/guides/modules/data_sync.md +149 -16
- package/dist/agentic/guides/modules/design_system.md +102 -0
- package/dist/agentic/guides/modules/dictionaries.md +107 -12
- package/dist/agentic/guides/modules/directory.md +148 -15
- package/dist/agentic/guides/modules/entities.md +145 -13
- package/dist/agentic/guides/modules/events.md +59 -2
- package/dist/agentic/guides/modules/feature_toggles.md +119 -9
- package/dist/agentic/guides/modules/gateway_stripe.md +92 -4
- package/dist/agentic/guides/modules/generators.md +45 -2
- package/dist/agentic/guides/modules/inbox_ops.md +207 -27
- package/dist/agentic/guides/modules/integrations.md +146 -16
- package/dist/agentic/guides/modules/messages.md +223 -24
- package/dist/agentic/guides/modules/notifications.md +96 -8
- package/dist/agentic/guides/modules/onboarding.md +77 -6
- package/dist/agentic/guides/modules/payment_gateways.md +164 -21
- package/dist/agentic/guides/modules/perspectives.md +77 -7
- package/dist/agentic/guides/modules/planner.md +136 -18
- package/dist/agentic/guides/modules/portal.md +93 -2
- package/dist/agentic/guides/modules/progress.md +104 -14
- package/dist/agentic/guides/modules/query_index.md +154 -15
- package/dist/agentic/guides/modules/record_locks.md +206 -21
- package/dist/agentic/guides/modules/resources.md +197 -30
- package/dist/agentic/guides/modules/sales.md +678 -84
- package/dist/agentic/guides/modules/scheduler.md +133 -14
- package/dist/agentic/guides/modules/search.md +170 -6
- package/dist/agentic/guides/modules/security.md +294 -35
- package/dist/agentic/guides/modules/shipping_carriers.md +134 -18
- package/dist/agentic/guides/modules/sso.md +151 -26
- package/dist/agentic/guides/modules/staff.md +369 -57
- package/dist/agentic/guides/modules/storage_s3.md +95 -5
- package/dist/agentic/guides/modules/sync_akeneo.md +85 -3
- package/dist/agentic/guides/modules/sync_excel.md +75 -6
- package/dist/agentic/guides/modules/system_status_overlays.md +60 -2
- package/dist/agentic/guides/modules/translations.md +104 -10
- package/dist/agentic/guides/modules/webhooks.md +203 -24
- package/dist/agentic/guides/modules/wms.md +441 -46
- package/dist/agentic/guides/modules/workflows.md +302 -43
- package/dist/agentic/guides/spec-delivery.md +22 -0
- package/dist/agentic/guides/testing-debugging.md +80 -0
- package/dist/agentic/guides/upstream/AGENTS.md +299 -0
- package/dist/agentic/guides/upstream/BACKWARD_COMPATIBILITY.md +316 -0
- package/dist/agentic/guides/upstream/manifest.json +8 -0
- package/dist/agentic/shared/AGENTS.md.template +124 -311
- package/dist/agentic/shared/ai/agentic.config.json +2 -0
- package/dist/agentic/shared/ai/harness/README.md +50 -0
- package/dist/agentic/shared/ai/harness/RELEASE.md +57 -0
- package/dist/agentic/shared/ai/harness/cases.json +13680 -0
- package/dist/agentic/shared/ai/harness/cases.schema.json +133 -0
- package/dist/agentic/shared/ai/harness/fixtures/index.json +49 -0
- package/dist/agentic/shared/ai/harness/fixtures/seeds.json +162 -0
- package/dist/agentic/shared/ai/harness/generated-code-review-policy.md +21 -0
- package/dist/agentic/shared/ai/harness/generated-code-review-response.schema.json +96 -0
- package/dist/agentic/shared/ai/harness/generated-code-review-result.schema.json +172 -0
- package/dist/agentic/shared/ai/harness/release-matrix.json +158 -0
- package/dist/agentic/shared/ai/harness/release-result.schema.json +219 -0
- package/dist/agentic/shared/ai/harness/result.schema.json +76 -0
- package/dist/agentic/shared/ai/harness/routing-response.schema.json +12 -0
- package/dist/agentic/shared/ai/harness/target-validation-result.schema.json +73 -0
- package/dist/agentic/shared/ai/harness/validators.json +78 -0
- package/dist/agentic/shared/ai/harness/writable-ast-oracles.mjs +2121 -0
- package/dist/agentic/shared/ai/harness/writable-behavior-oracles.mjs +1096 -0
- package/dist/agentic/shared/ai/lessons/_template.md +16 -0
- package/dist/agentic/shared/ai/lessons.md +26 -3
- package/dist/agentic/shared/ai/review-checklist.md +36 -0
- package/dist/agentic/shared/ai/skills/om-auto-implement-spec/SKILL.md +21 -0
- package/dist/agentic/shared/ai/skills/om-auto-review-pr/SKILL.md +4 -0
- package/dist/agentic/shared/ai/skills/om-auto-upgrade-0.6.6-to-0.6.7/SKILL.md +98 -0
- package/dist/agentic/shared/ai/skills/om-backend-ui-design/SKILL.md +20 -241
- package/dist/agentic/shared/ai/skills/om-backend-ui-design/references/crud-surfaces.md +16 -0
- package/dist/agentic/shared/ai/skills/om-backend-ui-design/references/frontend-and-design-system.md +53 -0
- package/dist/agentic/shared/ai/skills/om-backend-ui-design/references/page-and-navigation.md +13 -0
- package/dist/agentic/shared/ai/skills/om-backend-ui-design/references/quality-states.md +11 -0
- package/dist/agentic/shared/ai/skills/om-build-workflow/SKILL.md +30 -0
- package/dist/agentic/shared/ai/skills/om-build-workflow/references/activity-contracts.md +12 -0
- package/dist/agentic/shared/ai/skills/om-build-workflow/references/durability-and-progress.md +13 -0
- package/dist/agentic/shared/ai/skills/om-build-workflow/references/workflow-design.md +14 -0
- package/dist/agentic/shared/ai/skills/om-create-ai-agent/SKILL.md +28 -0
- package/dist/agentic/shared/ai/skills/om-create-ai-agent/references/attachments-and-overrides.md +12 -0
- package/dist/agentic/shared/ai/skills/om-create-ai-agent/references/module-agents-and-tools.md +22 -0
- package/dist/agentic/shared/ai/skills/om-create-ai-agent/references/orchestrator-agents.md +12 -0
- package/dist/agentic/shared/ai/skills/om-create-ai-agent/references/surface-selector.md +19 -0
- package/dist/agentic/shared/ai/skills/om-data-model-design/SKILL.md +16 -601
- package/dist/agentic/shared/ai/skills/om-data-model-design/references/integrity-and-concurrency.md +19 -0
- package/dist/agentic/shared/ai/skills/om-data-model-design/references/migration-workflow.md +13 -0
- package/dist/agentic/shared/ai/skills/om-data-model-design/references/schema-design.md +14 -0
- package/dist/agentic/shared/ai/skills/om-data-model-design/references/sensitive-data.md +10 -0
- package/dist/agentic/shared/ai/skills/om-eject-and-customize/SKILL.md +14 -310
- package/dist/agentic/shared/ai/skills/om-eject-and-customize/references/decision-and-procedure.md +17 -0
- package/dist/agentic/shared/ai/skills/om-evolve-harness/SKILL.md +29 -0
- package/dist/agentic/shared/ai/skills/om-evolve-harness/references/case-template.md +100 -0
- package/dist/agentic/shared/ai/skills/om-evolve-harness/references/case-workflow.md +16 -0
- package/dist/agentic/shared/ai/skills/om-evolve-harness/references/owner-selection.md +17 -0
- package/dist/agentic/shared/ai/skills/om-framework-context/SKILL.md +25 -0
- package/dist/agentic/shared/ai/skills/om-framework-context/references/resolver-procedure.md +11 -0
- package/dist/agentic/shared/ai/skills/om-framework-context/references/skew-and-escalation.md +13 -0
- package/dist/agentic/shared/ai/skills/om-help/SKILL.md +15 -97
- package/dist/agentic/shared/ai/skills/om-help/references/delivery-workflows.md +18 -0
- package/dist/agentic/shared/ai/skills/om-help/references/task-families.md +20 -0
- package/dist/agentic/shared/ai/skills/om-implement-spec/SKILL.md +33 -152
- package/dist/agentic/shared/ai/skills/om-implement-spec/references/phases-and-gates.md +33 -0
- package/dist/agentic/shared/ai/skills/om-implement-spec/references/planning-and-progress.md +40 -0
- package/dist/agentic/shared/ai/skills/om-implement-spec/references/report-templates.md +27 -0
- package/dist/agentic/shared/ai/skills/om-implement-spec/references/spec-resolution.md +24 -0
- package/dist/agentic/shared/ai/skills/om-integration-builder/SKILL.md +24 -708
- package/dist/agentic/shared/ai/skills/om-integration-builder/references/package-and-activation.md +16 -0
- package/dist/agentic/shared/ai/skills/om-integration-builder/references/provider-families.md +14 -0
- package/dist/agentic/shared/ai/skills/om-integration-builder/references/security-and-reliability.md +15 -0
- package/dist/agentic/shared/ai/skills/om-integration-builder/references/sync-and-files.md +12 -0
- package/dist/agentic/shared/ai/skills/om-judge-agent-session/SKILL.md +34 -0
- package/dist/agentic/shared/ai/skills/om-judge-agent-session/agents/openai.yaml +4 -0
- package/dist/agentic/shared/ai/skills/om-judge-agent-session/references/agentic-setup.md +11 -0
- package/dist/agentic/shared/ai/skills/om-judge-agent-session/references/input-normalization.md +31 -0
- package/dist/agentic/shared/ai/skills/om-judge-agent-session/references/judge-workflow.md +39 -0
- package/dist/agentic/shared/ai/skills/om-judge-agent-session/references/report-template.md +43 -0
- package/dist/agentic/shared/ai/skills/om-judge-agent-session/references/rules.md +11 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/SKILL.md +20 -820
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/api-and-domain.md +19 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/business-one-shot-blueprints.md +172 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/data-and-migrations.md +12 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/discovery-surface-catalog.md +83 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/module-surfaces.md +21 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/planning.md +11 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/runtime-cache-and-queues.md +22 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/verification.md +13 -0
- package/dist/agentic/shared/ai/skills/om-share-this-session/SKILL.md +41 -0
- package/dist/agentic/shared/ai/skills/om-share-this-session/references/agentic-setup.md +19 -0
- package/dist/agentic/shared/ai/skills/om-share-this-session/references/bundle-preparation.md +44 -0
- package/dist/agentic/shared/ai/skills/om-share-this-session/references/consent-and-review.md +39 -0
- package/dist/agentic/shared/ai/skills/om-share-this-session/references/publication.md +20 -0
- package/dist/agentic/shared/ai/skills/om-share-this-session/references/report-templates.md +57 -0
- package/dist/agentic/shared/ai/skills/om-share-this-session/references/rules.md +11 -0
- package/dist/agentic/shared/ai/skills/om-share-this-session/scripts/prepare-share-bundle.mjs +486 -0
- package/dist/agentic/shared/ai/skills/om-system-extension/SKILL.md +19 -843
- package/dist/agentic/shared/ai/skills/om-system-extension/references/extension-branches.md +18 -0
- package/dist/agentic/shared/ai/skills/om-system-extension/references/mechanism-selector.md +27 -0
- package/dist/agentic/shared/ai/skills/om-system-extension/references/read-write-roundtrip.md +13 -0
- package/dist/agentic/shared/ai/skills/om-system-extension/references/unified-overrides.md +41 -0
- package/dist/agentic/shared/ai/skills/om-system-extension/references/verification.md +11 -0
- package/dist/agentic/shared/ai/skills/om-trim-unused-modules/SKILL.md +15 -63
- package/dist/agentic/shared/ai/skills/om-trim-unused-modules/references/dependency-and-redirect.md +15 -0
- package/dist/agentic/shared/ai/skills/om-troubleshooter/SKILL.md +16 -467
- package/dist/agentic/shared/ai/skills/om-troubleshooter/references/diagnosis-map.md +16 -0
- package/dist/agentic/shared/ai/skills/om-troubleshooter/references/regression-oracles.md +14 -0
- package/dist/agentic/shared/ai/skills/tiers.json +143 -21
- package/dist/agentic/shared/ai/skills/tiers.schema.json +52 -40
- package/dist/agentic/shared/ai/specs/README.md +4 -3
- package/dist/agentic/shared/ai/specs/SPEC-000-template.md +226 -10
- package/dist/agentic/shared/ai/trackers/github.md +108 -4
- package/dist/agentic/shared/scripts/agent-harness-tool-server.mjs +187 -0
- package/dist/agentic/shared/scripts/check-lessons.mjs +178 -0
- package/dist/agentic/shared/scripts/evaluate-agent-harness.mjs +2958 -0
- package/dist/agentic/shared/scripts/execution-sandbox.mjs +329 -0
- package/dist/agentic/shared/scripts/framework-context.mjs +888 -0
- package/dist/agentic/shared/scripts/install-skills.mjs +1029 -0
- package/dist/agentic/shared/scripts/install-skills.sh +4 -694
- package/dist/agentic/shared/scripts/prepare-agent-harness-fixture.mjs +222 -0
- package/dist/agentic/shared/scripts/run-agent-harness-release.mjs +1774 -0
- package/dist/index.js +175 -184
- package/package.json +9 -7
- package/template/.env.example +59 -2
- package/template/.yarnrc.yml.template +9 -0
- package/template/AGENTS.md +93 -663
- package/template/eslint.config.mjs +1 -0
- package/template/gitignore +8 -0
- package/template/jest.config.cjs +2 -1
- package/template/jest.setup.ts +29 -0
- package/template/next.config.ts +55 -0
- package/template/package.json.template +31 -25
- package/template/scripts/dev-memory-monitor.mjs +92 -0
- package/template/scripts/dev-memory-sampler.mjs +464 -0
- package/template/scripts/dev-runtime-log-policy.mjs +33 -0
- package/template/scripts/dev-runtime.mjs +142 -76
- package/template/scripts/dev.mjs +129 -7
- package/template/scripts/evaluate-agent-harness.mjs +4 -0
- package/template/scripts/framework-context.mjs +4 -0
- package/template/scripts/install-skills.mjs +10 -0
- package/template/scripts/install-skills.sh +2 -19
- package/template/scripts/prepare-agent-harness-fixture.mjs +4 -0
- package/template/scripts/run-agent-harness-release.mjs +4 -0
- package/template/src/app/(backend)/backend/__tests__/layout-route-registry.test.tsx +1 -0
- package/template/src/app/(backend)/backend/layout.tsx +5 -3
- package/template/src/app/(frontend)/layout.tsx +1 -1
- package/template/src/app/api/[...slug]/route.ts +9 -0
- package/template/src/app/globals.css +61 -3
- package/template/src/app/layout.tsx +2 -18
- package/template/src/app/page.tsx +4 -1
- package/template/src/components/AppProviders.tsx +4 -1
- package/template/src/components/DemoFeedbackWidget.tsx +1 -1
- package/template/src/components/__tests__/AppProviders.test.tsx +11 -2
- package/template/src/components/__tests__/StartPageContent.test.tsx +69 -0
- package/template/src/components/__tests__/starter-chrome-ds.test.ts +35 -0
- package/template/src/i18n/de.json +21 -1
- package/template/src/i18n/en.json +21 -1
- package/template/src/i18n/es.json +21 -1
- package/template/src/i18n/ko.json +970 -0
- package/template/src/i18n/pl.json +21 -1
- package/template/src/instrumentation.ts +14 -1
- package/template/src/lib/i18n/register-dictionary-loader.ts +2 -0
- package/template/src/modules/example/__integration__/TC-EXAMPLE-001-todo-label-edit.spec.ts +123 -0
- package/template/src/modules/example/__integration__/TC-EXAMPLE-002-query-index-failure.spec.ts +155 -0
- package/template/src/modules/example/__integration__/TC-UMES-003.spec.ts +7 -3
- package/template/src/modules/example/__integration__/TC-UMES-005.spec.ts +7 -1
- package/template/src/modules/example/__integration__/TC-UMES-009.spec.ts +11 -10
- package/template/src/modules/example/__integration__/todo-priority-validation.spec.ts +31 -1
- package/template/src/modules/example/acl.ts +6 -0
- package/template/src/modules/example/backend/mutation-lifecycle/page.meta.ts +1 -9
- package/template/src/modules/example/backend/page.meta.ts +1 -10
- package/template/src/modules/example/backend/payments/page.meta.ts +1 -10
- package/template/src/modules/example/backend/payments/page.tsx +2 -2
- package/template/src/modules/example/backend/todos/create/page.meta.ts +1 -11
- package/template/src/modules/example/backend/todos/page.meta.ts +1 -10
- package/template/src/modules/example/backend/umes-extensions/page.meta.ts +1 -9
- package/template/src/modules/example/backend/umes-handlers/page.meta.ts +1 -10
- package/template/src/modules/example/backend/umes-integrations/page.meta.ts +1 -10
- package/template/src/modules/example/backend/umes-next-phases/page.meta.ts +1 -11
- package/template/src/modules/example/backend/umes-query-extensions/page.meta.ts +1 -11
- package/template/src/modules/example/commands/__tests__/todos.prepare-scope.test.ts +77 -0
- package/template/src/modules/example/commands/todos.ts +47 -2
- package/template/src/modules/example/i18n/ko.json +481 -0
- package/template/src/modules/example/i18n/pl.json +68 -68
- package/template/src/modules/example/lib/__tests__/mock-webhook-endpoint-adapter.test.ts +14 -0
- package/template/src/modules/example_customers_sync/i18n/ko.json +11 -0
- package/template/src/modules.ts +17 -0
- package/template/tsconfig.json +3 -2
- package/agentic/shared/ai/skills/om-auto-continue-pr-loop/SKILL.md +0 -27
- package/agentic/shared/ai/skills/om-auto-create-pr-loop/SKILL.md +0 -27
- package/agentic/shared/ai/skills/om-backend-ui-design/references/ui-components.md +0 -260
- package/agentic/shared/ai/skills/om-data-model-design/references/mikro-orm-cheatsheet.md +0 -146
- package/agentic/shared/ai/skills/om-help/references/skills-catalog.md +0 -84
- package/agentic/shared/ai/skills/om-help/references/workflow-sequences.md +0 -193
- package/agentic/shared/ai/skills/om-integration-builder/STANDALONE.md +0 -34
- package/agentic/shared/ai/skills/om-integration-builder/references/adapter-contracts.md +0 -762
- package/agentic/shared/ai/skills/om-module-scaffold/references/naming-conventions.md +0 -50
- package/agentic/shared/ai/skills/om-module-scaffold/references/navigation-patterns.md +0 -97
- package/agentic/shared/ai/skills/om-system-extension/references/extension-contracts.md +0 -271
- package/agentic/shared/ai/skills/om-troubleshooter/references/diagnostic-commands.md +0 -101
- package/dist/agentic/guides/cache.md +0 -45
- package/dist/agentic/guides/core.md +0 -453
- package/dist/agentic/guides/events.md +0 -117
- package/dist/agentic/guides/queue.md +0 -53
- package/dist/agentic/guides/search.md +0 -115
- package/dist/agentic/guides/shared.md +0 -108
- package/dist/agentic/guides/ui.md +0 -347
- package/dist/agentic/shared/ai/skills/om-auto-continue-pr-loop/SKILL.md +0 -27
- package/dist/agentic/shared/ai/skills/om-auto-create-pr-loop/SKILL.md +0 -27
- package/dist/agentic/shared/ai/skills/om-backend-ui-design/references/ui-components.md +0 -260
- package/dist/agentic/shared/ai/skills/om-data-model-design/references/mikro-orm-cheatsheet.md +0 -146
- package/dist/agentic/shared/ai/skills/om-help/references/skills-catalog.md +0 -84
- package/dist/agentic/shared/ai/skills/om-help/references/workflow-sequences.md +0 -193
- package/dist/agentic/shared/ai/skills/om-integration-builder/STANDALONE.md +0 -34
- package/dist/agentic/shared/ai/skills/om-integration-builder/references/adapter-contracts.md +0 -762
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/naming-conventions.md +0 -50
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/navigation-patterns.md +0 -97
- package/dist/agentic/shared/ai/skills/om-system-extension/references/extension-contracts.md +0 -271
- package/dist/agentic/shared/ai/skills/om-troubleshooter/references/diagnostic-commands.md +0 -101
package/template/AGENTS.md
CHANGED
|
@@ -1,698 +1,128 @@
|
|
|
1
|
-
# Standalone Open Mercato
|
|
1
|
+
# Standalone Open Mercato App — Agent Rules
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Route first; never probe unmatched context.
|
|
4
4
|
|
|
5
5
|
## Always
|
|
6
6
|
|
|
7
|
-
-
|
|
8
|
-
-
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
7
|
+
- Route all axes; missing context: `yarn mercato agentic:init --update-harness`.
|
|
8
|
+
- Lessons: scan `.ai/lessons.md` tags; open/update one matching record + row.
|
|
9
|
+
- App code: `src/modules/<id>/`; framework context only for named gaps.
|
|
10
|
+
- Derive trusted `tenantId` + `organizationId` and fail closed. Only an installed contract may use system scope (`organizationId: null`).
|
|
11
|
+
- Use commands/`makeCrudRoute`/`CrudForm`/`DataTable`, DI/events/UMES; effects stay post-commit.
|
|
12
|
+
- Put entities in `src/modules/<id>/data/entities.ts`; API routes need per-method `metadata` + `openApi`.
|
|
13
|
+
- Editable records expose `updated_at`/`updatedAt`; custom update/delete clients send the version and surface 409s.
|
|
14
|
+
- Run `yarn db:generate`, review scoped SQL/snapshot, and ask before applying it.
|
|
15
|
+
- Run `yarn generate` after discovery files, `src/modules.ts`, routes, pages, events, widgets, agents, tools, or workflows change.
|
|
16
|
+
- Contract-surface changes (route/schema/ID/export/seam/signature/event payload/CLI) MUST read `.ai/guides/upstream/BACKWARD_COMPATIBILITY.md`; tenant/org scope alone is not a contract.
|
|
17
|
+
- Localize strings; use shared UI/tokens and cover loading/empty/error/conflict/keyboard/a11y.
|
|
12
18
|
|
|
13
19
|
## Ask First
|
|
14
20
|
|
|
15
|
-
- Ask before
|
|
16
|
-
- Ask before using manual SQL instead of the generated migration path.
|
|
17
|
-
- Ask before adding a new framework primitive when a canonical mechanism is not listed below.
|
|
18
|
-
- Ask before enabling live external services, secrets, or provider credentials in tests.
|
|
21
|
+
- Ask before scope/architecture/public contracts/dependencies/ejection/canonical primitives; migrations/resets/DB targets; live credentials/providers; or weakening security/concurrency/retries/idempotency/audit/undo.
|
|
19
22
|
|
|
20
23
|
## Never
|
|
21
24
|
|
|
22
|
-
- Never
|
|
23
|
-
- Never
|
|
24
|
-
- Never
|
|
25
|
-
- Never
|
|
26
|
-
- Never
|
|
25
|
+
- Never leak tenants, trust payload scope, or treat missing scope as unrestricted.
|
|
26
|
+
- Never edit `node_modules`, `.mercato/generated/**`, generated facts, or shipped migrations.
|
|
27
|
+
- Never use cross-module ORM relations; use IDs/snapshots, events, enrichers, extensions, or optional DI.
|
|
28
|
+
- Never use raw admin `fetch`/`<form>`, ad hoc crypto/cache/queues, role-name guards, or direct mutations when helpers exist.
|
|
29
|
+
- Never hard-code user strings/status colors; expose secrets/transcripts; or guess answerable contracts.
|
|
27
30
|
|
|
28
|
-
## Validation
|
|
31
|
+
## Validation
|
|
29
32
|
|
|
30
|
-
|
|
31
|
-
yarn generate
|
|
32
|
-
yarn typecheck
|
|
33
|
-
yarn lint
|
|
34
|
-
yarn test
|
|
35
|
-
yarn build
|
|
36
|
-
yarn test:integration:ephemeral
|
|
37
|
-
```
|
|
33
|
+
Use the smallest relevant set. Broad: `yarn generate && yarn typecheck && yarn lint && yarn test && yarn build`; integration: `yarn test:integration:ephemeral`. Report failures; never migrate to validate.
|
|
38
34
|
|
|
39
|
-
##
|
|
35
|
+
## Three-Axis Context Assembler
|
|
40
36
|
|
|
41
|
-
|
|
37
|
+
Routes are additive: ownership says WHO; other axes say WHAT. Select every match.
|
|
42
38
|
|
|
43
|
-
-
|
|
44
|
-
- **Source exploration**: Search `node_modules/@open-mercato/` for module implementations
|
|
45
|
-
- **Key packages**:
|
|
46
|
-
- `@open-mercato/core` - Core business modules (auth, customers, catalog, sales, etc.)
|
|
47
|
-
- `@open-mercato/shared` - Shared utilities, types, DSL helpers, i18n
|
|
48
|
-
- `@open-mercato/ui` - UI components and primitives
|
|
49
|
-
- `@open-mercato/cli` - CLI tooling (mercato command)
|
|
50
|
-
- `@open-mercato/search` - Search module (fulltext, vector, tokens)
|
|
39
|
+
`debugging` is additive. A scalar-ID/snapshot fix to persisted records or commands linked to an installed record MUST use `module-data` + `umes` and load `om-data-model-design` + `om-system-extension`.
|
|
51
40
|
|
|
52
|
-
|
|
41
|
+
`debugging` = reported bug/security/drift, not designed failure UI. Specs use `spec-pr`; implementation owns domain guides. Custom fields/entities = `umes` + `module-data` + `om-data-model-design`; editable round trips add `backend-ui`, requested coverage adds `testing`. Never infer work from specs/PRs.
|
|
53
42
|
|
|
54
|
-
|
|
43
|
+
Unified-override audits = `umes` only; add `architecture`/`framework-context` only for unresolved ownership or installed keys. Durable process/activity/user task = `module-data` + `ai-workflow`. Multi-stage waits/cancel/restart are durable; reminders and renewal/batch schedules are `module-data`.
|
|
55
44
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
45
|
+
`backend-ui`: replacing/wrapping, prop-transforming, menu-editing, or adding visible feedback adds `backend-ui`; merely hiding/toggling/rewiring installed UI does not.
|
|
46
|
+
Staff UI preview/report/bulk = `backend-ui`.
|
|
47
|
+
Existing installed form/table fields, filters, row/bulk actions without app persistence = `umes` + `backend-ui` only: read `crud-surfaces` + `quality-states`; do not load contracts, module-scaffold, or page/navigation.
|
|
59
48
|
|
|
60
|
-
|
|
61
|
-
yarn dev:verbose
|
|
49
|
+
`backend-ui`: UI skill `references/quality-states.md`; public/portal/responsive/a11y adds `frontend-and-design-system.md`.
|
|
62
50
|
|
|
63
|
-
|
|
64
|
-
yarn dev:classic
|
|
51
|
+
### Axis 1 — Area/Ownership
|
|
65
52
|
|
|
66
|
-
|
|
67
|
-
yarn setup:classic
|
|
68
|
-
|
|
69
|
-
# Build for production
|
|
70
|
-
yarn build
|
|
71
|
-
|
|
72
|
-
# Run production server
|
|
73
|
-
yarn start
|
|
74
|
-
|
|
75
|
-
# Type checking
|
|
76
|
-
yarn typecheck
|
|
77
|
-
|
|
78
|
-
# Linting
|
|
79
|
-
yarn lint
|
|
80
|
-
|
|
81
|
-
# Run unit tests
|
|
82
|
-
yarn test
|
|
83
|
-
|
|
84
|
-
# Run a single unit test
|
|
85
|
-
yarn test path/to/test.spec.ts
|
|
86
|
-
|
|
87
|
-
# Run integration tests (preferred: provisions/reuses an ephemeral app + DB, runs Playwright)
|
|
88
|
-
yarn test:integration:ephemeral
|
|
89
|
-
|
|
90
|
-
# Start ephemeral app only (manual QA exploration or iterative test loops; admin@acme.com / secret)
|
|
91
|
-
yarn test:integration:ephemeral:start
|
|
92
|
-
|
|
93
|
-
# Iterate against the running ephemeral env with small filtered batches
|
|
94
|
-
yarn mercato test:integration <filter>
|
|
95
|
-
|
|
96
|
-
# View HTML integration test report
|
|
97
|
-
npx playwright show-report .ai/qa/test-results/html
|
|
98
|
-
|
|
99
|
-
# Generate code from modules
|
|
100
|
-
yarn generate
|
|
101
|
-
|
|
102
|
-
# Manually purge structural caches when needed (Redis nav:* + Turbopack barrel mtimes)
|
|
103
|
-
yarn mercato configs cache structural --all-tenants
|
|
104
|
-
|
|
105
|
-
# Escape hatch: clear .mercato/next/dev and legacy .next caches when Turbopack still serves a stale chunk
|
|
106
|
-
yarn dev:reset
|
|
107
|
-
|
|
108
|
-
# Database operations
|
|
109
|
-
yarn db:generate # Generate/probe migrations; keep or write only scoped SQL and update the touched snapshot
|
|
110
|
-
yarn db:migrate # Run migrations
|
|
111
|
-
yarn db:greenfield # Reset and recreate database
|
|
112
|
-
|
|
113
|
-
# Initialize/reinstall project
|
|
114
|
-
yarn initialize
|
|
115
|
-
yarn reinstall
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
## Dev Splash Features
|
|
119
|
-
|
|
120
|
-
- `yarn dev` serves the compact splash screen on `http://localhost:4000` by default and auto-opens it on supported local runs.
|
|
121
|
-
- When enabled, the splash can launch detected coding tools from the `Start coding with AI` menu.
|
|
122
|
-
- In standalone apps, the splash can also create or publish a GitHub repository through `gh` once the app is ready.
|
|
123
|
-
|
|
124
|
-
## Recommended Local Tooling
|
|
125
|
-
|
|
126
|
-
- GitHub CLI (`gh`) is recommended for the splash GitHub publish flow: <https://cli.github.com/>
|
|
127
|
-
- Codex CLI is recommended for the OpenAI terminal workflow surfaced by the splash: <https://developers.openai.com/codex/cli>
|
|
128
|
-
- Claude Code is recommended for the Anthropic terminal workflow surfaced by the splash: <https://code.claude.com/docs/en/setup>
|
|
129
|
-
- Visual Studio Code is the recommended general-purpose editor: <https://code.visualstudio.com/Download>
|
|
130
|
-
- Cursor is a recommended AI-first editor: <https://cursor.com/download>
|
|
131
|
-
|
|
132
|
-
## Dev Splash Environment Variables
|
|
133
|
-
|
|
134
|
-
| Variable | Default | Description |
|
|
135
|
-
|----------|---------|-------------|
|
|
136
|
-
| `OM_DEV_SPLASH_PORT` | `4000` | Override the splash port. Use `random` or `0` for an ephemeral free port. |
|
|
137
|
-
| `OM_DEV_AUTO_OPEN` | `1` | Set to `0` to disable browser auto-open for the splash. |
|
|
138
|
-
| `OM_DEV_CREATE_GIT_REPO_FLOW` | `true` | Set to `false` to hide the standalone GitHub publish panel from the splash. |
|
|
139
|
-
| `OM_ENABLE_CODING_FLOW_FROM_SPLASH` | `true` | Set to `false` to hide the coding tools menu from the splash. |
|
|
140
|
-
| `OM_DEV_SPLASH_VSCODE_PATH` | auto-detect | Optional path override for the VS Code CLI. |
|
|
141
|
-
| `OM_DEV_SPLASH_CURSOR_PATH` | auto-detect | Optional path override for the Cursor CLI. |
|
|
142
|
-
| `OM_DEV_SPLASH_CLAUDE_CODE_PATH` | auto-detect | Optional path override for the Claude Code CLI. |
|
|
143
|
-
| `OM_DEV_SPLASH_CODEX_PATH` | auto-detect | Optional path override for the Codex CLI. |
|
|
144
|
-
| `OM_DEV_AUTO_MIGRATE` | `1` | When set to `1` (default), `yarn dev` runs `yarn db:migrate` once at startup before Next.js boots. Set to `0` to disable. See "Single-shot Database Migrations" below. |
|
|
145
|
-
| `OM_DEV_DATABASE_NAME` | unset | Same as passing `--database-name=<value>` to `yarn dev` / `yarn setup`. CLI flag wins. |
|
|
146
|
-
| `OM_DEV_DATABASE_UPDATE_ENV` | unset | Non-interactive answer for the `.env` update prompt (`true`/`false`). Equivalent to `--update-env` / `--no-update-env`. |
|
|
147
|
-
|
|
148
|
-
### Persistent Parallel Local Databases
|
|
149
|
-
|
|
150
|
-
Add `--database-name[=<name>]` to `yarn dev`, `yarn dev:greenfield`, or `yarn setup` to point this app at an isolated PostgreSQL database without manually editing `.env` first. Behavior:
|
|
151
|
-
|
|
152
|
-
- `yarn dev` (no flag) is unchanged — no prompt, no `.env` mutation.
|
|
153
|
-
- `yarn setup --database-name=client_a` rewrites the `DATABASE_URL` database segment in `./.env` after a confirmation prompt (default yes).
|
|
154
|
-
- `yarn dev --database-name` (bare flag) derives the database name from the current directory.
|
|
155
|
-
- `yarn dev --database-name=review_1720 --no-update-env` injects the rewritten URL into the current child process only and leaves `.env` untouched.
|
|
156
|
-
- Non-interactive runs (`CI=true` or piped stdin) default to updating `.env`; pass `--no-update-env` to opt out.
|
|
157
|
-
|
|
158
|
-
The override only changes the database segment of `DATABASE_URL`. Credentials, host, port, query strings (`?schema=…`, `?sslmode=…`), and other env variables are preserved verbatim.
|
|
159
|
-
|
|
160
|
-
## Infrastructure
|
|
161
|
-
|
|
162
|
-
Start required services via Docker Compose:
|
|
163
|
-
```bash
|
|
164
|
-
docker compose up -d
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
Services: PostgreSQL (pgvector), Redis, Meilisearch
|
|
168
|
-
|
|
169
|
-
## Architecture
|
|
170
|
-
|
|
171
|
-
### Open Mercato Framework
|
|
172
|
-
|
|
173
|
-
This is a Next.js 16 application built on the **Open Mercato** modular ERP framework. The framework provides:
|
|
174
|
-
|
|
175
|
-
- **Module system**: Business modules (auth, customers, catalog, sales, etc.) from `@open-mercato/*` packages
|
|
176
|
-
- **Entity system**: MikroORM entities with code generation
|
|
177
|
-
- **DI container**: Awilix-based dependency injection
|
|
178
|
-
- **RBAC**: Role-based access control with feature flags
|
|
179
|
-
|
|
180
|
-
### Key Files
|
|
181
|
-
|
|
182
|
-
- `src/modules.ts` - Declares enabled modules and their sources (`@open-mercato/core`, `@open-mercato/*`, or `@app`)
|
|
183
|
-
- `src/di.ts` - App-level DI overrides (runs after core/module registrations)
|
|
184
|
-
- `src/bootstrap.ts` - Application initialization (imports generated files, registers i18n)
|
|
185
|
-
- `.mercato/generated/` - Auto-generated files from `yarn generate` (do not edit manually)
|
|
186
|
-
|
|
187
|
-
### Module Overrides
|
|
188
|
-
|
|
189
|
-
Use the unified `entry.overrides` field in `src/modules.ts` when this app needs to replace or disable a contract from a package-backed module without forking it. The template ships a non-applied `moduleOverrideExamples` object covering AI, routes, events, workers, widgets, notifications, interceptors, setup, ACL, DI, and encryption. Copy only the specific domains you need into the target module entry's `overrides` field.
|
|
190
|
-
|
|
191
|
-
Rules:
|
|
192
|
-
|
|
193
|
-
- `null` disables a matching contract; an object/function definition replaces it.
|
|
194
|
-
- API route keys are `'METHOD /api/path'`; page route keys are `'/backend/path'` or `'/frontend/path'`.
|
|
195
|
-
- `setup` overrides apply to the module entry carrying them, not to a separate setup id map.
|
|
196
|
-
- The standard `src/bootstrap.ts` already calls `applyModuleOverridesFromEnabledModules(enabledModules)` before registries load.
|
|
197
|
-
|
|
198
|
-
### Routing Structure
|
|
199
|
-
|
|
200
|
-
- `/backend/*` - Admin panel routes (AppShell with sidebar navigation)
|
|
201
|
-
- `/(frontend)/*` - Public-facing routes
|
|
202
|
-
- `/api/*` - API routes with automatic module routing via `findApi()`
|
|
203
|
-
|
|
204
|
-
### Module Development
|
|
205
|
-
|
|
206
|
-
Custom modules go in `src/modules/`. Each module can define:
|
|
207
|
-
- Entities (MikroORM)
|
|
208
|
-
- API routes
|
|
209
|
-
- Backend/frontend pages
|
|
210
|
-
- DI registrations
|
|
211
|
-
- Navigation entries
|
|
212
|
-
|
|
213
|
-
Add new modules to `src/modules.ts` with `from: '@app'`.
|
|
214
|
-
Install official package-backed modules with `yarn mercato module add @open-mercato/<package>`.
|
|
215
|
-
|
|
216
|
-
### Data Entities
|
|
217
|
-
|
|
218
|
-
- Define module entities in `src/modules/<module>/data/entities.ts`.
|
|
219
|
-
- Import entity decorators from `@mikro-orm/decorators/legacy`, not `@mikro-orm/core`.
|
|
220
|
-
- User-editable entities MUST carry an `updated_at` column (onCreate+onUpdate) — it backs OSS **optimistic locking** (default ON). Return `updatedAt` from CRUD list/detail responses, and on edit/delete UI let `CrudForm` auto-derive the version header from `initialValues.updatedAt`, or for custom handlers wrap with `withScopedApiRequestHeaders(buildOptimisticLockHeader(record.updatedAt), …)` + `surfaceRecordConflict(err, t)`. Without it, concurrent edits silently overwrite.
|
|
221
|
-
- Treat `yarn db:generate` as a schema-diff probe. Default to the generated SQL, but if it emits unrelated churn, keep or write only the scoped SQL for the module you are changing and update `src/modules/<module>/migrations/.snapshot-open-mercato.json` in the same change.
|
|
222
|
-
|
|
223
|
-
### API Route Files MUST Export `metadata`
|
|
224
|
-
|
|
225
|
-
Every `src/modules/<module>/api/**/route.ts` file that exports an HTTP handler (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) MUST also export a `metadata` object describing per-method auth requirements. Omitting it triggers the generator warning:
|
|
226
|
-
|
|
227
|
-
```
|
|
228
|
-
[generate] ⚠ Route file exports handlers but no metadata — auth will default to required: <file>
|
|
229
|
-
```
|
|
230
|
-
|
|
231
|
-
…and the generated registry falls back to "authentication required" for every method, which hides misconfigurations rather than surfacing them. Always be explicit.
|
|
232
|
-
|
|
233
|
-
Correct shape — per-method, with `requireAuth` and optional `requireFeatures`:
|
|
234
|
-
|
|
235
|
-
```ts
|
|
236
|
-
// src/modules/<module>/api/<path>/route.ts
|
|
237
|
-
export const metadata = {
|
|
238
|
-
GET: { requireAuth: true, requireFeatures: ['mymodule.view'] },
|
|
239
|
-
POST: { requireAuth: true, requireFeatures: ['mymodule.manage'] },
|
|
240
|
-
}
|
|
241
|
-
|
|
242
|
-
export async function GET(request: Request) { /* ... */ }
|
|
243
|
-
export async function POST(request: Request) { /* ... */ }
|
|
244
|
-
```
|
|
245
|
-
|
|
246
|
-
Public (unauthenticated) endpoints must opt out explicitly:
|
|
247
|
-
|
|
248
|
-
```ts
|
|
249
|
-
export const metadata = {
|
|
250
|
-
GET: { requireAuth: false },
|
|
251
|
-
}
|
|
252
|
-
```
|
|
253
|
-
|
|
254
|
-
Legacy top-level `export const requireAuth` / `export const requireFeatures` exports are NOT recognized by the registry generator — migrate any stragglers to the `metadata` object shape above.
|
|
255
|
-
|
|
256
|
-
### Single-shot Database Migrations
|
|
257
|
-
|
|
258
|
-
`yarn dev` auto-applies pending migrations at startup by default (see `OM_DEV_AUTO_MIGRATE` in the environment variables table). That means once a migration file has been committed to `src/modules/<module>/migrations/` and picked up by the dev server, it has likely already been applied to your local database.
|
|
259
|
-
|
|
260
|
-
Practical consequences:
|
|
261
|
-
|
|
262
|
-
- Prefer writing migration files in **one shot** — generate them with `yarn db:generate`, review, commit, move on.
|
|
263
|
-
- Treat `yarn db:generate` as a schema-diff probe. If it creates migrations for unrelated modules, delete that unrelated output and fix the stale snapshot instead of committing noise.
|
|
264
|
-
- Manual SQL is allowed when it is the only clean way to avoid unrelated churn, but the touched module's `.snapshot-open-mercato.json` MUST be updated to the post-change schema in the same change.
|
|
265
|
-
- For the specific entity change you are making, keep or write only the intended SQL migration and update `src/modules/<module>/migrations/.snapshot-open-mercato.json` to the post-change schema in the same change.
|
|
266
|
-
- Do not run `yarn db:migrate` unless the user explicitly asks you to apply migrations. A code change should carry migration files and snapshots; applying them is local database state.
|
|
267
|
-
- Editing an already-applied migration is risky: the next `yarn dev` / `yarn db:migrate` will skip the file (it is already marked applied), so your edits will not land in the database. If iteration is truly unavoidable:
|
|
268
|
-
1. Set `OM_DEV_AUTO_MIGRATE=0` in `.env.local` to stop auto-apply.
|
|
269
|
-
2. Roll back the migration (`yarn db:migrate --down` or reset the dev DB).
|
|
270
|
-
3. Edit the migration file.
|
|
271
|
-
4. Re-apply (`yarn db:migrate`) and commit.
|
|
272
|
-
- Never hand-edit historical migrations that have shipped; add a **new** migration that performs the correction instead.
|
|
273
|
-
|
|
274
|
-
## Entity Update Safety / Transaction Safety
|
|
275
|
-
|
|
276
|
-
MikroORM v7 can silently drop a pending scalar UPDATE when a query (`em.find`, `em.findOne`, or a sync helper) runs on the same `EntityManager` between the scalar mutation and `em.flush()`. For commands that mutate entities across multiple phases:
|
|
277
|
-
|
|
278
|
-
- Use `withAtomicFlush(em, phases, { transaction: true })` from `@open-mercato/shared/lib/commands/flush` for multi-phase scalar + relation mutations.
|
|
279
|
-
- Never interleave `em.find`/`em.findOne` between a scalar mutation and `em.flush()` without `withAtomicFlush`.
|
|
280
|
-
- Keep `emitCrudSideEffects` and cache invalidation OUTSIDE the `withAtomicFlush` block — they run only AFTER the DB write commits.
|
|
281
|
-
|
|
282
|
-
```ts
|
|
283
|
-
import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
|
|
284
|
-
|
|
285
|
-
await withAtomicFlush(em, [
|
|
286
|
-
() => { record.name = 'New Name'; record.status = 'active' },
|
|
287
|
-
() => syncEntityTags(em, record, tags),
|
|
288
|
-
], { transaction: true })
|
|
289
|
-
|
|
290
|
-
// Cache invalidation + side effects AFTER commit
|
|
291
|
-
await emitCrudSideEffects({ /* ... */ })
|
|
292
|
-
```
|
|
293
|
-
|
|
294
|
-
Cache invalidation running post-commit means reads can briefly observe a query-index convergence window. The opt-in `OM_CACHE_SAFETY_ALWAYS_CONSISTENT` env flag (default OFF, backward compatible) is planned to make the query-index read-projection tail converge synchronously on write, at a write-latency cost — opt-in/forthcoming, not on by default.
|
|
295
|
-
|
|
296
|
-
## AI Assistant — adding agents, tools, UI parts, and overrides
|
|
297
|
-
|
|
298
|
-
Standalone apps consume the AI framework from `@open-mercato/ai-assistant` (in `node_modules/`). The same conventions used in the monorepo apply here:
|
|
299
|
-
|
|
300
|
-
- Add a typed agent for a new module by creating `<module>/ai-agents.ts` + `<module>/ai-tools.ts` at the **module root**. Run `yarn generate` after.
|
|
301
|
-
- Add inline UI widgets (record cards, custom server-emitted parts) per the [UI Parts guide](https://docs.open-mercato.dev/framework/ai-assistant/ui-parts).
|
|
302
|
-
- Replace or disable an agent / tool that another module shipped through three paths: extra `aiAgentOverrides` / `aiToolOverrides` exports on the existing `<module>/ai-agents.ts` / `<module>/ai-tools.ts` (per-module), inline on a `ModuleEntry` in `src/modules.ts` (per-app), or programmatically via `applyAiAgentOverrides({...})` / `applyAiToolOverrides({...})` from `@open-mercato/ai-assistant`. `null` disables; a definition replaces. Resolution order is **programmatic → modules.ts → file-based → base**.
|
|
303
|
-
|
|
304
|
-
Example per-module override (preferred when the override should ship with a module):
|
|
305
|
-
|
|
306
|
-
```ts
|
|
307
|
-
// src/modules/<my_module>/ai-agents.ts
|
|
308
|
-
import type {
|
|
309
|
-
AiAgentDefinition,
|
|
310
|
-
AiAgentOverridesMap,
|
|
311
|
-
} from '@open-mercato/ai-assistant'
|
|
312
|
-
import myAgent from './agents/my-merchandising-agent'
|
|
313
|
-
|
|
314
|
-
export const aiAgents: AiAgentDefinition[] = [/* ...your module's own agents */]
|
|
315
|
-
|
|
316
|
-
export const aiAgentOverrides: AiAgentOverridesMap = {
|
|
317
|
-
'catalog.merchandising_assistant': myAgent, // replace
|
|
318
|
-
'catalog.catalog_assistant': null, // disable
|
|
319
|
-
}
|
|
320
|
-
```
|
|
321
|
-
|
|
322
|
-
Example `modules.ts` inline override (preferred for app-level decisions that do not deserve a fake module). All module contract domains live under the same `entry.overrides` umbrella per the [unified spec](https://github.com/open-mercato/open-mercato/blob/main/.ai/specs/implemented/2026-05-04-modules-ts-unified-overrides.md):
|
|
323
|
-
|
|
324
|
-
```ts
|
|
325
|
-
// src/modules.ts
|
|
326
|
-
{
|
|
327
|
-
id: 'example',
|
|
328
|
-
from: '@app',
|
|
329
|
-
overrides: {
|
|
330
|
-
ai: {
|
|
331
|
-
agents: { 'catalog.catalog_assistant': null },
|
|
332
|
-
tools: { 'inbox_ops_accept_action': null },
|
|
333
|
-
},
|
|
334
|
-
routes: {
|
|
335
|
-
api: {
|
|
336
|
-
'GET /api/example/override-probe': {
|
|
337
|
-
handler: async () => Response.json({ ok: true, source: 'override' }),
|
|
338
|
-
metadata: { requireAuth: false },
|
|
339
|
-
},
|
|
340
|
-
},
|
|
341
|
-
pages: {
|
|
342
|
-
'/backend/example/reports': null,
|
|
343
|
-
},
|
|
344
|
-
},
|
|
345
|
-
},
|
|
346
|
-
},
|
|
347
|
-
```
|
|
348
|
-
|
|
349
|
-
The template's `src/bootstrap.ts` already calls `applyModuleOverridesFromEnabledModules(enabledModules)` from `@open-mercato/shared/modules/overrides` for you. Importing `@open-mercato/ai-assistant` (also in bootstrap) runs the side-effect that registers the AI domain applier with the dispatcher.
|
|
350
|
-
|
|
351
|
-
Example programmatic override at boot (env-driven or test-only):
|
|
352
|
-
|
|
353
|
-
```ts
|
|
354
|
-
// src/bootstrap.ts (extra)
|
|
355
|
-
import {
|
|
356
|
-
applyAiAgentOverrides,
|
|
357
|
-
applyAiToolOverrides,
|
|
358
|
-
} from '@open-mercato/ai-assistant'
|
|
359
|
-
|
|
360
|
-
// Disable an agent provided by the assistant module by default.
|
|
361
|
-
applyAiAgentOverrides({ 'catalog.catalog_assistant': null })
|
|
362
|
-
// Disable a default tool we do not use.
|
|
363
|
-
applyAiToolOverrides({ 'inbox_ops_accept_action': null })
|
|
364
|
-
```
|
|
365
|
-
|
|
366
|
-
After editing any `aiAgentOverrides` / `aiToolOverrides` export:
|
|
367
|
-
|
|
368
|
-
```bash
|
|
369
|
-
yarn generate
|
|
370
|
-
yarn mercato configs cache structural --all-tenants
|
|
371
|
-
```
|
|
372
|
-
|
|
373
|
-
Refer to the `om-create-ai-agent` skill (`.ai/skills/om-create-ai-agent/SKILL.md`) and the public docs at `framework/ai-assistant/overrides` for the full contract, MUST rules, and the resolution order.
|
|
374
|
-
|
|
375
|
-
### Unified module contract overrides
|
|
376
|
-
|
|
377
|
-
The same `entry.overrides` surface that disables/replaces AI agents also wires routes, subscribers, workers, widgets, notifications, interceptors, enrichers, guards, CLI commands, setup hooks, ACL features, DI bindings, and encryption maps. Use it when you want to replace a contract shipped by an upstream module without forking the source.
|
|
378
|
-
|
|
379
|
-
```ts
|
|
380
|
-
// src/modules.ts — representative examples across override phases
|
|
381
|
-
{
|
|
382
|
-
id: 'example',
|
|
383
|
-
from: '@app',
|
|
384
|
-
overrides: {
|
|
385
|
-
routes: {
|
|
386
|
-
api: {
|
|
387
|
-
// disable
|
|
388
|
-
'DELETE /api/example/items': null,
|
|
389
|
-
// replace
|
|
390
|
-
'POST /api/example/items': {
|
|
391
|
-
handler: async (req) => new Response(JSON.stringify({ ok: true }), { status: 200 }),
|
|
392
|
-
metadata: { requireAuth: true, requireFeatures: ['example.manage'] },
|
|
393
|
-
},
|
|
394
|
-
},
|
|
395
|
-
pages: {
|
|
396
|
-
'/backend/example/items': null,
|
|
397
|
-
},
|
|
398
|
-
},
|
|
399
|
-
events: {
|
|
400
|
-
subscribers: {
|
|
401
|
-
'example.todo.created.notify': null,
|
|
402
|
-
},
|
|
403
|
-
},
|
|
404
|
-
workers: {
|
|
405
|
-
'example:sync': null,
|
|
406
|
-
},
|
|
407
|
-
widgets: {
|
|
408
|
-
injection: { 'example.toolbar': null },
|
|
409
|
-
dashboard: { 'example.kpi': null },
|
|
410
|
-
components: {
|
|
411
|
-
'page:/backend/example': {
|
|
412
|
-
target: { componentId: 'page:/backend/example' },
|
|
413
|
-
priority: 10,
|
|
414
|
-
propsTransform: (props) => props,
|
|
415
|
-
},
|
|
416
|
-
},
|
|
417
|
-
},
|
|
418
|
-
notifications: {
|
|
419
|
-
types: { 'example.notice': null },
|
|
420
|
-
handlers: { 'example.notice.toast': null },
|
|
421
|
-
},
|
|
422
|
-
interceptors: { 'example.items.audit': null },
|
|
423
|
-
commandInterceptors: { 'example.command.audit': null },
|
|
424
|
-
enrichers: { 'example.items.enricher': null },
|
|
425
|
-
guards: { 'example.backend.guard': null },
|
|
426
|
-
cli: { 'example seed': null },
|
|
427
|
-
setup: {
|
|
428
|
-
defaultRoleFeatures: { admin: ['example.view'] },
|
|
429
|
-
seedExamples: false,
|
|
430
|
-
},
|
|
431
|
-
acl: {
|
|
432
|
-
features: { 'example.manage': null },
|
|
433
|
-
},
|
|
434
|
-
di: {
|
|
435
|
-
exampleService: {
|
|
436
|
-
register: (container, key) => container.register({ [key]: { mode: 'replacement' } }),
|
|
437
|
-
},
|
|
438
|
-
},
|
|
439
|
-
encryption: {
|
|
440
|
-
maps: { 'example:item': null },
|
|
441
|
-
},
|
|
442
|
-
},
|
|
443
|
-
},
|
|
444
|
-
```
|
|
445
|
-
|
|
446
|
-
Programmatic equivalent (boot-time, env-driven, or test scaffold):
|
|
447
|
-
|
|
448
|
-
```ts
|
|
449
|
-
// src/bootstrap.ts (extra)
|
|
450
|
-
import {
|
|
451
|
-
applyApiRouteOverrides,
|
|
452
|
-
applyPageRouteOverrides,
|
|
453
|
-
applyWorkerOverrides,
|
|
454
|
-
} from '@open-mercato/shared/modules/overrides'
|
|
455
|
-
|
|
456
|
-
applyApiRouteOverrides({
|
|
457
|
-
'GET /api/example/items': null,
|
|
458
|
-
})
|
|
459
|
-
applyPageRouteOverrides({
|
|
460
|
-
'/backend/example/items': null,
|
|
461
|
-
})
|
|
462
|
-
applyWorkerOverrides({
|
|
463
|
-
'example:sync': null,
|
|
464
|
-
})
|
|
465
|
-
```
|
|
466
|
-
|
|
467
|
-
Key rules:
|
|
468
|
-
|
|
469
|
-
- Keys are `'METHOD /api/path'`; method is normalized, path leading slash optional, trailing slashes stripped.
|
|
470
|
-
- Page route keys are `'/backend/path'` or `'/frontend/path'`.
|
|
471
|
-
- `null` disables the matching contract; a definition replaces it.
|
|
472
|
-
- Programmatic > `modules.ts` > file-based where supported > base. The dispatcher MUST run before registries first-load — the template's `bootstrap.ts` already does this.
|
|
473
|
-
- Stale override keys log a warning so operators notice renamed or removed upstream contracts.
|
|
474
|
-
|
|
475
|
-
Full reference: `framework/modules/overrides` and `framework/modules/routes-and-pages`.
|
|
476
|
-
|
|
477
|
-
## Disabling the Dashboards Module: Update /backend
|
|
478
|
-
|
|
479
|
-
The default `/backend` page (`src/app/(backend)/backend/page.tsx`) renders `<DashboardScreen />` from `@open-mercato/ui/backend/dashboard`. That component's data flow depends on the `dashboards` module being enabled — widgets, layouts, and the dashboard API routes all live there.
|
|
480
|
-
|
|
481
|
-
If you or the `om-trim-unused-modules` skill removes `dashboards` from `src/modules.ts`, 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 current user can see — pick from the main sidebar group, fall back to `/backend/profile` when nothing else is enabled. Example:
|
|
482
|
-
|
|
483
|
-
```tsx
|
|
484
|
-
import { getAuthFromCookies } from '@open-mercato/shared/lib/auth/server'
|
|
485
|
-
import { redirect } from 'next/navigation'
|
|
486
|
-
|
|
487
|
-
export default async function BackendIndex() {
|
|
488
|
-
const auth = await getAuthFromCookies()
|
|
489
|
-
if (!auth) redirect('/api/auth/session/refresh?redirect=/backend')
|
|
490
|
-
// dashboards disabled — pick the first enabled backend page the user can reach
|
|
491
|
-
redirect('/backend/customers/people') // replace with your project's landing page
|
|
492
|
-
}
|
|
493
|
-
```
|
|
494
|
-
|
|
495
|
-
Do this in the same change where you disable the module — otherwise `/backend` will crash at request time because `DashboardScreen` will be missing from the bundle (or, worse, will render but fail to load widgets).
|
|
496
|
-
|
|
497
|
-
## Feature Grants: New Features MUST Be Visible Immediately
|
|
498
|
-
|
|
499
|
-
Every time you add a new feature ID (e.g. `my_module.view`, `my_module.manage`) to `src/modules/<module>/acl.ts`, you MUST also:
|
|
500
|
-
|
|
501
|
-
1. **Add it to `defaultRoleFeatures`** in the same module's `setup.ts` so the admin role and any other appropriate default roles receive it on every new tenant setup:
|
|
502
|
-
|
|
503
|
-
```ts
|
|
504
|
-
// src/modules/<module>/setup.ts
|
|
505
|
-
export const setup = {
|
|
506
|
-
defaultRoleFeatures: {
|
|
507
|
-
admin: ['my_module.view', 'my_module.manage'],
|
|
508
|
-
employee: ['my_module.view'],
|
|
509
|
-
},
|
|
510
|
-
// ...
|
|
511
|
-
}
|
|
512
|
-
```
|
|
513
|
-
|
|
514
|
-
2. **Reconcile existing tenants** by running the ACL sync command so existing installs pick up the new feature without a reinstall:
|
|
515
|
-
|
|
516
|
-
```bash
|
|
517
|
-
yarn mercato auth sync-role-acls
|
|
518
|
-
```
|
|
519
|
-
|
|
520
|
-
Do this automatically unless the user has explicitly said otherwise. If the current user has a default role that should access the module, they should see the feature you just built — not stare at a blank admin because their role is missing the grant. Use `--tenant <tenantId>` only when the user asks to target one tenant.
|
|
521
|
-
|
|
522
|
-
Feature IDs are FROZEN once shipped (they are stored in the DB as `role_features.feature_id`). If a rename is required, add the new ID, grant it, and keep the old one alongside as a deprecated alias until downstream data can be migrated.
|
|
523
|
-
|
|
524
|
-
## Mandatory Module Mechanisms (no DIY substitutes)
|
|
525
|
-
|
|
526
|
-
When building a new application or a new module under `src/modules/<id>/`, do not invent custom routing, auth, persistence, forms, or caching. The framework provides one canonical primitive for each concern. If a feature is not on this list, ask before adding it.
|
|
527
|
-
|
|
528
|
-
| Concern | Canonical mechanism | Reference |
|
|
53
|
+
| Route | Match | Context |
|
|
529
54
|
|---|---|---|
|
|
530
|
-
|
|
|
531
|
-
|
|
|
532
|
-
|
|
|
533
|
-
|
|
|
534
|
-
|
|
|
535
|
-
|
|
|
536
|
-
|
|
|
537
|
-
| Authorization (RBAC) | Declare features in `<module>/acl.ts`, grant in `<module>/setup.ts` `defaultRoleFeatures`, gate routes/pages with `requireFeatures` in `metadata`. NEVER use `requireRoles`. Run `yarn mercato auth sync-role-acls` after adding features | <https://docs.open-mercato.dev/framework/rbac/overview> |
|
|
538
|
-
| Multi-tenant scoping (default) | Every tenant-scoped entity MUST include indexed `organization_id` and `tenant_id`; every read/write filters by them. The CRUD factory injects the scope automatically — do not bypass it | <https://docs.open-mercato.dev/architecture/system-overview> |
|
|
539
|
-
| **Encryption maps for sensitive data** | Declare `<module>/encryption.ts` exporting `defaultEncryptionMaps: ModuleEncryptionMap[]`; read via `findWithDecryption` / `findOneWithDecryption`. NEVER hand-roll AES/KMS — see the next section | <https://docs.open-mercato.dev/user-guide/encryption> |
|
|
540
|
-
| Cache | Resolve from DI (`container.resolve('cache')`); never `new Redis(...)` or raw SQLite. Tag with `tenant:<id>` / `org:<id>` for tenant-scoped invalidation | <https://docs.open-mercato.dev/user-guide/cache-management> |
|
|
541
|
-
| Background workers | `src/modules/<id>/workers/*.ts` exporting `metadata: { queue, id?, concurrency? }` + default handler. Never spin up custom queues | <https://docs.open-mercato.dev/framework/events/queue-workers> |
|
|
542
|
-
| Events between modules | `<module>/events.ts` with `createModuleEvents({ moduleId, events } as const)`; subscribers in `subscribers/*.ts` | <https://docs.open-mercato.dev/framework/events/overview> |
|
|
543
|
-
| i18n (every user-facing string) | `useT()` client-side from `@open-mercato/shared/lib/i18n/context`, `resolveTranslations()` server-side from `@open-mercato/shared/lib/i18n/server`; keys in `src/i18n/<locale>.json` | The `@open-mercato/shared` package (`node_modules/@open-mercato/shared/lib/i18n/`) |
|
|
544
|
-
|
|
545
|
-
> Rule of thumb: if you reach for raw `fetch`, raw `<form>`, ad-hoc `crypto`, ad-hoc `Redis`, or a manual cross-module ORM join, stop and check the row above first.
|
|
546
|
-
|
|
547
|
-
## Data Encryption (sensitive / GDPR-relevant fields)
|
|
548
|
-
|
|
549
|
-
The framework ships a tenant-data-encryption mechanism with per-tenant DEKs, KMS-backed key resolution (Vault by default), declarative field-level maps per module, and deterministic-hash sibling columns for equality lookups. **Use it. Never hand-roll AES, `crypto.subtle`, or custom KMS calls. Never store sensitive columns as plaintext "for now".**
|
|
550
|
-
|
|
551
|
-
When the user asks for "we need this column encrypted", "store this securely", "this is PII", "GDPR", or "encryption at rest" — and whenever you are designing a column that holds names, addresses, contact info, free-text notes about people, integration credentials, secrets, or anything subject to a data-processing agreement — declare an `encryption.ts` at the module root.
|
|
552
|
-
|
|
553
|
-
```ts
|
|
554
|
-
// src/modules/<module>/encryption.ts
|
|
555
|
-
import type { ModuleEncryptionMap } from '@open-mercato/shared/modules/encryption'
|
|
556
|
-
|
|
557
|
-
export const defaultEncryptionMaps: ModuleEncryptionMap[] = [
|
|
558
|
-
{
|
|
559
|
-
entityId: '<module>:<entity>',
|
|
560
|
-
fields: [
|
|
561
|
-
{ field: 'first_name' },
|
|
562
|
-
{ field: 'last_name' },
|
|
563
|
-
{ field: 'phone' },
|
|
564
|
-
// For deterministic equality lookups (e.g. login by email), add a sibling hash column.
|
|
565
|
-
{ field: 'email', hashField: 'email_hash' },
|
|
566
|
-
],
|
|
567
|
-
},
|
|
568
|
-
]
|
|
569
|
-
|
|
570
|
-
export default defaultEncryptionMaps
|
|
571
|
-
```
|
|
572
|
-
|
|
573
|
-
Read with decryption — never raw `em.find` / `em.findOne` on encrypted columns:
|
|
574
|
-
|
|
575
|
-
```ts
|
|
576
|
-
import { findWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
|
|
577
|
-
|
|
578
|
-
// Signature: (em, entityName, where, options?, scope?). Pass MikroORM FindOptions in slot 4
|
|
579
|
-
// (or `undefined`), and the decryption scope in slot 5.
|
|
580
|
-
const records = await findWithDecryption(em, '<Entity>', filter, undefined, { tenantId, organizationId })
|
|
581
|
-
const single = await findOneWithDecryption(em, '<Entity>', { id }, undefined, { tenantId, organizationId })
|
|
582
|
-
```
|
|
583
|
-
|
|
584
|
-
Apply maps to existing tenants after declaring them (new tenants pick them up automatically during `auth:setup`):
|
|
585
|
-
|
|
586
|
-
```bash
|
|
587
|
-
yarn mercato entities seed-encryption --tenant <tenantId> [--organization <orgId>]
|
|
588
|
-
```
|
|
589
|
-
|
|
590
|
-
Notes:
|
|
591
|
-
|
|
592
|
-
- Toggling the **Encrypted** flag on a custom field via the admin UI only applies to data written *after* the change. Backfill historical plaintext rows with `yarn mercato entities rotate-encryption-key --tenant <tenantId> --org <organizationId>` (without `--old-key` it only encrypts plaintext and skips already-encrypted fields). Use `yarn mercato entities decrypt-database` to roll back.
|
|
593
|
-
- The `vector` module stores raw embeddings unencrypted in the vector store — treat embeddings as sensitive even when the source text is encrypted.
|
|
594
|
-
- Env switches: `TENANT_DATA_ENCRYPTION` (default `yes`), `TENANT_DATA_ENCRYPTION_DEBUG`, Vault (`VAULT_ADDR` / `VAULT_TOKEN` / `VAULT_KV_PATH`), and dev fallback (`TENANT_DATA_ENCRYPTION_FALLBACK_KEY`).
|
|
595
|
-
|
|
596
|
-
Full guide: <https://docs.open-mercato.dev/user-guide/encryption>.
|
|
597
|
-
|
|
598
|
-
## Design System (Strict — applies to every UI change)
|
|
599
|
-
|
|
600
|
-
All UI added or edited in `src/modules/<module>/backend/**` or `src/modules/<module>/frontend/**` MUST follow the Open Mercato design system. Non-compliant code will be blocked in `om-auto-review-pr`.
|
|
601
|
-
|
|
602
|
-
**Colors.** NEVER hardcode Tailwind status colors (`text-red-500`, `bg-green-100`, `text-amber-*`, `text-emerald-*`, `bg-blue-*`). Use semantic tokens: `text-status-error-text`, `bg-status-success-bg`, `border-status-warning-border`, `text-status-info-icon`. For destructive actions (buttons) use the `destructive` token (`text-destructive`, `bg-destructive`). All status tokens have dedicated dark-mode values — no `dark:` overrides needed.
|
|
603
|
-
|
|
604
|
-
**Typography.** NEVER use arbitrary text sizes (`text-[11px]`, `text-[13px]`, `text-[15px]`). Use the Tailwind scale: `text-xs` (12), `text-sm` (14), `text-base` (16), `text-lg` (18), `text-xl` (20), `text-2xl` (24). For 11px uppercase labels use the `text-overline` token.
|
|
605
|
-
|
|
606
|
-
**Components to use instead of raw HTML.**
|
|
607
|
-
|
|
608
|
-
| I need to… | Use |
|
|
609
|
-
|---|---|
|
|
610
|
-
| Show inline error / success / warning / info | `<Alert variant="destructive\|success\|warning\|info">` |
|
|
611
|
-
| Show a toast | `flash('message', 'success\|error\|warning\|info')` |
|
|
612
|
-
| Confirm a destructive action | `useConfirmDialog()` |
|
|
613
|
-
| Display entity status (active / draft / archived) | `<StatusBadge variant={statusMap[status]} dot>` |
|
|
614
|
-
| Wrap a form input with label + error | `<FormField label="…" error={…}>` |
|
|
615
|
-
| Section header with count + action | `<SectionHeader title="…" count={n} action={…}>` |
|
|
616
|
-
| Collapsible section | `<CollapsibleSection title="…">…</CollapsibleSection>` |
|
|
617
|
-
| Loading state | `<LoadingMessage />`, `<Spinner />`, or `<DataLoader />` |
|
|
618
|
-
| Empty state | `<EmptyState>` (or `emptyState` prop on `DataTable`) |
|
|
619
|
-
|
|
620
|
-
**Icons (page body).** Use `lucide-react` for every icon inside page body UI (`Page`, `DataTable`, `CrudForm`, cards, buttons, etc.) — never inline `<svg>`. Sizes: `size-3`, `size-4` (default), `size-5`, `size-6`. Do not override `strokeWidth` per-instance. Icon-only buttons MUST have `aria-label`.
|
|
55
|
+
| `architecture` | Capability/ownership/field-vs-history choice, boundary, upgrade, override, or registry failure; routine discovery stays in its area | `.ai/guides/architecture.md` + named facts |
|
|
56
|
+
| `module-data` | App-owned domain/data/API | `src/modules/<id>/` + `.ai/guides/contracts.md`; add architecture only when ownership is unresolved |
|
|
57
|
+
| `umes` | Extend/replace installed behavior | `.ai/guides/extensions.md` + named facts |
|
|
58
|
+
| `backend-ui` | Authored/restyled rendered surface or browser UI state/session bootstrap | `.ai/guides/backend-ui.md` + host facts; host-provided integration credentials/health UI alone does not match |
|
|
59
|
+
| `integration` | Provider, spreadsheet/CSV/file I/O, sync/webhook/storage | `.ai/guides/integrations.md`; imports = `integration`; AI consuming files = `ai-workflow`, NEVER `integration` unless transport/storage changes |
|
|
60
|
+
| `ai-workflow` | Agent/tool/MCP/orchestrator/durable workflow | `.ai/guides/ai-workflows.md` + facts; schedules/queues/workers/retries/progress alone are `module-data` |
|
|
61
|
+
| `debugging` | Bug/security/drift/runtime inconsistency | `.ai/guides/testing-debugging.md` + affected areas |
|
|
621
62
|
|
|
622
|
-
|
|
63
|
+
API/command/record/status/event/UI changes/guards = `umes`; app persistence = `module-data`; installed guard without app persistence = `umes` only, so do not load contracts; read-only behavior/auth/dependents/customization = `framework-context` (alone: no extensions guide; report `installed-version`). Facts do not. Providers are published, never `packages/*`.
|
|
623
64
|
|
|
624
|
-
|
|
625
|
-
import React from 'react'
|
|
65
|
+
### Axis 2 — Work Units
|
|
626
66
|
|
|
627
|
-
|
|
628
|
-
'svg',
|
|
629
|
-
{
|
|
630
|
-
width: 16,
|
|
631
|
-
height: 16,
|
|
632
|
-
viewBox: '0 0 24 24',
|
|
633
|
-
fill: 'none',
|
|
634
|
-
stroke: 'currentColor',
|
|
635
|
-
strokeWidth: 2,
|
|
636
|
-
strokeLinecap: 'round',
|
|
637
|
-
strokeLinejoin: 'round',
|
|
638
|
-
},
|
|
639
|
-
React.createElement('path', { d: 'M17 21v-2a4 4 0 0 0-4-4H7a4 4 0 0 0-4 4v2' }),
|
|
640
|
-
React.createElement('circle', { cx: 9, cy: 7, r: 4 }),
|
|
641
|
-
)
|
|
67
|
+
Match every work-unit row; OPEN its skill before selection.
|
|
642
68
|
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
|
670
|
-
|
|
671
|
-
| `
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
- The skills probe `gh repo view --json defaultBranchRef` for your repo's default branch; no assumption that it's `main` or `develop`.
|
|
677
|
-
- Pipeline labels (`review`, `qa`, `merge-queue`, etc.) are opt-in — the skills detect which labels exist in your repo via `gh label list` and skip gracefully when they're missing. If you want the full workflow, the skill README in each skill folder has a `gh label create` snippet you can paste in once.
|
|
678
|
-
- The validation gate runs `yarn typecheck`, `yarn test`, `yarn generate`, and `yarn build` only when the corresponding `package.json` script exists.
|
|
69
|
+
| Route | Work unit | Skill/context |
|
|
70
|
+
|---|---|---|
|
|
71
|
+
| `architecture` | Explain/choose module, UMES, package, eject | architecture; `om-help` for an unresolved or comparative choice across these mechanisms |
|
|
72
|
+
| `module-data` | Business slice or multi-seam domain/API/command fix | MUST load `om-module-scaffold` + its exact `.ai/skills/om-module-scaffold/references/business-one-shot-blueprints.md` key, which resolves units inside the slice, not ownership — an ownership/capability outline adds `architecture` |
|
|
73
|
+
| `spec-pr` | Spec/plan | Axis 3; phases+integration coverage (`integration-coverage`); no domain routes |
|
|
74
|
+
| `architecture` | Upgrade audit or disable built-in | troubleshooter + framework context, or trim skill + exact `src/modules.ts`/`package.json` |
|
|
75
|
+
| `architecture` + `integration` + `framework-context` | Provider superseded by installed capability | integration builder + exact framework context |
|
|
76
|
+
| `module-data` | Entity/link/validator/migration/encryption/lock/transaction | `om-data-model-design` + contracts |
|
|
77
|
+
| `module-data` | CRUD/API/command/OpenAPI/ACL/setup/mutation | `om-module-scaffold` + contracts |
|
|
78
|
+
| `backend-ui` | Form/table/page/renderer/middleware/nav/i18n/UI states | `om-backend-ui-design` + backend UI |
|
|
79
|
+
| `module-data` | Search/analytics/event/notification/message/worker/progress/cache/CLI | scaffold + contracts |
|
|
80
|
+
| `umes` | Fields/extension entities/links/enrichers/injection/interceptors/guards/subscribers/DOM/widgets/toggles/overrides | `om-system-extension` + extensions; choices load `mechanism-selector` + `extension-branches` |
|
|
81
|
+
| `integration` | Provider/credentials/health/webhook/files/client/reconciliation/package | `om-integration-builder` + integrations |
|
|
82
|
+
| `ai-workflow` | Agent/tool/MCP/OpenCode/Code Mode/orchestrator/AI file or content drafting/attachment/override | `om-create-ai-agent` + AI/workflows; MCP/OpenCode loads `surface-selector` + `ai_assistant` facts |
|
|
83
|
+
| `ai-workflow` | Workflow/activity/user task/idempotency/output/progress | `om-build-workflow` + AI/workflows |
|
|
84
|
+
| `testing` | REQUEST says test/coverage/prove, or verify by exercising API/browser/screen sizes/keyboard/screen-reader—not a fix's implicit regression duty or review/audit/config check | MUST read `.ai/guides/testing-debugging.md` + external `om-integration-tests` for integration/E2E/app tests |
|
|
85
|
+
| `debugging` | Reproduce/root-cause/minimal fix/regression oracle | `om-troubleshooter` + testing/debugging |
|
|
86
|
+
| `framework-context` | Exact installed contract still unknown | bounded `om-framework-context`, last |
|
|
87
|
+
| `debugging` + `testing` | Add/fix recurring harness case/test | `om-evolve-harness` |
|
|
88
|
+
|
|
89
|
+
`framework-context`: resolve one named module/framework fact first. Use bounded source only for an unresolved exact contract, current behavior, authorization, dependents, or safest customization seam; never for “installed contracts” alone.
|
|
90
|
+
|
|
91
|
+
### Axis 3 — SDLC and Delivery
|
|
92
|
+
|
|
93
|
+
Pinned delivery skills: `yarn install-skills` (refresh: `--update`). Read BOTH `.agents/skills/<id>/SKILL.md` and a matching `.ai/skills/<id>/SKILL.md` override. Commit+ready PR MUST add `spec-pr`, read `.ai/skills/om-auto-create-pr/SKILL.md`, and keep task routes (`delivery-route-preserves-task-routes`).
|
|
94
|
+
|
|
95
|
+
| Route ID | Delivery need | Skill |
|
|
96
|
+
|---|---|---|
|
|
97
|
+
| `spec-pr` | Write/revise spec | MUST invoke `om-spec-writing` (OMH-005) + `.ai/guides/spec-delivery.md` + config specs path |
|
|
98
|
+
| `spec-pr` | Implement approved phases locally | `om-implement-spec` (OMH-006) |
|
|
99
|
+
| `spec-pr` | Whole-spec / commit+ready PR / issue / review | `om-auto-implement-spec` / `om-auto-create-pr` / `om-auto-fix-issue` / `om-auto-review-pr` |
|
|
100
|
+
| `testing` | Integration/E2E/UI QA | `om-integration-tests` / `om-auto-qa-pr` |
|
|
101
|
+
| — | No PR/spec workflow requested | Do not load delivery skills |
|
|
679
102
|
|
|
680
|
-
|
|
103
|
+
Absent skill: run `yarn install-skills` once; never substitute.
|
|
681
104
|
|
|
682
|
-
|
|
105
|
+
### Token-Efficient Assembly Policy
|
|
683
106
|
|
|
684
|
-
|
|
107
|
+
- Load matched guides once, then only needed references/facts.
|
|
108
|
+
- Hard budgets: guide > skill > references; open a reference only for its named subject.
|
|
109
|
+
- Specs: open one match; `spec-pr` reads template via spec-delivery.
|
|
110
|
+
- Inspect app call sites before bounded `framework-context`.
|
|
111
|
+
- Additive page/form/table/conflict UI skips it.
|
|
112
|
+
- Never bulk-read guide, skill, fact, or source trees.
|
|
685
113
|
|
|
686
|
-
|
|
114
|
+
## Module-Specific Facts
|
|
687
115
|
|
|
688
|
-
|
|
689
|
-
- `@/.mercato/*` → `./.mercato/*`
|
|
116
|
+
Load facts for every named/targeted module, not incidental use. Mechanisms: events/subscribers→events; long operation/progress→progress; provider settings/health/OAuth→integrations; sync/import→data_sync. Hosts: session/auth→auth; customer/contact/deal/pipeline→customers; product/price/stock/inventory→catalog; currency/money→currencies; cart/checkout/shopper→checkout; portal→portal + customer_accounts; quote/order/invoice/sales assistant→sales; notification→notifications; webhook/callback→webhooks; schedule/reminder→scheduler; workflow/activity/user task→workflows; assistant→ai_assistant; maintained query index/reindex→query_index; search convergence→search. staff/employee≠optional staff; audit/record-who≠audit_logs unless extended. App primitives skip api_docs/search/query_index unless changed.
|
|
690
117
|
|
|
691
|
-
|
|
118
|
+
<!-- om:module-guides:start -->
|
|
119
|
+
<!-- om:module-guides:end -->
|
|
692
120
|
|
|
693
|
-
|
|
121
|
+
## Working Sequence
|
|
694
122
|
|
|
695
|
-
|
|
123
|
+
1. `spec-pr`: list `.ai/specs` once; open one match; plan-only skips specs.
|
|
124
|
+
2. Route; load only matched guides/skills/facts.
|
|
125
|
+
3. Implement the smallest complete slice through real call sites.
|
|
126
|
+
4. Discovery change: run `yarn generate`; then the smallest gate/integration paths.
|
|
696
127
|
|
|
697
|
-
|
|
698
|
-
- Yarn (via corepack)
|
|
128
|
+
Precedence: root → BC → installed `AGENTS.md` → facts; stop on skew/conflict; never guess.
|