@open-mercato/cli 0.6.7-develop.6828.1.ab1620a63e → 0.6.7-develop.6834.1.e76f4b8cbc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.7-develop.6828.1.ab1620a63e",
+  "version": "0.6.7-develop.6834.1.e76f4b8cbc",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,8 +60,9 @@
     "@mikro-orm/decorators": "^7.1.8",
     "@mikro-orm/migrations": "^7.1.8",
     "@mikro-orm/postgresql": "^7.1.8",
-    "@open-mercato/queue": "0.6.7-develop.6828.1.ab1620a63e",
-    "@open-mercato/shared": "0.6.7-develop.6828.1.ab1620a63e",
+    "@open-mercato/queue": "0.6.7-develop.6834.1.e76f4b8cbc",
+    "@open-mercato/shared": "0.6.7-develop.6834.1.e76f4b8cbc",
+    "@open-mercato/telemetry": "0.6.7-develop.6834.1.e76f4b8cbc",
     "cross-spawn": "^7.0.6",
     "pg": "8.22.0",
     "semver": "^7.8.5",
@@ -72,10 +73,10 @@
     "typescript-js": "npm:typescript@6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.7-develop.6828.1.ab1620a63e"
+    "@open-mercato/shared": "0.6.7-develop.6834.1.e76f4b8cbc"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.7-develop.6828.1.ab1620a63e",
+    "@open-mercato/shared": "0.6.7-develop.6834.1.e76f4b8cbc",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.12"

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/__tests__/load-env.test.ts

@@ -0,0 +1,65 @@
+import path from 'node:path'
+import fs from 'node:fs'
+import os from 'node:os'
+import { loadAppEnv } from '../load-env'
+
+/**
+ * Regression: bin.ts must load the app's `.env` before initTelemetry(), so
+ * TELEMETRY_BACKEND set only in `.env` reaches worker and scheduler processes
+ * (ensureEnvLoaded in run() happens after init — too late).
+ */
+
+describe('loadAppEnv', () => {
+  const TEST_KEY = 'OM_LOAD_ENV_TEST_BACKEND'
+  let tmpDir: string
+  let cwd: string
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'load-env-'))
+    cwd = process.cwd()
+    process.chdir(tmpDir)
+    delete process.env[TEST_KEY]
+  })
+
+  afterEach(() => {
+    process.chdir(cwd)
+    delete process.env[TEST_KEY]
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('loads .env from the app directory into process.env', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"env-test-app"}\n')
+    fs.mkdirSync(path.join(tmpDir, 'src'))
+    fs.writeFileSync(path.join(tmpDir, 'src', 'modules.ts'), 'export const enabledModules = []\n')
+    fs.writeFileSync(path.join(tmpDir, '.env'), `${TEST_KEY}=console\n`)
+
+    await loadAppEnv()
+
+    expect(process.env[TEST_KEY]).toBe('console')
+  })
+
+  it('does not override values already set in the real process env', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"env-test-app"}\n')
+    fs.writeFileSync(path.join(tmpDir, '.env'), `${TEST_KEY}=from-dotenv\n`)
+    process.env[TEST_KEY] = 'from-shell'
+
+    await loadAppEnv()
+
+    expect(process.env[TEST_KEY]).toBe('from-shell')
+  })
+
+  it('is a safe no-op when no .env exists', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"env-test-app"}\n')
+    await expect(loadAppEnv()).resolves.toBeUndefined()
+    expect(process.env[TEST_KEY]).toBeUndefined()
+  })
+
+  it('bin.ts awaits loadAppEnv() before initTelemetry() (the guarded ordering)', () => {
+    const binSource = fs.readFileSync(path.resolve(__dirname, '../../bin.ts'), 'utf8')
+    const loadEnvCall = binSource.indexOf('await loadAppEnv()')
+    const initTelemetryCall = binSource.indexOf('await initTelemetry()')
+    expect(loadEnvCall).toBeGreaterThan(-1)
+    expect(initTelemetryCall).toBeGreaterThan(-1)
+    expect(loadEnvCall).toBeLessThan(initTelemetryCall)
+  })
+})

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

@@ -0,0 +1,298 @@
+import path from 'node:path'
+import fs from 'node:fs'
+import os from 'node:os'
+import * as ts from 'typescript'
+import { runTelemetryInit } from '../telemetry-init'
+
+const TEMPLATE_DIR = path.join(__dirname, '../../../../../packages/create-app/template')
+const TEMPLATE_DISPATCHER = path.join(TEMPLATE_DIR, 'src/app/api/[...slug]/route.ts')
+const TEMPLATE_NEXT_CONFIG = path.join(TEMPLATE_DIR, 'next.config.ts')
+const TEMPLATE_INSTRUMENTATION = path.join(TEMPLATE_DIR, 'src/instrumentation.ts')
+
+// The telemetry statements the shipped scaffold wires into the dispatcher — the
+// oracle for "did the command reproduce the real wiring?". Read from the live
+// template so this test fails loudly if the scaffold's wiring changes and the
+// command doesn't keep up.
+const TELEMETRY_DISPATCHER_LINES = [
+  "import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'",
+  'getTelemetryRuntime()?.recordHttpDuration(method, match.route.path, finalResponse.status, startedAt)',
+  'getTelemetryRuntime()?.recordHttpDuration(method, match.route.path, 500, startedAt)',
+  'getTelemetryRuntime()?.reportError(error, {',
+]
+
+/** Assert a string is syntactically valid TypeScript (parse errors, not types). */
+function assertParses(code: string, label: string): void {
+  const sf = ts.createSourceFile(`${label}.ts`, code, ts.ScriptTarget.Latest, true)
+  const diagnostics = (sf as unknown as { parseDiagnostics?: ts.Diagnostic[] }).parseDiagnostics ?? []
+  const messages = diagnostics.map((d) => ts.flattenDiagnosticMessageText(d.messageText, '\n'))
+  expect({ label, messages }).toEqual({ label, messages: [] })
+}
+
+/** Turn the live wired template dispatcher back into a pre-telemetry one. */
+function stripTelemetry(src: string): string {
+  return src
+    .replace(/\n[ \t]*getTelemetryRuntime\(\)\?\.reportError\(error, \{[\s\S]*?\n[ \t]*\}\)/, '')
+    .split('\n')
+    .filter(
+      (line) =>
+        !line.includes("from '@open-mercato/telemetry'") &&
+        !line.includes("from '@open-mercato/telemetry/nextjs'") &&
+        !line.includes("from '@open-mercato/shared/lib/telemetry/runtime'") &&
+        !line.includes('recordHttpDuration('),
+    )
+    .join('\n')
+}
+
+const NEXT_CONFIG = `import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  serverExternalPackages: [
+    'esbuild',
+  ],
+}
+
+export default nextConfig
+`
+
+function baseFixture(dir: string): void {
+  fs.mkdirSync(path.join(dir, 'src', 'app', 'api', '[...slug]'), { recursive: true })
+  fs.writeFileSync(path.join(dir, 'src', 'modules.ts'), 'export const enabledModules = []\n')
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({ name: 'my-app', dependencies: { '@open-mercato/shared': '1.2.3' } }, null, 2) + '\n',
+  )
+  fs.writeFileSync(path.join(dir, '.env.example'), 'DATABASE_URL=postgres://localhost/app\n')
+  fs.writeFileSync(path.join(dir, 'next.config.ts'), NEXT_CONFIG)
+}
+
+const SIMPLE_DISPATCHER = `import { NextResponse, type NextRequest } from 'next/server'
+import { findApiRouteManifestMatch } from '@open-mercato/shared/modules/registry'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+
+async function handleRequest(method: string, req: NextRequest): Promise<Response> {
+  const startedAt = Date.now()
+  const match = { route: { path: '/api/thing' } }
+  try {
+    const finalResponse = NextResponse.json({ ok: true })
+    return finalResponse
+  } catch (error) {
+    throw error
+  }
+}
+`
+
+describe('mercato telemetry init', () => {
+  let tmpDir: string
+  let cwd: string
+  let logSpy: jest.SpyInstance
+  let errorSpy: jest.SpyInstance
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'telemetry-init-'))
+    cwd = process.cwd()
+    process.chdir(tmpDir)
+    logSpy = jest.spyOn(console, 'log').mockImplementation(() => {})
+    errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    process.chdir(cwd)
+    logSpy.mockRestore()
+    errorSpy.mockRestore()
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  const read = (rel: string) => fs.readFileSync(path.join(tmpDir, rel), 'utf8')
+  const dispatcherPath = 'src/app/api/[...slug]/route.ts'
+
+  it('rejects a directory that is not an Open Mercato app', async () => {
+    const code = await runTelemetryInit([])
+    expect(code).toBe(1)
+    expect(errorSpy).toHaveBeenCalled()
+  })
+
+  it('wires all files in a pre-telemetry app', async () => {
+    baseFixture(tmpDir)
+    fs.writeFileSync(path.join(tmpDir, dispatcherPath), SIMPLE_DISPATCHER)
+    const code = await runTelemetryInit([])
+    expect(code).toBe(0)
+
+    const pkg = JSON.parse(read('package.json'))
+    expect(pkg.dependencies['@open-mercato/telemetry']).toBe('1.2.3')
+    expect(pkg.optionalDependencies['bullmq-otel']).toBe('^1.3.1')
+
+    expect(read('.env.example')).toContain('TELEMETRY_BACKEND')
+    expect(read('.env.example')).toContain('OTEL_EXPORTER_OTLP_ENDPOINT')
+    expect(read('src/instrumentation.ts')).toContain('registerTelemetryForNextjs')
+
+    const nextConfig = read('next.config.ts')
+    expect(nextConfig).toContain('@open-mercato/telemetry/nextjs-config')
+    expect(nextConfig).toContain('...telemetryServerExternalPackages')
+
+    const route = read(dispatcherPath)
+    for (const line of TELEMETRY_DISPATCHER_LINES) expect(route).toContain(line)
+  })
+
+  it('every patched file is syntactically valid TypeScript', async () => {
+    baseFixture(tmpDir)
+    fs.writeFileSync(path.join(tmpDir, dispatcherPath), SIMPLE_DISPATCHER)
+    await runTelemetryInit([])
+    assertParses(read('next.config.ts'), 'next.config')
+    assertParses(read('src/instrumentation.ts'), 'instrumentation')
+    assertParses(read(dispatcherPath), 'dispatcher')
+    JSON.parse(read('package.json')) // valid JSON
+  })
+
+  it('reproduces the live template dispatcher wiring (round-trip)', async () => {
+    baseFixture(tmpDir)
+    const wired = fs.readFileSync(TEMPLATE_DISPATCHER, 'utf8')
+    const preTelemetry = stripTelemetry(wired)
+    // sanity: the derived pre-telemetry file no longer imports telemetry but still parses
+    expect(preTelemetry).not.toContain('@open-mercato/telemetry')
+    assertParses(preTelemetry, 'stripped-template')
+    fs.writeFileSync(path.join(tmpDir, dispatcherPath), preTelemetry)
+
+    await runTelemetryInit([])
+
+    const patched = read(dispatcherPath)
+    assertParses(patched, 'patched-template')
+    for (const line of TELEMETRY_DISPATCHER_LINES) expect(patched).toContain(line)
+    // the success metric lands before the response return, the 500 funnel in the catch
+    expect(patched.indexOf('finalResponse.status, startedAt')).toBeLessThan(patched.indexOf('return finalResponse'))
+    expect(patched.indexOf('reportError(error, {')).toBeLessThan(patched.indexOf(', 500, startedAt'))
+  })
+
+  it('is a no-op on the real (already-wired) template files', async () => {
+    baseFixture(tmpDir)
+    fs.copyFileSync(TEMPLATE_DISPATCHER, path.join(tmpDir, dispatcherPath))
+    fs.copyFileSync(TEMPLATE_NEXT_CONFIG, path.join(tmpDir, 'next.config.ts'))
+    fs.copyFileSync(TEMPLATE_INSTRUMENTATION, path.join(tmpDir, 'src', 'instrumentation.ts'))
+    const before = {
+      route: read(dispatcherPath),
+      nextConfig: read('next.config.ts'),
+      instrumentation: read('src/instrumentation.ts'),
+    }
+    await runTelemetryInit([])
+    expect(read(dispatcherPath)).toBe(before.route)
+    expect(read('next.config.ts')).toBe(before.nextConfig)
+    expect(read('src/instrumentation.ts')).toBe(before.instrumentation)
+  })
+
+  it('patches a recognizable-but-modified dispatcher (extra imports/code, anchors intact)', async () => {
+    baseFixture(tmpDir)
+    const modified = SIMPLE_DISPATCHER.replace(
+      "import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'",
+      "import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'\nimport { auditLog } from '@/lib/audit'",
+    ).replace('const match = { route: { path: \'/api/thing\' } }', 'const match = { route: { path: \'/api/thing\' } }\n  auditLog(method)')
+    fs.writeFileSync(path.join(tmpDir, dispatcherPath), modified)
+
+    await runTelemetryInit([])
+    const patched = read(dispatcherPath)
+    assertParses(patched, 'modified-dispatcher')
+    for (const line of TELEMETRY_DISPATCHER_LINES) expect(patched).toContain(line)
+    expect(patched).toContain("import { auditLog } from '@/lib/audit'") // preserved custom code
+  })
+
+  it('leaves an unrecognizable dispatcher untouched and prints the manual snippet', async () => {
+    baseFixture(tmpDir)
+    fs.writeFileSync(path.join(tmpDir, dispatcherPath), `export async function GET() { return new Response('custom') }\n`)
+    await runTelemetryInit([])
+    const route = read(dispatcherPath)
+    expect(route).not.toContain('@open-mercato/telemetry')
+    expect(route).toBe(`export async function GET() { return new Response('custom') }\n`)
+    const printed = logSpy.mock.calls.flat().join('\n')
+    expect(printed).toContain('manual step for src/app/api/[...slug]/route.ts')
+  })
+
+  it('handles next.config variations (single-line array, no trailing comma) and stays valid', async () => {
+    baseFixture(tmpDir)
+    fs.writeFileSync(path.join(tmpDir, dispatcherPath), SIMPLE_DISPATCHER)
+    fs.writeFileSync(
+      path.join(tmpDir, 'next.config.ts'),
+      `import type { NextConfig } from 'next'\nconst nextConfig: NextConfig = { serverExternalPackages: ['esbuild'] }\nexport default nextConfig\n`,
+    )
+    await runTelemetryInit([])
+    const nextConfig = read('next.config.ts')
+    assertParses(nextConfig, 'single-line-next-config')
+    expect(nextConfig).toContain('...telemetryServerExternalPackages')
+    expect(nextConfig).toContain('@open-mercato/telemetry/nextjs-config')
+  })
+
+  it('migrates the legacy nextjs import before adding the missing spread', async () => {
+    baseFixture(tmpDir)
+    fs.writeFileSync(path.join(tmpDir, dispatcherPath), SIMPLE_DISPATCHER)
+    fs.writeFileSync(
+      path.join(tmpDir, 'next.config.ts'),
+      `import type { NextConfig } from 'next'\nimport { telemetryServerExternalPackages } from '@open-mercato/telemetry/nextjs'\nconst nextConfig: NextConfig = { serverExternalPackages: ['esbuild', 'bullmq'] }\nexport default nextConfig\n`,
+    )
+
+    await runTelemetryInit([])
+
+    const nextConfig = read('next.config.ts')
+    assertParses(nextConfig, 'legacy-next-config')
+    expect(nextConfig).toContain("from '@open-mercato/telemetry/nextjs-config'")
+    expect(nextConfig).not.toContain("from '@open-mercato/telemetry/nextjs'")
+    expect(nextConfig).toContain("['esbuild', 'bullmq', ...telemetryServerExternalPackages]")
+  })
+
+  it('flags next.config as manual when serverExternalPackages is absent', async () => {
+    baseFixture(tmpDir)
+    fs.writeFileSync(path.join(tmpDir, dispatcherPath), SIMPLE_DISPATCHER)
+    fs.writeFileSync(
+      path.join(tmpDir, 'next.config.ts'),
+      `import type { NextConfig } from 'next'\nconst nextConfig: NextConfig = { distDir: '.next' }\nexport default nextConfig\n`,
+    )
+    await runTelemetryInit([])
+    expect(read('next.config.ts')).not.toContain('telemetryServerExternalPackages')
+    const printed = logSpy.mock.calls.flat().join('\n')
+    expect(printed).toContain('manual step for next.config.ts')
+  })
+
+  it('inserts into a pre-existing custom instrumentation.ts and preserves its body', async () => {
+    baseFixture(tmpDir)
+    fs.writeFileSync(path.join(tmpDir, dispatcherPath), SIMPLE_DISPATCHER)
+    fs.writeFileSync(
+      path.join(tmpDir, 'src', 'instrumentation.ts'),
+      `export async function register(): Promise<void> {\n  console.log('custom warmup')\n}\n`,
+    )
+    await runTelemetryInit([])
+    const instrumentation = read('src/instrumentation.ts')
+    assertParses(instrumentation, 'custom-instrumentation')
+    expect(instrumentation).toContain('registerTelemetryForNextjs')
+    expect(instrumentation).toContain("console.log('custom warmup')") // preserved
+  })
+
+  it('is idempotent — a second run changes nothing and does not double-insert', async () => {
+    baseFixture(tmpDir)
+    fs.writeFileSync(path.join(tmpDir, dispatcherPath), SIMPLE_DISPATCHER)
+    await runTelemetryInit([])
+    const after1 = {
+      pkg: read('package.json'),
+      env: read('.env.example'),
+      instrumentation: read('src/instrumentation.ts'),
+      nextConfig: read('next.config.ts'),
+      route: read(dispatcherPath),
+    }
+
+    await runTelemetryInit([])
+    expect(read('package.json')).toBe(after1.pkg)
+    expect(read('.env.example')).toBe(after1.env)
+    expect(read('src/instrumentation.ts')).toBe(after1.instrumentation)
+    expect(read('next.config.ts')).toBe(after1.nextConfig)
+    expect(read(dispatcherPath)).toBe(after1.route)
+
+    const route = read(dispatcherPath)
+    expect((read('next.config.ts').match(/@open-mercato\/telemetry\/nextjs-config/g) ?? []).length).toBe(1)
+    expect((route.match(/from '@open-mercato\/shared\/lib\/telemetry\/runtime'/g) ?? []).length).toBe(1)
+  })
+
+  it('dry run writes nothing', async () => {
+    baseFixture(tmpDir)
+    fs.writeFileSync(path.join(tmpDir, dispatcherPath), SIMPLE_DISPATCHER)
+    const before = read('next.config.ts')
+    await runTelemetryInit(['--dry-run'])
+    expect(read('next.config.ts')).toBe(before)
+    expect(fs.existsSync(path.join(tmpDir, 'src', 'instrumentation.ts'))).toBe(false)
+    expect(JSON.parse(read('package.json')).dependencies['@open-mercato/telemetry']).toBeUndefined()
+  })
+})

package/src/lib/load-env.ts

@@ -0,0 +1,30 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Bootstrap-free `.env` loader for the CLI binary. `bin.ts` must load the app's
+ * `.env` BEFORE `initTelemetry()` so `TELEMETRY_*` set only in `.env` resolves a
+ * real backend for worker/scheduler processes — `run()`'s `ensureEnvLoaded()`
+ * happens after telemetry init, which is too late. Deliberately read-only (no
+ * `.env.example` copy — that UX stays in `ensureEnvLoaded`) and pulls in only the
+ * resolver + dotenv, so nothing here loads `pg` and the OTEL instrumentation
+ * load-order guarantee is preserved.
+ */
+export async function loadAppEnv(options: { cwd?: string } = {}): Promise<void> {
+  try {
+    const { createResolver } = await import('./resolver.js')
+    const appDir = createResolver(options.cwd).getAppDir()
+    const envPath = path.join(appDir, '.env')
+    if (fs.existsSync(envPath)) {
+      const dotenv = await import('dotenv')
+      dotenv.config({ path: envPath, quiet: true })
+      return
+    }
+  } catch {
+    // Resolver can fail outside an app dir — fall through to plain cwd loading.
+  }
+  try {
+    const dotenv = await import('dotenv')
+    dotenv.config({ quiet: true })
+  } catch {}
+}