@intentius/chant-lexicon-k8s 0.42.1 → 0.44.2

package/src/components/argo-app.ts

@@ -0,0 +1,163 @@
+/**
+ * `argo-app` — the Argo CD deploy leaf for the component model (#1549
+ * piece 2).
+ *
+ * GitOps inverts the flow kubectl-apply assumes: the controller deploys,
+ * chant declares the controller's objects and observes convergence. This
+ * capability is that inversion as one step — apply the declared
+ * `Application` CR(s) through the SAME server-side apply `kubectl-apply`
+ * uses (ownership stamping, marker-scoped prune, stack labels all
+ * identical), then block until every applied Application reports
+ * `health=Healthy && sync=Synced` via the existing `waitForArgoSync`
+ * activity (#957).
+ *
+ * The deploy unit is the CR itself under its stack label — `stack` doubles
+ * as ownership identity and deploy unit exactly as kubectl-apply's, so
+ * `chant components status --live` observes the Application through the
+ * same label sweep with zero new status walks (core
+ * `components/deploy-units.ts`).
+ *
+ * The #1074 boundary applies: nothing exported from the lexicon entry point
+ * may statically import the API-client chain, so both the applier and the
+ * wait activity are reached by dynamic import inside `run()` and their
+ * argument shapes are structural mirrors, checked against the real ones at
+ * the call site.
+ */
+import type { Capability, DeployContext } from "@intentius/chant/components/capability";
+
+/** Structural mirrors of the activity modules' shapes (see the module doc). */
+interface AppliedRef {
+  apiVersion: string;
+  kind: string;
+  name: string;
+  namespace?: string;
+}
+
+interface ApplyOutcome {
+  fieldManager: string;
+  applied: AppliedRef[];
+  pruned: AppliedRef[];
+}
+
+interface ApplierArgs {
+  manifest: string;
+  environment?: string;
+  stack?: string;
+  context?: string;
+  deleteMode?: "never" | "owned-only" | "gated";
+}
+
+type Applier = (args: ApplierArgs) => Promise<ApplyOutcome>;
+
+interface ArgoWaiterArgs {
+  appName: string;
+  namespace?: string;
+  server?: string;
+  authToken?: string;
+  insecure?: boolean;
+  context?: string;
+  intervalMs?: number;
+}
+
+type ArgoWaiter = (args: ArgoWaiterArgs) => Promise<{ health: string; sync: string }>;
+
+/** One Application's final status, after the wait. */
+export interface ArgoAppSynced {
+  name: string;
+  namespace: string;
+  health: string;
+  sync: string;
+}
+
+export interface ArgoAppOutcome extends ApplyOutcome {
+  /** Every applied Application, Healthy+Synced, in wait order. */
+  synced: ArgoAppSynced[];
+}
+
+export interface ArgoAppInput {
+  /** Path to the Application CR manifest(s) — a file, or a directory of them. */
+  manifest: string;
+  /**
+   * The deploy unit / ownership stack — same double duty as kubectl-apply's.
+   * Omitted derives from the project's `ownership.stack`, but then the unit
+   * is invisible to `components status --live`. Name it.
+   */
+  stack?: string;
+  /** kubectl context. Omitted resolves `k8s.profiles.<ctx.env>.context`. */
+  context?: string;
+  /** Same delete vocabulary as kubectl-apply; default `never`. */
+  delete?: "never" | "owned-only";
+  /**
+   * Argo CD API base URL. When set, sync status is read from the REST API
+   * instead of the cluster — pass `authToken` with it (the `waitForArgoSync`
+   * surface, #957).
+   */
+  server?: string;
+  /** Bearer token for the Argo CD REST API (used with `server`). */
+  authToken?: string;
+  /** Skip TLS verification for the REST API (default false). */
+  insecure?: boolean;
+  /** Poll interval in ms (default 15000). */
+  intervalMs?: number;
+}
+
+/** True when the ref is an Argo CD Application (any argoproj.io version). */
+function isArgoApplication(ref: AppliedRef): boolean {
+  return ref.kind === "Application" && /^argoproj\.io(\/|$)/.test(ref.apiVersion);
+}
+
+/** Factory with injectable applier + waiter, so tests assert the exact
+ * delegation without a cluster — the kubectl-apply seam. Defaults resolve by
+ * dynamic import on first run, keeping the API-client chain off the build
+ * path (#1074). */
+export function createArgoAppCapability(
+  apply?: Applier,
+  wait?: ArgoWaiter,
+): Capability<ArgoAppInput, ArgoAppOutcome> {
+  return {
+    kind: "argo-app",
+    // The apply half is a server-side apply with no native undo, and Argo
+    // offers no declarative "un-sync" — same posture as kubectl-apply.
+    rollbackPolicy: "needs-opt-out",
+    async run(ctx: DeployContext, input: ArgoAppInput): Promise<ArgoAppOutcome> {
+      const applier: Applier = apply ?? (await import("../op/activities/kubectl")).applyManifest;
+      const outcome = await applier({
+        manifest: input.manifest,
+        environment: ctx.env,
+        ...(input.stack !== undefined ? { stack: input.stack } : {}),
+        ...(input.context !== undefined ? { context: input.context } : {}),
+        ...(input.delete !== undefined ? { deleteMode: input.delete } : {}),
+      });
+
+      // AppProject / ApplicationSet in the same manifest apply fine; the wait
+      // gates only on Applications (an ApplicationSet's generated Applications
+      // are the controller's, not declared here).
+      const apps = outcome.applied.filter(isArgoApplication);
+      if (apps.length === 0) {
+        throw new Error(
+          `argo-app: "${input.manifest}" applied no argoproj.io Application — nothing to sync on. ` +
+            `A plain manifest belongs on kubectl-apply.`,
+        );
+      }
+
+      const waiter: ArgoWaiter = wait ?? (await import("../op/activities/argo")).waitForArgoSync;
+      const synced: ArgoAppSynced[] = [];
+      for (const app of apps) {
+        const namespace = app.namespace ?? "argocd";
+        const status = await waiter({
+          appName: app.name,
+          namespace,
+          ...(input.server !== undefined ? { server: input.server } : {}),
+          ...(input.authToken !== undefined ? { authToken: input.authToken } : {}),
+          ...(input.insecure !== undefined ? { insecure: input.insecure } : {}),
+          ...(input.context !== undefined ? { context: input.context } : {}),
+          ...(input.intervalMs !== undefined ? { intervalMs: input.intervalMs } : {}),
+        });
+        synced.push({ name: app.name, namespace, health: status.health, sync: status.sync });
+      }
+      return { ...outcome, synced };
+    },
+  };
+}
+
+export const argoAppCapability = createArgoAppCapability();

package/src/components/builders.ts

@@ -14,9 +14,17 @@
 import { step } from "@intentius/chant/components";
 import type { KubectlApplyInput } from "./kubectl-apply";
 import type { KustomizeApplyInput } from "./kustomize-apply";
+import type { ArgoAppInput } from "./argo-app";
+import type { FluxReconcileInput } from "./flux-reconcile";
 
 export const kubectlApply = step<KubectlApplyInput & { noRollback?: string }>("kubectl-apply");
 
 // Same needs-opt-out posture, same sugar (#1548): a kustomize render in front
 // of the identical server-side apply.
 export const kustomizeApply = step<KustomizeApplyInput & { noRollback?: string }>("kustomize-apply");
+
+// GitOps verbs (#1549 piece 2): the identical server-side apply of the
+// controller's CR, then a convergence wait — Healthy+Synced for Argo, the
+// Flux readiness registry (Ready, terminal on wedge reasons) for Flux.
+export const argoApp = step<ArgoAppInput & { noRollback?: string }>("argo-app");
+export const fluxReconcile = step<FluxReconcileInput & { noRollback?: string }>("flux-reconcile");

package/src/components/capability-plugin.ts

@@ -12,9 +12,14 @@ import type { Capability } from "@intentius/chant/components/capability";
 import { ownPackageVersion, type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
 import { kubectlApplyCapability } from "./kubectl-apply";
 import { kustomizeApplyCapability } from "./kustomize-apply";
+import { argoAppCapability } from "./argo-app";
+import { fluxReconcileCapability } from "./flux-reconcile";
 
 export const K8S_VERB_FAMILIES = {
   apply: ["kubectl-apply", "kustomize-apply"],
+  // GitOps verbs (#1549 piece 2): apply the controller's CR through the same
+  // stack-labelled pipeline, then wait for the controller to converge.
+  gitops: ["argo-app", "flux-reconcile"],
 } as const;
 
 export const k8sCapabilityPlugin: CapabilityPlugin = {
@@ -23,7 +28,12 @@ export const k8sCapabilityPlugin: CapabilityPlugin = {
   // a literal here was stale one release after it was written.
   version: ownPackageVersion(import.meta.url),
   capabilities(): Array<Capability<never, unknown>> {
-    return [kubectlApplyCapability as Capability<never, unknown>, kustomizeApplyCapability as Capability<never, unknown>];
+    return [
+      kubectlApplyCapability as Capability<never, unknown>,
+      kustomizeApplyCapability as Capability<never, unknown>,
+      argoAppCapability as Capability<never, unknown>,
+      fluxReconcileCapability as Capability<never, unknown>,
+    ];
   },
   families(): Record<string, readonly string[]> {
     return K8S_VERB_FAMILIES;

package/src/components/flux-reconcile.test.ts

@@ -0,0 +1,145 @@
+/**
+ * `flux-reconcile` (#1549 piece 2) — the Flux deploy leaf. What must hold:
+ * the capability registers under its kind in the gitops family, the apply
+ * goes through the SAME applier delegation kubectl-apply uses, the wait runs
+ * the generic `waitForReady` once per applied Flux CR — sources before
+ * reconcilers, non-Flux objects skipped — with the group/kind the #1554
+ * readiness entries key on, a manifest with no Flux CR is an error, and the
+ * stack is the deploy unit core's status walk reads.
+ */
+import { describe, test, expect } from "vitest";
+import { createFluxReconcileCapability, fluxReconcileCapability, type FluxReconcileInput } from "./flux-reconcile";
+import { k8sCapabilityPlugin, K8S_VERB_FAMILIES } from "./capability-plugin";
+import { isCapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import type { DeployContext } from "@intentius/chant/components/capability";
+
+const ctx = { env: "dev" } as DeployContext;
+
+const KUSTOMIZATION = {
+  apiVersion: "kustomize.toolkit.fluxcd.io/v1",
+  kind: "Kustomization",
+  name: "apps",
+  namespace: "flux-system",
+};
+const GIT_REPO = {
+  apiVersion: "source.toolkit.fluxcd.io/v1",
+  kind: "GitRepository",
+  name: "repo",
+  namespace: "flux-system",
+};
+const HELM_RELEASE = {
+  apiVersion: "helm.toolkit.fluxcd.io/v2",
+  kind: "HelmRelease",
+  name: "podinfo",
+  namespace: "flux-system",
+};
+const NAMESPACE = { apiVersion: "v1", kind: "Namespace", name: "flux-system" };
+
+describe("flux-reconcile capability (#1549 piece 2)", () => {
+  test("registers on the k8s plugin, in the gitops family", () => {
+    expect(isCapabilityPlugin(k8sCapabilityPlugin)).toBe(true);
+    expect(k8sCapabilityPlugin.capabilities().map((c) => c.kind)).toContain("flux-reconcile");
+    expect(K8S_VERB_FAMILIES.gitops).toContain("flux-reconcile");
+  });
+
+  test("rollback is needs-opt-out — a server-side apply keeps no previous state", () => {
+    expect(fluxReconcileCapability.rollbackPolicy).toBe("needs-opt-out");
+  });
+
+  test("applies through the kubectl-apply delegation, then waits Ready on each Flux CR — sources first, non-Flux skipped", async () => {
+    const applierArgs: unknown[] = [];
+    const waited: Array<{ kind: string; group?: string }> = [];
+    const cap = createFluxReconcileCapability(
+      async (args) => {
+        applierArgs.push(args);
+        // Applied order: reconciler before its source, plus a plain Namespace.
+        return { fieldManager: "chant:gitops", applied: [NAMESPACE, KUSTOMIZATION, GIT_REPO, HELM_RELEASE], pruned: [] };
+      },
+      async (args) => {
+        waited.push(args);
+        return {};
+      },
+    );
+
+    const outcome = await cap.run(ctx, {
+      manifest: "flux/",
+      stack: "gitops",
+      delete: "owned-only",
+      intervalMs: 500,
+    } as FluxReconcileInput as never);
+
+    // The exact args kubectl-apply hands the shared applier — same path, same stamping.
+    expect(applierArgs).toEqual([
+      { manifest: "flux/", environment: "dev", stack: "gitops", deleteMode: "owned-only" },
+    ]);
+    // Source first (a Kustomization can't be Ready before its GitRepository has
+    // an artifact), then the reconcilers in applied order; the Namespace is not waited on.
+    expect(waited).toEqual([
+      {
+        kind: "GitRepository",
+        name: "repo",
+        namespace: "flux-system",
+        group: "source.toolkit.fluxcd.io",
+        environment: "dev",
+        intervalMs: 500,
+      },
+      {
+        kind: "Kustomization",
+        name: "apps",
+        namespace: "flux-system",
+        group: "kustomize.toolkit.fluxcd.io",
+        environment: "dev",
+        intervalMs: 500,
+      },
+      {
+        kind: "HelmRelease",
+        name: "podinfo",
+        namespace: "flux-system",
+        group: "helm.toolkit.fluxcd.io",
+        environment: "dev",
+        intervalMs: 500,
+      },
+    ]);
+    expect(outcome.ready).toEqual([GIT_REPO, KUSTOMIZATION, HELM_RELEASE]);
+    expect(outcome.fieldManager).toBe("chant:gitops");
+  });
+
+  test("the group/kind handed to waitForReady key the #1554 readiness registry entries", async () => {
+    // The registry is keyed "<group>/<kind>" — assert the pair the capability
+    // passes resolves to the ConditionReasonMatch entry, not the generic default.
+    const { readinessFor } = await import("../op/activities/wait-for-ready");
+    const spec = readinessFor("kustomize.toolkit.fluxcd.io", "Kustomization");
+    expect(spec.terminal).toBeDefined();
+    expect(JSON.stringify(spec.terminal)).toContain("BuildFailed");
+  });
+
+  test("a manifest that applied no Flux CR is an error, not a silent no-wait", async () => {
+    const cap = createFluxReconcileCapability(
+      async () => ({ fieldManager: "chant", applied: [NAMESPACE], pruned: [] }),
+      async () => ({}),
+    );
+    await expect(cap.run(ctx, { manifest: "k8s.yaml" } as FluxReconcileInput as never)).rejects.toThrow(
+      /no Flux CR/,
+    );
+  });
+
+  test("a wedged CR propagates — the step does not report success past a terminal Ready=False", async () => {
+    const cap = createFluxReconcileCapability(
+      async () => ({ fieldManager: "chant", applied: [KUSTOMIZATION], pruned: [] }),
+      async () => {
+        throw new Error("Kustomization/apps reached a terminal state");
+      },
+    );
+    await expect(cap.run(ctx, { manifest: "flux/" } as FluxReconcileInput as never)).rejects.toThrow(
+      /terminal state/,
+    );
+  });
+
+  test("the stack field is the deploy unit core's status walk reads (#1549 piece 2)", async () => {
+    const { deployUnits } = await import("@intentius/chant/components/deploy-units");
+    const units = deployUnits([
+      { phase: "Apply", steps: [{ kind: "flux-reconcile", manifest: "flux/", stack: "gitops" }] } as never,
+    ]);
+    expect(units).toEqual([{ unit: "gitops", lexicon: "k8s" }]);
+  });
+});

package/src/components/flux-reconcile.ts

@@ -0,0 +1,159 @@
+/**
+ * `flux-reconcile` — the Flux deploy leaf for the component model (#1549
+ * piece 2).
+ *
+ * The sibling of `argo-app` for the Flux toolkit: apply the declared Flux
+ * CRs (`GitRepository`, `Kustomization`, `HelmRelease`, `OCIRepository`, …)
+ * through the SAME server-side apply `kubectl-apply` uses — ownership
+ * stamping, marker-scoped prune, stack labels all identical — then block
+ * until every applied Flux CR reports `Ready=True` via the generic
+ * `waitForReady`. The readiness registry's Flux entries (#1554,
+ * `ConditionReasonMatch`) make that wait honest: a wedge reason like
+ * `BuildFailed` or `UpgradeFailed` fails fast instead of polling out the
+ * timeout.
+ *
+ * Sources are waited first (`source.toolkit.fluxcd.io` before the rest,
+ * applied order within each half): a Kustomization cannot become Ready
+ * before its GitRepository has an artifact, so gating on the source first
+ * surfaces a wedged clone as the source's error, not as a reconciler
+ * timeout downstream of it.
+ *
+ * The deploy unit is the CR itself under its stack label — one name, both
+ * jobs, exactly as kubectl-apply (core `components/deploy-units.ts`).
+ *
+ * The #1074 boundary applies: the applier and the wait activity are reached
+ * by dynamic import inside `run()`; their argument shapes are structural
+ * mirrors, checked against the real ones at the call site.
+ */
+import type { Capability, DeployContext } from "@intentius/chant/components/capability";
+
+/** Structural mirrors of the activity modules' shapes (see the module doc). */
+interface AppliedRef {
+  apiVersion: string;
+  kind: string;
+  name: string;
+  namespace?: string;
+}
+
+interface ApplyOutcome {
+  fieldManager: string;
+  applied: AppliedRef[];
+  pruned: AppliedRef[];
+}
+
+interface ApplierArgs {
+  manifest: string;
+  environment?: string;
+  stack?: string;
+  context?: string;
+  deleteMode?: "never" | "owned-only" | "gated";
+}
+
+type Applier = (args: ApplierArgs) => Promise<ApplyOutcome>;
+
+interface ReadyWaiterArgs {
+  kind: string;
+  name: string;
+  namespace?: string;
+  group?: string;
+  environment?: string;
+  context?: string;
+  intervalMs?: number;
+}
+
+type ReadyWaiter = (args: ReadyWaiterArgs) => Promise<Record<string, unknown>>;
+
+export interface FluxReconcileOutcome extends ApplyOutcome {
+  /** The Flux CRs that reached Ready, in wait order (sources first). */
+  ready: AppliedRef[];
+}
+
+export interface FluxReconcileInput {
+  /** Path to the Flux CR manifest(s) — a file, or a directory of them. */
+  manifest: string;
+  /**
+   * The deploy unit / ownership stack — same double duty as kubectl-apply's.
+   * Omitted derives from the project's `ownership.stack`, but then the unit
+   * is invisible to `components status --live`. Name it.
+   */
+  stack?: string;
+  /** kubectl context. Omitted resolves `k8s.profiles.<ctx.env>.context`. */
+  context?: string;
+  /** Same delete vocabulary as kubectl-apply; default `never`. */
+  delete?: "never" | "owned-only";
+  /** Poll interval in ms (default 15000). */
+  intervalMs?: number;
+}
+
+/** The API group of a ref, "" for the core group. */
+function groupOf(ref: AppliedRef): string {
+  const slash = ref.apiVersion.indexOf("/");
+  return slash === -1 ? "" : ref.apiVersion.slice(0, slash);
+}
+
+/**
+ * True for any Flux CR: the toolkit groups (`source.` / `kustomize.` /
+ * `helm.` / `image.` / `notification.toolkit.fluxcd.io`) plus the flux-operator
+ * group (`fluxcd.controlplane.io`, `FluxInstance`). Kinds without a registry
+ * entry still wait correctly — the toolkit is kstatus-conformant, so the
+ * generic `Ready=True` default covers them; the #1554 entries add fail-fast.
+ */
+function isFluxRef(ref: AppliedRef): boolean {
+  const group = groupOf(ref);
+  return /(^|\.)toolkit\.fluxcd\.io$/.test(group) || group === "fluxcd.controlplane.io";
+}
+
+/** Factory with injectable applier + waiter — the argo-app seam. Defaults
+ * resolve by dynamic import on first run (#1074). */
+export function createFluxReconcileCapability(
+  apply?: Applier,
+  wait?: ReadyWaiter,
+): Capability<FluxReconcileInput, FluxReconcileOutcome> {
+  return {
+    kind: "flux-reconcile",
+    // Server-side apply keeps no previous object state, and the controller
+    // reconciles forward only — same posture as kubectl-apply.
+    rollbackPolicy: "needs-opt-out",
+    async run(ctx: DeployContext, input: FluxReconcileInput): Promise<FluxReconcileOutcome> {
+      const applier: Applier = apply ?? (await import("../op/activities/kubectl")).applyManifest;
+      const outcome = await applier({
+        manifest: input.manifest,
+        environment: ctx.env,
+        ...(input.stack !== undefined ? { stack: input.stack } : {}),
+        ...(input.context !== undefined ? { context: input.context } : {}),
+        ...(input.delete !== undefined ? { deleteMode: input.delete } : {}),
+      });
+
+      // Namespaces/ConfigMaps alongside the CRs apply fine; the wait gates
+      // only on the Flux objects. Sources first — see the module doc.
+      const flux = outcome.applied.filter(isFluxRef);
+      if (flux.length === 0) {
+        throw new Error(
+          `flux-reconcile: "${input.manifest}" applied no Flux CR (toolkit.fluxcd.io / fluxcd.controlplane.io) — ` +
+            `nothing to reconcile on. A plain manifest belongs on kubectl-apply.`,
+        );
+      }
+      const sources = flux.filter((r) => groupOf(r) === "source.toolkit.fluxcd.io");
+      const rest = flux.filter((r) => groupOf(r) !== "source.toolkit.fluxcd.io");
+
+      const waiter: ReadyWaiter =
+        wait ?? ((await import("../op/activities/wait-for-ready")).waitForReady as unknown as ReadyWaiter);
+      const ready: AppliedRef[] = [];
+      for (const ref of [...sources, ...rest]) {
+        await waiter({
+          kind: ref.kind,
+          name: ref.name,
+          group: groupOf(ref),
+          environment: ctx.env,
+          ...(ref.namespace !== undefined ? { namespace: ref.namespace } : {}),
+          ...(input.context !== undefined ? { context: input.context } : {}),
+          ...(input.intervalMs !== undefined ? { intervalMs: input.intervalMs } : {}),
+        });
+        ready.push(ref);
+      }
+      return { ...outcome, ready };
+    },
+  };
+}
+
+export const fluxReconcileCapability = createFluxReconcileCapability();

package/src/components/index.ts

@@ -26,3 +26,16 @@ export {
   type KustomizeApplyInput,
   type KustomizeApplyOutcome,
 } from "./kustomize-apply";
+export {
+  argoAppCapability,
+  createArgoAppCapability,
+  type ArgoAppInput,
+  type ArgoAppOutcome,
+  type ArgoAppSynced,
+} from "./argo-app";
+export {
+  fluxReconcileCapability,
+  createFluxReconcileCapability,
+  type FluxReconcileInput,
+  type FluxReconcileOutcome,
+} from "./flux-reconcile";

package/src/components/kustomize-apply.ts

@@ -14,32 +14,26 @@
  * `stack` doubles as the ownership identity and the deploy unit, exactly as
  * `kubectl-apply` — one name, both jobs.
  *
- * Renderer resolution: `kustomize build`, falling back to
+ * Renderer resolution lives in `../kustomize/render.ts` (shared with the
+ * build-root path, #1548 piece 3): `kustomize build`, falling back to
  * `kubectl kustomize` (the same renderer vendored into kubectl) when the
  * standalone binary is absent. Both run through an injectable runner so tests
- * assert the exact command without either binary installed. The 64MiB
- * maxBuffer mirrors helm-upgrade's — a big overlay renders megabytes.
+ * assert the exact command without either binary installed.
  *
  * The #1074 boundary applies as it does to kubectl-apply: nothing exported
  * from the lexicon entry point may statically import the API-client chain, so
  * the applier is reached by dynamic import inside `run()` and its argument
  * shape is a structural mirror.
  */
-import { exec } from "node:child_process";
-import { promisify } from "node:util";
-import { loadAll } from "js-yaml";
 import type { Capability, DeployContext } from "@intentius/chant/components/capability";
+import {
+  defaultKustomizeRunner,
+  renderCommand,
+  renderKustomizeDocuments,
+  type KustomizeRunner,
+} from "../kustomize/render";
 
-const execAsync = promisify(exec);
-
-/** Injectable shell runner — the helm-upgrade seam, same buffer bound. */
-export type KustomizeRunner = (command: string) => Promise<{ stdout: string }>;
-const defaultRunner: KustomizeRunner = (command) => execAsync(command, { maxBuffer: 64 * 1024 * 1024 });
-
-/** Single-quote shell escaping, as helm-upgrade quotes its argv. */
-function q(v: string): string {
-  return `'${v.replace(/'/g, "'\\''")}'`;
-}
+export { renderCommand, type KustomizeRunner };
 
 /** Structural mirrors of the activity module's shapes (see the module doc). */
 interface AppliedRef {
@@ -81,33 +75,10 @@ export interface KustomizeApplyInput {
   delete?: "never" | "owned-only";
 }
 
-/** The exact render command, standalone binary first. Pure; exported for tests. */
-export function renderCommand(dir: string, tool: "kustomize" | "kubectl" = "kustomize"): string {
-  return tool === "kustomize" ? `kustomize build ${q(dir)}` : `kubectl kustomize ${q(dir)}`;
-}
-
-/** Render the overlay, falling back to kubectl's vendored kustomize when the
- * standalone binary is missing (ENOENT/127), and parse the emitted YAML. */
-async function renderDocuments(dir: string, run: KustomizeRunner): Promise<Array<Record<string, unknown>>> {
-  let stdout: string;
-  try {
-    ({ stdout } = await run(renderCommand(dir, "kustomize")));
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    if (!/ENOENT|not found|command not found|127/.test(message)) throw err;
-    ({ stdout } = await run(renderCommand(dir, "kubectl")));
-  }
-  const documents: Array<Record<string, unknown>> = [];
-  for (const doc of loadAll(stdout)) {
-    if (doc && typeof doc === "object" && !Array.isArray(doc)) documents.push(doc as Record<string, unknown>);
-  }
-  return documents;
-}
-
 /** Factory with injectable renderer + applier, so tests assert the render
  * command and the exact applier delegation without kustomize or a cluster. */
 export function createKustomizeApplyCapability(
-  run: KustomizeRunner = defaultRunner,
+  run: KustomizeRunner = defaultKustomizeRunner,
   apply?: Applier,
 ): Capability<KustomizeApplyInput, KustomizeApplyOutcome> {
   return {
@@ -116,7 +87,7 @@ export function createKustomizeApplyCapability(
     // undo of its own — same posture as kubectl-apply.
     rollbackPolicy: "needs-opt-out",
     async run(ctx: DeployContext, input: KustomizeApplyInput): Promise<KustomizeApplyOutcome> {
-      const documents = await renderDocuments(input.dir, run);
+      const documents = await renderKustomizeDocuments(input.dir, run);
       const applier: Applier = apply ?? ((await import("../op/activities/kubectl")).applyManifest as unknown as Applier);
       return applier({
         manifest: `kustomize:${input.dir}`,