@open-mercato/cli 0.10.1-develop.7990.1.82d0a183c5 → 0.10.1-develop.7994.1.c9f31972aa

package/src/lib/module-package.ts

@@ -1,13 +1,18 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { createRequire } from 'node:module'
+import ts from 'typescript-js'
 import type { PackageResolver } from './resolver'
+import { normalizeModuleLocator } from '@open-mercato/shared/modules/module-locators'
+import { sourceHasDefaultExport, sourceExportedHttpMethods } from './generators/source-exports'
+import { MODULE_CODE_EXTENSIONS, SCAN_CONFIGS, stripModuleCodeExtension, type ScanConfig } from './generators/scanner'
 
 type PackageJsonRecord = {
   name?: string
   version?: string
   dependencies?: Record<string, string>
   peerDependencies?: Record<string, string>
+  exports?: unknown
 }
 
 export type ModulePackageMetadata = {
@@ -18,6 +23,8 @@ export type ModulePackageMetadata = {
 export type ModuleInfoSnapshot = {
   title?: string
   description?: string
+  requires?: string[]
+  locator?: string
 }
 
 export type ValidatedOfficialModulePackage = {
@@ -54,20 +61,94 @@ function readPackageJson(packageJsonPath: string): PackageJsonRecord {
   }
 }
 
-function parseModuleInfo(indexPath: string): { title?: string; description?: string; ejectable?: boolean } {
-  if (!fs.existsSync(indexPath)) return {}
+function readPropertyName(property: ts.ObjectLiteralElementLike): string | null {
+  if (!('name' in property) || !property.name) return null
+  return ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)
+    ? property.name.text
+    : null
+}
+
+function unwrapExpression(expression: ts.Expression): ts.Expression {
+  if (
+    ts.isAsExpression(expression)
+    || ts.isTypeAssertionExpression(expression)
+    || ts.isParenthesizedExpression(expression)
+    || ts.isSatisfiesExpression(expression)
+  ) {
+    return unwrapExpression(expression.expression)
+  }
+  return expression
+}
+
+function findMetadataLiteral(source: string, indexPath: string): ts.ObjectLiteralExpression | null {
+  const sourceFile = ts.createSourceFile(indexPath, source, ts.ScriptTarget.Latest, true)
+  for (const statement of sourceFile.statements) {
+    if (!ts.isVariableStatement(statement)) continue
+    for (const declaration of statement.declarationList.declarations) {
+      if (
+        !ts.isIdentifier(declaration.name)
+        || declaration.name.text !== 'metadata'
+        || !declaration.initializer
+      ) continue
+      const initializer = unwrapExpression(declaration.initializer)
+      if (ts.isObjectLiteralExpression(initializer)) return initializer
+    }
+  }
+  return null
+}
+
+function parseModuleInfo(indexPath: string, validateRequires = false): {
+  title?: string
+  description?: string
+  ejectable?: boolean
+  locator?: string
+  requires: string[]
+} {
+  if (!fs.existsSync(indexPath)) return { requires: [] }
 
   const source = fs.readFileSync(indexPath, 'utf8')
-  const result: { title?: string; description?: string; ejectable?: boolean } = {}
+  const metadata = findMetadataLiteral(source, indexPath)
+  const result: { title?: string; description?: string; ejectable?: boolean; locator?: string; requires: string[] } = {
+    requires: [],
+  }
+  if (!metadata) return result
 
-  const titleMatch = source.match(/\btitle\s*:\s*['"]([^'"]+)['"]/)
-  if (titleMatch) result.title = titleMatch[1]
+  for (const property of metadata.properties) {
+    const propertyName = readPropertyName(property)
+    if (!ts.isPropertyAssignment(property)) {
+      if (validateRequires && propertyName === 'requires') {
+        throw new Error(`Module descriptor at ${indexPath} must declare "requires" as a static string array.`)
+      }
+      continue
+    }
+    const initializer = unwrapExpression(property.initializer)
 
-  const descriptionMatch = source.match(/\bdescription\s*:\s*['"]([^'"]+)['"]/)
-  if (descriptionMatch) result.description = descriptionMatch[1]
+    if ((propertyName === 'title' || propertyName === 'description' || propertyName === 'locator') && ts.isStringLiteralLike(initializer)) {
+      result[propertyName] = initializer.text
+      continue
+    }
 
-  const ejectableMatch = source.match(/\bejectable\s*:\s*(true|false)/)
-  if (ejectableMatch) result.ejectable = ejectableMatch[1] === 'true'
+    if (propertyName === 'ejectable') {
+      if (initializer.kind === ts.SyntaxKind.TrueKeyword) result.ejectable = true
+      if (initializer.kind === ts.SyntaxKind.FalseKeyword) result.ejectable = false
+      continue
+    }
+
+    if (propertyName !== 'requires') continue
+    if (!ts.isArrayLiteralExpression(initializer)) {
+      if (validateRequires) {
+        throw new Error(`Module descriptor at ${indexPath} must declare "requires" as a static string array.`)
+      }
+      continue
+    }
+    if (initializer.elements.some((element) => !ts.isStringLiteralLike(element))) {
+      if (validateRequires) {
+        throw new Error(`Module descriptor at ${indexPath} must contain only string module ids in "requires".`)
+      }
+      continue
+    }
+    result.requires = initializer.elements.map((element) => (element as ts.StringLiteralLike).text)
+  }
 
   return result
 }
@@ -175,7 +256,6 @@ function collectBoundaryViolations(moduleDir: string): string[] {
 
 function findResolvedPackageRoot(
   resolvedPath: string,
-  packageName: string,
 ): string | null {
   let currentPath = fs.statSync(resolvedPath).isDirectory()
     ? resolvedPath
@@ -185,7 +265,7 @@ function findResolvedPackageRoot(
     const packageJsonPath = path.join(currentPath, 'package.json')
     if (fs.existsSync(packageJsonPath)) {
       const packageJson = readPackageJson(packageJsonPath)
-      if (packageJson.name === packageName) {
+      if (typeof packageJson.name === 'string' && normalizeModuleLocator(`npm:${packageJson.name}`) === `npm:${packageJson.name}`) {
         return currentPath
       }
     }
@@ -195,7 +275,7 @@ function findResolvedPackageRoot(
   return null
 }
 
-function resolveInstalledPackageRootWithRequire(packageName: string, appDir: string): string | null {
+export function resolveInstalledPackageRootWithRequire(packageName: string, appDir: string): string | null {
   const specifiers = [`${packageName}/package.json`, packageName]
 
   for (const specifier of specifiers) {
@@ -205,7 +285,7 @@ function resolveInstalledPackageRootWithRequire(packageName: string, appDir: str
       })
       const packageRoot =
         specifier === packageName
-          ? findResolvedPackageRoot(resolvedPath, packageName)
+          ? findResolvedPackageRoot(resolvedPath)
           : path.dirname(resolvedPath)
 
       if (packageRoot) {
@@ -258,6 +338,130 @@ export function resolveInstalledPackageRoot(
   throw new Error(`Package "${packageName}" is not installed in ${resolver.getAppDir()}.`)
 }
 
+function resolveEsmExportTarget(value: unknown, substitution?: string): string | null | undefined {
+  if (typeof value === 'string') {
+    const target = substitution === undefined ? value : value.replaceAll('*', substitution)
+    if (!target.startsWith('./') || target.slice(2).split('/').some((segment) => ['..', '.', 'node_modules'].includes(segment))) return undefined
+    return target
+  }
+  if (value === null) return null
+  if (Array.isArray(value)) {
+    for (const candidate of value) {
+      const target = resolveEsmExportTarget(candidate, substitution)
+      if (target !== undefined && target !== null) return target
+    }
+    return null
+  }
+  if (value && typeof value === 'object') {
+    for (const [condition, candidate] of Object.entries(value)) {
+      if (!['import', 'node', 'node-addons', 'module-sync', 'default'].includes(condition)) continue
+      const target = resolveEsmExportTarget(candidate, substitution)
+      if (target !== undefined) return target
+    }
+  }
+  return undefined
+}
+
+function resolvePackageSubpathExport(exports: unknown, subpath: string): string | null | undefined {
+  if (!exports || typeof exports !== 'object' || Array.isArray(exports)) return undefined
+  const entries = Object.entries(exports)
+  const direct = entries.find(([key]) => key === subpath)
+  if (direct) return resolveEsmExportTarget(direct[1])
+  const patterns = entries.filter(([key]) => key.startsWith('./') && key.includes('*'))
+    .sort(([left], [right]) => right.indexOf('*') - left.indexOf('*') || right.length - left.length)
+  for (const [pattern, target] of patterns) {
+    const wildcard = pattern.indexOf('*')
+    const prefix = pattern.slice(0, wildcard)
+    const suffix = pattern.slice(wildcard + 1)
+    if (subpath.startsWith(prefix) && subpath.endsWith(suffix) && subpath.length >= prefix.length + suffix.length) {
+      return resolveEsmExportTarget(target, subpath.slice(prefix.length, subpath.length - suffix.length))
+    }
+  }
+  return undefined
+}
+
+function isGeneratedModuleImport(relativePath: string, moduleFiles: readonly string[], readSource?: (relativePath: string) => string): boolean {
+  const segments = relativePath.split('/')
+  if (segments.some((segment) => segment === '__tests__' || segment === '__mocks__')) return false
+  const fileName = segments[segments.length - 1]
+  if (fileName.endsWith('.d.ts') || /\.(?:test|spec)\.[jt]sx?$/.test(fileName)) return false
+  const basename = stripModuleCodeExtension(fileName)
+  if (segments.length === 1) {
+    return new Set(['index', 'acl', 'setup', 'cli', 'runtime', 'ce', 'search', 'events', 'notifications', 'notifications.client', 'notifications.handlers', 'translations', 'encryption', 'ai-tools', 'ai-agents', 'di', 'integration', 'vector']).has(basename)
+  }
+  if (['widgets/components', 'widgets/injection-table', 'api/interceptors', 'data/extensions', 'data/fields'].includes(stripModuleCodeExtension(relativePath))) return true
+  if (/^commands\//.test(relativePath)) {
+    return MODULE_CODE_EXTENSIONS.some((extension) => fileName.endsWith(extension)) && !['index', 'shared', 'factory'].includes(basename)
+  }
+  const scanConfigs: readonly ScanConfig[] = Object.values(SCAN_CONFIGS)
+  for (const config of scanConfigs) {
+    if (!relativePath.startsWith(`${config.folder}/`)) continue
+    const relativeSegments = relativePath.slice(config.folder.length + 1).split('/')
+    if (relativeSegments.slice(0, -1).some((segment) => config.skipDirs?.(segment))) continue
+    if (!config.include(fileName)) continue
+    if (config.folder === 'frontend' || config.folder === 'backend') return readSource ? sourceHasDefaultExport(relativePath, readSource(relativePath)) : false
+    if (config.folder === 'api') return readSource ? sourceExportedHttpMethods(readSource(relativePath)).length > 0 : false
+    return true
+  }
+  if (/^(?:frontend|backend)\//.test(relativePath) && (basename === 'meta' || basename.endsWith('.meta'))) {
+    const folder = segments.slice(0, -1).join('/')
+    const pageConfig = segments[0] === 'frontend' ? SCAN_CONFIGS.frontendPages : SCAN_CONFIGS.backendPages
+    const candidates = moduleFiles.filter((file) => file.startsWith(`${folder}/`) && !file.slice(folder.length + 1).includes('/') && pageConfig.include(path.posix.basename(file)))
+    return candidates.some((candidate) => (basename === 'meta' || basename === `${stripModuleCodeExtension(path.posix.basename(candidate))}.meta`) && Boolean(readSource && sourceHasDefaultExport(candidate, readSource(candidate))))
+  }
+  if (/^(?:data|db)\/(?:entities\.override|entities|schema)\.[jt]sx?$/.test(relativePath)) {
+    const selected = ['data', 'db'].flatMap((folder) => ['entities.override', 'entities', 'schema'].flatMap((candidate) => MODULE_CODE_EXTENSIONS.map((extension) => `${folder}/${candidate}${extension}`)))
+      .find((candidate) => moduleFiles.includes(candidate))
+    return relativePath === selected
+  }
+  return /^i18n\/[^/]+\.json$/.test(relativePath)
+}
+
+export function isModulePackageExportError(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'MODULE_PACKAGE_EXPORT_UNAVAILABLE'
+}
+
+export function assertModulePackageExports(
+  manifest: { exports?: unknown },
+  binding: string,
+  moduleId: string,
+  packageFiles: readonly string[],
+  readSource?: (relativePath: string) => string,
+): void {
+  const normalizedFiles = new Set(packageFiles.map((file) => file.replaceAll('\\', '/').replace(/^\.\//, '')))
+  const sourcePrefix = `src/modules/${moduleId}/`
+  const distPrefix = `dist/modules/${moduleId}/`
+  const sourceFiles = [...normalizedFiles].filter((file) => file.startsWith(sourcePrefix)).map((file) => file.slice(sourcePrefix.length))
+  const distFiles = [...normalizedFiles].filter((file) => file.startsWith(distPrefix)).map((file) => file.slice(distPrefix.length))
+  const moduleFiles = sourceFiles.length > 0 ? sourceFiles : distFiles
+  const cachedSources = new Map<string, string>()
+  const readModuleSource = readSource ? (relativePath: string): string => {
+    let source = cachedSources.get(relativePath)
+    if (source === undefined) {
+      source = readSource(`${sourceFiles.length > 0 ? sourcePrefix : distPrefix}${relativePath}`)
+      cachedSources.set(relativePath, source)
+    }
+    return source
+  } : undefined
+  const generatedCandidates = sourceFiles.length > 0 ? sourceFiles : distFiles
+  for (const sourcePath of generatedCandidates) {
+    if (!isGeneratedModuleImport(sourcePath, moduleFiles, readModuleSource)) continue
+    const isCode = /\.[jt]sx?$/.test(sourcePath)
+    const runtimePath = sourceFiles.length > 0 && isCode
+      ? distFiles.find((file) => /\.jsx?$/.test(file) && stripModuleCodeExtension(file) === stripModuleCodeExtension(sourcePath))
+      : sourcePath
+    const publicPath = `./modules/${moduleId}/${stripModuleCodeExtension(sourcePath)}`
+    if (!runtimePath) {
+      throw Object.assign(new Error(`Package binding "${binding}" cannot import "${binding}/${publicPath.slice(2)}": the package artifact is missing the compiled runtime entrypoint. Build the package before enabling it.`), { code: 'MODULE_PACKAGE_EXPORT_UNAVAILABLE' })
+    }
+    if (manifest.exports === undefined) continue
+    const target = resolvePackageSubpathExport(manifest.exports, publicPath)
+    if (!target || !normalizedFiles.has(target.slice(2))) {
+      throw Object.assign(new Error(`Package binding "${binding}" cannot import "${binding}/${publicPath.slice(2)}": the package exports do not provide an available ESM target. Keep the current provider and use a package exposing this module subpath before enabling it.`), { code: 'MODULE_PACKAGE_EXPORT_UNAVAILABLE' })
+    }
+  }
+}
+
 export function readOfficialModulePackageFromRoot(
   packageRoot: string,
   expectedPackageName?: string,
@@ -274,6 +478,10 @@ export function readOfficialModulePackageFromRoot(
     throw new Error(`Package manifest at ${packageJsonPath} is missing the "name" field.`)
   }
 
+  if (typeof packageName !== 'string' || normalizeModuleLocator(`npm:${packageName}`) !== `npm:${packageName}`) {
+    throw new Error(`Package manifest at ${packageJsonPath} has an invalid "name" field.`)
+  }
+
   if (expectedPackageName && packageName !== expectedPackageName) {
     throw new Error(`Resolved package "${packageName}" does not match requested package "${expectedPackageName}".`)
   }
@@ -317,26 +525,45 @@ export function readOfficialModulePackageFromRoot(
     throw new Error(`Package "${packageName}" is missing dist/modules/${moduleId}.`)
   }
 
-  const info = parseModuleInfo(path.join(sourceModuleDir, 'index.ts'))
+  const info = parseModuleInfo(path.join(sourceModuleDir, 'index.ts'), true)
 
   return {
     packageName,
     packageRoot,
     packageJson,
     metadata: { moduleId, ejectable: selected.ejectable },
-    moduleInfo: { title: info.title, description: info.description },
+    moduleInfo: { title: info.title, description: info.description, requires: info.requires, ...(info.locator ? { locator: info.locator } : {}) },
     sourceModuleDir,
     distModuleDir,
   }
 }
 
+function listPackageFiles(packageRoot: string, directory = packageRoot): string[] {
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    if (shouldSkipEntryName(entry.name)) return []
+    const fullPath = path.join(directory, entry.name)
+    return entry.isDirectory() ? listPackageFiles(packageRoot, fullPath) : [path.relative(packageRoot, fullPath)]
+  })
+}
+
 export function resolveInstalledOfficialModulePackage(
   resolver: PackageResolver,
   packageName: string,
   moduleId?: string,
 ): ValidatedOfficialModulePackage {
   const packageRoot = resolveInstalledPackageRoot(resolver, packageName)
-  return readOfficialModulePackageFromRoot(packageRoot, packageName, moduleId)
+  const modulePackage = readOfficialModulePackageFromRoot(packageRoot, undefined, moduleId)
+  const packageFiles = listPackageFiles(packageRoot)
+  assertModulePackageExports(modulePackage.packageJson, packageName, modulePackage.metadata.moduleId, packageFiles, (relativePath) => fs.readFileSync(path.join(packageRoot, relativePath), 'utf8'))
+  if (modulePackage.packageName !== packageName) {
+    const resolvedBindingRoot = resolveInstalledPackageRootWithRequire(packageName, resolver.getAppDir())
+    const installedBindingPath = path.join('node_modules', packageName)
+    const matchesBindingPath = path.normalize(packageRoot).endsWith(`${path.sep}${installedBindingPath}`)
+    if (!matchesBindingPath && (!resolvedBindingRoot || fs.realpathSync(resolvedBindingRoot) !== fs.realpathSync(packageRoot))) {
+      throw new Error(`Resolved package "${modulePackage.packageName}" does not match requested package binding "${packageName}".`)
+    }
+  }
+  return modulePackage
 }
 
 export function validateEjectBoundaries(modulePackage: ValidatedOfficialModulePackage): void {

package/src/lib/modules-config.ts

@@ -5,6 +5,8 @@ import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 export type ModuleEntry = {
   id: string
   from?: '@open-mercato/core' | '@app' | string
+  locator?: string
+  packageName?: string
 }
 
 type ModuleOccurrence = {
@@ -24,14 +26,24 @@ type ModuleConfigShape = {
 function parseModuleEntryFromObjectLiteral(node: ts.ObjectLiteralExpression): ModuleEntry | null {
   let id: string | null = null
   let from: string | null = null
+  let locator: string | undefined
+  let packageName: string | undefined
 
   for (const property of node.properties) {
-    if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name)) continue
+    if (!ts.isPropertyAssignment(property) || (!ts.isIdentifier(property.name) && !ts.isStringLiteralLike(property.name))) continue
 
     if (property.name.text === 'id' && ts.isStringLiteralLike(property.initializer)) {
       id = property.initializer.text
     }
 
+    if (property.name.text === 'packageName' && ts.isStringLiteralLike(property.initializer)) {
+      packageName = property.initializer.text
+    }
+
+    if (property.name.text === 'locator' && ts.isStringLiteralLike(property.initializer)) {
+      locator = property.initializer.text
+    }
+
     if (property.name.text === 'from' && ts.isStringLiteralLike(property.initializer)) {
       from = property.initializer.text
     }
@@ -42,6 +54,8 @@ function parseModuleEntryFromObjectLiteral(node: ts.ObjectLiteralExpression): Mo
   return {
     id,
     from: from ?? '@open-mercato/core',
+    ...(locator ? { locator } : {}),
+    ...(packageName ? { packageName } : {}),
   }
 }
 
@@ -368,6 +382,8 @@ function normalizeModuleEntry(entry: ModuleEntry): ModuleEntry {
   return {
     id: entry.id,
     from: entry.from ?? '@open-mercato/core',
+    ...(entry.locator ? { locator: entry.locator } : {}),
+    ...(entry.packageName ? { packageName: entry.packageName } : {}),
   }
 }
 
@@ -377,7 +393,7 @@ function escapeSingleQuotedString(value: string): string {
 
 function buildModuleEntryLiteral(entry: ModuleEntry): string {
   const normalized = normalizeModuleEntry(entry)
-  return `{ id: '${escapeSingleQuotedString(normalized.id)}', from: '${escapeSingleQuotedString(normalized.from ?? '@open-mercato/core')}' }`
+  return `{ id: '${escapeSingleQuotedString(normalized.id)}', from: '${escapeSingleQuotedString(normalized.from ?? '@open-mercato/core')}'${normalized.locator ? `, locator: '${escapeSingleQuotedString(normalized.locator)}'` : ''}${normalized.packageName ? `, packageName: '${escapeSingleQuotedString(normalized.packageName)}'` : ''} }`
 }
 
 function lineIndentAt(source: string, position: number): string {
@@ -443,16 +459,29 @@ function insertArrayElement(
   return head + insertion + closingLine + tail
 }
 
-function upsertModuleSource(objectLiteral: string, from: string): string {
-  if (/from\s*:\s*'[^']*'/.test(objectLiteral)) {
-    return objectLiteral.replace(/from\s*:\s*'[^']*'/, `from: '${escapeSingleQuotedString(from)}'`)
-  }
-
-  if (/from\s*:\s*"[^"]*"/.test(objectLiteral)) {
-    return objectLiteral.replace(/from\s*:\s*"[^"]*"/, `from: "${from.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`)
-  }
-
-  return objectLiteral.replace(/\}\s*$/, `, from: '${escapeSingleQuotedString(from)}' }`)
+function upsertModuleProperty(objectLiteral: string, propertyName: 'from' | 'locator' | 'packageName', value: string): string {
+  const prefix = 'const entry = '
+  const sourceFile = ts.createSourceFile('entry.ts', prefix + objectLiteral, ts.ScriptTarget.Latest, true)
+  const statement = sourceFile.statements[0]
+  const initializer = ts.isVariableStatement(statement) ? statement.declarationList.declarations[0]?.initializer : undefined
+  if (!initializer || !ts.isObjectLiteralExpression(initializer)) {
+    throw new Error('Cannot update module registration: expected an object literal.')
+  }
+  const property = initializer.properties.find((candidate) =>
+    'name' in candidate && candidate.name && (ts.isIdentifier(candidate.name) || ts.isStringLiteralLike(candidate.name)) && candidate.name.text === propertyName,
+  )
+  const quotedValue = `'${escapeSingleQuotedString(value)}'`
+  if (property) {
+    const target = ts.isPropertyAssignment(property) ? property.initializer : property
+    const existingQuote = ts.isPropertyAssignment(property) ? property.initializer.getText(sourceFile)[0] : undefined
+    const replacementValue = existingQuote === '"' ? JSON.stringify(value) : quotedValue
+    const replacement = ts.isPropertyAssignment(property) ? replacementValue : `${propertyName}: ${replacementValue}`
+    return objectLiteral.slice(0, target.getStart(sourceFile) - prefix.length) + replacement + objectLiteral.slice(target.end - prefix.length)
+  }
+  const lastProperty = initializer.properties[initializer.properties.length - 1]
+  const insertPosition = lastProperty ? lastProperty.end - prefix.length : initializer.end - prefix.length - 1
+  const separator = lastProperty ? ', ' : ' '
+  return objectLiteral.slice(0, insertPosition) + `${separator}${propertyName}: ${quotedValue}` + objectLiteral.slice(insertPosition)
 }
 
 export function readEnabledModules(modulesPath: string, env: NodeJS.ProcessEnv = process.env): ModuleEntry[] {
@@ -515,6 +544,16 @@ export function ensureModuleRegistration(
   }
 
   const source = fs.readFileSync(modulesPath, 'utf8')
+  const result = prepareModuleRegistration(source, entry, modulesPath)
+  if (result.changed) fs.writeFileSync(modulesPath, result.source)
+  return { changed: result.changed, registeredAs: result.registeredAs }
+}
+
+export function prepareModuleRegistration(
+  source: string,
+  entry: ModuleEntry,
+  modulesPath = 'src/modules.ts',
+): { source: string; changed: boolean; registeredAs: string } {
   const sourceFile = ts.createSourceFile('modules.ts', source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
   const config = parseModuleConfigShape(source)
   const normalized = normalizeModuleEntry(entry)
@@ -526,67 +565,76 @@ export function ensureModuleRegistration(
   }
 
   if (matches.length > 1) {
-    throw new Error(
-      `Module "${normalized.id}" is registered multiple times in ${modulesPath}. Resolve duplicates manually before running this command.`,
-    )
+    throw new Error(`Module "${normalized.id}" is registered multiple times in src/modules.ts. Resolve duplicates manually before running this command.`)
   }
 
   if (matches.length === 1) {
     const existing = normalizeModuleEntry(matches[0].entry)
     if (existing.from === normalized.from) {
-      return { changed: false, registeredAs: normalized.from ?? '@open-mercato/core' }
+      return { source, changed: false, registeredAs: normalized.from ?? '@open-mercato/core' }
     }
-
-    throw new Error(
-      `Module "${normalized.id}" is already registered from "${existing.from}". Remove or eject the existing registration first.`,
-    )
+    throw new Error(`Module "${normalized.id}" is already registered from "${existing.from}". Remove or eject the existing registration first.`)
   }
 
-  const updated = insertArrayElement(source, config.arrayNode, normalized, sourceFile)
-  fs.writeFileSync(modulesPath, updated)
-
-  return { changed: true, registeredAs: normalized.from ?? '@open-mercato/core' }
+  return {
+    source: insertArrayElement(source, config.arrayNode, normalized, sourceFile),
+    changed: true,
+    registeredAs: normalized.from ?? '@open-mercato/core',
+  }
 }
 
 export function setModuleRegistrationSource(
   modulesPath: string,
   moduleId: string,
   from: string,
+  provenance?: Pick<ModuleEntry, 'locator' | 'packageName'>,
 ): { changed: boolean } {
   if (!fs.existsSync(modulesPath)) {
     throw new Error(`modules.ts not found at ${modulesPath}`)
   }
 
   const source = fs.readFileSync(modulesPath, 'utf8')
+  const updated = prepareModuleRegistrationSource(source, moduleId, from, provenance)
+  if (updated === source) return { changed: false }
+  fs.writeFileSync(modulesPath, updated)
+  return { changed: true }
+}
+
+export function prepareModuleRegistrationSource(
+  source: string,
+  moduleId: string,
+  from: string,
+  provenance?: Pick<ModuleEntry, 'locator' | 'packageName'>,
+): string {
   const config = parseModuleConfigShape(source)
   const matches = config.occurrences.filter((occurrence) => occurrence.active && occurrence.entry.id === moduleId)
 
   if (matches.length === 0) {
     throw new Error(
-      `Could not find module entry for "${moduleId}" in ${modulesPath}. Expected a pattern like: { id: '${moduleId}', from: '...' } or { id: '${moduleId}' }`,
+      `Could not find module entry for "${moduleId}" in src/modules.ts. Expected a pattern like: { id: '${moduleId}', from: '...' } or { id: '${moduleId}' }`,
     )
   }
 
   if (matches.length > 1) {
     throw new Error(
-      `Module "${moduleId}" is registered multiple times in ${modulesPath}. Resolve duplicates manually before running this command.`,
+      `Module "${moduleId}" is registered multiple times in src/modules.ts. Resolve duplicates manually before running this command.`,
     )
   }
 
   const match = matches[0]
   const current = normalizeModuleEntry(match.entry)
-  if (current.from === from) {
-    return { changed: false }
+  if (current.from === from && (!provenance?.locator || current.locator === provenance.locator) && (!provenance?.packageName || current.packageName === provenance.packageName)) {
+    return source
   }
 
   const objectLiteral = source.slice(match.node.getStart(), match.node.end)
-  const updatedObjectLiteral = upsertModuleSource(objectLiteral, from)
+  let updatedObjectLiteral = upsertModuleProperty(objectLiteral, 'from', from)
+  if (provenance?.locator) updatedObjectLiteral = upsertModuleProperty(updatedObjectLiteral, 'locator', provenance.locator)
+  if (provenance?.packageName) updatedObjectLiteral = upsertModuleProperty(updatedObjectLiteral, 'packageName', provenance.packageName)
   const updated =
     source.slice(0, match.node.getStart()) +
     updatedObjectLiteral +
     source.slice(match.node.end)
 
-  fs.writeFileSync(modulesPath, updated)
-
-  return { changed: true }
+  return updated
 }