@thotischner/observability-mcp 1.6.0 → 1.7.1

package/config/sources.yaml

@@ -24,6 +24,16 @@ sources:
     url: http://loki:3100
     enabled: true
 
+  # Kubernetes topology source. Reads $KUBECONFIG which the compose file
+  # points at the in-network kubeconfig written by the k3s-init
+  # container. In a non-demo run the file is absent and the connector
+  # reports "down" cleanly. url/auth are unused — the connector reads
+  # server + credentials from kubeconfig.
+  - name: kubernetes
+    type: kubernetes
+    url: ""
+    enabled: true
+
 settings:
   checkIntervalMs: 30000
   defaultSensitivity: medium

package/dist/connectors/interface.d.ts

@@ -1,4 +1,4 @@
-import type { SignalType, ConnectorHealth, ServiceInfo, MetricInfo, MetricQuery, MetricResult, LogQuery, LogResult, SourceConfig, MetricDefinition } from "../types.js";
+import type { SignalType, ConnectorHealth, ServiceInfo, MetricInfo, MetricQuery, MetricResult, LogQuery, LogResult, SourceConfig, MetricDefinition, Resource, Edge, TopologySnapshot, TopologyChangeListener } from "../types.js";
 export interface ObservabilityConnector {
     readonly name: string;
     readonly type: string;
@@ -14,4 +14,14 @@ export interface ObservabilityConnector {
     listAvailableMetrics?(service: string): Promise<MetricInfo[]>;
     queryMetrics?(params: MetricQuery): Promise<MetricResult>;
     queryLogs?(params: LogQuery): Promise<LogResult>;
+    /** Current in-memory resource list. Should be O(1) — backed by the watch cache. */
+    listResources?(): Promise<Resource[]>;
+    /** Current in-memory edge list. Should be O(1) — backed by the watch cache. */
+    listEdges?(): Promise<Edge[]>;
+    /** Atomic snapshot of resources+edges with a monotonic revision counter. */
+    getTopologySnapshot?(): Promise<TopologySnapshot>;
+    /** Subscribe to incremental changes. Returns an unsubscribe function. */
+    watchTopology?(listener: TopologyChangeListener): () => void;
 }
+/** Narrowing guard: connectors that implement the topology capability. */
+export declare function isTopologyProvider(c: ObservabilityConnector): c is ObservabilityConnector & Required<Pick<ObservabilityConnector, "listResources" | "listEdges" | "getTopologySnapshot" | "watchTopology">>;

package/dist/connectors/interface.js

@@ -1 +1,7 @@
-export {};
+/** Narrowing guard: connectors that implement the topology capability. */
+export function isTopologyProvider(c) {
+    return (typeof c.listResources === "function" &&
+        typeof c.listEdges === "function" &&
+        typeof c.getTopologySnapshot === "function" &&
+        typeof c.watchTopology === "function");
+}

package/dist/connectors/kubernetes-client.d.ts

@@ -0,0 +1,3 @@
+import type { SourceConfig } from "../types.js";
+import type { InformerFactory } from "./kubernetes.js";
+export declare function createInformerFactory(config: SourceConfig): Promise<InformerFactory>;

package/dist/connectors/kubernetes-client.js

@@ -0,0 +1,90 @@
+// Thin adapter around @kubernetes/client-node. Kept in its own file so
+// the connector class itself stays SDK-free and unit-testable. The
+// loader imports this lazily so installations that don't configure a
+// kubernetes source don't pay the import cost.
+import { KubeConfig, CoreV1Api, AppsV1Api, makeInformer, } from "@kubernetes/client-node";
+function buildKubeConfig(config) {
+    const kc = new KubeConfig();
+    if (config.auth?.type === "bearer" && config.auth.token && config.url) {
+        // Explicit cluster + bearer-token config (e.g. remote cluster).
+        kc.loadFromOptions({
+            clusters: [
+                {
+                    name: config.name,
+                    server: config.url,
+                    skipTLSVerify: !!(config.tls?.skipVerify ?? config.tlsSkipVerify),
+                    caFile: config.tls?.caCert,
+                },
+            ],
+            users: [{ name: config.name, token: config.auth.token }],
+            contexts: [{ name: config.name, cluster: config.name, user: config.name }],
+            currentContext: config.name,
+        });
+        return kc;
+    }
+    // Fall through: in-cluster (ServiceAccount) or KUBECONFIG/~/.kube/config.
+    // In @kubernetes/client-node v1.x, loadFromCluster() no longer throws
+    // when env+files are missing — it silently produces "https://undefined:undefined".
+    // Detect in-cluster context by the well-known env vars instead.
+    const inCluster = !!process.env.KUBERNETES_SERVICE_HOST && !!process.env.KUBERNETES_SERVICE_PORT;
+    if (inCluster) {
+        kc.loadFromCluster();
+    }
+    else {
+        kc.loadFromDefault();
+    }
+    return kc;
+}
+function wrapInformer(inf) {
+    return {
+        on(event, handler) {
+            // @kubernetes/client-node Informer emits 'add' | 'update' | 'delete' | 'error'.
+            inf.on(event, handler);
+        },
+        async start() {
+            await inf.start();
+        },
+        async stop() {
+            await inf.stop();
+        },
+    };
+}
+export async function createInformerFactory(config) {
+    const kc = buildKubeConfig(config);
+    const core = kc.makeApiClient(CoreV1Api);
+    const apps = kc.makeApiClient(AppsV1Api);
+    // In @kubernetes/client-node v1+, list*() resolves directly to the
+    // KubernetesListObject (with `items`), not the v0.x `{ body, response }`.
+    const podInformer = makeInformer(kc, "/api/v1/pods", () => core.listPodForAllNamespaces());
+    const nodeInformer = makeInformer(kc, "/api/v1/nodes", () => core.listNode());
+    const nsInformer = makeInformer(kc, "/api/v1/namespaces", () => core.listNamespace());
+    const depInformer = makeInformer(kc, "/apis/apps/v1/deployments", () => apps.listDeploymentForAllNamespaces());
+    const rsInformer = makeInformer(kc, "/apis/apps/v1/replicasets", () => apps.listReplicaSetForAllNamespaces());
+    return {
+        pods: () => wrapInformer(podInformer),
+        nodes: () => wrapInformer(nodeInformer),
+        deployments: () => wrapInformer(depInformer),
+        replicaSets: () => wrapInformer(rsInformer),
+        namespaces: () => wrapInformer(nsInformer),
+        async healthCheck() {
+            const start = Date.now();
+            try {
+                // /version is unauthenticated on most clusters and exists on all.
+                await core.getAPIResources();
+                return { ok: true, latencyMs: Date.now() - start };
+            }
+            catch (err) {
+                return { ok: false, latencyMs: Date.now() - start, message: String(err) };
+            }
+        },
+        async close() {
+            await Promise.all([
+                podInformer.stop().catch(() => { }),
+                nodeInformer.stop().catch(() => { }),
+                nsInformer.stop().catch(() => { }),
+                depInformer.stop().catch(() => { }),
+                rsInformer.stop().catch(() => { }),
+            ]);
+        },
+    };
+}

package/dist/connectors/kubernetes-graph.d.ts

@@ -0,0 +1,73 @@
+import type { Resource, Edge, TopologySnapshot, TopologyChangeEvent } from "../types.js";
+export interface KubeObjectMeta {
+    name?: string;
+    namespace?: string;
+    uid?: string;
+    labels?: Record<string, string>;
+    ownerReferences?: Array<{
+        kind: string;
+        name: string;
+        uid?: string;
+    }>;
+}
+export interface KubePod {
+    metadata?: KubeObjectMeta;
+    spec?: {
+        nodeName?: string;
+    };
+    status?: {
+        phase?: string;
+    };
+}
+export interface KubeNode {
+    metadata?: KubeObjectMeta;
+    status?: {
+        conditions?: Array<{
+            type: string;
+            status: string;
+        }>;
+    };
+}
+export interface KubeDeployment {
+    metadata?: KubeObjectMeta;
+}
+export interface KubeReplicaSet {
+    metadata?: KubeObjectMeta;
+}
+export interface KubeNamespace {
+    metadata?: KubeObjectMeta;
+}
+export declare function namespacedId(kind: string, namespace: string, name: string): string;
+export declare function clusterScopedId(kind: string, name: string): string;
+export declare function podResource(source: string, pod: KubePod): Resource | undefined;
+export declare function nodeResource(source: string, node: KubeNode): Resource | undefined;
+export declare function deploymentResource(source: string, d: KubeDeployment): Resource | undefined;
+export declare function replicaSetResource(source: string, rs: KubeReplicaSet): Resource | undefined;
+export declare function namespaceResource(source: string, ns: KubeNamespace): Resource | undefined;
+export declare function podEdges(source: string, pod: KubePod): Edge[];
+export declare function replicaSetEdges(source: string, rs: KubeReplicaSet): Edge[];
+export declare function deploymentEdges(source: string, d: KubeDeployment): Edge[];
+/**
+ * In-memory store of the connector's current view of the cluster. The
+ * watch event handlers call add/remove and the store emits incremental
+ * change events to subscribers.
+ *
+ * Edges are tracked per-owner-resource so when a pod is deleted we can
+ * cleanly remove its outgoing edges without scanning the whole edge map.
+ */
+export declare class TopologyStore {
+    private readonly source;
+    private resources;
+    private edgesByOwner;
+    private rev;
+    private listeners;
+    constructor(source: string);
+    get revision(): number;
+    subscribe(listener: (e: TopologyChangeEvent) => void): () => void;
+    private emit;
+    upsertResource(r: Resource, ownedEdges: Edge[]): void;
+    removeResource(id: string): void;
+    listResources(): Resource[];
+    listEdges(): Edge[];
+    snapshot(): TopologySnapshot;
+}

package/dist/connectors/kubernetes-graph.js

@@ -0,0 +1,257 @@
+// Pure graph-building helpers for the Kubernetes connector.
+//
+// All Kubernetes object → Resource/Edge translation lives here so it can
+// be unit-tested without a live API server. The connector class
+// (kubernetes.ts) wires these into the watch event handlers.
+// --- Canonical IDs ------------------------------------------------------
+export function namespacedId(kind, namespace, name) {
+    return `k8s:${kind}:${namespace}/${name}`;
+}
+export function clusterScopedId(kind, name) {
+    return `k8s:${kind}:${name}`;
+}
+// --- Resource builders --------------------------------------------------
+const baseLabels = (m) => ({ ...(m?.labels ?? {}) });
+const baseAttrs = (m) => m?.uid ? { uid: m.uid } : {};
+export function podResource(source, pod) {
+    const name = pod.metadata?.name;
+    const namespace = pod.metadata?.namespace;
+    if (!name || !namespace)
+        return undefined;
+    return {
+        id: namespacedId("pod", namespace, name),
+        kind: "pod",
+        name,
+        source,
+        labels: baseLabels(pod.metadata),
+        attributes: {
+            ...baseAttrs(pod.metadata),
+            ...(pod.status?.phase ? { phase: pod.status.phase } : {}),
+            ...(pod.spec?.nodeName ? { nodeName: pod.spec.nodeName } : {}),
+        },
+    };
+}
+export function nodeResource(source, node) {
+    const name = node.metadata?.name;
+    if (!name)
+        return undefined;
+    const ready = node.status?.conditions?.find((c) => c.type === "Ready")?.status;
+    return {
+        id: clusterScopedId("node", name),
+        kind: "node",
+        name,
+        source,
+        labels: baseLabels(node.metadata),
+        attributes: { ...baseAttrs(node.metadata), ...(ready ? { ready } : {}) },
+    };
+}
+export function deploymentResource(source, d) {
+    const name = d.metadata?.name;
+    const namespace = d.metadata?.namespace;
+    if (!name || !namespace)
+        return undefined;
+    return {
+        id: namespacedId("deployment", namespace, name),
+        kind: "deployment",
+        name,
+        source,
+        labels: baseLabels(d.metadata),
+        attributes: baseAttrs(d.metadata),
+    };
+}
+export function replicaSetResource(source, rs) {
+    const name = rs.metadata?.name;
+    const namespace = rs.metadata?.namespace;
+    if (!name || !namespace)
+        return undefined;
+    return {
+        id: namespacedId("replicaset", namespace, name),
+        kind: "replicaset",
+        name,
+        source,
+        labels: baseLabels(rs.metadata),
+        attributes: baseAttrs(rs.metadata),
+    };
+}
+export function namespaceResource(source, ns) {
+    const name = ns.metadata?.name;
+    if (!name)
+        return undefined;
+    return {
+        id: clusterScopedId("namespace", name),
+        kind: "namespace",
+        name,
+        source,
+        labels: baseLabels(ns.metadata),
+        attributes: baseAttrs(ns.metadata),
+    };
+}
+// --- Edge builders ------------------------------------------------------
+const KNOWN_OWNER_KINDS = {
+    Deployment: "deployment",
+    ReplicaSet: "replicaset",
+    StatefulSet: "statefulset",
+    DaemonSet: "daemonset",
+    Job: "job",
+    CronJob: "cronjob",
+};
+function ownerEdges(source, fromId, meta, namespace) {
+    const out = [];
+    for (const ref of meta?.ownerReferences ?? []) {
+        const kind = KNOWN_OWNER_KINDS[ref.kind];
+        if (!kind)
+            continue;
+        out.push({
+            from: fromId,
+            to: namespacedId(kind, namespace, ref.name),
+            relation: "OWNED_BY",
+            source,
+            confidence: 1.0,
+        });
+    }
+    return out;
+}
+export function podEdges(source, pod) {
+    const name = pod.metadata?.name;
+    const namespace = pod.metadata?.namespace;
+    if (!name || !namespace)
+        return [];
+    const fromId = namespacedId("pod", namespace, name);
+    const edges = [
+        {
+            from: fromId,
+            to: clusterScopedId("namespace", namespace),
+            relation: "IN_NAMESPACE",
+            source,
+            confidence: 1.0,
+        },
+    ];
+    if (pod.spec?.nodeName) {
+        edges.push({
+            from: fromId,
+            to: clusterScopedId("node", pod.spec.nodeName),
+            relation: "RUNS_ON",
+            source,
+            confidence: 1.0,
+        });
+    }
+    edges.push(...ownerEdges(source, fromId, pod.metadata, namespace));
+    return edges;
+}
+export function replicaSetEdges(source, rs) {
+    const name = rs.metadata?.name;
+    const namespace = rs.metadata?.namespace;
+    if (!name || !namespace)
+        return [];
+    const fromId = namespacedId("replicaset", namespace, name);
+    return [
+        {
+            from: fromId,
+            to: clusterScopedId("namespace", namespace),
+            relation: "IN_NAMESPACE",
+            source,
+            confidence: 1.0,
+        },
+        ...ownerEdges(source, fromId, rs.metadata, namespace),
+    ];
+}
+export function deploymentEdges(source, d) {
+    const name = d.metadata?.name;
+    const namespace = d.metadata?.namespace;
+    if (!name || !namespace)
+        return [];
+    return [
+        {
+            from: namespacedId("deployment", namespace, name),
+            to: clusterScopedId("namespace", namespace),
+            relation: "IN_NAMESPACE",
+            source,
+            confidence: 1.0,
+        },
+    ];
+}
+// --- Graph store --------------------------------------------------------
+/**
+ * In-memory store of the connector's current view of the cluster. The
+ * watch event handlers call add/remove and the store emits incremental
+ * change events to subscribers.
+ *
+ * Edges are tracked per-owner-resource so when a pod is deleted we can
+ * cleanly remove its outgoing edges without scanning the whole edge map.
+ */
+export class TopologyStore {
+    source;
+    resources = new Map();
+    edgesByOwner = new Map(); // ownerId → outgoing edges
+    rev = 0;
+    listeners = new Set();
+    constructor(source) {
+        this.source = source;
+    }
+    get revision() {
+        return this.rev;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    emit(e) {
+        this.rev++;
+        for (const l of this.listeners) {
+            try {
+                l(e);
+            }
+            catch {
+                // listener errors must not poison the watch loop
+            }
+        }
+    }
+    upsertResource(r, ownedEdges) {
+        const existed = this.resources.has(r.id);
+        this.resources.set(r.id, r);
+        // Replace edges originating from this resource atomically.
+        const prev = this.edgesByOwner.get(r.id) ?? [];
+        this.edgesByOwner.set(r.id, ownedEdges);
+        this.emit({ type: existed ? "resource_updated" : "resource_added", resource: r });
+        // Diff edges so subscribers see precise add/remove.
+        const prevKeys = new Set(prev.map(edgeKey));
+        const nextKeys = new Set(ownedEdges.map(edgeKey));
+        for (const e of prev)
+            if (!nextKeys.has(edgeKey(e)))
+                this.emit({ type: "edge_removed", edge: e });
+        for (const e of ownedEdges)
+            if (!prevKeys.has(edgeKey(e)))
+                this.emit({ type: "edge_added", edge: e });
+    }
+    removeResource(id) {
+        const r = this.resources.get(id);
+        if (!r)
+            return;
+        this.resources.delete(id);
+        const prev = this.edgesByOwner.get(id) ?? [];
+        this.edgesByOwner.delete(id);
+        for (const e of prev)
+            this.emit({ type: "edge_removed", edge: e });
+        this.emit({ type: "resource_removed", resource: r });
+    }
+    listResources() {
+        return Array.from(this.resources.values());
+    }
+    listEdges() {
+        const out = [];
+        for (const arr of this.edgesByOwner.values())
+            out.push(...arr);
+        return out;
+    }
+    snapshot() {
+        return {
+            source: this.source,
+            resources: this.listResources(),
+            edges: this.listEdges(),
+            revision: this.rev,
+        };
+    }
+}
+function edgeKey(e) {
+    return `${e.from}|${e.relation}|${e.to}`;
+}

package/dist/connectors/kubernetes-graph.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/connectors/kubernetes-graph.test.js

@@ -0,0 +1,150 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { TopologyStore, podResource, podEdges, nodeResource, deploymentResource, replicaSetResource, replicaSetEdges, namespacedId, clusterScopedId, } from "./kubernetes-graph.js";
+const SRC = "test-cluster";
+const samplePod = {
+    metadata: {
+        name: "checkout-7f89d",
+        namespace: "default",
+        uid: "pod-uid-1",
+        labels: { app: "checkout" },
+        ownerReferences: [{ kind: "ReplicaSet", name: "checkout-7f89", uid: "rs-uid-1" }],
+    },
+    spec: { nodeName: "worker-1" },
+    status: { phase: "Running" },
+};
+describe("kubernetes-graph: resource builders", () => {
+    it("podResource produces a stable namespaced ID and preserves labels/uid", () => {
+        const r = podResource(SRC, samplePod);
+        assert.ok(r);
+        assert.equal(r.id, "k8s:pod:default/checkout-7f89d");
+        assert.equal(r.kind, "pod");
+        assert.equal(r.source, SRC);
+        assert.deepEqual(r.labels, { app: "checkout" });
+        assert.equal(r.attributes.uid, "pod-uid-1");
+        assert.equal(r.attributes.phase, "Running");
+    });
+    it("returns undefined when metadata is missing", () => {
+        assert.equal(podResource(SRC, {}), undefined);
+        assert.equal(podResource(SRC, { metadata: { name: "x" } }), undefined); // no namespace
+    });
+    it("nodeResource is cluster-scoped (no namespace in ID)", () => {
+        const r = nodeResource(SRC, {
+            metadata: { name: "worker-1" },
+            status: { conditions: [{ type: "Ready", status: "True" }] },
+        });
+        assert.equal(r.id, "k8s:node:worker-1");
+        assert.equal(r.attributes.ready, "True");
+    });
+    it("deploymentResource builds a namespaced ID", () => {
+        const r = deploymentResource(SRC, {
+            metadata: { name: "checkout", namespace: "default" },
+        });
+        assert.equal(r.id, "k8s:deployment:default/checkout");
+    });
+    it("replicaSetResource builds a namespaced ID", () => {
+        const r = replicaSetResource(SRC, {
+            metadata: { name: "checkout-7f89", namespace: "default" },
+        });
+        assert.equal(r.id, "k8s:replicaset:default/checkout-7f89");
+    });
+});
+describe("kubernetes-graph: edge builders", () => {
+    it("podEdges emits RUNS_ON, IN_NAMESPACE and OWNED_BY", () => {
+        const edges = podEdges(SRC, samplePod);
+        const rels = edges.map((e) => e.relation).sort();
+        assert.deepEqual(rels, ["IN_NAMESPACE", "OWNED_BY", "RUNS_ON"]);
+        const runs = edges.find((e) => e.relation === "RUNS_ON");
+        assert.equal(runs.to, "k8s:node:worker-1");
+        assert.equal(runs.confidence, 1.0);
+        assert.equal(runs.source, SRC);
+        const owned = edges.find((e) => e.relation === "OWNED_BY");
+        assert.equal(owned.to, "k8s:replicaset:default/checkout-7f89");
+    });
+    it("podEdges skips RUNS_ON when the pod has no nodeName yet (Pending)", () => {
+        const pending = {
+            metadata: { name: "p", namespace: "default" },
+            status: { phase: "Pending" },
+        };
+        const edges = podEdges(SRC, pending);
+        assert.equal(edges.find((e) => e.relation === "RUNS_ON"), undefined);
+        assert.ok(edges.find((e) => e.relation === "IN_NAMESPACE"));
+    });
+    it("replicaSetEdges chains OWNED_BY to a Deployment", () => {
+        const edges = replicaSetEdges(SRC, {
+            metadata: {
+                name: "checkout-7f89",
+                namespace: "default",
+                ownerReferences: [{ kind: "Deployment", name: "checkout" }],
+            },
+        });
+        const owned = edges.find((e) => e.relation === "OWNED_BY");
+        assert.ok(owned);
+        assert.equal(owned.to, "k8s:deployment:default/checkout");
+    });
+    it("ignores unknown owner kinds (forward-compat)", () => {
+        const edges = podEdges(SRC, {
+            metadata: {
+                name: "p",
+                namespace: "default",
+                ownerReferences: [{ kind: "FrobnicatorSet", name: "x" }],
+            },
+        });
+        assert.equal(edges.find((e) => e.relation === "OWNED_BY"), undefined);
+    });
+});
+describe("TopologyStore", () => {
+    it("upsertResource adds resource + edges and emits diffs", () => {
+        const store = new TopologyStore(SRC);
+        const events = [];
+        store.subscribe((e) => events.push(e.type));
+        const r = podResource(SRC, samplePod);
+        store.upsertResource(r, podEdges(SRC, samplePod));
+        assert.equal(store.listResources().length, 1);
+        assert.equal(store.listEdges().length, 3);
+        assert.ok(events.includes("resource_added"));
+        assert.equal(events.filter((t) => t === "edge_added").length, 3);
+        assert.ok(store.revision > 0);
+    });
+    it("update replaces edges atomically — emits removed/added for diff only", () => {
+        const store = new TopologyStore(SRC);
+        store.upsertResource(podResource(SRC, samplePod), podEdges(SRC, samplePod));
+        const events = [];
+        store.subscribe((e) => events.push(e.type));
+        // Pod moved to a new node — RUNS_ON edge should be replaced, others stable.
+        const moved = { ...samplePod, spec: { nodeName: "worker-2" } };
+        store.upsertResource(podResource(SRC, moved), podEdges(SRC, moved));
+        assert.equal(events.filter((t) => t === "edge_added").length, 1);
+        assert.equal(events.filter((t) => t === "edge_removed").length, 1);
+        assert.equal(events.filter((t) => t === "resource_updated").length, 1);
+        const runs = store.listEdges().find((e) => e.relation === "RUNS_ON");
+        assert.equal(runs.to, "k8s:node:worker-2");
+    });
+    it("removeResource drops the resource and all its outgoing edges", () => {
+        const store = new TopologyStore(SRC);
+        store.upsertResource(podResource(SRC, samplePod), podEdges(SRC, samplePod));
+        const id = namespacedId("pod", "default", "checkout-7f89d");
+        store.removeResource(id);
+        assert.equal(store.listResources().length, 0);
+        assert.equal(store.listEdges().length, 0);
+    });
+    it("snapshot() carries the current revision counter", () => {
+        const store = new TopologyStore(SRC);
+        const r0 = store.revision;
+        store.upsertResource(nodeResource(SRC, { metadata: { name: "n1" } }), []);
+        const snap = store.snapshot();
+        assert.ok(snap.revision > r0);
+        assert.equal(snap.source, SRC);
+        assert.equal(snap.resources[0].id, clusterScopedId("node", "n1"));
+    });
+    it("subscriber errors don't kill the store", () => {
+        const store = new TopologyStore(SRC);
+        store.subscribe(() => {
+            throw new Error("boom");
+        });
+        let saw = 0;
+        store.subscribe(() => saw++);
+        store.upsertResource(nodeResource(SRC, { metadata: { name: "n1" } }), []);
+        assert.ok(saw > 0);
+    });
+});

package/dist/connectors/kubernetes.d.ts

@@ -0,0 +1,53 @@
+import type { ObservabilityConnector } from "./interface.js";
+import type { SourceConfig, ConnectorHealth, ServiceInfo, MetricDefinition, Resource, Edge, TopologySnapshot, TopologyChangeListener, SignalType } from "../types.js";
+import { type KubePod, type KubeNode, type KubeDeployment, type KubeReplicaSet, type KubeNamespace } from "./kubernetes-graph.js";
+export interface Informer<T> {
+    on(event: "add" | "update", handler: (obj: T) => void): void;
+    on(event: "delete", handler: (obj: T) => void): void;
+    on(event: "error", handler: (err: unknown) => void): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface InformerFactory {
+    pods(): Informer<KubePod>;
+    nodes(): Informer<KubeNode>;
+    deployments(): Informer<KubeDeployment>;
+    replicaSets(): Informer<KubeReplicaSet>;
+    namespaces(): Informer<KubeNamespace>;
+    /** Cheap health probe — should hit /version or /healthz. */
+    healthCheck(): Promise<{
+        ok: boolean;
+        latencyMs: number;
+        message?: string;
+    }>;
+    close(): Promise<void>;
+}
+export type InformerFactoryProvider = (config: SourceConfig) => Promise<InformerFactory>;
+export declare function setDefaultInformerFactoryProvider(p: InformerFactoryProvider): void;
+export declare class KubernetesConnector implements ObservabilityConnector {
+    readonly type = "kubernetes";
+    readonly signalType: SignalType;
+    name: string;
+    private store;
+    private warnedVocab;
+    private factory?;
+    private informers;
+    private providerOverride?;
+    /** Constructor injection used by tests. */
+    constructor(provider?: InformerFactoryProvider);
+    connect(config: SourceConfig): Promise<void>;
+    private applyPod;
+    private applyNode;
+    private applyDeployment;
+    private applyReplicaSet;
+    private applyNamespace;
+    healthCheck(): Promise<ConnectorHealth>;
+    disconnect(): Promise<void>;
+    getDefaultMetrics(): MetricDefinition[];
+    getMetrics(): MetricDefinition[];
+    listServices(): Promise<ServiceInfo[]>;
+    listResources(): Promise<Resource[]>;
+    listEdges(): Promise<Edge[]>;
+    getTopologySnapshot(): Promise<TopologySnapshot>;
+    watchTopology(listener: TopologyChangeListener): () => void;
+}