@open-mercato/cli 0.8.1-develop.7275.1.f772b944d4 → 0.8.1-develop.7295.1.d0e0e33014

package/package.json

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

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

@@ -8,6 +8,10 @@ const TEMPLATE_DIR = path.join(__dirname, '../../../../../packages/create-app/te
 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')
+const TEMPLATE_LAYOUT = path.join(TEMPLATE_DIR, 'src/app/(backend)/backend/layout.tsx')
+const TEMPLATE_MODULES = path.join(TEMPLATE_DIR, 'src/modules.ts')
+
+const LAYOUT_FILE = 'src/app/(backend)/backend/layout.tsx'
 
 // The telemetry statements the shipped scaffold wires into the dispatcher — the
 // oracle for "did the command reproduce the real wiring?". Read from the live
@@ -21,8 +25,8 @@ const TELEMETRY_DISPATCHER_LINES = [
 ]
 
 /** 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)
+function assertParses(code: string, label: string, extension: '.ts' | '.tsx' = '.ts'): void {
+  const sf = ts.createSourceFile(`${label}${extension}`, 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: [] })
@@ -43,6 +47,20 @@ function stripTelemetry(src: string): string {
     .join('\n')
 }
 
+/** Turn the live wired template layout back into one from before browser RUM shipped. */
+function stripBrowserTelemetry(src: string): string {
+  return src
+    .replace(/\n[ \t]*\/\/ Resolved per request[\s\S]*?const browserTelemetryConfig = resolveBrowserTelemetryConfig\(.*\)\n/, '\n')
+    .split('\n')
+    .filter(
+      (line) =>
+        !line.includes("from '@open-mercato/telemetry/browser'") &&
+        !line.includes("from '@open-mercato/telemetry/browser/server'") &&
+        !line.includes('<BrowserTelemetry'),
+    )
+    .join('\n')
+}
+
 const NEXT_CONFIG = `import type { NextConfig } from 'next'
 
 const nextConfig: NextConfig = {
@@ -272,6 +290,7 @@ describe('mercato telemetry init', () => {
       instrumentation: read('src/instrumentation.ts'),
       nextConfig: read('next.config.ts'),
       route: read(dispatcherPath),
+      modules: read('src/modules.ts'),
     }
 
     await runTelemetryInit([])
@@ -280,18 +299,169 @@ describe('mercato telemetry init', () => {
     expect(read('src/instrumentation.ts')).toBe(after1.instrumentation)
     expect(read('next.config.ts')).toBe(after1.nextConfig)
     expect(read(dispatcherPath)).toBe(after1.route)
+    expect(read('src/modules.ts')).toBe(after1.modules)
 
     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)
   })
 
+  /**
+   * The adoption path the first RUM release has to serve: an app that already ran
+   * `mercato telemetry init` before browser RUM existed. Everything server-side is
+   * wired; none of the RUM wiring is.
+   */
+  describe('an app already initialized before browser RUM shipped', () => {
+    function legacyFixture(): void {
+      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'))
+      // The core env block as the pre-RUM command wrote it: no TELEMETRY_BROWSER_* keys.
+      fs.writeFileSync(
+        path.join(tmpDir, '.env.example'),
+        'DATABASE_URL=postgres://localhost/app\n\n# TELEMETRY_BACKEND=otlp\n# OTEL_SERVICE_NAME=open-mercato\n',
+      )
+      fs.mkdirSync(path.join(tmpDir, 'src', 'app', '(backend)', 'backend'), { recursive: true })
+      fs.writeFileSync(
+        path.join(tmpDir, LAYOUT_FILE),
+        stripBrowserTelemetry(fs.readFileSync(TEMPLATE_LAYOUT, 'utf8')),
+      )
+      fs.writeFileSync(
+        path.join(tmpDir, 'src', 'modules.ts'),
+        `import type { ModuleOverrides } from '@open-mercato/shared/modules/overrides'\n\nexport type ModuleEntry = { id: string; from?: string; overrides?: ModuleOverrides }\n\nexport const enabledModules: ModuleEntry[] = [\n  { id: 'auth', from: '@open-mercato/core' },\n]\n`,
+      )
+    }
+
+    it('appends the missing browser env keys instead of skipping the whole block', async () => {
+      legacyFixture()
+
+      await runTelemetryInit([])
+
+      const env = read('.env.example')
+      expect(env).toContain('TELEMETRY_BROWSER_ENABLED')
+      expect(env).toContain('TELEMETRY_BROWSER_SAMPLING_RATIO')
+      // The core block the app already had must not be duplicated.
+      expect((env.match(/^#?\s*TELEMETRY_BACKEND=/gm) ?? []).length).toBe(1)
+    })
+
+    it('registers the telemetry module, without which the browser exports into a 404', async () => {
+      legacyFixture()
+
+      await runTelemetryInit([])
+
+      const modules = read('src/modules.ts')
+      assertParses(modules, 'legacy-modules')
+      expect(modules).toContain("{ id: 'telemetry', from: '@open-mercato/telemetry' },")
+      expect(modules).toContain("{ id: 'auth', from: '@open-mercato/core' },") // preserved
+    })
+
+    it('renders the client bootstrap in the backoffice shell', async () => {
+      legacyFixture()
+
+      await runTelemetryInit([])
+
+      const layout = read(LAYOUT_FILE)
+      assertParses(layout, 'legacy-layout', '.tsx')
+      expect(layout).toContain("import { BrowserTelemetry } from '@open-mercato/telemetry/browser'")
+      // The credential-reading half stays on the server entry.
+      expect(layout).toContain("import { resolveBrowserTelemetryConfig } from '@open-mercato/telemetry/browser/server'")
+      // The scaffold layout already awaits cookies(), so the patcher reuses that binding — the
+      // header is read only by the integration-test opt-in, never in production.
+      expect(layout).toContain(
+        'const browserTelemetryConfig = resolveBrowserTelemetryConfig({ cookieHeader: cookieStore.toString() })',
+      )
+      expect(layout).toContain('<BrowserTelemetry config={browserTelemetryConfig} />')
+      // Resolved before it is used, and rendered inside the shell.
+      expect(layout.indexOf('const browserTelemetryConfig')).toBeLessThan(layout.indexOf('<BrowserTelemetry'))
+      expect(layout.indexOf('<BrowserTelemetry')).toBeLessThan(layout.indexOf('</AppShell>'))
+    })
+
+    it('reproduces the live template layout wiring (round-trip)', async () => {
+      legacyFixture()
+      const wired = fs.readFileSync(TEMPLATE_LAYOUT, 'utf8')
+
+      await runTelemetryInit([])
+
+      const patched = read(LAYOUT_FILE)
+      for (const line of [
+        "import { BrowserTelemetry } from '@open-mercato/telemetry/browser'",
+        "import { resolveBrowserTelemetryConfig } from '@open-mercato/telemetry/browser/server'",
+        'const browserTelemetryConfig = resolveBrowserTelemetryConfig({ cookieHeader: cookieStore.toString() })',
+        '<BrowserTelemetry config={browserTelemetryConfig} />',
+      ]) {
+        expect(wired).toContain(line)
+        expect(patched).toContain(line)
+      }
+    })
+
+    it('falls back to the argument-free call when the layout no longer awaits cookies()', async () => {
+      legacyFixture()
+      const layoutPath = path.join(tmpDir, LAYOUT_FILE)
+      // An app that customized the layout away from the scaffold's `cookies()` binding must still
+      // get something that compiles; the cookie is only ever read by the integration-test opt-in.
+      fs.writeFileSync(
+        layoutPath,
+        fs.readFileSync(layoutPath, 'utf8').replace(/const\s+cookieStore\s*=\s*await\s+cookies\(\)/, 'const cookieStore = null'),
+      )
+
+      await runTelemetryInit([])
+
+      const layout = read(LAYOUT_FILE)
+      assertParses(layout, 'no-cookies-layout', '.tsx')
+      expect(layout).toContain('const browserTelemetryConfig = resolveBrowserTelemetryConfig()')
+      expect(layout).toContain('<BrowserTelemetry config={browserTelemetryConfig} />')
+    })
+
+    it('is idempotent across the RUM steps too', async () => {
+      legacyFixture()
+      await runTelemetryInit([])
+      const afterFirst = { env: read('.env.example'), modules: read('src/modules.ts'), layout: read(LAYOUT_FILE) }
+
+      await runTelemetryInit([])
+
+      expect(read('.env.example')).toBe(afterFirst.env)
+      expect(read('src/modules.ts')).toBe(afterFirst.modules)
+      expect(read(LAYOUT_FILE)).toBe(afterFirst.layout)
+    })
+  })
+
+  it('is a no-op on the already-wired template layout and modules', async () => {
+    baseFixture(tmpDir)
+    fs.writeFileSync(path.join(tmpDir, dispatcherPath), SIMPLE_DISPATCHER)
+    fs.mkdirSync(path.join(tmpDir, 'src', 'app', '(backend)', 'backend'), { recursive: true })
+    fs.copyFileSync(TEMPLATE_LAYOUT, path.join(tmpDir, LAYOUT_FILE))
+    fs.copyFileSync(TEMPLATE_MODULES, path.join(tmpDir, 'src', 'modules.ts'))
+    const before = { layout: read(LAYOUT_FILE), modules: read('src/modules.ts') }
+
+    await runTelemetryInit([])
+
+    expect(read(LAYOUT_FILE)).toBe(before.layout)
+    expect(read('src/modules.ts')).toBe(before.modules)
+  })
+
+  it('leaves an unrecognizable backend layout untouched and prints the manual snippet', async () => {
+    baseFixture(tmpDir)
+    fs.writeFileSync(path.join(tmpDir, dispatcherPath), SIMPLE_DISPATCHER)
+    fs.mkdirSync(path.join(tmpDir, 'src', 'app', '(backend)', 'backend'), { recursive: true })
+    const custom = `export default function Layout() { return null }\n`
+    fs.writeFileSync(path.join(tmpDir, LAYOUT_FILE), custom)
+
+    await runTelemetryInit([])
+
+    expect(read(LAYOUT_FILE)).toBe(custom)
+    const printed = logSpy.mock.calls.flat().join('\n')
+    expect(printed).toContain(`manual step for ${LAYOUT_FILE}`)
+    expect(printed).toContain('<BrowserTelemetry config={browserTelemetryConfig} />')
+  })
+
   it('dry run writes nothing', async () => {
     baseFixture(tmpDir)
     fs.writeFileSync(path.join(tmpDir, dispatcherPath), SIMPLE_DISPATCHER)
-    const before = read('next.config.ts')
+    const before = { nextConfig: read('next.config.ts'), modules: read('src/modules.ts') }
     await runTelemetryInit(['--dry-run'])
-    expect(read('next.config.ts')).toBe(before)
+    expect(read('next.config.ts')).toBe(before.nextConfig)
+    expect(read('src/modules.ts')).toBe(before.modules)
     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/telemetry-init.ts

@@ -9,10 +9,15 @@ import { dirname, join, resolve } from 'node:path'
  * The web-tier wiring lives in app-owned source files (a dependency bump cannot
  * touch them), so this patches them in place using the same idioms the rest of
  * the CLI uses: JSON edits, detect-before-append for `.env`, a ts-morph edit for
- * `next.config.ts`, and anchored insertion for `instrumentation.ts` + the API
- * dispatcher. When a file's shape is not recognized (a customized dispatcher, an
- * unusual next.config), the step degrades to printing the exact snippet and
- * flags it as a manual step rather than editing code it does not understand.
+ * `next.config.ts`, and anchored insertion for `instrumentation.ts`, the API
+ * dispatcher, `src/modules.ts`, and the backoffice layout. When a file's shape is
+ * not recognized (a customized dispatcher, an unusual next.config, a rewritten
+ * layout), the step degrades to printing the exact snippet and flags it as a
+ * manual step rather than editing code it does not understand.
+ *
+ * "Already wired" is decided per capability, not per file: an app initialized
+ * before browser RUM shipped has the core telemetry block and none of the RUM
+ * wiring, and re-running the command is how it adopts the difference.
  *
  * Worker/scheduler telemetry is not handled here — it ships transitively via
  * `@open-mercato/cli`'s telemetry dependency once the app updates its packages.
@@ -34,7 +39,7 @@ type TelemetryInitOptions = {
   dryRun: boolean
 }
 
-const ENV_BLOCK = `
+const ENV_CORE_BLOCK = `
 # --- Telemetry & Observability (vendor-neutral OTLP: traces, logs, metrics, errors) ---
 # Off by default: leave TELEMETRY_BACKEND unset (or =noop) for a hard no-op
 # (the OpenTelemetry SDK is never loaded). Set to 'console' for local span/metric
@@ -66,6 +71,31 @@ const ENV_BLOCK = `
 # OTEL_RESOURCE_ATTRIBUTES=deployment.environment=local
 `
 
+/**
+ * Appended on its own when an app already carries the core block — an app
+ * initialized before browser RUM shipped must be able to adopt it by re-running
+ * the command.
+ */
+const ENV_BROWSER_BLOCK = `
+# --- Browser RUM (client-side telemetry) ---
+# Document-load and fetch spans exported from the backoffice through a
+# same-origin proxy (/api/telemetry/browser-traces) that adds the collector
+# credential server-side. Off by default; requires an active
+# TELEMETRY_BACKEND + OTLP endpoint above.
+# Read at request time (not NEXT_PUBLIC_*), so toggling needs no rebuild.
+# Browser spans join their server spans only when TELEMETRY_TRUST_INBOUND_TRACE=true
+# above; without it RUM still works, but each page yields two separate traces.
+# Ingest budget: each open tab exports at most 20 batches/min (a 3s batch delay),
+# and the proxy allows 400/min per authenticated user — roughly 20 concurrent tabs.
+# Over that, batches are dropped with 204 rather than a retryable status, so the
+# only symptom is missing spans for that one user, never a client retry storm.
+# TELEMETRY_BROWSER_ENABLED=false
+# TELEMETRY_BROWSER_SAMPLING_RATIO=1.0  # 0.0-1.0 (default 1.0)
+# TELEMETRY_BROWSER_SERVICE_NAME=       # default: <OTEL_SERVICE_NAME>-browser
+`
+
+const ENV_BLOCK = `${ENV_CORE_BLOCK}${ENV_BROWSER_BLOCK}`
+
 const INSTRUMENTATION_TS = `import { isTelemetryBackendEnabled } from '@open-mercato/shared/lib/telemetry/runtime'
 
 export async function register(): Promise<void> {
@@ -155,12 +185,138 @@ function patchEnvFile(appDir: string, relativePath: string, options: TelemetryIn
   const path = join(appDir, relativePath)
   if (!existsSync(path)) return null
   const content = readFileSync(path, 'utf8')
-  if (content.includes('TELEMETRY_BACKEND')) {
+  // Checked key by key, not block by block: an app initialized before browser RUM
+  // shipped has the core keys and none of the browser ones, and re-running the
+  // command is how it adopts them.
+  const hasCore = content.includes('TELEMETRY_BACKEND')
+  const hasBrowser = content.includes('TELEMETRY_BROWSER_ENABLED')
+  if (hasCore && hasBrowser) {
     return { file: relativePath, status: 'skipped', detail: 'TELEMETRY_* block already present' }
   }
-  const next = `${content.replace(/\s*$/, '')}\n${ENV_BLOCK}`
+  const next = `${content.replace(/\s*$/, '')}\n${hasCore ? ENV_BROWSER_BLOCK : ENV_BLOCK}`
+  if (!options.dryRun) writeFileSync(path, next)
+  return {
+    file: relativePath,
+    status: 'patched',
+    detail: hasCore
+      ? 'appended the missing TELEMETRY_BROWSER_* block'
+      : 'appended commented TELEMETRY_* / OTEL_* block',
+  }
+}
+
+const MODULES_SNIPPET = `  // in the enabledModules array:
+  { id: 'telemetry', from: '@open-mercato/telemetry' },`
+
+/**
+ * Register the `telemetry` module, which owns the same-origin OTLP proxy the
+ * browser exporter posts to. Without it `TELEMETRY_BROWSER_ENABLED` produces a
+ * client that exports into a 404.
+ */
+function patchModules(appDir: string, options: TelemetryInitOptions): StepResult {
+  const file = 'src/modules.ts'
+  const path = join(appDir, file)
+  const content = readFileSync(path, 'utf8')
+  if (/id:\s*'telemetry'/.test(content)) {
+    return { file, status: 'skipped', detail: 'telemetry module already enabled' }
+  }
+  const anchor = content.match(/export\s+const\s+enabledModules[^=]*=\s*\[/)
+  if (!anchor || anchor.index === undefined) {
+    return {
+      file,
+      status: 'manual',
+      detail: 'enabledModules array not found — add the entry by hand',
+      manualSnippet: MODULES_SNIPPET,
+    }
+  }
+  const insertAt = anchor.index + anchor[0].length
+  const block =
+    `\n  // Same-origin OTLP proxy for browser RUM spans; inert unless` +
+    `\n  // TELEMETRY_BROWSER_ENABLED is set alongside an active telemetry backend.` +
+    `\n  { id: 'telemetry', from: '@open-mercato/telemetry' },`
+  if (!options.dryRun) writeFileSync(path, content.slice(0, insertAt) + block + content.slice(insertAt))
+  return { file, status: 'patched', detail: "enabled the 'telemetry' module (browser-traces proxy route)" }
+}
+
+const LAYOUT_FILE = 'src/app/(backend)/backend/layout.tsx'
+
+const LAYOUT_SNIPPET = `  // add near the other imports:
+  import { BrowserTelemetry } from '@open-mercato/telemetry/browser'
+  import { resolveBrowserTelemetryConfig } from '@open-mercato/telemetry/browser/server'
+
+  // in the component body, before the returned JSX:
+  // pass the request's Cookie header when the layout already reads cookies
+  // (only consulted by the integration-test opt-in; production is env-only):
+  const browserTelemetryConfig = resolveBrowserTelemetryConfig({ cookieHeader: cookieStore.toString() })
+
+  // as the last child of <AppShell>:
+  <BrowserTelemetry config={browserTelemetryConfig} />`
+
+/**
+ * The config resolver takes the request's `Cookie` header so an integration spec can opt one page
+ * into browser RUM; production resolution is env-only and never reads it. A scaffolded layout
+ * already awaits `cookies()`, so reuse that binding — but an app that removed it must still get a
+ * layout that compiles, hence the argument-free fallback. Both forms behave identically outside an
+ * `OM_TEST_MODE` environment.
+ */
+function resolveArgument(layout: string): string {
+  const binding = layout.match(/const\s+(\w+)\s*=\s*await\s+cookies\(\)/)
+  return binding ? `{ cookieHeader: ${binding[1]}.toString() }` : ''
+}
+
+/**
+ * Render the client bootstrap in the backoffice shell. The config is resolved
+ * per request (the layout is `force-dynamic`), so RUM toggles per environment
+ * without a rebuild.
+ *
+ * A backoffice layout is the file apps customize most, so this only edits one
+ * that still matches the scaffold shape; anything else gets the snippet.
+ */
+function patchBackendLayout(appDir: string, options: TelemetryInitOptions): StepResult {
+  const path = join(appDir, LAYOUT_FILE)
+  if (!existsSync(path)) {
+    return { file: LAYOUT_FILE, status: 'manual', detail: 'backend layout not found', manualSnippet: LAYOUT_SNIPPET }
+  }
+  const content = readFileSync(path, 'utf8')
+  if (content.includes('<BrowserTelemetry')) {
+    return { file: LAYOUT_FILE, status: 'skipped', detail: 'BrowserTelemetry already rendered' }
+  }
+  const closingShell = content.lastIndexOf('</AppShell>')
+  const returnMatch = content.match(/^([ \t]*)return \(\s*$/m)
+  const lastImport = [...content.matchAll(/^import[^\n]*$/gm)].at(-1)
+  if (closingShell === -1 || !returnMatch || returnMatch.index === undefined || !lastImport) {
+    return {
+      file: LAYOUT_FILE,
+      status: 'manual',
+      detail: 'layout shape not recognized — apply the snippet by hand',
+      manualSnippet: LAYOUT_SNIPPET,
+    }
+  }
+
+  // Edit back to front so each earlier anchor's offset stays valid.
+  const shellIndent = content.slice(0, closingShell).match(/\n([ \t]*)$/)?.[1] ?? '        '
+  let next =
+    content.slice(0, closingShell) +
+    `<BrowserTelemetry config={browserTelemetryConfig} />\n${shellIndent}` +
+    content.slice(closingShell)
+
+  const returnIndent = returnMatch[1]
+  next =
+    next.slice(0, returnMatch.index) +
+    `${returnIndent}// Resolved per request (this layout is force-dynamic), so browser RUM can be\n` +
+    `${returnIndent}// toggled per environment without a rebuild. Null keeps the SDK chunk from\n` +
+    `${returnIndent}// ever being requested.\n` +
+    `${returnIndent}const browserTelemetryConfig = resolveBrowserTelemetryConfig(${resolveArgument(content)})\n\n` +
+    next.slice(returnMatch.index)
+
+  const importInsertAt = (lastImport.index ?? 0) + lastImport[0].length
+  next =
+    next.slice(0, importInsertAt) +
+    `\nimport { BrowserTelemetry } from '@open-mercato/telemetry/browser'` +
+    `\nimport { resolveBrowserTelemetryConfig } from '@open-mercato/telemetry/browser/server'` +
+    next.slice(importInsertAt)
+
   if (!options.dryRun) writeFileSync(path, next)
-  return { file: relativePath, status: 'patched', detail: 'appended commented TELEMETRY_* / OTEL_* block' }
+  return { file: LAYOUT_FILE, status: 'patched', detail: 'rendered <BrowserTelemetry /> in the backoffice shell' }
 }
 
 function patchInstrumentation(appDir: string, options: TelemetryInitOptions): StepResult {
@@ -427,6 +583,8 @@ export async function runTelemetryInit(args: string[]): Promise<number> {
   results.push(patchInstrumentation(appDir, options))
   results.push(await patchNextConfig(appDir, options))
   results.push(patchDispatcher(appDir, options))
+  results.push(patchModules(appDir, options))
+  results.push(patchBackendLayout(appDir, options))
 
   const icon: Record<StepStatus, string> = { created: '✍️ ', patched: '✅', skipped: '⏭️ ', manual: '⚠️ ' }
   for (const result of results) {

package/src/lib/testing/integration.ts

@@ -2182,6 +2182,11 @@ function buildReusableEnvironment(
     OM_TEST_MODE: '1',
     OM_TEST_EMAIL_CAPTURE_PATH: process.env.OM_TEST_EMAIL_CAPTURE_PATH ?? EPHEMERAL_EMAIL_CAPTURE_PATH,
     OM_TEST_AUTH_RATE_LIMIT_MODE: 'opt-in',
+    // Browser RUM is an environment-wide env switch, so without a per-request opt-in a spec
+    // could only cover the enabled path by booting the OTel web SDK on every page of every
+    // other spec. Same shape as the auth rate-limit escape hatch above: inert unless a request
+    // also carries the `om_test_browser_telemetry=on` cookie, which only TC-TELEMETRY-002 sets.
+    OM_TEST_BROWSER_TELEMETRY_MODE: 'opt-in',
     OM_DISABLE_EMAIL_DELIVERY: '0',
     OM_ENABLE_TEST_CHANNEL_SEEDING: 'true',
     OM_ENABLE_TEST_EMAIL_CAPTURE_DELIVERY: 'true',
@@ -3571,6 +3576,11 @@ export async function startEphemeralEnvironment(options: EphemeralRuntimeOptions
       OM_TEST_MODE: '1',
       OM_TEST_EMAIL_CAPTURE_PATH: process.env.OM_TEST_EMAIL_CAPTURE_PATH ?? EPHEMERAL_EMAIL_CAPTURE_PATH,
       OM_TEST_AUTH_RATE_LIMIT_MODE: 'opt-in',
+      // Browser RUM is an environment-wide env switch, so without a per-request opt-in a spec
+      // could only cover the enabled path by booting the OTel web SDK on every page of every
+      // other spec. Same shape as the auth rate-limit escape hatch above: inert unless a request
+      // also carries the `om_test_browser_telemetry=on` cookie, which only TC-TELEMETRY-002 sets.
+      OM_TEST_BROWSER_TELEMETRY_MODE: 'opt-in',
       OM_ENABLE_TEST_CHANNEL_SEEDING: 'true',
       OM_ENABLE_TEST_EMAIL_CAPTURE_DELIVERY: 'true',
       OM_TEST_SYSTEM_EMAIL_CAPTURE_PATH: EPHEMERAL_SYSTEM_EMAIL_CAPTURE_PATH,