feat(cli): add TRACEROUTE Hops column to checks stats [SIM-278] (#1385)

* feat(reporters): per-type TRACEROUTE/GRPC/SSL result rendering (P4-CLI-RESULTS)

Render failure-debug diagnostics for the three uptime monitor types across
every CLI result surface, mirroring the 4.1 public check-results fields:

- rest/check-results.ts: typed TracerouteCheckResult/GrpcCheckResult/
  SslCheckResult interfaces + additive fields on CheckResult/CheckResultField.
- formatters/check-result-detail.ts: per-type terminal + markdown diagnostic
  block (checks results get) keyed on the typed fields.
- reporters/util.ts: GRPC/SSL/TRACEROUTE branches in formatCheckResult
  (checkly test terminal), sourced from the runner artifact (checkRunData).
- formatters/batch-stats.ts: add the three types to TIMING_TYPES.
- reporters/json.ts: emit a per-type diagnostics object in the JSON report
  for a failed run (checkly test --reporter json).

Snapshot + assertion tests for each type across all three surfaces.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(constructs): add GrpcMonitor, SslMonitor, TracerouteMonitor IaC constructs

Implement the missing CLI constructs so users can author and deploy gRPC, SSL
and Traceroute uptime monitors via checkly/constructs, and so backend CLI export
templates that import these classes compile.

Constructs follow the DNS/TCP/ICMP monitor pattern (extend Monitor, register
with Session, validate, synthesize):

- GrpcMonitor / GrpcRequest / GrpcConfig / GrpcMetadata + GrpcAssertionBuilder
  (RESPONSE_TIME, GRPC_STATUS_CODE, GRPC_HEALTHCHECK_STATUS, GRPC_RESPONSE,
  GRPC_METADATA). checkType GRPC, top-level degraded/maxResponseTime (<=30000).
- SslMonitor / SslRequest / SslConfig / SecurityBaseline + SslAssertionBuilder
  (cert expiry, chain, hostname, TLS version, cipher, key size, etc). checkType
  SSL; response-time limits live in sslConfig (degraded/maxResponseTimeMs).
- TracerouteMonitor / TracerouteRequest + TracerouteAssertionBuilder
  (RESPONSE_TIME, HOP_COUNT, PACKET_LOSS). checkType TRACEROUTE, top-level
  degraded/maxResponseTime (<=30000); port dropped for ICMP probes.

Request shapes mirror the public API (verified against checkly-go-sdk types and
the p5-parity captured payloads). Wires exports in constructs/index.ts, import
codegen in check-codegen.ts (GRPC/SSL/TRACEROUTE -> *MonitorCodegen), and adds
the three types to constants.CheckTypes.

Tests: construct synthesize/validation/grouping specs, codegen specs (incl.
ICMP port-strip and assertion builders), and a regression spec asserting the
backend-style export snippets compile against checkly/constructs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(deploy): skip code-bundle upload when nothing was bundled

archive.store() (the 'Uploading Playwright tests' step) was called
unconditionally on every deploy. For a project of only uptime monitors
(GRPC/SSL/TRACEROUTE), the bundler registers no files, so this uploaded an
empty Playwright bundle — an unnecessary code-bundle upload in production, and
a hard failure in devenv where it 500s on the storage backend.

The remote code bundle is consumed only by Playwright check suites (via
bundler.marker -> playwright-check.ts); browser checks upload snapshots
separately. Add Bundler.isEmpty and skip store() when no files were registered.

Refs T65.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(cli): wire gRPC/SSL/Traceroute analytics paths + connection-error rendering

Addresses review (Simo) new-monitor checklist gaps:
- src/rest/analytics.ts: add checkTypeToPath (grpc-checks/ssl/traceroute) and
  defaultMetrics for the three types, matching the backend analytics routes +
  metric registries (gRPC total_*, SSL handshakeTimeMs_*/daysUntilExpiry_avg,
  TRACEROUTE finalHopLatencyAvg_*/totalHops_avg).
- src/reporters/util.ts: add the Connection Error subsection to the GRPC/SSL/
  TRACEROUTE result blocks, mirroring ICMP/DNS.

* docs(cli): AI context references + examples for gRPC/SSL/Traceroute monitors

Addresses review (Simo) new-monitor checklist Phases 5 & 7:
- ai-context/references/configure-{grpc,ssl,traceroute}-monitors.md + REFERENCES
  and EXAMPLE_CONFIGS entries in context.ts (inline exampleConfig).
- examples/advanced-project{,-js}/src/__checks__/uptime/{grpc,ssl,traceroute}
  TS + JS examples with group, assertions, and doc-link comments.

* test(cli): e2e deploy fixtures + Create assertions for gRPC/SSL/Traceroute

Addresses review (Simo) new-monitor checklist Phase 6:
- e2e/__tests__/fixtures/deploy-project/{grpc,ssl,traceroute}.check.ts (activated:false)
- deploy.spec.ts: assert the three logical IDs in the Create output.

* feat(cli): support TEXT_BODY assertions for gRPC monitors

Mirror monorepo #2730 which added TEXT_BODY to grpcMonitorAssertionSources.
Adds GrpcAssertionBuilder.textBody() (source TEXT_BODY) + codegen case,
matching the API check's textBody() builder.

* refactor(cli): restructure SslMonitor props per review (wire shape unchanged)

Per @sorccu's review: make SslMonitor ergonomics consistent with other monitors.
- degradedResponseTime/maxResponseTime -> construct top level (were in sslConfig)
- hostname/port/ipFamily -> request top level (were in sslConfig)
- sslClientCertificateId -> into sslConfig (was on request)
synthesize() remaps to the identical API wire shape (request.sslConfig.* +
request.sslClientCertificateId), so the payload the backend receives is unchanged.
Updated codegen (wire->construct), unit + codegen + export-snippet tests,
examples (ts+js), e2e fixture, and AI context.

* refactor(cli): drop Ms suffix on SslConfig.handshakeTimeout per review

@sorccu: we don't suffix timeout properties with Ms even when the value is
milliseconds. Renames the construct field handshakeTimeoutMs -> handshakeTimeout;
synthesize() and the codegen wire interface keep the API's handshakeTimeoutMs.

* refactor(cli): emit SSL degraded/maxResponseTime at top level to match gRPC/traceroute wire

* feat(cli): add TRACEROUTE Hops column to checks stats [SIM-278]

Adds a bespoke `Hops` column for TRACEROUTE checks in `checkly checks stats`,
mirroring the ICMP Latency/Pkt Loss bespoke-column pattern. TRACEROUTE keeps its
final-hop-latency Resp columns (stays in TIMING_TYPES) and additionally shows hop
count from the new hopCount_avg field.

Follow-up to #1362 (stacked on feat/cli-pertype-result-rendering). hopCount_avg is
populated by the SIM-278 backend change; until it deploys the column renders a dash.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Ubuntu <ubuntu@ip-172-31-7-108.eu-central-1.compute.internal>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

packages/cli/src/commands/checks/stats.ts

@@ -144,6 +144,7 @@ export default class ChecksStats extends AuthCommand {
             responseTime_p95: r.analytics?.responseTime_p95 ?? null,
             latency_avg: r.analytics?.latency_avg ?? null,
             packetLoss_avg: r.analytics?.packetLoss_avg ?? null,
+            hopCount_avg: r.analytics?.hopCount_avg ?? null,
           })),
           pagination: { page, limit, total: totalChecks, totalPages },
           range,

packages/cli/src/formatters/__tests__/batch-stats.spec.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from 'vitest'
+import { formatBatchStats, type StatsRow } from '../batch-stats.js'
+
+// Build a minimal StatsRow. Only the fields read by the batch-stats formatter
+// (name, checkType, activated, status, analytics) matter here.
+function row (
+  checkType: string,
+  analytics: Partial<StatsRow['analytics']> = {},
+  name = `${checkType} check`,
+): StatsRow {
+  return {
+    name,
+    checkType,
+    activated: true,
+    status: { hasFailures: false, hasErrors: false, isDegraded: false },
+    analytics: { availability: 99.9, ...analytics },
+  } as unknown as StatsRow
+}
+
+describe('formatBatchStats — TRACEROUTE columns', () => {
+  it('renders a Hops column with the average hop count for TRACEROUTE rows', () => {
+    const out = formatBatchStats([row('TRACEROUTE', { hopCount_avg: 12.5 })], 'last24Hours', 'md')
+
+    expect(out).toContain('Hops (avg)')
+    expect(out).toContain('12.50')
+  })
+
+  it('keeps the final-hop-latency responseTime columns for TRACEROUTE (no regression)', () => {
+    // responseTime_avg for TRACEROUTE is the final-hop latency (ms).
+    const out = formatBatchStats(
+      [row('TRACEROUTE', { hopCount_avg: 9, responseTime_avg: 42000 })],
+      'last24Hours',
+      'md',
+    )
+
+    expect(out).toContain('Resp (avg)')
+    expect(out).toContain('42.000s')
+    expect(out).toContain('Hops (avg)')
+  })
+
+  it('shows a dash in the Hops column for non-TRACEROUTE rows in a mixed batch', () => {
+    const out = formatBatchStats(
+      [
+        row('API', { responseTime_avg: 1000 }),
+        row('TRACEROUTE', { hopCount_avg: 15 }),
+      ],
+      'last24Hours',
+      'md',
+    )
+
+    expect(out).toContain('Hops (avg)')
+    // The API row has no hop count; the Hops cell falls back to the dash.
+    expect(out).toContain('—')
+    expect(out).toContain('15.00')
+  })
+
+  it('omits the Hops column entirely when no TRACEROUTE checks are present', () => {
+    const out = formatBatchStats([row('API', { responseTime_avg: 1000 })], 'last24Hours', 'md')
+
+    expect(out).not.toContain('Hops')
+  })
+
+  it('renders a dash when a TRACEROUTE row has no hop-count data yet', () => {
+    // Until the backend batch-analytics endpoint returns hopCount_avg, the column
+    // renders a dash rather than a bogus value.
+    const out = formatBatchStats([row('TRACEROUTE', { hopCount_avg: null })], 'last24Hours', 'md')
+
+    expect(out).toContain('Hops (avg)')
+    expect(out).toContain('—')
+  })
+
+  it('renders the Hops column in terminal format (count for traceroute, dash otherwise)', () => {
+    const out = formatBatchStats(
+      [
+        row('API', { responseTime_avg: 1000 }),
+        row('TRACEROUTE', { hopCount_avg: 15 }),
+      ],
+      'last24Hours',
+      'terminal',
+    )
+
+    // Terminal renders headers upper-cased ("HOPS"); the value and the
+    // non-traceroute dash both survive chalk styling.
+    expect(out).toContain('HOPS')
+    expect(out).toContain('15.00')
+    expect(out).toContain('—')
+  })
+})

packages/cli/src/formatters/batch-stats.ts

@@ -8,8 +8,11 @@ import type { QuickRange } from '../rest/analytics.js'
 
 export type StatsRow = CheckWithStatus & { analytics?: BatchAnalyticsResult }
 
+// TRACEROUTE stays in TIMING_TYPES so it keeps its final-hop-latency responseTime
+// columns; it additionally gets a bespoke Hops column (see hasTraceroute below).
 const TIMING_TYPES = new Set(['API', 'BROWSER', 'PLAYWRIGHT', 'MULTI_STEP', 'URL', 'TCP', 'DNS', 'GRPC', 'SSL', 'TRACEROUTE'])
 const ICMP_TYPE = 'ICMP'
+const TRACEROUTE_TYPE = 'TRACEROUTE'
 const DASH = '—'
 
 /**
@@ -63,6 +66,7 @@ function metricOrDash (
 function buildColumns (rows: StatsRow[], format: OutputFormat): ColumnDef<StatsRow>[] {
   const hasTiming = rows.some(r => TIMING_TYPES.has(r.checkType))
   const hasIcmp = rows.some(r => r.checkType === ICMP_TYPE)
+  const hasTraceroute = rows.some(r => r.checkType === TRACEROUTE_TYPE)
 
   if (format === 'md') {
     const cols: ColumnDef<StatsRow>[] = [
@@ -99,6 +103,13 @@ function buildColumns (rows: StatsRow[], format: OutputFormat): ColumnDef<StatsR
         value: (r, fmt) => metricOrDash('packetLoss_avg', r.analytics?.packetLoss_avg ?? null, fmt, r.checkType === ICMP_TYPE),
       })
     }
+    if (hasTraceroute) {
+      cols.push({
+        header: 'Hops (avg)',
+        align: 'right',
+        value: (r, fmt) => metricOrDash('hopCount_avg', r.analytics?.hopCount_avg ?? null, fmt, r.checkType === TRACEROUTE_TYPE),
+      })
+    }
     return cols
   }
 
@@ -162,6 +173,15 @@ function buildColumns (rows: StatsRow[], format: OutputFormat): ColumnDef<StatsR
     })
   }
 
+  if (hasTraceroute) {
+    cols.push({
+      header: 'Hops',
+      width: metricWidth,
+      align: 'right',
+      value: (r, fmt) => metricOrDash('hopCount_avg', r.analytics?.hopCount_avg ?? null, fmt, r.checkType === TRACEROUTE_TYPE),
+    })
+  }
+
   return cols
 }
 

packages/cli/src/rest/batch-analytics.ts

@@ -15,6 +15,7 @@ export interface BatchAnalyticsResult {
   packetLoss_avg: number | null
   packetLoss_p95: number | null
   packetLoss_p99: number | null
+  hopCount_avg: number | null
 }
 
 // Subset of QuickRange — excludes last30Days and thisMonth because their rolling windows