@open-mercato/cli 0.10.1-develop.7983.1.fd91207efe → 0.10.1-develop.7994.1.c9f31972aa

package/src/lib/module-identity.ts

@@ -0,0 +1,145 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import ts from 'typescript-js'
+import { normalizeModuleLocator, type ModuleIdentity } from '@open-mercato/shared/modules/module-locators'
+import type { ModuleEntry, PackageResolver } from './resolver'
+import { readEnabledModules } from './modules-config'
+
+function readJson(filePath: string): Record<string, unknown> {
+  try {
+    const value: unknown = JSON.parse(fs.readFileSync(filePath, 'utf8'))
+    return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+  } catch {
+    return {}
+  }
+}
+
+function readMetadataLocator(moduleBase: string): string | undefined {
+  const indexPath = ['index.ts', 'index.js'].map((name) => path.join(moduleBase, name)).find((candidate) => fs.existsSync(candidate))
+  if (!indexPath) return undefined
+  const source = ts.createSourceFile(indexPath, fs.readFileSync(indexPath, 'utf8'), ts.ScriptTarget.Latest, true)
+  let locator: string | undefined
+  function visit(node: ts.Node): void {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === 'metadata' && node.initializer) {
+      let initializer = node.initializer
+      while (ts.isAsExpression(initializer) || ts.isSatisfiesExpression(initializer) || ts.isParenthesizedExpression(initializer)) initializer = initializer.expression
+      if (ts.isObjectLiteralExpression(initializer)) {
+        for (const property of initializer.properties) {
+          if (ts.isPropertyAssignment(property) && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) && property.name.text === 'locator' && ts.isStringLiteralLike(property.initializer)) locator = property.initializer.text
+        }
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(source)
+  return locator
+}
+
+function sourceLocator(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const locator = normalizeModuleLocator(value)
+  return locator?.startsWith('npm:') || locator?.startsWith('github:') ? locator : undefined
+}
+
+function installedDependencyLocator(specifier: unknown, canonicalName: string | undefined): string | undefined {
+  if (typeof specifier !== 'string') return undefined
+  if (/^(?:github:|github\.com\/|(?:git\+)?https?:\/\/github\.com\/|git@github\.com:|(?:git\+)?ssh:\/\/|[a-z0-9][a-z0-9-]*\/[a-z0-9._-]+(?:[#@]|$))/i.test(specifier)) {
+    const locator = sourceLocator(specifier)
+    return locator?.startsWith('github:') ? locator : undefined
+  }
+  if (specifier.startsWith('npm:')) {
+    const aliasTarget = specifier.match(/^npm:(@[^/]+\/[^@]+|[^@]+)(?:@.+)?$/)?.[1]
+    return aliasTarget ? sourceLocator(`npm:${aliasTarget}`) : undefined
+  }
+  if (!canonicalName || /^(?:[a-z][a-z0-9+.-]*:|[./]|https?:)/i.test(specifier)) return undefined
+  return sourceLocator(`npm:${canonicalName}`)
+}
+
+function assertDeclaredIdentity(entry: ModuleEntry, observedLocator: string | undefined, canonicalName: string | undefined): void {
+  const binding = entry.from ?? '@open-mercato/core'
+  if (entry.packageName && canonicalName && entry.packageName !== canonicalName) {
+    throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${binding}': declared package '${entry.packageName}' disagrees with installed package '${canonicalName}'. Restore the intended binding or correct src/modules.ts, then regenerate.`)
+  }
+  const declaredLocator = sourceLocator(entry.locator)
+  if (declaredLocator && observedLocator && declaredLocator !== observedLocator) {
+    throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${binding}': declared origin '${declaredLocator}' disagrees with observed origin '${observedLocator}'. Disable the old provider before replacing it, then regenerate.`)
+  }
+  if (declaredLocator?.startsWith('npm:') && canonicalName && declaredLocator !== sourceLocator(`npm:${canonicalName}`)) {
+    throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${binding}': declared origin '${declaredLocator}' disagrees with installed package '${canonicalName}'. Correct src/modules.ts to select the intended provider, then regenerate.`)
+  }
+}
+
+function readModuleLocators(
+  entry: ModuleEntry,
+  resolver: PackageResolver,
+  appManifest: Record<string, unknown>,
+  packageManifests: Map<string, Record<string, unknown>>,
+): string[] {
+  const from = entry.from ?? '@open-mercato/core'
+  if (from === '@app') {
+    const retainedLocator = sourceLocator(entry.locator ?? readMetadataLocator(resolver.getModulePaths(entry).appBase))
+    assertDeclaredIdentity(entry, retainedLocator, entry.packageName)
+    return retainedLocator ? [retainedLocator] : []
+  }
+
+  let manifest = packageManifests.get(from)
+  if (!manifest) {
+    manifest = readJson(path.join(resolver.getPackageRoot(from), 'package.json'))
+    packageManifests.set(from, manifest)
+  }
+  const canonicalName = typeof manifest.name === 'string' ? manifest.name : undefined
+  const observedLocators = new Set<string>()
+  for (const section of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+    const dependencies = appManifest[section]
+    if (!dependencies || typeof dependencies !== 'object' || Array.isArray(dependencies)) continue
+    const specifier = (dependencies as Record<string, unknown>)[from]
+    const locator = installedDependencyLocator(specifier, canonicalName)
+    if (locator?.startsWith('npm:') && canonicalName !== from && typeof specifier === 'string' && !specifier.startsWith('npm:')) {
+      throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${from}': installed package '${canonicalName}' does not match the dependency binding. Restore the intended package or declare an explicit npm alias, then regenerate.`)
+    }
+    if (locator) observedLocators.add(locator)
+  }
+  if (observedLocators.size > 1) {
+    throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${from}': dependency sections declare conflicting origins. Keep one provider for this binding in package.json, then regenerate.`)
+  }
+  const observedLocator = [...observedLocators][0]
+  if (observedLocator?.startsWith('npm:') && canonicalName && observedLocator !== sourceLocator(`npm:${canonicalName}`)) {
+    throw new Error(`[modules] Cannot resolve module '${entry.id}' from binding '${from}': dependency origin '${observedLocator}' disagrees with installed package '${canonicalName}'. Restore the intended package through the package manager, then regenerate.`)
+  }
+  assertDeclaredIdentity(entry, observedLocator, canonicalName)
+  const locator = observedLocator ?? sourceLocator(entry.locator)
+  return locator ? [locator] : []
+}
+
+export function getModuleLocators(entry: ModuleEntry, resolver: PackageResolver): string[] {
+  return readModuleLocators(entry, resolver, readJson(path.join(resolver.getAppDir(), 'package.json')), new Map())
+}
+
+export function assertUniqueEnabledModuleIds(enabledModules: readonly ModuleEntry[], resolver: PackageResolver): void {
+  const byId = new Map<string, ModuleEntry>()
+  for (const entry of enabledModules) {
+    const existing = byId.get(entry.id)
+    if (existing) {
+      const describe = (provider: ModuleEntry): string => {
+        const binding = provider.from ?? '@open-mercato/core'
+        const source = sourceLocator(provider.locator)
+        return binding === '@app'
+          ? `@app (${resolver.getModulePaths(provider).appBase})${source ? `, origin ${source}` : ''}`
+          : `binding '${binding}'${source ? `, origin ${source}` : ''}`
+      }
+      throw new Error(`[generate] Duplicate enabled module ID '${entry.id}': ${describe(existing)} and ${describe(entry)}. Keep one provider in src/modules.ts, then run yarn mercato generate. Installing under another package alias does not allow both module IDs to run.`)
+    }
+    byId.set(entry.id, entry)
+  }
+}
+
+export function getEnabledModuleIdentities(resolver: PackageResolver, enabledModules: readonly ModuleEntry[] = resolver.loadEnabledModules()): ModuleIdentity[] {
+  const modulesPath = typeof resolver.getModulesConfigPath === 'function'
+    ? resolver.getModulesConfigPath()
+    : path.join(resolver.getAppDir(), 'src', 'modules.ts')
+  if (fs.existsSync(modulesPath)) assertUniqueEnabledModuleIds(readEnabledModules(modulesPath), resolver)
+  assertUniqueEnabledModuleIds(enabledModules, resolver)
+  const appManifest = readJson(path.join(resolver.getAppDir(), 'package.json'))
+  const packageManifests = new Map<string, Record<string, unknown>>()
+  return enabledModules.map((entry) => ({ id: entry.id, locators: readModuleLocators(entry, resolver, appManifest, packageManifests) }))
+}

package/src/lib/module-inspection.ts

@@ -0,0 +1,133 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import spawn from 'cross-spawn'
+import { assertModulePackageExports, isModulePackageExportError } from './module-package'
+
+export type InspectedModuleTarget = {
+  packageName: string
+  packageSpec: string
+  moduleIds: string[]
+  locator?: string
+  version?: string
+}
+
+type ArtifactInspection = { moduleIds: string[]; version?: string }
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+}
+
+function inspectFiles(manifest: Record<string, unknown>, packageName: string, files: string[], requiredModuleIds: readonly string[], readSource: (relativePath: string) => string): ArtifactInspection {
+  if (manifest.name !== packageName) throw new Error(`Inspected package does not match "${packageName}". No package was installed.`)
+  const moduleIds = [...new Set(files.flatMap((file) => {
+    const match = /^src\/modules\/([a-z0-9]+(?:_[a-z0-9]+)*)\/index\.ts$/.exec(file)
+    return match && files.includes(`dist/modules/${match[1]}/index.js`) ? [match[1]] : []
+  }))]
+  const checkedModuleIds = requiredModuleIds.length ? requiredModuleIds : moduleIds.length === 1 ? moduleIds : []
+  for (const moduleId of checkedModuleIds) {
+    if (!moduleIds.includes(moduleId)) throw new Error(`Package "${packageName}" is missing source or compiled descriptors for "${moduleId}". No package was installed.`)
+    assertModulePackageExports(manifest, packageName, moduleId, files, readSource)
+  }
+  if (moduleIds.length === 0) throw new Error(`Package "${packageName}" is missing source or compiled module descriptors. Build the package before retrying. No package was installed.`)
+  return { moduleIds, ...(typeof manifest.version === 'string' ? { version: manifest.version } : {}) }
+}
+
+function inspectArchive(archive: string, packageName: string, requiredModuleIds: readonly string[]): ArtifactInspection {
+  const manifest = record(JSON.parse(execFileSync('tar', ['-xOf', archive, 'package/package.json'], { encoding: 'utf8', timeout: 15_000 })))
+  const files = execFileSync('tar', ['-tf', archive], { encoding: 'utf8', timeout: 15_000, maxBuffer: 16 * 1024 * 1024 }).split('\n').filter((file) => file.startsWith('package/')).map((file) => file.slice('package/'.length))
+  return inspectFiles(manifest, packageName, files, requiredModuleIds, (relativePath) => execFileSync('tar', ['-xOf', archive, `package/${relativePath}`], { encoding: 'utf8', timeout: 15_000, maxBuffer: 1024 * 1024 }))
+}
+
+function packageFiles(packageRoot: string, relativeDir = ''): string[] {
+  return fs.readdirSync(path.join(packageRoot, relativeDir), { withFileTypes: true }).flatMap((entry) => {
+    if (entry.name === 'node_modules' || entry.name.startsWith('.')) return []
+    const relativePath = path.posix.join(relativeDir, entry.name)
+    return entry.isDirectory() ? packageFiles(packageRoot, relativePath) : entry.isFile() ? [relativePath] : []
+  })
+}
+
+function isModernYarnProject(appDir: string): boolean {
+  let directory = appDir
+  while (true) {
+    if (fs.existsSync(path.join(directory, '.yarnrc.yml'))) return true
+    const manifestPath = path.join(directory, 'package.json')
+    if (fs.existsSync(manifestPath)) {
+      const manifest = record(JSON.parse(fs.readFileSync(manifestPath, 'utf8')))
+      if (typeof manifest.packageManager === 'string' && /^yarn@(?:[2-9]|[1-9][0-9]+)\./.test(manifest.packageManager)) return true
+    }
+    const parent = path.dirname(directory)
+    if (parent === directory) return false
+    directory = parent
+  }
+}
+
+function yarnNpmConfiguration(appDir: string, packageName: string, temporaryDir: string): string[] {
+  if (!isModernYarnProject(appDir)) return []
+  const settings = new Map<string, unknown>()
+  for (const setting of ['npmRegistryServer', 'npmScopes', 'npmRegistries', 'npmAuthToken', 'npmAuthIdent']) {
+    const result = spawn.sync(process.platform === 'win32' ? 'yarn.cmd' : 'yarn', ['config', 'get', setting, '--json', '--no-redacted'], {
+      cwd: appDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 15_000,
+    })
+    if (result.error || result.status !== 0) throw new Error('Cannot inspect project package registry configuration')
+    settings.set(setting, JSON.parse(result.stdout))
+  }
+  const scope = packageName.startsWith('@') ? packageName.slice(1).split('/')[0] : undefined
+  const scopeSettings = scope ? record(record(settings.get('npmScopes'))[scope]) : {}
+  const registry = typeof scopeSettings.npmRegistryServer === 'string' ? scopeSettings.npmRegistryServer : settings.get('npmRegistryServer')
+  if (typeof registry !== 'string') throw new Error('Missing project package registry')
+  const registryUrl = new URL(registry)
+  if (!['http:', 'https:'].includes(registryUrl.protocol) || registryUrl.username || registryUrl.password) throw new Error('Invalid project package registry')
+  const registryKey = `//${registryUrl.host}${registryUrl.pathname}`.replace(/\/$/, '')
+  const registries = record(settings.get('npmRegistries'))
+  const registrySettings = record(registries[registry.replace(/\/$/, '')] ?? registries[registryKey] ?? registries[`${registryKey}/`])
+  const auth = scopeSettings.npmAuthToken || scopeSettings.npmAuthIdent ? scopeSettings
+    : registrySettings.npmAuthToken || registrySettings.npmAuthIdent ? registrySettings
+      : { npmAuthToken: settings.get('npmAuthToken'), npmAuthIdent: settings.get('npmAuthIdent') }
+  const userConfig = process.env.NPM_CONFIG_USERCONFIG ?? process.env.npm_config_userconfig ?? path.join(os.homedir(), '.npmrc')
+  const existingConfig = fs.existsSync(userConfig) ? fs.readFileSync(userConfig, 'utf8') : ''
+  const lines = [existingConfig, `registry=${JSON.stringify(registry)}`]
+  if (scope) lines.push(`@${scope}:registry=${JSON.stringify(registry)}`)
+  if (typeof auth.npmAuthToken === 'string' && auth.npmAuthToken) lines.push(`${registryKey}/:_authToken=${JSON.stringify(auth.npmAuthToken)}`)
+  else if (typeof auth.npmAuthIdent === 'string' && auth.npmAuthIdent) lines.push(`${registryKey}/:_auth=${Buffer.from(auth.npmAuthIdent).toString('base64')}`)
+  const configPath = path.join(temporaryDir, 'inspection.npmrc')
+  fs.writeFileSync(configPath, `${lines.join('\n')}\n`, { mode: 0o600 })
+  return ['--userconfig', configPath, '--registry', registry, ...(scope ? [`--@${scope}:registry=${registry}`] : [])]
+}
+
+export function inspectNpmModuleTarget(packageSpec: string, packageName: string, appDir: string, requiredModuleIds: readonly string[] = []): InspectedModuleTarget {
+  const filePrefix = `${packageName}@file:`
+  if (packageSpec.startsWith(filePrefix)) {
+    const packageRoot = path.resolve(appDir, packageSpec.slice(filePrefix.length))
+    if (fs.statSync(packageRoot).isFile()) return { packageName, packageSpec, ...inspectArchive(packageRoot, packageName, requiredModuleIds) }
+    const manifest = record(JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')))
+    const inspected = inspectFiles(manifest, packageName, packageFiles(packageRoot), requiredModuleIds, (relativePath) => fs.readFileSync(path.join(packageRoot, relativePath), 'utf8'))
+    return { packageName, packageSpec, ...inspected }
+  }
+
+  const temporaryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mercato-module-inspection-'))
+  let inspectionStep = 'read the project registry configuration'
+  try {
+    const configurationArgs = yarnNpmConfiguration(appDir, packageName, temporaryDir)
+    inspectionStep = 'fetch the exact npm artifact'
+    const packedProcess = spawn.sync(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['pack', packageSpec, '--ignore-scripts', '--json', '--pack-destination', temporaryDir, ...configurationArgs], {
+      cwd: appDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000, maxBuffer: 16 * 1024 * 1024,
+    })
+    if (packedProcess.error || packedProcess.status !== 0) throw new Error('Artifact inspection failed')
+    inspectionStep = 'parse the npm artifact response'
+    const packages: unknown = JSON.parse(packedProcess.stdout)
+    const packed = record(Array.isArray(packages) ? packages[0] : undefined)
+    if (packed.name !== packageName || typeof packed.version !== 'string' || !/^[0-9A-Za-z.+-]+$/.test(packed.version)
+      || typeof packed.filename !== 'string' || path.basename(packed.filename) !== packed.filename) throw new Error('Invalid packed manifest')
+    inspectionStep = 'validate the packed module artifact'
+    const inspected = inspectArchive(path.join(temporaryDir, packed.filename), packageName, requiredModuleIds)
+    if (inspected.version !== packed.version) throw new Error('Packed artifact version disagrees with resolution')
+    return { packageName, packageSpec, ...inspected, locator: `npm:${packageName}` }
+  } catch (error) {
+    const safeDetail = isModulePackageExportError(error) && error instanceof Error ? ` ${error.message}` : ''
+    throw new Error(`Cannot inspect the exact module artifact for "${packageName}" while trying to ${inspectionStep}.${safeDetail} Check project registry credentials, package access and shipped src/dist module descriptors before retrying. No package was installed.`)
+  } finally {
+    fs.rmSync(temporaryDir, { recursive: true, force: true })
+  }
+}

package/src/lib/module-install.ts

@@ -8,9 +8,13 @@ import {
   validateEjectBoundaries,
   type ValidatedOfficialModulePackage,
 } from './module-package'
-import { assertModuleNotGatedOff, ensureModuleRegistration } from './modules-config'
+import { assertModuleNotGatedOff, prepareModuleRegistration, prepareModuleRegistrationSource } from './modules-config'
 import type { PackageResolver } from './resolver'
 import { resolveSpawnCommand } from './spawn'
+import { parseModuleLocator, resolveModuleRequirement } from '@open-mercato/shared/modules/module-locators'
+import { getEnabledModuleIdentities, getModuleLocators } from './module-identity'
+import { resolveGithubModuleTarget } from './module-github'
+import { inspectNpmModuleTarget, type InspectedModuleTarget } from './module-inspection'
 
 export type ModuleCommandResult = {
   moduleId: string
@@ -91,7 +95,7 @@ function readFileIfExists(filePath: string): string | null {
   return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null
 }
 
-function isDeclaredAppDependency(appDir: string, packageName: string): boolean {
+function isDeclaredAppDependency(appDir: string, packageName: string, packageSpecifier?: string): boolean {
   const packageJsonContent = readFileIfExists(path.join(appDir, 'package.json'))
   if (!packageJsonContent) {
     return false
@@ -105,10 +109,13 @@ function isDeclaredAppDependency(appDir: string, packageName: string): boolean {
     throw new Error(`App package.json at ${path.join(appDir, 'package.json')} is not valid JSON. ${message}`)
   }
 
-  return ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'].some((field) => {
+  const declarations = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'].flatMap((field) => {
     const dependencies = packageJson[field]
     return typeof dependencies === 'object' && dependencies !== null && packageName in dependencies
+      ? [(dependencies as Record<string, unknown>)[packageName]]
+      : []
   })
+  return declarations.length > 0 && (packageSpecifier === undefined || declarations.every((declaration) => declaration === packageSpecifier))
 }
 
 function isGatedOffError(error: unknown): boolean {
@@ -187,7 +194,7 @@ function assertThirdPartyAllowed(packageName: string, allowThirdParty: boolean):
 }
 
 function assertSupportedPackageSpec(packageSpec: string, allowThirdParty: boolean): string {
-  const trimmed = packageSpec.trim()
+  const trimmed = packageSpec.trim().replace(/^npm:/, '')
 
   if (!SAFE_PACKAGE_SPEC_PATTERN.test(trimmed)) {
     throw new Error('Unsupported package spec. Provide a valid npm package name with an optional tag/version or file: locator.')
@@ -217,12 +224,71 @@ function validateBeforeRegistration(
   const appModuleDir = path.join(resolver.getAppDir(), 'src', 'modules', modulePackage.metadata.moduleId)
 
   if (eject && fs.existsSync(appModuleDir)) {
-    throw new Error(`Destination directory already exists: ${appModuleDir}. Remove it first or rerun without --eject.`)
+    throw new Error(`Destination directory already exists: ${appModuleDir}. Preserve local source and choose a different destination or resolve the conflict manually.`)
   }
 
   return appModuleDir
 }
 
+function assertRequiredModulesEnabled(
+  modulePackage: ValidatedOfficialModulePackage,
+  resolver: PackageResolver,
+): void {
+  const enabledModules = getEnabledModuleIdentities(resolver)
+  const missingModuleIds = Array.from(new Set(modulePackage.moduleInfo.requires ?? [])).filter(
+    (requirement) => !resolveModuleRequirement(requirement, enabledModules),
+  )
+  if (missingModuleIds.length === 0) return
+
+  throw new Error(
+    [
+      `Module "${modulePackage.metadata.moduleId}" requires module(s) that are not enabled: ${missingModuleIds.join(', ')}.`,
+      'Enable the missing module(s) in src/modules.ts first, then rerun this command.',
+      ...missingModuleIds.filter((requirement) => parseModuleLocator(requirement)?.kind !== 'module').map(
+        (requirement) => `Install ${requirement}: npx create-mercato-module install ${shellQuote(requirement)}`,
+      ),
+    ].join('\n'),
+  )
+}
+
+function shellQuote(value: string): string {
+  return "'" + value.replace(/'/g, "'\\''") + "'"
+}
+
+function assertNoModuleCollision(
+  resolver: PackageResolver,
+  moduleId: string,
+  packageName: string,
+  locator?: string,
+): void {
+  const registrations = resolver.loadEnabledModules().filter((entry) => entry.id === moduleId)
+  if (registrations.length > 1) {
+    throw new Error(`Module name collision: "${moduleId}" is registered multiple times from ${registrations.map((entry) => entry.locator ?? entry.from ?? '@open-mercato/core').join(', ')}. Resolve duplicate registrations before retrying.`)
+  }
+  const existing = registrations[0]
+  if (existing && (existing.from ?? '@open-mercato/core') !== packageName) {
+    throw new Error(`Module name collision: "${moduleId}" is already registered from "${existing.locator ?? existing.from ?? '@open-mercato/core'}"; requested source is "${locator ?? packageName}". Two sources cannot share one module id. Remove or rename the conflicting module explicitly before retrying.`)
+  }
+  const existingGithub = existing ? getModuleLocators(existing, resolver).find((value) => value.startsWith('github:')) : undefined
+  const requestedIdentity = locator ? parseModuleLocator(locator)?.identity : undefined
+  if (existingGithub && requestedIdentity && existingGithub !== requestedIdentity) {
+    throw new Error(`Module name collision: "${moduleId}" is already registered from "${existingGithub}"; requested source is "${locator}". Remove or rename the conflicting module explicitly before retrying.`)
+  }
+  if (!existing && fs.existsSync(path.join(resolver.getAppDir(), 'src', 'modules', moduleId))) {
+    throw new Error(`Module name collision: local src/modules/${moduleId} already exists; requested source is "${locator ?? packageName}". Remove or rename the conflicting module explicitly before retrying.`)
+  }
+}
+
+function assertBindingPreserved(resolver: PackageResolver, target: InspectedModuleTarget): void {
+  const consumers = resolver.loadEnabledModules().filter((entry) => (entry.from ?? '@open-mercato/core') === target.packageName)
+  for (const entry of consumers) {
+    const locators = getModuleLocators(entry, resolver)
+    if (!target.locator || !locators.includes(target.locator) || !target.moduleIds.includes(entry.id)) {
+      throw new Error(`Package binding collision: "${target.packageName}" supplies enabled module "${entry.id}" from "${locators.join(', ') || 'unknown origin'}". Requested "${target.locator ?? 'unknown origin'}" must preserve its source and module layout. Disable affected entries explicitly before replacing this binding. No package was installed.`)
+    }
+  }
+}
+
 function prepareRegistrationSource(
   modulePackage: ValidatedOfficialModulePackage,
   resolver: PackageResolver,
@@ -256,19 +322,38 @@ async function registerResolvedOfficialModule(
   modulePackage: ValidatedOfficialModulePackage,
   packageName: string,
   eject: boolean,
+  requestedLocator?: string,
 ): Promise<ModuleCommandResult> {
   assertModuleNotGatedOff(resolver.getModulesConfigPath(), modulePackage.metadata.moduleId)
-  const from = prepareRegistrationSource(modulePackage, resolver, packageName, eject)
-
-  const registration = ensureModuleRegistration(
-    resolver.getModulesConfigPath(),
+  const locators = getModuleLocators({ id: modulePackage.metadata.moduleId, from: packageName }, resolver)
+  if (requestedLocator && locators.length > 0 && !locators.includes(requestedLocator)) {
+    throw new Error(`Installed package "${packageName}" disagrees with inspected origin "${requestedLocator}". It is installed but not enabled. Restore the binding and lockfile through your package manager before retrying.`)
+  }
+  const locator = requestedLocator ?? locators[0]
+  assertNoModuleCollision(resolver, modulePackage.metadata.moduleId, packageName, locator)
+  assertRequiredModulesEnabled(modulePackage, resolver)
+  const existing = resolver.loadEnabledModules().find((entry) => entry.id === modulePackage.metadata.moduleId)
+  const from = eject ? '@app' : packageName
+  const provenance = {
+    ...(locator ? { locator } : {}),
+    ...(eject || modulePackage.packageName !== packageName ? { packageName: modulePackage.packageName } : {}),
+  }
+  const modulesPath = resolver.getModulesConfigPath()
+  const modulesSource = fs.readFileSync(modulesPath, 'utf8')
+  const registration = existing && eject
+    ? { changed: true, source: prepareModuleRegistrationSource(modulesSource, modulePackage.metadata.moduleId, from, provenance) }
+    : prepareModuleRegistration(
+    modulesSource,
     {
       id: modulePackage.metadata.moduleId,
       from,
+      ...(locator || eject || modulePackage.packageName !== packageName ? provenance : {}),
     },
   )
 
+  prepareRegistrationSource(modulePackage, resolver, packageName, eject)
   if (registration.changed) {
+    fs.writeFileSync(modulesPath, registration.source)
     await runGeneratorsWithRegistrationNotice(resolver, modulePackage.metadata.moduleId)
   }
 
@@ -287,24 +372,81 @@ export async function addOfficialModule(
   moduleId?: string,
   allowThirdParty = false,
 ): Promise<ModuleCommandResult> {
-  const safePackageSpec = assertSupportedPackageSpec(packageSpec, allowThirdParty)
-  const packageName = parsePackageNameFromSpec(safePackageSpec)
-  assertPackageName(packageName)
-
+  const input = packageSpec.trim()
+  getEnabledModuleIdentities(resolver)
+  const isGithub = !input.startsWith('@') && !input.startsWith('npm:') && (
+    input.includes('/') && !input.includes('@file:') || /^(?:github:|git@|(?:git\+)?ssh:)/i.test(input)
+  )
+  let safePackageSpec: string
+  let packageName: string
+  let target: InspectedModuleTarget
+  if (isGithub) {
+    if (!allowThirdParty) {
+      throw new Error('GitHub repository installs require --allow-third-party, independently of the declared npm package scope.')
+    }
+    target = resolveGithubModuleTarget(input, resolver.getAppDir(), { moduleId, enabledModules: resolver.loadEnabledModules() })
+    assertThirdPartyAllowed(target.packageName, allowThirdParty)
+    const selectedModuleId = moduleId ?? (target.moduleIds.length === 1 ? target.moduleIds[0] : undefined)
+    if (!selectedModuleId || !target.moduleIds.includes(selectedModuleId)) {
+      throw new Error(`Select a module with --module <moduleId>. Available in ${target.locator ?? target.packageName}: ${target.moduleIds.join(', ')}. No package was installed.`)
+    }
+    assertNoModuleCollision(resolver, selectedModuleId, target.packageName, target.locator)
+    safePackageSpec = target.packageSpec
+    packageName = target.packageName
+  } else {
+    safePackageSpec = assertSupportedPackageSpec(input, allowThirdParty)
+    const parsedName = parsePackageNameFromSpec(safePackageSpec)
+    assertPackageName(parsedName)
+    packageName = parsedName
+    if (moduleId) assertNoModuleCollision(resolver, moduleId, packageName, safePackageSpec.startsWith(`${packageName}@file:`) ? undefined : `npm:${packageName}`)
+    const requiredModuleIds = resolver.loadEnabledModules().filter((entry) => (entry.from ?? '@open-mercato/core') === packageName).map((entry) => entry.id)
+    target = inspectNpmModuleTarget(safePackageSpec, packageName, resolver.getAppDir(), [...new Set([...(moduleId ? [moduleId] : []), ...requiredModuleIds])])
+  }
+  const selectedModuleId = moduleId ?? (target.moduleIds.length === 1 ? target.moduleIds[0] : undefined)
+  if (!selectedModuleId || !target.moduleIds.includes(selectedModuleId)) {
+    throw new Error(`Select a module with --module <moduleId>. Available in ${target.locator ?? target.packageName}: ${target.moduleIds.join(', ')}. No package was installed.`)
+  }
+  assertNoModuleCollision(resolver, selectedModuleId, packageName, target.locator)
+  const existing = resolver.loadEnabledModules().find((entry) => entry.id === selectedModuleId)
+  if (!eject && existing && !target.locator
+    && target.packageSpec.startsWith(`${packageName}@file:`)
+    && getModuleLocators(existing, resolver).length === 0
+    && isDeclaredAppDependency(resolver.getAppDir(), packageName, target.packageSpec.slice(packageName.length + 1))) {
+    return enableOfficialModule(resolver, packageName, selectedModuleId, false, allowThirdParty)
+  }
+  assertBindingPreserved(resolver, target)
+  const modulesSource = fs.readFileSync(resolver.getModulesConfigPath(), 'utf8')
+  const from = eject ? '@app' : packageName
+  if (existing && eject) prepareModuleRegistrationSource(modulesSource, selectedModuleId, from, { locator: target.locator, packageName })
+  else prepareModuleRegistration(modulesSource, { id: selectedModuleId, from, locator: target.locator })
+  if (eject && fs.existsSync(path.join(resolver.getAppDir(), 'src', 'modules', selectedModuleId))) {
+    throw new Error(`Destination directory already exists for "${selectedModuleId}". Preserve local source and resolve the conflict manually. No package was installed.`)
+  }
+  safePackageSpec = target.packageSpec
+  assertModuleNotGatedOff(resolver.getModulesConfigPath(), selectedModuleId)
   const wasDeclaredBefore = isDeclaredAppDependency(resolver.getAppDir(), packageName)
   const modulesConfigBefore = readFileIfExists(resolver.getModulesConfigPath())
-
   await installPackageSpec(resolver, safePackageSpec)
 
   try {
-    const modulePackage = resolveInstalledOfficialModulePackage(resolver, packageName, moduleId)
-    return await registerResolvedOfficialModule(resolver, modulePackage, packageName, eject)
+    const modulePackage = resolveInstalledOfficialModulePackage(resolver, packageName, selectedModuleId)
+    if (modulePackage.packageName !== packageName) throw new Error('Installed manifest differs from inspected package name.')
+    if (target.version && modulePackage.packageJson.version !== target.version) {
+      throw new Error(`Installed version "${modulePackage.packageJson.version ?? 'unknown'}" differs from inspected version "${target.version}". No registration or source edits were made.`)
+    }
+    for (const entry of resolver.loadEnabledModules().filter((entry) => (entry.from ?? '@open-mercato/core') === packageName)) {
+      resolveInstalledOfficialModulePackage(resolver, packageName, entry.id)
+    }
+    return await registerResolvedOfficialModule(resolver, modulePackage, packageName, eject, target.locator)
   } catch (error) {
     const moduleWasRegistered = readFileIfExists(resolver.getModulesConfigPath()) !== modulesConfigBefore
-    if (wasDeclaredBefore || moduleWasRegistered || isGatedOffError(error)) {
-      throw error
-    }
-    throw withLeftoverPackageHint(error, resolver, packageName)
+    if (wasDeclaredBefore || moduleWasRegistered || isGatedOffError(error)) throw error
+    const message = error instanceof Error ? error.message : String(error)
+    throw withLeftoverPackageHint(
+      new Error(`Package "${packageName}" is installed; enablement did not complete. Review src/modules.ts and restore the package binding/lockfile through the package manager if needed. ${message}`),
+      resolver,
+      packageName,
+    )
   }
 }
 
@@ -315,8 +457,14 @@ export async function enableOfficialModule(
   eject = false,
   allowThirdParty = false,
 ): Promise<ModuleCommandResult> {
-  assertThirdPartyAllowed(packageName, allowThirdParty)
-
+  if (!SAFE_PACKAGE_SPEC_PATTERN.test(packageName) || parsePackageNameFromSpec(packageName) !== packageName) {
+    throw new Error('Unsupported installed package binding. Use the installed npm package name or alias, without a locator, path or version selector.')
+  }
+  getEnabledModuleIdentities(resolver)
   const modulePackage = resolveInstalledOfficialModulePackage(resolver, packageName, moduleId)
+  assertThirdPartyAllowed(modulePackage.packageName, allowThirdParty)
+  if (!allowThirdParty && getModuleLocators({ id: modulePackage.metadata.moduleId, from: packageName }, resolver).some((locator) => locator.startsWith('github:'))) {
+    throw new Error('GitHub repository installs require --allow-third-party, independently of the declared npm package scope.')
+  }
   return registerResolvedOfficialModule(resolver, modulePackage, packageName, eject)
 }