@intentius/chant-lexicon-k8s 0.30.0 → 0.32.0

package/src/lifecycle-integration.test.ts

@@ -1,34 +1,41 @@
 /**
  * Cross-lexicon lifecycle integration (#163) — Kubernetes row.
  *
- * Drives the REAL k8sPlugin through core's live-import driver and the changeset
- * path, with the `kubectl` edge mocked.
+ * Drives the REAL k8sPlugin through core's live-import driver and the
+ * changeset path, with the cluster edge faked at
+ * `@kubernetes/client-node`'s request layer (chant #1074, previously at
+ * `kubectl`). The plugin's own `describeResources` / `exportResources` are what
+ * run; only the socket is replaced, and only a literal kubeconfig is ever read.
  */
 import { describe, test, expect, vi, beforeEach } from "vitest";
 import { mkdtempSync, rmSync, readdirSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-const execMock = vi.fn();
-vi.mock("node:child_process", async () => {
-  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+/**
+ * The plugin reaches the cluster through `./api/connect`'s default connector,
+ * which is the one thing a test must not let run for real: it would read the
+ * developer's kubeconfig. Replacing the module swaps in a connector backed by
+ * `fakeCluster`, which still builds a real client over a literal kubeconfig.
+ */
+const clusterState: { objects: Record<string, unknown>; fail?: (path: string) => { status: number; body: unknown } | undefined } = {
+  objects: {},
+};
+
+vi.mock("./api/connect", async () => {
+  const { fakeCluster } = await import("./api/fake-cluster");
   return {
-    ...actual,
-    exec: (
-      cmd: string,
-      cb: (err: Error | null, out: { stdout: string; stderr: string }) => void,
-    ) => {
-      const r = execMock(cmd);
-      queueMicrotask(() =>
-        r instanceof Error
-          ? cb(r, { stdout: "", stderr: "" })
-          : cb(null, r as { stdout: string; stderr: string }),
-      );
-    },
+    defaultK8sConnector: (options: unknown) =>
+      fakeCluster({
+        objects: clusterState.objects as never,
+        respond: (req) => clusterState.fail?.(req.path),
+      }).connector(options as never),
   };
 });
 
 const { k8sPlugin } = await import("./plugin");
+const { objectKey } = await import("./api/fake-cluster");
+const { statusBody } = await import("@intentius/chant-k8s-client/testing");
 const { liveImportFromPlugins } = await import("@intentius/chant/cli/commands/import");
 const { buildChangeSet } = await import("@intentius/chant/lifecycle/change-set");
 const { normalizeObservation } = await import("@intentius/chant/observation");
@@ -42,24 +49,24 @@ const liveDeployment = {
   spec: { replicas: 3, selector: { matchLabels: { app: "web" } } },
 };
 
-const emptyList = { stdout: JSON.stringify({ items: [] }), stderr: "" };
+const observedWeb = {
+  apiVersion: "apps/v1",
+  kind: "Deployment",
+  metadata: { name: "web", namespace: "prod", uid: "uid-1" },
+  status: { readyReplicas: 3, replicas: 3 },
+};
 
 describe("k8s lifecycle integration (#163)", () => {
-  beforeEach(() => execMock.mockReset());
+  beforeEach(() => {
+    clusterState.objects = {};
+    clusterState.fail = undefined;
+  });
 
   test("live-import driver: real exportResources → IR → generated source", async () => {
-    execMock.mockImplementation((cmd?: string) =>
-      cmd?.includes("get deployment.apps")
-        ? { stdout: JSON.stringify({ items: [liveDeployment] }), stderr: "" }
-        : emptyList,
-    );
+    clusterState.objects = { [objectKey("apps/v1", "Deployment", "web", "default")]: liveDeployment };
     const output = mkdtempSync(join(tmpdir(), "chant-k8s-li-"));
     try {
-      const result = await liveImportFromPlugins([k8sPlugin], {
-        environment: "prod",
-        output,
-        force: true,
-      });
+      const result = await liveImportFromPlugins([k8sPlugin], { environment: "prod", output, force: true });
       expect(result.success).toBe(true);
       expect(result.generatedFiles.length).toBeGreaterThan(0);
       const all = readdirSync(output)
@@ -73,17 +80,7 @@ describe("k8s lifecycle integration (#163)", () => {
   });
 
   test("changeset path: real describeResources → buildChangeSet verdicts", async () => {
-    execMock.mockImplementation((cmd?: string) =>
-      cmd?.includes("deployment.apps web")
-        ? {
-            stdout: JSON.stringify({
-              metadata: { name: "web", namespace: "prod", uid: "uid-1" },
-              status: { readyReplicas: 3, replicas: 3 },
-            }),
-            stderr: "",
-          }
-        : new Error("not found"),
-    );
+    clusterState.objects = { [objectKey("apps/v1", "Deployment", "web", "prod")]: observedWeb };
 
     const { resources: observedNow } = normalizeObservation(
       await k8sPlugin.describeResources!({
@@ -97,45 +94,32 @@ describe("k8s lifecycle integration (#163)", () => {
     );
     expect(observedNow.web?.type).toBe("K8s::Apps::Deployment");
 
-    const cs = buildChangeSet("prod", {
-      declared: new Set(["webSvc"]),
-      observedNow,
-      observedThen: undefined,
-    });
+    const cs = buildChangeSet("prod", { declared: new Set(["webSvc"]), observedNow, observedThen: undefined });
     const byName = Object.fromEntries(cs.entries.map((e) => [e.name, e.action]));
     expect(byName.webSvc).toBe("create");
     expect(byName.web).toBe("adopt");
 
-    const cs2 = buildChangeSet("prod", {
-      declared: new Set(["web"]),
-      observedNow,
-      observedThen: undefined,
-    });
+    const cs2 = buildChangeSet("prod", { declared: new Set(["web"]), observedNow, observedThen: undefined });
     expect(cs2.entries.find((e) => e.name === "web")!.action).toBe("noop");
   });
 
   /**
-   * The #1089 chain, end to end on the real plugin: a declared CRD the lexicon
-   * has no reader for goes describe → plan → component status without ever
-   * turning into a create or a "stale" component.
+   * The #1089 chain, end to end on the real plugin. The entity that used to
+   * demonstrate it — a CRD with no `KUBECTL_RESOURCE` entry — is no longer a
+   * hole, because #1074 removed the map; an RBAC-denied read is what produces
+   * a hole now, and it has to survive describe → plan → status the same way.
    */
-  test("tri-state chain: an unreadable CRD stays unobserved through describe → plan → status (#1089)", async () => {
-    execMock.mockImplementation((cmd?: string) =>
-      cmd?.includes("deployment.apps web")
-        ? {
-            stdout: JSON.stringify({
-              metadata: { name: "web", namespace: "prod", uid: "uid-1" },
-              status: { readyReplicas: 3, replicas: 3 },
-            }),
-            stderr: "",
-          }
-        : new Error('Error from server (NotFound): deployments.apps "gone" not found'),
-    );
+  test("tri-state chain: an unreadable entity stays unobserved through describe → plan → status (#1089)", async () => {
+    clusterState.objects = { [objectKey("apps/v1", "Deployment", "web", "prod")]: observedWeb };
+    clusterState.fail = (path) =>
+      path.endsWith("/deployments/widget")
+        ? { status: 403, body: statusBody(403, "Forbidden", 'deployments.apps "widget" is forbidden') }
+        : undefined;
 
     const entities = new Map([
       ["web", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } }],
       ["gone", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "gone", namespace: "prod" } } }],
-      ["widget", { entityType: "K8s::Example::Widget", props: { metadata: { name: "widget", namespace: "prod" } } }],
+      ["widget", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "widget", namespace: "prod" } } }],
     ]);
 
     // 1. describe — three declared entities, three different verdicts.
@@ -148,10 +132,11 @@ describe("k8s lifecycle integration (#163)", () => {
       }),
     );
     expect(Object.keys(observed.resources)).toEqual(["web"]);
-    expect(observed.unobserved.widget.reason).toBe("unsupported-kind");
+    expect(observed.unobserved.widget.reason).toBe("no-credentials");
     expect(observed.unobserved.gone).toBeUndefined(); // NotFound is an absence
 
-    // 2. plan — the CRD is `unobserved`; only the confirmed-absent one is a create.
+    // 2. plan — the unreadable one is `unobserved`; only the confirmed-absent
+    // one is a create.
     const cs = buildChangeSet("prod", {
       declared: new Set(entities.keys()),
       observedNow: observed.resources,
@@ -163,15 +148,64 @@ describe("k8s lifecycle integration (#163)", () => {
 
     // 3. status — a recorded component whose entity was never read reports
     // `unknown`, not `stale`, and carries no `live` boolean at all.
-    const rows = reconcileStatus("prod", [
-      { component: "widget", env: "prod", digest: "sha256:abc", gitSha: "g", runId: "r", timestamp: "2026-01-01T00:00:00Z", actor: "ci" },
-    ], { liveEvidence: liveEvidenceFromChangeSet(cs) });
+    const rows = reconcileStatus(
+      "prod",
+      [
+        {
+          component: "widget",
+          env: "prod",
+          digest: "sha256:abc",
+          gitSha: "g",
+          runId: "r",
+          timestamp: "2026-01-01T00:00:00Z",
+          actor: "ci",
+        },
+      ],
+      { liveEvidence: liveEvidenceFromChangeSet(cs) },
+    );
     const widgetRow = rows.find((r) => r.component === "widget")!;
     expect(widgetRow.reconciliation).toBe("unknown");
     expect(widgetRow.live).toBeUndefined();
-    expect(widgetRow.unobserved?.reason).toBe("unsupported-kind");
+    expect(widgetRow.unobserved?.reason).toBe("no-credentials");
     expect(widgetRow.detail).toContain("could not be observed");
   });
+
+  /**
+   * chant #1074's coverage claim, on the real plugin: a CRD that the old path
+   * warn-skipped as `unsupported-kind` now reads like anything else.
+   */
+  test("a CRD is observed, not skipped (chant #1074)", async () => {
+    clusterState.objects = {
+      [objectKey("ray.io/v1", "RayCluster", "ml", "ray")]: {
+        apiVersion: "ray.io/v1",
+        kind: "RayCluster",
+        metadata: { name: "ml", namespace: "ray", uid: "uid-ray" },
+        status: { phase: "ready" },
+      },
+    };
+
+    const observed = normalizeObservation(
+      await k8sPlugin.describeResources!({
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["ml"],
+        entities: new Map([
+          ["ml", { entityType: "K8s::Ray::RayCluster", props: { metadata: { name: "ml", namespace: "ray" } } }],
+        ]),
+      }),
+    );
+
+    expect(observed.unobserved).toEqual({});
+    expect(observed.resources.ml?.physicalId).toBe("uid-ray");
+
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["ml"]),
+      observedNow: observed.resources,
+      observedThen: undefined,
+      unobserved: observed.unobserved,
+    });
+    expect(cs.entries.find((e) => e.name === "ml")!.action).toBe("noop");
+  });
 });
 
 // The shared conformance suite (#1089) — every observing lexicon runs it.
@@ -179,18 +213,22 @@ describeObservationConformance({
   lexicon: "k8s",
   scenarios: [
     {
-      name: "a CRD kind with no reader",
+      name: "an RBAC-denied read alongside a confirmed absence",
       declared: ["widget", "gone"],
       expectUnobserved: ["widget"],
       expectAbsent: ["gone"],
       run: () => {
-        execMock.mockImplementation(() => new Error('Error from server (NotFound): deployments.apps "gone" not found'));
+        clusterState.objects = {};
+        clusterState.fail = (path) =>
+          path.endsWith("/deployments/widget")
+            ? { status: 403, body: statusBody(403, "Forbidden", "forbidden") }
+            : undefined;
         return k8sPlugin.describeResources!({
           environment: "prod",
           buildOutput: "",
           entityNames: ["widget", "gone"],
           entities: new Map([
-            ["widget", { entityType: "K8s::Example::Widget", props: { metadata: { name: "widget" } } }],
+            ["widget", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "widget" } } }],
             ["gone", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "gone" } } }],
           ]),
         });
@@ -201,18 +239,15 @@ describeObservationConformance({
       declared: ["web"],
       expectUnobserved: ["web"],
       run: () => {
-        execMock.mockImplementation(() =>
-          Object.assign(new Error("kubectl failed"), {
-            stderr: "The connection to the server 127.0.0.1:6443 was refused - did you specify the right host or port?",
-          }),
-        );
+        clusterState.objects = {};
+        clusterState.fail = () => {
+          throw new Error("connect ECONNREFUSED 127.0.0.1:6443");
+        };
         return k8sPlugin.describeResources!({
           environment: "prod",
           buildOutput: "",
           entityNames: ["web"],
-          entities: new Map([
-            ["web", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web" } } }],
-          ]),
+          entities: new Map([["web", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web" } } }]]),
         });
       },
     },
@@ -221,20 +256,25 @@ describeObservationConformance({
       declared: ["web"],
       expectPresent: ["web"],
       run: () => {
-        execMock.mockImplementation(() => ({
-          stdout: JSON.stringify({
-            metadata: { name: "web", namespace: "prod", uid: "uid-1", labels: { "app.kubernetes.io/managed-by": "chant" } },
+        clusterState.fail = undefined;
+        clusterState.objects = {
+          [objectKey("apps/v1", "Deployment", "web", "default")]: {
+            apiVersion: "apps/v1",
+            kind: "Deployment",
+            metadata: {
+              name: "web",
+              namespace: "default",
+              uid: "uid-1",
+              labels: { "app.kubernetes.io/managed-by": "chant" },
+            },
             status: { readyReplicas: 1, replicas: 1 },
-          }),
-          stderr: "",
-        }));
+          },
+        };
         return k8sPlugin.describeResources!({
           environment: "prod",
           buildOutput: "",
           entityNames: ["web"],
-          entities: new Map([
-            ["web", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web" } } }],
-          ]),
+          entities: new Map([["web", { entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web" } } }]]),
         });
       },
     },

package/src/op/activities/index.ts

@@ -2,7 +2,10 @@
  * k8s Op activities — resolved by the core activity registry when a project's
  * `chant.config.ts` lists the `k8s` lexicon. Relocated from the temporal lexicon
  * (#809) so Kubernetes-facing imperative activities live with their product:
- *   - kubectlApply — `kubectl apply` a rendered manifest
+ *   - kubectlApply — server-side apply a rendered manifest (and, since chant
+ *     #1075, prune chant-owned objects it no longer declares; `applyManifest`
+ *     is the same work with a report of what it did, which is what the
+ *     Temporal lexicon's `nativeApply` dispatcher calls for a kubectl target)
  *   - k3dUp / k3dDown — boot/tear down a local k3d cluster
  *   - waitForArgoSync — block until an Argo CD Application is Healthy && Synced
  *
@@ -11,8 +14,8 @@
  * dependency-light — it shells out to a CLI and does not import the k8s declarable
  * surface — so a Temporal worker loads it cheaply.
  */
-export { kubectlApply } from "./kubectl";
-export type { KubectlApplyArgs } from "./kubectl";
+export { kubectlApply, applyManifest, readManifestDocuments } from "./kubectl";
+export type { KubectlApplyArgs, ApplyManifestResult, AppliedRef, ApplyDeleteMode } from "./kubectl";
 
 export { k3dUp, k3dDown, k3dUpCommand, k3dDownCommand, k3dExistsCommand } from "./k3d";
 export type { K3dUpArgs, K3dDownArgs } from "./k3d";
@@ -23,6 +26,7 @@ export type { WaitForArgoSyncArgs, ArgoAppStatus, ArgoStatusFetcher } from "./ar
 export {
   waitForReady,
   defaultResourceFetcher,
+  apiResourceFetcher,
   ReadinessFailedError,
   readinessFor,
   isReady,