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

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

@@ -1,5 +1,6 @@
+import { getEnabledModuleIdentities } from '../module-identity'
 import path from 'node:path'
-import { readOfficialModulePackageFromRoot, resolveInstalledPackageRoot } from '../module-package'
+import { resolveInstalledOfficialModulePackage } from '../module-package'
 import type { PackageResolver } from '../resolver'
 import { calculateChecksum, createGeneratorResult, type GeneratorResult, writeGeneratedFile } from '../utils'
 
@@ -24,14 +25,15 @@ export async function generateModulePackageSources(
   const sourcePaths = new Set<string>()
   const checksumInputs = new Set<string>()
 
-  for (const entry of resolver.loadEnabledModules()) {
-    if (!entry.from || entry.from === '@app' || entry.from === '@open-mercato/core') continue
+  const enabled = resolver.loadEnabledModules()
+  getEnabledModuleIdentities(resolver, enabled)
 
-    const packageRoot = resolveInstalledPackageRoot(resolver, entry.from)
+  for (const entry of enabled) {
+    if (!entry.from || entry.from === '@app' || entry.from === '@open-mercato/core') continue
 
     let modulePackage
     try {
-      modulePackage = readOfficialModulePackageFromRoot(packageRoot, entry.from, entry.id)
+      modulePackage = resolveInstalledOfficialModulePackage(resolver, entry.from, entry.id)
     } catch {
       continue
     }

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

@@ -1,9 +1,12 @@
+import { sourceHasDefaultExport, sourceExportedHttpMethods } from './source-exports'
 import fs from 'node:fs'
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { VariableDeclarationKind, type WriterFunction } from 'ts-morph'
 import ts from 'typescript-js'
 import type { ModuleEntry, PackageResolver } from '../resolver'
+import { getEnabledModuleIdentities } from '../module-identity'
+import { getModuleRequirementHint, resolveModuleRequirement } from '@open-mercato/shared/modules/module-locators'
 import {
   DEV_SUPERVISOR_MANIFEST_FILE,
   DEV_SUPERVISOR_MANIFEST_VERSION,
@@ -93,6 +96,7 @@ export interface ModuleRegistryOptions {
 interface ModuleRegistryDiscovery {
   enabled: ModuleEntry[]
   modules: ModuleRegistryDiscoveryEntry[]
+  identities: ReturnType<typeof getEnabledModuleIdentities>
   getStructureChecksum: () => string
 }
 
@@ -1158,44 +1162,11 @@ function inferScriptKind(filePath: string): ts.ScriptKind {
 }
 
 function hasDefaultExport(sourceFile: string): boolean {
-  let source = ''
   try {
-    source = fs.readFileSync(sourceFile, 'utf8')
+    return sourceHasDefaultExport(sourceFile, fs.readFileSync(sourceFile, 'utf8'))
   } catch {
     return false
   }
-
-  const parsed = ts.createSourceFile(
-    sourceFile,
-    source,
-    ts.ScriptTarget.Latest,
-    true,
-    inferScriptKind(sourceFile),
-  )
-
-  for (const statement of parsed.statements) {
-    if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
-      return true
-    }
-
-    if (
-      ts.isExportDeclaration(statement)
-      && statement.exportClause
-      && ts.isNamedExports(statement.exportClause)
-      && statement.exportClause.elements.some(
-        (element) => element.name.text === 'default' || element.propertyName?.text === 'default',
-      )
-    ) {
-      return true
-    }
-
-    const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined
-    if (modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword)) {
-      return true
-    }
-  }
-
-  return false
 }
 
 function requiresRuntimePageMetadataFromSourceFile(sourceFile: string): boolean {
@@ -1737,66 +1708,11 @@ async function resolveModuleRequiresFromIndexFile(indexFileAbsolutePath: string)
 }
 
 function detectExportedHttpMethods(sourceFile: string): HttpMethod[] {
-  let source = ''
   try {
-    source = fs.readFileSync(sourceFile, 'utf8')
+    return sourceExportedHttpMethods(fs.readFileSync(sourceFile, 'utf8'))
   } catch {
     return []
   }
-
-  const knownMethods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as HttpMethod[]
-  const exportedMethods = new Set<HttpMethod>()
-  const collectKnownMethods = (rawSpecifiers: string[], opts?: { useExportedAlias?: boolean; useDestructuredProperty?: boolean }) => {
-    for (const specifier of rawSpecifiers) {
-      const trimmed = specifier.trim()
-      if (!trimmed) continue
-
-      let candidate = trimmed
-      if (opts?.useExportedAlias) {
-        candidate = trimmed.split(/\s+as\s+/i).pop()?.trim() ?? trimmed
-      }
-      if (opts?.useDestructuredProperty) {
-        candidate = trimmed.split(':')[0]?.trim() ?? trimmed
-      }
-
-      if (knownMethods.includes(candidate as HttpMethod)) {
-        exportedMethods.add(candidate as HttpMethod)
-      }
-    }
-  }
-
-  for (const method of knownMethods) {
-    const pattern = new RegExp(`export\\s+(?:async\\s+)?function\\s+${method}\\b|export\\s+(?:const|let|var)\\s+${method}\\b`)
-    if (pattern.test(source)) {
-      exportedMethods.add(method)
-    }
-  }
-
-  const reExportPattern = /export\s*{([^}]+)}/g
-  for (const match of source.matchAll(reExportPattern)) {
-    const exportBlock = match[1] ?? ''
-    collectKnownMethods(
-      exportBlock
-      .split(',')
-      .map((part) => part.trim())
-      .filter((part) => part.length > 0),
-      { useExportedAlias: true },
-    )
-  }
-
-  const destructuredExportPattern = /export\s+(?:const|let|var)\s*{([^}]+)}/g
-  for (const match of source.matchAll(destructuredExportPattern)) {
-    const exportBlock = match[1] ?? ''
-    collectKnownMethods(
-      exportBlock
-        .split(',')
-        .map((part) => part.trim())
-        .filter((part) => part.length > 0),
-      { useDestructuredProperty: true },
-    )
-  }
-
-  return knownMethods.filter((method) => exportedMethods.has(method))
 }
 
 function buildPageRouteProps(metaExpr: string, routePath: string): string {
@@ -2062,12 +1978,22 @@ async function createModuleRegistryDiscovery(
 ): Promise<ModuleRegistryDiscovery> {
   resetConventionWarnings()
   const enabled = resolver.loadEnabledModules()
+  const rootsByEntry = new Map<ModuleEntry, ModuleRoots>()
+  const getModulePaths = (entry: ModuleEntry): ModuleRoots => {
+    let roots = rootsByEntry.get(entry)
+    if (!roots) {
+      roots = resolver.getModulePaths(entry)
+      rootsByEntry.set(entry, roots)
+    }
+    return roots
+  }
+  const identities = getEnabledModuleIdentities({ ...resolver, getModulePaths }, enabled)
   const modules: ModuleRegistryDiscoveryEntry[] = []
   const trackedRoots = new Set<string>()
 
   for (const entry of enabled) {
     const modId = entry.id
-    const roots = resolver.getModulePaths(entry)
+    const roots = getModulePaths(entry)
     verifyThirdPartyModuleShape(entry, roots.pkgBase)
     const rawImps = resolver.getModuleImportBase(entry)
     const appImportBase = entry.from === '@app' ? `../../src/modules/${modId}` : rawImps.appBase
@@ -2110,6 +2036,7 @@ async function createModuleRegistryDiscovery(
   return {
     enabled,
     modules,
+    identities,
     getStructureChecksum: () => structureChecksum ??= calculateStructureChecksum(Array.from(trackedRoots)),
   }
 }
@@ -4240,10 +4167,12 @@ async function generateModuleRegistryFromDiscovery(options: ModuleRegistryRender
   })
   // Validate module dependencies declared via ModuleInfo.requires
   {
-    const enabledIds = new Set(enabled.map((e) => e.id))
+    const identities = discovery.identities
     const problems: string[] = []
+    const missingRequirements = new Set<string>()
     for (const [modId, reqs] of requiresByModule.entries()) {
-      const missing = reqs.filter((r) => !enabledIds.has(r))
+      const missing = reqs.filter((requirement) => !resolveModuleRequirement(requirement, identities))
+      for (const requirement of missing) missingRequirements.add(requirement)
       if (missing.length) {
         problems.push(`- Module "${modId}" requires: ${missing.join(', ')}`)
       }
@@ -4251,12 +4180,7 @@ async function generateModuleRegistryFromDiscovery(options: ModuleRegistryRender
     if (problems.length) {
       console.error('\nModule dependency check failed:')
       for (const p of problems) console.error(p)
-      console.error('\nFix: Enable required module(s) in src/modules.ts. Example:')
-      console.error(
-        '  export const enabledModules = [ { id: \'' +
-          Array.from(new Set(requiresByModule.values()).values()).join("' }, { id: '") +
-          "' } ]"
-      )
+      for (const requirement of missingRequirements) console.error(`Fix: ${getModuleRequirementHint(requirement)}`)
       process.exit(1)
     }
   }
@@ -4720,10 +4644,12 @@ async function generateModuleRegistryAppFromDiscovery(options: ModuleRegistryRen
   })
 
   {
-    const enabledIds = new Set(enabled.map((e) => e.id))
+    const identities = discovery.identities
     const problems: string[] = []
+    const missingRequirements = new Set<string>()
     for (const [modId, reqs] of requiresByModule.entries()) {
-      const missing = reqs.filter((r) => !enabledIds.has(r))
+      const missing = reqs.filter((requirement) => !resolveModuleRequirement(requirement, identities))
+      for (const requirement of missing) missingRequirements.add(requirement)
       if (missing.length) {
         problems.push(`- Module "${modId}" requires: ${missing.join(', ')}`)
       }
@@ -4731,12 +4657,7 @@ async function generateModuleRegistryAppFromDiscovery(options: ModuleRegistryRen
     if (problems.length) {
       console.error('\nModule dependency check failed:')
       for (const p of problems) console.error(p)
-      console.error('\nFix: Enable required module(s) in src/modules.ts. Example:')
-      console.error(
-        '  export const enabledModules = [ { id: \'' +
-          Array.from(new Set(requiresByModule.values()).values()).join("' }, { id: '") +
-          "' } ]"
-      )
+      for (const requirement of missingRequirements) console.error(`Fix: ${getModuleRequirementHint(requirement)}`)
       process.exit(1)
     }
   }
@@ -5109,10 +5030,12 @@ async function generateModuleRegistryCliFromDiscovery(options: ModuleRegistryRen
 
   // Validate module dependencies declared via ModuleInfo.requires
   {
-    const enabledIds = new Set(enabled.map((e) => e.id))
+    const identities = discovery.identities
     const problems: string[] = []
+    const missingRequirements = new Set<string>()
     for (const [modId, reqs] of requiresByModule.entries()) {
-      const missing = reqs.filter((r) => !enabledIds.has(r))
+      const missing = reqs.filter((requirement) => !resolveModuleRequirement(requirement, identities))
+      for (const requirement of missing) missingRequirements.add(requirement)
       if (missing.length) {
         problems.push(`- Module "${modId}" requires: ${missing.join(', ')}`)
       }
@@ -5120,12 +5043,7 @@ async function generateModuleRegistryCliFromDiscovery(options: ModuleRegistryRen
     if (problems.length) {
       console.error('\nModule dependency check failed:')
       for (const p of problems) console.error(p)
-      console.error('\nFix: Enable required module(s) in src/modules.ts. Example:')
-      console.error(
-        '  export const enabledModules = [ { id: \'' +
-          Array.from(new Set(requiresByModule.values()).values()).join("' }, { id: '") +
-          "' } ]"
-      )
+      for (const requirement of missingRequirements) console.error(`Fix: ${getModuleRequirementHint(requirement)}`)
       process.exit(1)
     }
   }

package/src/lib/generators/openapi.ts

@@ -9,6 +9,7 @@
 import * as fs from 'node:fs'
 import * as path from 'node:path'
 import type { ModuleEntry, PackageResolver } from '../resolver'
+import { getEnabledModuleIdentities } from '../module-identity'
 import { isModuleRouteFile } from './scanner'
 import {
   calculateChecksum,
@@ -671,6 +672,8 @@ export async function generateOpenApi(options: GenerateOpenApiOptions): Promise<
   const checksumFile = path.join(outputDir, 'openapi.generated.checksum')
   const inputManifestFile = path.join(outputDir, 'openapi.generated.inputs.json')
 
+  getEnabledModuleIdentities(resolver, resolver.loadEnabledModules())
+
   // Ensure output directory exists
   if (!fs.existsSync(outputDir)) {
     fs.mkdirSync(outputDir, { recursive: true })

package/src/lib/generators/source-exports.ts

@@ -0,0 +1,93 @@
+import ts from 'typescript-js'
+
+export function sourceHasDefaultExport(sourceFile: string, source: string): boolean {
+  const parsed = ts.createSourceFile(
+    sourceFile,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    sourceFile.endsWith('.tsx') ? ts.ScriptKind.TSX : sourceFile.endsWith('.jsx') ? ts.ScriptKind.JSX : sourceFile.endsWith('.js') ? ts.ScriptKind.JS : ts.ScriptKind.TS,
+  )
+
+  for (const statement of parsed.statements) {
+    if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+      return true
+    }
+
+    if (
+      ts.isExportDeclaration(statement)
+      && statement.exportClause
+      && ts.isNamedExports(statement.exportClause)
+      && statement.exportClause.elements.some(
+        (element) => element.name.text === 'default' || element.propertyName?.text === 'default',
+      )
+    ) {
+      return true
+    }
+
+    const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined
+    if (modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword)) {
+      return true
+    }
+  }
+
+  return false
+}
+
+type SourceHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+
+export function sourceExportedHttpMethods(source: string): SourceHttpMethod[] {
+  const knownMethods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as SourceHttpMethod[]
+  const exportedMethods = new Set<SourceHttpMethod>()
+  const collectKnownMethods = (rawSpecifiers: string[], opts?: { useExportedAlias?: boolean; useDestructuredProperty?: boolean }) => {
+    for (const specifier of rawSpecifiers) {
+      const trimmed = specifier.trim()
+      if (!trimmed) continue
+
+      let candidate = trimmed
+      if (opts?.useExportedAlias) {
+        candidate = trimmed.split(/\s+as\s+/i).pop()?.trim() ?? trimmed
+      }
+      if (opts?.useDestructuredProperty) {
+        candidate = trimmed.split(':')[0]?.trim() ?? trimmed
+      }
+
+      if (knownMethods.includes(candidate as SourceHttpMethod)) {
+        exportedMethods.add(candidate as SourceHttpMethod)
+      }
+    }
+  }
+
+  for (const method of knownMethods) {
+    const pattern = new RegExp(`export\\s+(?:async\\s+)?function\\s+${method}\\b|export\\s+(?:const|let|var)\\s+${method}\\b`)
+    if (pattern.test(source)) {
+      exportedMethods.add(method)
+    }
+  }
+
+  const reExportPattern = /export\s*{([^}]+)}/g
+  for (const match of source.matchAll(reExportPattern)) {
+    const exportBlock = match[1] ?? ''
+    collectKnownMethods(
+      exportBlock
+      .split(',')
+      .map((part) => part.trim())
+      .filter((part) => part.length > 0),
+      { useExportedAlias: true },
+    )
+  }
+
+  const destructuredExportPattern = /export\s+(?:const|let|var)\s*{([^}]+)}/g
+  for (const match of source.matchAll(destructuredExportPattern)) {
+    const exportBlock = match[1] ?? ''
+    collectKnownMethods(
+      exportBlock
+        .split(',')
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0),
+      { useDestructuredProperty: true },
+    )
+  }
+
+  return knownMethods.filter((method) => exportedMethods.has(method))
+}

package/src/lib/init-summary.ts

@@ -0,0 +1,54 @@
+type InitSummaryUser = { icon: string; label: string; email: string; password: string }
+
+type InitSummaryOptions = {
+  users: InitSummaryUser[]
+  autoStart: boolean
+  columns?: number
+  color?: boolean
+}
+
+const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' })
+const panelStyle = '\u001b[48;2;57;62;70m\u001b[38;2;238;238;238m'
+const reset = '\u001b[0m'
+
+function cellWidth(value: string): number {
+  if (/\p{Extended_Pictographic}|\p{Regional_Indicator}|[\u1100-\u115f\u2329\u232a\u2e80-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe10-\ufe19\ufe30-\ufe6f\uff01-\uff60\uffe0-\uffe6]/u.test(value)) return 2
+  return /^\p{Mark}+$/u.test(value) ? 0 : 1
+}
+
+function wrapLine(line: string, width: number): string[] {
+  const wrapped: string[] = []
+  let current = ''
+  let currentWidth = 0
+  for (const { segment } of segmenter.segment(line)) {
+    const segmentWidth = cellWidth(segment)
+    if (currentWidth + segmentWidth > width && current) {
+      wrapped.push(current)
+      current = ''
+      currentWidth = 0
+    }
+    current += segment
+    currentWidth += segmentWidth
+  }
+  wrapped.push(current)
+  return wrapped
+}
+
+export function formatInitSummary({ users, autoStart, columns = 80, color = false }: InitSummaryOptions): string[] {
+  const width = Number.isFinite(columns) && columns >= 8 ? Math.floor(columns) : 80
+  const lines = ['', '🔑 DEVELOPMENT ACCOUNTS', '']
+  for (const user of users) {
+    lines.push(`${user.icon} ${user.label}`, `   Email:     ${user.email}`, `   Password:  ${user.password}`, '')
+  }
+  lines.push(...(autoStart
+    ? ['🚀 The dev server will start automatically.', '   Next time, run: yarn dev']
+    : ['🚀 Start the dev server: yarn dev']))
+  lines.push('')
+  const rule = '━'.repeat(width)
+  const content = lines.flatMap((line) => wrapLine(line, width - 4).map((part) => `  ${part}`))
+  return [rule, ...content, rule].map((line) => {
+    if (!color) return line
+    const visibleWidth = [...segmenter.segment(line)].reduce((total, { segment }) => total + cellWidth(segment), 0)
+    return `${panelStyle}${line}${' '.repeat(Math.max(0, width - visibleWidth))}${reset}`
+  })
+}

package/src/lib/module-github.ts

@@ -0,0 +1,109 @@
+import { execFileSync } from 'node:child_process'
+import { assertModulePackageExports, parsePackageNameFromSpec } from './module-package'
+
+export type GithubModuleTarget = {
+  packageName: string
+  packageSpec: string
+  moduleIds: string[]
+  locator: string
+}
+
+function githubApi(endpoint: string, cwd: string): unknown {
+  try {
+    return JSON.parse(execFileSync('gh', ['api', endpoint], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60_000, maxBuffer: 16 * 1024 * 1024 })) as unknown
+  } catch {
+    throw new Error(`Cannot read GitHub repository metadata at ${endpoint}. Check the locator and access with "gh auth login". No package was installed.`)
+  }
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+}
+
+export function resolveGithubModuleTarget(input: string, cwd: string, options: { moduleId?: string; enabledModules?: readonly { id: string; from?: string }[] } = {}): GithubModuleTarget {
+  let normalized = input.trim()
+    .replace(/^(?:(?:git\+)?https?:\/\/github\.com\/)+/i, '')
+    .replace(/^github\.com\//i, '')
+    .replace(/^github:/i, '')
+    .replace(/^git@github\.com:/i, '')
+    .replace(/^(?:git\+)?ssh:\/\/(?:git@)?github\.com\//i, '')
+  const hash = normalized.indexOf('#')
+  const separator = hash < 0 ? normalized.lastIndexOf('@') : hash
+  const requestedRef = separator < 0 ? undefined : normalized.slice(separator + 1)
+  if (requestedRef !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._/-]{0,254}$/.test(requestedRef)) {
+    throw new Error('Invalid GitHub revision. No package was installed.')
+  }
+  normalized = (separator < 0 ? normalized : normalized.slice(0, separator)).replace(/\/$/, '').replace(/\.git$/i, '')
+  if (/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(normalized)) {
+    const login = record(githubApi('user', cwd)).login
+    if (typeof login !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9-]*$/.test(login)) {
+      throw new Error('Cannot determine your GitHub account. Use owner/repository or a full GitHub URL.')
+    }
+    normalized = `${login}/${normalized}`
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/.test(normalized)) {
+    throw new Error('Unsupported GitHub locator. Use github:owner/repository, a repository URL, or owner/repository.')
+  }
+  const repository = normalized.toLowerCase()
+  const ref = requestedRef ?? record(githubApi(`repos/${repository}`, cwd)).default_branch
+  if (typeof ref !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._/-]{0,254}$/.test(ref)) {
+    throw new Error('Cannot determine a valid GitHub revision. Use a repository locator with #branch, #tag, or #commit.')
+  }
+  const sha = record(githubApi(`repos/${repository}/commits/${encodeURIComponent(ref)}`, cwd)).sha
+  if (typeof sha !== 'string' || !/^[0-9a-f]{40}$/.test(sha)) {
+    throw new Error(`Cannot resolve ${repository} to an immutable commit. No package was installed.`)
+  }
+  const contents = record(githubApi(`repos/${repository}/contents/package.json?ref=${sha}`, cwd))
+  if (contents.encoding !== 'base64' || typeof contents.content !== 'string') {
+    throw new Error(`Repository ${repository} has no readable package.json. No package was installed.`)
+  }
+  let manifest: Record<string, unknown>
+  try {
+    manifest = record(JSON.parse(Buffer.from(contents.content, 'base64').toString('utf8')))
+  } catch {
+    throw new Error(`Repository ${repository} has invalid package.json. No package was installed.`)
+  }
+  const packageName = manifest.name
+  if (typeof packageName !== 'string' || !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(packageName) || parsePackageNameFromSpec(packageName) !== packageName) {
+    throw new Error(`Repository ${repository} has no valid npm package name. No package was installed.`)
+  }
+  const tree = record(githubApi(`repos/${repository}/git/trees/${sha}?recursive=1`, cwd))
+  if (!Array.isArray(tree.tree) || tree.truncated === true) {
+    throw new Error(`Cannot enumerate modules in ${repository}. No package was installed.`)
+  }
+  const moduleIds = Array.from(new Set(tree.tree.flatMap((entry: unknown) => {
+    const filePath = record(entry).path
+    const match = typeof filePath === 'string' ? /^src\/modules\/([a-z0-9]+(?:_[a-z0-9]+)*)\/index\.ts$/.exec(filePath) : null
+    return match ? [match[1]] : []
+  })))
+  if (moduleIds.length === 0) throw new Error(`Repository ${repository} has no module descriptors in src/modules/. No package was installed.`)
+  const files = tree.tree.flatMap((entry: unknown) => {
+    const filePath = record(entry).path
+    if (typeof filePath !== 'string') return []
+    const compiledPath = /^src\/modules\/.+\.tsx?$/.test(filePath) ? filePath.replace(/^src\//, 'dist/').replace(/\.tsx?$/, '.js') : undefined
+    return compiledPath ? [filePath, compiledPath] : [filePath]
+  })
+  const requiredModuleIds = new Set([
+    ...(options.moduleId ? [options.moduleId] : moduleIds.length === 1 ? moduleIds : []),
+    ...(options.enabledModules ?? []).filter((entry) => (entry.from ?? '@open-mercato/core') === packageName).map((entry) => entry.id),
+  ])
+  const sourceCache = new Map<string, string>()
+  const readSource = (relativePath: string): string => {
+    const cached = sourceCache.get(relativePath)
+    if (cached !== undefined) return cached
+    const encodedPath = relativePath.split('/').map(encodeURIComponent).join('/')
+    const file = record(githubApi(`repos/${repository}/contents/${encodedPath}?ref=${sha}`, cwd))
+    if (file.encoding !== 'base64' || typeof file.content !== 'string' || file.content.length > 2 * 1024 * 1024) {
+      throw new Error(`Cannot inspect module source in ${repository} at the selected commit. No package was installed.`)
+    }
+    const source = Buffer.from(file.content, 'base64').toString('utf8')
+    if (Buffer.byteLength(source, 'utf8') > 1024 * 1024) throw new Error(`Module source inspection limit exceeded in ${repository}. No package was installed.`)
+    sourceCache.set(relativePath, source)
+    return source
+  }
+  for (const moduleId of requiredModuleIds) {
+    if (!moduleIds.includes(moduleId)) continue
+    assertModulePackageExports(manifest, packageName, moduleId, files, readSource)
+  }
+  return { packageName, packageSpec: `${packageName}@github:${repository}#${sha}`, moduleIds, locator: `github:${repository}` }
+}