@open-mercato/cli 0.6.6-develop.6383.1.27fcc83455 → 0.6.6-develop.6385.1.9a81faa5f0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.6-develop.6383.1.27fcc83455",
+  "version": "0.6.6-develop.6385.1.9a81faa5f0",
   "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.6383.1.27fcc83455",
-    "@open-mercato/shared": "0.6.6-develop.6383.1.27fcc83455",
+    "@open-mercato/queue": "0.6.6-develop.6385.1.9a81faa5f0",
+    "@open-mercato/shared": "0.6.6-develop.6385.1.9a81faa5f0",
     "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.6383.1.27fcc83455"
+    "@open-mercato/shared": "0.6.6-develop.6385.1.9a81faa5f0"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.6383.1.27fcc83455",
+    "@open-mercato/shared": "0.6.6-develop.6385.1.9a81faa5f0",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11"

package/src/lib/__integration__/TC-INT-008.spec.ts

@@ -4,6 +4,7 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { MODULE_FACTS_ALLOWLIST } from '../generators/module-facts'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const repoRoot = path.resolve(__dirname, '..', '..', '..', '..', '..')
@@ -15,6 +16,11 @@ const standaloneTemplatePackageJsonPath = path.join(repoRoot, 'packages', 'creat
 const agenticRoot = path.join(repoRoot, 'packages', 'create-app', 'agentic')
 const packagesRoot = path.join(repoRoot, 'packages')
 
+// Modules the standalone fixture enables in src/modules.ts. Both are on the
+// fact-sheet allowlist, so agentic:init must ship exactly their fact-sheets
+// (enabled ∩ allowlist — spec D6) and list them in the AGENTS.md marker block.
+const FIXTURE_ENABLED_MODULES = ['customers', 'sales']
+
 function normalizePath(value: string): string {
   return value.split(path.sep).join('/')
 }
@@ -57,7 +63,8 @@ function createStandaloneFixture(rootDir: string): string {
       2,
     ),
   )
-  writeFile(path.join(appDir, 'src', 'modules.ts'), 'export const enabledModules = []\n')
+  const moduleEntries = FIXTURE_ENABLED_MODULES.map((moduleId) => `  { id: '${moduleId}' },`).join('\n')
+  writeFile(path.join(appDir, 'src', 'modules.ts'), `export const enabledModules = [\n${moduleEntries}\n]\n`)
   return appDir
 }
 
@@ -167,6 +174,17 @@ function readPlaywrightConfigPathFromCliRunner(): string {
 function expectedGuideOutputNames(): string[] {
   const collected = new Set<string>()
 
+  // Static conceptual guides checked into create-app (e.g. module-system.md) are
+  // bundled into dist/agentic/guides by the CLI build and copied wholesale.
+  const staticGuidesRoot = path.join(agenticRoot, 'guides')
+  if (fs.existsSync(staticGuidesRoot)) {
+    for (const entry of fs.readdirSync(staticGuidesRoot, { withFileTypes: true })) {
+      if (entry.isFile() && entry.name.endsWith('.md')) {
+        collected.add(entry.name)
+      }
+    }
+  }
+
   for (const packageName of fs.readdirSync(packagesRoot)) {
     const packageGuide = path.join(packagesRoot, packageName, 'agentic', 'standalone-guide.md')
     if (fs.existsSync(packageGuide)) {
@@ -186,6 +204,21 @@ function expectedGuideOutputNames(): string[] {
     }
   }
 
+  // Generated fact-sheet artifacts (spec 2026-06-27-ts-morph-module-fact-sheets):
+  // the module-facts.json sidecar is copied as-is, fact-sheets are filtered to the
+  // fixture's enabled modules, and every allowlisted module whose hand-written
+  // core.<module>.md guide no longer exists gets a legacy redirect stub.
+  collected.add('module-facts.json')
+  for (const moduleId of FIXTURE_ENABLED_MODULES) {
+    collected.add(normalizePath(path.join('modules', `${moduleId}.md`)))
+  }
+  for (const moduleId of MODULE_FACTS_ALLOWLIST) {
+    const legacyGuideSource = path.join(packagesRoot, 'core', 'src', 'modules', moduleId, 'agentic', 'standalone-guide.md')
+    if (!fs.existsSync(legacyGuideSource)) {
+      collected.add(`core.${moduleId}.md`)
+    }
+  }
+
   return Array.from(collected).sort()
 }
 
@@ -230,6 +263,13 @@ test.describe('TC-INT-008: CLI agentic init mirrors standalone scaffolding asset
       expect(agentsSource).toContain('<!-- CODEX_ENFORCEMENT_RULES_START -->')
       expect(agentsSource).toContain('.ai/guides/core.md')
 
+      // The Module-Specific Guides marker block lists exactly the enabled modules'
+      // fact-sheets (enabled ∩ allowlist), not the full bundled set.
+      for (const moduleId of FIXTURE_ENABLED_MODULES) {
+        expect(agentsSource).toContain(`.ai/guides/modules/${moduleId}.md`)
+      }
+      expect(agentsSource).not.toContain('.ai/guides/modules/auth.md')
+
       const specsReadmeSource = fs.readFileSync(path.join(appDir, '.ai', 'specs', 'README.md'), 'utf8')
       expect(specsReadmeSource).toContain('sample-store')
 

package/src/lib/__tests__/worker-job-handler.test.ts

@@ -1,4 +1,8 @@
 import type { ModuleWorker } from '@open-mercato/shared/modules/registry'
+import {
+  getModuleResourceUsageReport,
+  resetModuleResourceUsage,
+} from '@open-mercato/shared/lib/modules/resource-usage'
 import { createPerJobWorkerHandler, type WorkerJobContainer } from '../worker-job-handler'
 
 type FakeContainer = WorkerJobContainer & {
@@ -32,6 +36,14 @@ function makeWorker(id: string, handler: ModuleWorker['handler']): ModuleWorker
 const baseCtx = { jobId: 'job-1', attemptNumber: 1, queueName: 'test' }
 
 describe('createPerJobWorkerHandler', () => {
+  beforeEach(() => {
+    resetModuleResourceUsage()
+  })
+
+  afterEach(() => {
+    resetModuleResourceUsage()
+  })
+
   it('creates a fresh container for every job invocation', async () => {
     const { factory } = makeContainerFactory()
     const worker = makeWorker('w', jest.fn())
@@ -132,4 +144,20 @@ describe('createPerJobWorkerHandler', () => {
     await expect(handler({ id: 'a' }, baseCtx)).rejects.toBe(boom)
     expect(containers[0].em.clear).toHaveBeenCalledTimes(1)
   })
+
+  it('attributes worker execution to the owning module', async () => {
+    const { factory } = makeContainerFactory()
+    const handler = createPerJobWorkerHandler(
+      [makeWorker('customers:workers:bulk-update', jest.fn())],
+      factory,
+    )
+
+    await handler({ id: 'a' }, baseCtx)
+
+    const report = getModuleResourceUsageReport()
+    expect(report.modules).toHaveLength(1)
+    expect(report.modules[0].moduleId).toBe('customers')
+    expect(report.modules[0].surfaces[0].surface).toBe('worker')
+    expect(report.modules[0].topOperations[0].operation).toBe('customers:workers:bulk-update')
+  })
 })

package/src/lib/agentic-setup.ts

@@ -9,6 +9,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, symlinkSync, lstatSync, unlinkSync, readdirSync } from 'node:fs'
 import { join, dirname, basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { Project, SyntaxKind } from 'ts-morph'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 // In the built output (dist/lib/agentic-setup.js), __dirname is dist/lib/.
@@ -52,14 +53,125 @@ function copyFile(srcDir: string, srcRelative: string, destPath: string): void {
   copyFileSync(srcPath, destPath)
 }
 
+// ─── Module fact-sheet selection (mirrors packages/create-app/src/setup/tools/shared.ts) ──
+
+// AST-parse the static `enabledModules` array literal in the app's src/modules.ts
+// and collect each entry's `id`. Only the static literal is read (conditional
+// .push()/spread entries are intentionally not seen — see spec D6).
+function readEnabledModuleIds(modulesPath: string): string[] {
+  if (!existsSync(modulesPath)) return []
+  try {
+    const project = new Project({ useInMemoryFileSystem: true })
+    const sourceFile = project.createSourceFile('modules.ts', readFileSync(modulesPath, 'utf-8'))
+    const declaration = sourceFile.getVariableDeclaration('enabledModules')
+    const arrayLiteral = declaration?.getInitializerIfKind(SyntaxKind.ArrayLiteralExpression)
+    if (!arrayLiteral) return []
+    const ids: string[] = []
+    for (const element of arrayLiteral.getElements()) {
+      const objectLiteral = element.asKind(SyntaxKind.ObjectLiteralExpression)
+      if (!objectLiteral) continue
+      const idProperty = objectLiteral.getProperty('id')?.asKind(SyntaxKind.PropertyAssignment)
+      const idValue = idProperty?.getInitializerIfKind(SyntaxKind.StringLiteral)?.getLiteralValue()
+      if (idValue) ids.push(idValue)
+    }
+    return ids
+  } catch {
+    return []
+  }
+}
+
+// Resolve which per-module fact-sheets to ship: the intersection of the bundled
+// fact-sheets (the D5 allowlist, materialized by build.mjs) with the app's enabled
+// modules. Falls back to the full bundled set when the enabled set cannot be read
+// (R5 — degraded, never empty).
+function selectModuleFactSheets(targetDir: string, modulesSubdir: string): string[] {
+  const available = existsSync(modulesSubdir)
+    ? readdirSync(modulesSubdir)
+        .filter((file) => file.endsWith('.md'))
+        .map((file) => file.replace(/\.md$/, ''))
+    : []
+  if (available.length === 0) return []
+  const enabled = new Set(readEnabledModuleIds(join(targetDir, 'src', 'modules.ts')))
+  const selected = available.filter((moduleId) => enabled.has(moduleId))
+  return selected.length > 0 ? selected : available
+}
+
+const MODULE_GUIDES_START = '<!-- om:module-guides:start -->'
+const MODULE_GUIDES_END = '<!-- om:module-guides:end -->'
+
+// Read each module's guide label from the bundled `module-facts.json` (emitted by
+// build.mjs from the generator's extraction of each module's own `metadata`). The
+// label falls back description → title → generic, so the CLI never re-declares
+// specific module names or descriptions. A missing/malformed sidecar degrades to an
+// empty map (generic labels), never a throw.
+function readModuleGuideLabels(guidesDir: string): Record<string, string> {
+  const factsPath = join(guidesDir, 'module-facts.json')
+  if (!existsSync(factsPath)) return {}
+  try {
+    const parsed = JSON.parse(readFileSync(factsPath, 'utf-8')) as Record<
+      string,
+      { description?: unknown; title?: unknown }
+    >
+    const labels: Record<string, string> = {}
+    for (const [moduleId, entry] of Object.entries(parsed)) {
+      const label =
+        (entry && typeof entry.description === 'string' && entry.description) ||
+        (entry && typeof entry.title === 'string' && entry.title) ||
+        ''
+      if (label) labels[moduleId] = label
+    }
+    return labels
+  } catch {
+    return {}
+  }
+}
+
+function renderModuleGuidesBlock(selected: string[], labels: Record<string, string>): string {
+  if (selected.length === 0) return '_No module fact-sheets are bundled for this app._'
+  const rows = selected.map((moduleId) => {
+    const label = labels[moduleId] ?? `Use the ${moduleId} module`
+    return `| ${label} | \`.ai/guides/modules/${moduleId}.md\` |`
+  })
+  return ['| Task | Load |', '|---|---|', ...rows].join('\n')
+}
+
+// Regenerate the marker-delimited Module-Specific Guides block in the written
+// AGENTS.md from the selected module set. Replaces strictly between the markers so
+// surrounding prose is untouched and repeat runs are idempotent.
+function injectModuleGuides(
+  agentsMdPath: string,
+  selected: string[],
+  labels: Record<string, string> = {},
+): void {
+  if (!existsSync(agentsMdPath)) return
+  const content = readFileSync(agentsMdPath, 'utf-8')
+  const startIndex = content.indexOf(MODULE_GUIDES_START)
+  const endIndex = content.indexOf(MODULE_GUIDES_END)
+  if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
+    console.warn(
+      `[agentic] Module-Specific Guides markers (${MODULE_GUIDES_START} … ${MODULE_GUIDES_END}) not found in ${agentsMdPath}; the per-module guide list was not generated.`,
+    )
+    return
+  }
+  const before = content.slice(0, startIndex + MODULE_GUIDES_START.length)
+  const after = content.slice(endIndex)
+  const next = `${before}\n${renderModuleGuidesBlock(selected, labels)}\n${after}`
+  if (next !== content) writeFileSync(agentsMdPath, next)
+}
+
 // ─── Generators ──────────────────────────────────────────────────────────
 
 function generateShared(config: AgenticConfig): void {
   const { targetDir } = config
   const srcDir = join(AGENTIC_DIR, 'shared')
 
+  // Resolve which per-module fact-sheets this app gets (enabled ∩ bundled allowlist).
+  const selectedModules = selectModuleFactSheets(targetDir, join(GUIDES_DIR, 'modules'))
+  const moduleGuideLabels = readModuleGuideLabels(GUIDES_DIR)
+
   // AGENTS.md
   writeTemplate(srcDir, 'AGENTS.md.template', join(targetDir, 'AGENTS.md'), config)
+  injectModuleGuides(join(targetDir, 'AGENTS.md'), selectedModules, moduleGuideLabels)
 
   // .ai/ structure
   writeTemplate(srcDir, 'ai/specs/README.md', join(targetDir, '.ai', 'specs', 'README.md'), config)
@@ -244,6 +356,9 @@ function generateShared(config: AgenticConfig): void {
 
   copyFile(srcDir, 'ai/qa/tests/playwright.config.ts', join(targetDir, '.ai', 'qa', 'tests', 'playwright.config.ts'))
 
+  // Package & conceptual guides are copied wholesale (framework-wide). Per-module
+  // fact-sheets (.ai/guides/modules/<module>.md) are filtered to the app's enabled
+  // module set; the combined module-facts.json sidecar is copied as-is.
   if (existsSync(GUIDES_DIR)) {
     const guidesDestDir = join(targetDir, '.ai', 'guides')
     for (const file of readdirSync(GUIDES_DIR)) {
@@ -253,6 +368,20 @@ function generateShared(config: AgenticConfig): void {
       ensureDir(destPath)
       copyFileSync(srcPath, destPath)
     }
+
+    const moduleFactsPath = join(GUIDES_DIR, 'module-facts.json')
+    if (existsSync(moduleFactsPath)) {
+      const destPath = join(guidesDestDir, 'module-facts.json')
+      ensureDir(destPath)
+      copyFileSync(moduleFactsPath, destPath)
+    }
+
+    const modulesSubdir = join(GUIDES_DIR, 'modules')
+    for (const moduleId of selectedModules) {
+      const destPath = join(guidesDestDir, 'modules', `${moduleId}.md`)
+      ensureDir(destPath)
+      copyFileSync(join(modulesSubdir, `${moduleId}.md`), destPath)
+    }
   }
 }
 

package/src/lib/worker-job-handler.ts

@@ -1,5 +1,9 @@
 import type { JobContext, JobHandler } from '@open-mercato/queue'
 import type { ModuleWorker } from '@open-mercato/shared/modules/registry'
+import {
+  inferModuleIdFromResourceId,
+  withModuleResourceUsage,
+} from '@open-mercato/shared/lib/modules/resource-usage'
 
 export type WorkerJobContainer = {
   resolve: <T = unknown>(name: string) => T
@@ -30,7 +34,15 @@ export function createPerJobWorkerHandler(
     const container = await createContainer()
     try {
       for (const worker of workers) {
-        await worker.handler(job, { ...ctx, resolve: container.resolve.bind(container) })
+        await withModuleResourceUsage(
+          {
+            moduleId: worker.moduleId ?? inferModuleIdFromResourceId(worker.id),
+            surface: 'worker',
+            operation: worker.id,
+            resourceId: worker.id,
+          },
+          () => worker.handler(job, { ...ctx, resolve: container.resolve.bind(container) }),
+        )
       }
     } finally {
       try {

package/src/mercato.ts

@@ -66,7 +66,10 @@ function getRegisteredCliWorkers(modules: Module[] = getCliModules()): ModuleWor
   const allWorkers: ModuleWorker[] = []
   for (const mod of modules) {
     if (mod.workers) {
-      allWorkers.push(...mod.workers)
+      allWorkers.push(...mod.workers.map((worker) => ({
+        ...worker,
+        moduleId: worker.moduleId ?? mod.id,
+      })))
     }
   }
   return allWorkers