@open-mercato/cli 0.7.0 → 0.7.1-develop.7103.1.41ff100d93

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.7.0",
+  "version": "0.7.1-develop.7103.1.41ff100d93",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,9 +60,9 @@
     "@mikro-orm/decorators": "^7.1.8",
     "@mikro-orm/migrations": "^7.1.8",
     "@mikro-orm/postgresql": "^7.1.8",
-    "@open-mercato/queue": "0.7.0",
-    "@open-mercato/shared": "0.7.0",
-    "@open-mercato/telemetry": "0.7.0",
+    "@open-mercato/queue": "0.7.1-develop.7103.1.41ff100d93",
+    "@open-mercato/shared": "0.7.1-develop.7103.1.41ff100d93",
+    "@open-mercato/telemetry": "0.7.1-develop.7103.1.41ff100d93",
     "cross-spawn": "^7.0.6",
     "pg": "8.22.0",
     "semver": "^7.8.5",
@@ -73,10 +73,10 @@
     "typescript-js": "npm:typescript@6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.7.0"
+    "@open-mercato/shared": "0.7.1-develop.7103.1.41ff100d93"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.7.0",
+    "@open-mercato/shared": "0.7.1-develop.7103.1.41ff100d93",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.12"
@@ -88,5 +88,6 @@
     "type": "git",
     "url": "https://github.com/open-mercato/open-mercato",
     "directory": "packages/cli"
-  }
+  },
+  "stableVersion": "0.7.0"
 }

package/src/__tests__/resolve-queue-abandon-hook.test.ts

@@ -0,0 +1,39 @@
+import { resolveQueueAbandonHook } from '../mercato'
+
+/**
+ * Covers the CLI's per-queue pick, which is the last link between worker metadata and the queue the
+ * worker runs on. The warning exists because two handlers on one queue each expecting to report is a
+ * wiring mistake, and a silent first-wins would hide it.
+ */
+describe('resolveQueueAbandonHook', () => {
+  const hookA = jest.fn(async () => {})
+  const hookB = jest.fn(async () => {})
+
+  it('returns undefined when no worker declares one', () => {
+    const warn = jest.fn()
+    expect(resolveQueueAbandonHook('q', [{ id: 'a' }, { id: 'b' }], warn)).toBeUndefined()
+    expect(warn).not.toHaveBeenCalled()
+  })
+
+  it('returns the single declared callback without warning', () => {
+    const warn = jest.fn()
+    expect(resolveQueueAbandonHook('q', [{ id: 'a' }, { id: 'b', onJobAbandoned: hookA }], warn)).toBe(hookA)
+    expect(warn).not.toHaveBeenCalled()
+  })
+
+  it('keeps the first and warns, naming the queue and every declaring worker', () => {
+    const warn = jest.fn()
+    const picked = resolveQueueAbandonHook(
+      'data-sync-import',
+      [{ id: 'first', onJobAbandoned: hookA }, { id: 'second', onJobAbandoned: hookB }],
+      warn,
+    )
+
+    expect(picked).toBe(hookA)
+    expect(warn).toHaveBeenCalledTimes(1)
+    const message = warn.mock.calls[0][0] as string
+    expect(message).toContain('data-sync-import')
+    expect(message).toContain('first')
+    expect(message).toContain('second')
+  })
+})

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

@@ -39,3 +39,26 @@ describe('resolveSpawnCommand', () => {
     )
   })
 })
+
+describe('resolveSpawnCommand detached passthrough', () => {
+  // The whole process-group teardown in the ephemeral harness rests on this flag reaching `spawn`:
+  // without it the app tree stays in the runner's group and the negated-pid kill has nothing of its
+  // own to signal.
+  it('passes detached through on the POSIX branch', () => {
+    const result = resolveSpawnCommand('yarn', ['start'], { platform: 'linux', detached: true })
+
+    expect(result.spawnOptions).toEqual({ detached: true })
+  })
+
+  it('passes detached through on the Windows cmd branch', () => {
+    const result = resolveSpawnCommand('yarn.cmd', ['start'], { platform: 'win32', detached: true })
+
+    expect(result.spawnOptions).toEqual({ detached: true })
+  })
+
+  it('omits detached entirely when the caller does not ask for it', () => {
+    expect(resolveSpawnCommand('yarn', ['start'], { platform: 'linux' }).spawnOptions).toEqual({})
+    expect(resolveSpawnCommand('yarn', ['start']).spawnOptions).not.toHaveProperty('detached')
+    expect(resolveSpawnCommand('yarn', ['start'], { platform: 'linux', detached: false }).spawnOptions).toEqual({})
+  })
+})

package/src/lib/generators/__tests__/__snapshots__/bootstrap-registrations.test.ts.snap

@@ -0,0 +1,14 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`renderBootstrapRegistrationsFile pins the emitted text so emitter changes surface as a reviewable diff 1`] = `
+"// AUTO-GENERATED by mercato generate registry
+import { backendRoutes } from "./backend-routes.generated";
+import { frontendRoutes } from "./frontend-routes.generated";
+import { registerBackendRouteManifests, registerFrontendRouteManifests } from "@open-mercato/shared/modules/registry";
+
+export function runBootstrapRegistrations(): void {
+  registerBackendRouteManifests(backendRoutes)
+  registerFrontendRouteManifests(frontendRoutes)
+}
+"
+`;

package/src/lib/generators/__tests__/__snapshots__/command-loaders.test.ts.snap

@@ -0,0 +1,23 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`renderCommandLoadersFile pins the emitted text so emitter changes surface as a reviewable diff 1`] = `
+"// AUTO-GENERATED by mercato generate command-loaders
+import type { CommandLoader } from "@open-mercato/shared/lib/commands";
+
+export const commandLoaderEntries: CommandLoader[] = [
+    {
+      moduleId: "catalog",
+      id: "catalog.products.create",
+      key: "catalog:commands:products",
+      load: () => import("@open-mercato/core/modules/catalog/commands/products")
+    },
+    {
+      moduleId: "catalog",
+      key: "catalog:commands:products",
+      load: () => import("@open-mercato/core/modules/catalog/commands/products")
+    }
+  ];
+
+export default commandLoaderEntries;
+"
+`;

package/src/lib/generators/__tests__/ast-writers-escaping.test.ts

@@ -0,0 +1,64 @@
+/**
+ * `stringLiteral` is the only place a JavaScript string value becomes source text in the
+ * AST generator stack. It must escape the characters that are legal inside a JSON string
+ * but hazardous inside an emitted source file, matching the escaping the string emitters
+ * applied before they were retired — otherwise the migration would have silently dropped
+ * that hardening from every generated file.
+ */
+import { escapeGeneratedJsonLiteral, stringLiteral, writeValue } from '../ast/writers'
+import type { CodeBlockWriter } from 'ts-morph'
+
+function render(value: unknown): string {
+  const chunks: string[] = []
+  const writer = { write: (text: string) => { chunks.push(text) } } as unknown as CodeBlockWriter
+  writeValue(writer, value as never)
+  return chunks.join('')
+}
+
+describe('stringLiteral', () => {
+  it('escapes angle brackets so an emitted value cannot close a surrounding script context', () => {
+    expect(stringLiteral('a</script>b')).toBe('"a\\u003c/script\\u003eb"')
+  })
+
+  it('escapes the line and paragraph separators older parsers reject inside a string literal', () => {
+    expect(stringLiteral('a
b
c')).toBe('"a\\u2028b\\u2029c"')
+  })
+
+  it('leaves an ordinary string as plain JSON', () => {
+    expect(stringLiteral('catalog:commands:products')).toBe('"catalog:commands:products"')
+  })
+
+  it('still escapes what JSON escapes', () => {
+    expect(stringLiteral('a"b\\c\nd')).toBe('"a\\"b\\\\c\\nd"')
+  })
+
+  it('denotes the same runtime string after escaping', () => {
+    const original = 'a</script>b
c'
+    expect(JSON.parse(stringLiteral(original))).toBe(original)
+  })
+})
+
+describe('escapeGeneratedJsonLiteral', () => {
+  it('hardens strings nested inside a serialized object', () => {
+    const literal = escapeGeneratedJsonLiteral(JSON.stringify({ GET: { title: 'a</script>b' } }))
+    expect(literal).toBe('{"GET":{"title":"a\\u003c/script\\u003eb"}}')
+  })
+
+  it('keeps the object literal parseable back to the same value', () => {
+    const value = { GET: { title: 'a</script>b
c
d' } }
+    expect(JSON.parse(escapeGeneratedJsonLiteral(JSON.stringify(value)))).toEqual(value)
+  })
+})
+
+describe('writeValue', () => {
+  it('routes string values through the escaping helper', () => {
+    expect(render('a<b>c')).toBe('"a\\u003cb\\u003ec"')
+  })
+
+  it('leaves non-string primitives alone', () => {
+    expect(render(42)).toBe('42')
+    expect(render(true)).toBe('true')
+    expect(render(null)).toBe('null')
+    expect(render(undefined)).toBe('undefined')
+  })
+})

package/src/lib/generators/__tests__/bootstrap-registrations.test.ts

@@ -0,0 +1,176 @@
+/**
+ * Contract tests for `renderBootstrapRegistrationsFile`, the emitter behind
+ * `bootstrap-registrations.generated.ts`.
+ *
+ * The file is always written — even when no generator plugin contributes a bootstrap
+ * registration — so `bootstrap.ts` can import it unconditionally. These tests cover
+ * that core-only case, one plugin, two plugins whose registration imports overlap
+ * (de-duplication), and a malformed import statement, which must fail at generation
+ * time with the offending statement named rather than emit a broken file.
+ */
+import ts from 'typescript-js'
+import { renderBootstrapRegistrationsFile } from '../module-registry'
+
+const CORE_ENTRY_IMPORTS = [
+  'import { backendRoutes } from "./backend-routes.generated"',
+  'import { frontendRoutes } from "./frontend-routes.generated"',
+]
+const CORE_REGISTRATION_IMPORTS = [
+  "import { registerBackendRouteManifests, registerFrontendRouteManifests } from '@open-mercato/shared/modules/registry'",
+]
+const CORE_CALLS = [
+  'registerBackendRouteManifests(backendRoutes)',
+  'registerFrontendRouteManifests(frontendRoutes)',
+]
+
+function parseFile(content: string): ts.SourceFile {
+  return ts.createSourceFile('bootstrap-registrations.generated.ts', content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+}
+
+function expectNoSyntaxErrors(content: string): void {
+  const sourceFile = parseFile(content)
+  const diagnostics = (sourceFile as unknown as { parseDiagnostics?: ts.Diagnostic[] }).parseDiagnostics ?? []
+  expect(diagnostics.map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, ' '))).toEqual([])
+}
+
+function parseImports(content: string): Array<{ moduleSpecifier: string; names: string[] }> {
+  return parseFile(content)
+    .statements.filter(ts.isImportDeclaration)
+    .map((declaration) => {
+      const bindings = declaration.importClause?.namedBindings
+      return {
+        moduleSpecifier: (declaration.moduleSpecifier as ts.StringLiteral).text,
+        names: bindings && ts.isNamedImports(bindings) ? bindings.elements.map((element) => element.name.text) : [],
+      }
+    })
+}
+
+function parseRegistrationCalls(content: string): string[] {
+  const sourceFile = parseFile(content)
+  const declaration = sourceFile.statements.find(
+    (statement): statement is ts.FunctionDeclaration =>
+      ts.isFunctionDeclaration(statement) && statement.name?.text === 'runBootstrapRegistrations',
+  )
+  if (!declaration) throw new Error('runBootstrapRegistrations declaration not found')
+  return (declaration.body?.statements ?? []).map((statement) => statement.getText(sourceFile).replace(/;$/, ''))
+}
+
+function isExportedVoidFunction(content: string): boolean {
+  const declaration = parseFile(content).statements.find(
+    (statement): statement is ts.FunctionDeclaration =>
+      ts.isFunctionDeclaration(statement) && statement.name?.text === 'runBootstrapRegistrations',
+  )
+  if (!declaration) return false
+  const isExported = declaration.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false
+  return isExported && declaration.type?.kind === ts.SyntaxKind.VoidKeyword
+}
+
+describe('renderBootstrapRegistrationsFile', () => {
+  it('emits the core route registrations when no plugin contributes one', () => {
+    const content = renderBootstrapRegistrationsFile({
+      entryImports: CORE_ENTRY_IMPORTS,
+      registrationImports: CORE_REGISTRATION_IMPORTS,
+      calls: CORE_CALLS,
+    })
+
+    expectNoSyntaxErrors(content)
+    expect(content.startsWith('// AUTO-GENERATED by mercato generate registry\n')).toBe(true)
+    expect(isExportedVoidFunction(content)).toBe(true)
+    expect(parseImports(content)).toEqual([
+      { moduleSpecifier: './backend-routes.generated', names: ['backendRoutes'] },
+      { moduleSpecifier: './frontend-routes.generated', names: ['frontendRoutes'] },
+      {
+        moduleSpecifier: '@open-mercato/shared/modules/registry',
+        names: ['registerBackendRouteManifests', 'registerFrontendRouteManifests'],
+      },
+    ])
+    expect(parseRegistrationCalls(content)).toEqual(CORE_CALLS)
+  })
+
+  it('appends a single plugin registration after the core ones', () => {
+    const content = renderBootstrapRegistrationsFile({
+      entryImports: [
+        ...CORE_ENTRY_IMPORTS,
+        'import { securityMfaProviderEntries } from "./security-mfa-providers.generated"',
+      ],
+      registrationImports: [
+        ...CORE_REGISTRATION_IMPORTS,
+        "import { registerMfaProviders } from '@open-mercato/core/modules/security/mfa'",
+      ],
+      calls: [...CORE_CALLS, 'registerMfaProviders(securityMfaProviderEntries)'],
+    })
+
+    expectNoSyntaxErrors(content)
+    expect(parseImports(content).map((parsed) => parsed.moduleSpecifier)).toEqual([
+      './backend-routes.generated',
+      './frontend-routes.generated',
+      './security-mfa-providers.generated',
+      '@open-mercato/shared/modules/registry',
+      '@open-mercato/core/modules/security/mfa',
+    ])
+    expect(parseRegistrationCalls(content)).toEqual([
+      ...CORE_CALLS,
+      'registerMfaProviders(securityMfaProviderEntries)',
+    ])
+  })
+
+  it('de-duplicates an identical registration import contributed by two plugins', () => {
+    const sharedRegistrationImport = "import { registerEntries } from '@open-mercato/core/modules/shared/registrations'"
+    const content = renderBootstrapRegistrationsFile({
+      entryImports: [
+        ...CORE_ENTRY_IMPORTS,
+        'import { firstPluginEntries } from "./first-plugin.generated"',
+        'import { secondPluginEntries } from "./second-plugin.generated"',
+      ],
+      registrationImports: [...CORE_REGISTRATION_IMPORTS, sharedRegistrationImport, sharedRegistrationImport],
+      calls: [...CORE_CALLS, 'registerEntries(firstPluginEntries)', 'registerEntries(secondPluginEntries)'],
+    })
+
+    expectNoSyntaxErrors(content)
+    expect(parseImports(content).filter((parsed) => parsed.names.includes('registerEntries'))).toHaveLength(1)
+    expect(parseRegistrationCalls(content)).toEqual([
+      ...CORE_CALLS,
+      'registerEntries(firstPluginEntries)',
+      'registerEntries(secondPluginEntries)',
+    ])
+  })
+
+  it('emits a valid module with an empty body when nothing registers at all', () => {
+    const content = renderBootstrapRegistrationsFile({ entryImports: [], registrationImports: [], calls: [] })
+
+    expectNoSyntaxErrors(content)
+    expect(isExportedVoidFunction(content)).toBe(true)
+    expect(parseImports(content)).toEqual([])
+    expect(parseRegistrationCalls(content)).toEqual([])
+  })
+
+  it('fails at generation time and names the statement when a plugin import is malformed', () => {
+    expect(() =>
+      renderBootstrapRegistrationsFile({
+        entryImports: CORE_ENTRY_IMPORTS,
+        registrationImports: [...CORE_REGISTRATION_IMPORTS, 'registerSomething from "./not-an-import"'],
+        calls: CORE_CALLS,
+      }),
+    ).toThrow('Expected import declaration, received: registerSomething from "./not-an-import"')
+  })
+
+  it('fails when a plugin import uses a non-literal module specifier', () => {
+    expect(() =>
+      renderBootstrapRegistrationsFile({
+        entryImports: CORE_ENTRY_IMPORTS,
+        registrationImports: [...CORE_REGISTRATION_IMPORTS, 'import { registerSomething } from `./templated`'],
+        calls: CORE_CALLS,
+      }),
+    ).toThrow('Unsupported import declaration: import { registerSomething } from `./templated`')
+  })
+
+  it('pins the emitted text so emitter changes surface as a reviewable diff', () => {
+    expect(
+      renderBootstrapRegistrationsFile({
+        entryImports: CORE_ENTRY_IMPORTS,
+        registrationImports: CORE_REGISTRATION_IMPORTS,
+        calls: CORE_CALLS,
+      }),
+    ).toMatchSnapshot()
+  })
+})

package/src/lib/generators/__tests__/command-loaders.test.ts

@@ -0,0 +1,239 @@
+/**
+ * Contract tests for `renderCommandLoadersFile`, the emitter behind
+ * `command-loaders.generated.ts`.
+ *
+ * The emitter is exercised directly rather than through a full generate run so the
+ * assertions stay readable and fast. Expectations are structural — the file is parsed
+ * and its exported array is inspected — so they survive the formatting differences a
+ * ts-morph emitter introduces. One inline snapshot pins the emitted text as well, so a
+ * reviewer can see the formatting delta of any future emitter change in the diff.
+ */
+import ts from 'typescript-js'
+import { renderCommandLoadersFile, type CommandLoaderGenerationEntry } from '../module-registry'
+
+type ParsedLoaderEntry = {
+  moduleId?: string
+  id?: string
+  key?: string
+  loadImportPath?: string
+  propertyOrder: string[]
+}
+
+function parseFile(content: string): ts.SourceFile {
+  return ts.createSourceFile('command-loaders.generated.ts', content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+}
+
+function expectNoSyntaxErrors(content: string): void {
+  const sourceFile = parseFile(content)
+  const diagnostics = (sourceFile as unknown as { parseDiagnostics?: ts.Diagnostic[] }).parseDiagnostics ?? []
+  expect(diagnostics.map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, ' '))).toEqual([])
+}
+
+function findExportedArray(sourceFile: ts.SourceFile, exportName: string): ts.ArrayLiteralExpression {
+  let found: ts.ArrayLiteralExpression | null = null
+  const visit = (node: ts.Node): void => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === exportName) {
+      if (node.initializer && ts.isArrayLiteralExpression(node.initializer)) {
+        found = node.initializer
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sourceFile)
+  if (!found) throw new Error(`Exported array "${exportName}" not found`)
+  return found
+}
+
+function readStringLiteral(node: ts.Expression): string | undefined {
+  return ts.isStringLiteralLike(node) ? node.text : undefined
+}
+
+function parseTypeOnlyImports(sourceFile: ts.SourceFile): Array<{ moduleSpecifier: string; names: string[] }> {
+  return sourceFile.statements
+    .filter(ts.isImportDeclaration)
+    .filter((declaration) => declaration.importClause?.isTypeOnly === true)
+    .map((declaration) => {
+      const bindings = declaration.importClause?.namedBindings
+      return {
+        moduleSpecifier: (declaration.moduleSpecifier as ts.StringLiteral).text,
+        names: bindings && ts.isNamedImports(bindings) ? bindings.elements.map((element) => element.name.text) : [],
+      }
+    })
+}
+
+function readExportedArrayTypeAnnotation(sourceFile: ts.SourceFile, exportName: string): string | undefined {
+  let annotation: string | undefined
+  const visit = (node: ts.Node): void => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === exportName) {
+      annotation = node.type?.getText(sourceFile)
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sourceFile)
+  return annotation
+}
+
+function readDefaultExportedIdentifier(sourceFile: ts.SourceFile): string | undefined {
+  const assignment = sourceFile.statements.find(ts.isExportAssignment)
+  if (!assignment || assignment.isExportEquals) return undefined
+  return ts.isIdentifier(assignment.expression) ? assignment.expression.text : undefined
+}
+
+function readLoadImportPath(node: ts.Expression): string | undefined {
+  if (!ts.isArrowFunction(node)) return undefined
+  const body = node.body
+  if (ts.isBlock(body)) return undefined
+  if (!ts.isCallExpression(body) || body.expression.kind !== ts.SyntaxKind.ImportKeyword) return undefined
+  const [specifier] = body.arguments
+  return specifier ? readStringLiteral(specifier) : undefined
+}
+
+function parseLoaderEntries(content: string): ParsedLoaderEntry[] {
+  const sourceFile = parseFile(content)
+  const array = findExportedArray(sourceFile, 'commandLoaderEntries')
+  return array.elements.map((element) => {
+    if (!ts.isObjectLiteralExpression(element)) throw new Error('Expected an object literal entry')
+    const parsed: ParsedLoaderEntry = { propertyOrder: [] }
+    for (const property of element.properties) {
+      if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name)) continue
+      const name = property.name.text
+      parsed.propertyOrder.push(name)
+      if (name === 'moduleId') parsed.moduleId = readStringLiteral(property.initializer)
+      if (name === 'id') parsed.id = readStringLiteral(property.initializer)
+      if (name === 'key') parsed.key = readStringLiteral(property.initializer)
+      if (name === 'load') parsed.loadImportPath = readLoadImportPath(property.initializer)
+    }
+    return parsed
+  })
+}
+
+function entry(overrides: Partial<CommandLoaderGenerationEntry> = {}): CommandLoaderGenerationEntry {
+  return {
+    moduleId: 'catalog',
+    key: 'catalog:commands:products',
+    importPath: '@open-mercato/core/modules/catalog/commands/products',
+    ids: ['catalog.products.create'],
+    ...overrides,
+  }
+}
+
+describe('renderCommandLoadersFile', () => {
+  it('emits a parseable module with the documented exports', () => {
+    const content = renderCommandLoadersFile([entry()])
+
+    expectNoSyntaxErrors(content)
+    expect(content.startsWith('// AUTO-GENERATED by mercato generate command-loaders\n')).toBe(true)
+    expect(content.endsWith('\n')).toBe(true)
+
+    const sourceFile = parseFile(content)
+    expect(parseTypeOnlyImports(sourceFile)).toEqual([
+      { moduleSpecifier: '@open-mercato/shared/lib/commands', names: ['CommandLoader'] },
+    ])
+    expect(readExportedArrayTypeAnnotation(sourceFile, 'commandLoaderEntries')).toBe('CommandLoader[]')
+    expect(readDefaultExportedIdentifier(sourceFile)).toBe('commandLoaderEntries')
+  })
+
+  it('emits one id-scoped entry per command id followed by the module-scoped fallback entry', () => {
+    const content = renderCommandLoadersFile([
+      entry({ ids: ['catalog.products.create', 'catalog.products.delete'] }),
+    ])
+
+    expect(parseLoaderEntries(content)).toEqual([
+      {
+        moduleId: 'catalog',
+        id: 'catalog.products.create',
+        key: 'catalog:commands:products',
+        loadImportPath: '@open-mercato/core/modules/catalog/commands/products',
+        propertyOrder: ['moduleId', 'id', 'key', 'load'],
+      },
+      {
+        moduleId: 'catalog',
+        id: 'catalog.products.delete',
+        key: 'catalog:commands:products',
+        loadImportPath: '@open-mercato/core/modules/catalog/commands/products',
+        propertyOrder: ['moduleId', 'id', 'key', 'load'],
+      },
+      {
+        moduleId: 'catalog',
+        id: undefined,
+        key: 'catalog:commands:products',
+        loadImportPath: '@open-mercato/core/modules/catalog/commands/products',
+        propertyOrder: ['moduleId', 'key', 'load'],
+      },
+    ])
+  })
+
+  it('keeps entries from several modules in input order', () => {
+    const content = renderCommandLoadersFile([
+      entry(),
+      entry({
+        moduleId: 'sales',
+        key: 'sales:commands:orders',
+        importPath: '@open-mercato/core/modules/sales/commands/orders',
+        ids: ['sales.orders.create'],
+      }),
+    ])
+
+    expect(parseLoaderEntries(content).map((parsed) => [parsed.key, parsed.id])).toEqual([
+      ['catalog:commands:products', 'catalog.products.create'],
+      ['catalog:commands:products', undefined],
+      ['sales:commands:orders', 'sales.orders.create'],
+      ['sales:commands:orders', undefined],
+    ])
+  })
+
+  it('emits the module-scoped entry only when a module declares no command ids', () => {
+    const content = renderCommandLoadersFile([entry({ ids: [] })])
+
+    expectNoSyntaxErrors(content)
+    expect(parseLoaderEntries(content)).toEqual([
+      {
+        moduleId: 'catalog',
+        id: undefined,
+        key: 'catalog:commands:products',
+        loadImportPath: '@open-mercato/core/modules/catalog/commands/products',
+        propertyOrder: ['moduleId', 'key', 'load'],
+      },
+    ])
+  })
+
+  it('emits a valid module with an empty array when no module contributes commands', () => {
+    const content = renderCommandLoadersFile([])
+
+    expectNoSyntaxErrors(content)
+    expect(parseLoaderEntries(content)).toEqual([])
+  })
+
+  it('rejects the same command id contributed by two different modules', () => {
+    expect(() =>
+      renderCommandLoadersFile([
+        entry(),
+        entry({
+          moduleId: 'sales',
+          key: 'sales:commands:products',
+          importPath: '@open-mercato/core/modules/sales/commands/products',
+        }),
+      ]),
+    ).toThrow(
+      '[generate] Duplicate command id "catalog.products.create" discovered in "catalog:commands:products" and "sales:commands:products"',
+    )
+  })
+
+  it('tolerates the same command id repeated within one module key', () => {
+    const content = renderCommandLoadersFile([
+      entry({ ids: ['catalog.products.create', 'catalog.products.create'] }),
+    ])
+
+    expect(parseLoaderEntries(content)).toHaveLength(3)
+  })
+
+  it('rejects an unsafe import path instead of emitting it', () => {
+    expect(() => renderCommandLoadersFile([entry({ importPath: '' })])).toThrow(
+      'Unsafe generated module specifier',
+    )
+  })
+
+  it('pins the emitted text so emitter changes surface as a reviewable diff', () => {
+    expect(renderCommandLoadersFile([entry()])).toMatchSnapshot()
+  })
+})