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

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

@@ -0,0 +1,279 @@
+import { expect, test } from '@playwright/test'
+import { execFileSync, spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..', '..')
+const cliBin = path.join(repoRoot, 'packages', 'cli', 'dist', 'bin.js')
+
+function writeFile(filePath: string, content: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, content)
+}
+
+function createPackage(packageRoot: string, packageName: string, moduleIds: string[]): void {
+  writeFile(path.join(packageRoot, 'package.json'), JSON.stringify({ name: packageName, version: '0.4.7', type: 'module' }))
+  for (const moduleId of moduleIds) {
+    writeFile(path.join(packageRoot, 'src', 'modules', moduleId, 'index.ts'), `export const metadata = { id: '${moduleId}', title: '${moduleId}', ejectable: true }\n`)
+    writeFile(path.join(packageRoot, 'dist', 'modules', moduleId, 'index.js'), `export const metadata = { id: '${moduleId}', title: '${moduleId}', ejectable: true }\n`)
+    writeFile(path.join(packageRoot, 'src', 'modules', moduleId, 'di.ts'), 'export function register() {}\n')
+    writeFile(path.join(packageRoot, 'dist', 'modules', moduleId, 'di.js'), 'export function register() {}\n')
+  }
+}
+
+function createApp(appDir: string, dependencies: Record<string, string> = {}): void {
+  writeFile(path.join(appDir, 'package.json'), JSON.stringify({ name: 'module-collision-integration', private: true, dependencies: { '@open-mercato/core': '0.4.7', ...dependencies } }))
+  writeFile(path.join(appDir, 'yarn.lock'), '')
+  writeFile(path.join(appDir, 'src', 'modules.ts'), 'export const enabledModules = []\n')
+  createPackage(path.join(appDir, 'node_modules', '@open-mercato', 'core'), '@open-mercato/core', [])
+}
+
+function runMercato(args: string[], appDir: string, environment: NodeJS.ProcessEnv = {}): { status: number | null; output: string } {
+  const result = spawnSync(process.execPath, [cliBin, ...args], {
+    cwd: appDir,
+    encoding: 'utf8',
+    env: { ...process.env, FORCE_COLOR: '0', NODE_NO_WARNINGS: '1', ...environment },
+  })
+  if (result.error) throw result.error
+  return { status: result.status, output: `${result.stdout}\n${result.stderr}` }
+}
+
+function installCommandStubs(appDir: string, candidateName?: string, candidateModuleId?: string): NodeJS.ProcessEnv {
+  const executableDir = path.join(appDir, 'bin')
+  const marker = path.join(appDir, 'yarn-invoked')
+  const yarnPath = path.join(executableDir, process.platform === 'win32' ? 'yarn.cmd' : 'yarn')
+  const yarnScript = `require('node:fs').writeFileSync(${JSON.stringify(marker)}, 'invoked'); process.exit(1)\n`
+  writeFile(yarnPath, process.platform === 'win32'
+    ? `@"${process.execPath}" "%~dp0yarn-stub.cjs" %*\r\n`
+    : `#!${process.execPath}\n${yarnScript}`)
+  writeFile(path.join(executableDir, 'yarn-stub.cjs'), yarnScript)
+  fs.chmodSync(yarnPath, 0o755)
+  if (candidateName && candidateModuleId) {
+    const manifest = Buffer.from(JSON.stringify({ name: candidateName })).toString('base64')
+    const ghScript = `const endpoint = process.argv[3] || ''
+const value = endpoint === 'user' ? { login: 'candidate' }
+  : endpoint.includes('/commits/') ? { sha: 'a'.repeat(40) }
+  : endpoint.includes('/contents/') ? { encoding: 'base64', content: ${JSON.stringify(manifest)} }
+  : endpoint.includes('/git/trees/') ? { tree: [{ path: 'src/modules/${candidateModuleId}/index.ts' }, { path: 'dist/modules/${candidateModuleId}/index.js' }] }
+  : { default_branch: 'main' }
+process.stdout.write(JSON.stringify(value))\n`
+    const ghPath = path.join(executableDir, process.platform === 'win32' ? 'gh.cmd' : 'gh')
+    writeFile(ghPath, process.platform === 'win32'
+      ? `@"${process.execPath}" "%~dp0gh-stub.cjs" %*\r\n`
+      : `#!${process.execPath}\n${ghScript}`)
+    writeFile(path.join(executableDir, 'gh-stub.cjs'), ghScript)
+    fs.chmodSync(ghPath, 0o755)
+  }
+  return { PATH: executableDir + path.delimiter + process.env.PATH }
+}
+
+function snapshotDirectory(directory: string): Record<string, string> {
+  if (!fs.existsSync(directory)) return {}
+  const files: Record<string, string> = {}
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const fullPath = path.join(directory, entry.name)
+    if (entry.isDirectory()) {
+      for (const [relativePath, content] of Object.entries(snapshotDirectory(fullPath))) files[path.join(entry.name, relativePath)] = content
+    } else {
+      files[entry.name] = fs.readFileSync(fullPath).toString('base64')
+    }
+  }
+  return files
+}
+
+test.describe('TC-INT-009: CLI source collision lifecycle safeguards', () => {
+  for (const kind of ['directory', 'archive']) {
+    test(`rejects a local ${kind} with unknown provenance before replacing an active npm binding`, () => {
+      const root = fs.mkdtempSync(path.join(os.tmpdir(), 'mercato-file-origin-'))
+      const appDir = path.join(root, 'app')
+      try {
+        const binding = '@publisher/consents'
+        createApp(appDir, { [binding]: '0.4.7' })
+        createPackage(path.join(appDir, 'node_modules', binding), binding, ['consents'])
+        const packageRoot = path.join(root, 'package')
+        createPackage(packageRoot, binding, ['consents'])
+        if (kind === 'archive') execFileSync('tar', ['-czf', path.join(root, 'candidate.tgz'), '-C', root, 'package'])
+        const modulesSource = `export const enabledModules = [{ id: 'consents', from: '${binding}', locator: 'npm:${binding}' }]\n`
+        writeFile(path.join(appDir, 'src', 'modules.ts'), modulesSource)
+        const manifestBefore = fs.readFileSync(path.join(appDir, 'package.json'), 'utf8')
+        const installedBefore = snapshotDirectory(path.join(appDir, 'node_modules'))
+        const environment = installCommandStubs(appDir)
+        const locator = kind === 'archive' ? 'file:../candidate.tgz' : 'file:../package'
+        const result = runMercato(['module', 'add', `${binding}@${locator}`, '--eject', '--allow-third-party'], appDir, environment)
+
+        expect(result.status, result.output).not.toBe(0)
+        expect(result.output).toContain('Package binding collision')
+        expect(result.output).toContain('unknown origin')
+        expect(result.output).toContain('consents')
+        expect(fs.existsSync(path.join(appDir, 'yarn-invoked'))).toBe(false)
+        expect(fs.readFileSync(path.join(appDir, 'src', 'modules.ts'), 'utf8')).toBe(modulesSource)
+        expect(fs.readFileSync(path.join(appDir, 'package.json'), 'utf8')).toBe(manifestBefore)
+        expect(snapshotDirectory(path.join(appDir, 'node_modules'))).toEqual(installedBefore)
+        expect(fs.existsSync(path.join(appDir, 'src', 'modules', 'consents'))).toBe(false)
+        expect(fs.existsSync(path.join(appDir, '.mercato', 'generated'))).toBe(false)
+      } finally { fs.rmSync(root, { recursive: true, force: true }) }
+    })
+  }
+
+  test('rejects a GitHub replacement of an active binding even when the selected module ID differs', () => {
+    const appDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mercato-binding-collision-'))
+    try {
+      const binding = '@publisher/shared-package'
+      createApp(appDir, { [binding]: 'github:existing/provider#main' })
+      createPackage(path.join(appDir, 'node_modules', binding), binding, ['active_module'])
+      const modulesSource = `export const enabledModules = [{ id: 'active_module', from: '${binding}', locator: 'github:existing/provider', packageName: '${binding}' }]\n`
+      writeFile(path.join(appDir, 'src', 'modules.ts'), modulesSource)
+      const manifestBefore = fs.readFileSync(path.join(appDir, 'package.json'), 'utf8')
+      const environment = installCommandStubs(appDir, binding, 'candidate_module')
+      const result = runMercato(['module', 'add', 'github:candidate/provider', '--allow-third-party'], appDir, environment)
+
+      expect(result.status, result.output).not.toBe(0)
+      expect(result.output).toContain('active_module')
+      expect(result.output).toContain(binding)
+      expect(result.output).toContain('github:existing/provider')
+      expect(result.output).toContain('github:candidate/provider')
+      expect(fs.existsSync(path.join(appDir, 'yarn-invoked'))).toBe(false)
+      expect(fs.readFileSync(path.join(appDir, 'src', 'modules.ts'), 'utf8')).toBe(modulesSource)
+      expect(fs.readFileSync(path.join(appDir, 'package.json'), 'utf8')).toBe(manifestBefore)
+      expect(fs.existsSync(path.join(appDir, 'src', 'modules', 'candidate_module'))).toBe(false)
+    } finally {
+      fs.rmSync(appDir, { recursive: true, force: true })
+    }
+  })
+
+  test('rejects an npm file package runtime ID collision before invoking Yarn or copying sources', () => {
+    const appDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mercato-file-collision-'))
+    try {
+      createApp(appDir)
+      const candidateDir = path.join(appDir, 'candidate')
+      createPackage(candidateDir, '@publisher/candidate', ['consents'])
+      const modulesSource = "export const enabledModules = [{ id: 'consents', from: '@app', locator: 'github:existing/consents' }]\n"
+      writeFile(path.join(appDir, 'src', 'modules.ts'), modulesSource)
+      writeFile(path.join(appDir, 'src', 'modules', 'consents', 'index.ts'), 'export const metadata = { ejectable: true }\n')
+      const sourceBefore = snapshotDirectory(path.join(appDir, 'src'))
+      const manifestBefore = fs.readFileSync(path.join(appDir, 'package.json'), 'utf8')
+      const result = runMercato(['module', 'add', '@publisher/candidate@file:./candidate', '--allow-third-party', '--eject'], appDir, installCommandStubs(appDir))
+
+      expect(result.status, result.output).not.toBe(0)
+      expect(result.output).toContain('consents')
+      expect(result.output).toMatch(/collision|already registered|conflict/i)
+      expect(fs.existsSync(path.join(appDir, 'yarn-invoked'))).toBe(false)
+      expect(snapshotDirectory(path.join(appDir, 'src'))).toEqual(sourceBefore)
+      expect(fs.readFileSync(path.join(appDir, 'package.json'), 'utf8')).toBe(manifestBefore)
+    } finally {
+      fs.rmSync(appDir, { recursive: true, force: true })
+    }
+  })
+
+  test('every generate command rejects duplicate effective registrations before changing existing output', () => {
+    const appDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mercato-generate-duplicates-'))
+    try {
+      createApp(appDir)
+      writeFile(path.join(appDir, 'src', 'modules.ts'), "export const enabledModules = [{ id: 'consents', from: '@app' }]\nif (process.env.COLLISION_DUPLICATE_ENABLED === 'true') enabledModules.push({ id: 'consents', from: '@app' })\n")
+      writeFile(path.join(appDir, 'src', 'modules', 'consents', 'index.ts'), 'export const metadata = {}\n')
+      const outputDir = path.join(appDir, '.mercato', 'generated')
+      for (const file of ['entities.ids.generated.ts', 'modules.generated.ts', 'entities.generated.ts', 'di.generated.ts', 'module-package-sources.css']) writeFile(path.join(outputDir, file), 'preserved output\n')
+      const before = snapshotDirectory(outputDir)
+
+      for (const command of ['all', 'entity-ids', 'registry', 'entities', 'di']) {
+        const result = runMercato(['generate', command, '--quiet'], appDir, { COLLISION_DUPLICATE_ENABLED: 'true' })
+        expect(result.status, `${command}: ${result.output}`).not.toBe(0)
+        expect(result.output).toContain("Duplicate enabled module ID 'consents'")
+        expect(snapshotDirectory(outputDir), command).toEqual(before)
+      }
+      const singleProvider = runMercato(['generate', 'all', '--quiet'], appDir, { COLLISION_DUPLICATE_ENABLED: 'false' })
+      expect(singleProvider.status, singleProvider.output).toBe(0)
+    } finally {
+      fs.rmSync(appDir, { recursive: true, force: true })
+    }
+  })
+
+  test('an installed alias generates binding imports, ejects with canonical provenance, and disables cleanly', () => {
+    const appDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mercato-alias-lifecycle-'))
+    try {
+      const binding = 'consents_candidate'
+      const canonicalName = '@publisher/consents'
+      createApp(appDir, { [binding]: `npm:${canonicalName}@0.4.7` })
+      const packageRoot = path.join(appDir, 'node_modules', binding)
+      createPackage(packageRoot, canonicalName, ['consents', 'sibling'])
+      writeFile(path.join(packageRoot, 'src', 'modules', 'consents', 'sibling.ts'), "export { metadata } from '../sibling'\n")
+      const enabled = runMercato(['module', 'enable', binding, '--module', 'consents', '--allow-third-party'], appDir)
+      expect(enabled.status, enabled.output).toBe(0)
+      const outputDir = path.join(appDir, '.mercato', 'generated')
+      const modulesSource = fs.readFileSync(path.join(appDir, 'src', 'modules.ts'), 'utf8')
+      expect(modulesSource).toContain(`from: '${binding}'`)
+      expect(modulesSource).toContain(`packageName: '${canonicalName}'`)
+      expect(fs.readFileSync(path.join(outputDir, 'di.generated.ts'), 'utf8')).toContain(`${binding}/modules/consents/di`)
+      expect(fs.readFileSync(path.join(outputDir, 'module-package-sources.css'), 'utf8')).toContain(`node_modules/${binding}/src/`)
+
+      const ejected = runMercato(['module', 'eject', 'consents'], appDir)
+      expect(ejected.status, ejected.output).toBe(0)
+      const ejectedSource = fs.readFileSync(path.join(appDir, 'src', 'modules.ts'), 'utf8')
+      expect(ejectedSource).toContain("from: '@app'")
+      expect(ejectedSource).toContain(`packageName: '${canonicalName}'`)
+      expect(ejectedSource).toContain(`locator: 'npm:${canonicalName}'`)
+      expect(fs.readFileSync(path.join(appDir, 'src', 'modules', 'consents', 'sibling.ts'), 'utf8')).toContain(`${binding}/modules/sibling`)
+
+      writeFile(path.join(appDir, 'src', 'modules.ts'), 'export const enabledModules = []\n')
+      const disabled = runMercato(['generate', 'all', '--quiet'], appDir)
+      expect(disabled.status, disabled.output).toBe(0)
+      expect(fs.readFileSync(path.join(outputDir, 'di.generated.ts'), 'utf8')).not.toContain('consents')
+      expect(fs.readFileSync(path.join(outputDir, 'module-package-sources.css'), 'utf8')).toBe('')
+      expect(fs.existsSync(path.join(packageRoot, 'package.json'))).toBe(true)
+      expect(fs.existsSync(path.join(appDir, 'src', 'modules', 'consents', 'index.ts'))).toBe(true)
+    } finally {
+      fs.rmSync(appDir, { recursive: true, force: true })
+    }
+  })
+
+  test('missing alias exports fail enable and direct eject before source or config changes', () => {
+    const appDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mercato-alias-exports-'))
+    try {
+      const binding = 'consents_candidate'
+      createApp(appDir, { [binding]: 'npm:@publisher/consents@0.4.7' })
+      const packageRoot = path.join(appDir, 'node_modules', binding)
+      createPackage(packageRoot, '@publisher/consents', ['consents'])
+      writeFile(path.join(packageRoot, 'package.json'), JSON.stringify({ name: '@publisher/consents', exports: { '.': './dist/modules/consents/index.js' } }))
+      const configPath = path.join(appDir, 'src', 'modules.ts')
+      const emptyConfig = fs.readFileSync(configPath, 'utf8')
+
+      const enabled = runMercato(['module', 'enable', binding, '--module', 'consents', '--eject', '--allow-third-party'], appDir)
+      expect(enabled.status, enabled.output).not.toBe(0)
+      expect(enabled.output).toContain(`${binding}/modules/consents/`)
+      expect(fs.readFileSync(configPath, 'utf8')).toBe(emptyConfig)
+      expect(fs.existsSync(path.join(appDir, 'src', 'modules', 'consents'))).toBe(false)
+
+      const registeredConfig = `export const enabledModules = [{ id: 'consents', from: '${binding}' }]\n`
+      writeFile(configPath, registeredConfig)
+      const ejected = runMercato(['module', 'eject', 'consents'], appDir)
+      expect(ejected.status, ejected.output).not.toBe(0)
+      expect(ejected.output).toContain(`${binding}/modules/consents/`)
+      expect(fs.readFileSync(configPath, 'utf8')).toBe(registeredConfig)
+      expect(fs.existsSync(path.join(appDir, 'src', 'modules', 'consents'))).toBe(false)
+    } finally {
+      fs.rmSync(appDir, { recursive: true, force: true })
+    }
+  })
+
+  test('a single package registration with a local overlay remains valid', () => {
+    const appDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mercato-single-overlay-'))
+    try {
+      const binding = '@publisher/consents'
+      createApp(appDir, { [binding]: '0.4.7' })
+      createPackage(path.join(appDir, 'node_modules', binding), binding, ['consents'])
+      writeFile(path.join(appDir, 'src', 'modules.ts'), `export const enabledModules = [{ id: 'consents', from: '${binding}' }]\n`)
+      writeFile(path.join(appDir, 'src', 'modules', 'consents', 'index.ts'), "export const metadata = { title: 'Local overlay' }\n")
+      const before = snapshotDirectory(path.join(appDir, 'src'))
+
+      const result = runMercato(['generate', 'all', '--quiet'], appDir)
+
+      expect(result.status, result.output).toBe(0)
+      expect(snapshotDirectory(path.join(appDir, 'src'))).toEqual(before)
+      expect(fs.readFileSync(path.join(appDir, '.mercato', 'generated', 'di.generated.ts'), 'utf8')).toContain(`${binding}/modules/consents/di`)
+    } finally {
+      fs.rmSync(appDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/lib/__tests__/eject.test.ts

@@ -9,7 +9,9 @@ import {
   listEjectableModules,
   ejectModule,
 } from '../eject'
-import type { PackageResolver } from '../resolver'
+import { readEnabledModulesFromConfig, type PackageResolver } from '../resolver'
+import { getModuleLocators } from '../module-identity'
+import { resolveModuleRequirement } from '@open-mercato/shared/modules/module-locators'
 
 describe('eject', () => {
   let tmpDir: string
@@ -292,6 +294,7 @@ describe('eject', () => {
       fs.mkdirSync(path.join(installedPackageRoot, 'src', 'modules', 'test_package'), { recursive: true })
       fs.mkdirSync(path.join(installedPackageRoot, 'dist', 'modules', 'test_package'), { recursive: true })
 
+      fs.writeFileSync(path.join(appDir, 'package.json'), JSON.stringify({ dependencies: { '@open-mercato/test-package': '^0.1.0' } }))
       fs.writeFileSync(
         path.join(appDir, 'src', 'modules.ts'),
         "export const enabledModules = [{ id: 'test_package', from: '@open-mercato/test-package' }]\n",
@@ -331,7 +334,7 @@ describe('eject', () => {
           appBase: path.join(appDir, 'src', 'modules', 'test_package'),
           pkgBase: path.join(baseDir, 'packages', 'test-package', 'src', 'modules', 'test_package'),
         }),
-        getPackageRoot: () => path.join(baseDir, 'packages', 'test-package'),
+        getPackageRoot: () => installedPackageRoot,
       } as unknown as PackageResolver
     }
 
@@ -348,6 +351,95 @@ describe('eject', () => {
       ])
     })
 
+    it('rejects duplicate module registrations before copying source', () => {
+      const resolver = createOfficialModuleResolver(tmpDir)
+      const duplicates = [
+        { id: 'test_package', from: '@open-mercato/test-package' },
+        { id: 'test_package', from: '@other/test-package' },
+      ]
+      fs.writeFileSync(resolver.getModulesConfigPath(), `export const enabledModules = ${JSON.stringify(duplicates)}`)
+      const sourceBefore = fs.readFileSync(resolver.getModulesConfigPath(), 'utf8')
+      expect(() => ejectModule({ ...resolver, loadEnabledModules: () => duplicates }, 'test_package')).toThrow("Duplicate enabled module ID 'test_package'")
+      expect(fs.existsSync(resolver.getModulePaths(duplicates[0]).appBase)).toBe(false)
+      expect(fs.readFileSync(resolver.getModulesConfigPath(), 'utf8')).toBe(sourceBefore)
+    })
+
+    it('rejects duplicate registrations elsewhere in the effective set before copying', () => {
+      const resolver = createOfficialModuleResolver(tmpDir)
+      const entries = [...resolver.loadEnabledModules(), { id: 'customers' }, { id: 'customers', from: '@other/customers' }]
+      const before = fs.readFileSync(resolver.getModulesConfigPath(), 'utf8')
+
+      expect(() => ejectModule({ ...resolver, loadEnabledModules: () => entries }, 'test_package')).toThrow("Duplicate enabled module ID 'customers'")
+      expect(fs.existsSync(resolver.getModulePaths(entries[0]).appBase)).toBe(false)
+      expect(fs.readFileSync(resolver.getModulesConfigPath(), 'utf8')).toBe(before)
+    })
+
+    it('checks the config mutation before copying when effective entries cannot be edited', () => {
+      const resolver = createOfficialModuleResolver(tmpDir)
+      const before = "const entries = [{ id: 'test_package', from: '@open-mercato/test-package' }]; export const enabledModules = entries;\n"
+      fs.writeFileSync(resolver.getModulesConfigPath(), before)
+
+      expect(() => ejectModule(resolver, 'test_package')).toThrow('Could not find enabledModules array')
+      expect(fs.existsSync(resolver.getModulePaths(resolver.loadEnabledModules()[0]).appBase)).toBe(false)
+      expect(fs.readFileSync(resolver.getModulesConfigPath(), 'utf8')).toBe(before)
+    })
+
+    it('rejects contradictory observed provenance before copying source', () => {
+      const resolver = createOfficialModuleResolver(tmpDir)
+      const entry = { id: 'test_package', from: '@open-mercato/test-package', locator: 'github:unexpected/provider' }
+      const before = "export const enabledModules = [{ id: 'test_package', from: '@open-mercato/test-package', locator: 'github:unexpected/provider' }]\n"
+      fs.writeFileSync(resolver.getModulesConfigPath(), before)
+
+      expect(() => ejectModule({ ...resolver, loadEnabledModules: () => [entry] }, 'test_package')).toThrow('disagrees with observed origin')
+      expect(fs.existsSync(resolver.getModulePaths(entry).appBase)).toBe(false)
+      expect(fs.readFileSync(resolver.getModulesConfigPath(), 'utf8')).toBe(before)
+    })
+
+    it('preserves an existing local overlay and gives a recovery without deleting source', () => {
+      const resolver = createOfficialModuleResolver(tmpDir)
+      const appBase = resolver.getModulePaths(resolver.loadEnabledModules()[0]).appBase
+      fs.mkdirSync(appBase, { recursive: true })
+      fs.writeFileSync(path.join(appBase, 'local.ts'), 'export const local = true\n')
+      const before = fs.readFileSync(resolver.getModulesConfigPath(), 'utf8')
+
+      expect(() => ejectModule(resolver, 'test_package')).toThrow('Keep the existing local source')
+      expect(fs.readFileSync(path.join(appBase, 'local.ts'), 'utf8')).toBe('export const local = true\n')
+      expect(fs.existsSync(path.join(appBase, 'index.ts'))).toBe(false)
+      expect(fs.readFileSync(resolver.getModulesConfigPath(), 'utf8')).toBe(before)
+    })
+
+    it('keeps canonical provenance and rewrites sibling imports using the installed alias', () => {
+      const resolver = createOfficialModuleResolver(tmpDir)
+      const packageRoot = resolver.getPackageRoot('@open-mercato/test-package')
+      const aliasRoot = path.join(resolver.getAppDir(), 'node_modules', 'candidate_consents')
+      fs.mkdirSync(path.dirname(aliasRoot), { recursive: true })
+      fs.symlinkSync(packageRoot, aliasRoot, 'dir')
+      fs.writeFileSync(path.join(resolver.getAppDir(), 'package.json'), JSON.stringify({ dependencies: { candidate_consents: 'npm:@open-mercato/test-package@1.0.0' } }))
+      const entry = { id: 'test_package', from: 'candidate_consents' }
+      fs.writeFileSync(resolver.getModulesConfigPath(), `export const enabledModules = [${JSON.stringify(entry)}]\n`)
+      fs.mkdirSync(path.join(packageRoot, 'src', 'modules', 'sibling'), { recursive: true })
+      fs.writeFileSync(path.join(packageRoot, 'src', 'modules', 'sibling', 'index.ts'), 'export const sibling = true\n')
+      fs.writeFileSync(path.join(packageRoot, 'src', 'modules', 'test_package', 'widget.ts'), "export { sibling } from '../sibling'\n")
+      const aliasResolver = { ...resolver, loadEnabledModules: () => [entry], getPackageRoot: () => aliasRoot }
+
+      ejectModule(aliasResolver, 'test_package')
+
+      expect(readEnabledModulesFromConfig(resolver.getModulesConfigPath())[0]).toEqual({ id: 'test_package', from: '@app', packageName: '@open-mercato/test-package', locator: 'npm:@open-mercato/test-package' })
+      const appBase = resolver.getModulePaths(entry).appBase
+      expect(fs.readFileSync(path.join(appBase, 'widget.ts'), 'utf8')).toContain("from 'candidate_consents/modules/sibling'")
+    })
+
+    it('preserves GitHub origin and canonical package attribution through legacy eject', () => {
+      const resolver = createOfficialModuleResolver(tmpDir)
+      fs.writeFileSync(path.join(resolver.getAppDir(), 'package.json'), JSON.stringify({ dependencies: { '@open-mercato/test-package': 'github:pkarw/test-package#main' } }))
+      ejectModule(resolver, 'test_package')
+      const entry = readEnabledModulesFromConfig(resolver.getModulesConfigPath())[0]
+      expect(entry).toEqual({ id: 'test_package', from: '@app', packageName: '@open-mercato/test-package', locator: 'github:pkarw/test-package' })
+      const identities = [{ id: entry.id, locators: getModuleLocators(entry, resolver) }]
+      expect(resolveModuleRequirement('npm:@open-mercato/test-package', identities)).toBeUndefined()
+      expect(resolveModuleRequirement('github:pkarw/test-package', identities)).toBe('test_package')
+    })
+
     it('ejects module packages using module index.ts ejectable flag', () => {
       const resolver = createOfficialModuleResolver(tmpDir)
       const appModuleDir = path.join(tmpDir, 'apps', 'mercato', 'src', 'modules', 'test_package')
@@ -358,7 +450,7 @@ describe('eject', () => {
       expect(fs.existsSync(path.join(appModuleDir, 'index.ts'))).toBe(true)
       expect(fs.existsSync(path.join(appModuleDir, 'widget.ts'))).toBe(true)
       expect(fs.readFileSync(modulesTsPath, 'utf8')).toContain(
-        "{ id: 'test_package', from: '@app' }",
+        "{ id: 'test_package', from: '@app', locator: 'npm:@open-mercato/test-package', packageName: '@open-mercato/test-package' }",
       )
     })
   })
@@ -381,6 +473,8 @@ describe('eject', () => {
         path.join(appDir, 'src', 'modules.ts'),
         "export const enabledModules = [{ id: 'customers', from: '@open-mercato/core' }]\n",
       )
+      fs.writeFileSync(path.join(packageRoot, 'package.json'), JSON.stringify({ name: '@open-mercato/core' }))
+      fs.writeFileSync(path.join(appDir, 'package.json'), JSON.stringify({ dependencies: { '@open-mercato/core': '^0.1.0' } }))
       fs.writeFileSync(
         path.join(distModuleDir, 'index.js'),
         'var metadata = { title: "Customers", description: "Compiled", ejectable: true };\nexport { metadata };\n',
@@ -431,7 +525,7 @@ describe('eject', () => {
       expect(fs.existsSync(path.join(appModuleDir, 'index.ts'))).toBe(true)
       expect(fs.existsSync(path.join(appModuleDir, 'acl.ts'))).toBe(true)
       expect(fs.existsSync(path.join(appModuleDir, 'index.js'))).toBe(false)
-      expect(fs.readFileSync(modulesTsPath, 'utf8')).toContain("{ id: 'customers', from: '@app' }")
+      expect(fs.readFileSync(modulesTsPath, 'utf8')).toContain("{ id: 'customers', from: '@app', locator: 'npm:@open-mercato/core', packageName: '@open-mercato/core' }")
     })
 
     it('falls back to compiled index.js metadata for dist-only packages', () => {

package/src/lib/__tests__/init-summary.test.ts

@@ -0,0 +1,50 @@
+import { formatInitSummary } from '../init-summary'
+
+const users = [
+  { icon: '👑', label: 'Superadmin', email: 'owner@example.test', password: 'demo-superadmin' },
+  { icon: '🧰', label: 'Admin', email: 'admin@example.test', password: 'demo-admin' },
+  { icon: '👷', label: 'Employee', email: 'employee@example.test', password: 'demo-employee' },
+]
+
+describe('formatInitSummary', () => {
+  it('renders every supplied account and its own password without side borders', () => {
+    const output = formatInitSummary({ users, autoStart: true }).join('\n')
+    for (const user of users) {
+      expect(output).toContain(`${user.icon} ${user.label}`)
+      expect(output).toContain(user.email)
+      expect(output).toContain(user.password)
+    }
+    expect(output).not.toMatch(/[╔║╚]/u)
+    expect(output).toContain('The dev server will start automatically.')
+    expect(output).not.toContain('\u001b[')
+  })
+
+  it('shows the manual startup hint when initialization is invoked directly', () => {
+    const output = formatInitSummary({ users: users.slice(0, 1), autoStart: false }).join('\n')
+    expect(output).toContain('🚀 Start the dev server: yarn dev')
+    expect(output).not.toContain('automatically')
+    expect(output).not.toContain('🧰 Admin')
+  })
+
+  it.each([8, 20, 40, 80])('wraps long credentials within %i columns without dropping characters', (columns) => {
+    const password = 'long-demo-password-'.repeat(12)
+    const lines = formatInitSummary({ users: [{ ...users[0], password }], autoStart: true, columns })
+    for (const line of lines) {
+      const width = [...line].reduce((total, character) => total + (/\p{Extended_Pictographic}/u.test(character) ? 2 : 1), 0)
+      expect(width).toBeLessThanOrEqual(columns)
+    }
+    expect(lines.map((line) => line.trim()).join('')).toContain(password)
+  })
+
+  it('paints complete rows dark gray with light text and resets after each row', () => {
+    const lines = formatInitSummary({ users, autoStart: true, color: true, columns: 80 })
+    for (const line of lines) {
+      expect(line).toMatch(/^\u001b\[48;2;57;62;70m\u001b\[38;2;238;238;238m/u)
+      expect(line).toMatch(/\u001b\[0m$/u)
+    }
+  })
+
+  it.each([NaN, Infinity, 0, -1])('uses a safe width for invalid columns %s', (columns) => {
+    expect(formatInitSummary({ users, autoStart: false, columns })[0]).toHaveLength(80)
+  })
+})

package/src/lib/__tests__/module-github.test.ts

@@ -0,0 +1,108 @@
+import { execFileSync } from 'node:child_process'
+import { resolveGithubModuleTarget } from '../module-github'
+
+jest.mock('node:child_process', () => ({ execFileSync: jest.fn() }))
+const execute = jest.mocked(execFileSync)
+const sha = 'a'.repeat(40)
+
+function mockGithub(manifest: unknown = { name: '@pkarw/consents' }, files = ['src/modules/marketing_consents/index.ts']): void {
+  execute.mockImplementation((_command, args) => {
+    const endpoint = args?.[1]
+    const value = endpoint === 'user' ? { login: 'pkarw' }
+      : typeof endpoint === 'string' && endpoint.includes('/commits/') ? { sha }
+        : typeof endpoint === 'string' && endpoint.includes('/contents/') ? { encoding: 'base64', content: Buffer.from(JSON.stringify(manifest)).toString('base64') }
+          : typeof endpoint === 'string' && endpoint.includes('/git/trees/') ? { tree: files.map((filePath) => ({ path: filePath })) }
+            : { default_branch: 'main' }
+    return JSON.stringify(value)
+  })
+}
+
+beforeEach(() => execute.mockReset())
+
+test.each([
+  'pkarw/consents', 'github:pkarw/consents', 'https://github.com/pkarw/consents.git/',
+  'git@github.com:pkarw/consents.git', 'ssh://git@github.com/pkarw/consents.git',
+  'git+https://github.com/pkarw/consents', 'github:consents',
+  'git+ssh://git@github.com/pkarw/consents.git', 'http://github.com/pkarw/consents',
+  'https://github.com/https://github.com/pkarw/consents', 'github.com/pkarw/consents',
+])('pins GitHub locator %s to one revision', (locator) => {
+  mockGithub()
+  expect(resolveGithubModuleTarget(locator, '/app')).toEqual({
+    packageName: '@pkarw/consents', packageSpec: `@pkarw/consents@github:pkarw/consents#${sha}`,
+    locator: 'github:pkarw/consents', moduleIds: ['marketing_consents'],
+  })
+  expect(execute).toHaveBeenCalledWith('gh', ['api', `repos/pkarw/consents/contents/package.json?ref=${sha}`], expect.objectContaining({ cwd: '/app' }))
+  expect(execute).toHaveBeenCalledWith('gh', expect.any(Array), expect.objectContaining({ maxBuffer: 16 * 1024 * 1024 }))
+})
+
+test('resolves selected refs once and inspects the same immutable revision', () => {
+  mockGithub()
+  resolveGithubModuleTarget('github:pkarw/consents#release/v1', '/app')
+  expect(execute).toHaveBeenCalledWith('gh', ['api', 'repos/pkarw/consents/commits/release%2Fv1'], expect.anything())
+  expect(execute).toHaveBeenCalledTimes(3)
+})
+
+test.each(['https://example.com/owner/repo', 'pkarw/consents/tree/main', 'github:pkarw/consents#--bad'])('rejects invalid locator %s', (locator) => {
+  mockGithub()
+  expect(() => resolveGithubModuleTarget(locator, '/app')).toThrow()
+  expect(execute).not.toHaveBeenCalled()
+})
+
+test('accepts a GitHub .git@ref locator', () => {
+  mockGithub()
+  resolveGithubModuleTarget('git+ssh://git@github.com/pkarw/consents.git@release/v1', '/app')
+  expect(execute).toHaveBeenCalledWith('gh', ['api', 'repos/pkarw/consents/commits/release%2Fv1'], expect.anything())
+})
+
+test('rejects malformed manifest package identities', () => {
+  mockGithub({ name: '--bad' })
+  expect(() => resolveGithubModuleTarget('pkarw/consents', '/app')).toThrow('valid npm package name')
+})
+
+test('reports authentication and repository errors without leaking command stderr', () => {
+  execute.mockImplementation(() => { throw new Error('private token stderr') })
+  expect(() => resolveGithubModuleTarget('pkarw/consents', '/app')).toThrow('gh auth login')
+  expect(() => resolveGithubModuleTarget('pkarw/consents', '/app')).not.toThrow('private token')
+})
+
+test('rejects an exact GitHub revision denying a generated subpath before installation', () => {
+  mockGithub({ name: '@pkarw/consents', exports: { './modules/marketing_consents/index': './dist/modules/marketing_consents/index.js' } }, [
+    'src/modules/marketing_consents/index.ts', 'src/modules/marketing_consents/di.ts',
+  ])
+  expect(() => resolveGithubModuleTarget('github:pkarw/consents#main', '/app')).toThrow('@pkarw/consents/modules/marketing_consents/di')
+})
+
+test('allows source-only GitHub repositories to produce generated runtime artifacts during installation', () => {
+  mockGithub({ name: '@pkarw/consents', exports: { './modules/marketing_consents/*': './dist/modules/marketing_consents/*.js' } }, [
+    'src/modules/marketing_consents/index.ts', 'src/modules/marketing_consents/di.ts',
+  ])
+
+  expect(() => resolveGithubModuleTarget('github:pkarw/consents#main', '/app')).not.toThrow()
+})
+
+test('checks every active sibling against GitHub exports even when selecting another module', () => {
+  mockGithub({ name: '@pkarw/consents', exports: { './modules/alpha/index': null, './modules/beta/index': './dist/modules/beta/index.js' } }, [
+    'src/modules/alpha/index.ts', 'src/modules/beta/index.ts',
+  ])
+  expect(() => resolveGithubModuleTarget('github:pkarw/consents#main', '/app', {
+    moduleId: 'beta', enabledModules: [{ id: 'alpha', from: '@pkarw/consents' }],
+  })).toThrow('@pkarw/consents/modules/alpha/index')
+})
+
+
+test('reads exact-commit page source without executing private lowercase helpers', () => {
+  const moduleRoot = 'src/modules/marketing_consents/'
+  mockGithub({ name: '@pkarw/consents', exports: { './modules/marketing_consents/index': './dist/modules/marketing_consents/index.js' } }, [moduleRoot + 'index.ts', moduleRoot + 'backend/form-utils.tsx', moduleRoot + 'backend/orders/page.tsx'])
+  const metadataImplementation = execute.getMockImplementation()!
+  execute.mockImplementation((command, args, options) => {
+    const endpoint = String(args?.[1])
+    if (endpoint.includes('/backend/')) {
+      expect(endpoint).toContain(`?ref=${sha}`)
+      const content = endpoint.includes('form-utils') ? "throw new Error('must not execute'); export const renderLabel = () => null" : 'export default function Page() {}'
+      return JSON.stringify({ encoding: 'base64', content: Buffer.from(content).toString('base64') })
+    }
+    return metadataImplementation(command, args, options)
+  })
+  expect(() => resolveGithubModuleTarget('github:pkarw/consents', '/app')).toThrow('@pkarw/consents/modules/marketing_consents/backend/orders/page')
+  expect(execute.mock.calls.filter(([, args]) => String(args?.[1]).includes('form-utils'))).toHaveLength(1)
+})