@livestore/utils-dev 0.4.0-dev.9 → 0.4.0

package/src/node/cmd.ts

@@ -1,80 +1,132 @@
-import { isNotUndefined, shouldNeverHappen } from '@livestore/utils'
-import { Command, type CommandExecutor, Effect, identity, type PlatformError, Schema } from '@livestore/utils/effect'
+import fs from 'node:fs'
+
+import { isNotUndefined } from '@livestore/utils'
+import {
+  Cause,
+  Command,
+  type CommandExecutor,
+  Effect,
+  Fiber,
+  FiberId,
+  FiberRefs,
+  HashMap,
+  identity,
+  List,
+  LogLevel,
+  type PlatformError,
+  Schema,
+  Stream,
+} from '@livestore/utils/effect'
+
+import { applyLoggingToCommand } from './cmd-log.ts'
+import * as FileLogger from './FileLogger.ts'
+import { CurrentWorkingDirectory } from './workspace.ts'
+
+// Branded zero value so we can compare exit codes without touching internals.
+const SUCCESS_EXIT_CODE: CommandExecutor.ExitCode = 0 as CommandExecutor.ExitCode
 
 export const cmd: (
   commandInput: string | (string | undefined)[],
-  options?:
-    | {
-        cwd?: string
-        stderr?: 'inherit' | 'pipe'
-        stdout?: 'inherit' | 'pipe'
-        shell?: boolean
-        env?: Record<string, string | undefined>
-      }
-    | undefined,
-) => Effect.Effect<CommandExecutor.ExitCode, PlatformError.PlatformError | CmdError, CommandExecutor.CommandExecutor> =
-  Effect.fn('cmd')(function* (commandInput, options) {
-    const cwd = options?.cwd ?? process.env.WORKSPACE_ROOT ?? shouldNeverHappen('WORKSPACE_ROOT is not set')
-    const [command, ...args] = Array.isArray(commandInput)
-      ? commandInput.filter(isNotUndefined)
-      : commandInput.split(' ')
+  options?: {
+    stderr?: 'inherit' | 'pipe'
+    stdout?: 'inherit' | 'pipe'
+    shell?: boolean
+    env?: Record<string, string | undefined>
+    /**
+     * When provided, streams command output to terminal AND to a canonical log file (`${logDir}/dev.log`) in this directory.
+     * Also archives the previous run to `${logDir}/archive/dev-<ISO>.log` and keeps only the latest 50 archives.
+     */
+    logDir?: string
+    /** Optional basename for the canonical log file; defaults to 'dev.log' */
+    logFileName?: string
+    /** Optional number of archived logs to retain; defaults to 50 */
+    logRetention?: number
+  },
+) => Effect.Effect<
+  CommandExecutor.ExitCode,
+  PlatformError.PlatformError | CmdError,
+  CommandExecutor.CommandExecutor | CurrentWorkingDirectory
+> = Effect.fn('cmd')(function* (commandInput, options) {
+  const cwd = yield* CurrentWorkingDirectory
 
-    const debugEnvStr = Object.entries(options?.env ?? {})
-      .map(([key, value]) => `${key}='${value}' `)
-      .join('')
-    const subshellStr = options?.shell ? ' (in subshell)' : ''
-    const commandDebugStr = debugEnvStr + [command, ...args].join(' ')
+  const asArray = Array.isArray(commandInput)
+  const parts = asArray === true ? commandInput.filter(isNotUndefined) : undefined
+  const [command, ...args] = asArray === true ? (parts as string[]) : commandInput.split(' ')
 
-    yield* Effect.logDebug(`Running '${commandDebugStr}' in '${cwd}'${subshellStr}`)
-    yield* Effect.annotateCurrentSpan({ 'span.label': commandDebugStr, cwd, command, args })
+  const debugEnvStr = Object.entries(options?.env ?? {})
+    .map(([key, value]) => `${key}='${String(value)}' `)
+    .join('')
 
-    return yield* Command.make(command!, ...args).pipe(
-      // TODO don't forward abort signal to the command
-      Command.stdin('inherit'), // Forward stdin to the command
-      // inherit = Stream stdout to process.stdout, pipe = Stream stdout to process.stderr
-      Command.stdout(options?.stdout ?? 'inherit'),
-      // inherit = Stream stderr to process.stderr, pipe = Stream stderr to process.stdout
-      Command.stderr(options?.stderr ?? 'inherit'),
-      Command.workingDirectory(cwd),
-      options?.shell ? Command.runInShell(true) : identity,
-      Command.env(options?.env ?? {}),
-      Command.exitCode,
-      Effect.tap((exitCode) =>
-        exitCode === 0
-          ? Effect.void
-          : Effect.fail(
-              CmdError.make({
-                command: command!,
-                args,
-                cwd,
-                env: options?.env ?? {},
-                stderr: options?.stderr ?? 'inherit',
-              }),
-            ),
-      ),
-    )
+  const loggingOpts = {
+    ...(options?.logDir !== undefined ? { logDir: options.logDir } : {}),
+    ...(options?.logFileName !== undefined ? { logFileName: options.logFileName } : {}),
+    ...(options?.logRetention !== undefined ? { logRetention: options.logRetention } : {}),
+  } as const
+  const { input: finalInput, subshell: needsShell, logPath } = yield* applyLoggingToCommand(commandInput, loggingOpts)
+
+  const stdoutMode = options?.stdout ?? 'inherit'
+  const stderrMode = options?.stderr ?? 'inherit'
+  const useShell = (options?.shell === true ? true : false) || needsShell
+
+  const commandDebugStr = debugEnvStr + (Array.isArray(finalInput) === true ? finalInput.join(' ') : finalInput)
+  const subshellStr = useShell === true ? ' (in subshell)' : ''
+
+  yield* Effect.logDebug(`Running '${commandDebugStr}' in '${cwd}'${subshellStr}`)
+  yield* Effect.annotateCurrentSpan({
+    'span.label': commandDebugStr,
+    cwd,
+    command,
+    args,
+    logDir: options?.logDir,
   })
 
+  const baseArgs = {
+    commandInput: finalInput,
+    cwd,
+    env: options?.env ?? {},
+    stdoutMode,
+    stderrMode,
+    useShell,
+  } as const
+
+  const exitCode = yield* isNotUndefined(logPath) === true
+    ? Effect.gen(function* () {
+        yield* Effect.sync(() => console.log(`Logging output to ${logPath}`))
+        return yield* runWithLogging({ ...baseArgs, logPath, threadName: commandDebugStr })
+      })
+    : runWithoutLogging(baseArgs)
+
+  if (exitCode !== SUCCESS_EXIT_CODE) {
+    return yield* CmdError.make({
+      command: command!,
+      args,
+      cwd,
+      env: options?.env ?? {},
+      stderr: stderrMode,
+    })
+  }
+
+  return exitCode
+})
+
 export const cmdText: (
   commandInput: string | (string | undefined)[],
   options?: {
-    cwd?: string
     stderr?: 'inherit' | 'pipe'
     runInShell?: boolean
     env?: Record<string, string | undefined>
   },
-) => Effect.Effect<string, PlatformError.PlatformError, CommandExecutor.CommandExecutor> = Effect.fn('cmdText')(
-  function* (commandInput, options) {
-    const cwd = options?.cwd ?? process.env.WORKSPACE_ROOT ?? shouldNeverHappen('WORKSPACE_ROOT is not set')
-    const [command, ...args] = Array.isArray(commandInput)
-      ? commandInput.filter(isNotUndefined)
-      : commandInput.split(' ')
+) => Effect.Effect<string, PlatformError.PlatformError, CommandExecutor.CommandExecutor | CurrentWorkingDirectory> =
+  Effect.fn('cmdText')(function* (commandInput, options) {
+    const cwd = yield* CurrentWorkingDirectory
+    const [command, ...args] =
+      Array.isArray(commandInput) === true ? commandInput.filter(isNotUndefined) : commandInput.split(' ')
     const debugEnvStr = Object.entries(options?.env ?? {})
-      .map(([key, value]) => `${key}='${value}' `)
+      .map(([key, value]) => `${key}='${String(value)}' `)
       .join('')
 
     const commandDebugStr = debugEnvStr + [command, ...args].join(' ')
-    const subshellStr = options?.runInShell ? ' (in subshell)' : ''
+    const subshellStr = options?.runInShell === true ? ' (in subshell)' : ''
 
     yield* Effect.logDebug(`Running '${commandDebugStr}' in '${cwd}'${subshellStr}`)
     yield* Effect.annotateCurrentSpan({ 'span.label': commandDebugStr, command, cwd })
@@ -83,17 +135,283 @@ export const cmdText: (
       // inherit = Stream stderr to process.stderr, pipe = Stream stderr to process.stdout
       Command.stderr(options?.stderr ?? 'inherit'),
       Command.workingDirectory(cwd),
-      options?.runInShell ? Command.runInShell(true) : identity,
+      options?.runInShell === true ? Command.runInShell(true) : identity,
       Command.env(options?.env ?? {}),
       Command.string,
     )
-  },
-)
+  })
 
-export class CmdError extends Schema.TaggedError<CmdError>()('CmdError', {
+export class CmdError extends Schema.TaggedError<CmdError>('~@livestore/utils-dev/CmdError')('CmdError', {
   command: Schema.String,
   args: Schema.Array(Schema.String),
   cwd: Schema.String,
   env: Schema.Record({ key: Schema.String, value: Schema.String.pipe(Schema.UndefinedOr) }),
   stderr: Schema.Literal('inherit', 'pipe'),
 }) {}
+
+type TRunBaseArgs = {
+  readonly commandInput: string | string[]
+  readonly cwd: string
+  readonly env: Record<string, string | undefined>
+  readonly stdoutMode: 'inherit' | 'pipe'
+  readonly stderrMode: 'inherit' | 'pipe'
+  readonly useShell: boolean
+}
+
+const runWithoutLogging = ({ commandInput, cwd, env, stdoutMode, stderrMode, useShell }: TRunBaseArgs) =>
+  buildCommand(commandInput, useShell).pipe(
+    Command.stdin('inherit'),
+    Command.stdout(stdoutMode),
+    Command.stderr(stderrMode),
+    Command.workingDirectory(cwd),
+    useShell === true ? Command.runInShell(true) : identity,
+    Command.env(env),
+    Command.exitCode,
+  )
+
+type TRunWithLoggingArgs = TRunBaseArgs & {
+  readonly logPath: string
+  readonly threadName: string
+}
+
+const runWithLogging = ({
+  commandInput,
+  cwd,
+  env,
+  stdoutMode,
+  stderrMode,
+  useShell,
+  logPath,
+  threadName,
+}: TRunWithLoggingArgs) =>
+  // When logging is enabled we have to replace the `2>&1 | tee` pipeline the
+  // shell used to give us. We now pipe both streams through Effect so we can
+  // mirror to the terminal (only when requested) and append formatted entries
+  // into the canonical log ourselves.
+  Effect.scoped(
+    Effect.gen(function* () {
+      const envWithColor = env.FORCE_COLOR === undefined ? { ...env, FORCE_COLOR: '1' } : env
+
+      const logFile = yield* Effect.acquireRelease(
+        Effect.sync(() => fs.openSync(logPath, 'a', 0o666)),
+        (fd) => Effect.sync(() => fs.closeSync(fd)),
+      )
+
+      const prettyLogger = FileLogger.prettyLoggerTty({
+        colors: true,
+        stderr: false,
+        formatDate: (date) => `${FileLogger.defaultDateFormat(date)} ${threadName}`,
+      })
+
+      const appendLog = ({ channel, content }: { channel: 'stdout' | 'stderr'; content: string }) =>
+        Effect.sync(() => {
+          const formatted = prettyLogger.log({
+            fiberId: FiberId.none,
+            logLevel: channel === 'stdout' ? LogLevel.Info : LogLevel.Warning,
+            message: [`[${channel}]${content.length > 0 ? ` ${content}` : ''}`],
+            cause: Cause.empty,
+            context: FiberRefs.empty(),
+            spans: List.empty(),
+            annotations: HashMap.empty(),
+            date: new Date(),
+          })
+          fs.writeSync(logFile, formatted)
+        })
+
+      const command = buildCommand(commandInput, useShell).pipe(
+        Command.stdin('inherit'),
+        Command.stdout('pipe'),
+        Command.stderr('pipe'),
+        Command.workingDirectory(cwd),
+        useShell === true ? Command.runInShell(true) : identity,
+        Command.env(envWithColor),
+      )
+
+      // Acquire/start the command and make sure we kill it on interruption.
+      const runningProcess = yield* Effect.acquireRelease(command.pipe(Command.start), (proc) =>
+        proc.isRunning.pipe(
+          Effect.flatMap((running) =>
+            running === true ? proc.kill().pipe(Effect.catchAll(() => Effect.void)) : Effect.void,
+          ),
+          Effect.ignore,
+        ),
+      )
+
+      const stdoutHandler = makeStreamHandler({
+        channel: 'stdout',
+        ...(stdoutMode === 'inherit' ? { mirrorTarget: process.stdout } : {}),
+        appendLog,
+      })
+      const stderrHandler = makeStreamHandler({
+        channel: 'stderr',
+        ...(stderrMode === 'inherit' ? { mirrorTarget: process.stderr } : {}),
+        appendLog,
+      })
+
+      const stdoutFiber = yield* runningProcess.stdout.pipe(
+        Stream.decodeText('utf8'),
+        Stream.runForEach((chunk) => stdoutHandler.onChunk(chunk)),
+        Effect.forkScoped,
+      )
+
+      const stderrFiber = yield* runningProcess.stderr.pipe(
+        Stream.decodeText('utf8'),
+        Stream.runForEach((chunk) => stderrHandler.onChunk(chunk)),
+        Effect.forkScoped,
+      )
+
+      // Dump any buffered data and finish both stream fibers before we return.
+      const flushOutputs = Effect.gen(function* () {
+        const stillRunning = yield* runningProcess.isRunning.pipe(Effect.catchAll(() => Effect.succeed(false)))
+        if (stillRunning === true) {
+          yield* Effect.ignore(runningProcess.kill())
+        }
+        yield* Effect.ignore(Fiber.join(stdoutFiber))
+        yield* Effect.ignore(Fiber.join(stderrFiber))
+        yield* stdoutHandler.flush()
+        yield* stderrHandler.flush()
+      })
+
+      const exitCode = yield* runningProcess.exitCode.pipe(Effect.ensuring(flushOutputs))
+
+      return exitCode
+    }),
+  )
+
+const buildCommand = (input: string | string[], useShell: boolean) => {
+  if (Array.isArray(input) === true) {
+    const [c, ...a] = input
+    return Command.make(c!, ...a)
+  }
+
+  if (useShell === true) {
+    return Command.make(input)
+  }
+
+  const [c, ...a] = input.split(' ')
+  return Command.make(c!, ...a)
+}
+
+type TLineTerminator = 'newline' | 'carriage-return' | 'none'
+
+type TStreamHandler = {
+  readonly onChunk: (chunk: string) => Effect.Effect<void>
+  readonly flush: () => Effect.Effect<void>
+}
+
+const makeStreamHandler = ({
+  channel,
+  mirrorTarget,
+  appendLog,
+}: {
+  readonly channel: 'stdout' | 'stderr'
+  readonly mirrorTarget?: NodeJS.WriteStream
+  readonly appendLog: (args: { channel: 'stdout' | 'stderr'; content: string }) => Effect.Effect<void>
+}): TStreamHandler => {
+  let buffer = ''
+
+  // Effect's FileLogger expects line-oriented messages, but the subprocess
+  // gives us arbitrary UTF-8 chunks. We keep a tiny line splitter here so the
+  // log and console stay readable (and consistent with the previous `tee`
+  // behaviour).
+  const emit = (content: string, terminator: TLineTerminator) =>
+    emitSegment({
+      channel,
+      content,
+      terminator,
+      ...(mirrorTarget !== undefined ? { mirrorTarget } : {}),
+      appendLog,
+    })
+
+  const consumeBuffer = (): Effect.Effect<void> => {
+    if (buffer.length === 0) return Effect.void
+
+    const lastChar = buffer[buffer.length - 1]
+    if (lastChar === '\r') {
+      const line = buffer.slice(0, -1)
+      buffer = ''
+      return emit(line, 'carriage-return')
+    }
+
+    const line = buffer
+    buffer = ''
+    return line.length === 0 ? Effect.void : emit(line, 'none')
+  }
+
+  return {
+    onChunk: (chunk) =>
+      Effect.gen(function* () {
+        buffer += chunk
+        while (buffer.length > 0) {
+          const newlineIndex = buffer.indexOf('\n')
+          const carriageIndex = buffer.indexOf('\r')
+
+          if (newlineIndex === -1 && carriageIndex === -1) {
+            break
+          }
+
+          let index: number
+          let terminator: TLineTerminator
+          let skip = 1
+
+          if (carriageIndex !== -1 && (newlineIndex === -1 || carriageIndex < newlineIndex)) {
+            index = carriageIndex
+            if (carriageIndex + 1 < buffer.length && buffer[carriageIndex + 1] === '\n') {
+              skip = 2
+              terminator = 'newline'
+            } else {
+              terminator = 'carriage-return'
+            }
+          } else {
+            index = newlineIndex!
+            terminator = 'newline'
+          }
+
+          const line = buffer.slice(0, index)
+          buffer = buffer.slice(index + skip)
+          yield* emit(line, terminator)
+        }
+      }),
+    flush: () => consumeBuffer(),
+  }
+}
+
+const emitSegment = ({
+  channel,
+  content,
+  terminator,
+  mirrorTarget,
+  appendLog,
+}: {
+  readonly channel: 'stdout' | 'stderr'
+  readonly content: string
+  readonly terminator: TLineTerminator
+  readonly mirrorTarget?: NodeJS.WriteStream
+  readonly appendLog: (args: { channel: 'stdout' | 'stderr'; content: string }) => Effect.Effect<void>
+}) =>
+  Effect.gen(function* () {
+    if (mirrorTarget !== undefined) {
+      yield* Effect.sync(() => mirrorSegment(mirrorTarget, content, terminator))
+    }
+
+    const contentForLog = terminator === 'carriage-return' ? `${content}\r` : content
+
+    yield* appendLog({ channel, content: contentForLog })
+  })
+
+const mirrorSegment = (target: NodeJS.WriteStream, content: string, terminator: TLineTerminator) => {
+  switch (terminator) {
+    case 'newline': {
+      target.write(`${content}\n`)
+      break
+    }
+    case 'carriage-return': {
+      target.write(`${content}\r`)
+      break
+    }
+    case 'none': {
+      target.write(content)
+      break
+    }
+  }
+}

package/src/node/mod.ts

@@ -1,16 +1,17 @@
 import { performance } from 'node:perf_hooks'
 
 import * as OtelNodeSdk from '@effect/opentelemetry/NodeSdk'
-import { IS_BUN, isNonEmptyString } from '@livestore/utils'
-import type { Tracer } from '@livestore/utils/effect'
-import { Config, Effect, FiberRef, Layer, LogLevel, OtelTracer } from '@livestore/utils/effect'
-import { OtelLiveDummy } from '@livestore/utils/node'
 import * as otel from '@opentelemetry/api'
 import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http'
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
 import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics'
 import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base'
 
+import { IS_BUN, isNonEmptyString } from '@livestore/utils'
+import type { Tracer } from '@livestore/utils/effect'
+import { Config, Effect, FiberRef, Layer, LogLevel, OtelTracer, Schema } from '@livestore/utils/effect'
+import { OtelLiveDummy } from '@livestore/utils/node'
+
 export { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http'
 export { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
 export * from './cmd.ts'
@@ -24,6 +25,7 @@ export {
   startDockerComposeServicesScoped,
 } from './DockerComposeService/DockerComposeService.ts'
 export * as FileLogger from './FileLogger.ts'
+export * from './workspace.ts'
 
 export const OtelLiveHttp = ({
   serviceName,
@@ -39,16 +41,16 @@ export const OtelLiveHttp = ({
   rootSpanAttributes?: Record<string, unknown>
   skipLogUrl?: boolean
   traceNodeBootstrap?: boolean
-} = {}): Layer.Layer<OtelTracer.OtelTracer | Tracer.ParentSpan, never, never> =>
+} = {}): Layer.Layer<OtelTracer.OtelTracer | Tracer.ParentSpan> =>
   Effect.gen(function* () {
     const configRes = yield* Config.all({
       exporterUrl: Config.string('OTEL_EXPORTER_OTLP_ENDPOINT').pipe(
         Config.validate({ message: 'OTEL_EXPORTER_OTLP_ENDPOINT must be set', validation: isNonEmptyString }),
       ),
-      serviceName: serviceName
+      serviceName: serviceName !== undefined
         ? Config.succeed(serviceName)
         : Config.string('OTEL_SERVICE_NAME').pipe(Config.withDefault('livestore-utils-dev')),
-      rootSpanName: rootSpanName
+      rootSpanName: rootSpanName !== undefined
         ? Config.succeed(rootSpanName)
         : Config.string('OTEL_ROOT_SPAN_NAME').pipe(Config.withDefault('RootSpan')),
     }).pipe(Effect.option)
@@ -90,24 +92,22 @@ export const OtelLiveHttp = ({
 
     const RootSpanLive = Layer.span(config.rootSpanName, {
       attributes: { config, ...rootSpanAttributes },
-      onEnd: skipLogUrl ? undefined : (span: any) => logTraceUiUrlForSpan()(span.span),
+      onEnd: skipLogUrl === true ? undefined : (span: any) => logTraceUiUrlForSpan()(span.span),
       parent: parentSpan,
     })
 
     const layer = yield* Layer.memoize(RootSpanLive.pipe(Layer.provideMerge(OtelLive)))
 
-    if (traceNodeBootstrap) {
+    if (traceNodeBootstrap === true && IS_BUN === false) {
       /**
        * Create a span representing the Node.js bootstrap duration.
+       * Note: Skipped in Bun since performance.nodeTiming is not properly supported.
        */
       yield* Effect.gen(function* () {
         const tracer = yield* OtelTracer.OtelTracer
         const currentSpan = yield* OtelTracer.currentOtelSpan
 
-        const nodeTiming = performance.nodeTiming
-
-        // TODO get rid of this workaround for Bun once Bun properly supports performance.nodeTiming
-        const startTime = IS_BUN ? nodeTiming.startTime : performance.timeOrigin + nodeTiming.nodeStart
+        const { nodeTiming, endAbs, durationAttr } = computeBootstrapTiming()
 
         const bootSpan = tracer.startSpan(
           'node-bootstrap',
@@ -118,13 +118,13 @@ export const OtelLiveHttp = ({
               'node.timing.environment': nodeTiming.environment,
               'node.timing.bootstrapComplete': nodeTiming.bootstrapComplete,
               'node.timing.loopStart': nodeTiming.loopStart,
-              'node.timing.duration': nodeTiming.duration,
+              'node.timing.duration': durationAttr,
             },
           },
           otel.trace.setSpanContext(otel.context.active(), currentSpan.spanContext()),
         )
 
-        bootSpan.end(startTime + nodeTiming.duration)
+        bootSpan.end(endAbs)
       }).pipe(Effect.provide(layer), Effect.orDie)
     }
 
@@ -137,7 +137,7 @@ export const logTraceUiUrlForSpan = (printMsg?: (url: string) => string) => (spa
       if (url === undefined) {
         return Effect.logWarning('No tracing backend url found')
       } else {
-        if (printMsg) {
+        if (printMsg !== undefined) {
           return Effect.log(printMsg(url))
         } else {
           return Effect.log(`Trace URL: ${url}`)
@@ -156,15 +156,63 @@ export const getTracingBackendUrl = (span: otel.Span) =>
     // Grafana + Tempo
 
     const grafanaEndpoint = endpoint.value
+    const left = yield* Schema.encode(Schema.parseJson())({
+      datasource: 'tempo',
+      queries: [{ query: traceId, queryType: 'traceql', refId: 'A' }],
+      range: { from: 'now-1h', to: 'now' },
+    }).pipe(Effect.orDie)
     const searchParams = new URLSearchParams({
       orgId: '1',
-      left: JSON.stringify({
-        datasource: 'tempo',
-        queries: [{ query: traceId, queryType: 'traceql', refId: 'A' }],
-        range: { from: 'now-1h', to: 'now' },
-      }),
+      left,
     })
 
     // TODO make dynamic via env var
     return `${grafanaEndpoint}/explore?${searchParams.toString()}`
   })
+
+/**
+ * Compute absolute start/end timestamps for the Node.js bootstrap span in a
+ * way that works in both Node and Bun.
+ *
+ * Context: Bun's perf_hooks PerformanceNodeTiming currently throws when
+ * accessing standard PerformanceEntry getters like `startTime` and
+ * `duration`, and some fields differ in semantics (e.g. `nodeStart` appears
+ * as an epoch timestamp rather than an offset). See:
+ * https://github.com/oven-sh/bun/issues/23041
+ *
+ * We therefore avoid the problematic getters and derive absolute timestamps
+ * using fields that exist in both runtimes.
+ *
+ * TODO: Simplify to a single, non-branching computation once the Bun issue
+ * above is fixed and Bun matches Node's semantics for PerformanceNodeTiming.
+ */
+const computeBootstrapTiming = () => {
+  const nodeTiming = performance.nodeTiming
+
+  // Absolute start time in ms since epoch.
+  const startAbs = IS_BUN === true
+    ? typeof nodeTiming.nodeStart === 'number'
+      ? nodeTiming.nodeStart
+      : performance.timeOrigin
+    : performance.timeOrigin + nodeTiming.nodeStart
+
+  // Absolute end time.
+  const endAbs = IS_BUN === true
+    ? (() => {
+        const { loopStart, bootstrapComplete } = nodeTiming
+        if (typeof loopStart === 'number' && loopStart > 0) return startAbs + loopStart
+        if (typeof bootstrapComplete === 'number' && bootstrapComplete >= startAbs) return bootstrapComplete
+        return startAbs + 1
+      })()
+    : startAbs + nodeTiming.duration
+
+  // Duration attribute value for the span.
+  const durationAttr = IS_BUN === true
+    ? (() => {
+        const { loopStart } = nodeTiming
+        return typeof loopStart === 'number' && loopStart > 0 ? loopStart : 0
+      })()
+    : nodeTiming.duration
+
+  return { nodeTiming, startAbs, endAbs, durationAttr } as const
+}