@open-mercato/cli 0.6.6-develop.6377.1.d26fed7324 → 0.6.6-develop.6382.1.4b9b9091ab

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.6-develop.6377.1.d26fed7324",
+  "version": "0.6.6-develop.6382.1.4b9b9091ab",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     "@mikro-orm/decorators": "^7.1.4",
     "@mikro-orm/migrations": "^7.1.4",
     "@mikro-orm/postgresql": "^7.1.4",
-    "@open-mercato/queue": "0.6.6-develop.6377.1.d26fed7324",
-    "@open-mercato/shared": "0.6.6-develop.6377.1.d26fed7324",
+    "@open-mercato/queue": "0.6.6-develop.6382.1.4b9b9091ab",
+    "@open-mercato/shared": "0.6.6-develop.6382.1.4b9b9091ab",
     "cross-spawn": "^7.0.6",
     "pg": "8.22.0",
     "semver": "^7.8.5",
@@ -71,10 +71,10 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.6377.1.d26fed7324"
+    "@open-mercato/shared": "0.6.6-develop.6382.1.4b9b9091ab"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.6377.1.d26fed7324",
+    "@open-mercato/shared": "0.6.6-develop.6382.1.4b9b9091ab",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11"

package/src/__tests__/mercato.test.ts

@@ -359,6 +359,7 @@ describe('init command failure output', () => {
       generateModuleDi: jest.fn().mockResolvedValue(undefined),
       generateModulePackageSources: jest.fn().mockResolvedValue(undefined),
       generateOpenApi: jest.fn().mockResolvedValue(undefined),
+      generateModuleFacts: jest.fn().mockResolvedValue(undefined),
     }))
     jest.doMock('../lib/resolver', () => ({
       createResolver: () => ({
@@ -407,6 +408,7 @@ describe('init command failure output', () => {
       generateModuleDi: jest.fn().mockResolvedValue(undefined),
       generateModulePackageSources: jest.fn().mockResolvedValue(undefined),
       generateOpenApi: jest.fn().mockResolvedValue(undefined),
+      generateModuleFacts: jest.fn().mockResolvedValue(undefined),
     }))
     jest.doMock('../lib/resolver', () => ({
       createResolver: () => ({
@@ -458,6 +460,7 @@ describe('init command failure output', () => {
       generateModuleDi: jest.fn().mockResolvedValue(undefined),
       generateModulePackageSources: jest.fn().mockResolvedValue(undefined),
       generateOpenApi: jest.fn().mockResolvedValue(undefined),
+      generateModuleFacts: jest.fn().mockResolvedValue(undefined),
     }))
     jest.doMock('../lib/db', () => ({
       dbMigrate: jest.fn().mockResolvedValue(undefined),
@@ -566,6 +569,7 @@ describe('generate post-step structural cache purge', () => {
       generateModuleDi,
       generateModulePackageSources,
       generateOpenApi,
+      generateModuleFacts: jest.fn().mockResolvedValue(undefined),
     }))
     jest.doMock('../lib/resolver', () => ({
       createResolver: () => ({
@@ -615,6 +619,7 @@ describe('generate post-step structural cache purge', () => {
       generateModuleDi,
       generateModulePackageSources,
       generateOpenApi,
+      generateModuleFacts: jest.fn().mockResolvedValue(undefined),
     }))
     jest.doMock('../lib/resolver', () => ({
       createResolver: () => ({

package/src/lib/generators/__tests__/module-facts.auth-source.test.ts

@@ -0,0 +1,83 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { extractModuleFacts } from '../module-facts'
+
+function findCoreSrcRoot(): string {
+  let dir = __dirname
+  for (let depth = 0; depth < 10; depth += 1) {
+    const candidate = path.join(dir, 'packages', 'core', 'src', 'modules')
+    if (fs.existsSync(candidate)) return candidate
+    dir = path.dirname(dir)
+  }
+  throw new Error('[internal] could not locate packages/core/src/modules from the test directory')
+}
+
+const REGISTRY_SOURCE = `
+export const modules = [
+  {
+    id: 'customers',
+    apis: [
+      {
+        path: '/api/customers/people',
+        handlers: { GET: handlerGet, POST: handlerPost },
+        metadata: {
+          GET: { requireAuth: true, requireFeatures: ['customers.people.view'] },
+          POST: { requireAuth: true, requireFeatures: ['customers.people.manage'] },
+        },
+      },
+      {
+        path: '/api/customers/people/:id',
+        handlers: { GET: handlerGet, PUT: handlerPut, DELETE: handlerDelete },
+        metadata: {
+          GET: { requireFeatures: ['customers.people.view'] },
+          PUT: { requireFeatures: ['customers.people.manage'] },
+          DELETE: { requireFeatures: ['customers.people.manage'] },
+        },
+      },
+    ],
+  },
+  {
+    id: 'sales',
+    apis: [
+      {
+        path: '/api/sales/orders',
+        handlers: { GET: handlerGet },
+        metadata: { GET: { requireFeatures: ['sales.orders.view'] } },
+      },
+    ],
+  },
+]
+`
+
+describe('module-facts API route auth source (T2)', () => {
+  const coreSrcRoot = findCoreSrcRoot()
+  const facts = extractModuleFacts({ moduleId: 'customers', coreSrcRoot, registrySource: REGISTRY_SOURCE })
+
+  it('reads per-method auth from the registry apis[].metadata for the requested module', () => {
+    const list = facts.apiRoutes.find((route) => route.path === '/api/customers/people')
+    expect(list).toBeDefined()
+    expect(list?.methods).toEqual(['GET', 'POST'])
+    expect(list?.auth.GET).toEqual({ requireAuth: true, requireFeatures: ['customers.people.view'] })
+    expect(list?.auth.POST).toEqual({ requireAuth: true, requireFeatures: ['customers.people.manage'] })
+
+    const detail = facts.apiRoutes.find((route) => route.path === '/api/customers/people/:id')
+    expect(detail?.methods).toEqual(['GET', 'PUT', 'DELETE'])
+    expect(detail?.auth.PUT).toEqual({ requireFeatures: ['customers.people.manage'] })
+    expect(detail?.auth.DELETE).toEqual({ requireFeatures: ['customers.people.manage'] })
+  })
+
+  it('scopes routes to the requested module and ignores other modules in the registry', () => {
+    expect(facts.apiRoutes.some((route) => route.path.startsWith('/api/sales/'))).toBe(false)
+    expect(facts.warnings.some((warning) => warning.includes('module registry unavailable'))).toBe(false)
+  })
+
+  it('omits API routes (and warns) when a registry path is provided but the file is missing', () => {
+    const missing = extractModuleFacts({
+      moduleId: 'customers',
+      coreSrcRoot,
+      registryPath: path.join(coreSrcRoot, '__does_not_exist__', 'modules.runtime.generated.ts'),
+    })
+    expect(missing.apiRoutes).toEqual([])
+    expect(missing.warnings.some((warning) => warning.includes('module registry unavailable'))).toBe(true)
+  })
+})

package/src/lib/generators/__tests__/module-facts.bc-guard.test.ts

@@ -0,0 +1,56 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { extractAllModuleFacts, MODULE_FACTS_ALLOWLIST } from '../module-facts'
+
+function findCoreSrcRoot(): string {
+  let dir = __dirname
+  for (let depth = 0; depth < 10; depth += 1) {
+    const candidate = path.join(dir, 'packages', 'core', 'src', 'modules')
+    if (fs.existsSync(candidate)) return candidate
+    dir = path.dirname(dir)
+  }
+  throw new Error('[internal] could not locate packages/core/src/modules from the test directory')
+}
+
+function isUnique(values: string[]): boolean {
+  return values.length === new Set(values).size
+}
+
+describe('module-facts BC resolve guard (T3)', () => {
+  const coreSrcRoot = findCoreSrcRoot()
+  const { factsByModule } = extractAllModuleFacts({ coreSrcRoot })
+
+  it('emits facts for every allowlisted module', () => {
+    expect(Object.keys(factsByModule).sort()).toEqual([...MODULE_FACTS_ALLOWLIST].sort())
+  })
+
+  for (const moduleId of MODULE_FACTS_ALLOWLIST) {
+    describe(`${moduleId}`, () => {
+      it('namespaces entity / event / acl / notification ids under the module and keeps them unique', () => {
+        const facts = factsByModule[moduleId]
+        const entityIds = facts.entities.map((entity) => entity.id)
+
+        expect(entityIds.every((id) => id.startsWith(`${moduleId}:`))).toBe(true)
+        expect(isUnique(entityIds)).toBe(true)
+        expect(facts.events.every((event) => event.id.startsWith(`${moduleId}.`))).toBe(true)
+        expect(isUnique(facts.events.map((event) => event.id))).toBe(true)
+        expect(facts.aclFeatures.every((feature) => feature.startsWith(`${moduleId}.`))).toBe(true)
+        expect(isUnique(facts.aclFeatures)).toBe(true)
+        expect(facts.notifications.every((notification) => notification.startsWith(`${moduleId}.`))).toBe(true)
+      })
+
+      it('resolves search and host-token references against the module entity set', () => {
+        const facts = factsByModule[moduleId]
+        const entityIds = new Set(facts.entities.map((entity) => entity.id))
+
+        for (const searchEntity of facts.searchEntities) {
+          expect(entityIds.has(searchEntity)).toBe(true)
+        }
+        for (const hostEntityId of facts.hostTokens.entityIds) {
+          expect(entityIds.has(hostEntityId)).toBe(true)
+          expect(hostEntityId.endsWith('_entity')).toBe(true)
+        }
+      })
+    })
+  }
+})

package/src/lib/generators/__tests__/module-facts.customers.fixture.test.ts

@@ -0,0 +1,69 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { extractModuleFacts } from '../module-facts'
+
+function findCoreSrcRoot(): string {
+  let dir = __dirname
+  for (let depth = 0; depth < 10; depth += 1) {
+    const candidate = path.join(dir, 'packages', 'core', 'src', 'modules')
+    if (fs.existsSync(candidate)) return candidate
+    dir = path.dirname(dir)
+  }
+  throw new Error('[internal] could not locate packages/core/src/modules from the test directory')
+}
+
+describe('module-facts customers fixture (T1 anti-drift guard)', () => {
+  const coreSrcRoot = findCoreSrcRoot()
+  const facts = extractModuleFacts({ moduleId: 'customers', coreSrcRoot })
+
+  it('locks the source-derived customers entity surface in colon-form ids', () => {
+    expect(facts.module).toBe('customers')
+    expect(facts.entities).toHaveLength(25)
+    expect(facts.entities.every((entity) => entity.id.startsWith('customers:'))).toBe(true)
+    expect(facts.entities[0]).toMatchObject({ id: 'customers:customer_entity' })
+    for (const entity of facts.entities) {
+      expect(entity.class.length).toBeGreaterThan(0)
+      expect(entity.table.length).toBeGreaterThan(0)
+    }
+  })
+
+  it('locks customers events, acl, search, and notification surfaces', () => {
+    expect(facts.events).toHaveLength(49)
+    expect(facts.aclFeatures).toHaveLength(21)
+    expect(facts.searchEntities).toEqual([
+      'customers:customer_person_profile',
+      'customers:customer_company_profile',
+      'customers:customer_comment',
+      'customers:customer_deal',
+      'customers:customer_activity',
+      'customers:customer_todo_link',
+    ])
+    expect(facts.notifications).toEqual(['customers.deal.won', 'customers.deal.lost'])
+  })
+
+  it('locks the real cli commands and host table ids, not the abbreviated spec example', () => {
+    expect(facts.cli).toEqual([
+      'seed-dictionaries',
+      'seed-examples',
+      'seed-stresstest',
+      'interactions:backfill',
+    ])
+    expect(facts.hostTokens.tableIds).toEqual([
+      'customers.companies.list',
+      'customers.deals.list',
+      'customers.people.list',
+    ])
+    expect(facts.hostTokens.entityIds).toEqual(['customers:customer_entity'])
+    expect(facts.diTokens).toEqual([])
+  })
+
+  it('omits API route auth and warns when no module registry is provided', () => {
+    expect(facts.apiRoutes).toEqual([])
+    expect(facts.warnings.some((warning) => warning.includes('module registry unavailable'))).toBe(true)
+  })
+
+  it('locks the module metadata surface extracted from index.ts', () => {
+    expect(facts.title).toBe('Customer Relationship Management')
+    expect(facts.description).toBe('Core CRM capabilities for people, companies, deals, and activities.')
+  })
+})

package/src/lib/generators/__tests__/module-facts.malformed.test.ts

@@ -0,0 +1,76 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { extractModuleFacts } from '../module-facts'
+
+let tmpRoot: string
+
+function writeModuleFile(moduleId: string, relativePath: string, content: string): void {
+  const fullPath = path.join(tmpRoot, moduleId, relativePath)
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true })
+  fs.writeFileSync(fullPath, content)
+}
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'module-facts-malformed-'))
+})
+
+afterEach(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true })
+})
+
+describe('module-facts malformed source handling (T4)', () => {
+  it('returns empty sections plus warnings (never throws) for malformed convention files', () => {
+    writeModuleFile('broken', 'data/entities.ts', 'export const notAnEntity = 1\nexport class LooseClass {}\n')
+    writeModuleFile('broken', 'search.ts', 'export const unrelatedConfig = { entities: [] }\n')
+    writeModuleFile('broken', 'notifications.ts', 'export const notifications = "not-an-array"\n')
+    writeModuleFile('broken', 'cli.ts', 'export const commands = []\n')
+
+    const run = (): ReturnType<typeof extractModuleFacts> =>
+      extractModuleFacts({ moduleId: 'broken', coreSrcRoot: tmpRoot })
+    expect(run).not.toThrow()
+
+    const facts = run()
+    expect(facts.entities).toEqual([])
+    expect(facts.events).toEqual([])
+    expect(facts.aclFeatures).toEqual([])
+    expect(facts.searchEntities).toEqual([])
+    expect(facts.notifications).toEqual([])
+    expect(facts.cli).toEqual([])
+    expect(facts.apiRoutes).toEqual([])
+
+    const warnings = facts.warnings.join('\n')
+    expect(warnings).toContain('search.ts present but no searchConfig')
+    expect(warnings).toContain('notifications.ts present but no notificationTypes array')
+    expect(warnings).toContain('cli.ts present but no default export')
+    expect(warnings).toContain('module registry unavailable')
+  })
+
+  it('survives a syntactically broken source file without throwing', () => {
+    writeModuleFile('broken', 'search.ts', 'export const searchConfig = { entities: [ this is not valid typescript\n')
+
+    const run = (): ReturnType<typeof extractModuleFacts> =>
+      extractModuleFacts({ moduleId: 'broken', coreSrcRoot: tmpRoot })
+    expect(run).not.toThrow()
+    expect(run().searchEntities).toEqual([])
+  })
+
+  it('returns all-empty facts (never throws) for a module with no convention files', () => {
+    fs.mkdirSync(path.join(tmpRoot, 'empty'), { recursive: true })
+
+    const run = (): ReturnType<typeof extractModuleFacts> =>
+      extractModuleFacts({ moduleId: 'empty', coreSrcRoot: tmpRoot })
+    expect(run).not.toThrow()
+
+    expect(run()).toMatchObject({
+      module: 'empty',
+      entities: [],
+      events: [],
+      aclFeatures: [],
+      searchEntities: [],
+      notifications: [],
+      cli: [],
+      diTokens: [],
+    })
+  })
+})

package/src/lib/generators/index.ts

@@ -4,3 +4,4 @@ export { generateModuleEntities, type ModuleEntitiesOptions } from './module-ent
 export { generateModuleDi, type ModuleDiOptions } from './module-di'
 export { generateModulePackageSources, type ModulePackageSourcesOptions } from './module-package-sources'
 export { generateOpenApi, type GenerateOpenApiOptions } from './openapi'
+export { generateModuleFacts, type ModuleFactsOptions } from './module-facts-generate'

package/src/lib/generators/module-facts-generate.ts

@@ -0,0 +1,68 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { PackageResolver } from '../resolver'
+import {
+  createGeneratorResult,
+  ensureDir,
+  logGenerationResult,
+  type GeneratorResult,
+} from '../utils'
+import { extractAllModuleFacts, renderModuleFactsJson } from './module-facts'
+
+export interface ModuleFactsOptions {
+  resolver: PackageResolver
+  quiet?: boolean
+}
+
+function readCoreVersion(coreSrcRoot: string): string | null {
+  const corePackageJsonPath = path.resolve(coreSrcRoot, '..', '..', 'package.json')
+  if (!fs.existsSync(corePackageJsonPath)) return null
+  try {
+    const parsed = JSON.parse(fs.readFileSync(corePackageJsonPath, 'utf8')) as { version?: unknown }
+    return typeof parsed.version === 'string' ? parsed.version : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Emits the versioned `apps/mercato/src/module-facts.generated.json` artifact from
+ * monorepo core module sources. Must run AFTER `generateModuleRegistry` because
+ * per-route API auth is read from the generated `modules.runtime.generated.ts`
+ * registry (`apis[].metadata`). Registry-derived warnings are non-fatal.
+ */
+export async function generateModuleFacts(options: ModuleFactsOptions): Promise<GeneratorResult> {
+  const { resolver, quiet } = options
+  const result = createGeneratorResult()
+
+  const rootDir = resolver.getRootDir()
+  const coreSrcRoot = path.join(rootDir, 'packages', 'core', 'src', 'modules')
+  if (!fs.existsSync(coreSrcRoot)) {
+    if (!quiet) {
+      console.warn(`[module-facts] core module sources not found at ${coreSrcRoot}; skipping module-facts generation`)
+    }
+    return result
+  }
+
+  const registryPath = path.join(resolver.getOutputDir(), 'modules.runtime.generated.ts')
+  const coreVersion = readCoreVersion(coreSrcRoot)
+
+  const { factsByModule, warnings } = extractAllModuleFacts({ coreSrcRoot, registryPath, coreVersion })
+  for (const warning of warnings) {
+    console.warn(warning)
+  }
+
+  const content = renderModuleFactsJson(factsByModule)
+  const outFile = path.join(resolver.getAppDir(), 'src', 'module-facts.generated.json')
+  const existing = fs.existsSync(outFile) ? fs.readFileSync(outFile, 'utf8') : null
+  if (existing === content) {
+    result.filesUnchanged.push(outFile)
+    return result
+  }
+
+  ensureDir(outFile)
+  fs.writeFileSync(outFile, content)
+  result.filesWritten.push(outFile)
+  logGenerationResult(path.relative(process.cwd(), outFile), true)
+  return result
+}