@open-mercato/cli 0.6.6-develop.5654.1.ca21e35f26 → 0.6.6-develop.5672.1.11e27afad2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.6-develop.5654.1.ca21e35f26",
+  "version": "0.6.6-develop.5672.1.11e27afad2",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -59,8 +59,8 @@
     "@mikro-orm/decorators": "^7.1.4",
     "@mikro-orm/migrations": "^7.1.4",
     "@mikro-orm/postgresql": "^7.1.4",
-    "@open-mercato/queue": "0.6.6-develop.5654.1.ca21e35f26",
-    "@open-mercato/shared": "0.6.6-develop.5654.1.ca21e35f26",
+    "@open-mercato/queue": "0.6.6-develop.5672.1.11e27afad2",
+    "@open-mercato/shared": "0.6.6-develop.5672.1.11e27afad2",
     "cross-spawn": "^7.0.6",
     "pg": "8.21.0",
     "semver": "^7.8.4",
@@ -70,10 +70,10 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.5654.1.ca21e35f26"
+    "@open-mercato/shared": "0.6.6-develop.5672.1.11e27afad2"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.5654.1.ca21e35f26",
+    "@open-mercato/shared": "0.6.6-develop.5672.1.11e27afad2",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11"

package/src/lib/__tests__/module-install-args.test.ts

@@ -32,4 +32,27 @@ describe('parseModuleInstallArgs', () => {
       'Unsupported option: --installed',
     )
   })
+
+  it('defaults allowThirdParty to false', () => {
+    expect(parseModuleInstallArgs(['@open-mercato/test-package'])).toMatchObject({
+      allowThirdParty: false,
+    })
+  })
+
+  it('accepts --allow-third-party as a boolean flag', () => {
+    expect(parseModuleInstallArgs(['@scope/pkg', '--allow-third-party'])).toMatchObject({
+      packageSpec: '@scope/pkg',
+      allowThirdParty: true,
+    })
+    expect(parseModuleInstallArgs(['--allow-third-party', '@scope/pkg'])).toMatchObject({
+      packageSpec: '@scope/pkg',
+      allowThirdParty: true,
+    })
+  })
+
+  it('rejects --allow-third-party values', () => {
+    expect(() => parseModuleInstallArgs(['@scope/pkg', '--allow-third-party=true'])).toThrow(
+      '--allow-third-party does not accept a value',
+    )
+  })
 })

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

@@ -10,15 +10,17 @@ function buildPackageFixture(
   options?: {
     ejectable?: boolean
     extraSourceFiles?: Array<{ relativePath: string; content: string }>
+    packageName?: string
   },
 ): void {
   const ejectable = options?.ejectable ?? false
+  const packageName = options?.packageName ?? '@open-mercato/test-package'
   for (const base of ['src', 'dist']) {
     fs.mkdirSync(path.join(packageRoot, base, 'modules', moduleId), { recursive: true })
   }
   fs.writeFileSync(
     path.join(packageRoot, 'package.json'),
-    JSON.stringify({ name: '@open-mercato/test-package', version: '0.1.0' }),
+    JSON.stringify({ name: packageName, version: '0.1.0' }),
   )
   fs.writeFileSync(
     path.join(packageRoot, 'src', 'modules', moduleId, 'index.ts'),
@@ -236,3 +238,66 @@ describe('enableOfficialModule', () => {
     ).rejects.toThrow('Unsupported package spec suffix')
   })
 })
+
+describe('third-party module packages', () => {
+  let tmpDir: string
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'module-install-3p-test-'))
+  })
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('rejects adding a non-@open-mercato package without --allow-third-party', async () => {
+    const packageRoot = path.join(tmpDir, 'node_modules', '@fast-white-cat', 'integration-ksef-direct')
+    const appDir = path.join(tmpDir, 'app')
+    buildPackageFixture(packageRoot, 'ksef_direct', {
+      packageName: '@fast-white-cat/integration-ksef-direct',
+    })
+
+    const resolver = buildResolver(appDir, packageRoot, 'export const enabledModules = []\n')
+
+    await expect(
+      addOfficialModule(resolver, '@fast-white-cat/integration-ksef-direct@0.1.0', false),
+    ).rejects.toThrow('Re-run with --allow-third-party')
+  })
+
+  it('rejects enabling a non-@open-mercato package without --allow-third-party', async () => {
+    const packageRoot = path.join(tmpDir, 'node_modules', '@fast-white-cat', 'integration-ksef-direct')
+    const appDir = path.join(tmpDir, 'app')
+    buildPackageFixture(packageRoot, 'ksef_direct', {
+      packageName: '@fast-white-cat/integration-ksef-direct',
+    })
+
+    const resolver = buildResolver(appDir, packageRoot, 'export const enabledModules = []\n')
+
+    await expect(
+      enableOfficialModule(resolver, '@fast-white-cat/integration-ksef-direct'),
+    ).rejects.toThrow('Re-run with --allow-third-party')
+  })
+
+  it('enables a non-@open-mercato package when --allow-third-party is set', async () => {
+    const packageRoot = path.join(tmpDir, 'node_modules', '@fast-white-cat', 'integration-ksef-direct')
+    const appDir = path.join(tmpDir, 'app')
+    buildPackageFixture(packageRoot, 'ksef_direct', {
+      packageName: '@fast-white-cat/integration-ksef-direct',
+    })
+
+    const resolver = buildResolver(appDir, packageRoot, 'export const enabledModules = []\n')
+
+    await expect(
+      enableOfficialModule(resolver, '@fast-white-cat/integration-ksef-direct', undefined, false, true),
+    ).resolves.toEqual({
+      moduleId: 'ksef_direct',
+      packageName: '@fast-white-cat/integration-ksef-direct',
+      from: '@fast-white-cat/integration-ksef-direct',
+      registrationChanged: true,
+    })
+
+    expect(fs.readFileSync(path.join(appDir, 'src', 'modules.ts'), 'utf8')).toContain(
+      "{ id: 'ksef_direct', from: '@fast-white-cat/integration-ksef-direct' }",
+    )
+  })
+})

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

@@ -57,6 +57,33 @@ describe('module-package', () => {
     expect(modulePackage.distModuleDir).toContain(path.join('dist', 'modules', 'test_package'))
   })
 
+  it('validates a third-party (non-@open-mercato) module package by structure', () => {
+    const packageRoot = path.join(tmpDir, 'node_modules', '@fast-white-cat', 'integration-ksef-direct')
+    for (const base of ['src', 'dist']) {
+      fs.mkdirSync(path.join(packageRoot, base, 'modules', 'ksef_direct'), { recursive: true })
+    }
+    fs.writeFileSync(
+      path.join(packageRoot, 'package.json'),
+      JSON.stringify({ name: '@fast-white-cat/integration-ksef-direct', version: '0.1.0' }),
+    )
+    fs.writeFileSync(
+      path.join(packageRoot, 'src', 'modules', 'ksef_direct', 'index.ts'),
+      "export const metadata = { title: 'KSeF Direct', ejectable: false }\n",
+    )
+    fs.writeFileSync(
+      path.join(packageRoot, 'dist', 'modules', 'ksef_direct', 'index.js'),
+      'exports.metadata = {};\n',
+    )
+
+    const modulePackage = readOfficialModulePackageFromRoot(
+      packageRoot,
+      '@fast-white-cat/integration-ksef-direct',
+    )
+
+    expect(modulePackage.packageName).toBe('@fast-white-cat/integration-ksef-direct')
+    expect(modulePackage.metadata.moduleId).toBe('ksef_direct')
+  })
+
   it('resolves a hoisted installed module package from a monorepo app', () => {
     const appDir = path.join(tmpDir, 'apps', 'mercato')
     const installedPackageRoot = path.join(tmpDir, 'node_modules', '@open-mercato', 'test-package')

package/src/lib/module-install-args.ts

@@ -2,12 +2,14 @@ export type ParsedModuleInstallArgs = {
   packageSpec: string | null
   eject: boolean
   moduleId: string | null
+  allowThirdParty: boolean
 }
 
 export function parseModuleInstallArgs(args: string[]): ParsedModuleInstallArgs {
   let packageSpec: string | null = null
   let eject = false
   let moduleId: string | null = null
+  let allowThirdParty = false
 
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index]
@@ -22,6 +24,15 @@ export function parseModuleInstallArgs(args: string[]): ParsedModuleInstallArgs
       throw new Error('--eject does not accept a value')
     }
 
+    if (arg === '--allow-third-party') {
+      allowThirdParty = true
+      continue
+    }
+
+    if (arg.startsWith('--allow-third-party=')) {
+      throw new Error('--allow-third-party does not accept a value')
+    }
+
     if (arg === '--module') {
       const next = args[index + 1]
       if (next && !next.startsWith('-')) {
@@ -46,5 +57,5 @@ export function parseModuleInstallArgs(args: string[]): ParsedModuleInstallArgs
     }
   }
 
-  return { packageSpec, eject, moduleId }
+  return { packageSpec, eject, moduleId, allowThirdParty }
 }

package/src/lib/module-install.ts

@@ -24,7 +24,8 @@ type InstallTarget = {
   args: string[]
 }
 
-const SAFE_PACKAGE_SPEC_PATTERN = /^@open-mercato\/[a-z0-9][a-z0-9-]*(?:@.+)?$/i
+const OFFICIAL_PACKAGE_SCOPE = '@open-mercato/'
+const SAFE_PACKAGE_SPEC_PATTERN = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:@.+)?$/i
 const SAFE_PACKAGE_TAG_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
 const SAFE_PACKAGE_FILE_LOCATOR_PATTERN = /^file:[A-Za-z0-9_./: \\-]+$/
 
@@ -133,21 +134,36 @@ async function runGeneratorsWithRegistrationNotice(
   }
 }
 
+function isOfficialPackage(packageName: string): boolean {
+  return packageName.startsWith(OFFICIAL_PACKAGE_SCOPE)
+}
+
 function assertPackageName(packageName: string | null): asserts packageName is string {
-  if (!packageName || !packageName.startsWith('@open-mercato/')) {
-    throw new Error('Only @open-mercato/* package specs are supported by "mercato module add".')
+  if (!packageName) {
+    throw new Error('Could not determine a package name from the provided spec.')
+  }
+}
+
+function assertThirdPartyAllowed(packageName: string, allowThirdParty: boolean): void {
+  if (isOfficialPackage(packageName) || allowThirdParty) {
+    return
   }
+
+  throw new Error(
+    `Package "${packageName}" is outside the ${OFFICIAL_PACKAGE_SCOPE}* scope. Re-run with --allow-third-party to install third-party module packages.`,
+  )
 }
 
-function assertSupportedPackageSpec(packageSpec: string): string {
+function assertSupportedPackageSpec(packageSpec: string, allowThirdParty: boolean): string {
   const trimmed = packageSpec.trim()
 
   if (!SAFE_PACKAGE_SPEC_PATTERN.test(trimmed)) {
-    throw new Error('Unsupported package spec. Only direct @open-mercato/* package specs are allowed.')
+    throw new Error('Unsupported package spec. Provide a valid npm package name with an optional tag/version or file: locator.')
   }
 
   const packageName = parsePackageNameFromSpec(trimmed)
   assertPackageName(packageName)
+  assertThirdPartyAllowed(packageName, allowThirdParty)
 
   if (trimmed === packageName) {
     return trimmed
@@ -240,8 +256,9 @@ export async function addOfficialModule(
   packageSpec: string,
   eject: boolean,
   moduleId?: string,
+  allowThirdParty = false,
 ): Promise<ModuleCommandResult> {
-  const safePackageSpec = assertSupportedPackageSpec(packageSpec)
+  const safePackageSpec = assertSupportedPackageSpec(packageSpec, allowThirdParty)
   const packageName = parsePackageNameFromSpec(safePackageSpec)
   assertPackageName(packageName)
 
@@ -256,10 +273,9 @@ export async function enableOfficialModule(
   packageName: string,
   moduleId?: string,
   eject = false,
+  allowThirdParty = false,
 ): Promise<ModuleCommandResult> {
-  if (!packageName.startsWith('@open-mercato/')) {
-    throw new Error('Only @open-mercato/* packages can be enabled with "mercato module enable".')
-  }
+  assertThirdPartyAllowed(packageName, allowThirdParty)
 
   const modulePackage = resolveInstalledOfficialModulePackage(resolver, packageName, moduleId)
   return registerResolvedOfficialModule(resolver, modulePackage, packageName, eject)

package/src/lib/module-package.ts

@@ -270,8 +270,8 @@ export function readOfficialModulePackageFromRoot(
 
   const packageJson = readPackageJson(packageJsonPath)
   const packageName = packageJson.name
-  if (!packageName || !packageName.startsWith('@open-mercato/')) {
-    throw new Error(`Package at ${packageRoot} is not under the @open-mercato scope.`)
+  if (!packageName) {
+    throw new Error(`Package manifest at ${packageJsonPath} is missing the "name" field.`)
   }
 
   if (expectedPackageName && packageName !== expectedPackageName) {

package/src/mercato.ts

@@ -1282,8 +1282,8 @@ export async function run(argv = process.argv) {
 
       if (!subcommand || subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
         console.log('Usage: yarn mercato module <add|enable|eject> ...')
-        console.log('  yarn mercato module add <packageSpec> [--module <moduleId>] [--eject]')
-        console.log('  yarn mercato module enable <packageName> [--module <moduleId>] [--eject]')
+        console.log('  yarn mercato module add <packageSpec> [--module <moduleId>] [--eject] [--allow-third-party]')
+        console.log('  yarn mercato module enable <packageName> [--module <moduleId>] [--eject] [--allow-third-party]')
         console.log('  yarn mercato module eject <moduleId>')
         return 0
       }
@@ -1291,14 +1291,14 @@ export async function run(argv = process.argv) {
       if (subcommand === 'add') {
         const { createResolver } = await import('./lib/resolver')
         const { addOfficialModule } = await import('./lib/module-install')
-        const { packageSpec, eject, moduleId } = parseModuleInstallArgs(commandArgs)
+        const { packageSpec, eject, moduleId, allowThirdParty } = parseModuleInstallArgs(commandArgs)
 
         if (!packageSpec) {
-          console.error('Usage: yarn mercato module add <packageSpec> [--module <moduleId>] [--eject]')
+          console.error('Usage: yarn mercato module add <packageSpec> [--module <moduleId>] [--eject] [--allow-third-party]')
           return 1
         }
 
-        const result = await addOfficialModule(createResolver(), packageSpec, eject, moduleId ?? undefined)
+        const result = await addOfficialModule(createResolver(), packageSpec, eject, moduleId ?? undefined, allowThirdParty)
         console.log(`\n✅ Module "${result.moduleId}" enabled from ${result.from}.\n`)
         console.log('Next steps:')
         console.log('  1. Review generated files if needed: .mercato/generated/')
@@ -1309,14 +1309,14 @@ export async function run(argv = process.argv) {
       if (subcommand === 'enable') {
         const packageName = commandArgs.find((arg) => !arg.startsWith('-'))
         if (!packageName) {
-          console.error('Usage: yarn mercato module enable <packageName> [--module <moduleId>] [--eject]')
+          console.error('Usage: yarn mercato module enable <packageName> [--module <moduleId>] [--eject] [--allow-third-party]')
           return 1
         }
 
         const { createResolver } = await import('./lib/resolver')
         const { enableOfficialModule } = await import('./lib/module-install')
-        const { moduleId, eject } = parseModuleInstallArgs(commandArgs)
-        const result = await enableOfficialModule(createResolver(), packageName, moduleId ?? undefined, eject)
+        const { moduleId, eject, allowThirdParty } = parseModuleInstallArgs(commandArgs)
+        const result = await enableOfficialModule(createResolver(), packageName, moduleId ?? undefined, eject, allowThirdParty)
         console.log(`\n✅ Module "${result.moduleId}" enabled from ${result.from}.\n`)
         console.log('Next steps:')
         console.log('  1. Review generated files if needed: .mercato/generated/')