@intentius/chant-lexicon-k8s 0.30.0 → 0.31.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

@@ -11,7 +11,7 @@
  * 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 { kubectlApply, readManifestDocuments } from "./kubectl";
 export type { KubectlApplyArgs } from "./kubectl";
 
 export { k3dUp, k3dDown, k3dUpCommand, k3dDownCommand, k3dExistsCommand } from "./k3d";
@@ -23,6 +23,7 @@ export type { WaitForArgoSyncArgs, ArgoAppStatus, ArgoStatusFetcher } from "./ar
 export {
   waitForReady,
   defaultResourceFetcher,
+  apiResourceFetcher,
   ReadinessFailedError,
   readinessFor,
   isReady,

package/src/op/activities/kubectl.test.ts

@@ -0,0 +1,148 @@
+/**
+ * `kubectlApply` over the typed API client (chant #1074).
+ *
+ * The activity contract is what Temporal workers register, so the shape of the
+ * arguments and the `Promise<void>` return are asserted alongside the new
+ * behavior. Nothing here spawns a process or reads an ambient kubeconfig,
+ * which is the acceptance criterion: a worker image needs no `kubectl` binary.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { kubectlApply, readManifestDocuments } from "./kubectl";
+import { fakeCluster } from "../../api/fake-cluster";
+import { statusBody } from "@intentius/chant-k8s-client/testing";
+
+let dir: string;
+
+const deploymentYaml = `apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web
+  namespace: prod
+spec:
+  replicas: 3
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: web-svc
+  namespace: prod
+spec:
+  ports:
+    - port: 80
+`;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "chant-k8s-apply-"));
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("readManifestDocuments", () => {
+  test("splits a multi-document file, dropping empty documents", () => {
+    const file = join(dir, "k8s.yaml");
+    writeFileSync(file, `${deploymentYaml}---\n---\n`);
+    const docs = readManifestDocuments(file);
+    expect(docs.map((d) => d.kind)).toEqual(["Deployment", "Service"]);
+  });
+
+  test("a directory is read in sorted file order, as `kubectl apply -f <dir>` does", () => {
+    writeFileSync(join(dir, "20-service.yaml"), "apiVersion: v1\nkind: Service\nmetadata:\n  name: b\n");
+    writeFileSync(join(dir, "10-deployment.yaml"), "apiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: a\n");
+    writeFileSync(join(dir, "notes.txt"), "ignored");
+    const docs = readManifestDocuments(dir);
+    expect(docs.map((d) => d.kind)).toEqual(["Deployment", "Service"]);
+  });
+
+  test("JSON manifests are read too", () => {
+    const file = join(dir, "k8s.json");
+    writeFileSync(file, JSON.stringify({ apiVersion: "v1", kind: "ConfigMap", metadata: { name: "c" } }));
+    expect(readManifestDocuments(file).map((d) => d.kind)).toEqual(["ConfigMap"]);
+  });
+});
+
+describe("kubectlApply", () => {
+  test("server-side applies every document, in file order, as the chant field manager", async () => {
+    const file = join(dir, "k8s.yaml");
+    writeFileSync(file, deploymentYaml);
+    const cluster = fakeCluster({
+      respond: (req) => (req.method === "PATCH" ? { body: JSON.parse(String(req.body)) } : undefined),
+    });
+
+    await kubectlApply({ manifest: file }, undefined, cluster.connector);
+
+    const patches = cluster.layer.requests.filter((r) => r.method === "PATCH");
+    expect(patches.map((p) => p.path)).toEqual([
+      "/apis/apps/v1/namespaces/prod/deployments/web",
+      "/api/v1/namespaces/prod/services/web-svc",
+    ]);
+    for (const patch of patches) {
+      expect(patch.headers["Content-Type"]).toBe("application/apply-patch+yaml");
+      expect(patch.query).toMatchObject({ fieldManager: "chant", force: "false" });
+    }
+  });
+
+  test("an explicit context is honored and skips the environment lookup entirely", async () => {
+    const file = join(dir, "k8s.yaml");
+    writeFileSync(file, deploymentYaml);
+    const cluster = fakeCluster({
+      respond: (req) => (req.method === "PATCH" ? { body: JSON.parse(String(req.body)) } : undefined),
+    });
+
+    await kubectlApply({ manifest: file, context: "test-context" }, undefined, cluster.connector);
+
+    expect(cluster.connects[0]).toMatchObject({ context: "test-context" });
+    expect(cluster.connects[0].environment).toBeUndefined();
+  });
+
+  test("an environment is passed through so the cluster binding applies to the write path too", async () => {
+    const file = join(dir, "k8s.yaml");
+    writeFileSync(file, deploymentYaml);
+    const cluster = fakeCluster({
+      respond: (req) => (req.method === "PATCH" ? { body: JSON.parse(String(req.body)) } : undefined),
+    });
+
+    await kubectlApply({ manifest: file, environment: "prod" }, undefined, cluster.connector);
+    expect(cluster.connects[0]).toMatchObject({ environment: "prod" });
+  });
+
+  test("force is forwarded, for the caller that means to take ownership (chant #1075)", async () => {
+    const file = join(dir, "k8s.yaml");
+    writeFileSync(file, deploymentYaml);
+    const cluster = fakeCluster({
+      respond: (req) => (req.method === "PATCH" ? { body: JSON.parse(String(req.body)) } : undefined),
+    });
+
+    await kubectlApply({ manifest: file, force: true, fieldManager: "chant-op" }, undefined, cluster.connector);
+    const patch = cluster.layer.requests.find((r) => r.method === "PATCH")!;
+    expect(patch.query).toMatchObject({ force: "true", fieldManager: "chant-op" });
+  });
+
+  test("a field-ownership conflict surfaces as a typed error rather than parsed stderr", async () => {
+    const file = join(dir, "k8s.yaml");
+    writeFileSync(file, deploymentYaml);
+    const cluster = fakeCluster({
+      respond: (req) =>
+        req.method === "PATCH"
+          ? { status: 409, body: statusBody(409, "Conflict", 'Apply failed with 1 conflict: conflict with "kubectl"') }
+          : undefined,
+    });
+
+    const err = await kubectlApply({ manifest: file }, undefined, cluster.connector).catch((e: unknown) => e);
+    expect((err as { name?: string }).name).toBe("K8sApiError");
+    expect((err as { statusCode?: number }).statusCode).toBe(409);
+  });
+
+  test("resolves to undefined, keeping the activity's Promise<void> contract", async () => {
+    const file = join(dir, "k8s.yaml");
+    writeFileSync(file, "apiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: c\n  namespace: prod\n");
+    const cluster = fakeCluster({
+      respond: (req) => (req.method === "PATCH" ? { body: JSON.parse(String(req.body)) } : undefined),
+    });
+    await expect(kubectlApply({ manifest: file }, undefined, cluster.connector)).resolves.toBeUndefined();
+  });
+});

package/src/op/activities/kubectl.ts

@@ -1,10 +1,35 @@
-import { exec } from "node:child_process";
-import { promisify } from "node:util";
-import { safeHeartbeat } from "@intentius/chant/op";
+/**
+ * `kubectlApply` — apply a rendered manifest to a cluster.
+ *
+ * chant #1074 moved this off `kubectl apply -f`. The activity contract is
+ * unchanged (a manifest path, an optional context, `Promise<void>`, the
+ * `longInfra` profile's 15s heartbeat) because Temporal workers register it by
+ * that signature; what changed is underneath. The name is kept for the same
+ * reason.
+ *
+ * Consequences worth knowing:
+ *
+ * - **A worker image needs no `kubectl` binary.** That was the point.
+ * - **It is a server-side apply**, with `chant` as the field manager, rather
+ *   than the client-side three-way merge `kubectl apply` performs by default.
+ *   Server-side apply is the direction Kubernetes itself has taken, it removes
+ *   the `last-applied-configuration` annotation from the story, and it is what
+ *   chant #1075 builds the field-ownership and conflict surface on. A conflict
+ *   with another field manager arrives here as a typed 409 rather than a line
+ *   of stderr; #1075 is where it gets a proper presentation.
+ * - **Documents apply in file order**, as `kubectl apply -f` does, and a
+ *   directory's files are read in sorted order.
+ */
 
-const execAsync = promisify(exec);
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { loadAll } from "js-yaml";
+import { safeHeartbeat } from "@intentius/chant/op";
+import type { K8sObject } from "@intentius/chant-k8s-client";
+import { defaultK8sConnector, type K8sConnector } from "../../api/connect";
 
 export interface KubectlApplyArgs {
+  /** Path to a manifest file, or a directory of them. */
   manifest: string;
   /**
    * kubectl context name. Uses the ambient context if omitted. To target the
@@ -13,25 +38,73 @@ export interface KubectlApplyArgs {
    * `./index.ts` and pass `.context` through.
    */
   context?: string;
+  /**
+   * chant environment, used to resolve `k8s.profiles.<env>.context` when no
+   * explicit `context` is given. Optional and additive: omitting both keeps
+   * the previous behavior of using whatever the kubeconfig selects.
+   */
+  environment?: string;
+  /** Field manager recorded on the applied objects. Default `chant`. */
+  fieldManager?: string;
+  /** Take ownership of fields another manager owns instead of failing (chant #1075). */
+  force?: boolean;
+}
+
+/** Read a manifest path — one file, or every YAML/JSON file in a directory. */
+export function readManifestDocuments(path: string): Record<string, unknown>[] {
+  const files = statSync(path).isDirectory()
+    ? readdirSync(path)
+        .filter((f) => /\.(ya?ml|json)$/i.test(f))
+        .sort()
+        .map((f) => join(path, f))
+    : [path];
+
+  const documents: Record<string, unknown>[] = [];
+  for (const file of files) {
+    for (const doc of loadAll(readFileSync(file, "utf-8"))) {
+      // Multi-document YAML files routinely carry empty documents between
+      // separators; they are not objects to apply.
+      if (doc && typeof doc === "object") documents.push(doc as Record<string, unknown>);
+    }
+  }
+  return documents;
 }
 
 /**
- * Run `kubectl apply -f <manifest>`.
+ * Apply every document in `args.manifest`.
  * Uses longInfra profile — 20m timeout, heartbeat every 15s.
  */
-export async function kubectlApply(args: KubectlApplyArgs, signal?: AbortSignal): Promise<void> {
-  const ctx = args.context ? `--context ${args.context}` : "";
+export async function kubectlApply(
+  args: KubectlApplyArgs,
+  signal?: AbortSignal,
+  connect: K8sConnector = defaultK8sConnector,
+): Promise<void> {
+  const documents = readManifestDocuments(args.manifest);
   const heartbeatInterval = setInterval(() => {
     safeHeartbeat({ step: "kubectl apply", manifest: args.manifest });
   }, 15_000);
 
   try {
-    const { stdout, stderr } = await execAsync(
-      `kubectl apply -f ${args.manifest} ${ctx} --wait=true`,
-      { signal },
-    );
-    if (stdout) console.log(stdout);
-    if (stderr) console.error(stderr);
+    const { client } = await connect({
+      ...(args.environment !== undefined ? { environment: args.environment } : {}),
+      ...(args.context !== undefined ? { context: args.context } : {}),
+    });
+
+    for (const document of documents) {
+      const applied = await client.apply(document as K8sObject, {
+        fieldManager: args.fieldManager ?? "chant",
+        force: args.force ?? false,
+        signal,
+      });
+      safeHeartbeat({
+        step: "kubectl apply",
+        manifest: args.manifest,
+        applied: `${applied.kind ?? document.kind}/${applied.metadata?.name ?? "?"}`,
+      });
+      console.log(
+        `${String(applied.apiVersion ?? document.apiVersion)} ${String(applied.kind ?? document.kind)}/${String(applied.metadata?.name ?? "")} applied`,
+      );
+    }
   } finally {
     clearInterval(heartbeatInterval);
   }