create-mercato-app 0.10.1-develop.8072.1.592356afda → 0.10.1-develop.8098.1.f4decc8a57
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/agentic/shared/ai/skills/om-data-model-design/references/integrity-and-concurrency.md +1 -1
- package/agentic/shared/ai/skills/om-implement-spec/SKILL.md +1 -0
- package/agentic/shared/ai/skills/om-module-scaffold/references/api-and-domain.md +4 -3
- package/dist/agentic/guides/module-facts.json +300 -281
- package/dist/agentic/guides/module-facts.v2.json +300 -281
- package/dist/agentic/guides/modules/agent_orchestrator/index.md +1 -1
- package/dist/agentic/guides/modules/ai_assistant/index.md +1 -1
- package/dist/agentic/guides/modules/api_docs/index.md +1 -1
- package/dist/agentic/guides/modules/api_keys/index.md +1 -1
- package/dist/agentic/guides/modules/attachments/index.md +1 -1
- package/dist/agentic/guides/modules/audit_logs/index.md +1 -1
- package/dist/agentic/guides/modules/auth/index.md +1 -1
- package/dist/agentic/guides/modules/availability/index.md +1 -1
- package/dist/agentic/guides/modules/business_rules/index.md +1 -1
- package/dist/agentic/guides/modules/carrier_inpost/index.md +1 -1
- package/dist/agentic/guides/modules/cart/index.md +1 -1
- package/dist/agentic/guides/modules/catalog/index.md +1 -1
- package/dist/agentic/guides/modules/channel_apns/index.md +1 -1
- package/dist/agentic/guides/modules/channel_discord/index.md +1 -1
- package/dist/agentic/guides/modules/channel_expo/index.md +1 -1
- package/dist/agentic/guides/modules/channel_fcm/index.md +1 -1
- package/dist/agentic/guides/modules/channel_gmail/index.md +1 -1
- package/dist/agentic/guides/modules/channel_imap/index.md +1 -1
- package/dist/agentic/guides/modules/channel_resend/index.md +1 -1
- package/dist/agentic/guides/modules/channel_ses/index.md +1 -1
- package/dist/agentic/guides/modules/channel_smtp/index.md +1 -1
- package/dist/agentic/guides/modules/checkout/index.md +1 -1
- package/dist/agentic/guides/modules/communication_channels/exact-override-targets.md +2 -2
- package/dist/agentic/guides/modules/communication_channels/index.md +1 -1
- package/dist/agentic/guides/modules/communication_channels/workers.md +2 -2
- package/dist/agentic/guides/modules/configs/index.md +1 -1
- package/dist/agentic/guides/modules/content/index.md +1 -1
- package/dist/agentic/guides/modules/currencies/index.md +1 -1
- package/dist/agentic/guides/modules/customer_accounts/index.md +1 -1
- package/dist/agentic/guides/modules/customer_groups/index.md +1 -1
- package/dist/agentic/guides/modules/customers/active-extension-bindings.md +1 -2
- package/dist/agentic/guides/modules/customers/incoming-installed-contributions.md +6 -6
- package/dist/agentic/guides/modules/customers/index.md +1 -1
- package/dist/agentic/guides/modules/dashboards/index.md +1 -1
- package/dist/agentic/guides/modules/data_sync/index.md +1 -1
- package/dist/agentic/guides/modules/design_system/index.md +1 -1
- package/dist/agentic/guides/modules/devices/index.md +1 -1
- package/dist/agentic/guides/modules/dictionaries/index.md +1 -1
- package/dist/agentic/guides/modules/directory/index.md +1 -1
- package/dist/agentic/guides/modules/documents/contribution-resolutions.md +3 -3
- package/dist/agentic/guides/modules/documents/index.md +1 -1
- package/dist/agentic/guides/modules/documents/umes-contributions.md +3 -3
- package/dist/agentic/guides/modules/ecommerce/index.md +1 -1
- package/dist/agentic/guides/modules/entities/index.md +1 -1
- package/dist/agentic/guides/modules/eudr/index.md +1 -1
- package/dist/agentic/guides/modules/events/index.md +1 -1
- package/dist/agentic/guides/modules/feature_toggles/index.md +1 -1
- package/dist/agentic/guides/modules/forms/index.md +1 -1
- package/dist/agentic/guides/modules/gateway_autopay/index.md +1 -1
- package/dist/agentic/guides/modules/gateway_stripe/index.md +1 -1
- package/dist/agentic/guides/modules/gateway_tpay/index.md +1 -1
- package/dist/agentic/guides/modules/generators/index.md +1 -1
- package/dist/agentic/guides/modules/inbox_ops/index.md +1 -1
- package/dist/agentic/guides/modules/integrations/index.md +1 -1
- package/dist/agentic/guides/modules/messages/index.md +1 -1
- package/dist/agentic/guides/modules/notifications/index.md +1 -1
- package/dist/agentic/guides/modules/onboarding/index.md +1 -1
- package/dist/agentic/guides/modules/payment_gateways/index.md +1 -1
- package/dist/agentic/guides/modules/perspectives/index.md +1 -1
- package/dist/agentic/guides/modules/phone_calls/index.md +1 -1
- package/dist/agentic/guides/modules/planner/index.md +1 -1
- package/dist/agentic/guides/modules/portal/index.md +1 -1
- package/dist/agentic/guides/modules/progress/index.md +1 -1
- package/dist/agentic/guides/modules/promotions/exact-override-targets.md +1 -1
- package/dist/agentic/guides/modules/promotions/index.md +1 -1
- package/dist/agentic/guides/modules/promotions/workers.md +1 -1
- package/dist/agentic/guides/modules/push_notifications/index.md +1 -1
- package/dist/agentic/guides/modules/query_index/index.md +1 -1
- package/dist/agentic/guides/modules/record_locks/index.md +1 -1
- package/dist/agentic/guides/modules/resources/index.md +1 -1
- package/dist/agentic/guides/modules/sales/index.md +1 -1
- package/dist/agentic/guides/modules/scheduler/index.md +1 -1
- package/dist/agentic/guides/modules/search/index.md +1 -1
- package/dist/agentic/guides/modules/security/index.md +1 -1
- package/dist/agentic/guides/modules/seeds/index.md +1 -1
- package/dist/agentic/guides/modules/shipping_carriers/index.md +1 -1
- package/dist/agentic/guides/modules/sso/index.md +1 -1
- package/dist/agentic/guides/modules/staff/domain-commands.md +2 -0
- package/dist/agentic/guides/modules/staff/entities.md +1 -0
- package/dist/agentic/guides/modules/staff/index.md +7 -7
- package/dist/agentic/guides/modules/staff/umes-hosts.md +1 -0
- package/dist/agentic/guides/modules/storage_s3/index.md +1 -1
- package/dist/agentic/guides/modules/sync_akeneo/index.md +1 -1
- package/dist/agentic/guides/modules/sync_excel/index.md +1 -1
- package/dist/agentic/guides/modules/system_status_overlays/index.md +1 -1
- package/dist/agentic/guides/modules/telemetry/index.md +1 -1
- package/dist/agentic/guides/modules/tillio/index.md +1 -1
- package/dist/agentic/guides/modules/translations/index.md +1 -1
- package/dist/agentic/guides/modules/warranty_claims/index.md +1 -1
- package/dist/agentic/guides/modules/webhooks/index.md +1 -1
- package/dist/agentic/guides/modules/wms/index.md +1 -1
- package/dist/agentic/guides/modules/workflows/contribution-resolutions.md +3 -3
- package/dist/agentic/guides/modules/workflows/exact-override-targets.md +1 -1
- package/dist/agentic/guides/modules/workflows/index.md +1 -1
- package/dist/agentic/guides/modules/workflows/umes-contributions.md +3 -3
- package/dist/agentic/guides/reference-module-facts.json +2 -2
- package/dist/agentic/guides/reference-modules/example/index.md +1 -1
- package/dist/agentic/guides/upstream/manifest.json +1 -1
- package/dist/agentic/shared/ai/skills/om-data-model-design/references/integrity-and-concurrency.md +1 -1
- package/dist/agentic/shared/ai/skills/om-implement-spec/SKILL.md +1 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/api-and-domain.md +4 -3
- package/package.json +3 -3
- package/template/.env.example +6 -4
- package/template/scripts/dev-runtime-log-policy.mjs +24 -0
- package/template/scripts/dev-runtime.mjs +2 -1
- package/template/src/modules/example/api/organizations/route.ts +5 -3
package/agentic/shared/ai/skills/om-data-model-design/references/integrity-and-concurrency.md
CHANGED
|
@@ -6,7 +6,7 @@ Load this reference for writes, locking, retries, and relation synchronization.
|
|
|
6
6
|
- Capture custom fields with `loadCustomFieldSnapshot(em, { entityId, recordId, tenantId, organizationId })` from that same `commands/customFieldSnapshots` module. `DataEngine` has no `getCustomFields`; write them only with the single object argument `dataEngine.setCustomFields({ entityId, recordId, tenantId, organizationId, values, notify })`, never positional arguments.
|
|
7
7
|
- Type each object as `CommandHandler<Input, Result>`, implement `undo: async ({ logEntry, ctx }) => { ... }`, then call `registerCommand(command)` separately; `registerCommand` returns no command object. Call `extractUndoPayload<UndoPayload>(logEntry)`. Enforce a lock with the single options object `enforceCommandOptimisticLock({ resourceKind, resourceId, current, expected, request: ctx.request })`, not positional timestamps.
|
|
8
8
|
- `execute` returns `Result` directly, never `{ result, undo }`. `prepare` returns exactly `{ before: snapshot }`; `captureAfter` returns the after-snapshot value directly; `buildLog({ result, snapshots, ctx })` reads `snapshots.before`/`snapshots.after` and returns `{ resourceId: result.id, payload: { undo: ... } }`. Never invent `snapshots.snapshot` or nest payload under `{ metadata: { payload } }`, and never cast or mutate `ctx` to shuttle command-local undo state. The command bus supplies that log to `undo`. Guard a nullable `extractUndoPayload` result before reading it. `logEntry.resourceId` is nullable, so store the stable record ID in the undo payload and validate/use that required string (or explicitly guard `resourceId`) before a scoped finder call.
|
|
9
|
-
- Resolve infrastructure with types: `const em = ctx.container.resolve<EntityManager>('em').fork()` and `const dataEngine = ctx.container.resolve<DataEngine>('dataEngine')`, importing `CommandRuntimeContext`, `EntityManager` from `@mikro-orm/postgresql`, and `DataEngine` from `@open-mercato/shared/lib/data/engine`. Type command helpers as `(ctx: CommandRuntimeContext)`; do not cast `ctx` or `ctx.container` to `any` and then apply generic type arguments. Trusted scope is `ctx.auth?.tenantId` plus the concrete string `ctx.selectedOrganizationId ?? ctx.organizationScope?.selectedId`; `ctx.organizationScope` is an object, never an organization ID. `ctx.auth.organizationId`, `ctx.em`, and `ctx.dataEngine` are not command runtime fields.
|
|
9
|
+
- Resolve infrastructure with types: `const em = ctx.container.resolve<EntityManager>('em').fork()` once per command, passed to every helper the command calls (never fork again inside helpers or per item), and `const dataEngine = ctx.container.resolve<DataEngine>('dataEngine')`, importing `CommandRuntimeContext`, `EntityManager` from `@mikro-orm/postgresql`, and `DataEngine` from `@open-mercato/shared/lib/data/engine`. Type command helpers as `(ctx: CommandRuntimeContext)`; do not cast `ctx` or `ctx.container` to `any` and then apply generic type arguments. Trusted scope is `ctx.auth?.tenantId` plus the concrete string `ctx.selectedOrganizationId ?? ctx.organizationScope?.selectedId`; `ctx.organizationScope` is an object, never an organization ID. `ctx.auth.organizationId`, `ctx.em`, and `ctx.dataEngine` are not command runtime fields.
|
|
10
10
|
- Import `withAtomicFlush` from `@open-mercato/shared/lib/commands/flush` and call `withAtomicFlush(em, [() => { em.persist(record) }, async () => { await syncRelations() }], { transaction: true })`: the second argument is an array of zero-argument phases that close over the same `EntityManager`, not one callback receiving an `em`. A phase callback must return `void`/`Promise<void>`; use a block such as `() => { em.persist(record) }`, never the expression `() => em.persist(record)` that returns the manager. Keep notifications, queues, external calls, cache invalidation, and indexing after commit, with durable compensation/recovery when those side effects can fail. Import `emitCrudSideEffects`/`emitCrudUndoSideEffects` from `@open-mercato/shared/lib/commands/helpers` and pass their documented options object (`dataEngine`, action, entity, scoped identifiers, events/indexer), not a runtime context plus invented effects descriptor.
|
|
11
11
|
- MikroORM `em.create(Entity, data)` must receive all required typed fields even when entity property initializers exist: supply `created_at` and `updated_at` on create (or the entity's camel-case equivalents). Delete undo must capture a concrete full snapshot and rebuild every required field explicitly; do not pass `Partial<Entity>` to `em.create`.
|
|
12
12
|
- CRUD effects use past-tense `action: 'created' | 'updated' | 'deleted'` and `identifiers: { id, tenantId, organizationId }`. Define mutable typed values (`const events: CrudEventsConfig = ...`, `const indexer: CrudIndexerConfig = ...`) as `{ module, entity, persistent?, buildPayload? }` and `{ entityType, cacheAliases? }`; do not use `as const` for mutable `cacheAliases`, or put `eventId`/loose scope fields in an effect call.
|
|
@@ -38,6 +38,7 @@ Leave the app working after every phase and keep implementation traceable to the
|
|
|
38
38
|
- Only one dependency-ordered phase may be `in_progress`. A phase remains open when it has stubs, failing validation, missing integration evidence, or unmet acceptance IDs, regardless of how many files were generated.
|
|
39
39
|
- Parallel agents may own independent slices inside the active phase only. Every brief names its owned files, routed guides/skills, closest installed reference, canonical primitives, acceptance IDs, and validation oracle.
|
|
40
40
|
- Backend UI must use the platform page shell, `DataTable`/`CrudForm` where their contracts apply, shared API helpers, exported controls, and semantic tokens. Raw tables/forms/fetch, copied component families, arbitrary values, hard-coded palette/status colors, and light-only styling require an approved spec exception.
|
|
41
|
+
- Request paths stay cheap: handlers use the dispatcher's `ctx.auth`, create the request container at most once and pass it down, reuse the request `em` (fork only with a stated reason), batch related reads instead of querying per item, and never call `*Sync` crypto or filesystem APIs. Report the statement count of each new list, detail or write route.
|
|
41
42
|
- Each completed implementation phase must leave a working app (`working-phases`) and report its smallest focused validation gate (`smallest-validation`); `integration-coverage` belongs to writing the spec, not implementing already approved phases.
|
|
42
43
|
- Preserve compatibility and standalone writable boundaries; never patch installed/generated files.
|
|
43
44
|
- Regression tests must fail before their fix and use self-contained fixtures.
|
|
@@ -13,8 +13,9 @@ for the QueryEngine `$ilike` versus raw ORM token-lookup distinction and its pop
|
|
|
13
13
|
|
|
14
14
|
There is no `@open-mercato/shared/lib/http/types`. A hand-written route handler takes the
|
|
15
15
|
platform `Request` (`export async function GET(request: Request)`) and returns a platform
|
|
16
|
-
`Response
|
|
17
|
-
`(request: Request, ctx: { params?: { id?: string } })`.
|
|
16
|
+
`Response`. The dispatcher passes a second argument with the route params and the auth it has
|
|
17
|
+
already verified, `(request: Request, ctx: { params?: { id?: string }; auth?: AuthContext | null })`.
|
|
18
|
+
Use `ctx.auth` instead of resolving auth again, and create the request container once per handler.
|
|
18
19
|
|
|
19
20
|
1. Implement create/update/delete as command objects with stable IDs and call `registerCommand` from `@open-mercato/shared/lib/commands` for each object. A route action naming a command ID does not register it. Include audit/undo/event/cache/index side effects.
|
|
20
21
|
2. Create `src/modules/<moduleId>/api/<resource>/route.ts`; generated discovery mounts it at `/api/<moduleId>/<resource>`. Import `makeCrudRoute` from `@open-mercato/shared/lib/crud/factory`, then export per-method `metadata`, the selected factory handlers, and matching `openApi`. Smoke-test the generated URL rather than assuming a hyphenated or module-less path.
|
|
@@ -39,7 +40,7 @@ Command IDs in `actions` are stable strings; a route does not import command imp
|
|
|
39
40
|
| Smallest complete `makeCrudRoute` (per-method ACL, ORM/scope/soft-delete, list schema + sort map, `mapToEntity`/`applyToEntity`) | [`api/customer-priorities/route.ts`](../../../../src/modules/example/api/customer-priorities/route.ts) |
|
|
40
41
|
| Query-engine list fields, `cf:*` projection, command-backed `actions`, CSV export | [`api/todos/route.ts`](../../../../src/modules/example/api/todos/route.ts) |
|
|
41
42
|
| Module OpenAPI factory | [`api/openapi.ts`](../../../../src/modules/example/api/openapi.ts) |
|
|
42
|
-
| Hand-written route
|
|
43
|
+
| Hand-written route: auth from the dispatcher context, one request container | [`api/organizations/route.ts`](../../../../src/modules/example/api/organizations/route.ts) |
|
|
43
44
|
| `optionsUrl` option-source routes | [`api/tags/route.ts`](../../../../src/modules/example/api/tags/route.ts), [`api/assignees/route.ts`](../../../../src/modules/example/api/assignees/route.ts) |
|
|
44
45
|
| Registered command handlers, `ensureScope`, `prepare` snapshots, undo/redo | [`commands/todos.ts`](../../../../src/modules/example/commands/todos.ts) |
|
|
45
46
|
|