@open-mercato/cli 0.6.7-develop.6726.1.983ae8a07e → 0.6.7-develop.6749.1.6b54c56dfe

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.7-develop.6726.1.983ae8a07e",
+  "version": "0.6.7-develop.6749.1.6b54c56dfe",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     "@mikro-orm/decorators": "^7.1.5",
     "@mikro-orm/migrations": "^7.1.5",
     "@mikro-orm/postgresql": "^7.1.5",
-    "@open-mercato/queue": "0.6.7-develop.6726.1.983ae8a07e",
-    "@open-mercato/shared": "0.6.7-develop.6726.1.983ae8a07e",
+    "@open-mercato/queue": "0.6.7-develop.6749.1.6b54c56dfe",
+    "@open-mercato/shared": "0.6.7-develop.6749.1.6b54c56dfe",
     "cross-spawn": "^7.0.6",
     "pg": "8.22.0",
     "semver": "^7.8.5",
@@ -72,10 +72,10 @@
     "typescript-js": "npm:typescript@6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.7-develop.6726.1.983ae8a07e"
+    "@open-mercato/shared": "0.6.7-develop.6749.1.6b54c56dfe"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.7-develop.6726.1.983ae8a07e",
+    "@open-mercato/shared": "0.6.7-develop.6749.1.6b54c56dfe",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11"

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

@@ -0,0 +1,119 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { extractModuleFacts, renderModuleFactsMarkdown } from '../module-facts'
+
+function writeFixture(root: string, relativePath: string, source: string): void {
+  const filePath = path.join(root, relativePath)
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, source)
+}
+
+describe('module-facts source-linked extension surfaces', () => {
+  let temporaryRoot: string
+  let moduleRoot: string
+
+  beforeAll(() => {
+    temporaryRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'module-facts-source-links-'))
+    moduleRoot = path.join(temporaryRoot, 'facts')
+    writeFixture(moduleRoot, 'index.ts', "export const metadata = { title: 'Facts' }\n")
+    writeFixture(
+      moduleRoot,
+      'api/records/route.ts',
+      "export const metadata = { path: '/facts/records-custom' }\nexport async function GET() {}\n",
+    )
+    writeFixture(moduleRoot, 'backend/page.tsx', 'export default function FactsPage() { return null }\n')
+    writeFixture(
+      moduleRoot,
+      'backend/facts/items/[id]/page.tsx',
+      'export default function FactItemPage() { return null }\n',
+    )
+    writeFixture(
+      moduleRoot,
+      'frontend/facts/portal/[id]/page.tsx',
+      'export default function FactPortalPage() { return null }\n',
+    )
+    writeFixture(
+      moduleRoot,
+      'cli.ts',
+      "const commands = [{ command: 'facts:sync' }, { command: 'facts:check' }]\nexport default commands\n",
+    )
+    writeFixture(
+      moduleRoot,
+      'ai-tools/tools-pack.ts',
+      "type FactsAiToolDefinition = { name: string; description: string }\nconst inspectTool: FactsAiToolDefinition = { name: 'facts.inspect', description: 'Inspect facts' }\nexport default [inspectTool]\n",
+    )
+    writeFixture(
+      moduleRoot,
+      'ai-tools.ts',
+      "type FactsAiToolDefinition = { name: string; description: string }\nconst listTool: FactsAiToolDefinition = { name: 'facts.list', description: 'List facts' }\nexport const aiTools = [listTool]\nexport default aiTools\n",
+    )
+    writeFixture(
+      moduleRoot,
+      'ai-agents.ts',
+      "type AiAgentDefinition = { id: string; label: string }\nconst AGENT_ID = 'facts.assistant'\nconst agent: AiAgentDefinition = { id: AGENT_ID, label: 'Facts assistant' }\nexport const aiAgents = [agent]\nexport default aiAgents\n",
+    )
+  })
+
+  afterAll(() => {
+    fs.rmSync(temporaryRoot, { recursive: true, force: true })
+  })
+
+  it('emits portable source links for routes, pages, commands, tools, and agents', () => {
+    const registrySource = `export const modules = [{
+      id: 'facts',
+      apis: [{
+        path: '/facts/records-custom',
+        handlers: { GET: async () => undefined },
+        metadata: { GET: { requireFeatures: ['facts.view'] } },
+      }],
+    }]`
+    const facts = extractModuleFacts({
+      moduleId: 'facts',
+      moduleRoot,
+      sourcePackage: '@open-mercato/example',
+      sourceVersion: '1.2.3',
+      registrySource,
+    })
+
+    expect(facts.sourceRoot).toBe('node_modules/@open-mercato/example/src/modules/facts')
+    expect(facts.apiRoutes).toEqual([
+      {
+        path: '/facts/records-custom',
+        methods: ['GET'],
+        auth: { GET: { requireFeatures: ['facts.view'] } },
+        sourcePath: 'node_modules/@open-mercato/example/src/modules/facts/api/records/route.ts',
+      },
+    ])
+    expect(facts.backendPages).toEqual([
+      {
+        path: '/backend/facts',
+        sourcePath: 'node_modules/@open-mercato/example/src/modules/facts/backend/page.tsx',
+      },
+      {
+        path: '/backend/facts/items/[id]',
+        sourcePath: 'node_modules/@open-mercato/example/src/modules/facts/backend/facts/items/[id]/page.tsx',
+      },
+    ])
+    expect(facts.frontendPages).toEqual([
+      {
+        path: '/facts/portal/[id]',
+        sourcePath: 'node_modules/@open-mercato/example/src/modules/facts/frontend/facts/portal/[id]/page.tsx',
+      },
+    ])
+    expect(facts.cli).toEqual(['facts:sync', 'facts:check'])
+    expect(facts.cliCommands.map((command) => command.command)).toEqual(['facts:sync', 'facts:check'])
+    expect(facts.aiTools.map((tool) => tool.name)).toEqual(['facts.inspect', 'facts.list'])
+    expect(facts.aiAgents.map((agentFact) => agentFact.id)).toEqual(['facts.assistant'])
+
+    const markdown = renderModuleFactsMarkdown(facts)
+    expect(markdown).toContain('## Backend pages')
+    expect(markdown).toContain('## Frontend pages')
+    expect(markdown).toContain('## CLI commands')
+    expect(markdown).toContain('## AI tools / MCP capabilities')
+    expect(markdown).toContain('## AI agents')
+    expect(markdown).toContain(
+      '(../../../node_modules/@open-mercato/example/src/modules/facts/api/records/route.ts)',
+    )
+  })
+})

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

@@ -21,6 +21,27 @@ export interface ModuleApiRouteFact {
   path: string
   methods: string[]
   auth: Record<string, ApiRouteAuthRule>
+  sourcePath: string | null
+}
+
+export interface ModulePageFact {
+  path: string
+  sourcePath: string
+}
+
+export interface ModuleCliCommandFact {
+  command: string
+  sourcePath: string
+}
+
+export interface ModuleAiToolFact {
+  name: string
+  sourcePath: string
+}
+
+export interface ModuleAiAgentFact {
+  id: string
+  sourcePath: string
 }
 
 export interface ModuleEventFact {
@@ -42,6 +63,7 @@ export interface ModuleFacts {
   coreVersion: string | null
   sourcePackage: string | null
   sourceVersion: string | null
+  sourceRoot: string
   entities: ModuleEntityFact[]
   events: ModuleEventFact[]
   aclFeatures: string[]
@@ -51,6 +73,11 @@ export interface ModuleFacts {
   hostTokens: ModuleHostTokens
   notifications: string[]
   cli: string[]
+  backendPages: ModulePageFact[]
+  frontendPages: ModulePageFact[]
+  cliCommands: ModuleCliCommandFact[]
+  aiTools: ModuleAiToolFact[]
+  aiAgents: ModuleAiAgentFact[]
   warnings: string[]
 }
 
@@ -495,13 +522,14 @@ function parseApiRouteEntry(entryLiteral: ts.ObjectLiteralExpression): ModuleApi
     }
   }
 
-  return { path: routePath, methods, auth }
+  return { path: routePath, methods, auth, sourcePath: null }
 }
 
 function extractApiRoutes(
   moduleId: string,
   registrySource: string | null,
   registryDescription: string,
+  routeSourcePaths: ReadonlyMap<string, string>,
   warnings: string[],
 ): ModuleApiRouteFact[] {
   if (registrySource == null) {
@@ -529,7 +557,7 @@ function extractApiRoutes(
           const route = parseApiRouteEntry(element)
           if (route && !seenPaths.has(route.path)) {
             seenPaths.add(route.path)
-            routes.push(route)
+            routes.push({ ...route, sourcePath: routeSourcePaths.get(route.path) ?? null })
           }
         }
       }
@@ -717,6 +745,190 @@ function listSourceFilesRecursive(directory: string): string[] {
   return files
 }
 
+function toPortableSourceRoot(moduleId: string, sourcePackage: string | null): string {
+  return path.posix.join('node_modules', sourcePackage ?? '@open-mercato/core', 'src', 'modules', moduleId)
+}
+
+function toPortableSourcePath(moduleRoot: string, sourceRoot: string, filePath: string): string {
+  const relativePath = path.relative(moduleRoot, filePath).split(path.sep).join('/')
+  return path.posix.join(sourceRoot, relativePath)
+}
+
+function sourceHasDefaultExport(sourceFile: ts.SourceFile): boolean {
+  return sourceFile.statements.some((statement) => {
+    if (ts.isExportAssignment(statement) && !statement.isExportEquals) return true
+    if (!ts.isFunctionDeclaration(statement) && !ts.isClassDeclaration(statement)) return false
+    return statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword) ?? false
+  })
+}
+
+function readRouteMetadataPath(sourceFile: ts.SourceFile): string | null {
+  const metadata = findObjectLiteralDeclaration(sourceFile, 'metadata')
+  return metadata ? readStringPropertyInitializer(metadata, 'path') ?? null : null
+}
+
+function extractApiRouteSourcePaths(
+  moduleId: string,
+  moduleRoot: string,
+  sourceRoot: string,
+): Map<string, string> {
+  const apiRoot = path.join(moduleRoot, 'api')
+  const sources = new Map<string, string>()
+  if (!fs.existsSync(apiRoot)) return sources
+  const methodDirectories = new Set(['get', 'post', 'put', 'patch', 'delete'])
+
+  for (const filePath of listSourceFilesRecursive(apiRoot)) {
+    const relativePath = path.relative(apiRoot, filePath).split(path.sep).join('/')
+    const segments = relativePath.split('/')
+    const fileName = segments.pop() as string
+    const fileStem = fileName.replace(/\.tsx?$/, '')
+    let routeSegments: string[]
+    if (fileStem === 'route') {
+      routeSegments = segments
+    } else if (segments[0] && methodDirectories.has(segments[0].toLowerCase())) {
+      routeSegments = [...segments.slice(1), fileStem]
+    } else {
+      routeSegments = [...segments, fileStem]
+    }
+    const defaultPath = `/${[moduleId, ...routeSegments].filter(Boolean).join('/')}`
+    const sourceFile = readSourceFile(filePath)
+    const routePath = sourceFile ? readRouteMetadataPath(sourceFile) ?? defaultPath : defaultPath
+    sources.set(routePath, toPortableSourcePath(moduleRoot, sourceRoot, filePath))
+  }
+  return sources
+}
+
+function extractModulePages(
+  moduleId: string,
+  moduleRoot: string,
+  sourceRoot: string,
+  surface: 'backend' | 'frontend',
+): ModulePageFact[] {
+  const pageRoot = path.join(moduleRoot, surface)
+  if (!fs.existsSync(pageRoot)) return []
+  const pages: ModulePageFact[] = []
+  const seen = new Set<string>()
+
+  for (const filePath of listSourceFilesRecursive(pageRoot)) {
+    if (!filePath.endsWith('.tsx')) continue
+    const relativePath = path.relative(pageRoot, filePath).split(path.sep).join('/')
+    const segments = relativePath.split('/')
+    const fileName = segments.pop() as string
+    const fileStem = fileName.replace(/\.tsx$/, '')
+    const isModernPage = fileStem === 'page'
+    if (!isModernPage && (fileStem.endsWith('.meta') || /^[A-Z]/.test(fileStem))) continue
+    const sourceFile = readSourceFile(filePath)
+    if (!sourceFile || !sourceHasDefaultExport(sourceFile)) continue
+    const routeSegments = isModernPage ? segments : [...segments, fileStem]
+    const routePath = surface === 'frontend'
+      ? `/${routeSegments.filter(Boolean).join('/')}`
+      : isModernPage
+        ? `/backend/${routeSegments.join('/') || moduleId}`
+        : `/backend/${routeSegments[0] === moduleId
+            ? routeSegments.filter(Boolean).join('/')
+            : [moduleId, ...routeSegments].filter(Boolean).join('/')}`
+    if (seen.has(routePath)) continue
+    seen.add(routePath)
+    pages.push({
+      path: routePath,
+      sourcePath: toPortableSourcePath(moduleRoot, sourceRoot, filePath),
+    })
+  }
+  return pages.sort((left, right) => left.path.localeCompare(right.path))
+}
+
+function findAncestorVariableDeclaration(node: ts.Node): ts.VariableDeclaration | null {
+  let current: ts.Node | undefined = node.parent
+  while (current) {
+    if (ts.isVariableDeclaration(current)) return current
+    current = current.parent
+  }
+  return null
+}
+
+function findAncestorCallExpression(node: ts.Node): ts.CallExpression | null {
+  let current: ts.Node | undefined = node.parent
+  while (current) {
+    if (ts.isCallExpression(current)) return current
+    if (ts.isVariableDeclaration(current) || ts.isStatement(current)) return null
+    current = current.parent
+  }
+  return null
+}
+
+function extractNamedAiFacts(
+  filePaths: readonly string[],
+  moduleRoot: string,
+  sourceRoot: string,
+  propertyName: 'name' | 'id',
+): Array<{ value: string; sourcePath: string }> {
+  const facts: Array<{ value: string; sourcePath: string }> = []
+  const seen = new Set<string>()
+  for (const filePath of filePaths) {
+    const sourceFile = readSourceFile(filePath)
+    if (!sourceFile) continue
+    const initializers = buildVariableInitializerMap(sourceFile)
+    const readDefinitionValue = (objectLiteral: ts.ObjectLiteralExpression): string | undefined => {
+      const initializer = getObjectPropertyInitializer(objectLiteral, propertyName)
+      if (!initializer) return undefined
+      const resolved = unwrapExpression(initializer)
+      if (ts.isStringLiteralLike(resolved)) return resolved.text
+      if (ts.isIdentifier(resolved)) {
+        const declarationInitializer = initializers.get(resolved.text)
+        if (declarationInitializer) {
+          const declarationValue = unwrapExpression(declarationInitializer)
+          if (ts.isStringLiteralLike(declarationValue)) return declarationValue.text
+        }
+      }
+      return undefined
+    }
+    const visit = (node: ts.Node): void => {
+      if (ts.isObjectLiteralExpression(node)) {
+        const value = readDefinitionValue(node)
+        if (value && !seen.has(value)) {
+          const declaration = findAncestorVariableDeclaration(node)
+          const declarationName = declaration && ts.isIdentifier(declaration.name) ? declaration.name.text : ''
+          const declarationType = declaration?.type?.getText(sourceFile) ?? ''
+          const call = findAncestorCallExpression(node)
+          const callee = call?.expression.getText(sourceFile) ?? ''
+          const isDefinition = propertyName === 'name'
+            ? /AiTool/.test(declarationType) || /tool$/i.test(declarationName) || /AiTool/.test(callee)
+            : /AiAgentDefinition/.test(declarationType) || /agent$/i.test(declarationName) || /defineAiAgent/.test(callee)
+          if (isDefinition) {
+            seen.add(value)
+            facts.push({
+              value,
+              sourcePath: toPortableSourcePath(moduleRoot, sourceRoot, filePath),
+            })
+          }
+        }
+      }
+      node.forEachChild(visit)
+    }
+    sourceFile.forEachChild(visit)
+  }
+  return facts.sort((left, right) => left.value.localeCompare(right.value))
+}
+
+function extractAiTools(moduleRoot: string, sourceRoot: string): ModuleAiToolFact[] {
+  const files = new Set<string>()
+  const rootFile = resolveConventionFile(moduleRoot, 'ai-tools')
+  if (rootFile) files.add(rootFile)
+  const toolsDirectory = path.join(moduleRoot, 'ai-tools')
+  if (fs.existsSync(toolsDirectory)) {
+    for (const filePath of listSourceFilesRecursive(toolsDirectory)) files.add(filePath)
+  }
+  return extractNamedAiFacts([...files], moduleRoot, sourceRoot, 'name')
+    .map((fact) => ({ name: fact.value, sourcePath: fact.sourcePath }))
+}
+
+function extractAiAgents(moduleRoot: string, sourceRoot: string): ModuleAiAgentFact[] {
+  const agentsFile = resolveConventionFile(moduleRoot, 'ai-agents')
+  if (!agentsFile) return []
+  return extractNamedAiFacts([agentsFile], moduleRoot, sourceRoot, 'id')
+    .map((fact) => ({ id: fact.value, sourcePath: fact.sourcePath }))
+}
+
 function extractTableIds(moduleRoot: string): string[] {
   if (!fs.existsSync(moduleRoot)) return []
 
@@ -780,6 +992,7 @@ export function extractModuleFacts(options: ExtractModuleFactsOptions): ModuleFa
   if (!moduleRoot) {
     throw new Error(`[internal] extractModuleFacts requires moduleRoot or coreSrcRoot for module "${moduleId}"`)
   }
+  const sourceRoot = toPortableSourceRoot(moduleId, sourcePackage)
 
   const entitiesFilePath =
     resolveConventionFile(path.join(moduleRoot, 'data'), 'entities') ??
@@ -802,11 +1015,22 @@ export function extractModuleFacts(options: ExtractModuleFactsOptions): ModuleFa
   const aclFeatures = extractAclFeatures(aclFilePath)
 
   const { source: registrySource, description: registryDescription } = resolveRegistrySource(options)
-  const apiRoutes = extractApiRoutes(moduleId, registrySource, registryDescription, warnings)
+  const apiRouteSourcePaths = extractApiRouteSourcePaths(moduleId, moduleRoot, sourceRoot)
+  const apiRoutes = extractApiRoutes(moduleId, registrySource, registryDescription, apiRouteSourcePaths, warnings)
   const diTokens = extractDiTokens(diFilePath)
   const searchEntities = extractSearchEntities(searchFilePath, warnings)
   const notifications = extractNotifications(notificationsFilePath, warnings)
   const cli = extractCli(cliFilePath, warnings)
+  const cliCommands = cliFilePath
+    ? cli.map((command) => ({
+        command,
+        sourcePath: toPortableSourcePath(moduleRoot, sourceRoot, cliFilePath),
+      }))
+    : []
+  const backendPages = extractModulePages(moduleId, moduleRoot, sourceRoot, 'backend')
+  const frontendPages = extractModulePages(moduleId, moduleRoot, sourceRoot, 'frontend')
+  const aiTools = extractAiTools(moduleRoot, sourceRoot)
+  const aiAgents = extractAiAgents(moduleRoot, sourceRoot)
   const hostTokens: ModuleHostTokens = {
     entityIds: extractHostEntityIds(entities),
     tableIds: extractTableIds(moduleRoot),
@@ -819,6 +1043,7 @@ export function extractModuleFacts(options: ExtractModuleFactsOptions): ModuleFa
     coreVersion,
     sourcePackage,
     sourceVersion,
+    sourceRoot,
     entities,
     events,
     aclFeatures,
@@ -828,6 +1053,11 @@ export function extractModuleFacts(options: ExtractModuleFactsOptions): ModuleFa
     hostTokens,
     notifications,
     cli,
+    backendPages,
+    frontendPages,
+    cliCommands,
+    aiTools,
+    aiAgents,
     warnings,
   }
 }
@@ -844,6 +1074,7 @@ export interface ModuleFactsJsonEntry {
   coreVersion: string | null
   sourcePackage: string | null
   sourceVersion: string | null
+  sourceRoot: string
   entities: ModuleEntityFact[]
   events: ModuleFactsJsonEvent[]
   aclFeatures: string[]
@@ -853,6 +1084,11 @@ export interface ModuleFactsJsonEntry {
   hostTokens: ModuleHostTokens
   notifications: string[]
   cli: string[]
+  backendPages: ModulePageFact[]
+  frontendPages: ModulePageFact[]
+  cliCommands: ModuleCliCommandFact[]
+  aiTools: ModuleAiToolFact[]
+  aiAgents: ModuleAiAgentFact[]
 }
 
 const EMPTY_SECTION_MARKER = '_none_'
@@ -894,6 +1130,10 @@ function renderInlineListSection(heading: string, values: string[]): string {
   return `${heading}\n\n${values.join(' · ')}`
 }
 
+function renderSourceLink(sourcePath: string): string {
+  return `[${sourcePath}](../../../${sourcePath})`
+}
+
 function describeAuthRule(rule: ApiRouteAuthRule | undefined): string {
   if (!rule) return 'public'
   if (rule.requireFeatures && rule.requireFeatures.length > 0) return rule.requireFeatures.join(', ')
@@ -916,14 +1156,23 @@ function renderApiRouteAuthCell(route: ModuleApiRouteFact): string {
 
 function renderApiRoutesSection(routes: ModuleApiRouteFact[]): string {
   if (routes.length === 0) return `## API routes\n\n${EMPTY_SECTION_MARKER}`
-  const header = '| Path | Methods | Auth (per-method requireFeatures) |'
-  const divider = '|---|---|---|'
+  const header = '| Path | Methods | Auth (per-method requireFeatures) | Source |'
+  const divider = '|---|---|---|---|'
   const rows = routes.map(
-    (route) => `| ${route.path} | ${route.methods.join(' ')} | ${renderApiRouteAuthCell(route)} |`,
+    (route) => `| ${route.path} | ${route.methods.join(' ')} | ${renderApiRouteAuthCell(route)} | ${route.sourcePath ? renderSourceLink(route.sourcePath) : '—'} |`,
   )
   return ['## API routes', '', header, divider, ...rows].join('\n')
 }
 
+function renderLinkedFactsSection(
+  heading: string,
+  facts: ReadonlyArray<{ label: string; sourcePath: string }>,
+): string {
+  if (facts.length === 0) return `${heading}\n\n${EMPTY_SECTION_MARKER}`
+  const rows = facts.map((fact) => `| ${fact.label} | ${renderSourceLink(fact.sourcePath)} |`)
+  return [heading, '', '| ID / path | Source |', '|---|---|', ...rows].join('\n')
+}
+
 function renderHostTokensSection(hostTokens: ModuleHostTokens): string {
   const entityIdsLine = hostTokens.entityIds.length > 0 ? hostTokens.entityIds.join(' · ') : EMPTY_SECTION_MARKER
   const tableIdsLine = hostTokens.tableIds.length > 0 ? hostTokens.tableIds.join(' · ') : EMPTY_SECTION_MARKER
@@ -934,6 +1183,7 @@ export function renderModuleFactsMarkdown(facts: ModuleFacts): string {
   const sections = [
     `# ${facts.module} — module facts (generated, do not edit)`,
     renderVersionStamp(facts.coreVersion, facts.sourcePackage, facts.sourceVersion),
+    `Source root: ${renderSourceLink(facts.sourceRoot)}`,
     '',
     renderEntitiesSection(facts.entities),
     '',
@@ -943,6 +1193,10 @@ export function renderModuleFactsMarkdown(facts: ModuleFacts): string {
     '',
     renderApiRoutesSection(facts.apiRoutes),
     '',
+    renderLinkedFactsSection('## Backend pages', facts.backendPages.map((page) => ({ label: page.path, sourcePath: page.sourcePath }))),
+    '',
+    renderLinkedFactsSection('## Frontend pages', facts.frontendPages.map((page) => ({ label: page.path, sourcePath: page.sourcePath }))),
+    '',
     renderInlineListSection('## DI service tokens', facts.diTokens),
     '',
     renderInlineListSection('## Search entities', facts.searchEntities),
@@ -951,7 +1205,11 @@ export function renderModuleFactsMarkdown(facts: ModuleFacts): string {
     '',
     renderInlineListSection('## Notifications', facts.notifications),
     '',
-    renderInlineListSection('## CLI', facts.cli),
+    renderLinkedFactsSection('## CLI commands', facts.cliCommands.map((command) => ({ label: command.command, sourcePath: command.sourcePath }))),
+    '',
+    renderLinkedFactsSection('## AI tools / MCP capabilities', facts.aiTools.map((tool) => ({ label: tool.name, sourcePath: tool.sourcePath }))),
+    '',
+    renderLinkedFactsSection('## AI agents', facts.aiAgents.map((agent) => ({ label: agent.id, sourcePath: agent.sourcePath }))),
     '',
   ]
   return sections.join('\n')
@@ -964,6 +1222,7 @@ export function toModuleFactsJsonEntry(facts: ModuleFacts): ModuleFactsJsonEntry
     coreVersion: facts.coreVersion,
     sourcePackage: facts.sourcePackage,
     sourceVersion: facts.sourceVersion,
+    sourceRoot: facts.sourceRoot,
     entities: facts.entities,
     events: facts.events.map((event) => ({ id: event.id, category: event.category, entity: event.entity })),
     aclFeatures: facts.aclFeatures,
@@ -973,6 +1232,11 @@ export function toModuleFactsJsonEntry(facts: ModuleFacts): ModuleFactsJsonEntry
     hostTokens: facts.hostTokens,
     notifications: facts.notifications,
     cli: facts.cli,
+    backendPages: facts.backendPages,
+    frontendPages: facts.frontendPages,
+    cliCommands: facts.cliCommands,
+    aiTools: facts.aiTools,
+    aiAgents: facts.aiAgents,
   }
 }
 

package/src/lib/generators/module-registry.ts

@@ -224,6 +224,8 @@ type SerializableWorkerMetadata = {
   id?: string
   queue?: string
   concurrency?: number
+  lockDuration?: number
+  maxStalledCount?: number
 }
 
 type PageMetadataManifestLoadResult = {
@@ -1553,6 +1555,8 @@ function normalizeWorkerMetadata(raw: unknown): SerializableWorkerMetadata | nul
   if (typeof source.id === 'string' && source.id.length > 0) normalized.id = source.id
   if (typeof source.queue === 'string' && source.queue.length > 0) normalized.queue = source.queue
   if (typeof source.concurrency === 'number') normalized.concurrency = source.concurrency
+  if (typeof source.lockDuration === 'number') normalized.lockDuration = source.lockDuration
+  if (typeof source.maxStalledCount === 'number') normalized.maxStalledCount = source.maxStalledCount
   return Object.keys(normalized).length > 0 ? normalized : null
 }
 
@@ -2055,7 +2059,7 @@ function processWorkers(discovered: DiscoveredWorker[]): string[] {
   for (const { id, importPath, metadata } of discovered) {
     const workerId = metadata.id ?? id
     workers.push(
-      `{ id: ${toLiteral(workerId)}, queue: ${toLiteral(metadata.queue)}, concurrency: ${toLiteral(metadata.concurrency ?? 1)}, handler: createLazyModuleWorker(() => ${buildDynamicImportExpression(importPath)}, ${toLiteral(workerId)}) }`
+      `{ id: ${toLiteral(workerId)}, queue: ${toLiteral(metadata.queue)}, concurrency: ${toLiteral(metadata.concurrency ?? 1)}${metadata.lockDuration === undefined ? '' : `, lockDuration: ${toLiteral(metadata.lockDuration)}`}${metadata.maxStalledCount === undefined ? '' : `, maxStalledCount: ${toLiteral(metadata.maxStalledCount)}`}, handler: createLazyModuleWorker(() => ${buildDynamicImportExpression(importPath)}, ${toLiteral(workerId)}) }`
     )
   }
   return workers
@@ -2730,6 +2734,8 @@ function processWorkersAst(discovered: DiscoveredWorker[]): WriterFunction[] {
         { name: 'id', value: workerId },
         { name: 'queue', value: metadata.queue },
         { name: 'concurrency', value: metadata.concurrency ?? 1 },
+        ...(metadata.lockDuration === undefined ? [] : [{ name: 'lockDuration', value: metadata.lockDuration }]),
+        ...(metadata.maxStalledCount === undefined ? [] : [{ name: 'maxStalledCount', value: metadata.maxStalledCount }]),
         {
           name: 'handler',
           value: callExpression(identifier('createLazyModuleWorker'), [

package/src/mercato.ts

@@ -1654,6 +1654,8 @@ export async function run(argv = process.argv) {
                 effectiveByQueue.get(queue) ??
                 concurrencyOverride ??
                 Math.max(...queueWorkers.map((w) => w.concurrency), 1)
+              const maxStalledCount = Math.max(...queueWorkers.map((w) => w.maxStalledCount ?? 1), 1)
+              const lockDuration = Math.max(...queueWorkers.map((w) => w.lockDuration ?? 0), 0) || undefined
 
               console.log(`[worker] Starting "${queue}" with ${queueWorkers.length} handler(s), concurrency: ${concurrency}`)
 
@@ -1662,6 +1664,8 @@ export async function run(argv = process.argv) {
                 queueName: queue,
                 connection: queueRedisUrl ? { url: queueRedisUrl } : undefined,
                 concurrency,
+                lockDuration,
+                maxStalledCount,
                 background: true,
                 handler: createPerJobWorkerHandler(queueWorkers, createRequestContainer),
               })
@@ -1705,6 +1709,8 @@ export async function run(argv = process.argv) {
               // never check out more pooled connections than the worker pool holds.
               const budgetPlan = await resolveWorkerBudgetPlan([{ queue: queueName!, concurrency: requested }])
               const concurrency = budgetPlan.entries[0]?.effective ?? requested
+              const maxStalledCount = Math.max(...queueWorkers.map((w) => w.maxStalledCount ?? 1), 1)
+              const lockDuration = Math.max(...queueWorkers.map((w) => w.lockDuration ?? 0), 0) || undefined
 
               console.log(`[worker] Found ${queueWorkers.length} worker(s) for queue "${queueName}"`)
 
@@ -1713,6 +1719,8 @@ export async function run(argv = process.argv) {
                 queueName: queueName!,
                 connection: queueRedisUrl ? { url: queueRedisUrl } : undefined,
                 concurrency,
+                lockDuration,
+                maxStalledCount,
                 handler: createPerJobWorkerHandler(queueWorkers, createRequestContainer),
               })
             } else {