@intentius/chant-lexicon-k8s 0.1.5 → 0.1.8

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "765368076fbc136a32bb79f1caf9191f01f3295cd882f843dde11f755049d49f",
+    "manifest.json": "26168ff9d5f4d906e451b0e2c9e7a868b9ae3ab366579d9abf76a45ace9a3b95",
     "meta.json": "970c70eb6eea1686f7cb8ce6ceccc46ce2e57d696d344f1dd52460e266f9a56c",
     "types/index.d.ts": "07473e029254345488bc9952585e88bcf18da79d1026cc26744027683f472554",
     "rules/hardcoded-namespace.ts": "ba3f43f2adbffdd87db20a2c45839354ceecda1b9f04f29ae31c4c077dddc7ec",
@@ -42,5 +42,5 @@
     "skills/chant-k8s-gke.md": "8938840bf9ef5ed58d6333fdd773b3dd54ecaf25a9df35e58f7f5c3355d4928f",
     "skills/chant-k8s-aks.md": "e18f0e2b055f72cd7a37deaf258d7027c2d4d3e286e8fd4975b27a1f981a3ad9"
   },
-  "composite": "cf6af567d6fd5f863bf2683642615268150b89521d63f545b452c599bb61a1b5"
+  "composite": "de04872487ff8b14bc40143791702adeea08ff52942eca65e90e6611623ed767"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "k8s",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "chantVersion": ">=0.1.0",
   "namespace": "K8s",
   "intrinsics": [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/codegen/docs.ts

@@ -548,7 +548,11 @@ const { statefulSet, service } = StatefulApp({
         slug: "composite-examples",
         title: "Examples: Composites",
         description: "Composite examples — WebApp, CronWorkload, AutoscaledService, WorkerPool, NamespaceEnv, NodeAgent",
-        content: `Composites are higher-level constructs that produce multiple coordinated K8s resources from a single function call.
+        content: `import Diagram from '../../components/Diagram.astro';
+
+Composites are higher-level constructs that produce multiple coordinated K8s resources from a single function call.
+
+<Diagram name="composite-expansion" alt="Single CockroachDbCluster composite declaration expanding into Namespace, StatefulSet, Service, ServiceAccount, NetworkPolicy, PodDisruptionBudget, and ConfigMap resources serialized to one YAML file" caption="Composite expansion: one declaration → many resources" />
 
 ## WebApp
 

package/src/describe-resources.test.ts

@@ -0,0 +1,162 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+
+const execMock = vi.fn();
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return { ...actual, exec: (cmd: string, cb: (err: Error | null, out: { stdout: string; stderr: string }) => void) => {
+    Promise.resolve(execMock(cmd)).then(
+      (out) => cb(null, out),
+      (err) => cb(err as Error, { stdout: "", stderr: "" }),
+    );
+  } };
+});
+
+const { describeResources } = await import("./describe-resources");
+
+function makeEntities(records: Array<{ name: string; entityType: string; props: Record<string, unknown> }>) {
+  return new Map(records.map((r) => [r.name, { entityType: r.entityType, props: r.props }]));
+}
+
+describe("k8s describeResources", () => {
+  beforeEach(() => {
+    execMock.mockReset();
+  });
+
+  test("queries kubectl for each declared K8s entity and maps response to ResourceMetadata", async () => {
+    execMock.mockImplementation((cmd: string) => {
+      if (cmd.includes("deployment.apps web")) {
+        return {
+          stdout: JSON.stringify({
+            metadata: { name: "web", namespace: "prod", uid: "uid-1", creationTimestamp: "2026-05-01T00:00:00Z", labels: { app: "web" } },
+            status: { readyReplicas: 3, replicas: 3 },
+          }),
+          stderr: "",
+        };
+      }
+      if (cmd.includes("service web-svc")) {
+        return {
+          stdout: JSON.stringify({
+            metadata: { name: "web-svc", namespace: "prod", uid: "uid-2", creationTimestamp: "2026-05-01T00:00:00Z" },
+          }),
+          stderr: "",
+        };
+      }
+      throw new Error(`unexpected cmd: ${cmd}`);
+    });
+
+    const entities = makeEntities([
+      { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } },
+      { name: "webSvc", entityType: "K8s::Core::Service", props: { metadata: { name: "web-svc", namespace: "prod" } } },
+    ]);
+
+    const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["web", "webSvc"], entities });
+
+    expect(result["web"]).toMatchObject({
+      type: "K8s::Apps::Deployment",
+      physicalId: "uid-1",
+      status: "READY",
+      attributes: expect.objectContaining({ namespace: "prod", labels: { app: "web" } }),
+    });
+    expect(result["webSvc"]).toMatchObject({
+      type: "K8s::Core::Service",
+      physicalId: "uid-2",
+      status: "PRESENT",
+    });
+  });
+
+  test("kubectl-not-found leaves entity out of the result (so state diff reports as missing)", async () => {
+    execMock.mockImplementation(() => { throw new Error('Error from server (NotFound): deployments.apps "missing" not found'); });
+
+    const entities = makeEntities([
+      { name: "missing", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "missing", namespace: "prod" } } },
+    ]);
+
+    const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["missing"], entities });
+
+    expect(result).toEqual({});
+  });
+
+  test("entity types without kubectl mapping are warn-skipped", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const entities = makeEntities([
+      { name: "exotic", entityType: "K8s::Custom::CRD::SomeOperator", props: { metadata: { name: "x" } } },
+    ]);
+
+    const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["exotic"], entities });
+
+    expect(result).toEqual({});
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("kubectl mapping"));
+    expect(warnSpy.mock.calls[0][0]).toContain("K8s::Custom::CRD::SomeOperator");
+    warnSpy.mockRestore();
+  });
+
+  test("Deployment with replicas != readyReplicas reports PROGRESSING", async () => {
+    execMock.mockResolvedValue({
+      stdout: JSON.stringify({
+        metadata: { name: "web", namespace: "prod", uid: "uid", creationTimestamp: "t" },
+        status: { readyReplicas: 1, replicas: 3 },
+      }),
+      stderr: "",
+    });
+
+    const entities = makeEntities([
+      { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } },
+    ]);
+
+    const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["web"], entities });
+
+    expect(result["web"].status).toBe("PROGRESSING(1/3)");
+  });
+
+  test("Pod uses status.phase as the status", async () => {
+    execMock.mockResolvedValue({
+      stdout: JSON.stringify({
+        metadata: { name: "p", namespace: "prod", uid: "uid", creationTimestamp: "t" },
+        status: { phase: "Running" },
+      }),
+      stderr: "",
+    });
+
+    const entities = makeEntities([
+      { name: "p", entityType: "K8s::Core::Pod", props: { metadata: { name: "p", namespace: "prod" } } },
+    ]);
+
+    const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["p"], entities });
+
+    expect(result["p"].status).toBe("Running");
+  });
+
+  test("namespace-less resource omits the -n flag", async () => {
+    let receivedCmd = "";
+    execMock.mockImplementation((cmd: string) => {
+      receivedCmd = cmd;
+      return {
+        stdout: JSON.stringify({
+          metadata: { name: "mynamespace", uid: "uid", creationTimestamp: "t" },
+          status: { phase: "Active" },
+        }),
+        stderr: "",
+      };
+    });
+
+    const entities = makeEntities([
+      { name: "ns", entityType: "K8s::Core::Namespace", props: { metadata: { name: "mynamespace" } } },
+    ]);
+
+    await describeResources({ environment: "prod", buildOutput: "", entityNames: ["ns"], entities });
+
+    expect(receivedCmd).not.toContain("-n");
+    expect(receivedCmd).toContain("namespace mynamespace");
+  });
+
+  test("entity without metadata.name is silently skipped", async () => {
+    const entities = makeEntities([
+      { name: "broken", entityType: "K8s::Apps::Deployment", props: {} },
+    ]);
+
+    const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["broken"], entities });
+
+    expect(result).toEqual({});
+    expect(execMock).not.toHaveBeenCalled();
+  });
+});

package/src/describe-resources.ts

@@ -0,0 +1,134 @@
+/**
+ * Live introspection of a Kubernetes cluster — implements the
+ * LexiconPlugin.describeResources() contract for the k8s lexicon.
+ *
+ * For each declared K8s entity, runs `kubectl get <kind> <name> [-n <ns>] -o json`
+ * and maps the response to a ResourceMetadata entry keyed by the chant entity
+ * name (using the props.metadata.name + props.metadata.namespace from #39's
+ * entity-prop pass-through).
+ *
+ * Resource-not-found is silent — `state diff --live` then reports it as
+ * missing (declared, not in cloud). Unknown entity types are warn-skipped;
+ * extending the KUBECTL_RESOURCE map covers more.
+ */
+
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+
+const execAsync = promisify(exec);
+
+/**
+ * Map chant entity types to `kubectl get` resource names. Add entries here
+ * as new types are needed.
+ */
+const KUBECTL_RESOURCE: Record<string, string> = {
+  "K8s::Apps::Deployment": "deployment.apps",
+  "K8s::Apps::StatefulSet": "statefulset.apps",
+  "K8s::Apps::DaemonSet": "daemonset.apps",
+  "K8s::Apps::ReplicaSet": "replicaset.apps",
+  "K8s::Core::Service": "service",
+  "K8s::Core::ConfigMap": "configmap",
+  "K8s::Core::Secret": "secret",
+  "K8s::Core::Namespace": "namespace",
+  "K8s::Core::Pod": "pod",
+  "K8s::Core::PersistentVolumeClaim": "persistentvolumeclaim",
+  "K8s::Core::ServiceAccount": "serviceaccount",
+  "K8s::Batch::Job": "job.batch",
+  "K8s::Batch::CronJob": "cronjob.batch",
+  "K8s::Networking::Ingress": "ingress.networking.k8s.io",
+  "K8s::Networking::NetworkPolicy": "networkpolicy.networking.k8s.io",
+  "K8s::Rbac::Role": "role.rbac.authorization.k8s.io",
+  "K8s::Rbac::RoleBinding": "rolebinding.rbac.authorization.k8s.io",
+  "K8s::Rbac::ClusterRole": "clusterrole.rbac.authorization.k8s.io",
+  "K8s::Rbac::ClusterRoleBinding": "clusterrolebinding.rbac.authorization.k8s.io",
+};
+
+interface KubectlResponse {
+  metadata?: {
+    name?: string;
+    namespace?: string;
+    uid?: string;
+    creationTimestamp?: string;
+    labels?: Record<string, string>;
+    resourceVersion?: string;
+  };
+  status?: {
+    phase?: string;
+    [k: string]: unknown;
+  };
+}
+
+function pruneUndefined<T extends Record<string, unknown>>(obj: T): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) out[k] = v;
+  }
+  return out;
+}
+
+function statusFromKubectl(obj: KubectlResponse): string {
+  // Different K8s resource types report status differently. Fall back to
+  // "PRESENT" if we can't extract a meaningful field.
+  const phase = obj.status?.phase;
+  if (typeof phase === "string") return phase;
+  // Deployment/StatefulSet — readyReplicas == replicas → READY
+  const status = obj.status as Record<string, unknown> | undefined;
+  if (status && typeof status.readyReplicas === "number" && typeof status.replicas === "number") {
+    return status.readyReplicas === status.replicas ? "READY" : `PROGRESSING(${status.readyReplicas}/${status.replicas})`;
+  }
+  return "PRESENT";
+}
+
+export async function describeResources(options: {
+  environment: string;
+  buildOutput: string;
+  entityNames: string[];
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+}): Promise<Record<string, ResourceMetadata>> {
+  const result: Record<string, ResourceMetadata> = {};
+  const skippedTypes = new Set<string>();
+
+  for (const [entityName, { entityType, props }] of options.entities) {
+    const kubectlResource = KUBECTL_RESOURCE[entityType];
+    if (!kubectlResource) {
+      skippedTypes.add(entityType);
+      continue;
+    }
+
+    const metadata = props.metadata as { name?: string; namespace?: string } | undefined;
+    const name = metadata?.name;
+    if (!name) continue;
+
+    const nsArg = metadata.namespace ? ["-n", metadata.namespace] : [];
+    const cmd = ["kubectl", "get", kubectlResource, name, ...nsArg, "-o", "json"].join(" ");
+
+    try {
+      const { stdout } = await execAsync(cmd);
+      const obj: KubectlResponse = JSON.parse(stdout);
+      result[entityName] = {
+        type: entityType,
+        physicalId: obj.metadata?.uid,
+        status: statusFromKubectl(obj),
+        lastUpdated: obj.metadata?.creationTimestamp,
+        attributes: pruneUndefined({
+          namespace: obj.metadata?.namespace,
+          labels: obj.metadata?.labels,
+          resourceVersion: obj.metadata?.resourceVersion,
+        }),
+      };
+    } catch {
+      // Resource not found / kubectl error — leave it out so state diff
+      // can report it as missing. Don't fail the whole snapshot.
+    }
+  }
+
+  if (skippedTypes.size > 0) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[k8s] skipped ${skippedTypes.size} entity type(s) without kubectl mapping: ${[...skippedTypes].join(", ")}`,
+    );
+  }
+
+  return result;
+}

package/src/index.ts

@@ -21,7 +21,7 @@ export {
   BatchJob, SecureIngress, ConfiguredApp, SidecarApp, MonitoredService, NetworkIsolatedApp,
   IrsaServiceAccount, AlbIngress, EbsStorageClass, EfsStorageClass, FluentBitAgent, ExternalDnsAgent, AdotCollector,
   MetricsServer, WorkloadIdentityServiceAccount, GcePdStorageClass, FilestoreStorageClass, GkeGateway, ConfigConnectorContext,
-  GceIngress, CockroachDbCluster,
+  GceIngress, CockroachDbCluster, CockroachDbRegionStack,
   RayCluster, RayJob, RayService,
   AgicIngress, AzureDiskStorageClass, AzureFileStorageClass, AzureMonitorCollector,
   AksWorkloadIdentityServiceAccount,
@@ -45,6 +45,7 @@ export type {
   GkeGatewayProps, GkeGatewayResult,
   ConfigConnectorContextProps, ConfigConnectorContextResult,
   GceIngressProps, GceIngressResult, CockroachDbClusterProps, CockroachDbClusterResult,
+  CockroachDbRegionStackConfig, CockroachDbRegionCockroachConfig, CockroachDbRegionTlsConfig,
   RayClusterProps, RayClusterResult, RayClusterSpec, ResourceSpec, HeadGroupSpec, WorkerGroupSpec,
   RayJobProps, RayJobResult,
   RayServiceProps, RayServiceResult,

package/src/plugin.test.ts

@@ -177,13 +177,13 @@ describe("k8sPlugin", () => {
   test("mcpTools() returns diff tool", () => {
     const tools = k8sPlugin.mcpTools!();
     expect(Array.isArray(tools)).toBe(true);
-    expect(tools.some((t) => t.name === "diff")).toBe(true);
+    expect(tools.some((t) => t.name === "k8s:diff")).toBe(true);
   });
 
   test("mcpResources() returns resource-catalog and examples", () => {
     const resources = k8sPlugin.mcpResources!();
     expect(Array.isArray(resources)).toBe(true);
-    expect(resources.some((r) => r.uri === "resource-catalog")).toBe(true);
+    expect(resources.some((r) => r.uri === "k8s:resource-catalog")).toBe(true);
     expect(resources.some((r) => r.uri === "examples/basic-deployment")).toBe(true);
   });
 

package/src/plugin.ts

@@ -364,12 +364,12 @@ export const service = new Service({
   },
 
   mcpTools() {
-    return [createDiffTool(k8sSerializer, "Compare current build output against previous output for Kubernetes manifests")];
+    return [createDiffTool(k8sSerializer, "Compare current build output against previous output for Kubernetes manifests", "k8s")];
   },
 
   mcpResources() {
     return [
-      createCatalogResource(import.meta.url, "Kubernetes Resource Catalog", "JSON list of all supported Kubernetes resource types", "lexicon-k8s.json"),
+      createCatalogResource(import.meta.url, "Kubernetes Resource Catalog", "JSON list of all supported Kubernetes resource types", "lexicon-k8s.json", "k8s"),
       {
         uri: "examples/basic-deployment",
         name: "Basic Deployment Example",
@@ -657,4 +657,9 @@ const { deployment, service, serviceMonitor, prometheusRule } = MonitoredService
         ],
       },
     ]),
+
+  async describeResources(options) {
+    const { describeResources } = await import("./describe-resources");
+    return describeResources(options);
+  },
 };