feat(cli): show analytics stats in checks get [AI-55] (#1249)

* refactor(cli): extract analytics formatting into shared module

* feat(cli): show analytics stats in checks get output [AI-55]

* fix(cli): tighten extractMetrics return type and stats header style

- Return Record<string, number> with isNaN guard instead of Record<string, number | string>
- Use dim styling for range in STATS header for visual consistency

* chore(cli): remove standalone checks stats command

Stats are shown inline in checks get, no separate subcommand needed.

* chore(cli): wire analytics REST client into API module

* refactor(cli): use shared CheckTypes constant for check type mappings

Expands CheckTypes in constants.ts to include all 9 check types and
uses it in analytics.ts and list.ts instead of hardcoded strings.

* fix(cli): handle array series data and clean up stats output

- Fix extractMetrics to handle API returning series[0].data as array
- Filter out bonus fields (total, success) by using requestedMetrics
- Display metrics in intended order (availability first)

* fix(cli): use human-friendly range labels in stats output

"last24Hours" → "last 24 hours", "last7Days" → "last 7 days", etc.

* feat(cli): add --group-by, --metrics, --filter-status flags and fix error rendering

- Add --group-by location|statusCode for per-region/status-code stats breakdown
- Add --metrics flag for custom metric selection (overrides defaults)
- Add --filter-status success|failure to filter stats by run outcome
- Update browser/playwright defaults to include Web Vitals (LCP, CLS, TBT)
- Add CLS as "score" unit type with appropriate thresholds
- Fix formatMetricLabel to preserve uppercase acronyms (LCP, CLS, TBT)
- Fix Analytics.get() return type to match { data: T } pattern
- Replace non-null assertions with ?? fallbacks
- Remove dead listMetrics() method
- Use API metadata for unit detection with heuristic fallback
- Fix [object Object] rendering for Playwright Test error objects
- Expand test coverage: findUnit branches, grouped output, metadata, error objects

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: thebiglabasky

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

@@ -11,6 +11,8 @@ import {
   formatErrorGroups,
 } from '../../formatters/checks'
 import { formatResultDetail } from '../../formatters/check-result-detail'
+import { quickRangeValues, type QuickRange, type GroupBy } from '../../rest/analytics'
+import { formatAnalyticsSection } from '../../formatters/analytics'
 
 export default class ChecksGet extends AuthCommand {
   static hidden = false
@@ -41,6 +43,22 @@ export default class ChecksGet extends AuthCommand {
     'results-cursor': Flags.string({
       description: 'Cursor for results pagination (from previous output).',
     }),
+    'stats-range': Flags.string({
+      description: 'Time range for stats.',
+      options: quickRangeValues,
+      default: 'last24Hours',
+    }),
+    'group-by': Flags.string({
+      description: 'Group stats by dimension.',
+      options: ['location', 'statusCode'],
+    }),
+    'metrics': Flags.string({
+      description: 'Comma-separated list of metrics to show (overrides defaults).',
+    }),
+    'filter-status': Flags.string({
+      description: 'Only include runs with this status in stats.',
+      options: ['success', 'failure'],
+    }),
     'output': outputFlag({ default: 'detail' }),
   }
 
@@ -59,22 +77,32 @@ export default class ChecksGet extends AuthCommand {
         return await this.showErrorGroupDetail(args.id, flags['error-group'], flags.output ?? 'detail')
       }
 
-      const [{ data: check }, statusResp, resultsResp, errorGroupsResp] = await Promise.all([
-        api.checks.get(args.id),
+      // Fetch check first (need checkType for analytics)
+      const { data: check } = await api.checks.get(args.id)
+
+      // Fetch remaining data in parallel
+      const [statusResp, resultsResp, errorGroupsResp, analyticsResp] = await Promise.all([
         api.checkStatuses.get(args.id).catch(() => ({ data: undefined })),
         api.checkResults.getAll(args.id, {
           limit: flags['results-limit'],
           nextId: flags['results-cursor'],
         }).catch(() => ({ data: { entries: [], nextId: null, length: 0 } })),
         api.errorGroups.getByCheckId(args.id).catch(() => ({ data: [] })),
+        api.analytics.get(args.id, check.checkType, {
+          quickRange: (flags['stats-range'] ?? 'last24Hours') as QuickRange,
+          groupBy: flags['group-by'] === 'location' ? 'runLocation' : flags['group-by'] as GroupBy | undefined,
+          metrics: flags.metrics ? flags.metrics.split(',').map(m => m.trim()) : undefined,
+          filterByStatus: flags['filter-status'] as 'success' | 'failure' | undefined,
+        }).then(r => r.data).catch(() => undefined),
       ])
 
       const status = statusResp.data
       const { entries: results, nextId } = resultsResp.data
       const errorGroups = errorGroupsResp.data
 
       if (flags.output === 'json') {
-        this.log(JSON.stringify({ check, status, results, nextId, errorGroups }, null, 2))
+        const analytics = analyticsResp ?? null
+        this.log(JSON.stringify({ check, status, results, nextId, errorGroups, analytics }, null, 2))
         return
       }
 
@@ -85,6 +113,11 @@ export default class ChecksGet extends AuthCommand {
         const lines = [
           formatCheckDetail(checkWithStatus, fmt),
         ]
+        const statsOutput = formatAnalyticsSection(analyticsResp, flags['stats-range'] ?? 'last24Hours', fmt)
+        if (statsOutput) {
+          lines.push('')
+          lines.push(statsOutput)
+        }
         const errorGroupsOutput = formatErrorGroups(errorGroups, fmt)
         if (errorGroupsOutput) {
           lines.push('')
@@ -106,6 +139,12 @@ export default class ChecksGet extends AuthCommand {
       output.push(formatCheckDetail(checkWithStatus, fmt))
       output.push('')
 
+      const statsOutput = formatAnalyticsSection(analyticsResp, flags['stats-range'] ?? 'last24Hours', fmt)
+      if (statsOutput) {
+        output.push(statsOutput)
+        output.push('')
+      }
+
       const errorGroupsOutput = formatErrorGroups(errorGroups, fmt)
       if (errorGroupsOutput) {
         output.push(errorGroupsOutput)
@@ -133,6 +172,8 @@ export default class ChecksGet extends AuthCommand {
       if (nextId) {
         output.push(`  ${chalk.dim('More results:')}   checkly checks get ${args.id} --results-cursor ${nextId}`)
       }
+      output.push(`  ${chalk.dim('Change range:')}   checkly checks get ${args.id} --stats-range last7Days`)
+      output.push(`  ${chalk.dim('By region:')}     checkly checks get ${args.id} --group-by location`)
       output.push(`  ${chalk.dim('Back to list:')}   checkly checks list`)
 
       this.log(output.join('\n'))

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

@@ -5,6 +5,7 @@ import { outputFlag } from '../../helpers/flags'
 import * as api from '../../rest/api'
 import type { CheckWithStatus } from '../../formatters/checks'
 import type { OutputFormat } from '../../formatters/render'
+import { allCheckTypes } from '../../constants'
 import {
   formatChecks,
   formatSummaryBar,
@@ -41,7 +42,7 @@ export default class ChecksList extends AuthCommand {
     }),
     'type': Flags.string({
       description: 'Filter by check type.',
-      options: ['API', 'BROWSER', 'MULTI_STEP', 'HEARTBEAT', 'PLAYWRIGHT', 'TCP', 'DNS', 'ICMP', 'URL'],
+      options: allCheckTypes,
     }),
     'status': Flags.string({
       description: 'Filter by check status.',

packages/cli/src/constants.ts

@@ -3,6 +3,15 @@ export const CheckTypes = {
   BROWSER: 'BROWSER',
   HEARTBEAT: 'HEARTBEAT',
   MULTI_STEP: 'MULTI_STEP',
-}
+  PLAYWRIGHT: 'PLAYWRIGHT',
+  TCP: 'TCP',
+  ICMP: 'ICMP',
+  DNS: 'DNS',
+  URL: 'URL',
+} as const
+
+export type CheckType = typeof CheckTypes[keyof typeof CheckTypes]
+
+export const allCheckTypes = Object.values(CheckTypes)
 
 export const LOGICAL_ID_PATTERN = /^[A-Za-z0-9_\-/#.]+$/

packages/cli/src/formatters/__tests__/__fixtures__/fixtures.ts

@@ -335,6 +335,18 @@ export const apiCheckResultWithError: CheckResult = {
   } as ApiCheckResult,
 }
 
+export const browserCheckResultWithObjectErrors: CheckResult = {
+  ...browserCheckResult,
+  id: 'result-6',
+  browserCheckResult: {
+    ...browserCheckResult.browserCheckResult!,
+    // The API sometimes returns error objects instead of strings
+    errors: [
+      { name: 'Error', message: 'expect(received).toBe(expected) // Object.is equality' },
+    ] as any,
+  } as BrowserCheckResult,
+}
+
 export const minimalCheckResult: CheckResult = {
   id: 'result-4',
   checkId: 'check-6',