peachsim 0.1.527

package/cli/rnx-in-process.ts

@@ -0,0 +1,98 @@
+// running an rnx command inside the calling process instead of spawning the CLI.
+//
+// the parse and the dispatch here are the CLI's own: parseRnxArgs, the command
+// registry behind it, and the same per-command handlers main.ts reaches. what
+// changes is the transport and the boundary. the caller hands in the WsBridge,
+// so one vocabulary and one parser run against three of them: the local ws
+// daemon, a cloud box's commands route, and, inside a box shell in workerd, the
+// Box Durable Object's own command router with no network hop.
+//
+// the boundary is run-rnx.ts: output comes back as a value rather than reaching
+// a terminal, and a command that would have called process.exit throws instead,
+// which is what makes this safe to call in workerd, where process.exit cancels
+// the whole request.
+
+import { parseRnxArgs, TOP_LEVEL_RUNTIME_COMMANDS } from './parse-args'
+import { type RnxRunResult, runRnx } from './run-rnx'
+import type { ParsedBridgeCliArgs, WsBridge } from './ws-bridge'
+
+// the verbs that reach a simulator through the bridge and nothing else. every
+// other registered command needs the machine rnx is installed on: a device to
+// boot, a browser to open, a credential store, the bridge daemon, or the local
+// filesystem. `state` and `reset` sit outside runInspect but take the same
+// bridge, so they belong here too.
+const IN_PROCESS_COMMANDS: ReadonlySet<string> = new Set([
+  ...TOP_LEVEL_RUNTIME_COMMANDS,
+  'state',
+  'reset',
+])
+
+const RUNNABLE = [...IN_PROCESS_COMMANDS].sort().join(', ')
+
+export interface RnxInProcessOptions {
+  /** the command and its arguments, with no node/script prefix. */
+  argv: string[]
+  /**
+   * the transport the command runs against. it takes the parsed bridge args
+   * because the local host builds its bridge out of `--sim`, `--port`, and
+   * `--timeout`, while a box ignores all three and answers on its own socket.
+   */
+  createBridge: (parsed: ParsedBridgeCliArgs) => WsBridge
+}
+
+export async function runRnxInProcess(
+  options: RnxInProcessOptions,
+): Promise<RnxRunResult> {
+  return runRnx(options.argv, async (argv) => {
+    const parsed = parseRnxArgs(argv)
+    for (const warning of parsed.warnings) console.error(warning)
+    const command = parsed.command
+    if (!command || !IN_PROCESS_COMMANDS.has(command)) {
+      const named = command ? `rnx ${command}` : 'rnx'
+      console.error(
+        `  ${named} is not available here; this rnx drives a simulator and has no machine to run on. runs here: ${RUNNABLE}`,
+      )
+      return 1
+    }
+
+    const simTarget = parsed.globalFlags['sim'] ?? parsed.globalFlags['session']
+    const commandArgs =
+      typeof simTarget === 'string'
+        ? ['--sim', simTarget, ...parsed.commandArgs]
+        : parsed.commandArgs
+    if (commandArgs.includes('--then')) {
+      console.error(
+        '  rnx do --then is not available here; a chain runs against a sim connection rather than the bridge. run the actions one at a time.',
+      )
+      return 1
+    }
+
+    const port = parsed.globalFlags['port']
+    const opts = {
+      ...(typeof port === 'number' ? { port } : {}),
+      createBridge: options.createBridge,
+    }
+    if (command === 'state') {
+      const { runState } = await import('./commands/state')
+      return runState(commandArgs, opts)
+    }
+    if (command === 'reset') {
+      const { runReset } = await import('./commands/reset')
+      return runReset(commandArgs, opts)
+    }
+    const { runInspect } = await import('./commands/inspect')
+    await runInspect([command, ...commandArgs], { ...opts, verbose: parsed.verbose })
+    return 0
+  })
+}
+
+// the transport contract and the command's own name, re-exported so a host
+// that only wants to register this entry and supply a bridge (a Box Durable
+// Object, say) has one module to import.
+export { rnxPublicBrand } from '../src/public-brand'
+export type {
+  BridgeClaimResult,
+  BridgeSimInfo,
+  ParsedBridgeCliArgs,
+  WsBridge,
+} from './ws-bridge'

package/cli/run-registry.ts

@@ -0,0 +1,226 @@
+// shared test-run registration for both runners (Maestro / Detox). posts a
+// `sootRun` row to /api/sootsim/test-runs so the org
+// dashboard and PR comments get a pass/fail list with git provenance and a
+// link into the hosted replay (the uploaded preview share).
+//
+// registration policy: a run registers when it produced a hosted share
+// (--preview) or when it runs in CI (github-token / actions env) — local
+// iteration without --preview stays local. registration failures warn and
+// never change the run's exit code; the test result is the playback result.
+
+import { execSync } from 'child_process'
+import { authHeaderValue, resolveCliAuth, type CliAuth } from './auth'
+import type { SootSimFlowTraceStep } from './bridge-flow-runner'
+
+export type RunKind = 'maestro' | 'detox'
+
+export type RunProvenance = {
+  owner: string | null
+  repo: string | null
+  branch: string | null
+  commitSha: string | null
+  githubUsername: string | null
+  pullRequestNumber: number | null
+  pullRequestTitle: string | null
+  githubRunId: string | null
+  source: 'cli' | 'ci'
+}
+
+function gitOutput(command: string): string | null {
+  try {
+    const out = execSync(command, {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 3000,
+      encoding: 'utf8',
+    }).trim()
+    return out || null
+  } catch {
+    return null
+  }
+}
+
+function parsePositiveInt(value: string | undefined): number | null {
+  const trimmed = value?.trim()
+  if (!trimmed || !/^\d+$/.test(trimmed)) return null
+  return Number(trimmed)
+}
+
+// owner/repo from the checkout's github remote, for local runs with no
+// CONTRAST_REPO/GITHUB_REPOSITORY env. runs are repo-scoped on the dashboard
+// (/org/<owner>/<repo>/runs), so a repo-less registration has no home — the
+// server 400s it. handles ssh (git@github.com:o/r.git) and https
+// (https://github.com/o/r(.git)) remote shapes.
+function ownerRepoFromGitRemote(): { owner: string; repo: string } | null {
+  const url = gitOutput('git remote get-url origin')
+  if (!url) return null
+  const match = url.match(/github\.com[/:]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i)
+  if (!match) return null
+  return { owner: match[1], repo: match[2] }
+}
+
+// git provenance for the current run. in GitHub Actions the CONTRAST_*/GITHUB_*
+// env is authoritative (the checkout can be a detached merge ref); locally
+// we ask git itself.
+export function resolveRunProvenance(): RunProvenance {
+  const isActions = process.env.GITHUB_ACTIONS === 'true'
+  const contrastBranch = process.env.CONTRAST_BRANCH?.trim() || null
+  const contrastSha = process.env.CONTRAST_SHA?.trim() || null
+  const pullRequestTitle = process.env.CONTRAST_PR_TITLE?.trim() || null
+  const repoSlug = (
+    process.env.CONTRAST_REPO ||
+    process.env.GITHUB_REPOSITORY ||
+    ''
+  ).trim()
+  const [envOwner, envRepo] = repoSlug.includes('/')
+    ? repoSlug.split('/', 2)
+    : [null, null]
+
+  if (isActions) {
+    // pull_request events: GITHUB_HEAD_REF is the PR head branch and
+    // GITHUB_REF looks like refs/pull/<n>/merge. push events: GITHUB_REF_NAME.
+    const prFromRef = process.env.GITHUB_REF?.match(/^refs\/pull\/(\d+)\//)?.[1]
+    return {
+      owner: envOwner,
+      repo: envRepo,
+      branch:
+        contrastBranch ||
+        process.env.GITHUB_HEAD_REF?.trim() ||
+        process.env.GITHUB_REF_NAME?.trim() ||
+        null,
+      commitSha: contrastSha || process.env.GITHUB_SHA?.trim() || null,
+      githubUsername: process.env.GITHUB_ACTOR?.trim() || null,
+      pullRequestNumber:
+        parsePositiveInt(process.env.CONTRAST_PR_NUMBER) ?? parsePositiveInt(prFromRef),
+      pullRequestTitle,
+      githubRunId: process.env.GITHUB_RUN_ID?.trim() || null,
+      source: 'ci',
+    }
+  }
+
+  const branch = contrastBranch ?? gitOutput('git rev-parse --abbrev-ref HEAD')
+  // env slug wins when present; otherwise infer from the github remote so a
+  // a plain local `rnx maestro test --preview` still lands on its repo's dashboard.
+  const remote = envOwner ? null : ownerRepoFromGitRemote()
+  return {
+    owner: envOwner ?? remote?.owner ?? null,
+    repo: envRepo ?? remote?.repo ?? null,
+    branch: branch === 'HEAD' ? null : branch,
+    commitSha: contrastSha ?? gitOutput('git rev-parse HEAD'),
+    githubUsername: null,
+    pullRequestNumber: parsePositiveInt(process.env.CONTRAST_PR_NUMBER),
+    pullRequestTitle,
+    githubRunId: null,
+    source: 'cli',
+  }
+}
+
+export function stepSummaryFromTrace(steps: SootSimFlowTraceStep[]): {
+  stepCount: number | null
+  failedStepIndex: number | null
+} {
+  if (steps.length === 0) return { stepCount: null, failedStepIndex: null }
+  const failed = steps.find((step) => step.status === 'failure')
+  return {
+    stepCount: steps.length,
+    failedStepIndex: failed ? failed.stepIndex : null,
+  }
+}
+
+// whether this run should register at all — see the policy note at the top.
+export function shouldRegisterRun(args: {
+  uploadedShare: boolean
+  auth: CliAuth | null
+}): boolean {
+  if (!args.auth) return false
+  if (args.uploadedShare) return true
+  return args.auth.kind === 'github' || process.env.GITHUB_ACTIONS === 'true'
+}
+
+export type RegisterRunArgs = {
+  origin: string
+  kind: RunKind
+  status: 'passed' | 'failed'
+  name?: string | null
+  prompt?: string | null
+  summary?: string | null
+  failureMessage?: string | null
+  previewShareId?: string | null
+  // explicit --owner/--repo flags override env/git detection
+  owner?: string | null
+  repo?: string | null
+  durationMs?: number | null
+  flowYamlSizeBytes?: number | null
+  stepCount?: number | null
+  failedStepIndex?: number | null
+  auth?: CliAuth | null
+}
+
+export type RegisteredRun = {
+  id: string
+  previewUrl: string | null
+  traceUrl: string | null
+}
+
+export async function registerRun(args: RegisterRunArgs): Promise<RegisteredRun | null> {
+  const auth = args.auth ?? resolveCliAuth()
+  if (!auth) return null
+  const provenance = resolveRunProvenance()
+  const owner =
+    args.owner ?? (auth.kind === 'github' ? auth.owner : null) ?? provenance.owner
+  const repo = args.repo ?? (auth.kind === 'github' ? auth.repo : null) ?? provenance.repo
+
+  try {
+    const res = await fetch(`${args.origin.replace(/\/$/, '')}/api/sootsim/test-runs`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: authHeaderValue(auth),
+      },
+      body: JSON.stringify({
+        kind: args.kind,
+        source: provenance.source,
+        name: args.name ?? undefined,
+        prompt: args.prompt ?? undefined,
+        summary: args.summary ?? undefined,
+        status: args.status,
+        failureMessage: args.failureMessage ?? undefined,
+        previewShareId: args.previewShareId ?? undefined,
+        owner: owner ?? undefined,
+        repo: repo ?? undefined,
+        branch: provenance.branch ?? undefined,
+        commitSha: provenance.commitSha ?? undefined,
+        githubUsername: provenance.githubUsername ?? undefined,
+        pullRequestNumber: provenance.pullRequestNumber ?? undefined,
+        githubRunId: provenance.githubRunId ?? undefined,
+        stepCount: args.stepCount ?? undefined,
+        failedStepIndex: args.failedStepIndex ?? undefined,
+        durationMs: args.durationMs ?? undefined,
+        flowYamlSizeBytes: args.flowYamlSizeBytes ?? undefined,
+      }),
+    })
+    if (!res.ok) {
+      const text = await res.text().catch(() => '')
+      console.warn(
+        `  warn: run registration failed: /api/sootsim/test-runs ${res.status}${text ? `: ${text.slice(0, 200)}` : ''}`,
+      )
+      return null
+    }
+    const body = (await res.json()) as {
+      run?: { id?: string; traceUrl?: string | null; previewUrl?: string | null }
+    }
+    if (!body.run?.id) {
+      console.warn('  warn: run registration returned no id')
+      return null
+    }
+    return {
+      id: body.run.id,
+      previewUrl: body.run.previewUrl ?? null,
+      traceUrl: body.run.traceUrl ?? null,
+    }
+  } catch (err) {
+    console.warn(
+      `  warn: run registration failed: ${err instanceof Error ? err.message : String(err)}`,
+    )
+    return null
+  }
+}

package/cli/run-rnx-core.ts

@@ -0,0 +1,148 @@
+import {
+  createRnxCommandInvocation,
+  getRnxCommandAvailability,
+  getRnxFirstPositional,
+} from './command-registry'
+import { renderRnxHelp } from './help-core'
+import { resolveHiddenRuntimeAlias } from './hidden-runtime-alias'
+import { parseRnxArgs } from './parse-args'
+import type {
+  CommandArtifact,
+  CommandExecutionResult,
+  CommandWriter,
+  RunRnxCoreOptions,
+  SemanticInvocation,
+} from './command-contract'
+
+interface CapturedCommandWriter {
+  writer: CommandWriter
+  stdout: string[]
+  stderr: string[]
+}
+
+function createCapturedWriter(writer?: CommandWriter): CapturedCommandWriter {
+  const stdout: string[] = []
+  const stderr: string[] = []
+  return {
+    stdout,
+    stderr,
+    writer: {
+      stdout(text) {
+        stdout.push(text)
+        writer?.stdout(text)
+      },
+      stderr(text) {
+        stderr.push(text)
+        writer?.stderr(text)
+      },
+    },
+  }
+}
+
+function result(
+  captured: CapturedCommandWriter,
+  exitCode: number,
+  invocations: SemanticInvocation[] = [],
+  artifacts: CommandArtifact[] = [],
+): CommandExecutionResult {
+  return {
+    exitCode,
+    stdout: captured.stdout.join(''),
+    stderr: captured.stderr.join(''),
+    invocations,
+    artifacts,
+  }
+}
+
+export async function runRnxCore(
+  argv: string[],
+  options: RunRnxCoreOptions,
+): Promise<CommandExecutionResult> {
+  const captured = createCapturedWriter(options.writer)
+  const signal = options.signal ?? new AbortController().signal
+  let parsed = parseRnxArgs(argv)
+  for (const warning of parsed.warnings) captured.writer.stderr(`${warning}\n`)
+
+  if (!parsed.command && parsed.commandArgs.length > 0) {
+    parsed = resolveHiddenRuntimeAlias(parsed)
+  }
+
+  if (parsed.version) {
+    captured.writer.stderr(
+      'rnx --version is unavailable in the browser backend; use the node backend.\n',
+    )
+    return result(captured, 1)
+  }
+
+  if (!parsed.command) {
+    if (parsed.commandArgs.length > 0) {
+      const attempted = getRnxFirstPositional(parsed.commandArgs) ?? parsed.commandArgs[0]
+      captured.writer.stderr(`unknown command: ${attempted}\n`)
+      return result(captured, 1)
+    }
+    captured.writer.stdout(`${renderRnxHelp({ backend: options.backend.kind })}\n`)
+    return result(captured, 0)
+  }
+
+  const command = parsed.command
+  const helpRequested =
+    parsed.help ||
+    parsed.commandArgs.includes('--help') ||
+    parsed.commandArgs.includes('-h')
+  if (helpRequested) {
+    const grouping = new Set(['do', 'get', 'debug', 'wait'])
+    const subVerb = getRnxFirstPositional(parsed.commandArgs)
+    captured.writer.stdout(
+      `${renderRnxHelp({
+        backend: options.backend.kind,
+        command,
+        commandArgs: parsed.commandArgs,
+        prefer: grouping.has(command) && subVerb ? 'verb' : undefined,
+        group: grouping.has(command) ? command : undefined,
+      })}\n`,
+    )
+    return result(captured, 0)
+  }
+
+  const availability = getRnxCommandAvailability(
+    command,
+    parsed.commandArgs,
+    options.backend.kind,
+  )
+  if (!availability.available) {
+    captured.writer.stderr(`${availability.reason ?? `rnx ${command} is unavailable`}\n`)
+    return result(captured, 1)
+  }
+
+  if (signal.aborted) {
+    captured.writer.stderr('rnx: command cancelled\n')
+    return result(captured, 1)
+  }
+
+  const invocation = createRnxCommandInvocation({
+    command,
+    args: parsed.commandArgs,
+    globalFlags: parsed.globalFlags,
+  })
+
+  try {
+    const execution = await options.backend.execute(invocation, {
+      writer: captured.writer,
+      signal,
+    })
+    return result(
+      captured,
+      execution.exitCode,
+      execution.invocations,
+      execution.artifacts,
+    )
+  } catch (error) {
+    const message = signal.aborted
+      ? 'command cancelled'
+      : error instanceof Error
+        ? error.message
+        : String(error)
+    captured.writer.stderr(`rnx: ${message}\n`)
+    return result(captured, 1)
+  }
+}

package/cli/run-rnx.ts

@@ -0,0 +1,137 @@
+// node/workerd compatibility for command modules that still write through
+// process and console. browser-safe commands use run-rnx-core.ts, whose
+// explicit context carries its writer, cancellation signal, semantic
+// invocations, and artifacts without touching ambient process state.
+//
+// two things stand between the command modules and an in-process call, and
+// this module owns both:
+//
+//   output — the modules write to console.* and process.std*.write, ~1,777
+//   sites. they are not rewritten to take a writer. instead the sinks are
+//   resolved from async context, so two commands running concurrently in one
+//   isolate keep their output separate. RAN: a global current-sink instead of
+//   AsyncLocalStorage interleaves them, which is what makes the context
+//   version necessary rather than merely tidy.
+//
+//   exit — a command that calls process.exit ends the host process instead of
+//   returning a code to its caller. `rnxExit` throws instead, and `runRnx`
+//   turns it back into a code at the boundary.
+//
+// AsyncLocalStorage keeps this compatibility module node/workerd only. migrate
+// a command to the explicit core before exposing it through a browser backend.
+
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+export interface RnxRunResult {
+  stdout: string
+  stderr: string
+  exitCode: number
+}
+
+interface RnxSinks {
+  stdout: string[]
+  stderr: string[]
+}
+
+// thrown by `rnxExit` in place of process.exit. every catch that reports an
+// error must re-throw this before reporting, or it turns a deliberate exit
+// into a spurious "command failed" line with the sentinel's own text.
+export class RnxExit extends Error {
+  readonly code: number
+
+  constructor(code: number) {
+    super(`rnx exited with code ${code}`)
+    this.name = 'RnxExit'
+    this.code = code
+  }
+}
+
+const sinks = new AsyncLocalStorage<RnxSinks>()
+
+// stop a command's deliberate exit from being reported as a failure. the
+// guard every reporting catch needs, in one place so the call sites stay one
+// line.
+export function rethrowIfExit(error: unknown): void {
+  if (error instanceof RnxExit) throw error
+}
+
+// the in-process replacement for process.exit. returns `never` exactly as
+// process.exit does, so it substitutes without changing any call site's types.
+export function rnxExit(code: number): never {
+  throw new RnxExit(code)
+}
+
+function write(stream: 'stdout' | 'stderr', text: string): boolean {
+  const current = sinks.getStore()
+  if (!current) return false
+  current[stream].push(text)
+  return true
+}
+
+let installed = false
+
+// replace the process-wide writers once. each resolves its destination from
+// async context, so a call made outside any `runRnx` still reaches the real
+// terminal and the host CLI keeps behaving exactly as it did.
+function installCapture(): void {
+  if (installed) return
+  installed = true
+
+  const realLog = console.log.bind(console)
+  const realError = console.error.bind(console)
+  const realWarn = console.warn.bind(console)
+  const realStdout = process.stdout.write.bind(process.stdout)
+  const realStderr = process.stderr.write.bind(process.stderr)
+
+  const line = (args: unknown[]): string => `${args.map(String).join(' ')}\n`
+
+  console.log = (...args: unknown[]) => {
+    if (!write('stdout', line(args))) realLog(...args)
+  }
+  console.error = (...args: unknown[]) => {
+    if (!write('stderr', line(args))) realError(...args)
+  }
+  console.warn = (...args: unknown[]) => {
+    if (!write('stderr', line(args))) realWarn(...args)
+  }
+  process.stdout.write = (chunk: string | Uint8Array, ...rest: unknown[]) => {
+    if (
+      write('stdout', typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk))
+    ) {
+      return true
+    }
+    return Reflect.apply(realStdout, process.stdout, [chunk, ...rest])
+  }
+  process.stderr.write = (chunk: string | Uint8Array, ...rest: unknown[]) => {
+    if (
+      write('stderr', typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk))
+    ) {
+      return true
+    }
+    return Reflect.apply(realStderr, process.stderr, [chunk, ...rest])
+  }
+}
+
+// run one rnx invocation and return what it wrote plus its exit code, instead
+// of writing to the terminal and ending the process. `argv` is the command and
+// its arguments with no node/script prefix, e.g. ['describe', '--json'].
+export async function runRnx(
+  argv: string[],
+  dispatch: (argv: string[]) => Promise<number>,
+): Promise<RnxRunResult> {
+  installCapture()
+  const current: RnxSinks = { stdout: [], stderr: [] }
+  const exitCode = await sinks.run(current, async () => {
+    try {
+      return await dispatch(argv)
+    } catch (error) {
+      if (error instanceof RnxExit) return error.code
+      throw error
+    }
+  })
+  return {
+    stdout: current.stdout.join(''),
+    stderr: current.stderr.join(''),
+    exitCode,
+  }
+}

package/cli/runtime-notes.ts

@@ -0,0 +1,66 @@
+import { RNX_CHANGELOG_API_URL, RNX_CHANGELOG_URL } from '../src/runtime-delivery'
+import type { ChangelogEntry } from '../../../scripts/changelog/types'
+
+function isChangelogEntry(value: unknown): value is ChangelogEntry {
+  if (!value || typeof value !== 'object') return false
+  const sections = Reflect.get(value, 'sections')
+  return (
+    typeof Reflect.get(value, 'title') === 'string' &&
+    Array.isArray(sections) &&
+    sections.every(
+      (section) =>
+        section &&
+        typeof section === 'object' &&
+        typeof Reflect.get(section, 'title') === 'string' &&
+        Array.isArray(Reflect.get(section, 'items')) &&
+        Reflect.get(section, 'items').every(
+          (item: unknown) =>
+            item &&
+            typeof item === 'object' &&
+            typeof Reflect.get(item, 'summary') === 'string' &&
+            typeof Reflect.get(item, 'hash') === 'string',
+        ),
+    )
+  )
+}
+
+export async function fetchRuntimeReleaseNotes(
+  version: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<ChangelogEntry | null> {
+  try {
+    const url = new URL(RNX_CHANGELOG_API_URL)
+    url.searchParams.set('version', version)
+    const response = await fetchImpl(url, {
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(5000),
+    })
+    if (!response.ok) return null
+    const payload: unknown = await response.json()
+    if (!payload || typeof payload !== 'object') return null
+    const entries = Reflect.get(payload, 'entries')
+    if (!Array.isArray(entries) || !isChangelogEntry(entries[0])) return null
+    return entries[0]
+  } catch {
+    return null
+  }
+}
+
+export function formatRuntimeReleaseNotes(
+  version: string,
+  entry: ChangelogEntry | null,
+): string {
+  const lines = [`what's new in rnx engine v${version}:`]
+  if (!entry || entry.sections.length === 0) {
+    lines.push(`  release notes are not available yet`)
+  } else {
+    for (const section of entry.sections) {
+      lines.push(`  ${section.title}:`)
+      for (const item of section.items) {
+        lines.push(`    • ${item.summary}`)
+      }
+    }
+  }
+  lines.push(`  full changelog: ${RNX_CHANGELOG_URL}`)
+  return lines.join('\n')
+}

package/cli/runtime-summary.ts

@@ -0,0 +1,25 @@
+import { readActiveRuntime, shouldSkipPersistentDaemon } from '../src/home-paths'
+import { resolveBridgeWorld } from './ws-bridge'
+
+export type RuntimeSummary = {
+  primary: string
+  installedRuntime: string | null
+  isDevBridge: boolean
+}
+
+export function getRuntimeSummary(): RuntimeSummary {
+  const active = readActiveRuntime()
+  const dev = shouldSkipPersistentDaemon() ? resolveBridgeWorld() : null
+  if (dev?.source === 'dev-bridge') {
+    return {
+      primary: `engine dev source (:${dev.bridgePort})`,
+      installedRuntime: active ? `installed runtime v${active}` : null,
+      isDevBridge: true,
+    }
+  }
+  return {
+    primary: active ? `runtime v${active}` : 'runtime not installed',
+    installedRuntime: null,
+    isDevBridge: false,
+  }
+}