@skyhook-io/k8s-ui 1.5.2 → 1.5.4

package/src/components/ui/drawer-components.tsx

@@ -642,6 +642,17 @@ export function getKindColor(kind: string): string {
   return getKindColorClass(kind)
 }
 
+// In drawer headers, kind sits next to a status pill ("Pod" / "Running"). Both
+// filled creates two pills competing for attention even though kind is just
+// metadata (the user already clicked the resource) and status is the signal.
+// Stripping the fills makes kind read as a label and status as a value.
+export function getKindColorOutline(kind: string): string {
+  return getKindColorClass(kind)
+    .replace(/\b(?:dark:)?bg-\S+/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
 export function formatKindName(kind: string): string {
   const k = kind.toLowerCase()
   const names: Record<string, string> = {

package/src/components/ui/index.ts

@@ -1,4 +1,11 @@
 export { Tooltip } from './Tooltip'
+export { ClusterName } from './ClusterName'
+export { EmptyState } from './EmptyState'
+export type { EmptyStateTone, EmptyStateVariant } from './EmptyState'
+export { FilterPill } from './FilterPill'
+export type { FilterPillTone } from './FilterPill'
+export { StatusDot, mapHealthToTone } from './status-tone'
+export type { StatusTone, StatusDotProps } from './status-tone'
 export { DialogPortal } from './DialogPortal'
 export { ConfirmDialog } from './ConfirmDialog'
 export { HealthRing } from './HealthRing'

package/src/components/ui/provider-logos/azure.svg

@@ -0,0 +1,23 @@
+<svg width="150" height="150" viewBox="0 0 96 96" xmlns="http://www.w3.org/2000/svg">
+    <defs>
+        <linearGradient id="e399c19f-b68f-429d-b176-18c2117ff73c" x1="-1032.172" x2="-1059.213" y1="145.312" y2="65.426" gradientTransform="matrix(1 0 0 -1 1075 158)" gradientUnits="userSpaceOnUse">
+            <stop offset="0" stop-color="#114a8b"/>
+            <stop offset="1" stop-color="#0669bc"/>
+        </linearGradient>
+        <linearGradient id="ac2a6fc2-ca48-4327-9a3c-d4dcc3256e15" x1="-1023.725" x2="-1029.98" y1="108.083" y2="105.968" gradientTransform="matrix(1 0 0 -1 1075 158)" gradientUnits="userSpaceOnUse">
+            <stop offset="0" stop-opacity=".3"/>
+            <stop offset=".071" stop-opacity=".2"/>
+            <stop offset=".321" stop-opacity=".1"/>
+            <stop offset=".623" stop-opacity=".05"/>
+            <stop offset="1" stop-opacity="0"/>
+        </linearGradient>
+        <linearGradient id="a7fee970-a784-4bb1-af8d-63d18e5f7db9" x1="-1027.165" x2="-997.482" y1="147.642" y2="68.561" gradientTransform="matrix(1 0 0 -1 1075 158)" gradientUnits="userSpaceOnUse">
+            <stop offset="0" stop-color="#3ccbf4"/>
+            <stop offset="1" stop-color="#2892df"/>
+        </linearGradient>
+    </defs>
+    <path fill="url(#e399c19f-b68f-429d-b176-18c2117ff73c)" d="M33.338 6.544h26.038l-27.03 80.087a4.152 4.152 0 0 1-3.933 2.824H8.149a4.145 4.145 0 0 1-3.928-5.47L29.404 9.368a4.152 4.152 0 0 1 3.934-2.825z"/>
+    <path fill="#0078d4" d="M71.175 60.261h-41.29a1.911 1.911 0 0 0-1.305 3.309l26.532 24.764a4.171 4.171 0 0 0 2.846 1.121h23.38z"/>
+    <path fill="url(#ac2a6fc2-ca48-4327-9a3c-d4dcc3256e15)" d="M33.338 6.544a4.118 4.118 0 0 0-3.943 2.879L4.252 83.917a4.14 4.14 0 0 0 3.908 5.538h20.787a4.443 4.443 0 0 0 3.41-2.9l5.014-14.777 17.91 16.705a4.237 4.237 0 0 0 2.666.972H81.24L71.024 60.261l-29.781.007L59.47 6.544z"/>
+    <path fill="url(#a7fee970-a784-4bb1-af8d-63d18e5f7db9)" d="M66.595 9.364a4.145 4.145 0 0 0-3.928-2.82H33.648a4.146 4.146 0 0 1 3.928 2.82l25.184 74.62a4.146 4.146 0 0 1-3.928 5.472h29.02a4.146 4.146 0 0 0 3.927-5.472z"/>
+</svg>

package/src/components/ui/status-tone.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest'
+import { mapHealthToTone } from './status-tone'
+
+// Inputs flow in from heterogeneous sources (Problems API, Audit findings,
+// multi-cluster aggregation). A regression here is a silent visual
+// downgrade — the wrong color renders, no error thrown. Pin the
+// canonical mappings so a vocabulary drift on either side fails loudly.
+
+describe('mapHealthToTone', () => {
+  it('maps healthy/ok/success/passing → healthy', () => {
+    expect(mapHealthToTone('healthy')).toBe('healthy')
+    expect(mapHealthToTone('ok')).toBe('healthy')
+    expect(mapHealthToTone('success')).toBe('healthy')
+    expect(mapHealthToTone('passing')).toBe('healthy')
+  })
+
+  it('maps degraded/warning/warn/medium → degraded', () => {
+    expect(mapHealthToTone('degraded')).toBe('degraded')
+    expect(mapHealthToTone('warning')).toBe('degraded')
+    expect(mapHealthToTone('warn')).toBe('degraded')
+    expect(mapHealthToTone('medium')).toBe('degraded')
+  })
+
+  it('maps high/alert → alert (the orange tier)', () => {
+    expect(mapHealthToTone('high')).toBe('alert')
+    expect(mapHealthToTone('alert')).toBe('alert')
+  })
+
+  it('maps unhealthy/danger/critical/error/failed → unhealthy', () => {
+    expect(mapHealthToTone('unhealthy')).toBe('unhealthy')
+    expect(mapHealthToTone('danger')).toBe('unhealthy')
+    expect(mapHealthToTone('critical')).toBe('unhealthy')
+    expect(mapHealthToTone('error')).toBe('unhealthy')
+    expect(mapHealthToTone('failed')).toBe('unhealthy')
+  })
+
+  it('maps neutral/info → neutral', () => {
+    expect(mapHealthToTone('neutral')).toBe('neutral')
+    expect(mapHealthToTone('info')).toBe('neutral')
+  })
+
+  it('falls back to unknown for unrecognized input', () => {
+    expect(mapHealthToTone('frobnicated')).toBe('unknown')
+    expect(mapHealthToTone('')).toBe('unknown')
+    expect(mapHealthToTone('low')).toBe('unknown')
+  })
+
+  it('is case-insensitive', () => {
+    expect(mapHealthToTone('CRITICAL')).toBe('unhealthy')
+    expect(mapHealthToTone('Healthy')).toBe('healthy')
+    expect(mapHealthToTone('HIGH')).toBe('alert')
+  })
+})

package/src/components/ui/status-tone.tsx

@@ -0,0 +1,104 @@
+import { type HealthLevel } from '../resources/resource-utils';
+
+// StatusDot + mapHealthToTone are typed helpers over the canonical OSS
+// status vocabulary defined in `packages/k8s-ui/src/theme/components.css`.
+// The `.status-*` CSS classes (.status-healthy / .status-degraded /
+// .status-alert / .status-unhealthy / .status-neutral / .status-unknown)
+// are the source of truth for color; this file just adds dot-color
+// tokens and a tone-normalization helper.
+//
+// For pill-shaped status badges, use the canonical pattern directly:
+//
+//   <span className={`badge ${healthColors[tone]}`}>...</span>
+//
+// (no typed component wrapper — that pattern is widely used across OSS
+// already and adding a wrapper would split the call sites without
+// fitting the count-badge / button-pill / icon-pill variants OSS uses).
+//
+// Vocabulary (escalating urgency):
+//   healthy   — running / live / passing  (emerald)
+//   degraded  — warning / slow / advisory (amber)
+//   alert     — high-severity but not foundationally broken (orange)
+//   unhealthy — critical / failing / blocked (red)
+//   neutral   — informational / scope counter (sky)
+//   unknown   — terminal / unknown / no-action-needed (slate)
+//
+// `alert` is the intermediate tier between degraded and unhealthy. Used
+// when the data carries a 3-step severity gradient (Problems pages,
+// Audit findings, Cert expiry buckets) — without it, "high" and either
+// "critical" or "medium" collapse into the same color.
+
+// `StatusTone` is intentionally a name for `HealthLevel` at call sites
+// where the concern is presentation (which color/dot to render) rather
+// than the underlying health state — `tone: StatusTone` reads cleaner
+// than `tone: HealthLevel`. The two are structurally identical today;
+// keeping a separate name preserves the option to diverge later (e.g.
+// a future `brand` tone that isn't a health state).
+export type StatusTone = HealthLevel;
+
+// Solid dot colors for StatusDot (the .status-* CSS classes are pill
+// backgrounds, too soft for a tiny solid indicator). Kept in lockstep
+// with the CSS palette so tone names stay aligned.
+const DOT_CLASS: Record<StatusTone, string> = {
+  healthy: 'bg-emerald-500',
+  degraded: 'bg-amber-500',
+  alert: 'bg-orange-500',
+  unhealthy: 'bg-rose-500',
+  neutral: 'bg-sky-500',
+  unknown: 'bg-slate-400',
+};
+
+// Normalize the variety of severity / health vocabularies that flow in
+// from APIs (Problems, Audit, multi-cluster aggregation endpoints) onto
+// a single tone. Inputs are case-insensitive. Returns 'unknown' for
+// unrecognized values.
+export function mapHealthToTone(input: string): StatusTone {
+  switch (input.toLowerCase()) {
+    case 'healthy':
+    case 'ok':
+    case 'success':
+    case 'passing':
+      return 'healthy';
+    case 'degraded':
+    case 'warning':
+    case 'warn':
+    case 'medium':
+      return 'degraded';
+    case 'high':
+    case 'alert':
+      return 'alert';
+    case 'unhealthy':
+    case 'danger':
+    case 'critical':
+    case 'error':
+    case 'failed':
+      return 'unhealthy';
+    case 'neutral':
+    case 'info':
+      return 'neutral';
+    default:
+      return 'unknown';
+  }
+}
+
+export interface StatusDotProps {
+  tone: StatusTone;
+  /** Dot diameter. Default 'sm'. */
+  size?: 'xs' | 'sm' | 'md';
+  className?: string;
+}
+
+const DOT_SIZE: Record<NonNullable<StatusDotProps['size']>, string> = {
+  xs: 'h-1 w-1',
+  sm: 'h-1.5 w-1.5',
+  md: 'h-2 w-2',
+};
+
+export function StatusDot({ tone, size = 'sm', className = '' }: StatusDotProps) {
+  return (
+    <span
+      className={`inline-block rounded-full ${DOT_SIZE[size]} ${DOT_CLASS[tone]} ${className}`}
+      aria-hidden
+    />
+  );
+}

package/src/components/workload/WorkloadView.tsx

@@ -39,7 +39,7 @@ import {
 import { ResourceActionsBar } from '../shared/ResourceActionsBar'
 import { EditableYamlView, SaveSuccessAnimation } from '../shared/EditableYamlView'
 import { ResourceRendererDispatch, getResourceStatus, type RendererOverrides } from '../shared/ResourceRendererDispatch'
-import { getKindColor, formatKindName } from '../ui/drawer-components'
+import { getKindColorOutline, formatKindName } from '../ui/drawer-components'
 
 type TabType = 'overview' | 'timeline' | 'logs' | 'metrics' | 'yaml'
 
@@ -360,7 +360,7 @@ export function WorkloadView({
           {/* Top row: badges and controls */}
           <div className="flex items-center justify-between px-4 pt-3 pb-2">
             <div className="flex items-center gap-2 flex-wrap">
-              <span className={clsx('badge', getKindColor(apiKind))}>
+              <span className={clsx('badge', getKindColorOutline(apiKind))}>
                 {formatKindName(apiKind)}
               </span>
               {status && (
@@ -497,7 +497,7 @@ export function WorkloadView({
               </button>
             </div>
             <div className="flex items-center gap-3 text-sm text-theme-text-secondary">
-              <span className={clsx('badge', getKindColor(apiKind))}>
+              <span className={clsx('badge', getKindColorOutline(apiKind))}>
                 {formatKindName(apiKind)}
               </span>
               {status && (

package/src/theme/components.css

@@ -146,6 +146,13 @@
     border-color: light-dark(#fcd34d, rgba(120, 53, 15, 0.4));
   }
 
+  /* Alert - orange (between degraded and unhealthy; "high severity"). */
+  .status-alert {
+    background-color: light-dark(#ffedd5, rgba(124, 45, 18, 0.5));
+    color: light-dark(#c2410c, #fdba74);
+    border-color: light-dark(#fdba74, rgba(124, 45, 18, 0.4));
+  }
+
   /* Unhealthy/Error - red */
   .status-unhealthy {
     background-color: light-dark(#fee2e2, rgba(127, 29, 29, 0.5));

package/src/utils/badge-colors.ts

@@ -36,6 +36,7 @@ export const OPERATION_BADGE_COLORS: Record<string, string> = {
 export const HEALTH_BADGE_COLORS: Record<string, string> = {
   healthy: BADGE_SEVERITY_COLORS.success,
   degraded: BADGE_SEVERITY_COLORS.warning,
+  alert: BADGE_SEVERITY_COLORS.alert,
   unhealthy: BADGE_SEVERITY_COLORS.error,
   unknown: BADGE_SEVERITY_COLORS.neutral,
 }

package/src/utils/context-name.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect } from 'vitest'
+import { parseContextName } from './context-name'
+
+describe('parseContextName', () => {
+  describe('GKE', () => {
+    it('parses zonal cluster context', () => {
+      const r = parseContextName('gke_my-project_us-east1-b_prod-cluster')
+      expect(r.provider).toBe('GKE')
+      expect(r.account).toBe('my-project')
+      expect(r.region).toBe('us-east1-b')
+      expect(r.clusterName).toBe('prod-cluster')
+    })
+
+    it('parses regional cluster context', () => {
+      const r = parseContextName('gke_my-project_us-central1_my-cluster')
+      expect(r.provider).toBe('GKE')
+      expect(r.region).toBe('us-central1')
+      expect(r.clusterName).toBe('my-cluster')
+    })
+
+    it('handles cluster names with underscores in the suffix', () => {
+      const r = parseContextName('gke_proj_us-east1-b_my_funky_cluster')
+      expect(r.provider).toBe('GKE')
+      expect(r.clusterName).toBe('my_funky_cluster')
+    })
+
+    it('does NOT match arbitrary 3-underscore strings (regression)', () => {
+      // The pre-fix regex `^gke_([^_]+)_([^_]+)_(.+)$` matched anything
+      // gke-prefixed with three underscores. Tightened: zone must contain
+      // a digit (every real GCP zone does).
+      const r = parseContextName('gke_a_b_c')
+      expect(r.provider).toBeNull()
+    })
+
+    it('rejects non-GKE-zone middle segment', () => {
+      const r = parseContextName('gke_proj_notazone_cluster')
+      expect(r.provider).toBeNull()
+      expect(r.clusterName).toBe('gke_proj_notazone_cluster')
+    })
+  })
+
+  describe('EKS ARN', () => {
+    it('parses standard EKS ARN', () => {
+      const r = parseContextName('arn:aws:eks:us-east-1:123456789012:cluster/my-prod')
+      expect(r.provider).toBe('EKS')
+      expect(r.account).toBe('123456789012')
+      expect(r.region).toBe('us-east-1')
+      expect(r.clusterName).toBe('my-prod')
+    })
+
+    it('handles cluster names with hyphens', () => {
+      const r = parseContextName('arn:aws:eks:eu-central-1:982081053473:cluster/us-east-1-nonprod')
+      expect(r.clusterName).toBe('us-east-1-nonprod')
+    })
+  })
+
+  describe('eksctl format', () => {
+    it('parses user@cluster.region.eksctl.io', () => {
+      const r = parseContextName('admin@my-cluster.us-east-1.eksctl.io')
+      expect(r.provider).toBe('EKS')
+      expect(r.account).toBe('eksctl')
+      expect(r.region).toBe('us-east-1')
+      expect(r.clusterName).toBe('my-cluster')
+    })
+  })
+
+  describe('AKS', () => {
+    it('parses clusterUser_<rg>_<name>', () => {
+      const r = parseContextName('clusterUser_my-rg_my-cluster')
+      expect(r.provider).toBe('AKS')
+      expect(r.account).toBe('my-rg')
+      expect(r.clusterName).toBe('my-cluster')
+    })
+
+    it('parses clusterAdmin_<rg>_<name>', () => {
+      const r = parseContextName('clusterAdmin_prod-rg_prod-cluster')
+      expect(r.provider).toBe('AKS')
+      expect(r.account).toBe('prod-rg')
+      expect(r.clusterName).toBe('prod-cluster')
+    })
+
+    it('does NOT mis-tag user-named clusters that happen to contain "aks"', () => {
+      // Regression: pre-fix used substring match for "aks", so these
+      // false-positive matched.
+      expect(parseContextName('tracks-prod').provider).toBeNull()
+      expect(parseContextName('my-aks-experiment').provider).toBeNull()
+      expect(parseContextName('aks').provider).toBeNull()
+    })
+  })
+
+  describe('unknown', () => {
+    it('returns user-named cluster unchanged', () => {
+      const r = parseContextName('my-staging-cluster')
+      expect(r.provider).toBeNull()
+      expect(r.clusterName).toBe('my-staging-cluster')
+      expect(r.raw).toBe('my-staging-cluster')
+    })
+
+    it('returns empty-shape unknown for unparseable input', () => {
+      const r = parseContextName('something-else-entirely')
+      expect(r.provider).toBeNull()
+      expect(r.account).toBeNull()
+      expect(r.region).toBeNull()
+    })
+  })
+})

package/src/utils/context-name.ts

@@ -11,8 +11,19 @@ export interface ParsedContextName {
  * and cluster name. Used by the context switcher and error views.
  */
 export function parseContextName(name: string): ParsedContextName {
-  // GKE format: gke_{project}_{region}_{cluster-name}
-  const gkeMatch = name.match(/^gke_([^_]+)_([^_]+)_(.+)$/)
+  // GKE format: gke_{project}_{region|zone}_{cluster-name}
+  // Region is `<continent>-<direction><number>` (e.g. us-east1, europe-west1,
+  // asia-northeast1). Zonal clusters append `-<letter>` (e.g. us-east1-b).
+  // We require the middle segment to contain at least one digit; that rules
+  // out garbage like `gke_a_b_c` and `gke_proj_notazone_cluster` while
+  // matching all real GCP zone shapes without enumerating them.
+  //
+  // Linear-time form: a non-consuming lookahead asserts "this segment
+  // contains a digit" up to the next `_`, then a single greedy capture
+  // consumes the segment. The earlier `[a-z0-9-]*\d[a-z0-9-]*` shape had
+  // overlapping repeats around the digit, which CodeQL flagged as a
+  // polynomial backtracking risk.
+  const gkeMatch = name.match(/^gke_([a-z][a-z0-9-]+)_(?=[a-z0-9-]*\d)([a-z][a-z0-9-]*)_(.+)$/)
   if (gkeMatch) {
     const [, project, region, cluster] = gkeMatch
     return {
@@ -50,13 +61,21 @@ export function parseContextName(name: string): ParsedContextName {
     }
   }
 
-  // AKS format: try to detect
-  if (name.toLowerCase().includes('aks') || name.includes('.azure.') || name.includes('azurecr')) {
+  // AKS context format produced by `az aks get-credentials`:
+  //   clusterUser_<resourceGroup>_<clusterName>
+  //   clusterAdmin_<resourceGroup>_<clusterName>
+  // Strict regex — the prior heuristic (substring match for "aks") was a
+  // correctness bug that mis-tagged user-named clusters like "tracks-prod"
+  // (contains "aks") or "my-aks-experiment". Better to fall through to
+  // unknown than to mis-parse.
+  const aksMatch = name.match(/^cluster(?:User|Admin)_([^_]+)_(.+)$/)
+  if (aksMatch) {
+    const [, resourceGroup, cluster] = aksMatch
     return {
       provider: 'AKS',
-      account: null,
+      account: resourceGroup,
       region: null,
-      clusterName: name,
+      clusterName: cluster,
       raw: name,
     }
   }

package/src/utils/index.ts

@@ -1,4 +1,5 @@
 export * from './format'
+export * from './pluralize'
 export * from './badge-colors'
 export * from './resource-icons'
 export * from './navigation'

package/src/utils/navigation.ts

@@ -1,4 +1,5 @@
 import type { SelectedResource, ResourceRef, APIResource } from '../types/core'
+import { englishPlural } from './pluralize'
 
 /**
  * Canonical callback type for navigating to a resource.
@@ -93,14 +94,9 @@ export function kindToPlural(kind: string): string {
   }
   if (aliases[kindLower]) return aliases[kindLower]
 
-  // Fallback: English pluralization rules (covers *Class→*classes, *Policy→*policies, *Repository→*repositories, etc.)
-  if (kindLower.endsWith('s') || kindLower.endsWith('x') || kindLower.endsWith('ch') || kindLower.endsWith('sh')) {
-    return kindLower + 'es'
-  }
-  if (kindLower.endsWith('y') && !/[aeiou]y$/.test(kindLower)) {
-    return kindLower.slice(0, -1) + 'ies'
-  }
-  return kindLower + 's'
+  // Fallback: English pluralization rules (shared with pluralize() in
+  // utils/pluralize.ts so a rule change updates both call paths).
+  return englishPlural(kindLower)
 }
 
 /**

package/src/utils/pluralize.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect } from 'vitest'
+import { englishPlural, pluralNoun, pluralize } from './pluralize'
+
+describe('englishPlural', () => {
+  describe('default +s', () => {
+    it('handles common nouns', () => {
+      expect(englishPlural('cluster')).toBe('clusters')
+      expect(englishPlural('cert')).toBe('certs')
+      expect(englishPlural('chart')).toBe('charts')
+    })
+  })
+
+  describe('s/x/ch/sh → +es', () => {
+    it('handles s ending', () => {
+      expect(englishPlural('class')).toBe('classes')
+      expect(englishPlural('ingress')).toBe('ingresses')
+    })
+
+    it('handles x ending', () => {
+      expect(englishPlural('box')).toBe('boxes')
+    })
+
+    it('handles ch ending', () => {
+      expect(englishPlural('match')).toBe('matches')
+    })
+
+    it('handles sh ending', () => {
+      expect(englishPlural('brush')).toBe('brushes')
+    })
+  })
+
+  describe('consonant-y → -y +ies', () => {
+    it('handles policy', () => {
+      expect(englishPlural('policy')).toBe('policies')
+    })
+
+    it('handles directory', () => {
+      expect(englishPlural('directory')).toBe('directories')
+    })
+
+    it('preserves vowel-y → +s (does not strip)', () => {
+      expect(englishPlural('day')).toBe('days')
+      expect(englishPlural('boy')).toBe('boys')
+    })
+  })
+
+  describe('case insensitivity in detection', () => {
+    // The detection regex is case-insensitive (recognizes Class as ending
+    // in 's'-class, POLICY as consonant-y) but the rule appends lowercase
+    // suffixes. In practice all callers normalize to lowercase before
+    // calling — kindToPlural() lowercases its input; pluralize() takes
+    // user-controlled nouns which are typically lowercase.
+    it('detects rule-applicable suffixes regardless of case', () => {
+      expect(englishPlural('Class')).toBe('Classes')   // +es appended lowercase
+      expect(englishPlural('Box')).toBe('Boxes')
+    })
+  })
+})
+
+describe('pluralNoun', () => {
+  it('returns singular for n===1', () => {
+    expect(pluralNoun(1, 'cluster')).toBe('cluster')
+  })
+
+  it('returns plural for n!==1', () => {
+    expect(pluralNoun(0, 'cluster')).toBe('clusters')
+    expect(pluralNoun(2, 'cluster')).toBe('clusters')
+    expect(pluralNoun(99, 'cluster')).toBe('clusters')
+  })
+
+  it('uses englishPlural rules by default', () => {
+    expect(pluralNoun(2, 'policy')).toBe('policies')
+    expect(pluralNoun(2, 'class')).toBe('classes')
+  })
+
+  it('honors explicit override for irregular plurals', () => {
+    expect(pluralNoun(2, 'index', 'indices')).toBe('indices')
+    expect(pluralNoun(1, 'index', 'indices')).toBe('index')
+  })
+})
+
+describe('pluralize', () => {
+  it('formats count + noun', () => {
+    expect(pluralize(0, 'cluster')).toBe('0 clusters')
+    expect(pluralize(1, 'cluster')).toBe('1 cluster')
+    expect(pluralize(5, 'cluster')).toBe('5 clusters')
+  })
+
+  it('handles irregular plurals via override', () => {
+    expect(pluralize(3, 'index', 'indices')).toBe('3 indices')
+  })
+
+  it('applies English rules without override', () => {
+    expect(pluralize(2, 'policy')).toBe('2 policies')
+    expect(pluralize(2, 'class')).toBe('2 classes')
+    expect(pluralize(2, 'box')).toBe('2 boxes')
+  })
+})

package/src/utils/pluralize.ts

@@ -0,0 +1,60 @@
+// Pluralization helpers shared across the package. Layered:
+//
+//   englishPlural(noun)         — lowest level. Applies regular English
+//                                 rules: s/x/ch/sh → +es; consonant-y → ies;
+//                                 default +s.
+//   pluralNoun(n, sing, plural?) — count-aware plural form (just the noun).
+//                                 Returns sing when n===1, else plural
+//                                 (or englishPlural(sing) if not specified).
+//   pluralize(n, sing, plural?)  — count + plural noun phrase. "1 cluster"
+//                                 / "5 clusters" / "0 issues".
+//
+// kindToPlural() in navigation.ts also delegates to englishPlural for its
+// English fallback, so both call paths share rule changes automatically.
+
+/**
+ * Apply English regular-pluralization rules to a noun.
+ *
+ *   englishPlural('class')  → 'classes'   (s/x/ch/sh → +es)
+ *   englishPlural('policy') → 'policies'  (consonant-y → -y +ies)
+ *   englishPlural('boy')    → 'boys'      (vowel-y → +s)
+ *   englishPlural('cluster')→ 'clusters'  (default +s)
+ *
+ * Case-insensitive matching but preserves input case. Doesn't handle
+ * irregular plurals (child/children, mouse/mice) — callers should pass
+ * an explicit override for those.
+ */
+export function englishPlural(noun: string): string {
+  if (/(?:s|x|ch|sh)$/i.test(noun)) return noun + 'es';
+  if (/[^aeiou]y$/i.test(noun)) return noun.slice(0, -1) + 'ies';
+  return noun + 's';
+}
+
+/**
+ * Count-aware plural noun. Returns the singular when n===1, else the
+ * plural form (passed-in or derived via englishPlural).
+ *
+ *   pluralNoun(1, 'cluster') → 'cluster'
+ *   pluralNoun(5, 'cluster') → 'clusters'
+ *   pluralNoun(0, 'cluster') → 'clusters'   (zero is plural in English)
+ *   pluralNoun(2, 'index', 'indices') → 'indices'  (irregular override)
+ */
+export function pluralNoun(n: number, singular: string, plural?: string): string {
+  return n === 1 ? singular : (plural ?? englishPlural(singular));
+}
+
+/**
+ * Format a count + noun phrase with proper agreement.
+ *
+ *   pluralize(1, 'cluster') → '1 cluster'
+ *   pluralize(5, 'cluster') → '5 clusters'
+ *   pluralize(0, 'issue')   → '0 issues'
+ *   pluralize(3, 'index', 'indices') → '3 indices'
+ *
+ * For Kubernetes resource kinds with structured plural mappings (e.g.
+ * NetworkPolicy → networkpolicies), use kindToPlural() from
+ * navigation.ts to produce the noun, then pass it as the plural override.
+ */
+export function pluralize(n: number, singular: string, plural?: string): string {
+  return `${n} ${pluralNoun(n, singular, plural)}`;
+}