create-mercato-app 0.6.2-develop.3467.1.2a1818709d → 0.6.3-develop.3484.1.1427e58147

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mercato-app",
-  "version": "0.6.2-develop.3467.1.2a1818709d",
+  "version": "0.6.3-develop.3484.1.1427e58147",
   "type": "module",
   "description": "Create a new Open Mercato application",
   "main": "./dist/index.js",
@@ -21,10 +21,10 @@
     "tar": "^7.5.15"
   },
   "devDependencies": {
-    "@types/node": "^25.6.2",
+    "@types/node": "^25.9.0",
     "esbuild": "^0.28.0",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "tsx": "^4.22.2",
+    "typescript": "^6.0.3"
   },
   "publishConfig": {
     "access": "public"
@@ -42,5 +42,5 @@
     "cli"
   ],
   "license": "MIT",
-  "stableVersion": "0.6.1"
+  "stableVersion": "0.6.2"
 }

package/template/AGENTS.md

@@ -147,6 +147,17 @@ This is a Next.js 16 application built on the **Open Mercato** modular ERP frame
 - `src/bootstrap.ts` - Application initialization (imports generated files, registers i18n)
 - `.mercato/generated/` - Auto-generated files from `yarn generate` (do not edit manually)
 
+### Module Overrides
+
+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.
+
+Rules:
+
+- `null` disables a matching contract; an object/function definition replaces it.
+- API route keys are `'METHOD /api/path'`; page route keys are `'/backend/path'` or `'/frontend/path'`.
+- `setup` overrides apply to the module entry carrying them, not to a separate setup id map.
+- The standard `src/bootstrap.ts` already calls `applyModuleOverridesFromEnabledModules(enabledModules)` before registries load.
+
 ### Routing Structure
 
 - `/backend/*` - Admin panel routes (AppShell with sidebar navigation)
@@ -248,7 +259,7 @@ export const aiAgentOverrides: AiAgentOverridesMap = {
 }
 ```
 
-Example `modules.ts` inline override (preferred for app-level decisions that don't deserve a fake module). AI lives at `overrides.ai.*`; other domains (routes, events, workers, widgets, …) reuse the same `entry.overrides` umbrella per the [unified spec](https://github.com/open-mercato/open-mercato/blob/main/.ai/specs/2026-05-04-modules-ts-unified-overrides.md) — AI is Phase 1, other domains roll out as separate PRs:
+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/2026-05-04-modules-ts-unified-overrides.md):
 
 ```ts
 // src/modules.ts
@@ -260,6 +271,17 @@ Example `modules.ts` inline override (preferred for app-level decisions that don
       agents: { 'catalog.catalog_assistant': null },
       tools:  { 'inbox_ops_accept_action': null },
     },
+    routes: {
+      api: {
+        'GET /api/example/override-probe': {
+          handler: async () => Response.json({ ok: true, source: 'override' }),
+          metadata: { requireAuth: false },
+        },
+      },
+      pages: {
+        '/backend/example/reports': null,
+      },
+    },
   },
 },
 ```
@@ -290,6 +312,108 @@ yarn mercato configs cache structural --all-tenants
 
 Refer to the `create-ai-agent` skill (`.ai/skills/create-ai-agent/SKILL.md`) and the public docs at `framework/ai-assistant/overrides` for the full contract, MUST rules, and the resolution order.
 
+### Unified module contract overrides
+
+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.
+
+```ts
+// src/modules.ts — representative examples across override phases
+{
+  id: 'example',
+  from: '@app',
+  overrides: {
+    routes: {
+      api: {
+        // disable
+        'DELETE /api/example/items': null,
+        // replace
+        'POST /api/example/items': {
+          handler: async (req) => new Response(JSON.stringify({ ok: true }), { status: 200 }),
+          metadata: { requireAuth: true, requireFeatures: ['example.manage'] },
+        },
+      },
+      pages: {
+        '/backend/example/items': null,
+      },
+    },
+    events: {
+      subscribers: {
+        'example.todo.created.notify': null,
+      },
+    },
+    workers: {
+      'example:sync': null,
+    },
+    widgets: {
+      injection: { 'example.toolbar': null },
+      dashboard: { 'example.kpi': null },
+      components: {
+        'page:/backend/example': {
+          target: { componentId: 'page:/backend/example' },
+          priority: 10,
+          propsTransform: (props) => props,
+        },
+      },
+    },
+    notifications: {
+      types: { 'example.notice': null },
+      handlers: { 'example.notice.toast': null },
+    },
+    interceptors: { 'example.items.audit': null },
+    commandInterceptors: { 'example.command.audit': null },
+    enrichers: { 'example.items.enricher': null },
+    guards: { 'example.backend.guard': null },
+    cli: { 'example seed': null },
+    setup: {
+      defaultRoleFeatures: { admin: ['example.view'] },
+      seedExamples: false,
+    },
+    acl: {
+      features: { 'example.manage': null },
+    },
+    di: {
+      exampleService: {
+        register: (container, key) => container.register({ [key]: { mode: 'replacement' } }),
+      },
+    },
+    encryption: {
+      maps: { 'example:item': null },
+    },
+  },
+},
+```
+
+Programmatic equivalent (boot-time, env-driven, or test scaffold):
+
+```ts
+// src/bootstrap.ts (extra)
+import {
+  applyApiRouteOverrides,
+  applyPageRouteOverrides,
+  applyWorkerOverrides,
+} from '@open-mercato/shared/modules/overrides'
+
+applyApiRouteOverrides({
+  'GET /api/example/items': null,
+})
+applyPageRouteOverrides({
+  '/backend/example/items': null,
+})
+applyWorkerOverrides({
+  'example:sync': null,
+})
+```
+
+Key rules:
+
+- Keys are `'METHOD /api/path'`; method is normalized, path leading slash optional, trailing slashes stripped.
+- Page route keys are `'/backend/path'` or `'/frontend/path'`.
+- `null` disables the matching contract; a definition replaces it.
+- Programmatic > `modules.ts` > file-based where supported > base. The dispatcher MUST run before registries first-load — the template's `bootstrap.ts` already does this.
+- Stale override keys log a warning so operators notice renamed or removed upstream contracts.
+
+Full reference: `framework/modules/overrides` and `framework/modules/routes-and-pages`.
+
 ## Disabling the Dashboards Module: Update /backend
 
 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.

package/template/package.json.template

@@ -78,7 +78,7 @@
     "@uiw/react-markdown-preview": "^5.2.0",
     "@uiw/react-md-editor": "^4.1.0",
     "@xyflow/react": "^12.6.0",
-    "ai": "^6.0.177",
+    "ai": "^6.0.185",
     "awilix": "^12.0.5",
     "bcryptjs": "^3.0.3",
     "class-variance-authority": "^0.7.1",
@@ -90,7 +90,7 @@
     "mammoth": "^1.9.0",
     "newrelic": "^13.19.1",
     "next": "16.2.6",
-    "pg": "8.20.0",
+    "pg": "8.21.0",
     "pdfjs-dist": "^5.4.149",
     "react": "19.2.5",
     "react-big-calendar": "^1.19.4",
@@ -103,8 +103,8 @@
     "semver": "^7.7.4",
     "tailwind-merge": "^3.5.0",
     "zod": "4.3.6",
-    "@stripe/react-stripe-js": "^6.3.0",
-    "@stripe/stripe-js": "^9.3.1",
+    "@stripe/react-stripe-js": "^6.4.0",
+    "@stripe/stripe-js": "^9.6.0",
     "@open-mercato/gateway-stripe": "{{PACKAGE_VERSION}}",
     "@open-mercato/sync-akeneo": "{{PACKAGE_VERSION}}"
   },

package/template/src/app/(backend)/backend/[...slug]/page.tsx

@@ -1,8 +1,9 @@
 import { notFound, redirect } from 'next/navigation'
 import { cookies } from 'next/headers'
 import Link from 'next/link'
-import { findRouteManifestMatch } from '@open-mercato/shared/modules/registry'
+import { findRouteManifestMatch, getBackendRouteManifests, registerBackendRouteManifests } from '@open-mercato/shared/modules/registry'
 import { backendRoutes } from '@/.mercato/generated/backend-routes.generated'
+import { bootstrap } from '@/bootstrap'
 import { getAuthFromCookies } from '@open-mercato/shared/lib/auth/server'
 import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
 import { ApplyBreadcrumb } from '@open-mercato/ui/backend/AppShell'
@@ -17,6 +18,9 @@ import { resolveLocalizedTitleMetadata } from '@/lib/metadata'
 import { resolvePageMiddlewareRedirect } from '@open-mercato/shared/lib/middleware/page-executor'
 import { backendMiddlewareEntries } from '@/.mercato/generated/backend-middleware.generated'
 
+bootstrap()
+registerBackendRouteManifests(backendRoutes)
+
 type Awaitable<T> = T | Promise<T>
 
 type BackendParams = { params: Awaitable<{ slug?: string[] }> }
@@ -39,7 +43,7 @@ async function renderAccessDenied() {
 export async function generateMetadata(props: BackendParams): Promise<Metadata> {
   const params = await props.params
   const pathname = '/backend/' + (params.slug?.join('/') ?? '')
-  const match = findRouteManifestMatch(backendRoutes, pathname)
+  const match = findRouteManifestMatch(getBackendRouteManifests(), pathname)
   if (!match) {
     return {}
   }
@@ -53,7 +57,7 @@ export async function generateMetadata(props: BackendParams): Promise<Metadata>
 export default async function BackendCatchAll(props: BackendParams) {
   const params = await props.params
   const pathname = '/backend/' + (params.slug?.join('/') ?? '')
-  const match = findRouteManifestMatch(backendRoutes, pathname)
+  const match = findRouteManifestMatch(getBackendRouteManifests(), pathname)
   if (!match) return notFound()
   let auth: AuthContext = null
   let container: Awaited<ReturnType<typeof createRequestContainer>> | null = null

package/template/src/app/(backend)/backend/__tests__/backend-require-features.test.tsx

@@ -8,6 +8,11 @@ jest.mock('@/.mercato/generated/backend-routes.generated', () => ({
   backendRoutes: [],
 }))
 
+jest.mock('@/bootstrap', () => ({
+  bootstrap: jest.fn(),
+  isBootstrapped: jest.fn(() => true),
+}))
+
 import BackendCatchAll from '@/app/(backend)/backend/[...slug]/page'
 
 // Mock UI breadcrumb component to avoid UI package dependency
@@ -39,6 +44,8 @@ jest.mock('@open-mercato/shared/modules/registry', () => ({
     },
     params: {},
   })),
+  getBackendRouteManifests: jest.fn(() => []),
+  registerBackendRouteManifests: jest.fn(),
 }))
 
 jest.mock('@/.mercato/generated/backend-middleware.generated', () => ({

package/template/src/app/(frontend)/[...slug]/page.tsx

@@ -1,9 +1,8 @@
 import { notFound, redirect } from 'next/navigation'
 import Link from 'next/link'
-import { findRouteManifestMatch, registerFrontendRouteManifests } from '@open-mercato/shared/modules/registry'
+import { findRouteManifestMatch, getFrontendRouteManifests, registerFrontendRouteManifests } from '@open-mercato/shared/modules/registry'
+import { bootstrap } from '@/bootstrap'
 import { frontendRoutes } from '@/.mercato/generated/frontend-routes.generated'
-
-registerFrontendRouteManifests(frontendRoutes)
 import { getAuthFromCookies } from '@open-mercato/shared/lib/auth/server'
 import { AccessDeniedMessage } from '@open-mercato/ui/backend/detail'
 import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
@@ -16,6 +15,9 @@ import { resolveLocalizedTitleMetadata } from '@/lib/metadata'
 import { resolvePageMiddlewareRedirect } from '@open-mercato/shared/lib/middleware/page-executor'
 import { frontendMiddlewareEntries } from '@/.mercato/generated/frontend-middleware.generated'
 
+bootstrap()
+registerFrontendRouteManifests(frontendRoutes)
+
 type FrontendParams = { params: Promise<{ slug: string[] }> }
 
 async function renderAccessDenied() {
@@ -36,7 +38,7 @@ async function renderAccessDenied() {
 export async function generateMetadata({ params }: FrontendParams): Promise<Metadata> {
   const p = await params
   const pathname = '/' + (p.slug?.join('/') ?? '')
-  const match = findRouteManifestMatch(frontendRoutes, pathname)
+  const match = findRouteManifestMatch(getFrontendRouteManifests(), pathname)
   if (!match) {
     return {}
   }
@@ -50,7 +52,7 @@ export async function generateMetadata({ params }: FrontendParams): Promise<Meta
 export default async function SiteCatchAll({ params }: FrontendParams) {
   const p = await params
   const pathname = '/' + (p.slug?.join('/') ?? '')
-  const match = findRouteManifestMatch(frontendRoutes, pathname)
+  const match = findRouteManifestMatch(getFrontendRouteManifests(), pathname)
   if (!match) return notFound()
 
   // Customer portal auth gate — separate from staff auth

package/template/src/app/api/[...slug]/route.ts

@@ -1,17 +1,9 @@
 import { NextResponse, type NextRequest } from 'next/server'
-import { findApiRouteManifestMatch, registerApiRouteManifests, registerBackendRouteManifests, registerFrontendRouteManifests, type HttpMethod } from '@open-mercato/shared/modules/registry'
+import { findApiRouteManifestMatch, getApiRouteManifests, registerApiRouteManifests, type HttpMethod } from '@open-mercato/shared/modules/registry'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { apiRoutes } from '@/.mercato/generated/api-routes.generated'
-import { backendRoutes } from '@/.mercato/generated/backend-routes.generated'
-import { frontendRoutes } from '@/.mercato/generated/frontend-routes.generated'
 import { resolveAuthFromRequestDetailed } from '@open-mercato/shared/lib/auth/server'
 import { bootstrap } from '@/bootstrap'
-
-// Ensure all package registrations are initialized for API routes
-bootstrap()
-registerBackendRouteManifests(backendRoutes)
-registerFrontendRouteManifests(frontendRoutes)
-registerApiRouteManifests(apiRoutes)
 import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
@@ -25,6 +17,10 @@ import { checkRateLimit, getClientIp, RATE_LIMIT_ERROR_KEY, RATE_LIMIT_ERROR_FAL
 import { getGlobalEventBus } from '@open-mercato/shared/modules/events'
 import { applicationLifecycleEvents, type ApplicationLifecycleEventId } from '@open-mercato/shared/lib/runtime/events'
 
+// Ensure all package registrations are initialized for API routes.
+bootstrap()
+registerApiRouteManifests(apiRoutes)
+
 type MethodMetadata = {
   requireAuth?: boolean
   /** @deprecated Use `requireFeatures` instead — role names are mutable and can be spoofed */
@@ -293,7 +289,7 @@ async function handleRequest(
     receivedAt: new Date().toISOString(),
   }
   await emitLifecycleEvent(applicationLifecycleEvents.requestReceived, receivedPayload)
-  const match = findApiRouteManifestMatch(apiRoutes, method, pathname)
+  const match = findApiRouteManifestMatch(getApiRouteManifests(), method, pathname)
   if (!match) {
     const response = NextResponse.json({ error: t('api.errors.notFound', 'Not Found') }, { status: 404 })
     await emitLifecycleEvent(applicationLifecycleEvents.requestNotFound, {

package/template/src/bootstrap.ts

@@ -29,7 +29,7 @@ registerAppDictionaryLoader(async (locale: Locale): Promise<Record<string, unkno
 })
 
 // modules.ts inline overrides (replace/disable any contract a module
-// presents — AI today, other domains rolling out per the unified spec).
+// presents through the unified modules.ts override surface).
 // Importing @open-mercato/ai-assistant here also runs the side-effect
 // that registers the AI domain applier with the umbrella dispatcher.
 import { enabledModules } from '@/modules'

package/template/src/modules/example/__integration__/TC-UMES-022-overrides.spec.ts

@@ -0,0 +1,21 @@
+import { test, expect } from '@playwright/test'
+
+function resolveUrl(path: string): string {
+  const baseUrl = process.env.BASE_URL?.trim()
+  return baseUrl ? `${baseUrl}${path}` : path
+}
+
+test.describe('TC-UMES-022: modules.ts overrides', () => {
+  test('routes.api override replaces the example override probe handler', async ({ request }) => {
+    const response = await request.get(resolveUrl('/api/example/override-probe'))
+
+    expect(response.ok(), `GET /api/example/override-probe returned ${response.status()}`).toBeTruthy()
+    const body = await response.json()
+    expect(body).toMatchObject({
+      ok: true,
+      source: 'modules.ts override',
+      route: 'example.override-probe',
+    })
+  })
+})
+

package/template/src/modules/example/api/override-probe/route.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { exampleTag } from '../openapi'
+
+export const metadata = {
+  GET: { requireAuth: false },
+}
+
+export async function GET() {
+  return Response.json({
+    ok: true,
+    source: 'base',
+    route: 'example.override-probe',
+  })
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: exampleTag,
+  methods: {
+    GET: {
+      summary: 'Example override probe',
+      description: 'Returns a small payload used by integration tests to verify modules.ts API route overrides.',
+      tags: [exampleTag],
+      responses: [
+        {
+          status: 200,
+          description: 'Probe payload',
+          schema: z.object({
+            ok: z.boolean(),
+            source: z.string(),
+            route: z.string(),
+          }),
+        },
+      ],
+    },
+  },
+}
+

package/template/src/modules.ts

@@ -2,12 +2,13 @@
 // - id: module id (plural snake_case; special cases: 'auth')
 // - from: '@open-mercato/core' | '@app' | custom alias/path in future
 // - overrides: optional unified per-app override surface — replace or
-//   disable any contract a module presents. AI is wired today (Phase 1);
-//   other domains are stubbed and emit a one-shot warning if used.
+//   disable any contract a module presents: AI, routes, events, workers,
+//   widgets, notifications, interceptors, setup, ACL, DI, encryption, etc.
 //   See `.ai/specs/2026-05-04-modules-ts-unified-overrides.md` and
-//   `apps/docs/docs/framework/ai-assistant/overrides.mdx`.
+//   `apps/docs/docs/framework/modules/overrides.mdx`.
 import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import type { ModuleOverrides } from '@open-mercato/shared/modules/overrides'
+import { officialModuleEntries } from './official-modules.generated'
 
 export type ModuleEntry = {
   id: string
@@ -15,6 +16,52 @@ export type ModuleEntry = {
   overrides?: ModuleOverrides
 }
 
+/**
+ * Copyable examples for every wired `entry.overrides` domain.
+ *
+ * This object is intentionally not assigned to any enabled module. Use it as
+ * a reference when a downstream app needs to disable or replace contracts
+ * from a package-backed module without editing that module's source.
+ */
+export const moduleOverrideExamples: ModuleOverrides = {
+  ai: {
+    agents: { 'catalog.catalog_assistant': null },
+    tools: { inbox_ops_accept_action: null },
+  },
+  routes: {
+    api: { 'DELETE /api/example/items': null },
+    pages: { '/backend/example/reports': null },
+  },
+  events: {
+    subscribers: { 'example.todo.audit': null },
+  },
+  workers: { 'example:sync': null },
+  widgets: {
+    injection: { 'example.sidebar': null },
+    components: { 'page:/backend/example': null },
+    dashboard: { 'example.kpi': null },
+  },
+  notifications: {
+    types: { 'example.notice': null },
+    handlers: { 'example.notice.toast': null },
+  },
+  interceptors: { 'example.items.interceptor': null },
+  commandInterceptors: { 'example.command.interceptor': null },
+  enrichers: { 'example.items.enricher': null },
+  guards: { 'example.backend.guard': null },
+  cli: { 'example seed': null },
+  setup: {
+    seedExamples: false,
+  },
+  acl: {
+    features: { 'example.manage': null },
+  },
+  di: { exampleService: null },
+  encryption: {
+    maps: { 'example:item': null },
+  },
+}
+
 export const enabledModules: ModuleEntry[] = [
   { id: 'dashboards', from: '@open-mercato/core' },
   { id: 'auth', from: '@open-mercato/core' },
@@ -60,10 +107,33 @@ export const enabledModules: ModuleEntry[] = [
   { id: 'webhooks', from: '@open-mercato/webhooks' },
   { id: 'customer_accounts', from: '@open-mercato/core' },
   { id: 'portal', from: '@open-mercato/core' },
-  { id: 'example', from: '@app' },
+  {
+    id: 'example',
+    from: '@app',
+    overrides: {
+      routes: {
+        api: {
+          'GET /api/example/override-probe': {
+            handler: async () => Response.json({
+              ok: true,
+              source: 'modules.ts override',
+              route: 'example.override-probe',
+            }),
+            metadata: { requireAuth: false },
+          },
+        },
+      },
+    },
+  },
   { id: 'ratelimit_probe', from: '@app' },
 ]
 
+// Official modules activated via official-modules.json / official-modules.local.json
+// (managed by `yarn official-modules`; backed by the external/official-modules submodule).
+for (const entry of officialModuleEntries) {
+  if (!enabledModules.some((existing) => existing.id === entry.id)) enabledModules.push(entry)
+}
+
 if (enabledModules.some((entry) => entry.id === 'example')) {
   enabledModules.push({ id: 'example_customers_sync', from: '@app' })
 }

package/template/src/official-modules.generated.ts

@@ -0,0 +1,14 @@
+// AUTO-GENERATED — do not edit by hand.
+// Source: official-modules.json (+ official-modules.local.json override).
+// Regenerate with: yarn official-modules
+//
+// Why is this file in src/ and not under .mercato/generated/?
+// It is a *versioned* generated registry — the activation set must travel
+// with the repo and survive `yarn clean-generated`. Moving it under any
+// `generated/` folder would gitignore-and-wipe it. See
+// .ai/specs/2026-05-19-official-modules-generated-location-decision.md
+// and the "Generated Files: versioned vs ephemeral" section in AGENTS.md.
+import type { ModuleEntry } from './modules'
+
+export const officialModuleEntries: ModuleEntry[] = [
+]