@open-mercato/cli 0.9.1-develop.7477.1.64ba865101 → 0.9.1-develop.7496.1.3346415f94

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.9.1-develop.7477.1.64ba865101",
+  "version": "0.9.1-develop.7496.1.3346415f94",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,10 +60,10 @@
     "@mikro-orm/decorators": "^7.1.14",
     "@mikro-orm/migrations": "^7.1.14",
     "@mikro-orm/postgresql": "^7.1.14",
-    "@open-mercato/events": "0.9.1-develop.7477.1.64ba865101",
-    "@open-mercato/queue": "0.9.1-develop.7477.1.64ba865101",
-    "@open-mercato/shared": "0.9.1-develop.7477.1.64ba865101",
-    "@open-mercato/telemetry": "0.9.1-develop.7477.1.64ba865101",
+    "@open-mercato/events": "0.9.1-develop.7496.1.3346415f94",
+    "@open-mercato/queue": "0.9.1-develop.7496.1.3346415f94",
+    "@open-mercato/shared": "0.9.1-develop.7496.1.3346415f94",
+    "@open-mercato/telemetry": "0.9.1-develop.7496.1.3346415f94",
     "cross-spawn": "^7.0.6",
     "pg": "8.23.0",
     "semver": "^7.8.5",
@@ -74,10 +74,10 @@
     "typescript-js": "npm:typescript@6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.9.1-develop.7477.1.64ba865101"
+    "@open-mercato/shared": "0.9.1-develop.7496.1.3346415f94"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.9.1-develop.7477.1.64ba865101",
+    "@open-mercato/shared": "0.9.1-develop.7496.1.3346415f94",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.12"

package/src/__tests__/mercato.test.ts

@@ -3,7 +3,9 @@ import {
   registerCliModules,
   getCliModules,
   hasCliModules,
+  isHelpRequest,
   padByCodePointWidth,
+  resolveEnvBootstrapOptions,
   run,
 } from '../mercato'
 import { pathIncludes } from '../lib/__tests__/path-helpers'
@@ -187,6 +189,264 @@ describe('padByCodePointWidth', () => {
   })
 })
 
+describe('--help never triggers side effects (issue #5581)', () => {
+  beforeEach(() => {
+    jest.restoreAllMocks()
+  })
+
+  describe('isHelpRequest', () => {
+    it('matches the long and short help flags in any position', () => {
+      expect(isHelpRequest(['db', 'generate', '--help'])).toBe(true)
+      expect(isHelpRequest(['-h'])).toBe(true)
+    })
+
+    it('does not match arguments that merely contain the flag text', () => {
+      expect(isHelpRequest(['db', 'generate'])).toBe(false)
+      expect(isHelpRequest(['--help-me'])).toBe(false)
+      expect(isHelpRequest(['--no-help'])).toBe(false)
+      expect(isHelpRequest([])).toBe(false)
+    })
+  })
+
+  describe('resolveEnvBootstrapOptions', () => {
+    it('refuses to create .env from .env.example for a help invocation', () => {
+      expect(resolveEnvBootstrapOptions(['db', 'generate', '--help'])).toEqual({
+        createIfMissing: false,
+        quiet: true,
+      })
+      expect(resolveEnvBootstrapOptions(['-h'])).toEqual({ createIfMissing: false, quiet: true })
+    })
+
+    it('still creates .env for a real command invocation', () => {
+      expect(resolveEnvBootstrapOptions(['db', 'generate'])).toEqual({
+        createIfMissing: true,
+        quiet: false,
+      })
+    })
+
+    it('keeps the pre-existing deploy and telemetry opt-outs', () => {
+      expect(resolveEnvBootstrapOptions(['deploy', 'railway'])).toEqual({
+        createIfMissing: false,
+        quiet: true,
+      })
+      expect(resolveEnvBootstrapOptions(['telemetry', 'init'])).toEqual({
+        createIfMissing: false,
+        quiet: true,
+      })
+    })
+  })
+
+  describe('dispatcher help branch', () => {
+    it('prints usage instead of running db:generate when --help is passed', async () => {
+      const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+      const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+      const dbGenerate = jest.fn()
+
+      registerCliModules([
+        {
+          id: 'db',
+          cli: [{ command: 'generate', help: 'Writes migrations. Applies nothing.', run: dbGenerate }],
+        } as any,
+      ])
+
+      const exitCode = await run(['node', 'mercato', 'db', 'generate', '--help'])
+
+      expect(exitCode).toBe(0)
+      expect(dbGenerate).not.toHaveBeenCalled()
+      const printed = consoleLogSpy.mock.calls.map((call) => String(call[0])).join('\n')
+      expect(printed).toContain('mercato db generate [args]')
+      expect(printed).toContain('Writes migrations. Applies nothing.')
+
+      consoleLogSpy.mockRestore()
+      consoleErrorSpy.mockRestore()
+    })
+
+    it('prints usage instead of running db:migrate when -h is passed', async () => {
+      const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+      const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+      const dbMigrate = jest.fn()
+
+      registerCliModules([
+        { id: 'db', cli: [{ command: 'migrate', run: dbMigrate }] } as any,
+      ])
+
+      const exitCode = await run(['node', 'mercato', 'db', 'migrate', '-h'])
+
+      expect(exitCode).toBe(0)
+      expect(dbMigrate).not.toHaveBeenCalled()
+
+      consoleLogSpy.mockRestore()
+      consoleErrorSpy.mockRestore()
+    })
+
+    it('prints usage instead of destroying data when greenfield --yes --help is passed', async () => {
+      const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+      const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+      const dbGreenfield = jest.fn()
+
+      registerCliModules([
+        {
+          id: 'db',
+          cli: [{
+            command: 'greenfield',
+            help: 'Destroys all data.',
+            run: dbGreenfield,
+          }],
+        } as any,
+      ])
+
+      // --yes is the flag that skips greenfield's confirmation prompt, so pairing it with
+      // --help is the scenario that must never reach `run`, regardless of flag order.
+      const exitCode = await run(['node', 'mercato', 'db', 'greenfield', '--yes', '--help'])
+
+      expect(exitCode).toBe(0)
+      expect(dbGreenfield).not.toHaveBeenCalled()
+
+      consoleLogSpy.mockRestore()
+      consoleErrorSpy.mockRestore()
+    })
+
+    it('forwards --help to commands that declare handlesHelp', async () => {
+      const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+      const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+      const deploy = jest.fn()
+
+      registerCliModules([
+        { id: 'deploy', cli: [{ command: 'railway', handlesHelp: true, run: deploy }] } as any,
+      ])
+
+      const exitCode = await run(['node', 'mercato', 'deploy', 'railway', '--help'])
+
+      expect(exitCode).toBe(0)
+      expect(deploy).toHaveBeenCalledWith(['--help'])
+
+      consoleLogSpy.mockRestore()
+      consoleErrorSpy.mockRestore()
+    })
+
+    it('lists the module commands when the help flag sits in the command slot', async () => {
+      const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+      const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+      const dbGenerate = jest.fn()
+
+      registerCliModules([
+        {
+          id: 'db',
+          cli: [
+            { command: 'generate', run: dbGenerate },
+            { command: 'migrate', run: jest.fn() },
+          ],
+        } as any,
+      ])
+
+      const exitCode = await run(['node', 'mercato', 'db', '--help'])
+
+      expect(exitCode).toBe(0)
+      expect(dbGenerate).not.toHaveBeenCalled()
+      expect(consoleErrorSpy).not.toHaveBeenCalled()
+      const printed = consoleLogSpy.mock.calls.map((call) => String(call[0])).join('\n')
+      expect(printed).toContain('Commands for "db": generate, migrate')
+
+      consoleLogSpy.mockRestore()
+      consoleErrorSpy.mockRestore()
+    })
+
+    it('lets a self-documenting command print its own subcommand help', async () => {
+      const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+      const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+      // Mirrors packages/core/src/modules/configs/cli.ts, whose `cache` command routes
+      // --help to its own printCacheHelp() rather than to the dispatcher's generic usage.
+      const cache = jest.fn((rest: string[]) => {
+        if (rest[0] === '--help') console.log('configs cache: stats | purge | structural')
+      })
+
+      registerCliModules([
+        { id: 'configs', cli: [{ command: 'cache', handlesHelp: true, run: cache }] } as any,
+      ])
+
+      const exitCode = await run(['node', 'mercato', 'configs', 'cache', '--help'])
+
+      expect(exitCode).toBe(0)
+      expect(cache).toHaveBeenCalledWith(['--help'])
+      const printed = consoleLogSpy.mock.calls.map((call) => String(call[0])).join('\n')
+      expect(printed).toContain('configs cache: stats | purge | structural')
+      expect(printed).not.toContain('Usage: ✨ mercato configs cache [args]')
+
+      consoleLogSpy.mockRestore()
+      consoleErrorSpy.mockRestore()
+    })
+
+    it('still runs the command when no help flag is present', async () => {
+      const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+      const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+      const dbGenerate = jest.fn()
+
+      registerCliModules([
+        { id: 'db', cli: [{ command: 'generate', run: dbGenerate }] } as any,
+      ])
+
+      const exitCode = await run(['node', 'mercato', 'db', 'generate'])
+
+      expect(exitCode).toBe(0)
+      expect(dbGenerate).toHaveBeenCalled()
+
+      consoleLogSpy.mockRestore()
+      consoleErrorSpy.mockRestore()
+    })
+  })
+
+  describe('top-level command help', () => {
+    it('prints usage instead of initializing the app when init --help is passed', async () => {
+      const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+      const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+
+      const exitCode = await run(['node', 'mercato', 'init', '--help'])
+
+      expect(exitCode).toBe(0)
+      const printed = consoleLogSpy.mock.calls.map((call) => String(call[0])).join('\n')
+      expect(printed).toContain('Usage: mercato init')
+
+      consoleLogSpy.mockRestore()
+      consoleErrorSpy.mockRestore()
+    })
+
+    it('prints usage instead of seeding when seed:defaults --help is passed', async () => {
+      const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+      const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+
+      const exitCode = await run(['node', 'mercato', 'seed:defaults', '--help'])
+
+      expect(exitCode).toBe(0)
+      const printed = consoleLogSpy.mock.calls.map((call) => String(call[0])).join('\n')
+      expect(printed).toContain('Usage: mercato seed:defaults')
+
+      consoleLogSpy.mockRestore()
+      consoleErrorSpy.mockRestore()
+    })
+
+    it.each(['constructor', 'toString', 'valueOf', 'hasOwnProperty', '__proto__'])(
+      'reports %s as an unknown module instead of matching an inherited prototype key',
+      async (inheritedKey) => {
+        const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+        const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+
+        registerCliModules([
+          { id: 'db', cli: [{ command: 'generate', run: jest.fn() }] } as any,
+        ])
+
+        const exitCode = await run(['node', 'mercato', inheritedKey, '--help'])
+
+        expect(exitCode).toBe(1)
+        const errors = consoleErrorSpy.mock.calls.map((call) => String(call[0])).join('\n')
+        expect(errors).toContain(`Module not found: "${inheritedKey}"`)
+
+        consoleLogSpy.mockRestore()
+        consoleErrorSpy.mockRestore()
+      },
+    )
+  })
+})
+
 describe('db command failure output', () => {
   const originalDatabaseUrl = process.env.DATABASE_URL
 

package/src/mercato.ts

@@ -327,7 +327,11 @@ async function ensureEnvLoaded(options: { createIfMissing?: boolean; quiet?: boo
       const examplePath = path.join(appDir, '.env.example')
       if (fs.existsSync(examplePath)) {
         fs.copyFileSync(examplePath, envPath)
-        console.log(`📋 Copied .env.example → .env (edit ${envPath} to customize)`)
+        console.log('')
+        console.log('⚠️  No .env was found, so one was created from .env.example.')
+        console.log(`   ${envPath}`)
+        console.log('   It carries the example placeholders — review DATABASE_URL and secrets before continuing.')
+        console.log('')
       }
     }
     if (fs.existsSync(envPath)) {
@@ -894,14 +898,67 @@ async function buildAllModules(): Promise<Module[]> {
   return all
 }
 
+export function isHelpRequest(args: string[]): boolean {
+  return args.some((arg) => arg === '--help' || arg === '-h')
+}
+
+// Top-level commands that return before the module dispatcher and therefore never reach its
+// generic help branch. Without an entry here, `mercato init --help` runs a full install.
+const TOP_LEVEL_COMMAND_HELP: Record<string, string[]> = {
+  init: [
+    'Usage: mercato init [--reinstall|-r] [--no-examples] [--stresstest [--lite] [--count=<n>]]',
+    'Initializes this app: installs dependencies, runs generators, applies migrations and seeds data.',
+  ],
+  'agentic:init': [
+    'Usage: mercato agentic:init [--force]',
+    'Scaffolds the agentic harness (AGENTS.md, .ai/ config and skills) into this app.',
+  ],
+  'seed:defaults': [
+    'Usage: mercato seed:defaults [--module <moduleId>]',
+    'Runs every enabled module\'s seedDefaults hook, or only the named module\'s.',
+  ],
+  'umes:list': [
+    'Usage: mercato umes:list',
+    'Lists the extension points every enabled module declares.',
+  ],
+  'umes:inspect': [
+    'Usage: mercato umes:inspect --module <moduleId>',
+    'Prints the extension surface a single module declares.',
+  ],
+  'umes:check': [
+    'Usage: mercato umes:check',
+    'Validates declared extension points against the modules that implement them.',
+  ],
+}
+
+// A help invocation must never materialize .env from .env.example — asking what the flags are
+// should not mutate the working tree, least of all with the example's placeholder DATABASE_URL.
+export function resolveEnvBootstrapOptions(parts: string[]): { createIfMissing: boolean; quiet: boolean } {
+  const first = parts[0]
+  const opaqueEnvCommand = first === 'deploy' || first === 'telemetry'
+  const helpRequested = isHelpRequest(parts)
+  return {
+    createIfMissing: !helpRequested && !opaqueEnvCommand,
+    quiet: helpRequested || opaqueEnvCommand,
+  }
+}
+
 export async function run(argv = process.argv) {
   const [, , ...parts] = argv
   const [first, second, ...remaining] = parts
-  await ensureEnvLoaded({
-    createIfMissing: first !== 'deploy' && first !== 'telemetry',
-    quiet: first === 'deploy' || first === 'telemetry',
-  })
-  
+  // Help must never have side effects: it must not create .env, and must not fall through
+  // to the command it is asking about.
+  const helpRequested = isHelpRequest(parts)
+  await ensureEnvLoaded(resolveEnvBootstrapOptions(parts))
+
+  // Object.hasOwn, not a truthiness check: the map is indexed with raw user input, and an
+  // inherited Object.prototype member (`constructor`, `toString`, …) would otherwise pass the
+  // guard and then fail to iterate instead of reporting the module as not found.
+  if (helpRequested && first && Object.hasOwn(TOP_LEVEL_COMMAND_HELP, first)) {
+    for (const line of TOP_LEVEL_COMMAND_HELP[first]) console.log(`  ${line}`)
+    return 0
+  }
+
   // Handle init command directly
   if (first === 'init') {
     const { execSync } = await import('child_process')
@@ -1633,6 +1690,8 @@ export async function run(argv = process.argv) {
     cli: [
       {
         command: 'railway',
+        // Parses --help/-h itself and prints railwayDeployHelp() without deploying.
+        handlesHelp: true,
         run: async (args: string[]) => {
           const { runRailwayDeploy } = await import('./lib/deploy/railway/index')
           await runRailwayDeploy(args)
@@ -2001,6 +2060,7 @@ export async function run(argv = process.argv) {
     cli: [
       {
         command: 'generate',
+        help: 'Generates a migration per module from the current ORM entities and refreshes each\nmodule\'s .snapshot-open-mercato.json. Writes files only — nothing is applied.',
         run: async () => {
           const { createResolver } = await import('./lib/resolver')
           const { dbGenerate } = await import('./lib/db')
@@ -2010,6 +2070,7 @@ export async function run(argv = process.argv) {
       },
       {
         command: 'migrate',
+        help: 'Applies every pending migration to the database DATABASE_URL points at.\nThis mutates the database — check .env before running it.',
         run: async () => {
           const { createResolver } = await import('./lib/resolver')
           const { dbMigrate } = await import('./lib/db')
@@ -2019,6 +2080,7 @@ export async function run(argv = process.argv) {
       },
       {
         command: 'greenfield',
+        help: 'Drops and recreates the schema from scratch, then re-applies every migration.\nDestroys all data. Pass --yes (-y) to skip the confirmation prompt.',
         run: async (args: string[]) => {
           const { createResolver } = await import('./lib/resolver')
           const { dbGreenfield } = await import('./lib/db')
@@ -2689,12 +2751,31 @@ export async function run(argv = process.argv) {
     console.log(pad(`Commands for "${modName}": ${mod.cli.map((c) => c.command).join(', ')}`))
     return 1
   }
+  // A help flag in the command slot (`mercato db --help`) asks what this module offers.
+  if (isHelpRequest([cmdName])) {
+    console.log(pad(`Usage: ✨ mercato ${modName} <command> [args]`))
+    console.log(pad(`Commands for "${modName}": ${mod.cli.map((c) => c.command).join(', ')}`))
+    return 0
+  }
   const cmd = mod.cli.find((c) => c.command === cmdName)
   if (!cmd) {
     console.error(`🤔 Unknown command "${cmdName}". Available: ${mod.cli.map((c) => c.command).join(', ')}`)
     return 1
   }
 
+  // `--help` must describe the command, never run it. Commands that parse the flag themselves
+  // opt out via `handlesHelp` so their own richer usage text still wins.
+  if (isHelpRequest(rest) && !cmd.handlesHelp) {
+    console.log(pad(`Usage: ✨ mercato ${modName} ${cmdName} [args]`))
+    if (cmd.help) {
+      console.log('')
+      for (const line of cmd.help.split('\n')) console.log(pad(line))
+    }
+    console.log('')
+    console.log(pad(`Commands for "${modName}": ${mod.cli.map((c) => c.command).join(', ')}`))
+    return 0
+  }
+
   console.log('')
   const started = Date.now()
   const loggedArgs = modName === 'deploy' && cmdName === 'railway'