@open-mercato/cli 0.6.7 → 0.6.8-develop.6875.1.871a4afc94

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.7",
+  "version": "0.6.8-develop.6875.1.871a4afc94",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,12 +56,13 @@
     "node": "24.x"
   },
   "dependencies": {
-    "@mikro-orm/core": "^7.1.5",
-    "@mikro-orm/decorators": "^7.1.5",
-    "@mikro-orm/migrations": "^7.1.5",
-    "@mikro-orm/postgresql": "^7.1.5",
-    "@open-mercato/queue": "0.6.7",
-    "@open-mercato/shared": "0.6.7",
+    "@mikro-orm/core": "^7.1.8",
+    "@mikro-orm/decorators": "^7.1.8",
+    "@mikro-orm/migrations": "^7.1.8",
+    "@mikro-orm/postgresql": "^7.1.8",
+    "@open-mercato/queue": "0.6.8-develop.6875.1.871a4afc94",
+    "@open-mercato/shared": "0.6.8-develop.6875.1.871a4afc94",
+    "@open-mercato/telemetry": "0.6.8-develop.6875.1.871a4afc94",
     "cross-spawn": "^7.0.6",
     "pg": "8.22.0",
     "semver": "^7.8.5",
@@ -72,13 +73,13 @@
     "typescript-js": "npm:typescript@6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.7"
+    "@open-mercato/shared": "0.6.8-develop.6875.1.871a4afc94"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.7",
+    "@open-mercato/shared": "0.6.8-develop.6875.1.871a4afc94",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
-    "ts-jest": "^29.4.11"
+    "ts-jest": "^29.4.12"
   },
   "publishConfig": {
     "access": "public"
@@ -87,5 +88,6 @@
     "type": "git",
     "url": "https://github.com/open-mercato/open-mercato",
     "directory": "packages/cli"
-  }
+  },
+  "stableVersion": "0.6.7"
 }

package/src/bin.ts

@@ -4,7 +4,12 @@
  * Called from within a Next.js app directory as: yarn mercato <command>
  * Uses dynamic app resolution to find generated files at .mercato/generated/
  */
-import { run } from './mercato.js'
+import {
+  getTelemetryRuntime,
+  isTelemetryBackendEnabled,
+} from '@open-mercato/shared/lib/telemetry/runtime'
+// `run` is imported dynamically inside `main()` so telemetry can initialize
+// before the mercato entry (and its Postgres driver) loads — see main().
 
 // Commands that can run without bootstrap (without generated files)
 // - generate: creates the generated files
@@ -18,6 +23,7 @@ const BOOTSTRAP_FREE_COMMANDS = [
   'db',
   'init',
   'agentic:init',
+  'telemetry',
   'eject',
   'test',
   'test:integration',
@@ -85,6 +91,26 @@ async function main(): Promise<void> {
   const requiresBootstrap = needsBootstrap(process.argv)
 
   if (requiresBootstrap) {
+    // Load the app's `.env` BEFORE initTelemetry(): `run()` only dotenv-loads it
+    // later (ensureEnvLoaded), which is too late — TELEMETRY_BACKEND set only in
+    // `.env` would silently resolve to `noop` for worker/scheduler processes.
+    // The loader touches only the resolver + dotenv (no `pg`), preserving the
+    // instrumentation load-order guarantee below.
+    const { loadAppEnv } = await import('./lib/load-env.js')
+    await loadAppEnv()
+
+    // Initialize telemetry BEFORE bootstrapping the app graph. Bootstrap and the
+    // per-command handlers load MikroORM's Postgres driver → `pg`, and the
+    // OpenTelemetry pg/undici auto-instrumentation only records spans for a
+    // driver required AFTER the SDK has started. Registering here — ahead of any
+    // app module — is what lets long-running worker/scheduler processes emit DB
+    // spans (not just the bullmq-otel add/process envelope). The package itself
+    // is not imported unless an explicit supported backend is selected.
+    if (isTelemetryBackendEnabled()) {
+      const { initTelemetry } = await import('@open-mercato/telemetry')
+      await initTelemetry()
+    }
+
     const bootstrapSucceeded = await tryBootstrap()
     if (!bootstrapSucceeded) {
       console.error('╔═══════════════════════════════════════════════════════════════════╗')
@@ -100,7 +126,13 @@ async function main(): Promise<void> {
     }
   }
 
+  // Dynamic import (not a top-level static import) so the mercato entry — and the
+  // Postgres driver it pulls in — loads only after initTelemetry() above.
+  const { run } = await import('./mercato.js')
   const code = await run(process.argv)
+  // Flush spans/logs for commands that return (workers block forever and flush via
+  // their own shutdown handler instead).
+  await getTelemetryRuntime()?.shutdown()
   process.exit(code ?? 0)
 }
 

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

@@ -14,6 +14,8 @@ const cliIntegrationRunnerPath = path.join(cliDir, 'src', 'lib', 'testing', 'int
 const standaloneTemplatePackageJsonPath = path.join(repoRoot, 'packages', 'create-app', 'template', 'package.json.template')
 const agenticRoot = path.join(repoRoot, 'packages', 'create-app', 'agentic')
 const packagesRoot = path.join(repoRoot, 'packages')
+const coreVersion = JSON.parse(fs.readFileSync(path.join(packagesRoot, 'core', 'package.json'), 'utf8')).version as string
+const UNROUTED_PACKAGE_GUIDES = new Set(['cache', 'core', 'events', 'queue', 'search', 'shared', 'ui'])
 
 // Modules the standalone fixture enables in src/modules.ts. Both are on the
 // fact-sheet allowlist, so agentic:init must ship exactly their fact-sheets
@@ -24,7 +26,7 @@ function normalizePath(value: string): string {
   return value.split(path.sep).join('/')
 }
 
-function runCommand(command: string, args: string[], cwd: string): string {
+function runCommand(command: string, args: string[], cwd: string, env: NodeJS.ProcessEnv = {}): string {
   return execFileSync(command, args, {
     cwd,
     encoding: 'utf8',
@@ -36,6 +38,7 @@ function runCommand(command: string, args: string[], cwd: string): string {
       // whose external step (`npx skills add`) needs the network. Local tier
       // symlinks are still installed.
       OM_SKIP_EXTERNAL_SKILLS: '1',
+      ...env,
     },
   })
 }
@@ -61,16 +64,48 @@ function createStandaloneFixture(rootDir: string): string {
       {
         name: 'sample-store',
         private: true,
+        dependencies: { '@open-mercato/core': coreVersion },
       },
       null,
       2,
     ),
   )
-  const moduleEntries = FIXTURE_ENABLED_MODULES.map((moduleId) => `  { id: '${moduleId}' },`).join('\n')
+  const moduleEntries = FIXTURE_ENABLED_MODULES
+    .map((moduleId) => `  { id: '${moduleId}', from: '@open-mercato/core' },`)
+    .join('\n')
   writeFile(path.join(appDir, 'src', 'modules.ts'), `export const enabledModules = [\n${moduleEntries}\n]\n`)
   return appDir
 }
 
+function installFakeFrameworkPackage(appDir: string): string {
+  const packageRoot = path.join(appDir, 'node_modules', '@open-mercato', 'core')
+  writeFile(path.join(packageRoot, 'package.json'), JSON.stringify({
+    name: '@open-mercato/core',
+    version: coreVersion,
+    type: 'module',
+    exports: { '.': './dist/index.js' },
+  }))
+  writeFile(path.join(packageRoot, 'dist', 'index.js'), 'export {}\n')
+  writeFile(path.join(packageRoot, 'AGENTS.md'), '# Installed core instructions\n')
+  for (const moduleId of FIXTURE_ENABLED_MODULES) {
+    writeFile(path.join(packageRoot, 'src', 'modules', moduleId, 'AGENTS.md'), `# Installed ${moduleId} instructions\n`)
+    writeFile(
+      path.join(packageRoot, 'src', 'modules', moduleId, 'data', 'entities.ts'),
+      `export class ${moduleId === 'customers' ? 'Person' : 'Sale'} {}\n`,
+    )
+  }
+  return packageRoot
+}
+
+function snapshotTextFiles(rootDir: string): Record<string, string> {
+  return Object.fromEntries(
+    listRelativeFiles(rootDir).map((relativePath) => [
+      relativePath,
+      fs.readFileSync(path.join(rootDir, relativePath), 'utf8'),
+    ]),
+  )
+}
+
 function listRelativeFiles(rootDir: string): string[] {
   if (!fs.existsSync(rootDir)) {
     return []
@@ -194,7 +229,7 @@ function expectedGuideOutputNames(): string[] {
 
   for (const packageName of fs.readdirSync(packagesRoot)) {
     const packageGuide = path.join(packagesRoot, packageName, 'agentic', 'standalone-guide.md')
-    if (fs.existsSync(packageGuide)) {
+    if (fs.existsSync(packageGuide) && !UNROUTED_PACKAGE_GUIDES.has(packageName)) {
       collected.add(`${packageName}.md`)
     }
 
@@ -214,8 +249,14 @@ function expectedGuideOutputNames(): string[] {
   // Generated fact-sheet artifacts (spec 2026-06-27-ts-morph-module-fact-sheets):
   // the module-facts.json sidecar is copied as-is and fact-sheets are filtered to the
   // fixture's enabled modules. The legacy core.<module>.md redirect stubs are no longer
-  // emitted (#3754).
+  // emitted (#3754). framework-extension-points.md is likewise generated into
+  // dist/agentic/guides by both build.mjs pipelines (#4810) rather than checked in
+  // alongside the static conceptual guides, so it needs an explicit entry here.
   collected.add('module-facts.json')
+  collected.add('framework-extension-points.md')
+  collected.add('upstream/AGENTS.md')
+  collected.add('upstream/BACKWARD_COMPATIBILITY.md')
+  collected.add('upstream/manifest.json')
   for (const moduleId of FIXTURE_ENABLED_MODULES) {
     collected.add(normalizePath(path.join('modules', `${moduleId}.md`)))
   }
@@ -262,14 +303,17 @@ test.describe('TC-INT-008: CLI agentic init mirrors standalone scaffolding asset
 
       const agentsSource = fs.readFileSync(path.join(appDir, 'AGENTS.md'), 'utf8')
       expect(agentsSource).toContain('<!-- CODEX_ENFORCEMENT_RULES_START -->')
-      expect(agentsSource).toContain('.ai/guides/core.md')
+      expect(agentsSource).toContain('.ai/guides/upstream/BACKWARD_COMPATIBILITY.md')
 
-      // The Module-Specific Guides marker block lists exactly the enabled modules'
-      // fact-sheets (enabled ∩ allowlist), not the full bundled set.
+      // The Module-Specific Guides marker block is a compact enabled-module ID
+      // index (enabled ∩ bundled) plus one progressively loaded path pattern.
       for (const moduleId of FIXTURE_ENABLED_MODULES) {
-        expect(agentsSource).toContain(`.ai/guides/modules/${moduleId}.md`)
+        expect(agentsSource).toContain(`\`${moduleId}\``)
       }
-      expect(agentsSource).not.toContain('.ai/guides/modules/auth.md')
+      expect(agentsSource).toContain('`.ai/guides/modules/<id>.md`')
+      expect(agentsSource.match(/\.ai\/guides\/modules\//g)).toHaveLength(1)
+      expect(agentsSource).not.toContain('`auth`')
+      expect(agentsSource).not.toContain('Core CRM capabilities')
 
       const specsReadmeSource = fs.readFileSync(path.join(appDir, '.ai', 'specs', 'README.md'), 'utf8')
       expect(specsReadmeSource).toContain('sample-store')
@@ -308,4 +352,58 @@ test.describe('TC-INT-008: CLI agentic init mirrors standalone scaffolding asset
       fs.rmSync(tempRoot, { recursive: true, force: true })
     }
   })
+
+  test('emits a runnable exact-version framework context escape hatch for an installed package', () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'mercato-cli-framework-context-'))
+
+    try {
+      const appDir = createStandaloneFixture(tempRoot)
+      const packageRoot = installFakeFrameworkPackage(appDir)
+      const resolvedPackageRoot = fs.realpathSync(packageRoot)
+      const packageBefore = snapshotTextFiles(packageRoot)
+
+      runMercato(['agentic:init', '--tool=codex'], appDir)
+      const generatedScript = path.join(appDir, 'scripts', 'framework-context.mjs')
+      expect(fs.existsSync(generatedScript)).toBe(true)
+
+      const output = runCommand(
+        process.execPath,
+        [generatedScript, '--module', 'customers', '--query', 'Person', '--json'],
+        appDir,
+        // The generated standalone helper must not depend on a globally
+        // installed ripgrep binary; process.execPath is already absolute.
+        { PATH: '', Path: '' },
+      )
+      const context = JSON.parse(output) as {
+        module: string
+        package: { name: string; version: string; root: string }
+        sourceKind: string
+        sourceRoot: string
+        materializedSource: string
+        instructions: Array<{ kind: string; path: string | null; materializedPath?: string }>
+        boundedSearch: { status: string; matches: number; maxMatches: number; result: string }
+        warnings: string[]
+      }
+
+      expect(context.module).toBe('customers')
+      expect(context.package).toEqual({ name: '@open-mercato/core', version: coreVersion, root: resolvedPackageRoot })
+      expect(context.sourceKind).toBe('source')
+      expect(normalizePath(context.sourceRoot)).toBe(normalizePath(path.join(resolvedPackageRoot, 'src', 'modules', 'customers')))
+      expect(context.instructions.filter((entry) => entry.path).map((entry) => entry.kind)).toEqual([
+        'standalone-root',
+        'upstream-bc',
+        'package',
+        'module-1',
+        'upstream-root',
+      ])
+      expect(context.instructions.filter((entry) => entry.path).every((entry) => entry.materializedPath)).toBe(true)
+      expect(context.boundedSearch).toMatchObject({ status: 'matched', matches: 1, maxMatches: 200 })
+      expect(fs.existsSync(path.join(appDir, context.materializedSource))).toBe(true)
+      expect(fs.existsSync(path.join(appDir, context.boundedSearch.result))).toBe(true)
+      expect(context.warnings.some((warning) => warning.includes('Generated facts for customers are stale'))).toBe(false)
+      expect(snapshotTextFiles(packageRoot)).toEqual(packageBefore)
+    } finally {
+      fs.rmSync(tempRoot, { recursive: true, force: true })
+    }
+  })
 })

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

@@ -17,7 +17,11 @@ const loadRunAgenticInit = async ({
 }: {
   existingPaths: Set<string>
   questionAnswer?: string
-  runAgenticSetupImplementation?: (targetDir: string, ask: (question: string) => Promise<string>, options?: { tool?: string; force?: boolean }) => Promise<void>
+  runAgenticSetupImplementation?: (
+    targetDir: string,
+    ask: (question: string) => Promise<string>,
+    options?: { tool?: string; force?: boolean; updateHarness?: boolean },
+  ) => Promise<void>
 }): Promise<AgenticInitTestContext> => {
   jest.resetModules()
 
@@ -136,6 +140,22 @@ describe('runAgenticInit', () => {
     expect(testContext.runAgenticSetup).not.toHaveBeenCalled()
   })
 
+  it('rejects force and ownership-aware update together before setup', async () => {
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+    const testContext = await loadRunAgenticInit({
+      existingPaths: new Set<string>([appModulesPath]),
+    })
+
+    const exitCode = await testContext.runAgenticInit(['--force', '--update-harness'])
+
+    expect(exitCode).toBe(1)
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      '❌  --force and --update-harness are mutually exclusive',
+    )
+    expect(testContext.createInterface).not.toHaveBeenCalled()
+    expect(testContext.runAgenticSetup).not.toHaveBeenCalled()
+  })
+
   it('warns and exits early when relevant agentic files already exist without force', async () => {
     const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
     const testContext = await loadRunAgenticInit({
@@ -150,7 +170,7 @@ describe('runAgenticInit', () => {
     expect(consoleLogSpy.mock.calls.flat()).toEqual(expect.arrayContaining([
       '⚠️  Agentic files already exist:',
       '   • .codex/mcp.json.example',
-      'Run with --force to regenerate from current templates.',
+      'Run with --update-harness to preserve local edits, or --force to replace generated files.',
     ]))
   })
 
@@ -160,7 +180,7 @@ describe('runAgenticInit', () => {
       questionAnswer: '  cursor  ',
       runAgenticSetupImplementation: async (currentTargetDir, ask, options) => {
         expect(currentTargetDir).toBe(targetDir)
-        expect(options).toEqual({ tool: undefined, force: undefined })
+        expect(options).toEqual({ tool: undefined, force: undefined, updateHarness: undefined })
         await expect(ask('Select a tool')).resolves.toBe('cursor')
       },
     })
@@ -188,7 +208,7 @@ describe('runAgenticInit', () => {
     expect(testContext.runAgenticSetup).toHaveBeenCalledWith(
       targetDir,
       expect.any(Function),
-      { tool: 'codex', force: undefined },
+      { tool: 'codex', force: undefined, updateHarness: undefined },
     )
     expect(consoleLogSpy.mock.calls.flat()).not.toContain('⚠️  Agentic files already exist:')
     expect(testContext.closeInterface).toHaveBeenCalledTimes(1)
@@ -205,7 +225,23 @@ describe('runAgenticInit', () => {
     expect(testContext.runAgenticSetup).toHaveBeenCalledWith(
       targetDir,
       expect.any(Function),
-      { tool: 'codex', force: true },
+      { tool: 'codex', force: true, updateHarness: undefined },
+    )
+    expect(testContext.closeInterface).toHaveBeenCalledTimes(1)
+  })
+
+  it('bypasses overwrite warnings and requests an ownership-aware update', async () => {
+    const testContext = await loadRunAgenticInit({
+      existingPaths: new Set<string>([appModulesPath, codexConfigPath]),
+    })
+
+    const exitCode = await testContext.runAgenticInit(['--tool=codex', '--update-harness'])
+
+    expect(exitCode).toBe(0)
+    expect(testContext.runAgenticSetup).toHaveBeenCalledWith(
+      targetDir,
+      expect.any(Function),
+      { tool: 'codex', force: undefined, updateHarness: true },
     )
     expect(testContext.closeInterface).toHaveBeenCalledTimes(1)
   })