@skyhook-io/k8s-ui 1.6.0 → 1.6.2

package/src/components/compare/normalize.test.ts

@@ -0,0 +1,193 @@
+import { describe, it, expect } from 'vitest'
+import { normalizeForCompare, toComparableYaml } from './normalize'
+
+describe('normalizeForCompare', () => {
+  it('strips server-assigned metadata fields', () => {
+    const input = {
+      apiVersion: 'apps/v1',
+      kind: 'Deployment',
+      metadata: {
+        name: 'api',
+        namespace: 'prod',
+        resourceVersion: '12345',
+        uid: 'abc-def',
+        generation: 3,
+        creationTimestamp: '2024-01-01T00:00:00Z',
+        selfLink: '/apis/apps/v1/...',
+        managedFields: [{ manager: 'kubectl' }],
+      },
+      spec: { replicas: 3 },
+    }
+    const out = normalizeForCompare(input) as any
+    expect(out.metadata.name).toBe('api')
+    expect(out.metadata.namespace).toBe('prod')
+    expect(out.metadata.resourceVersion).toBeUndefined()
+    expect(out.metadata.uid).toBeUndefined()
+    expect(out.metadata.generation).toBeUndefined()
+    expect(out.metadata.creationTimestamp).toBeUndefined()
+    expect(out.metadata.selfLink).toBeUndefined()
+    expect(out.metadata.managedFields).toBeUndefined()
+  })
+
+  it('drops kubectl last-applied annotation', () => {
+    const input = {
+      metadata: {
+        name: 'api',
+        annotations: {
+          'kubectl.kubernetes.io/last-applied-configuration': '{"large":"blob"}',
+          'deployment.kubernetes.io/revision': '5',
+          'custom-annotation': 'keep-me',
+        },
+      },
+    }
+    const out = normalizeForCompare(input) as any
+    expect(out.metadata.annotations['custom-annotation']).toBe('keep-me')
+    expect(out.metadata.annotations['kubectl.kubernetes.io/last-applied-configuration']).toBeUndefined()
+    expect(out.metadata.annotations['deployment.kubernetes.io/revision']).toBeUndefined()
+  })
+
+  it('removes annotations object entirely when all keys are stripped', () => {
+    const input = {
+      metadata: {
+        name: 'api',
+        annotations: {
+          'kubectl.kubernetes.io/last-applied-configuration': '{}',
+        },
+      },
+    }
+    const out = normalizeForCompare(input) as any
+    expect(out.metadata.annotations).toBeUndefined()
+  })
+
+  it('strips pod-template-hash label noise', () => {
+    const input = {
+      metadata: {
+        name: 'api',
+        labels: {
+          app: 'api',
+          'pod-template-hash': 'abc123',
+          'controller-revision-hash': 'xyz789',
+        },
+      },
+    }
+    const out = normalizeForCompare(input) as any
+    expect(out.metadata.labels.app).toBe('api')
+    expect(out.metadata.labels['pod-template-hash']).toBeUndefined()
+    expect(out.metadata.labels['controller-revision-hash']).toBeUndefined()
+  })
+
+  it('drops status when specOnly is true', () => {
+    const input = {
+      spec: { replicas: 3 },
+      status: { readyReplicas: 3, conditions: [{ type: 'Available' }] },
+    }
+    const out = normalizeForCompare(input, { specOnly: true }) as any
+    expect(out.spec.replicas).toBe(3)
+    expect(out.status).toBeUndefined()
+  })
+
+  it('keeps status when specOnly is false', () => {
+    const input = {
+      spec: { replicas: 3 },
+      status: { readyReplicas: 3 },
+    }
+    const out = normalizeForCompare(input) as any
+    expect(out.status.readyReplicas).toBe(3)
+  })
+
+  it('keeps server-assigned metadata when rawMetadata is true', () => {
+    const input = {
+      metadata: {
+        name: 'api',
+        resourceVersion: '12345',
+        uid: 'abc-def',
+        managedFields: [{ manager: 'kubectl' }],
+        annotations: { 'kubectl.kubernetes.io/last-applied-configuration': '{}' },
+        labels: { 'pod-template-hash': 'abc123', app: 'api' },
+      },
+    }
+    const out = normalizeForCompare(input, { rawMetadata: true }) as any
+    expect(out.metadata.resourceVersion).toBe('12345')
+    expect(out.metadata.uid).toBe('abc-def')
+    expect(out.metadata.managedFields).toEqual([{ manager: 'kubectl' }])
+    expect(out.metadata.annotations['kubectl.kubernetes.io/last-applied-configuration']).toBe('{}')
+    expect(out.metadata.labels['pod-template-hash']).toBe('abc123')
+  })
+
+  it('still drops status when rawMetadata is true and specOnly is true', () => {
+    const input = { metadata: { name: 'api', uid: 'x' }, status: { phase: 'Running' } }
+    const out = normalizeForCompare(input, { rawMetadata: true, specOnly: true }) as any
+    expect(out.metadata.uid).toBe('x')
+    expect(out.status).toBeUndefined()
+  })
+
+  it('does not mutate the input', () => {
+    const input = {
+      metadata: { name: 'api', resourceVersion: '1', managedFields: [{ manager: 'kubectl' }] },
+    }
+    normalizeForCompare(input)
+    expect((input as any).metadata.resourceVersion).toBe('1')
+    expect((input as any).metadata.managedFields).toEqual([{ manager: 'kubectl' }])
+  })
+
+  it('returns input unchanged when not an object', () => {
+    expect(normalizeForCompare(null)).toBe(null)
+    expect(normalizeForCompare(undefined)).toBe(undefined)
+    expect(normalizeForCompare('string')).toBe('string')
+  })
+
+  it('handles missing metadata gracefully', () => {
+    const out = normalizeForCompare({ spec: { replicas: 1 } }) as any
+    expect(out.spec.replicas).toBe(1)
+    expect(out.metadata).toBeUndefined()
+  })
+
+  it('handles non-object metadata gracefully (defensive)', () => {
+    expect(() => normalizeForCompare({ metadata: 'oops', spec: {} })).not.toThrow()
+  })
+
+  it('handles null annotations object', () => {
+    const out = normalizeForCompare({ metadata: { name: 'x', annotations: null } }) as any
+    expect(out.metadata.name).toBe('x')
+    expect(out.metadata.annotations).toBeNull()
+  })
+
+  // Recursing into spec.template.metadata risks stripping user-defined selector
+  // labels that are themselves the diff signal — leave the template alone.
+  it('does NOT strip pod-template-hash inside spec.template.metadata.labels', () => {
+    const out = normalizeForCompare({
+      spec: {
+        template: {
+          metadata: {
+            labels: { app: 'api', 'pod-template-hash': 'abc' },
+          },
+        },
+      },
+    }) as any
+    expect(out.spec.template.metadata.labels['pod-template-hash']).toBe('abc')
+    expect(out.spec.template.metadata.labels.app).toBe('api')
+  })
+})
+
+describe('toComparableYaml', () => {
+  it('produces deterministic YAML output', () => {
+    const input = {
+      apiVersion: 'apps/v1',
+      kind: 'Deployment',
+      metadata: { name: 'api', namespace: 'prod', resourceVersion: '123' },
+      spec: { replicas: 3 },
+    }
+    const yaml = toComparableYaml(input)
+    expect(yaml).toContain('apiVersion: apps/v1')
+    expect(yaml).toContain('name: api')
+    expect(yaml).toContain('replicas: 3')
+    // Stripped fields should be absent
+    expect(yaml).not.toContain('resourceVersion')
+  })
+
+  it('identical inputs produce identical YAML', () => {
+    const a = { metadata: { name: 'x' }, spec: { replicas: 2 } }
+    const b = { metadata: { name: 'x' }, spec: { replicas: 2 } }
+    expect(toComparableYaml(a)).toBe(toComparableYaml(b))
+  })
+})

package/src/components/compare/normalize.ts

@@ -0,0 +1,69 @@
+import { stringify } from 'yaml'
+
+const NOISY_METADATA_KEYS = new Set([
+  'managedFields',
+  'resourceVersion',
+  'uid',
+  'generation',
+  'creationTimestamp',
+  'selfLink',
+  'deletionGracePeriodSeconds',
+])
+
+const NOISY_ANNOTATIONS = new Set([
+  'kubectl.kubernetes.io/last-applied-configuration',
+  'deployment.kubernetes.io/revision',
+  'control-plane.alpha.kubernetes.io/leader',
+  'autoscaling.alpha.kubernetes.io/conditions',
+  'autoscaling.alpha.kubernetes.io/current-metrics',
+])
+
+export interface NormalizeOptions {
+  /** When true, drop status from both sides — focuses the diff on intent. */
+  specOnly?: boolean
+  /** When true, keep server-assigned metadata noise (resourceVersion, uid, managedFields, etc.).
+   *  Off by default — the diff is signal not noise. Flip on when debugging API-level oddities. */
+  rawMetadata?: boolean
+}
+
+/**
+ * Strip server-assigned fields that always differ between two resources but
+ * don't represent meaningful configuration differences.
+ */
+export function normalizeForCompare(input: unknown, opts: NormalizeOptions = {}): unknown {
+  if (!input || typeof input !== 'object') return input
+
+  const obj = JSON.parse(JSON.stringify(input)) as Record<string, any>
+
+  if (!opts.rawMetadata && obj.metadata && typeof obj.metadata === 'object') {
+    for (const key of NOISY_METADATA_KEYS) {
+      delete obj.metadata[key]
+    }
+    if (obj.metadata.annotations && typeof obj.metadata.annotations === 'object') {
+      for (const key of NOISY_ANNOTATIONS) {
+        delete obj.metadata.annotations[key]
+      }
+      if (Object.keys(obj.metadata.annotations).length === 0) {
+        delete obj.metadata.annotations
+      }
+    }
+    if (obj.metadata.labels && typeof obj.metadata.labels === 'object') {
+      delete obj.metadata.labels['pod-template-hash']
+      delete obj.metadata.labels['controller-revision-hash']
+      if (Object.keys(obj.metadata.labels).length === 0) {
+        delete obj.metadata.labels
+      }
+    }
+  }
+
+  if (opts.specOnly) {
+    delete obj.status
+  }
+
+  return obj
+}
+
+export function toComparableYaml(input: unknown, opts: NormalizeOptions = {}): string {
+  const normalized = normalizeForCompare(input, opts)
+  return stringify(normalized, { sortMapEntries: false, lineWidth: 0 })
+}

package/src/components/compare/picks.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest'
+import { togglePick, pickIndex, COMPARE_PICK_CAP } from './picks'
+import type { NamespacedRef } from './types'
+
+const ref = (namespace: string, name: string): NamespacedRef => ({ namespace, name })
+
+describe('togglePick', () => {
+  it('adds first pick', () => {
+    expect(togglePick([], ref('prod', 'api'))).toEqual([ref('prod', 'api')])
+  })
+
+  it('adds second pick after first (A,B order preserved)', () => {
+    const after = togglePick([ref('prod', 'api')], ref('staging', 'api'))
+    expect(after).toEqual([ref('prod', 'api'), ref('staging', 'api')])
+  })
+
+  it('removes existing pick (deselect)', () => {
+    const start: NamespacedRef[] = [ref('prod', 'api'), ref('staging', 'api')]
+    expect(togglePick(start, ref('prod', 'api'))).toEqual([ref('staging', 'api')])
+  })
+
+  it('replaces oldest when at cap — clicking a third row keeps the click visible', () => {
+    const start: NamespacedRef[] = [ref('prod', 'api'), ref('staging', 'api')]
+    expect(togglePick(start, ref('dev', 'api'))).toEqual([ref('staging', 'api'), ref('dev', 'api')])
+  })
+
+  it('treats cluster-scoped (ns="") with same name as same pick', () => {
+    const start: NamespacedRef[] = [ref('', 'cluster-admin')]
+    expect(togglePick(start, ref('', 'cluster-admin'))).toEqual([])
+  })
+
+  it('treats same name in different namespaces as different picks', () => {
+    const start: NamespacedRef[] = [ref('prod', 'api')]
+    expect(togglePick(start, ref('staging', 'api'))).toEqual([ref('prod', 'api'), ref('staging', 'api')])
+  })
+
+  it('ignores ref without a name (defensive against bad row data)', () => {
+    const start: NamespacedRef[] = [ref('prod', 'api')]
+    expect(togglePick(start, ref('prod', ''))).toBe(start)
+  })
+
+  it('does not mutate the input array', () => {
+    const start: NamespacedRef[] = [ref('prod', 'api')]
+    const out = togglePick(start, ref('staging', 'api'))
+    expect(start).toEqual([ref('prod', 'api')])
+    expect(out).not.toBe(start)
+  })
+
+  it('cap is 2', () => {
+    expect(COMPARE_PICK_CAP).toBe(2)
+  })
+})
+
+describe('pickIndex', () => {
+  it('returns -1 when not in list', () => {
+    expect(pickIndex([], ref('prod', 'api'))).toBe(-1)
+  })
+
+  it('returns 0 for the first slot (A)', () => {
+    expect(pickIndex([ref('prod', 'api'), ref('staging', 'api')], ref('prod', 'api'))).toBe(0)
+  })
+
+  it('returns 1 for the second slot (B)', () => {
+    expect(pickIndex([ref('prod', 'api'), ref('staging', 'api')], ref('staging', 'api'))).toBe(1)
+  })
+
+  it('returns -1 for ref with empty name', () => {
+    expect(pickIndex([ref('prod', 'api')], ref('prod', ''))).toBe(-1)
+  })
+})
+
+describe('togglePick — cross-cluster scope', () => {
+  // Same ns/name in DIFFERENT clusters must be treated as distinct
+  // picks. Otherwise the second click on the same resource name in the
+  // second cluster would deselect the first.
+  const refC = (cid: string, namespace: string, name: string): NamespacedRef => (
+    { namespace, name, clusterId: cid }
+  )
+
+  it('keeps two same-ns-name picks from different clusters', () => {
+    const start: NamespacedRef[] = [refC('cl_a', 'kube-system', 'coredns')]
+    expect(togglePick(start, refC('cl_b', 'kube-system', 'coredns'))).toEqual([
+      refC('cl_a', 'kube-system', 'coredns'),
+      refC('cl_b', 'kube-system', 'coredns'),
+    ])
+  })
+
+  it('removes a pick keyed by clusterId when same ref re-clicked', () => {
+    const start: NamespacedRef[] = [refC('cl_a', 'kube-system', 'coredns')]
+    expect(togglePick(start, refC('cl_a', 'kube-system', 'coredns'))).toEqual([])
+  })
+
+  it('does not match scoped ref against unscoped pick of same ns+name', () => {
+    const unscoped: NamespacedRef = { namespace: 'kube-system', name: 'coredns' }
+    expect(pickIndex([unscoped], refC('cl_a', 'kube-system', 'coredns'))).toBe(-1)
+  })
+})

package/src/components/compare/picks.ts

@@ -0,0 +1,35 @@
+import type { NamespacedRef } from './types'
+
+/** Max picks the compare flow accepts. Two-way compare only. */
+export const COMPARE_PICK_CAP = 2
+
+/**
+ * Toggle a resource in the compare picks list.
+ * Existing pick → remove. Below cap → append. At cap → drop the oldest so the
+ * row click always changes state (no silent no-op).
+ */
+function sameRef(a: NamespacedRef, b: NamespacedRef): boolean {
+  // clusterId may be undefined on both (OSS single-cluster compare) or
+  // set on both (cross-cluster compare). When set, two picks with the
+  // same kind+ns+name in DIFFERENT clusters must be treated as distinct
+  // — otherwise the second pick would toggle off the first.
+  return a.clusterId === b.clusterId && a.namespace === b.namespace && a.name === b.name
+}
+
+export function togglePick(picks: NamespacedRef[], ref: NamespacedRef): NamespacedRef[] {
+  if (!ref.name) return picks
+  const existingIdx = picks.findIndex(p => sameRef(p, ref))
+  if (existingIdx >= 0) {
+    return picks.filter((_, i) => i !== existingIdx)
+  }
+  if (picks.length >= COMPARE_PICK_CAP) {
+    return [...picks.slice(1), ref]
+  }
+  return [...picks, ref]
+}
+
+/** -1 if not picked; otherwise the slot index (0 = A, 1 = B). */
+export function pickIndex(picks: NamespacedRef[], ref: NamespacedRef): number {
+  if (!ref.name) return -1
+  return picks.findIndex(p => sameRef(p, ref))
+}

package/src/components/compare/sort.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest'
+import { sortCandidates, filterCandidates } from './sort'
+
+const c = (namespace: string, name: string) => ({ namespace, name })
+
+describe('sortCandidates', () => {
+  it('puts same-namespace candidates first', () => {
+    const result = sortCandidates(
+      [c('other', 'aa'), c('prod', 'zz'), c('other', 'bb'), c('prod', 'aa')],
+      { namespace: 'prod', name: 'src' },
+    )
+    expect(result.map(r => r.namespace)).toEqual(['prod', 'prod', 'other', 'other'])
+  })
+
+  it('alphabetizes within the same-namespace group', () => {
+    const result = sortCandidates(
+      [c('prod', 'zz'), c('prod', 'aa'), c('prod', 'mm')],
+      { namespace: 'prod', name: 'src' },
+    )
+    expect(result.map(r => r.name)).toEqual(['aa', 'mm', 'zz'])
+  })
+
+  it('alphabetizes within the other-namespace group too', () => {
+    const result = sortCandidates(
+      [c('other', 'zz'), c('other', 'aa')],
+      { namespace: 'prod', name: 'src' },
+    )
+    expect(result.map(r => r.name)).toEqual(['aa', 'zz'])
+  })
+
+  it('excludes the source itself', () => {
+    const result = sortCandidates(
+      [c('prod', 'src'), c('prod', 'api')],
+      { namespace: 'prod', name: 'src' },
+    )
+    expect(result).toEqual([c('prod', 'api')])
+  })
+
+  it('tie-breaks identical names on namespace', () => {
+    const result = sortCandidates(
+      [c('zeta', 'api'), c('alpha', 'api')],
+      { namespace: 'prod', name: 'src' },
+    )
+    expect(result.map(r => r.namespace)).toEqual(['alpha', 'zeta'])
+  })
+
+  it('does not mutate input', () => {
+    const input = [c('prod', 'zz'), c('prod', 'aa')]
+    sortCandidates(input, { namespace: 'prod', name: 'src' })
+    expect(input).toEqual([c('prod', 'zz'), c('prod', 'aa')])
+  })
+
+  it('handles empty candidate list', () => {
+    expect(sortCandidates([], { namespace: 'prod', name: 'src' })).toEqual([])
+  })
+})
+
+describe('filterCandidates', () => {
+  it('returns full list for empty query', () => {
+    const list = [c('prod', 'api'), c('staging', 'web')]
+    expect(filterCandidates(list, '')).toEqual(list)
+  })
+
+  it('returns full list for whitespace-only query', () => {
+    const list = [c('prod', 'api')]
+    expect(filterCandidates(list, '   ')).toEqual(list)
+  })
+
+  it('filters by name substring (case insensitive)', () => {
+    const result = filterCandidates([c('prod', 'mongo-api'), c('prod', 'web')], 'MONGO')
+    expect(result).toEqual([c('prod', 'mongo-api')])
+  })
+
+  it('filters by namespace substring', () => {
+    const result = filterCandidates([c('mongodb', 'api'), c('redis', 'api')], 'mongo')
+    expect(result).toEqual([c('mongodb', 'api')])
+  })
+})

package/src/components/compare/sort.ts

@@ -0,0 +1,26 @@
+import type { NamespacedRef } from './types'
+
+/**
+ * Order candidates for the compare picker: same-namespace as source first
+ * (that's the obvious target), then alphabetical, then namespace tie-break.
+ * The source itself is filtered out.
+ */
+export function sortCandidates<T extends NamespacedRef>(candidates: T[], source: NamespacedRef): T[] {
+  return [...candidates]
+    .filter(c => !(c.namespace === source.namespace && c.name === source.name))
+    .sort((x, y) => {
+      const xSameNs = x.namespace === source.namespace ? 0 : 1
+      const ySameNs = y.namespace === source.namespace ? 0 : 1
+      if (xSameNs !== ySameNs) return xSameNs - ySameNs
+      const nameCmp = x.name.localeCompare(y.name)
+      if (nameCmp !== 0) return nameCmp
+      return x.namespace.localeCompare(y.namespace)
+    })
+}
+
+/** Apply a free-text filter to candidates by name OR namespace substring. */
+export function filterCandidates<T extends NamespacedRef>(candidates: T[], query: string): T[] {
+  const q = query.trim().toLowerCase()
+  if (!q) return candidates
+  return candidates.filter(c => c.name.toLowerCase().includes(q) || c.namespace.toLowerCase().includes(q))
+}

package/src/components/compare/types.ts

@@ -0,0 +1,43 @@
+export interface NamespacedRef {
+  namespace: string
+  name: string
+  /**
+   * Optional cluster scope. Populated by cross-cluster compare flows
+   * (Radar Hub fleet search) so the same `kube-system/coredns` in two
+   * different clusters can both be picked. Undefined in OSS single-
+   * cluster compare; equality then falls back to namespace+name only.
+   */
+  clusterId?: string
+  /** Display name for the cluster — surfaced in tray pills + diff side titles. */
+  clusterName?: string
+}
+
+export type CompareSide = 'a' | 'b'
+
+/** Per-side palette. One place for the A/B colors so the picker chip, drawer pill,
+ *  tray pill, and table row highlight stay in sync if the palette ever changes. */
+export const SIDE_TONES: Record<CompareSide, {
+  /** Small label chip: filled background. */
+  chipBg: string
+  /** Outlined container: border + tint. */
+  containerBorder: string
+  containerBg: string
+  /** Row-level highlight in the resources table. */
+  rowBg: string
+  rowBgHover: string
+}> = {
+  a: {
+    chipBg: 'bg-blue-400/90 text-blue-950',
+    containerBorder: 'border-blue-400/40',
+    containerBg: 'bg-blue-500/10',
+    rowBg: 'bg-blue-500/15',
+    rowBgHover: 'group-hover/row:bg-blue-500/25',
+  },
+  b: {
+    chipBg: 'bg-emerald-400/90 text-emerald-950',
+    containerBorder: 'border-emerald-400/40',
+    containerBg: 'bg-emerald-500/10',
+    rowBg: 'bg-emerald-500/15',
+    rowBgHover: 'group-hover/row:bg-emerald-500/25',
+  },
+}

package/src/components/compare/url.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest'
+import { parseRef, refToParam } from './url'
+
+describe('parseRef', () => {
+  it('parses namespaced ref into namespace and name', () => {
+    expect(parseRef('prod/api')).toEqual({ namespace: 'prod', name: 'api' })
+  })
+
+  it('treats slashless value as cluster-scoped', () => {
+    expect(parseRef('my-cluster-role')).toEqual({ namespace: '', name: 'my-cluster-role' })
+  })
+
+  it('returns null for null', () => {
+    expect(parseRef(null)).toBeNull()
+  })
+
+  it('returns null for undefined', () => {
+    expect(parseRef(undefined)).toBeNull()
+  })
+
+  it('returns null for empty string', () => {
+    expect(parseRef('')).toBeNull()
+  })
+
+  it('returns null when name is empty after the slash', () => {
+    // A URL like `?a=prod/` would otherwise leave the caller stuck in loading
+    // because the gated query has nothing to fetch.
+    expect(parseRef('prod/')).toBeNull()
+    expect(parseRef('/')).toBeNull()
+  })
+
+  it('splits on FIRST slash only — pins behavior against name shape changes', () => {
+    expect(parseRef('ns/a/b')).toEqual({ namespace: 'ns', name: 'a/b' })
+  })
+
+  it('handles namespace with leading hyphen edge case', () => {
+    expect(parseRef('-ns/api')).toEqual({ namespace: '-ns', name: 'api' })
+  })
+})
+
+describe('refToParam', () => {
+  it('emits ns/name for namespaced', () => {
+    expect(refToParam({ namespace: 'prod', name: 'api' })).toBe('prod/api')
+  })
+
+  it('emits bare name for cluster-scoped', () => {
+    expect(refToParam({ namespace: '', name: 'my-cluster-role' })).toBe('my-cluster-role')
+  })
+})
+
+describe('parseRef + refToParam round-trip', () => {
+  it('preserves namespaced refs', () => {
+    const input = 'prod/api'
+    expect(refToParam(parseRef(input)!)).toBe(input)
+  })
+
+  it('preserves cluster-scoped refs', () => {
+    const input = 'my-cluster-role'
+    expect(refToParam(parseRef(input)!)).toBe(input)
+  })
+})

package/src/components/compare/url.ts

@@ -0,0 +1,26 @@
+import type { NamespacedRef } from './types'
+
+export type ParsedRef = NamespacedRef
+
+/**
+ * Parse a `?a=` / `?b=` query value into `{namespace, name}`.
+ * Cluster-scoped resources have no slash: `"my-cluster-role"` → `{namespace: "", name: "my-cluster-role"}`.
+ * K8s names are DNS-1123 (no `/`) so splitting on the first slash is unambiguous.
+ * Empty name is rejected — a URL like `?a=prod/` would otherwise wedge the
+ * caller in an indefinite loading state since `useResource` has no name to fetch.
+ */
+export function parseRef(value: string | null | undefined): ParsedRef | null {
+  if (!value) return null
+  const slash = value.indexOf('/')
+  if (slash < 0) {
+    return { namespace: '', name: value }
+  }
+  const name = value.slice(slash + 1)
+  if (!name) return null
+  return { namespace: value.slice(0, slash), name }
+}
+
+/** Inverse of parseRef. Cluster-scoped emits just the name. */
+export function refToParam(r: NamespacedRef): string {
+  return r.namespace ? `${r.namespace}/${r.name}` : r.name
+}