create-mercato-app 0.7.1-develop.7150.1.c1941e0c22 → 0.7.1-develop.7152.1.a69e92f9c9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/agentic/shared/ai/harness/cases.json +4 -2
  2. package/dist/agentic/guides/module-facts.json +828 -149
  3. package/dist/agentic/guides/module-facts.v2.json +828 -149
  4. package/dist/agentic/guides/modules/ai_assistant/index.md +1 -1
  5. package/dist/agentic/guides/modules/api_docs/index.md +1 -1
  6. package/dist/agentic/guides/modules/api_keys/index.md +1 -1
  7. package/dist/agentic/guides/modules/attachments/index.md +1 -1
  8. package/dist/agentic/guides/modules/audit_logs/index.md +1 -1
  9. package/dist/agentic/guides/modules/auth/index.md +1 -1
  10. package/dist/agentic/guides/modules/business_rules/index.md +1 -1
  11. package/dist/agentic/guides/modules/catalog/index.md +1 -1
  12. package/dist/agentic/guides/modules/channel_apns/index.md +1 -1
  13. package/dist/agentic/guides/modules/channel_discord/index.md +1 -1
  14. package/dist/agentic/guides/modules/channel_expo/index.md +1 -1
  15. package/dist/agentic/guides/modules/channel_fcm/index.md +1 -1
  16. package/dist/agentic/guides/modules/channel_gmail/index.md +1 -1
  17. package/dist/agentic/guides/modules/channel_imap/index.md +1 -1
  18. package/dist/agentic/guides/modules/channel_resend/acl-features.md +12 -0
  19. package/dist/agentic/guides/modules/channel_resend/contribution-resolutions.md +11 -0
  20. package/dist/agentic/guides/modules/channel_resend/di-registrations-rich.md +12 -0
  21. package/dist/agentic/guides/modules/channel_resend/exact-override-targets.md +16 -0
  22. package/dist/agentic/guides/modules/channel_resend/index.md +18 -0
  23. package/dist/agentic/guides/modules/channel_resend/owned-contract-module-metadata.md +11 -0
  24. package/dist/agentic/guides/modules/channel_resend/setup.md +11 -0
  25. package/dist/agentic/guides/modules/channel_resend/umes-contributions.md +11 -0
  26. package/dist/agentic/guides/modules/channel_ses/acl-features.md +12 -0
  27. package/dist/agentic/guides/modules/channel_ses/contribution-resolutions.md +11 -0
  28. package/dist/agentic/guides/modules/channel_ses/di-registrations-rich.md +12 -0
  29. package/dist/agentic/guides/modules/channel_ses/exact-override-targets.md +16 -0
  30. package/dist/agentic/guides/modules/channel_ses/index.md +18 -0
  31. package/dist/agentic/guides/modules/channel_ses/owned-contract-module-metadata.md +11 -0
  32. package/dist/agentic/guides/modules/channel_ses/setup.md +11 -0
  33. package/dist/agentic/guides/modules/channel_ses/umes-contributions.md +11 -0
  34. package/dist/agentic/guides/modules/checkout/index.md +1 -1
  35. package/dist/agentic/guides/modules/communication_channels/di-registrations-rich.md +10 -9
  36. package/dist/agentic/guides/modules/communication_channels/exact-override-targets.md +12 -11
  37. package/dist/agentic/guides/modules/communication_channels/index.md +1 -1
  38. package/dist/agentic/guides/modules/communication_channels/setup.md +1 -1
  39. package/dist/agentic/guides/modules/configs/index.md +1 -1
  40. package/dist/agentic/guides/modules/content/index.md +1 -1
  41. package/dist/agentic/guides/modules/currencies/index.md +1 -1
  42. package/dist/agentic/guides/modules/customer_accounts/index.md +1 -1
  43. package/dist/agentic/guides/modules/customers/index.md +1 -1
  44. package/dist/agentic/guides/modules/dashboards/index.md +1 -1
  45. package/dist/agentic/guides/modules/data_sync/index.md +1 -1
  46. package/dist/agentic/guides/modules/design_system/index.md +1 -1
  47. package/dist/agentic/guides/modules/devices/index.md +1 -1
  48. package/dist/agentic/guides/modules/dictionaries/index.md +1 -1
  49. package/dist/agentic/guides/modules/directory/index.md +1 -1
  50. package/dist/agentic/guides/modules/documents/index.md +1 -1
  51. package/dist/agentic/guides/modules/entities/index.md +1 -1
  52. package/dist/agentic/guides/modules/eudr/index.md +1 -1
  53. package/dist/agentic/guides/modules/events/index.md +1 -1
  54. package/dist/agentic/guides/modules/feature_toggles/index.md +1 -1
  55. package/dist/agentic/guides/modules/gateway_stripe/index.md +1 -1
  56. package/dist/agentic/guides/modules/generators/index.md +1 -1
  57. package/dist/agentic/guides/modules/inbox_ops/index.md +1 -1
  58. package/dist/agentic/guides/modules/integrations/index.md +1 -1
  59. package/dist/agentic/guides/modules/messages/index.md +1 -1
  60. package/dist/agentic/guides/modules/notifications/index.md +1 -1
  61. package/dist/agentic/guides/modules/onboarding/index.md +1 -1
  62. package/dist/agentic/guides/modules/payment_gateways/index.md +1 -1
  63. package/dist/agentic/guides/modules/perspectives/index.md +1 -1
  64. package/dist/agentic/guides/modules/planner/index.md +1 -1
  65. package/dist/agentic/guides/modules/portal/index.md +1 -1
  66. package/dist/agentic/guides/modules/progress/index.md +1 -1
  67. package/dist/agentic/guides/modules/push_notifications/index.md +1 -1
  68. package/dist/agentic/guides/modules/query_index/index.md +1 -1
  69. package/dist/agentic/guides/modules/record_locks/index.md +1 -1
  70. package/dist/agentic/guides/modules/resources/index.md +1 -1
  71. package/dist/agentic/guides/modules/sales/index.md +1 -1
  72. package/dist/agentic/guides/modules/scheduler/index.md +1 -1
  73. package/dist/agentic/guides/modules/search/index.md +1 -1
  74. package/dist/agentic/guides/modules/security/index.md +1 -1
  75. package/dist/agentic/guides/modules/shipping_carriers/index.md +1 -1
  76. package/dist/agentic/guides/modules/sso/index.md +1 -1
  77. package/dist/agentic/guides/modules/staff/index.md +1 -1
  78. package/dist/agentic/guides/modules/storage_s3/index.md +1 -1
  79. package/dist/agentic/guides/modules/sync_akeneo/index.md +1 -1
  80. package/dist/agentic/guides/modules/sync_excel/index.md +1 -1
  81. package/dist/agentic/guides/modules/system_status_overlays/index.md +1 -1
  82. package/dist/agentic/guides/modules/translations/index.md +1 -1
  83. package/dist/agentic/guides/modules/warranty_claims/index.md +1 -1
  84. package/dist/agentic/guides/modules/webhooks/index.md +1 -1
  85. package/dist/agentic/guides/modules/wms/index.md +1 -1
  86. package/dist/agentic/guides/modules/workflows/index.md +1 -1
  87. package/dist/agentic/guides/reference-module-facts.json +1 -1
  88. package/dist/agentic/guides/upstream/manifest.json +1 -1
  89. package/dist/agentic/shared/ai/harness/cases.json +4 -2
  90. package/package.json +3 -3
  91. package/template/.env.example +46 -1
  92. package/template/package.json.template +2 -0
  93. package/template/scripts/dev-runtime-actions.mjs +99 -0
  94. package/template/scripts/dev-runtime-config.mjs +89 -0
  95. package/template/scripts/dev-runtime-diagnostics.mjs +292 -0
  96. package/template/scripts/dev-runtime-gateway.mjs +370 -0
  97. package/template/scripts/dev-runtime-probe.mjs +77 -0
  98. package/template/scripts/dev-runtime-state.mjs +571 -0
  99. package/template/scripts/dev-runtime-supervisor.mjs +268 -0
  100. package/template/scripts/dev-runtime.mjs +29 -0
  101. package/template/scripts/dev-splash-state.mjs +14 -0
  102. package/template/scripts/dev-splash.html +357 -2
  103. package/template/scripts/dev.mjs +396 -14
  104. package/template/src/app/__tests__/start-page-bootstrap.test.ts +34 -0
  105. package/template/src/app/api/dev-runtime/actions/[action]/route.ts +5 -0
  106. package/template/src/app/api/dev-runtime/diagnostics/route.ts +5 -0
  107. package/template/src/app/api/dev-runtime/logs/route.ts +5 -0
  108. package/template/src/app/api/dev-runtime/status/route.ts +5 -0
  109. package/template/src/app/api/healthz/__tests__/route.test.ts +3 -1
  110. package/template/src/app/global-error.tsx +7 -0
  111. package/template/src/app/layout.tsx +11 -0
  112. package/template/src/app/start/page.tsx +11 -1
  113. package/template/src/i18n/de.json +27 -0
  114. package/template/src/i18n/en.json +27 -0
  115. package/template/src/i18n/es.json +27 -0
  116. package/template/src/i18n/ko.json +27 -0
  117. package/template/src/i18n/pl.json +27 -0
  118. package/template/src/modules/example/__integration__/TC-START-001-onboarding-gate.spec.ts +33 -0
  119. package/template/src/modules.ts +2 -0
@@ -33,8 +33,13 @@ import { killProcessTree } from './dev-shutdown-utils.mjs'
33
33
  import { resolveSpawnCommand } from './dev-spawn-utils.mjs'
34
34
  import { createDevSplashCodingFlow } from './dev-splash-coding-flow.mjs'
35
35
  import { createDevSplashGitRepoFlow } from './dev-splash-git-repo-flow.mjs'
36
- import { resolveSplashBindHost } from './dev-splash-shared.mjs'
36
+ import { assertLocalSplashRequest, resolveSplashBindHost } from './dev-splash-shared.mjs'
37
37
  import { normalizeSplashDisplayState } from './dev-splash-state.mjs'
38
+ import { DevRuntimeConfigError, resolveDevRuntimeConfig } from './dev-runtime-config.mjs'
39
+ import { createDevRuntimeSupervisor } from './dev-runtime-supervisor.mjs'
40
+ import { createDevRuntimeGateway } from './dev-runtime-gateway.mjs'
41
+ import { createDevRuntimeActionRunner } from './dev-runtime-actions.mjs'
42
+ import { isMatchingDevRuntimeToken } from './dev-runtime-diagnostics.mjs'
38
43
  import {
39
44
  resolveDevBaseUrl,
40
45
  resolveSplashUrl as resolveSplashAccessUrl,
@@ -215,6 +220,21 @@ const standaloneStageTotal = setupMode ? 5 : 4
215
220
  const splashEnabled = !classic && !appOnly && splashPortConfig.enabled
216
221
  const autoOpenSplash = splashEnabled && process.stdout.isTTY && process.env.CI !== 'true' && process.env.OM_DEV_AUTO_OPEN !== '0'
217
222
  const splashBindHost = resolveSplashBindHost(process.env)
223
+ const publicAppPort = resolveDevBaseUrl(process.env).port ?? 3000
224
+ const devRuntimeConfig = (() => {
225
+ try {
226
+ return resolveDevRuntimeConfig(process.env, { splashEnabled, publicPort: publicAppPort })
227
+ } catch (error) {
228
+ if (error instanceof DevRuntimeConfigError) {
229
+ console.error(`❌ ${error.message}`)
230
+ process.exit(1)
231
+ }
232
+ throw error
233
+ }
234
+ })()
235
+ // The gateway owns the public port only when explicitly opted in; `direct` mode
236
+ // keeps the historical topology where Next.js binds it.
237
+ const gatewayMode = devRuntimeConfig.mode === 'proxy'
218
238
  const standaloneRuntimeScript = path.join(process.cwd(), 'scripts', 'dev-runtime.mjs')
219
239
  const monorepoPackageWatchScript = path.join(process.cwd(), 'scripts', 'watch-packages.mjs')
220
240
  const monorepoAppDir = path.join(process.cwd(), 'apps', 'mercato')
@@ -290,6 +310,15 @@ const children = new Set()
290
310
  let shuttingDown = false
291
311
  let splashServer = null
292
312
  let splashUrl = null
313
+ let devGateway = null
314
+ let devUpstreamPort = null
315
+ let managedAppChild = null
316
+ let restartRequestedReason = null
317
+ // Gateway mode answers a startup-stage failure by keeping the supervisor alive
318
+ // instead of shutting down, so the startup pipeline has to stop itself. Without
319
+ // this latch the remaining stages — and the app launch — would run against a
320
+ // tree that already failed to build.
321
+ let startupAborted = false
293
322
  let splashChildStateFile = null
294
323
  let splashLogoSvg = null
295
324
  let splashHtmlTemplate = null
@@ -323,6 +352,38 @@ const splashState = {
323
352
  : (setupMode ? 'Preparing project setup' : 'Preparing app runtime'),
324
353
  activities: [],
325
354
  }
355
+ const devRuntime = createDevRuntimeSupervisor({
356
+ enabled: devRuntimeConfig.diagnosticsEnabled,
357
+ config: devRuntimeConfig,
358
+ stateDirectory: path.join(process.cwd(), '.mercato'),
359
+ publicUrl: resolveDevBaseUrl(process.env).url,
360
+ configuredPort: publicAppPort,
361
+ resolveBaseUrl: () => resolveRuntimeProbeBaseUrl(),
362
+ readChildState: () => readSplashChildState(),
363
+ // Drains recovery requests queued by the dev-only app route (in-app banner).
364
+ runAction: (action) => devRuntimeActions.run(action),
365
+ })
366
+ // Recovery actions map a fixed enum onto lifecycle steps the supervisor already
367
+ // owns. They never build a command from request input.
368
+ const devRuntimeActions = createDevRuntimeActionRunner({
369
+ state: devRuntime,
370
+ handlers: {
371
+ generate: async () => {
372
+ const exitCode = await runRecoveryCommand('Regenerating module artifacts', ['generate'])
373
+ if (exitCode === 0) restartManagedRuntime('generate action')
374
+ return exitCode
375
+ },
376
+ migrate: async () => {
377
+ const exitCode = await runRecoveryCommand('Applying database migrations', ['db:migrate'])
378
+ if (exitCode === 0) restartManagedRuntime('migrate action')
379
+ return exitCode
380
+ },
381
+ restart: async () => {
382
+ restartManagedRuntime('restart action')
383
+ return 0
384
+ },
385
+ },
386
+ })
326
387
  const codingFlow = createDevSplashCodingFlow({
327
388
  env: process.env,
328
389
  platform: process.platform,
@@ -347,6 +408,14 @@ function resolveExpectedAppBaseUrl() {
347
408
  return resolveDevBaseUrl(process.env).url
348
409
  }
349
410
 
411
+ // The continuous probe always talks to the managed runtime directly, so in
412
+ // gateway mode it must target the internal loopback port rather than the public
413
+ // gateway it is meant to diagnose.
414
+ function resolveRuntimeProbeBaseUrl() {
415
+ if (gatewayMode && devUpstreamPort) return `http://127.0.0.1:${devUpstreamPort}`
416
+ return resolveExpectedAppBaseUrl()
417
+ }
418
+
350
419
  function resolveExpectedBackendUrl() {
351
420
  return `${resolveExpectedAppBaseUrl()}/backend`
352
421
  }
@@ -596,6 +665,7 @@ function buildSplashChildEnv(options = {}) {
596
665
  if (!splashChildStateFile) {
597
666
  const env = {
598
667
  ...childEnv,
668
+ ...devRuntime.childEnv(),
599
669
  OM_DEV_SHUTDOWN_NOTICE_OWNER: 'parent',
600
670
  }
601
671
  return Object.keys(env).length > 0 ? env : undefined
@@ -603,6 +673,9 @@ function buildSplashChildEnv(options = {}) {
603
673
 
604
674
  return {
605
675
  ...childEnv,
676
+ ...devRuntime.childEnv(),
677
+ // Lets the in-app banner link "View logs" back to the standalone splash.
678
+ ...(splashUrl ? { OM_DEV_RUNTIME_SPLASH_URL: splashUrl } : {}),
606
679
  OM_DEV_SPLASH_CHILD_STATE_FILE: splashChildStateFile,
607
680
  OM_DEV_WARMUP_READY_FILE: warmupReadyFilePath,
608
681
  OM_DEV_SPLASH_MODE: splashMode,
@@ -699,6 +772,9 @@ function buildAppDevEnv(options = {}) {
699
772
  const env = applyLocalDevBackgroundServiceDefaults({
700
773
  ...(buildSplashChildEnv(options) ?? {}),
701
774
  ...(memoryTraceEnabled ? { OM_DEV_MEMORY_TRACE_OWNER: 'parent' } : {}),
775
+ // In gateway mode the managed runtime binds the internal loopback port and
776
+ // the gateway keeps the public one.
777
+ ...(gatewayMode && devUpstreamPort ? { PORT: String(devUpstreamPort) } : {}),
702
778
  })
703
779
  if (isMonorepo) {
704
780
  // `yarn workspace ... dev` used to inject the workspace binaries into PATH.
@@ -712,6 +788,7 @@ function buildAppDevEnv(options = {}) {
712
788
  }
713
789
 
714
790
  function launchStandaloneDev(options = {}) {
791
+ if (startupAborted) return
715
792
  if (!fs.existsSync(standaloneRuntimeScript)) {
716
793
  console.error(`❌ Standalone dev runtime not found at ${standaloneRuntimeScript}`)
717
794
  shutdown(1)
@@ -743,15 +820,60 @@ function launchStandaloneDev(options = {}) {
743
820
  activity,
744
821
  })
745
822
 
823
+ writeSplashChildStateFileClear()
824
+ devRuntime.beginGeneration('standalone app runtime launch')
746
825
  const app = spawnCommand(process.execPath, runtimeArgs, {
747
826
  stdio: 'inherit',
748
827
  env: buildAppDevEnv({ stageCurrent, stageTotal }),
749
828
  })
829
+ managedAppChild = app
750
830
 
751
831
  app.on('close', (code) => {
752
- if (!shuttingDown) {
753
- shutdown(code ?? 0)
754
- }
832
+ if (shuttingDown) return
833
+ if (consumeRequestedRestart()) return
834
+ recordManagedRuntimeExit(code ?? 0, null)
835
+ if (keepSupervisorAliveAfterFailure()) return
836
+ shutdown(code ?? 0)
837
+ })
838
+ }
839
+
840
+ // A restart requested through a recovery action is an expected exit, so it
841
+ // relaunches instead of tearing the supervisor down.
842
+ function consumeRequestedRestart() {
843
+ if (!restartRequestedReason) return false
844
+ const reason = restartRequestedReason
845
+ restartRequestedReason = null
846
+ managedAppChild = null
847
+ relaunchManagedRuntime(reason)
848
+ return true
849
+ }
850
+
851
+ // Only the gateway can keep serving feedback once the managed runtime is gone,
852
+ // so only gateway mode survives a failure. Direct mode keeps its existing
853
+ // shutdown behavior.
854
+ function keepSupervisorAliveAfterFailure() {
855
+ if (!gatewayMode || shuttingDown) return false
856
+ managedAppChild = null
857
+ console.error('⚠️ The app runtime stopped. The dev gateway stays available for diagnostics and recovery actions.')
858
+ return true
859
+ }
860
+
861
+ // A managed runtime that dies on its own is the strongest possible signal that
862
+ // the public URL cannot serve anything, so it always produces a blocking
863
+ // incident regardless of how far startup had progressed.
864
+ function recordManagedRuntimeExit(exitCode, signal) {
865
+ if (!devRuntime.enabled) return
866
+ if (exitCode === 0 && !signal) return
867
+ const cause = signal ? `signal ${signal}` : `exit code ${exitCode}`
868
+ devRuntime.recordSignal({
869
+ source: 'process',
870
+ code: 'runtime_process_exited',
871
+ title: 'App runtime stopped',
872
+ detail: `The managed app runtime terminated with ${cause}`,
873
+ message: `app runtime terminated with ${cause}`,
874
+ failureCommand: 'yarn dev',
875
+ failureStage: 'App runtime',
876
+ blocking: true,
755
877
  })
756
878
  }
757
879
 
@@ -976,6 +1098,15 @@ async function reportStageFailure(label, commandArgs, capturedLines, code, optio
976
1098
  const failureLines = extractFailureLines(capturedLines)
977
1099
  const detail = resolveFailureDetail(label, capturedLines)
978
1100
 
1101
+ devRuntime.recordSignal({
1102
+ source: 'process',
1103
+ message: failureLines.join('\n') || detail,
1104
+ detail,
1105
+ failureLines,
1106
+ failureCommand: Array.isArray(commandArgs) ? commandArgs.join(' ') : undefined,
1107
+ failureStage: label,
1108
+ })
1109
+
979
1110
  updateSplashState({
980
1111
  phase: `${label} failed`,
981
1112
  detail,
@@ -998,9 +1129,20 @@ async function reportStageFailure(label, commandArgs, capturedLines, code, optio
998
1129
  }
999
1130
 
1000
1131
  await waitForSplashFailureRender()
1132
+ if (keepSupervisorAliveAfterStageFailure(label)) return
1001
1133
  shutdown(code ?? 1)
1002
1134
  }
1003
1135
 
1136
+ // Gateway mode keeps the supervisor alive after a startup-stage failure so the
1137
+ // developer can run an allowlisted recovery action without restarting the
1138
+ // terminal process. Direct mode preserves its existing shutdown behavior.
1139
+ function keepSupervisorAliveAfterStageFailure(label) {
1140
+ if (!gatewayMode || shuttingDown) return false
1141
+ startupAborted = true
1142
+ console.error(`⚠️ "${label}" failed. The dev gateway stays available on ${resolveExpectedAppBaseUrl()} for diagnostics and recovery actions.`)
1143
+ return true
1144
+ }
1145
+
1004
1146
  function readSplashChildState() {
1005
1147
  if (!splashChildStateFile || !fs.existsSync(splashChildStateFile)) return null
1006
1148
  try {
@@ -1012,11 +1154,23 @@ function readSplashChildState() {
1012
1154
 
1013
1155
  function getMergedSplashState() {
1014
1156
  const childState = readSplashChildState()
1015
- const mergedState = childState ? normalizeSplashDisplayState({
1157
+ devRuntime.ingestChildState(childState)
1158
+ const runtimeStatus = devRuntime.enabled ? devRuntime.getStatus() : null
1159
+
1160
+ // `runtimeSignals` is the child's raw hand-off channel; it is consumed by the
1161
+ // collector and must never reach the splash payload.
1162
+ const { runtimeSignals: _ignoredChildSignals, ...childDisplayState } = childState ?? {}
1163
+
1164
+ const mergedState = normalizeSplashDisplayState({
1016
1165
  ...splashState,
1017
- ...childState,
1018
- activities: mergeActivities(splashState.activities, childState.activities),
1019
- }) : normalizeSplashDisplayState({ ...splashState })
1166
+ ...childDisplayState,
1167
+ ...(childState ? { activities: mergeActivities(splashState.activities, childState.activities) } : {}),
1168
+ // The structured runtime state is the authority for ready/failed once the
1169
+ // collector is active, so a post-ready incident is no longer normalized away.
1170
+ ...(runtimeStatus
1171
+ ? { runtime: runtimeStatus, ready: runtimeStatus.ready, failed: runtimeStatus.failed }
1172
+ : {}),
1173
+ })
1020
1174
 
1021
1175
  mergedState.codingFlow = codingFlow.getSnapshot({
1022
1176
  ready: mergedState.ready,
@@ -1043,6 +1197,9 @@ function renderSplashHtml(req) {
1043
1197
  localeLabels,
1044
1198
  codingFlow: codingFlow.getBootstrapPayload(),
1045
1199
  gitRepoFlow: gitRepoFlow.getBootstrapPayload(),
1200
+ // Per-run token for the additive recovery endpoint. It never leaves the
1201
+ // local dev browser and is regenerated on every supervisor start.
1202
+ runtimeToken: devRuntime.enabled ? devRuntime.token : null,
1046
1203
  })
1047
1204
  return loadSplashHtmlTemplate()
1048
1205
  .replace('__SPLASH_INITIAL_LOCALE__', initialLocale)
@@ -1090,6 +1247,69 @@ async function startSplashServer() {
1090
1247
  return
1091
1248
  }
1092
1249
 
1250
+ if (req.url === '/runtime/status') {
1251
+ res.setHeader('Content-Type', 'application/json; charset=utf-8')
1252
+ const guard = assertLocalSplashRequest(req, process.env)
1253
+ if (!guard.ok) {
1254
+ res.statusCode = guard.status
1255
+ res.end(JSON.stringify({ error: { code: 'forbidden', message: guard.error } }))
1256
+ return
1257
+ }
1258
+ res.end(JSON.stringify(devRuntime.enabled ? devRuntime.getStatus() : { error: { code: 'diagnostics_disabled', message: 'Dev runtime diagnostics are disabled.' } }))
1259
+ return
1260
+ }
1261
+
1262
+ // Additive recovery endpoint for the default direct topology. Existing
1263
+ // splash routes and their response shapes are untouched.
1264
+ if (req.method === 'POST' && req.url.startsWith('/runtime/actions/')) {
1265
+ res.setHeader('Content-Type', 'application/json; charset=utf-8')
1266
+ const guard = assertLocalSplashRequest(req, process.env)
1267
+ if (!guard.ok) {
1268
+ res.statusCode = guard.status
1269
+ res.end(JSON.stringify({ error: { code: 'forbidden', message: guard.error } }))
1270
+ return
1271
+ }
1272
+ if (!devRuntime.enabled) {
1273
+ res.statusCode = 404
1274
+ res.end(JSON.stringify({ error: { code: 'diagnostics_disabled', message: 'Dev runtime diagnostics are disabled.' } }))
1275
+ return
1276
+ }
1277
+ if (!isMatchingDevRuntimeToken(devRuntime.token, req.headers['x-om-dev-runtime-token'])) {
1278
+ res.statusCode = 403
1279
+ res.end(JSON.stringify({ error: { code: 'forbidden', message: 'Invalid dev runtime token.' } }))
1280
+ return
1281
+ }
1282
+
1283
+ const action = req.url.slice('/runtime/actions/'.length).split('?')[0]
1284
+ const result = await devRuntimeActions.run(action)
1285
+ if (!result.ok) {
1286
+ res.statusCode = result.status
1287
+ res.end(JSON.stringify({ error: { code: result.code, message: result.message } }))
1288
+ return
1289
+ }
1290
+ res.statusCode = 202
1291
+ res.end(JSON.stringify({ accepted: true, actionId: result.actionId, generation: result.generation }))
1292
+ return
1293
+ }
1294
+
1295
+ if (req.url.startsWith('/runtime/logs')) {
1296
+ res.setHeader('Content-Type', 'application/json; charset=utf-8')
1297
+ const guard = assertLocalSplashRequest(req, process.env)
1298
+ if (!guard.ok) {
1299
+ res.statusCode = guard.status
1300
+ res.end(JSON.stringify({ error: { code: 'forbidden', message: guard.error } }))
1301
+ return
1302
+ }
1303
+ if (!devRuntime.enabled) {
1304
+ res.statusCode = 404
1305
+ res.end(JSON.stringify({ error: { code: 'diagnostics_disabled', message: 'Dev runtime diagnostics are disabled.' } }))
1306
+ return
1307
+ }
1308
+ const cursor = Number.parseInt(new URL(req.url, 'http://localhost').searchParams.get('cursor') ?? '', 10)
1309
+ res.end(JSON.stringify(devRuntime.getDiagnosticLines(Number.isInteger(cursor) ? cursor : 0)))
1310
+ return
1311
+ }
1312
+
1093
1313
  if (req.url === '/' || req.url.startsWith('/?')) {
1094
1314
  res.setHeader('Content-Type', 'text/html; charset=utf-8')
1095
1315
  res.end(renderSplashHtml(req))
@@ -1173,11 +1393,162 @@ async function startSplashServer() {
1173
1393
  console.log('ℹ️ Open either URL manually while the runtime is starting.')
1174
1394
  }
1175
1395
 
1396
+ // Runs one allowlisted lifecycle command for a recovery action. Unlike
1397
+ // `runStage` it never shuts the supervisor down: a failed recovery becomes an
1398
+ // incident so the developer can try another action.
1399
+ // `waitForClose` only settles on 'close', which needs every stdio pipe to drain.
1400
+ // A recovery child that fails to spawn — or leaves a grandchild holding the
1401
+ // pipes — would therefore never settle, wedging the single-action latch until
1402
+ // the action timeout. Settling on 'exit'/'error' too keeps the latch honest.
1403
+ function waitForRecoveryChildExit(child) {
1404
+ return new Promise((resolve) => {
1405
+ let settled = false
1406
+ const settle = (result) => {
1407
+ if (settled) return
1408
+ settled = true
1409
+ resolve(result)
1410
+ }
1411
+ child.on('close', (code, signal) => settle({ code, signal }))
1412
+ child.on('exit', (code, signal) => settle({ code, signal }))
1413
+ child.on('error', () => settle({ code: 1, signal: null }))
1414
+ })
1415
+ }
1416
+
1417
+ async function runRecoveryCommand(label, commandArgs) {
1418
+ console.log(`🛠️ ${label}...`)
1419
+ updateSplashState({ phase: label, detail: 'Recovery action in progress', activity: `${label} started` })
1420
+
1421
+ const child = spawnCommand(yarnCommand, commandArgs, { label, logFile: getDevRunnerLog() })
1422
+ const capturedLines = []
1423
+ const capture = (line) => {
1424
+ const normalized = normalizeCapturedLine(line)
1425
+ devRuntime.appendDiagnosticLine(normalized, { source: 'process' })
1426
+ capturedLines.push(normalized)
1427
+ if (capturedLines.length > 200) capturedLines.shift()
1428
+ }
1429
+ connectLineStream(child.stdout, capture)
1430
+ connectLineStream(child.stderr, capture)
1431
+
1432
+ const exitCode = resolveChildExitCode(await waitForRecoveryChildExit(child))
1433
+ if (exitCode !== 0) {
1434
+ devRuntime.recordSignal({
1435
+ source: 'process',
1436
+ message: extractFailureLines(capturedLines).join('\n') || `${label} failed`,
1437
+ detail: resolveFailureDetail(label, capturedLines),
1438
+ failureLines: extractFailureLines(capturedLines),
1439
+ failureCommand: `${yarnCommand} ${commandArgs.join(' ')}`,
1440
+ failureStage: label,
1441
+ })
1442
+ console.error(`❌ ${label} failed with exit code ${exitCode}`)
1443
+ return exitCode
1444
+ }
1445
+
1446
+ console.log(`✅ ${label} completed`)
1447
+ return 0
1448
+ }
1449
+
1450
+ // Restarts the managed runtime through the existing launcher so stage ordering
1451
+ // and process ownership stay in one place. The child's close handler relaunches
1452
+ // it, which also opens a fresh generation.
1453
+ function restartManagedRuntime(reason) {
1454
+ if (!managedAppChild || managedAppChild.killed) {
1455
+ relaunchManagedRuntime(reason)
1456
+ return
1457
+ }
1458
+ restartRequestedReason = reason
1459
+ killProcessTree(managedAppChild, 'SIGTERM')
1460
+ }
1461
+
1462
+ function relaunchManagedRuntime(reason) {
1463
+ // A recovery action is the deliberate answer to the failure that latched the
1464
+ // pipeline, so relaunching clears it.
1465
+ startupAborted = false
1466
+ console.log(`🔁 Restarting the app runtime (${reason})`)
1467
+ if (isMonorepo) {
1468
+ launchMonorepoAppDev()
1469
+ return
1470
+ }
1471
+ launchStandaloneDev()
1472
+ }
1473
+
1474
+ // Picks an ephemeral loopback port for the managed runtime by letting the OS
1475
+ // assign one and releasing it immediately. The window between release and the
1476
+ // child's bind is small and local; a collision surfaces as a clear child error.
1477
+ function reserveLoopbackPort() {
1478
+ return new Promise((resolve, reject) => {
1479
+ const probe = createServer()
1480
+ probe.once('error', reject)
1481
+ probe.listen(0, '127.0.0.1', () => {
1482
+ const { port } = probe.address()
1483
+ probe.close(() => resolve(port))
1484
+ })
1485
+ })
1486
+ }
1487
+
1488
+ async function startDevRuntimeGateway() {
1489
+ if (!gatewayMode) return true
1490
+
1491
+ try {
1492
+ devUpstreamPort = devRuntimeConfig.upstreamPort ?? await reserveLoopbackPort()
1493
+ } catch (error) {
1494
+ console.error(`❌ Unable to reserve an internal port for the dev runtime gateway: ${error instanceof Error ? error.message : String(error)}`)
1495
+ shutdown(1)
1496
+ return false
1497
+ }
1498
+
1499
+ devGateway = createDevRuntimeGateway({
1500
+ token: devRuntime.token,
1501
+ env: process.env,
1502
+ logger: console,
1503
+ getStatus: () => (devRuntime.enabled ? devRuntime.getStatus() : null),
1504
+ getDiagnosticLines: (cursor) => devRuntime.getDiagnosticLines(cursor),
1505
+ recordBrowserReport: (report) => {
1506
+ devRuntime.recordSignal({
1507
+ source: 'browser',
1508
+ severity: 'error',
1509
+ message: report.message,
1510
+ digest: report.digest,
1511
+ path: report.path,
1512
+ blocking: false,
1513
+ })
1514
+ return devRuntime.getStatus().issueSummary?.id ?? null
1515
+ },
1516
+ runAction: (action) => devRuntimeActions.run(action),
1517
+ resolveUpstream: () => (devUpstreamPort ? { host: '127.0.0.1', port: devUpstreamPort } : null),
1518
+ renderSplashHtml: (req) => renderSplashHtml(req),
1519
+ })
1520
+
1521
+ try {
1522
+ await devGateway.listen(publicAppPort, splashBindHost)
1523
+ } catch (error) {
1524
+ const reason = error?.code === 'EADDRINUSE'
1525
+ ? `port ${publicAppPort} is already in use`
1526
+ : (error instanceof Error ? error.message : String(error))
1527
+ console.error(`❌ Unable to start the dev runtime gateway: ${reason}`)
1528
+ console.error(' Free the port, choose another PORT, or set OM_DEV_RUNTIME_MODE=direct.')
1529
+ devGateway = null
1530
+ shutdown(1)
1531
+ return false
1532
+ }
1533
+
1534
+ devRuntime.setUpstream({ configuredPort: publicAppPort, actualPort: devUpstreamPort })
1535
+ console.log(`🛡️ Dev runtime gateway on ${resolveExpectedAppBaseUrl()} → managed runtime on 127.0.0.1:${devUpstreamPort}`)
1536
+ return true
1537
+ }
1538
+
1539
+ function closeDevRuntimeGateway() {
1540
+ if (!devGateway) return
1541
+ void devGateway.close()
1542
+ devGateway = null
1543
+ }
1544
+
1176
1545
  function closeSplashServer() {
1177
1546
  if (splashServer) {
1178
1547
  splashServer.close()
1179
1548
  splashServer = null
1180
1549
  }
1550
+ closeDevRuntimeGateway()
1551
+ devRuntime.stop()
1181
1552
  writeSplashChildStateFileClear()
1182
1553
  }
1183
1554
 
@@ -1537,6 +1908,7 @@ function classifyStageMarker(commandArgs) {
1537
1908
  }
1538
1909
 
1539
1910
  async function runStage(label, commandArgs, options = {}) {
1911
+ if (startupAborted) return
1540
1912
  const startedAt = Date.now()
1541
1913
  const stageTotal = options.stageTotal ?? (greenfield ? 5 : 3)
1542
1914
  const stageCurrent = options.stageCurrent
@@ -1629,6 +2001,7 @@ async function runStage(label, commandArgs, options = {}) {
1629
2001
  }
1630
2002
 
1631
2003
  async function runPassthroughStage(label, commandArgs, options = {}) {
2004
+ if (startupAborted) return
1632
2005
  const startedAt = Date.now()
1633
2006
  const stageOrder = {
1634
2007
  'build:packages': 1,
@@ -1738,6 +2111,7 @@ function resolveActiveWatchScope(watchScopeEnv = buildWatchScopeEnv()) {
1738
2111
  }
1739
2112
 
1740
2113
  function startPackageWatch() {
2114
+ if (startupAborted) return
1741
2115
  const watchScript = resolveWatchPackagesScript()
1742
2116
  const watchCommand = watchScript === 'watch:packages'
1743
2117
  ? { command: process.execPath, args: [monorepoPackageWatchScript] }
@@ -1846,6 +2220,7 @@ function startPackageWatch() {
1846
2220
  }
1847
2221
 
1848
2222
  function launchMonorepoAppDev() {
2223
+ if (startupAborted) return
1849
2224
  const appArgs = [monorepoAppDevScript]
1850
2225
  if (classic) appArgs.push('--classic')
1851
2226
  else if (verbose) appArgs.push('--verbose')
@@ -1863,19 +2238,24 @@ function launchMonorepoAppDev() {
1863
2238
  progressLabel: 'Launching app runtime',
1864
2239
  activity: 'App runtime is starting',
1865
2240
  })
2241
+ writeSplashChildStateFileClear()
2242
+ devRuntime.beginGeneration('app runtime launch')
1866
2243
  const app = spawnCommand(process.execPath, appArgs, {
1867
2244
  cwd: monorepoAppDir,
1868
2245
  stdio: 'inherit',
1869
2246
  env: buildAppDevEnv({ stageCurrent, stageTotal }),
1870
2247
  })
2248
+ managedAppChild = app
1871
2249
 
1872
2250
  app.on('close', (code, signal) => {
1873
- if (!shuttingDown) {
1874
- // Unexpected child exit MUST surface as non-zero even if the child reported
1875
- // code 0 — hiding a broken runtime as success masks failures from scripts/CI.
1876
- const childCode = resolveChildExitCode({ code, signal }, 1)
1877
- shutdown(childCode === 0 ? 1 : childCode)
1878
- }
2251
+ if (shuttingDown) return
2252
+ if (consumeRequestedRestart()) return
2253
+ // Unexpected child exit MUST surface as non-zero even if the child reported
2254
+ // code 0 — hiding a broken runtime as success masks failures from scripts/CI.
2255
+ const childCode = resolveChildExitCode({ code, signal }, 1)
2256
+ recordManagedRuntimeExit(childCode, signal)
2257
+ if (keepSupervisorAliveAfterFailure()) return
2258
+ shutdown(childCode === 0 ? 1 : childCode)
1879
2259
  })
1880
2260
  }
1881
2261
 
@@ -1978,7 +2358,9 @@ async function runClassicStandaloneDev() {
1978
2358
 
1979
2359
  async function main() {
1980
2360
  printDevLogLocation()
2361
+ devRuntime.start()
1981
2362
  await startSplashServer()
2363
+ if (!await startDevRuntimeGateway()) return
1982
2364
  if (!ensureDevFileWatchLimits()) return
1983
2365
 
1984
2366
  if (!isMonorepo) {
@@ -0,0 +1,34 @@
1
+ import fs from 'node:fs'
2
+ import path from 'node:path'
3
+
4
+ /**
5
+ * `/start` reads the database counters through `createRequestContainer()` and gates the
6
+ * self-service onboarding CTA on `isEmailDeliveryConfigured()`. Both depend on the process
7
+ * having been bootstrapped: the container throws until `registerDiRegistrars()` has run, and
8
+ * the email transport the capability check reads is registered by a module's DI `register()`.
9
+ *
10
+ * Neither failure is visible — the container error is swallowed into the database panel and the
11
+ * missing transport just reads as "email is not configured" — so the page answered a cold
12
+ * process with an error panel and no CTA on a fully configured instance, then corrected itself
13
+ * once any API route bootstrapped the process (#5817). Asserting the call is a statement at
14
+ * module scope, rather than merely that the identifier appears, keeps an import-only or
15
+ * inside-a-branch regression from passing.
16
+ */
17
+ describe('start page bootstrap', () => {
18
+ const source = fs.readFileSync(path.join(process.cwd(), 'src/app/start/page.tsx'), 'utf8')
19
+
20
+ it('imports the full app bootstrap', () => {
21
+ expect(source).toMatch(/^import \{ bootstrap \} from '@\/bootstrap'$/m)
22
+ })
23
+
24
+ it('invokes it at module scope, before any request is served', () => {
25
+ const moduleScopeCall = /^bootstrap\(\)$/m
26
+ expect(source).toMatch(moduleScopeCall)
27
+
28
+ const callIndex = source.search(moduleScopeCall)
29
+ const defaultExportIndex = source.indexOf('export default async function StartPage')
30
+ expect(callIndex).toBeGreaterThan(-1)
31
+ expect(defaultExportIndex).toBeGreaterThan(-1)
32
+ expect(callIndex).toBeLessThan(defaultExportIndex)
33
+ })
34
+ })
@@ -0,0 +1,5 @@
1
+ import { createDevRuntimeActionsRoute } from '@open-mercato/shared/lib/dev-runtime/routes'
2
+
3
+ export const dynamic = 'force-dynamic'
4
+
5
+ export const POST = createDevRuntimeActionsRoute()
@@ -0,0 +1,5 @@
1
+ import { createDevRuntimeDiagnosticsRoute } from '@open-mercato/shared/lib/dev-runtime/routes'
2
+
3
+ export const dynamic = 'force-dynamic'
4
+
5
+ export const POST = createDevRuntimeDiagnosticsRoute()
@@ -0,0 +1,5 @@
1
+ import { createDevRuntimeLogsRoute } from '@open-mercato/shared/lib/dev-runtime/routes'
2
+
3
+ export const dynamic = 'force-dynamic'
4
+
5
+ export const GET = createDevRuntimeLogsRoute()
@@ -0,0 +1,5 @@
1
+ import { createDevRuntimeStatusRoute } from '@open-mercato/shared/lib/dev-runtime/routes'
2
+
3
+ export const dynamic = 'force-dynamic'
4
+
5
+ export const GET = createDevRuntimeStatusRoute()
@@ -1,4 +1,6 @@
1
- jest.mock('@/bootstrap', () => ({
1
+ // The route imports `@/bootstrap-api` and calls `bootstrap()` at module scope,
2
+ // so that exact module has to be mocked or importing the route boots the app.
3
+ jest.mock('@/bootstrap-api', () => ({
2
4
  bootstrap: jest.fn(),
3
5
  }))
4
6
 
@@ -2,6 +2,7 @@
2
2
 
3
3
  import { Button } from '@open-mercato/ui/primitives/button'
4
4
  import { useEffect, useState } from 'react'
5
+ import { reportDevRuntimeError } from '@open-mercato/shared/lib/dev-runtime/report'
5
6
  import { reloadPage } from './global-error-reload'
6
7
 
7
8
  export function isNetworkError(error: unknown): boolean {
@@ -33,6 +34,12 @@ export default function GlobalError({ error, reset }: GlobalErrorProps) {
33
34
  const [isOffline, setIsOffline] = useState<boolean>(false)
34
35
  const networkError = isNetworkError(error)
35
36
 
37
+ // Best-effort dev diagnostic. It is a no-op outside a supervised dev runtime
38
+ // and never blocks or retries, so the fallback below always renders.
39
+ useEffect(() => {
40
+ reportDevRuntimeError({ kind: 'global-error', error })
41
+ }, [error])
42
+
36
43
  useEffect(() => {
37
44
  if (typeof navigator !== 'undefined' && typeof navigator.onLine === 'boolean') {
38
45
  setIsOffline(!navigator.onLine)