@open-mercato/core 0.5.1-develop.2970.ec144ae954 → 0.5.1-develop.2975.ccbadc8198

package/AGENTS.md

@@ -122,6 +122,19 @@ Follow the customers module API patterns (CRUD factory + query engine):
 - Set `indexer: { entityType }` in `makeCrudRoute`
 - Reference: `src/modules/customers/api/people/route.ts`
 
+### Entity Schema And Migration Workflow
+
+When adding or changing a MikroORM entity, coding agents MUST read this section, the customers reference module guide, and `packages/cli/AGENTS.md` before editing.
+
+1. Update `data/entities.ts` using MikroORM v7 imports: decorators from `@mikro-orm/decorators/legacy`, types from `@mikro-orm/core`.
+2. Run `yarn generate` when module structure or entity discovery changed.
+3. Treat `yarn db:generate` as a schema-diff probe. Review every generated file before keeping it.
+4. Keep only SQL for the intended module/entity change. If the generator emits unrelated migrations because another module's snapshot is stale, remove those files from the diff instead of committing them.
+5. If you author a scoped SQL migration yourself to avoid unrelated generated churn, base it on the entity metadata and existing module migration style, then update that module's `migrations/.snapshot-open-mercato.json` to the post-change schema in the same commit.
+6. Do not run `yarn db:migrate` unless the user explicitly asks to apply migrations. PRs should normally contain the migration file and snapshot, not local DB state.
+
+For new CRUD modules, use `packages/core/src/modules/customers/AGENTS.md` as the file-structure reference and copy the command/API patterns before inventing new ones.
+
 ## Module Setup Convention
 
 Every module participating in tenant initialization must declare `setup.ts`. The generator auto-discovers these files.
@@ -463,7 +476,8 @@ await emitCrudSideEffects({ ... })
 - Module-scoped with MikroORM: files live in `src/modules/<module>/migrations/`
 - Generate: `yarn db:generate` (iterates all modules)
 - Apply: `yarn db:migrate` (ordered, directory first)
-- **Never hand-write migration files.** Update ORM entities, let `yarn db:generate` emit SQL.
+- Default: update ORM entities and let `yarn db:generate` emit SQL.
+- Exception: when generated output includes unrelated snapshot drift, keep or write only the intended SQL and update that module's `.snapshot-open-mercato.json` in the same change.
 
 ## Database Entities
 

package/jest.setup.ts

@@ -26,6 +26,12 @@ class MockResponse {
   async text() {
     return this.body
   }
+
+  clone() {
+    const cloned = new MockResponse(this.body, { status: this.status })
+    cloned.headers = new Map(this.headers)
+    return cloned
+  }
 }
 
 if (typeof globalThis.Response === 'undefined') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/core",
-  "version": "0.5.1-develop.2970.ec144ae954",
+  "version": "0.5.1-develop.2975.ccbadc8198",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -237,10 +237,10 @@
     "ts-pattern": "^5.0.0"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.5.1-develop.2970.ec144ae954"
+    "@open-mercato/shared": "0.5.1-develop.2975.ccbadc8198"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.5.1-develop.2970.ec144ae954",
+    "@open-mercato/shared": "0.5.1-develop.2975.ccbadc8198",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.1",

package/src/modules/customers/AGENTS.md

@@ -39,6 +39,16 @@
 - **Comments** — notes on records. MUST reference the parent entity
 - **Addresses** — multi-address support. MUST link to person or company via FK
 
+## New Entity Checklist For Agents
+
+When creating a new entity or CRUD slice, copy the customers module structure first, then align with `packages/core/AGENTS.md` and `packages/cli/AGENTS.md`.
+
+1. Define MikroORM v7 entities in `data/entities.ts` with decorators imported from `@mikro-orm/decorators/legacy`.
+2. Use UUID primary keys, snake_case table/column names, `organization_id`, `tenant_id`, and standard timestamp/soft-delete columns.
+3. Add validators, commands, CRUD route, backend pages, ACL, setup grants, events, search, and translations as applicable.
+4. Generate or author the migration for only this entity change, then update the module's `migrations/.snapshot-open-mercato.json`.
+5. Run `yarn db:generate` again as a no-op check; expected output for the touched module is `no changes`.
+
 ## CRUD API Pattern
 
 The CRUD factory API route (`api/people/route.ts`) demonstrates: