@skyhook-io/k8s-ui 1.5.10 → 1.5.11

package/src/components/ui/tooltip-position.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect } from 'vitest'
+import { computeTooltipPosition } from './tooltip-position'
+
+const VIEWPORT = { width: 1280, height: 800 }
+
+describe('computeTooltipPosition', () => {
+  it('returns null when the trigger has no layout (prevents 0,0 flash)', () => {
+    expect(
+      computeTooltipPosition({
+        triggerRect: { top: 0, left: 0, width: 0, height: 0 },
+        tooltipSize: { width: 80, height: 24 },
+        position: 'top',
+        viewport: VIEWPORT,
+      })
+    ).toBeNull()
+  })
+
+  it('returns a valid position even when the tooltip itself is unmeasured (size 0,0)', () => {
+    // Real situation on the very first show: tooltip portal exists but
+    // hasn't laid out yet, so its rect is (0,0,0,0). We still need a
+    // sane anchor so the next frame's update has something to refine —
+    // but it must NOT be (0,0).
+    const result = computeTooltipPosition({
+      triggerRect: { top: 12, left: 200, width: 80, height: 28 },
+      tooltipSize: { width: 0, height: 0 },
+      position: 'top',
+      viewport: VIEWPORT,
+    })
+    expect(result).not.toBeNull()
+    // Top placement above a near-the-edge trigger flips to bottom; either
+    // way the tooltip must not land at the viewport origin.
+    expect(result!.top).toBeGreaterThanOrEqual(8)
+    expect(result!.left).toBeGreaterThanOrEqual(8)
+  })
+
+  it('centers a top-placed tooltip horizontally above the trigger', () => {
+    const result = computeTooltipPosition({
+      triggerRect: { top: 200, left: 400, width: 100, height: 40 },
+      tooltipSize: { width: 80, height: 24 },
+      position: 'top',
+      viewport: VIEWPORT,
+    })
+    expect(result).toEqual({
+      // 200 - 24 - 6
+      top: 170,
+      // 400 + 50 - 40
+      left: 410,
+    })
+  })
+
+  it('flips a top-placed tooltip to bottom when the trigger is too close to the top edge (nav button case)', () => {
+    // Trigger near the top edge: "top" placement computes a negative top,
+    // so the helper must flip below.
+    const result = computeTooltipPosition({
+      triggerRect: { top: 12, left: 200, width: 80, height: 28 },
+      tooltipSize: { width: 80, height: 24 },
+      position: 'top',
+      viewport: VIEWPORT,
+    })
+    // 12 - 24 - 6 = -18 → flips to 12 + 28 + 6 = 46
+    expect(result!.top).toBe(46)
+    // Centered: 200 + 40 - 40 = 200
+    expect(result!.left).toBe(200)
+  })
+
+  it('clamps a tooltip that would overflow the right edge', () => {
+    const result = computeTooltipPosition({
+      triggerRect: { top: 100, left: 1240, width: 30, height: 28 },
+      tooltipSize: { width: 200, height: 24 },
+      position: 'top',
+      viewport: VIEWPORT,
+    })
+    // viewport.width - tooltipWidth - padding = 1280 - 200 - 8
+    expect(result!.left).toBe(1072)
+  })
+
+  it('clamps a tooltip that would overflow the left edge', () => {
+    const result = computeTooltipPosition({
+      triggerRect: { top: 100, left: 4, width: 30, height: 28 },
+      tooltipSize: { width: 200, height: 24 },
+      position: 'top',
+      viewport: VIEWPORT,
+    })
+    expect(result!.left).toBe(8)
+  })
+
+  it('places a bottom-anchored tooltip below the trigger', () => {
+    const result = computeTooltipPosition({
+      triggerRect: { top: 200, left: 400, width: 100, height: 40 },
+      tooltipSize: { width: 80, height: 24 },
+      position: 'bottom',
+      viewport: VIEWPORT,
+    })
+    expect(result!.top).toBe(246)
+  })
+
+  it('places a left-anchored tooltip to the left of the trigger and centers vertically', () => {
+    const result = computeTooltipPosition({
+      triggerRect: { top: 200, left: 400, width: 100, height: 40 },
+      tooltipSize: { width: 80, height: 24 },
+      position: 'left',
+      viewport: VIEWPORT,
+    })
+    expect(result).toEqual({
+      // 200 + 20 - 12
+      top: 208,
+      // 400 - 80 - 6
+      left: 314,
+    })
+  })
+
+  it('places a right-anchored tooltip to the right of the trigger', () => {
+    const result = computeTooltipPosition({
+      triggerRect: { top: 200, left: 400, width: 100, height: 40 },
+      tooltipSize: { width: 80, height: 24 },
+      position: 'right',
+      viewport: VIEWPORT,
+    })
+    expect(result!.left).toBe(506)
+  })
+
+  it('respects a custom padding', () => {
+    const result = computeTooltipPosition({
+      triggerRect: { top: 100, left: 4, width: 30, height: 28 },
+      tooltipSize: { width: 200, height: 24 },
+      position: 'top',
+      viewport: VIEWPORT,
+      padding: 20,
+    })
+    expect(result!.left).toBe(20)
+  })
+})

package/src/components/ui/tooltip-position.ts

@@ -0,0 +1,86 @@
+export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right'
+
+export interface Rect {
+  top: number
+  left: number
+  width: number
+  height: number
+}
+
+export interface Size {
+  width: number
+  height: number
+}
+
+export interface Viewport {
+  width: number
+  height: number
+}
+
+export interface ComputeTooltipPositionInput {
+  triggerRect: Rect
+  tooltipSize: Size
+  position: TooltipPlacement
+  viewport: Viewport
+  padding?: number
+}
+
+/**
+ * Returns null when the trigger has no layout (zero rect at origin) so the
+ * caller can render hidden until a real measurement is available, instead
+ * of painting at (0, 0).
+ */
+export function computeTooltipPosition({
+  triggerRect,
+  tooltipSize,
+  position,
+  viewport,
+  padding = 8,
+}: ComputeTooltipPositionInput): { top: number; left: number } | null {
+  const triggerHasNoLayout =
+    triggerRect.width === 0 &&
+    triggerRect.height === 0 &&
+    triggerRect.top === 0 &&
+    triggerRect.left === 0
+  if (triggerHasNoLayout) {
+    return null
+  }
+
+  const { width: tw, height: th } = tooltipSize
+
+  let top = 0
+  let left = 0
+
+  switch (position) {
+    case 'top':
+      top = triggerRect.top - th - 6
+      left = triggerRect.left + triggerRect.width / 2 - tw / 2
+      break
+    case 'bottom':
+      top = triggerRect.top + triggerRect.height + 6
+      left = triggerRect.left + triggerRect.width / 2 - tw / 2
+      break
+    case 'left':
+      top = triggerRect.top + triggerRect.height / 2 - th / 2
+      left = triggerRect.left - tw - 6
+      break
+    case 'right':
+      top = triggerRect.top + triggerRect.height / 2 - th / 2
+      left = triggerRect.left + triggerRect.width + 6
+      break
+  }
+
+  if (left < padding) left = padding
+  if (left + tw > viewport.width - padding) {
+    left = viewport.width - tw - padding
+  }
+  if (top < padding) {
+    top = triggerRect.top + triggerRect.height + 6
+  }
+  if (top + th > viewport.height - padding) {
+    top = triggerRect.top - th - 6
+  }
+  if (top < padding) top = padding
+
+  return { top, left }
+}

package/src/components/workload/WorkloadView.tsx

@@ -1,6 +1,7 @@
 import { useState, useMemo, useEffect, useRef, useCallback, type ReactNode } from 'react'
 import { flushSync } from 'react-dom'
 import { useRefreshAnimation } from '../../hooks/useRefreshAnimation'
+import { startViewTransitionSafe } from '../../utils/view-transition'
 import { PaneLoader } from '../ui/PaneLoader'
 import { useRegisterShortcuts } from '../../hooks/useKeyboardShortcuts'
 import { clsx } from 'clsx'
@@ -212,12 +213,11 @@ export function WorkloadView({
   }, [kindProp, namespace, name, initialTab])
 
   const switchView = useCallback((yaml: boolean) => {
-    const update = () => flushSync(() => setShowYaml(yaml))
-    if (document.startViewTransition) {
-      document.startViewTransition(update)
-    } else {
-      setShowYaml(yaml)
-    }
+    // startViewTransitionSafe handles the API-missing fallback AND
+    // swallows the InvalidStateError that the API rejects with when
+    // a new transition supersedes an in-flight one (rapid clicks).
+    // (SKY-833 bug 49)
+    startViewTransitionSafe(() => flushSync(() => setShowYaml(yaml)))
   }, [])
 
   const [selectedEventId, setSelectedEventId] = useState<string | null>(null)

package/src/utils/badge-colors.ts

@@ -53,6 +53,25 @@ export const HELM_STATUS_COLORS: Record<string, string> = {
   uninstalled: BADGE_SEVERITY_COLORS.neutral,
 }
 
+// Cloud instance capacity/priority badges — used by Karpenter NodeClaim and CAPI cloud-provider renderers
+// Keyed by the value as it appears in the resource (spot, on-demand, regular, onDemand)
+export const CAPACITY_TYPE_BADGE: Record<string, string> = {
+  spot: 'bg-amber-100 text-amber-800 border-amber-300 dark:bg-amber-950/50 dark:text-amber-400 dark:border-amber-700/40',
+  'on-demand': 'bg-sky-100 text-sky-700 border-sky-300 dark:bg-sky-950/50 dark:text-sky-400 dark:border-sky-700/40',
+  onDemand: 'bg-sky-100 text-sky-700 border-sky-300 dark:bg-sky-950/50 dark:text-sky-400 dark:border-sky-700/40',
+  regular: 'bg-sky-100 text-sky-700 border-sky-300 dark:bg-sky-950/50 dark:text-sky-400 dark:border-sky-700/40',
+}
+
+// AKS-style nodepool mode badges — System (control plane) vs User (workload)
+export const NODEPOOL_MODE_BADGE: Record<string, string> = {
+  System: 'bg-purple-100 text-purple-800 border-purple-300 dark:bg-purple-950/50 dark:text-purple-400 dark:border-purple-700/40',
+  User: 'bg-sky-100 text-sky-700 border-sky-300 dark:bg-sky-950/50 dark:text-sky-400 dark:border-sky-700/40',
+}
+
+// Translucent gray badge for "inactive / unknown / pending / unset / disabled" states.
+// The de-facto fallback in renderers when no severity or category applies.
+export const BADGE_INACTIVE = 'bg-gray-500/20 text-gray-400'
+
 // Best practices category colors
 export const BP_CATEGORY_BADGE: Record<string, string> = {
   Security: 'bg-purple-50 text-purple-700 border-purple-200 dark:bg-purple-950/40 dark:text-purple-400 dark:border-purple-800/40',

package/src/utils/index.ts

@@ -12,3 +12,5 @@ export * from './api-resources'
 export * from './skeleton-yaml'
 export * from './k8s-errors'
 export * from './parse-go-time'
+export * from './view-transition'
+export * from './validators'

package/src/utils/validators.test.ts

@@ -0,0 +1,207 @@
+import { describe, it, expect } from 'vitest'
+import {
+  validateRFC1123Label,
+  validateRFC1123Subdomain,
+  validateHelmReleaseName,
+  validatePort,
+} from './validators'
+
+// Validation in user-facing forms is a silent-correctness-or-loud-error
+// boundary: a regression here either lets bad input through to the API
+// (helm install fails with a server-side 422 the user can't connect to
+// their action) or rejects valid input (user is locked out of a
+// legitimate name). Pin the canonical k8s / Helm rules so any drift
+// fails the test instead of the user.
+
+describe('validateRFC1123Label', () => {
+  it('accepts simple lowercase labels', () => {
+    expect(validateRFC1123Label('default').valid).toBe(true)
+    expect(validateRFC1123Label('my-app').valid).toBe(true)
+    expect(validateRFC1123Label('a').valid).toBe(true)
+    expect(validateRFC1123Label('a1').valid).toBe(true)
+    expect(validateRFC1123Label('1a').valid).toBe(true)
+  })
+
+  it('rejects empty input', () => {
+    const r = validateRFC1123Label('')
+    expect(r.valid).toBe(false)
+    if (!r.valid) expect(r.error).toMatch(/empty/)
+  })
+
+  it('rejects uppercase characters and special chars', () => {
+    const r = validateRFC1123Label('INVALID_NAME!@#')
+    expect(r.valid).toBe(false)
+    if (!r.valid) expect(r.error).toMatch(/lowercase/)
+  })
+
+  it('rejects underscores, spaces, and other special characters', () => {
+    expect(validateRFC1123Label('my_app').valid).toBe(false)
+    expect(validateRFC1123Label('my app').valid).toBe(false)
+    expect(validateRFC1123Label('my.app').valid).toBe(false)
+    expect(validateRFC1123Label('my!app').valid).toBe(false)
+  })
+
+  it('rejects names with leading or trailing hyphens', () => {
+    expect(validateRFC1123Label('-app').valid).toBe(false)
+    expect(validateRFC1123Label('app-').valid).toBe(false)
+  })
+
+  it('rejects names longer than 63 characters', () => {
+    const r = validateRFC1123Label('a'.repeat(64))
+    expect(r.valid).toBe(false)
+    if (!r.valid) expect(r.error).toMatch(/63/)
+  })
+
+  it('accepts a name exactly 63 characters long (boundary)', () => {
+    expect(validateRFC1123Label('a'.repeat(63)).valid).toBe(true)
+  })
+})
+
+describe('validateRFC1123Subdomain', () => {
+  it('accepts dotted subdomains', () => {
+    expect(validateRFC1123Subdomain('foo.bar').valid).toBe(true)
+    expect(validateRFC1123Subdomain('foo.bar.baz').valid).toBe(true)
+    expect(validateRFC1123Subdomain('foo').valid).toBe(true)
+  })
+
+  it('rejects names with consecutive dots or trailing dots', () => {
+    expect(validateRFC1123Subdomain('foo..bar').valid).toBe(false)
+    expect(validateRFC1123Subdomain('foo.').valid).toBe(false)
+    expect(validateRFC1123Subdomain('.foo').valid).toBe(false)
+  })
+
+  it('rejects uppercase', () => {
+    expect(validateRFC1123Subdomain('Foo.bar').valid).toBe(false)
+  })
+
+  it('rejects names longer than 253 characters', () => {
+    const seg = 'a'.repeat(60)
+    const tooLong = `${seg}.${seg}.${seg}.${seg}.${seg}` // 60*5 + 4 dots = 304
+    const r = validateRFC1123Subdomain(tooLong)
+    expect(r.valid).toBe(false)
+    if (!r.valid) expect(r.error).toMatch(/253/)
+  })
+
+  it('rejects single labels longer than 63 chars even when total is under 253', () => {
+    // K8s' IsDNS1123Subdomain enforces ≤ 63 chars per dot-
+    // separated label on top of the 253-char total. Without the
+    // per-label check, a single 200-char label slipped through
+    // client-side and was rejected only server-side.
+    const huge = 'a'.repeat(200)
+    const r = validateRFC1123Subdomain(huge)
+    expect(r.valid).toBe(false)
+    if (!r.valid) expect(r.error).toMatch(/63/)
+  })
+
+  it('accepts a 63-char label at the boundary', () => {
+    expect(validateRFC1123Subdomain('a'.repeat(63)).valid).toBe(true)
+  })
+
+  it('rejects only the offending label when other labels are fine', () => {
+    const r = validateRFC1123Subdomain(`ok.${'a'.repeat(64)}.also-ok`)
+    expect(r.valid).toBe(false)
+    if (!r.valid) expect(r.error).toMatch(/63/)
+  })
+})
+
+describe('validateHelmReleaseName', () => {
+  it('rejects names with spaces and special characters', () => {
+    const r = validateHelmReleaseName('Invalid Name With Spaces!')
+    expect(r.valid).toBe(false)
+  })
+
+  it('accepts legal release names', () => {
+    expect(validateHelmReleaseName('nginx').valid).toBe(true)
+    expect(validateHelmReleaseName('my-nginx-1').valid).toBe(true)
+  })
+
+  it('rejects release names longer than 53 characters', () => {
+    const r = validateHelmReleaseName('a'.repeat(54))
+    expect(r.valid).toBe(false)
+    if (!r.valid) expect(r.error).toMatch(/53/)
+  })
+
+  it('accepts a name exactly 53 characters long (boundary)', () => {
+    expect(validateHelmReleaseName('a'.repeat(53)).valid).toBe(true)
+  })
+
+  it('error string has no trailing period (call-site composition convention)', () => {
+    // ValidationResult contract: error strings have no trailing
+    // period — the caller composes them into sentences and adds
+    // its own. InstallWizard renders `Release name {error}.` so a
+    // trailing period in this error string produced "...limit.." in
+    // the UI when a user exceeded the cap.
+    const r = validateHelmReleaseName('a'.repeat(54))
+    if (r.valid) throw new Error('expected invalid')
+    expect(r.error.endsWith('.')).toBe(false)
+  })
+
+  it('rejects dotted names (generated resource names must be DNS-1123 labels)', () => {
+    // Helm itself permits dots, but generated resource names like
+    // `<release>-<chart>-<hash>` must be valid labels. Catch the dot
+    // up front instead of letting K8s reject the apply server-side.
+    expect(validateHelmReleaseName('my.app').valid).toBe(false)
+    expect(validateHelmReleaseName('foo.bar.baz').valid).toBe(false)
+  })
+})
+
+describe('validatePort', () => {
+  it('accepts ports in [1, 65535]', () => {
+    for (const p of [1, 80, 443, 8080, 65535]) {
+      const r = validatePort(p)
+      expect(r.valid).toBe(true)
+      if (r.valid) expect(r.value).toBe(p)
+    }
+  })
+
+  it('accepts string ports', () => {
+    const r = validatePort('8080')
+    expect(r.valid).toBe(true)
+    if (r.valid) expect(r.value).toBe(8080)
+  })
+
+  it('rejects 0', () => {
+    const r = validatePort('0')
+    expect(r.valid).toBe(false)
+    if (!r.valid) expect(r.error).toMatch(/0 is reserved|between 1/)
+  })
+
+  it('rejects negative numbers', () => {
+    const r = validatePort('-1')
+    expect(r.valid).toBe(false)
+  })
+
+  it('rejects ports above 65535', () => {
+    const r = validatePort('70000')
+    expect(r.valid).toBe(false)
+    if (!r.valid) expect(r.error).toMatch(/65535|between/)
+  })
+
+  it('rejects empty input', () => {
+    expect(validatePort('').valid).toBe(false)
+  })
+
+  it('rejects non-integer formats (decimals, scientific, signed, padded)', () => {
+    expect(validatePort('1.0').valid).toBe(false)
+    expect(validatePort('1e3').valid).toBe(false)
+    expect(validatePort('+1').valid).toBe(false)
+    expect(validatePort(' 80 ').valid).toBe(false)
+    expect(validatePort('80abc').valid).toBe(false)
+  })
+
+  it('does not silently truncate (the "70000 → 7000" maxlength bug)', () => {
+    // The browser's number input was effectively dropping the 5th digit
+    // on certain triple-select+type sequences. Our validator must NOT
+    // accept the truncated value silently — it must reject the full
+    // string the user typed.
+    const r = validatePort('70000')
+    expect(r.valid).toBe(false)
+    // Make sure we don't accidentally massage the value into 7000 just
+    // because that happens to be a valid port.
+    if (!r.valid) {
+      // No `value` field on the failure shape — guarantees we never
+      // pretend the user typed something else.
+      expect((r as unknown as { value?: number }).value).toBeUndefined()
+    }
+  })
+})

package/src/utils/validators.ts

@@ -0,0 +1,178 @@
+// Pure validators for user-provided form inputs.
+//
+// Centralised here so the same rules apply to every form (Helm install
+// release name, Audit Settings ignored namespaces, Port Forward local
+// port, anything else that lands later). Reasons live next to the
+// constraints so reviewers can sanity-check us against the underlying
+// Kubernetes / Helm specs instead of folklore.
+
+/**
+ * Result shape for all validators. `valid: true` is success; otherwise
+ * `error` is a short, user-readable explanation suitable for inline
+ * form feedback (no leading capital, no trailing period — call sites
+ * compose them into sentences).
+ */
+export type ValidationResult =
+  | { valid: true }
+  | { valid: false; error: string }
+
+const RFC1123_LABEL_MAX = 63
+// Kubernetes namespace / pod / service names are RFC 1123 labels:
+// lowercase alphanumeric or '-', start and end alphanumeric, ≤63 chars.
+// Source: k8s.io/apimachinery/pkg/util/validation.IsDNS1123Label.
+const RFC1123_LABEL_RE = /^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/
+
+const RFC1123_SUBDOMAIN_MAX = 253
+// RFC 1123 subdomain = one or more labels joined by '.', total ≤253.
+const RFC1123_SUBDOMAIN_RE =
+  /^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$/
+
+const HELM_RELEASE_NAME_MAX = 53
+// Helm release names: DNS subdomain plus the additional limit of 53
+// chars so the generated resource names (`<release>-<chart>-<hash>`)
+// fit under the 63-char label cap. Source:
+// https://helm.sh/docs/chart_best_practices/conventions/#chart-names
+
+/**
+ * Validates a Kubernetes RFC 1123 label. Used for namespace names,
+ * pod / service / configmap / secret names — anything Kubernetes
+ * accepts as a single-segment identifier.
+ */
+export function validateRFC1123Label(input: string): ValidationResult {
+  if (input.length === 0) {
+    return { valid: false, error: 'must not be empty' }
+  }
+  if (input.length > RFC1123_LABEL_MAX) {
+    return {
+      valid: false,
+      error: `must be at most ${RFC1123_LABEL_MAX} characters (got ${input.length})`,
+    }
+  }
+  if (input !== input.toLowerCase()) {
+    return {
+      valid: false,
+      error: 'must be lowercase (Kubernetes names are case-sensitive and only allow [a-z0-9-])',
+    }
+  }
+  if (!RFC1123_LABEL_RE.test(input)) {
+    return {
+      valid: false,
+      error: 'must contain only lowercase letters, numbers, and hyphens, and start/end with a letter or number',
+    }
+  }
+  return { valid: true }
+}
+
+/**
+ * Validates a Kubernetes RFC 1123 subdomain (labels joined by dots).
+ * Used for Helm chart names, image registries — anything that allows
+ * dotted segments. NOT for pod/namespace names; use the label form.
+ */
+export function validateRFC1123Subdomain(input: string): ValidationResult {
+  if (input.length === 0) {
+    return { valid: false, error: 'must not be empty' }
+  }
+  if (input.length > RFC1123_SUBDOMAIN_MAX) {
+    return {
+      valid: false,
+      error: `must be at most ${RFC1123_SUBDOMAIN_MAX} characters (got ${input.length})`,
+    }
+  }
+  if (input !== input.toLowerCase()) {
+    return {
+      valid: false,
+      error: 'must be lowercase',
+    }
+  }
+  if (!RFC1123_SUBDOMAIN_RE.test(input)) {
+    return {
+      valid: false,
+      error: 'must contain only lowercase letters, numbers, hyphens, and dots, and each segment must start/end with a letter or number',
+    }
+  }
+  // Per-label cap: K8s' IsDNS1123Subdomain enforces ≤ 63 chars
+  // PER dot-separated label on top of the 253-char total. The
+  // regex above doesn't catch that; without this check a single
+  // 200-char label passes here and only fails server-side.
+  for (const label of input.split('.')) {
+    if (label.length > RFC1123_LABEL_MAX) {
+      return {
+        valid: false,
+        error: `each dot-separated label must be at most ${RFC1123_LABEL_MAX} characters (got ${label.length} for "${label}")`,
+      }
+    }
+  }
+  return { valid: true }
+}
+
+/**
+ * Validates a Helm release name. Same shape as an RFC 1123 label
+ * (no dots) capped at 53 chars (Helm's hard limit; longer names
+ * produce resources that exceed K8s' 63-char label limit).
+ *
+ * Why label and not subdomain: Helm itself permits dots in release
+ * names, but most charts compose resource names as
+ * `<release>-<chart>-<hash>` which must be valid DNS-1123 labels.
+ * A dotted release name like `my.app` produces resources whose
+ * names fail K8s label validation server-side. Reject the dot up
+ * front so the user sees a clear inline error instead of a server
+ * 422 after submit.
+ */
+export function validateHelmReleaseName(input: string): ValidationResult {
+  if (input.length === 0) {
+    return { valid: false, error: 'must not be empty' }
+  }
+  if (input.length > HELM_RELEASE_NAME_MAX) {
+    return {
+      valid: false,
+      // No trailing period — call sites compose this into a sentence
+      // and append their own.
+      error: `must be at most ${HELM_RELEASE_NAME_MAX} characters (got ${input.length}); Helm caps release names so derived resource names fit under K8s' 63-char limit`,
+    }
+  }
+  return validateRFC1123Label(input)
+}
+
+/**
+ * Validates a TCP/UDP port number provided as a free-text input.
+ *
+ * Accepts:
+ *   - a number-like string with no whitespace, no leading zeros, no '+'
+ *   - in [1, 65535]
+ *
+ * Rejects '0' (reserved), negative numbers, fractional numbers,
+ * scientific notation, and anything containing non-digit characters.
+ *
+ * Returns the parsed integer alongside the validation result so call
+ * sites don't have to re-parse.
+ */
+export type PortValidationResult =
+  | { valid: true; value: number }
+  | { valid: false; error: string }
+
+export function validatePort(input: string | number): PortValidationResult {
+  // Coerce a number argument to its decimal string form so the same
+  // strict rules (no fractional, no NaN) apply regardless of how the
+  // value reached us. We then re-parse to integer.
+  const raw = typeof input === 'number' ? String(input) : input
+  if (raw === '' || raw == null) {
+    return { valid: false, error: 'port is required' }
+  }
+  // Reject anything other than digits — '+1', '1.0', '1e3', ' 80 '
+  // all fail here. Catching them as parse failures gives clearer
+  // feedback than silently truncating via Number().
+  if (!/^\d+$/.test(raw)) {
+    return {
+      valid: false,
+      error: 'port must be a whole number between 1 and 65535',
+    }
+  }
+  const n = Number(raw)
+  if (!Number.isInteger(n) || n < 1 || n > 65535) {
+    return {
+      valid: false,
+      error: 'port must be between 1 and 65535 (0 is reserved)',
+    }
+  }
+  return { valid: true, value: n }
+}