Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

35.4 KB
Raw Blame
import type { Connection, ConnectionAgentIdentity } from '@/api/connections';
import type { ConnectionType } from '@/api/connections';
import type {
  ConnectionFleetAdapterHealth,
  ConnectionFleetCommandPolicy,
  ConnectionFleetConfigDrift,
  ConnectionFleetCredentialHealth,
  ConnectionFleetEnrollmentState,
  ConnectionFleetGovernance,
  ConnectionFleetLivenessState,
  ConnectionFleetRolloutState,
  ConnectionFleetUpdateStatus,
  ConnectionFleetVersionDrift,
} from '@/api/connections';
import { getAgentHostProfileFamily } from '@/utils/platformSupportManifest';
import { AGENT_WAITING_FOR_FIRST_REPORT_LABEL } from '@/utils/agentResources';
import {
  buildDockerPath,
  buildKubernetesPath,
  buildProxmoxPath,
  buildTrueNASPath,
  buildVmwarePath,
} from '@/routing/resourceLinks';

export const lastActivityTextFromLastSeen = (lastSeen?: string | null): string => {
  if (!lastSeen) return 'No activity yet';
  const ts = Date.parse(lastSeen);
  if (Number.isNaN(ts)) return 'Unknown';
  const diff = Math.max(0, Date.now() - ts);
  const sec = Math.floor(diff / 1000);
  if (sec < 60) return `${sec}s ago`;
  const min = Math.floor(sec / 60);
  if (min < 60) return `${min}m ago`;
  const hr = Math.floor(min / 60);
  if (hr < 24) return `${hr}h ago`;
  const days = Math.floor(hr / 24);
  return `${days}d ago`;
};

export const connectionLastActivityText = (connection: Connection): string =>
  lastActivityTextFromLastSeen(connection.lastSeen);

type ConnectionAgentIdentityPresentation = ConnectionAgentIdentity & {
  hostProfile?: string | null;
};

const prettifyPlatform = (platform?: string | null): string | null => {
  const normalized = platform?.trim().toLowerCase();
  if (!normalized) return null;
  switch (normalized) {
    case 'linux':
      return 'Linux';
    case 'windows':
      return 'Windows';
    case 'darwin':
    case 'macos':
      return 'macOS';
    case 'freebsd':
      return 'FreeBSD';
    default:
      return platform?.trim() ?? null;
  }
};

const connectionAgentHostProfileLabel = (
  identity?: ConnectionAgentIdentityPresentation | null,
): string | null => {
  const hostProfile = identity?.hostProfile?.trim();
  if (hostProfile) {
    return getAgentHostProfileFamily(hostProfile) ?? prettifyPlatform(hostProfile);
  }
  // Prefer osName over platform: osName carries the specific platform identity
  // ("Proxmox VE", "Unraid", "TrueNAS SCALE") while platform is the broader OS
  // family ("debian", "linux") that loses that identity on display.
  const osName = identity?.osName?.trim();
  const platform = identity?.platform?.trim();
  return prettifyPlatform(osName || platform);
};

const isIPv4Literal = (value: string): boolean => /^\d{1,3}(?:\.\d{1,3}){3}$/.test(value);

const firstDistinctAgentIPv4Alias = (connection: Connection): string | null => {
  const excluded = new Set(
    [
      connection.name,
      connection.address,
      connection.agentIdentity?.hostname,
      connection.agentIdentity?.reportIp,
    ]
      .map((value) => value?.trim().toLowerCase())
      .filter((value): value is string => Boolean(value)),
  );

  for (const candidate of connection.hostAliases ?? []) {
    const trimmed = candidate.trim();
    if (!trimmed || !isIPv4Literal(trimmed)) continue;
    if (excluded.has(trimmed.toLowerCase())) continue;
    return trimmed;
  }
  return null;
};

export const connectionAgentIdentitySummary = (connection: Connection): string | null => {
  const hostProfile = connectionAgentHostProfileLabel(connection.agentIdentity);
  const osName = connection.agentIdentity?.osName?.trim();
  const osVersion = connection.agentIdentity?.osVersion?.trim();
  if (hostProfile && osVersion) return `${hostProfile} ${osVersion}`;
  if (osName && osVersion) return `${osName} ${osVersion}`;
  if (osName) return osName;
  return hostProfile;
};

export const connectionAgentEndpointDisplay = (connection: Connection): string | null => {
  const normalizedName = connection.name.trim().toLowerCase();
  const reportIp = connection.agentIdentity?.reportIp?.trim();
  if (reportIp) return reportIp;

  const aliasIPv4 = firstDistinctAgentIPv4Alias(connection);
  if (aliasIPv4) return aliasIPv4;

  const hostname = connection.agentIdentity?.hostname?.trim();
  if (hostname && hostname.toLowerCase() !== normalizedName) {
    return hostname;
  }

  const address = connection.address?.trim();
  if (!address) return null;
  return address.toLowerCase() !== normalizedName ? address : null;
};

export interface ConnectionAgentVersionPresentation {
  badgeClassName: string;
  badgeLabel: string;
  detail: string;
  title: string;
}

export const connectionAgentVersionPresentation = (
  connection: Connection,
): ConnectionAgentVersionPresentation | null => {
  const currentVersion = connection.agentVersion?.trim() ?? '';
  const expectedVersion = connection.expectedAgentVersion?.trim() ?? '';

  if (connection.agentUpdateAvailable && currentVersion && expectedVersion) {
    return {
      badgeClassName:
        'inline-flex items-center rounded-full bg-amber-100 px-2 py-0.5 text-[11px] font-medium text-amber-800 dark:bg-amber-900/25 dark:text-amber-200',
      badgeLabel: 'Update available',
      detail: `${currentVersion} -> ${expectedVersion}`,
      title: `Pulse Agent update available: ${currentVersion} -> ${expectedVersion}`,
    };
  }

  if (currentVersion) {
    return {
      badgeClassName:
        'inline-flex items-center rounded-full border border-border bg-surface-alt px-2 py-0.5 text-[11px] font-medium text-base-content',
      badgeLabel: 'Agent version',
      detail: currentVersion,
      title: `Pulse Agent version ${currentVersion}`,
    };
  }

  if (expectedVersion) {
    return {
      badgeClassName:
        'inline-flex items-center rounded-full border border-border bg-surface-alt px-2 py-0.5 text-[11px] font-medium text-base-content',
      badgeLabel: 'Version target',
      detail: expectedVersion,
      title: `Pulse Agent target version ${expectedVersion}`,
    };
  }

  return null;
};

const SURFACE_LABELS: Record<string, string> = {
  vms: 'VMs',
  containers: 'Containers',
  storage: 'Storage',
  backups: 'Backups',
  datastores: 'Datastores',
  syncJobs: 'Sync jobs',
  verifyJobs: 'Verify jobs',
  pruneJobs: 'Prune jobs',
  garbageJobs: 'GC jobs',
  mailStats: 'Mail stats',
  queues: 'Queues',
  quarantine: 'Quarantine',
  domainStats: 'Domain stats',
  host: 'Host telemetry',
  hosts: 'Hosts',
  datasets: 'Datasets',
  pools: 'Pools',
  replication: 'Replication',
  availability: 'Availability',
};

export const surfaceLabel = (key: string): string => SURFACE_LABELS[key] ?? key;

export type InfrastructureSourceKind = 'api' | 'agent' | 'both' | 'probe' | 'unknown';

export interface InfrastructureSourcePresentation {
  label: string;
  badgeClassName: string;
  title: string;
}

const SOURCE_PRESENTATION: Record<InfrastructureSourceKind, InfrastructureSourcePresentation> = {
  api: {
    label: 'API',
    badgeClassName:
      'inline-flex items-center rounded-full bg-surface-alt px-2 py-0.5 text-[11px] font-medium text-base-content',
    title: 'Data collected via the platform API',
  },
  agent: {
    label: 'Agent',
    badgeClassName:
      'inline-flex items-center rounded-full bg-emerald-100 px-2 py-0.5 text-[11px] font-medium text-emerald-800 dark:bg-emerald-950/40 dark:text-emerald-200',
    title: 'Data collected via Pulse Agent',
  },
  both: {
    label: 'API + Agent',
    badgeClassName:
      'inline-flex items-center rounded-full bg-indigo-100 px-2 py-0.5 text-[11px] font-medium text-indigo-800 dark:bg-indigo-950/40 dark:text-indigo-200',
    title: 'Data collected via the platform API and Pulse Agent',
  },
  probe: {
    label: 'Probe',
    badgeClassName:
      'inline-flex items-center rounded-full bg-cyan-100 px-2 py-0.5 text-[11px] font-medium text-cyan-800 dark:bg-cyan-950/40 dark:text-cyan-200',
    title: 'Data collected by an agentless availability probe',
  },
  unknown: {
    label: '—',
    badgeClassName: 'text-[12px] text-muted',
    title: 'No source attached',
  },
};

export const infrastructureSourcePresentation = (
  source: InfrastructureSourceKind,
): InfrastructureSourcePresentation => SOURCE_PRESENTATION[source];

export type FleetGovernanceSignalKey =
  | 'enrollment'
  | 'liveness'
  | 'version'
  | 'adapter'
  | 'module-health'
  | 'config'
  | 'config-drift'
  | 'credentials'
  | 'rollout'
  | 'credential-health'
  | 'updates'
  | 'remote-control'
  | 'command-policy';

export type FleetGovernanceSignalTone = 'ok' | 'info' | 'warning' | 'critical' | 'muted';

export interface FleetGovernanceSignal {
  key: FleetGovernanceSignalKey;
  label: string;
  detail: string;
  tone: FleetGovernanceSignalTone;
  // An agent that is behind or has an update waiting is maintenance, not a
  // problem: the row's Agent update badge already says so and opens Agent
  // Doctor, so the row does not repeat it as its problem line or count it as
  // needing attention. The Manage drawer still lists the signal.
  maintenance?: boolean;
}

const DEFAULT_FLEET_GOVERNANCE: ConnectionFleetGovernance = {
  enrollmentState: 'pending',
  livenessState: 'pending',
  versionDrift: 'unknown',
  adapterHealth: 'unknown',
  configRollout: 'unknown',
  credentialStatus: 'unknown',
  updateStatus: 'unknown',
  remoteControl: 'not-applicable',
};

export const fleetGovernanceForConnection = (connection: Connection): ConnectionFleetGovernance =>
  connection.fleet ?? DEFAULT_FLEET_GOVERNANCE;

const configDriftFromFleet = (fleet: ConnectionFleetGovernance): ConnectionFleetConfigDrift => {
  if (fleet.configDrift) return fleet.configDrift;

  switch (fleet.configRollout) {
    case 'configured':
    case 'reported':
      return { status: 'current', reason: 'Configuration is current.' };
    case 'paused':
      return { status: 'paused', reason: 'Configuration rollout is paused.' };
    case 'unknown':
      return { status: 'unknown', reason: 'Configuration drift state is unknown.' };
  }
};

const rolloutFromFleet = (fleet: ConnectionFleetGovernance): ConnectionFleetRolloutState => {
  if (fleet.rollout) return fleet.rollout;

  switch (fleet.configRollout) {
    case 'configured':
    case 'reported':
      return { status: 'current', stage: 'applied' };
    case 'paused':
      return { status: 'paused', stage: 'paused' };
    case 'unknown':
      return { status: 'unknown' };
  }
};

const credentialHealthFromFleet = (
  fleet: ConnectionFleetGovernance,
): ConnectionFleetCredentialHealth => {
  if (fleet.credentialHealth) return fleet.credentialHealth;

  switch (fleet.credentialStatus) {
    case 'verified':
      return { status: 'verified' };
    case 'invalid':
      return { status: 'invalid' };
    case 'paused':
      return { status: 'paused' };
    case 'unknown':
      return { status: 'unknown' };
  }
};

const commandPolicyFromFleet = (fleet: ConnectionFleetGovernance): ConnectionFleetCommandPolicy => {
  if (fleet.commandPolicy) return fleet.commandPolicy;

  switch (fleet.remoteControl) {
    case 'disconnected':
      return {
        status: 'blocked',
        desired: 'unknown',
        applied: 'enabled',
        enforcement: 'blocked',
        reason: 'The agent reports command execution enabled, but no command channel is connected.',
      };
    case 'enabled':
      return {
        status: 'enabled',
        desired: 'unknown',
        applied: 'enabled',
        enforcement: 'not-applicable',
      };
    case 'disabled':
      return {
        status: 'disabled',
        desired: 'unknown',
        applied: 'disabled',
        enforcement: 'not-applicable',
      };
    case 'not-applicable':
      return { status: 'not-applicable', enforcement: 'not-applicable' };
    case 'unknown':
      return {
        status: 'unknown',
        desired: 'unknown',
        applied: 'unknown',
        enforcement: 'pending',
      };
  }
};

const fleetSignalClassNameByTone: Record<FleetGovernanceSignalTone, string> = {
  ok: 'border-emerald-200 bg-emerald-50 text-emerald-800 dark:border-emerald-900/25 dark:bg-emerald-950/30 dark:text-emerald-200',
  info: 'border-blue-200 bg-blue-50 text-blue-800 dark:border-blue-900/25 dark:bg-blue-950/30 dark:text-blue-200',
  warning:
    'border-amber-200 bg-amber-50 text-amber-800 dark:border-amber-900/25 dark:bg-amber-950/30 dark:text-amber-200',
  critical:
    'border-rose-200 bg-rose-50 text-rose-800 dark:border-rose-900/25 dark:bg-rose-950/30 dark:text-rose-200',
  muted: 'border-border bg-surface-alt text-muted',
};

export const fleetSignalClassName = (tone: FleetGovernanceSignalTone): string =>
  `inline-flex items-center rounded-full border px-2 py-0.5 text-[11px] font-medium whitespace-nowrap ${fleetSignalClassNameByTone[tone]}`;

const enrollmentSignal = (
  state: ConnectionFleetEnrollmentState,
  connection: Connection,
): FleetGovernanceSignal => {
  switch (state) {
    case 'configured':
      return {
        key: 'enrollment',
        label: 'Configured',
        detail: 'This source is configured in the infrastructure ledger.',
        tone: 'ok',
      };
    case 'enrolled':
      return {
        key: 'enrollment',
        label: 'Enrolled',
        detail: 'This agent has reported into the fleet ledger.',
        tone: 'ok',
      };
    case 'paused':
      return {
        key: 'enrollment',
        label: 'Paused',
        detail: 'This source is present but currently paused.',
        tone: 'muted',
      };
    case 'pending':
      return {
        key: 'enrollment',
        label: 'Enrollment pending',
        detail:
          connection.type === 'agent'
            ? 'Pulse has not received the first agent report yet.'
            : 'Pulse has not confirmed this source yet.',
        tone: 'warning',
      };
  }
};

const livenessSignal = (state: ConnectionFleetLivenessState): FleetGovernanceSignal => {
  switch (state) {
    case 'active':
      return {
        key: 'liveness',
        label: 'Live',
        detail: 'Pulse has recent activity for this source.',
        tone: 'ok',
      };
    case 'paused':
      return {
        key: 'liveness',
        label: 'Paused',
        detail: 'Pulse is not polling this source while it is paused.',
        tone: 'muted',
      };
    case 'stale':
      return {
        key: 'liveness',
        label: 'Stale',
        detail: 'Pulse has not seen recent activity from this source.',
        tone: 'warning',
      };
    case 'degraded':
      return {
        key: 'liveness',
        label: 'Degraded',
        detail: 'Pulse reaches this source, but some of its readings failed.',
        tone: 'warning',
      };
    case 'pending':
      return {
        key: 'liveness',
        label: 'Pending',
        detail: 'Pulse is waiting for first activity from this source.',
        tone: 'warning',
      };
    case 'unauthorized':
      return {
        key: 'liveness',
        label: 'Unauthorized',
        detail: 'The configured credential is being rejected.',
        tone: 'critical',
      };
    case 'unreachable':
      return {
        key: 'liveness',
        label: 'Unreachable',
        detail: 'Pulse cannot currently reach this source.',
        tone: 'critical',
      };
  }
};

const versionSignal = (state: ConnectionFleetVersionDrift): FleetGovernanceSignal => {
  switch (state) {
    case 'behind':
      return {
        key: 'version',
        label: 'Version behind',
        detail: 'This agent is behind the current Pulse Agent target.',
        tone: 'warning',
        maintenance: true,
      };
    case 'current':
      return {
        key: 'version',
        label: 'Version current',
        detail: 'This agent matches the current Pulse Agent target.',
        tone: 'ok',
      };
    case 'unknown':
      return {
        key: 'version',
        label: 'Version unknown',
        detail: 'Pulse does not yet have enough version data for this agent.',
        tone: 'muted',
      };
    case 'not-applicable':
      return {
        key: 'version',
        label: 'No agent version',
        detail: 'This source is not governed by the Pulse Agent binary version.',
        tone: 'muted',
      };
  }
};

const adapterSignal = (state: ConnectionFleetAdapterHealth): FleetGovernanceSignal => {
  switch (state) {
    case 'healthy':
      return {
        key: 'adapter',
        label: 'Adapter healthy',
        detail: 'The collection adapter is operating normally.',
        tone: 'ok',
      };
    case 'degraded':
      return {
        key: 'adapter',
        label: 'Adapter degraded',
        detail: 'The collection adapter needs attention or first confirmation.',
        tone: 'warning',
      };
    case 'blocked':
      return {
        key: 'adapter',
        label: 'Adapter blocked',
        detail: 'The collection adapter cannot complete its current read path.',
        tone: 'critical',
      };
    case 'paused':
      return {
        key: 'adapter',
        label: 'Adapter paused',
        detail: 'Collection is paused for this source.',
        tone: 'muted',
      };
    case 'unknown':
      return {
        key: 'adapter',
        label: 'Adapter unknown',
        detail: 'Pulse has not classified adapter health yet.',
        tone: 'muted',
      };
  }
};

const configDriftSignal = (state: ConnectionFleetConfigDrift): FleetGovernanceSignal => {
  switch (state.status) {
    case 'current':
      return {
        key: 'config-drift',
        label: 'Config current',
        detail: state.reason || 'Desired and applied configuration fingerprints match.',
        tone: 'ok',
      };
    case 'drifted':
      return {
        key: 'config-drift',
        label: 'Config drift',
        detail: state.reason || 'Desired and applied configuration fingerprints do not match.',
        tone: 'warning',
      };
    case 'pending':
      return {
        key: 'config-drift',
        label: 'Config pending',
        detail: state.reason || 'Pulse is waiting for applied configuration confirmation.',
        tone: 'warning',
      };
    case 'paused':
      return {
        key: 'config-drift',
        label: 'Config paused',
        detail: state.reason || 'Configuration rollout is paused for this source.',
        tone: 'muted',
      };
    case 'unknown':
      return {
        key: 'config-drift',
        label: 'Config unknown',
        detail: state.reason || 'Pulse does not yet have enough config fingerprint data.',
        tone: 'warning',
      };
    case 'not-applicable':
      return {
        key: 'config-drift',
        label: 'No config drift',
        detail: state.reason || 'This source is not governed by desired/applied config rollout.',
        tone: 'muted',
      };
  }
};

const rolloutSignal = (state: ConnectionFleetRolloutState): FleetGovernanceSignal => {
  switch (state.status) {
    case 'current':
      return {
        key: 'rollout',
        label: 'Rollout current',
        detail: state.reason || 'The rollout state is current.',
        tone: 'ok',
      };
    case 'pending':
      return {
        key: 'rollout',
        label: 'Rollout pending',
        detail: state.reason || 'The staged rollout is waiting for confirmation.',
        tone: 'warning',
      };
    case 'paused':
      return {
        key: 'rollout',
        label: 'Rollout paused',
        detail: state.reason || 'The staged rollout is paused.',
        tone: 'warning',
      };
    case 'blocked':
      return {
        key: 'rollout',
        label: 'Rollout blocked',
        detail: state.reason || 'The rollout is blocked by the current connection state.',
        tone: 'critical',
      };
    case 'unknown':
      return {
        key: 'rollout',
        label: 'Rollout unknown',
        detail: state.reason || 'Pulse has not classified staged rollout state yet.',
        tone: 'warning',
      };
    case 'not-applicable':
      return {
        key: 'rollout',
        label: 'No rollout',
        detail: state.reason || 'This source does not use staged rollout control.',
        tone: 'muted',
      };
  }
};

const credentialHealthSignal = (state: ConnectionFleetCredentialHealth): FleetGovernanceSignal => {
  switch (state.status) {
    case 'verified':
      return {
        key: 'credential-health',
        label: 'Credentials verified',
        detail: 'The current credential path is accepted.',
        tone: 'ok',
      };
    case 'invalid':
      return {
        key: 'credential-health',
        label: 'Credentials invalid',
        detail: 'The current credential path is rejected by the source.',
        tone: 'critical',
      };
    case 'expired':
      return {
        key: 'credential-health',
        label: 'Credentials expired',
        detail: 'The credential has passed its configured expiration.',
        tone: 'critical',
      };
    case 'expiring':
      return {
        key: 'credential-health',
        label: 'Credentials expiring',
        detail: 'The credential is approaching its configured expiration.',
        tone: 'warning',
      };
    case 'paused':
      return {
        key: 'credential-health',
        label: 'Credentials paused',
        detail: 'Credential checks are paused with this source.',
        tone: 'muted',
      };
    case 'unknown':
      return {
        key: 'credential-health',
        label: 'Credentials unknown',
        detail: 'Pulse has not verified this credential path yet.',
        tone: 'warning',
      };
    case 'not-applicable':
      return {
        key: 'credential-health',
        label: 'No credentials',
        detail: 'This source does not use a stored credential path.',
        tone: 'muted',
      };
  }
};

const updateSignal = (
  state: ConnectionFleetUpdateStatus,
  update?: Connection['agentUpdate'],
): FleetGovernanceSignal => {
  switch (state) {
    case 'update-available':
      return {
        key: 'updates',
        label: 'Update available',
        detail: 'A newer Pulse Agent binary is available for this system.',
        tone: 'warning',
        maintenance: true,
      };
    case 'checking':
      return {
        key: 'updates',
        label: 'Checking for updates',
        detail: 'This agent is checking the Pulse server for an updated binary.',
        tone: 'info',
      };
    case 'updating':
      return {
        key: 'updates',
        label: 'Agent updating',
        detail: 'This agent is verifying and applying an updated binary.',
        tone: 'info',
      };
    case 'failed':
      return {
        key: 'updates',
        label: 'Agent update failed',
        detail:
          update?.lastError ||
          'The agent could not complete its latest update check or update attempt.',
        tone: 'critical',
      };
    case 'disabled':
      return {
        key: 'updates',
        label: 'Auto-update off',
        detail: 'Automatic Pulse Agent updates are disabled on this system.',
        tone: 'warning',
      };
    case 'current':
      return {
        key: 'updates',
        label: 'Update current',
        detail: 'This agent is already on the current target version.',
        tone: 'ok',
      };
    case 'unknown':
      return {
        key: 'updates',
        label: 'Update unknown',
        detail: 'Pulse cannot yet compare this agent with the target version.',
        tone: 'muted',
      };
    case 'not-applicable':
      return {
        key: 'updates',
        label: 'No agent update',
        detail: 'This source is not updated through the Pulse Agent binary rollout.',
        tone: 'muted',
      };
  }
};

const moduleHealthSignal = (connection: Connection): FleetGovernanceSignal | undefined => {
  const module = connection.agentModules?.find(
    (candidate) => candidate.enabled && candidate.state !== 'running',
  );
  if (!module) return undefined;

  const displayName =
    module.name === 'docker'
      ? 'Docker'
      : module.name === 'kubernetes'
        ? 'Kubernetes'
        : module.name === 'host'
          ? 'Host'
          : module.name;
  return {
    key: 'module-health',
    label: `${displayName} module ${module.state}`,
    detail:
      module.lastError || `${displayName} monitoring is enabled but the module is not running yet.`,
    tone: 'warning',
  };
};

const commandPolicySignal = (state: ConnectionFleetCommandPolicy): FleetGovernanceSignal => {
  if (state.enforcement === 'drifted') {
    const desiredDisabledAppliedEnabled =
      state.desired === 'disabled' && state.applied === 'enabled';
    return {
      key: 'command-policy',
      label: 'Command policy mismatch',
      detail: state.reason || 'Desired and applied command-policy states do not match.',
      tone: desiredDisabledAppliedEnabled ? 'critical' : 'warning',
    };
  }
  if (state.enforcement === 'pending') {
    return {
      key: 'command-policy',
      label: 'Command policy pending',
      detail: state.reason || 'Pulse is waiting for applied command-policy confirmation.',
      tone: 'warning',
    };
  }

  switch (state.status) {
    case 'enabled':
      return {
        key: 'command-policy',
        label: 'Remote control enabled',
        detail: state.reason || 'Pulse command execution is enabled for this agent.',
        tone: 'info',
      };
    case 'disabled':
      return {
        key: 'command-policy',
        label: 'Remote control disabled',
        detail: state.reason || 'Pulse command execution is disabled for this agent.',
        tone: 'info',
      };
    case 'blocked':
      return {
        key: 'command-policy',
        label: 'Remote control blocked',
        detail: state.reason || 'Pulse command execution is blocked by policy.',
        tone: 'critical',
      };
    case 'unknown':
      return {
        key: 'command-policy',
        label: 'Remote control unknown',
        detail: state.reason || 'Pulse has not confirmed command-policy state yet.',
        tone: 'warning',
      };
    case 'not-applicable':
      return {
        key: 'command-policy',
        label: 'No remote control',
        detail: state.reason || 'This source does not use Pulse Agent command execution.',
        tone: 'muted',
      };
  }
};

// Builds the row-level problem line when an attached Pulse Agent isn't
// reporting. Derived directly from connection state — not laundered
// through the fleet-signal pipeline — so the row builder owns the user
// story for "API works, agent doesn't" without a synthesized chip hack.
export const agentAttachmentProblem = (agent: Connection): InfrastructureRowProblem | undefined => {
  switch (agent.state) {
    case 'stale': {
      const ago = lastActivityTextFromLastSeen(agent.lastSeen);
      const suffix = ago && ago !== 'No activity yet' && ago !== 'Unknown' ? ` · ${ago}` : '';
      return {
        label: `Agent offline${suffix}`,
        detail:
          agent.stateReason ||
          'The Pulse Agent on this host has not reported recently. Proxmox API metrics are unaffected.',
        tone: 'warning',
      };
    }
    case 'unreachable':
      return {
        label: 'Agent unreachable',
        detail: agent.stateReason || 'Pulse cannot currently reach the agent on this host.',
        tone: 'critical',
      };
    case 'unauthorized':
      return {
        label: 'Agent unauthorized',
        detail: agent.stateReason || 'The Pulse Agent token is being rejected.',
        tone: 'critical',
      };
    case 'pending':
      return {
        label: AGENT_WAITING_FOR_FIRST_REPORT_LABEL,
        detail: agent.stateReason || 'The Pulse Agent has not reported yet.',
        tone: 'warning',
      };
    default:
      return undefined;
  }
};

// Connections that run a Pulse Agent / collector binary. Agent-binary and
// managed-config governance (version drift, config drift, staged rollout,
// binary updates, remote command policy) only describes these — a pull-based
// API source (PVE, PBS, PMG, vSphere, TrueNAS, availability probe) has no
// agent, so the backend's echoed rollout/config state must not be surfaced as
// the row's problem. Without this gate an unreachable PBS reads "Rollout
// blocked" instead of plainly reflecting that it is unreachable.
const AGENT_FLEET_CONNECTION_TYPES: ReadonlySet<ConnectionType> = new Set([
  'agent',
  'docker',
  'kubernetes',
]);

const connectionRunsAgentFleet = (connection: Connection): boolean =>
  AGENT_FLEET_CONNECTION_TYPES.has(connection.type);

export const fleetGovernanceSignalsForConnection = (
  connection: Connection,
): FleetGovernanceSignal[] => {
  const fleet = fleetGovernanceForConnection(connection);
  const runsAgentFleet = connectionRunsAgentFleet(connection);
  const signals: FleetGovernanceSignal[] = [
    enrollmentSignal(fleet.enrollmentState, connection),
    livenessSignal(fleet.livenessState),
    credentialHealthSignal(credentialHealthFromFleet(fleet)),
  ];
  if (runsAgentFleet) {
    const moduleSignal = moduleHealthSignal(connection);
    if (moduleSignal) signals.push(moduleSignal);
    signals.push(
      configDriftSignal(configDriftFromFleet(fleet)),
      rolloutSignal(rolloutFromFleet(fleet)),
      versionSignal(fleet.versionDrift),
      updateSignal(fleet.updateStatus, connection.agentUpdate),
    );
  }
  signals.push(adapterSignal(fleet.adapterHealth));
  if (runsAgentFleet) {
    signals.push(commandPolicySignal(commandPolicyFromFleet(fleet)));
  }
  return signals;
};

// The row shows at most three highlights. A row's problem is picked from the
// whole visible list (limit Infinity) so a critical signal from a second
// attached agent cannot fall behind the cap.
export const visibleFleetGovernanceSignals = (
  signals: readonly FleetGovernanceSignal[],
  limit = 3,
): FleetGovernanceSignal[] => {
  const hasPassiveAgentConfigConfirmation = signals.some(isPassiveAgentConfigConfirmationSignal);
  const visibleSignals = signals.filter((signal) => {
    if (isPassiveAgentConfigConfirmationSignal(signal)) return false;
    if (isPassiveAgentRolloutConfirmationFallbackSignal(signal, hasPassiveAgentConfigConfirmation))
      return false;
    // Liveness duplicates the row's status badge column; skip it here so a
    // stale connection doesn't get "Stale" rendered twice.
    if (signal.key === 'liveness') return false;
    // "Adapter degraded" is internal collection-health terminology that
    // doesn't name a user-actionable problem. The agent-attachment chip
    // names the specific failure ("Agent offline · 4h ago") when it
    // matters; everything else this signal raised was redundant noise.
    if (signal.key === 'adapter') return false;
    // Default-disabled remote control is the unconfigured state on every
    // fresh agent. Surface only when policy is actively wrong
    // (blocked/mismatched/pending/unknown). The Manage drawer is the right
    // place to read informational policy state.
    if (signal.key === 'command-policy' && signal.tone === 'info') return false;
    return true;
  });
  // Problems lead; maintenance (an agent behind or with an update waiting)
  // follows them, since the Agent update badge already carries it.
  const attention = visibleSignals.filter(
    (signal) => !signal.maintenance && (signal.tone === 'critical' || signal.tone === 'warning'),
  );
  const maintenance = visibleSignals.filter((signal) => signal.maintenance);
  const control = visibleSignals.filter((signal) => !signal.maintenance && signal.tone === 'info');
  return [...attention, ...maintenance, ...control].slice(0, limit);
};

const isPassiveAgentConfigConfirmationSignal = (signal: FleetGovernanceSignal): boolean => {
  if (signal.tone !== 'warning') return false;
  if (signal.key !== 'config-drift' && signal.key !== 'rollout') return false;

  const detail = signal.detail.toLowerCase();
  return (
    detail.includes('comparable applied agent config fingerprint') ||
    detail.includes('comparable applied agent configuration fingerprint') ||
    detail.includes('agent to report an applied configuration fingerprint')
  );
};

const isPassiveAgentRolloutConfirmationFallbackSignal = (
  signal: FleetGovernanceSignal,
  hasPassiveAgentConfigConfirmation: boolean,
): boolean => {
  if (!hasPassiveAgentConfigConfirmation) return false;
  if (signal.tone !== 'warning' || signal.key !== 'rollout') return false;

  const detail = signal.detail.toLowerCase();
  return (
    detail.includes('staged rollout is waiting for confirmation') ||
    detail.includes(
      'rollout state cannot be confirmed without comparable desired and applied agent config fingerprints',
    )
  );
};

// A row-level operational problem expressed as one plain-English sentence
// — rendered below the status badge instead of as a parallel coloured chip.
// `fleetHighlights` is retained on the row model for downstream consumers
// (Manage drawer, audit views) that need the full structured signal list.
export interface InfrastructureRowProblem {
  label: string;
  detail: string;
  tone: 'warning' | 'critical';
}

export interface InfrastructureSystemMemberRow {
  id: string;
  nodeIdentity?: string;
  name: string;
  nativeName?: string;
  subtitle: string;
  source: InfrastructureSourceKind;
  host?: string;
  hostAliases?: string[];
  coverageLabels: string[];
  statusLabel: string;
  statusClassName: string;
  lastActivityText: string;
  fleetSignals: FleetGovernanceSignal[];
  fleetHighlights: FleetGovernanceSignal[];
  problem?: InfrastructureRowProblem;
  primary: boolean;
  agentConnection?: Connection;
}

export interface InfrastructureSystemRow {
  id: string;
  ownerType: ConnectionType;
  name: string;
  subtitle?: string;
  identitySubtitle?: string;
  source: InfrastructureSourceKind;
  host?: string;
  coverageLabels: string[];
  statusLabel: string;
  statusClassName: string;
  agentUpdateCount: number;
  lastActivityText: string;
  lastErrorMessage?: string;
  // A partial read (some readings failed on a reachable source) is a warning,
  // not an outage.
  lastErrorTone?: 'warning' | 'critical';
  fleetSignals: FleetGovernanceSignal[];
  fleetHighlights: FleetGovernanceSignal[];
  problem?: InfrastructureRowProblem;
  enabled: boolean;
  canEdit: boolean;
  canPause: boolean;
  canRemove: boolean;
  isAgent: boolean;
  isCluster: boolean;
  /** Proxmox cluster name for cluster rows; the cluster agent deploy API is keyed on it. */
  clusterName?: string;
  attachedConnections: Connection[];
  members: InfrastructureSystemMemberRow[];
  connection: Connection;
}

// The page that shows a connected system's data. Settings lists the
// connection, but a PBS reads as Active here while its servers live under
// Proxmox > Backups, which users did not find (#2905). Agent hosts appear on
// different pages depending on what they run, and availability checks under
// Machines, so neither has a single destination.
const MONITORING_PATH_BY_CONNECTION_TYPE: Partial<Record<ConnectionType, string>> = {
  pve: buildProxmoxPath(),
  pbs: buildProxmoxPath('backups'),
  pmg: buildProxmoxPath('mail'),
  vmware: buildVmwarePath(),
  truenas: buildTrueNASPath(),
  docker: buildDockerPath(),
  kubernetes: buildKubernetesPath(),
};

export const infrastructureRowMonitoringPath = (
  row: Pick<InfrastructureSystemRow, 'ownerType'>,
): string | undefined => MONITORING_PATH_BY_CONNECTION_TYPE[row.ownerType];

// Pick the single most important problem to surface in the row's status
// column. Critical beats warning; otherwise first wins — the upstream
// builder has already prioritised highlights (attention before info).
// Maintenance signals never become the problem (see FleetGovernanceSignal).
export const primaryRowProblem = (
  allSignals: readonly FleetGovernanceSignal[],
): InfrastructureRowProblem | undefined => {
  const signals = allSignals.filter((signal) => !signal.maintenance);
  const critical = signals.find((signal) => signal.tone === 'critical');
  if (critical) {
    return { label: critical.label, detail: critical.detail, tone: 'critical' };
  }
  const warning = signals.find((signal) => signal.tone === 'warning');
  if (warning) {
    return { label: warning.label, detail: warning.detail, tone: 'warning' };
  }
  return undefined;
};