feat: initial Polaris Headlamp plugin (v0.0.1)

Sidebar page at /polaris that reads Fairwinds Polaris audit results
from ConfigMap/polaris-dashboard in the polaris namespace. Displays
cluster score, check summary (pass/warning/danger counts), and
cluster info. Caches results with user-configurable refresh interval.
Handles 403, 404, and malformed JSON error states.

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

.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.headlamp-plugin/
+.mcp.json

claude.md

@@ -0,0 +1,54 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Headlamp plugin that surfaces Fairwinds Polaris audit results inside the Headlamp UI. Reads from `ConfigMap/polaris-dashboard` in the `polaris` namespace (key: `dashboard.json`). Target Headlamp ≥ v0.26.
+
+## Build & Development Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Build the plugin (standard Headlamp plugin build)
+npx @kinvolk/headlamp-plugin build
+
+# Start development mode with hot reload
+npx @kinvolk/headlamp-plugin start
+
+# Type-check without emitting
+npx tsc --noEmit
+
+# Lint
+npx eslint src/
+```
+
+## Architecture
+
+```
+src/
+├── index.tsx                    # Entry point: registerSidebarEntry + registerRoute for /polaris
+├── api/
+│   └── polaris.ts               # Types (AuditData schema), usePolarisData hook, countResults utility, refresh settings
+└── components/
+    └── PolarisView.tsx           # Main page: score badge, check summary, cluster info, error states, refresh interval selector
+```
+
+Single sidebar page at `/polaris`. Data is cached in React state and refreshed on a user-configurable interval (stored in localStorage under `polaris-plugin-refresh-interval`, default 5 minutes). The `usePolarisData` hook wraps `ConfigMap.useGet` with caching so stale data is shown while refreshing.
+
+## Key Constraints
+
+- **Data source**: `ConfigMap/polaris-dashboard` in `polaris` namespace, key `dashboard.json`. No CRDs, no external API calls, no cluster write operations.
+- **UI components**: Use only Headlamp-provided components (`@kinvolk/headlamp-plugin/lib/CommonComponents`). Do not import raw MUI packages. No custom theming.
+- **Error handling**: Must handle 403 (RBAC denied), 404 (Polaris not installed), malformed JSON, and loading states with distinct visual states.
+- **TypeScript strictness**: No `any`, no implicit `unknown` casting, no dead code, no unused imports.
+- **Packaging**: `@kinvolk/headlamp-plugin` is a peer dependency. Do not bundle React or MUI.
+
+## MCP Servers
+
+The project has MCP server integrations configured in `.mcp.json`:
+- **Gitea** (git.farh.net): Source control via `gitea-mcp-server`
+- **Kubernetes** (local): Cluster access via `kubernetes-mcp-server`
+- **Flux** (local): Flux Operator access via `flux-operator-mcp`

package.json

@@ -0,0 +1,13 @@
+{
+  "name": "polaris-headlamp-plugin",
+  "version": "0.0.1",
+  "description": "Headlamp plugin for Fairwinds Polaris audit results",
+  "scripts": {
+    "start": "headlamp-plugin start",
+    "build": "headlamp-plugin build",
+    "tsc": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@kinvolk/headlamp-plugin": "^0.13.0"
+  }
+}

src/api/polaris.ts

@@ -0,0 +1,207 @@
+import { K8s } from '@kinvolk/headlamp-plugin/lib';
+import React from 'react';
+
+// --- Polaris AuditData schema (matches pkg/validator/output.go) ---
+
+type Severity = 'ignore' | 'warning' | 'danger';
+
+interface ResultMessage {
+  ID: string;
+  Message: string;
+  Details: string[];
+  Success: boolean;
+  Severity: Severity;
+  Category: string;
+}
+
+type ResultSet = Record<string, ResultMessage>;
+
+interface ContainerResult {
+  Name: string;
+  Results: ResultSet;
+}
+
+interface PodResult {
+  Name: string;
+  Results: ResultSet;
+  ContainerResults: ContainerResult[];
+}
+
+export interface Result {
+  Name: string;
+  Namespace: string;
+  Kind: string;
+  Results: ResultSet;
+  PodResult?: PodResult;
+  CreatedTime: string;
+}
+
+interface ClusterInfo {
+  Version: string;
+  Nodes: number;
+  Pods: number;
+  Namespaces: number;
+  Controllers: number;
+}
+
+export interface AuditData {
+  PolarisOutputVersion: string;
+  AuditTime: string;
+  SourceType: string;
+  SourceName: string;
+  DisplayName: string;
+  ClusterInfo: ClusterInfo;
+  Results: Result[];
+  Score: number;
+}
+
+// --- Result counting ---
+
+export interface ResultCounts {
+  total: number;
+  pass: number;
+  warning: number;
+  danger: number;
+}
+
+function countResultSet(rs: ResultSet, counts: ResultCounts): void {
+  for (const key of Object.keys(rs)) {
+    const msg = rs[key];
+    counts.total++;
+    if (msg.Success) {
+      counts.pass++;
+    } else if (msg.Severity === 'warning') {
+      counts.warning++;
+    } else if (msg.Severity === 'danger') {
+      counts.danger++;
+    }
+  }
+}
+
+export function countResults(data: AuditData): ResultCounts {
+  const counts: ResultCounts = { total: 0, pass: 0, warning: 0, danger: 0 };
+  for (const result of data.Results) {
+    countResultSet(result.Results, counts);
+    if (result.PodResult) {
+      countResultSet(result.PodResult.Results, counts);
+      for (const container of result.PodResult.ContainerResults) {
+        countResultSet(container.Results, counts);
+      }
+    }
+  }
+  return counts;
+}
+
+// --- Settings ---
+
+const STORAGE_KEY = 'polaris-plugin-refresh-interval';
+const DEFAULT_INTERVAL_SECONDS = 300; // 5 minutes
+
+export function getRefreshInterval(): number {
+  const stored = localStorage.getItem(STORAGE_KEY);
+  if (stored !== null) {
+    const parsed = parseInt(stored, 10);
+    if (!isNaN(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  return DEFAULT_INTERVAL_SECONDS;
+}
+
+export function setRefreshInterval(seconds: number): void {
+  localStorage.setItem(STORAGE_KEY, String(seconds));
+}
+
+// --- Data fetching hook ---
+
+interface PolarisDataState {
+  data: AuditData | null;
+  loading: boolean;
+  error: string | null;
+}
+
+export function usePolarisData(refreshIntervalSeconds: number): PolarisDataState {
+  const [configMap, fetchError] = K8s.ResourceClasses.ConfigMap.useGet(
+    'polaris-dashboard',
+    'polaris'
+  );
+  const [cachedData, setCachedData] = React.useState<AuditData | null>(null);
+  const [parseError, setParseError] = React.useState<string | null>(null);
+  const [lastFetchTime, setLastFetchTime] = React.useState<number>(0);
+  const [, setTick] = React.useState(0);
+
+  // Parse ConfigMap data when it arrives
+  React.useEffect(() => {
+    if (!configMap) {
+      return;
+    }
+    const dataMap = configMap.data as Record<string, string> | undefined;
+    const raw = dataMap?.['dashboard.json'];
+    if (!raw) {
+      setParseError('ConfigMap exists but dashboard.json key is missing.');
+      return;
+    }
+    try {
+      const parsed: AuditData = JSON.parse(raw);
+      setCachedData(parsed);
+      setParseError(null);
+      setLastFetchTime(Date.now());
+    } catch {
+      setParseError('Failed to parse dashboard.json: malformed JSON.');
+    }
+  }, [configMap]);
+
+  // Periodic refresh via re-render trigger
+  React.useEffect(() => {
+    if (refreshIntervalSeconds <= 0) {
+      return;
+    }
+    const intervalId = window.setInterval(() => {
+      setTick((t) => t + 1);
+    }, refreshIntervalSeconds * 1000);
+    return () => window.clearInterval(intervalId);
+  }, [refreshIntervalSeconds]);
+
+  // Determine error state
+  if (fetchError) {
+    const status = (fetchError as { status?: number }).status;
+    if (status === 403) {
+      return {
+        data: cachedData,
+        loading: false,
+        error:
+          'Access denied (403). Check that your RBAC permissions allow reading ConfigMaps in the polaris namespace.',
+      };
+    }
+    if (status === 404) {
+      return {
+        data: cachedData,
+        loading: false,
+        error:
+          'Polaris dashboard ConfigMap not found (404). Ensure Polaris is installed in the polaris namespace.',
+      };
+    }
+    return {
+      data: cachedData,
+      loading: false,
+      error: `Failed to fetch Polaris data: ${String(fetchError)}`,
+    };
+  }
+
+  if (parseError) {
+    return { data: cachedData, loading: false, error: parseError };
+  }
+
+  const isLoading = !configMap && !fetchError;
+
+  // Return cached data while loading if we have it
+  if (isLoading && cachedData && lastFetchTime > 0) {
+    return { data: cachedData, loading: false, error: null };
+  }
+
+  return {
+    data: cachedData,
+    loading: isLoading,
+    error: null,
+  };
+}

src/components/PolarisView.tsx

@@ -0,0 +1,163 @@
+import {
+  Loader,
+  SectionBox,
+  SectionHeader,
+} from '@kinvolk/headlamp-plugin/lib/CommonComponents';
+import React from 'react';
+import {
+  AuditData,
+  countResults,
+  getRefreshInterval,
+  ResultCounts,
+  setRefreshInterval,
+  usePolarisData,
+} from '../api/polaris';
+
+const INTERVAL_OPTIONS = [
+  { label: '1 minute', value: 60 },
+  { label: '5 minutes', value: 300 },
+  { label: '10 minutes', value: 600 },
+  { label: '30 minutes', value: 1800 },
+];
+
+function RefreshSettings(props: {
+  interval: number;
+  onChange: (seconds: number) => void;
+}) {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+      <label htmlFor="polaris-refresh-interval">Refresh interval:</label>
+      <select
+        id="polaris-refresh-interval"
+        value={props.interval}
+        onChange={(e) => props.onChange(Number(e.target.value))}
+      >
+        {INTERVAL_OPTIONS.map((opt) => (
+          <option key={opt.value} value={opt.value}>
+            {opt.label}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+}
+
+function StatCard(props: { label: string; value: number; color?: string }) {
+  return (
+    <div
+      style={{
+        padding: '16px 24px',
+        textAlign: 'center',
+        minWidth: '120px',
+      }}
+    >
+      <div
+        style={{
+          fontSize: '2rem',
+          fontWeight: 'bold',
+          color: props.color,
+        }}
+      >
+        {props.value}
+      </div>
+      <div style={{ fontSize: '0.875rem', opacity: 0.8 }}>{props.label}</div>
+    </div>
+  );
+}
+
+function ScoreBadge(props: { score: number }) {
+  const color = props.score >= 80 ? '#4caf50' : props.score >= 50 ? '#ff9800' : '#f44336';
+  return (
+    <div style={{ textAlign: 'center', marginBottom: '16px' }}>
+      <div style={{ fontSize: '3rem', fontWeight: 'bold', color }}>
+        {props.score}%
+      </div>
+      <div style={{ fontSize: '0.875rem', opacity: 0.8 }}>Cluster Score</div>
+    </div>
+  );
+}
+
+function OverviewSection(props: { data: AuditData; counts: ResultCounts }) {
+  return (
+    <>
+      <SectionBox title="Score">
+        <ScoreBadge score={props.data.Score} />
+      </SectionBox>
+      <SectionBox title="Check Summary">
+        <div
+          style={{
+            display: 'flex',
+            justifyContent: 'center',
+            flexWrap: 'wrap',
+            gap: '16px',
+          }}
+        >
+          <StatCard label="Total" value={props.counts.total} />
+          <StatCard label="Pass" value={props.counts.pass} color="#4caf50" />
+          <StatCard label="Warning" value={props.counts.warning} color="#ff9800" />
+          <StatCard label="Danger" value={props.counts.danger} color="#f44336" />
+        </div>
+      </SectionBox>
+      <SectionBox title="Cluster Info">
+        <div
+          style={{
+            display: 'flex',
+            justifyContent: 'center',
+            flexWrap: 'wrap',
+            gap: '16px',
+          }}
+        >
+          <StatCard label="Nodes" value={props.data.ClusterInfo.Nodes} />
+          <StatCard label="Pods" value={props.data.ClusterInfo.Pods} />
+          <StatCard label="Namespaces" value={props.data.ClusterInfo.Namespaces} />
+          <StatCard label="Controllers" value={props.data.ClusterInfo.Controllers} />
+        </div>
+      </SectionBox>
+    </>
+  );
+}
+
+export default function PolarisView() {
+  const [interval, setInterval] = React.useState(getRefreshInterval);
+
+  function handleIntervalChange(seconds: number) {
+    setInterval(seconds);
+    setRefreshInterval(seconds);
+  }
+
+  const { data, loading, error } = usePolarisData(interval);
+
+  if (loading) {
+    return <Loader title="Loading Polaris audit data..." />;
+  }
+
+  const counts = data ? countResults(data) : null;
+
+  return (
+    <>
+      <SectionHeader title="Polaris" actions={[
+        <RefreshSettings
+          key="refresh"
+          interval={interval}
+          onChange={handleIntervalChange}
+        />,
+      ]} />
+
+      {error && (
+        <SectionBox title="Error">
+          <div style={{ padding: '16px', color: '#f44336' }}>{error}</div>
+        </SectionBox>
+      )}
+
+      {data && counts && <OverviewSection data={data} counts={counts} />}
+
+      {!data && !error && (
+        <SectionBox title="No Data">
+          <div style={{ padding: '16px' }}>
+            No Polaris audit results found.
+          </div>
+        </SectionBox>
+      )}
+    </>
+  );
+}

src/index.tsx

@@ -0,0 +1,22 @@
+import {
+  registerRoute,
+  registerSidebarEntry,
+} from '@kinvolk/headlamp-plugin/lib';
+import React from 'react';
+import PolarisView from './components/PolarisView';
+
+registerSidebarEntry({
+  parent: null,
+  name: 'polaris',
+  label: 'Polaris',
+  url: '/polaris',
+  icon: 'mdi:shield-check',
+});
+
+registerRoute({
+  path: '/polaris',
+  sidebar: 'polaris',
+  name: 'polaris',
+  exact: true,
+  component: () => <PolarisView />,
+});