orca/src/shared/execution-host-registry.ts

import type { RuntimeEnvironmentStatus } from './runtime-host-status'
import {
  LOCAL_EXECUTION_HOST_ID,
  getLocalExecutionHostLabel,
  getRepoExecutionHostId,
  getSettingsFocusedExecutionHostId,
  getSshTargetIdForExecutionHost,
  isRuntimeOwnedSshTargetId,
  normalizeHostPart,
  parseExecutionHostId,
  toRuntimeExecutionHostId,
  toSshExecutionHostId,
  type ExecutionHostId,
  type ExecutionHostKind
} from './execution-host'
import { evaluateRuntimeCompat, type RuntimeCompatVerdict } from './protocol-compat'
import { MIN_COMPATIBLE_RUNTIME_SERVER_VERSION, RUNTIME_PROTOCOL_VERSION } from './protocol-version'
import type { RuntimeStatus } from './runtime-types'
import type { SshConnectionState, SshConnectionStatus } from './ssh-types'
import type { RuntimeEnvironmentSource } from './runtime-environments'
import type { GlobalSettings } from './global-settings-types'
import type { Repo } from './repo-types'
import {
  annotateManagedOrcadExecutionHosts,
  type ManagedOrcadDeploymentSummary
} from './managed-orcad-execution-host'
import { getSshConnectionHealth, type ExecutionHostHealth } from './execution-host-health'

export type { ExecutionHostHealth } from './execution-host-health'

export type ExecutionHostRegistryEntry = {
  id: ExecutionHostId
  kind: ExecutionHostKind
  label: string
  detail: string
  health: ExecutionHostHealth
  connectionStatus?: SshConnectionStatus
  compatibility?: RuntimeCompatVerdict
  capabilities?: readonly string[]
  appVersion?: string | null
  protocolVersion?: number | null
  minCompatibleClientVersion?: number | null
  platform?: NodeJS.Platform | null
  remoteControlState?: RuntimeStatus['remoteControl']
  source?: RuntimeEnvironmentSource
  /** See managed-orcad-execution-host: pairs an SSH host with its managed server. */
  aliasHostIds?: readonly ExecutionHostId[]
  mergedIntoHostId?: ExecutionHostId
}

type RuntimeEnvironmentSummary = {
  id: string
  name?: string | null
  source?: RuntimeEnvironmentSource
  orcadDeployment?: ManagedOrcadDeploymentSummary | null
}

type RuntimeStatusByEnvironmentId = ReadonlyMap<string, RuntimeEnvironmentStatus>

export type ExecutionHostSource = 'configured-only' | 'include-references'

function runtimeCompatibility(
  status: RuntimeStatus | null | undefined
): RuntimeCompatVerdict | null {
  if (!status) {
    return null
  }
  return evaluateRuntimeCompat({
    clientProtocolVersion: RUNTIME_PROTOCOL_VERSION,
    minCompatibleServerProtocolVersion: MIN_COMPATIBLE_RUNTIME_SERVER_VERSION,
    serverProtocolVersion: status.runtimeProtocolVersion ?? status.protocolVersion,
    serverMinCompatibleClientProtocolVersion:
      status.minCompatibleRuntimeClientVersion ?? status.minCompatibleMobileVersion
  })
}

function runtimeHealth(
  status: RuntimeStatus | null | undefined,
  compatibility: RuntimeCompatVerdict | null,
  remoteControl: RuntimeStatus['remoteControl'] | null | undefined
): ExecutionHostHealth {
  // Why: with no live status we have no evidence the Orca server is reachable,
  // unless a ready shared-control socket already proved the transport is up.
  if (!status) {
    return remoteControl?.state === 'ready' ? 'available' : 'disconnected'
  }
  if (!compatibility) {
    return 'available'
  }
  return compatibility.kind === 'blocked' ? 'blocked' : 'available'
}

function runtimeControlHealth(
  remoteControl: RuntimeStatus['remoteControl'] | null | undefined
): ExecutionHostHealth | null {
  switch (remoteControl?.state) {
    case 'awaiting_authenticated':
    case 'awaiting_ready':
    case 'reconnecting':
      return 'connecting'
    case 'closed':
      return remoteControl.lastError ? 'error' : 'disconnected'
    case 'ready':
      return null
    case undefined:
      return null
  }
}

function setHost(
  hosts: Map<ExecutionHostId, ExecutionHostRegistryEntry>,
  entry: ExecutionHostRegistryEntry
): void {
  const existing = hosts.get(entry.id)
  if (!existing) {
    hosts.set(entry.id, entry)
    return
  }
  if (existing.health !== 'disconnected') {
    return
  }
  // Why: a later status-bearing registration may upgrade health, but the first
  // (named) registration is authoritative for the label — runtime envs are
  // seeded with a friendly name before the id-labeled status/focus/repo
  // fallbacks run, so keep the existing label on a health-only upgrade.
  hosts.set(entry.id, { ...entry, label: existing.label, source: existing.source ?? entry.source })
}

function addRuntimeHost(
  hosts: Map<ExecutionHostId, ExecutionHostRegistryEntry>,
  environmentId: string,
  label: string,
  source: RuntimeEnvironmentSource | undefined,
  statusByEnvironmentId: RuntimeStatusByEnvironmentId | undefined
): void {
  const hostId = toRuntimeExecutionHostId(environmentId)
  const runtimeStatus = statusByEnvironmentId?.get(environmentId)
  const status = runtimeStatus?.status
  const snapshot = runtimeStatus?.snapshot
  const metadata = status ?? snapshot?.status
  const compatibility = runtimeCompatibility(metadata)
  const remoteControl = runtimeStatus?.remoteControl ?? status?.remoteControl
  // Why: the status owner withdraws `verified` whenever a ready socket drops, so a verified
  // answer proves the host reachable while shared control is still connecting (#10704).
  const reachable =
    snapshot?.transport === 'ready'
      ? snapshot.verification !== 'checking'
      : snapshot?.verification === 'verified' && snapshot.transport !== 'disconnected'
  const controlHealth = snapshot?.retired
    ? 'disconnected'
    : snapshot?.verification === 'blocked'
      ? 'blocked'
      : reachable
        ? compatibility?.kind === 'blocked'
          ? 'blocked'
          : 'available'
        : !runtimeStatus ||
            snapshot?.verification === 'checking' ||
            snapshot?.transport === 'disconnected' ||
            snapshot?.transport === 'connecting'
          ? 'connecting'
          : runtimeControlHealth(remoteControl)
  setHost(hosts, {
    id: hostId,
    kind: 'runtime',
    label,
    detail: 'Orca server',
    health: controlHealth ?? runtimeHealth(status, compatibility, remoteControl),
    compatibility: compatibility ?? undefined,
    capabilities: metadata?.capabilities,
    appVersion: runtimeStatus?.appVersion ?? metadata?.appVersion ?? null,
    protocolVersion: metadata?.runtimeProtocolVersion ?? metadata?.protocolVersion ?? null,
    minCompatibleClientVersion:
      metadata?.minCompatibleRuntimeClientVersion ?? metadata?.minCompatibleMobileVersion ?? null,
    platform: metadata?.hostPlatform ?? null,
    remoteControlState: remoteControl ?? null,
    ...(source ? { source } : {})
  })
}

export function buildExecutionHostRegistry(args: {
  repos: readonly Pick<Repo, 'connectionId' | 'executionHostId'>[]
  settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
  hostSource?: ExecutionHostSource
  sshTargetLabels?: ReadonlyMap<string, string>
  sshConnectionStates?: ReadonlyMap<string, SshConnectionState>
  runtimeEnvironments?: readonly RuntimeEnvironmentSummary[]
  runtimeStatusByEnvironmentId?: RuntimeStatusByEnvironmentId
  // Why: user-chosen per-host display labels override the derived label so a
  // rename in the host menu/settings shows everywhere the registry feeds.
  hostLabelOverrides?: ReadonlyMap<ExecutionHostId, string>
}): ExecutionHostRegistryEntry[] {
  const hosts = new Map<ExecutionHostId, ExecutionHostRegistryEntry>()
  hosts.set(LOCAL_EXECUTION_HOST_ID, {
    id: LOCAL_EXECUTION_HOST_ID,
    kind: 'local',
    label: getLocalExecutionHostLabel(),
    detail: 'This computer',
    health: 'local'
  })

  for (const environment of args.runtimeEnvironments ?? []) {
    const environmentId = normalizeHostPart(environment.id)
    if (!environmentId) {
      continue
    }
    addRuntimeHost(
      hosts,
      environmentId,
      normalizeHostPart(environment.name) ?? environmentId,
      environment.source,
      args.runtimeStatusByEnvironmentId
    )
  }
  for (const environmentId of args.runtimeStatusByEnvironmentId?.keys() ?? []) {
    addRuntimeHost(
      hosts,
      environmentId,
      environmentId,
      undefined,
      args.runtimeStatusByEnvironmentId
    )
  }

  const focusedHost = getSettingsFocusedExecutionHostId(args.settings)
  const parsedFocusedHost = parseExecutionHostId(focusedHost)
  if (parsedFocusedHost?.kind === 'runtime' && args.hostSource !== 'configured-only') {
    addRuntimeHost(
      hosts,
      parsedFocusedHost.environmentId,
      parsedFocusedHost.environmentId,
      undefined,
      args.runtimeStatusByEnvironmentId
    )
  }

  const sshTargetIds = new Set<string>()
  if (args.hostSource !== 'configured-only') {
    for (const repo of args.repos) {
      const parsedHost = parseExecutionHostId(repo.executionHostId)
      if (parsedHost?.kind === 'runtime') {
        addRuntimeHost(
          hosts,
          parsedHost.environmentId,
          parsedHost.environmentId,
          undefined,
          args.runtimeStatusByEnvironmentId
        )
      }
      // Why: a VM-backed repo's executionHostId is `ssh:runtime-ssh-<id>`. Runtime-owned
      // targets are hidden, so they must not become visible SSH run-target hosts here.
      if (parsedHost?.kind === 'ssh' && !isRuntimeOwnedSshTargetId(parsedHost.targetId)) {
        sshTargetIds.add(parsedHost.targetId)
      }
    }
  }
  for (const targetId of args.sshTargetLabels?.keys() ?? []) {
    const normalized = normalizeHostPart(targetId)
    if (normalized && !isRuntimeOwnedSshTargetId(normalized)) {
      sshTargetIds.add(normalized)
    }
  }
  if (args.hostSource !== 'configured-only') {
    for (const repo of args.repos) {
      // Why the host, not `connectionId`: a paired-server repo's `connectionId` is the server's
      // own SSH target, which this client cannot dial.
      const targetId = getSshTargetIdForExecutionHost(getRepoExecutionHostId(repo))
      if (targetId && !isRuntimeOwnedSshTargetId(targetId)) {
        sshTargetIds.add(targetId)
      }
    }
  }

  for (const targetId of sshTargetIds) {
    const state = args.sshConnectionStates?.get(targetId)
    setHost(hosts, {
      id: toSshExecutionHostId(targetId),
      kind: 'ssh',
      label: args.sshTargetLabels?.get(targetId) || targetId,
      detail: 'SSH',
      health: getSshConnectionHealth(state?.status),
      connectionStatus: state?.status
    })
  }

  annotateManagedOrcadExecutionHosts({
    hosts,
    runtimeEnvironments: args.runtimeEnvironments ?? [],
    sshConnectionStates: args.sshConnectionStates
  })

  const overrides = args.hostLabelOverrides
  if (!overrides || overrides.size === 0) {
    return [...hosts.values()]
  }
  return [...hosts.values()].map((host) => {
    // Why the alias fallback: a rename saved on the merged-away id still names the merged row.
    const label =
      overrides.get(host.id) ??
      host.aliasHostIds?.map((aliasHostId) => overrides.get(aliasHostId)).find(Boolean)
    return label ? { ...host, label } : host
  })
}