@intentius/chant-lexicon-k8s 0.41.19 → 0.42.1

package/src/describe-resources.ts

@@ -104,9 +104,54 @@ export function statusFromObject(obj: K8sObject): string {
       ? "READY"
       : `PROGRESSING(${status.readyReplicas}/${status.replicas})`;
   }
+
+  // The kstatus rung (#1549): an object with NO phase and NO replica counts —
+  // a Flux Kustomization/HelmRelease, cert-manager, any conditions-first CRD —
+  // used to fall straight to PRESENT, so a wedged reconciler read exactly like
+  // a healthy one. `Ready` is the contract those objects speak: False → its
+  // reason (`BuildFailed`, `UpgradeFailed`, …), True → READY. Deliberately
+  // BELOW the phase/replica rungs so no Pod or workload word changes — for
+  // those objects a False Ready is already visible through the rungs above.
+  const ready = readyConditionWord(status);
+  if (ready) return ready;
+
+  // Argo's Application speaks health/sync, not a Ready condition (the same
+  // split the readiness registry encodes) — `Degraded` / `OutOfSync` beats
+  // PRESENT for the one object whose whole job is convergence.
+  const argo = argoStatusWord(status);
+  if (argo) return argo;
+
   return "PRESENT";
 }
 
+/** The `Ready` condition rendered as a status word: False → its reason (or
+ * NOT-READY when the controller gave none), True → READY, absent → nothing. */
+function readyConditionWord(status: K8sObject["status"]): string | undefined {
+  const conditions = (status as { conditions?: unknown } | undefined)?.conditions;
+  if (!Array.isArray(conditions)) return undefined;
+  for (const c of conditions) {
+    const cond = c as { type?: unknown; status?: unknown; reason?: unknown };
+    if (cond.type !== "Ready") continue;
+    if (cond.status === "True") return "READY";
+    if (cond.status === "False") {
+      return typeof cond.reason === "string" && cond.reason.length > 0 ? cond.reason : "NOT-READY";
+    }
+  }
+  return undefined;
+}
+
+/** Argo Application health/sync as a status word: anything but the happy pair
+ * surfaces the unhappy half; Healthy+Synced reads as READY. */
+function argoStatusWord(status: K8sObject["status"]): string | undefined {
+  const s = status as { health?: { status?: unknown }; sync?: { status?: unknown } } | undefined;
+  const health = typeof s?.health?.status === "string" ? s.health.status : undefined;
+  const sync = typeof s?.sync?.status === "string" ? s.sync.status : undefined;
+  if (!health && !sync) return undefined;
+  if (health && health !== "Healthy") return health;
+  if (sync && sync !== "Synced") return sync;
+  return "READY";
+}
+
 /**
  * The reason a container is stuck, if one is — `CrashLoopBackOff`,
  * `ImagePullBackOff`, `CreateContainerConfigError`.
@@ -333,7 +378,7 @@ export async function describeResources(
     if (op && op.apiVersion.includes("/")) runtimeGroupVersions.add(op.apiVersion);
   }
 
-  await addRuntimeChildren(client, resources, options.owned, runtimeGroupVersions);
+  await addRuntimeChildren(client, resources, options.owned, runtimeGroupVersions, declared);
 
   return observation(resources, unobserved);
 }
@@ -360,22 +405,99 @@ export async function describeResources(
  * axis for them to report against, the same way an out-of-band AWS child
  * resource has none either.
  */
+/** The declared GitOps CRs, indexed the way their controllers' labels can be
+ * resolved (#1549). `byRef` keys are `type\0namespace\0name` (Flux — exact);
+ * `argoByName` maps an Application's name to its declared entity, or null
+ * when two declared Applications share the name (ambiguous → no claim). */
+interface GitopsIndex {
+  present: boolean;
+  byRef: Map<string, string>;
+  argoByName: Map<string, string | null>;
+  targetNamespaces: Set<string>;
+}
+
+function gitopsIndex(declared: readonly Declared[]): GitopsIndex {
+  const byRef = new Map<string, string>();
+  const argoByName = new Map<string, string | null>();
+  const targetNamespaces = new Set<string>();
+  let present = false;
+  for (const { entityName, entityType, props } of declared) {
+    const isArgo = entityType === "K8s::Argo::Application";
+    const isFlux = entityType === "K8s::Flux::Kustomization" || entityType === "K8s::Flux::HelmRelease";
+    if (!isArgo && !isFlux) continue;
+    present = true;
+    const meta = props.metadata as { name?: string; namespace?: string } | undefined;
+    const spec = props.spec as { targetNamespace?: unknown; destination?: { namespace?: unknown } } | undefined;
+    const name = meta?.name;
+    if (!name) continue;
+    if (isFlux) {
+      byRef.set(`${entityType}\0${meta?.namespace ?? "default"}\0${name}`, entityName);
+      if (typeof spec?.targetNamespace === "string") targetNamespaces.add(spec.targetNamespace);
+    } else {
+      argoByName.set(name, argoByName.has(name) ? null : entityName);
+      if (typeof spec?.destination?.namespace === "string") targetNamespaces.add(spec.destination.namespace);
+    }
+  }
+  return { present, byRef, argoByName, targetNamespaces };
+}
+
+/** The declared GitOps CR a swept object's controller labels resolve to, or
+ * undefined. Flux's label pairs are exact; Argo's bare instance label claims
+ * only a UNIQUE declared Application. */
+function gitopsOwner(labels: Record<string, string> | undefined, gitops: GitopsIndex): string | undefined {
+  if (!labels || !gitops.present) return undefined;
+  const ksName = labels["kustomize.toolkit.fluxcd.io/name"];
+  const ksNs = labels["kustomize.toolkit.fluxcd.io/namespace"];
+  if (ksName && ksNs) {
+    const hit = gitops.byRef.get(`K8s::Flux::Kustomization\0${ksNs}\0${ksName}`);
+    if (hit) return hit;
+  }
+  const hrName = labels["helm.toolkit.fluxcd.io/name"];
+  const hrNs = labels["helm.toolkit.fluxcd.io/namespace"];
+  if (hrName && hrNs) {
+    const hit = gitops.byRef.get(`K8s::Flux::HelmRelease\0${hrNs}\0${hrName}`);
+    if (hit) return hit;
+  }
+  const instance = labels["app.kubernetes.io/instance"];
+  if (instance) {
+    const hit = gitops.argoByName.get(instance);
+    if (hit) return hit; // null (ambiguous) and undefined both decline
+  }
+  return undefined;
+}
+
 async function addRuntimeChildren(
   client: K8sClient,
   resources: Record<string, ResourceMetadata>,
   owned: boolean | undefined,
   groupVersions: ReadonlySet<string> = new Set(),
+  declared: readonly Declared[] = [],
 ): Promise<void> {
   const declaredByUid = new Map<string, string>();
   for (const [entityName, meta] of Object.entries(resources)) {
     if (meta.physicalId) declaredByUid.set(meta.physicalId, entityName);
   }
 
+  // GitOps attribution (#1549): Argo and Flux stamp their managed objects with
+  // labels, not ownerReferences, so the chain walk never reaches a declared
+  // entity for them. The label channel resolves against the DECLARED CRs by
+  // (type, namespace, name) — exact for Flux (its labels carry both halves) —
+  // and by unique name for Argo (its instance label carries no namespace, and
+  // it doubles as a generic Helm label, so anything ambiguous resolves to
+  // nothing: the module's standing conservatism).
+  const gitops = gitopsIndex(declared);
+
   const namespaces = new Set<string>();
   for (const meta of Object.values(resources)) {
     const namespace = (meta.attributes as { namespace?: string } | undefined)?.namespace;
     if (namespace) namespaces.add(namespace);
   }
+  // The namespaces a declared GitOps CR TARGETS are declared literals too
+  // (Argo `spec.destination.namespace`, Flux `spec.targetNamespace`) — the
+  // controller puts the workloads there, so the scan must look there, and
+  // reading it off the declaration keeps this bounded by the estate, never a
+  // cluster-wide sweep.
+  for (const ns of gitops.targetNamespaces) namespaces.add(ns);
   if (namespaces.size === 0) return;
 
   // The kinds to scan: Pods, plus each declared groupVersion's namespaced,
@@ -384,6 +506,18 @@ async function addRuntimeChildren(
   const kinds: Array<{ apiVersion: string; kind: string; typeName: string }> = [
     { apiVersion: "v1", kind: "Pod", typeName: "K8s::Core::Pod" },
   ];
+  // A GitOps estate's managed WORKLOADS live in groups the estate itself never
+  // declares (a pure Argo/Flux estate declares only the CRs), so without this
+  // the label channel could only ever fire on Pods (#1549).
+  if (gitops.present) {
+    kinds.push(
+      { apiVersion: "apps/v1", kind: "Deployment", typeName: "K8s::Apps::Deployment" },
+      { apiVersion: "apps/v1", kind: "StatefulSet", typeName: "K8s::Apps::StatefulSet" },
+      { apiVersion: "apps/v1", kind: "DaemonSet", typeName: "K8s::Apps::DaemonSet" },
+      { apiVersion: "v1", kind: "Service", typeName: "K8s::Core::Service" },
+      { apiVersion: "v1", kind: "ConfigMap", typeName: "K8s::Core::ConfigMap" },
+    );
+  }
   for (const gv of [...groupVersions].sort()) {
     let infos;
     try {
@@ -413,7 +547,13 @@ async function addRuntimeChildren(
         if (!uid || !name || declaredByUid.has(uid)) return; // declared directly, or unaddressable
         if (resources[`${namespace}/${name}`]) return; // already reported by an earlier kind
 
-        const ownerChain = await resolveK8sOwnerChain(obj, { declaredByUid, reader: client, namespace });
+        let ownerChain = await resolveK8sOwnerChain(obj, { declaredByUid, reader: client, namespace });
+        // The label channel (#1549) — only when the chain itself said nothing:
+        // a verdict the walk DID reach is never overridden.
+        if (ownerChain.root !== "declared") {
+          const entity = gitopsOwner(obj.metadata?.labels, gitops);
+          if (entity) ownerChain = { root: "declared", entity };
+        }
 
         // `--owned`: withhold an object that is neither a runtime child of a
         // declared entity nor carrying chant's own marker — the same rule the

package/src/index.ts

@@ -9,6 +9,7 @@ export { k8sPlugin } from "./plugin";
 // cfn-deploy.
 export { k8sCapabilityPlugin, K8S_VERB_FAMILIES } from "./components/capability-plugin";
 export { kubectlApplyCapability, createKubectlApplyCapability, type KubectlApplyInput } from "./components/kubectl-apply";
+export { kustomizeApplyCapability, createKustomizeApplyCapability, type KustomizeApplyInput } from "./components/kustomize-apply";
 
 // Default labels & annotations
 export { defaultLabels, defaultAnnotations, isDefaultLabels, isDefaultAnnotations } from "./default-labels";

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

@@ -281,6 +281,28 @@ describe("kubectlApply", () => {
     expect(body.metadata?.labels).toBeUndefined();
   });
 
+  test("inline documents bypass the filesystem — the kustomize-apply seam (#1548)", async () => {
+    const cluster = fakeCluster({ respond: echoApplies });
+    const result = await applyManifest(
+      {
+        manifest: "kustomize:overlays/dev", // a label; nothing at this path
+        documents: [
+          { apiVersion: "v1", kind: "Namespace", metadata: { name: "web" } },
+          { apiVersion: "apps/v1", kind: "Deployment", metadata: { name: "app", namespace: "web" } },
+        ],
+        stack: "web",
+      },
+      undefined,
+      cluster.connector,
+    );
+    expect(result.applied.map((r) => r.kind)).toEqual(["Namespace", "Deployment"]);
+    // The documents were stamped like any read-from-disk manifest.
+    const body = JSON.parse(String(cluster.layer.requests.find((r) => r.method === "PATCH")!.body)) as {
+      metadata?: { labels?: Record<string, string> };
+    };
+    expect(body.metadata?.labels?.["chant.intentius.io/stack"]).toBe("web");
+  });
+
   test("an explicit context is honored and skips the environment lookup entirely", async () => {
     const file = join(dir, "k8s.yaml");
     writeFileSync(file, deploymentYaml);

package/src/op/activities/kubectl.ts

@@ -55,8 +55,21 @@ import { DEFAULT_IMPORT_TYPES } from "../../api/sweep-types";
 export type ApplyDeleteMode = "never" | "owned-only" | "gated";
 
 export interface KubectlApplyArgs {
-  /** Path to a manifest file, or a directory of them. */
+  /**
+   * Path to a manifest file, or a directory of them. With `documents` given,
+   * this becomes only the human-facing label the heartbeats and logs carry
+   * (e.g. `kustomize:<dir>`), and nothing is read from disk.
+   */
   manifest: string;
+  /**
+   * Already-parsed documents to apply INSTEAD of reading `manifest` (#1548):
+   * a renderer that produced the objects in memory — kustomize-apply's
+   * `kustomize build` — hands them straight in rather than round-tripping
+   * through a temp file. Everything downstream (ownership stamping, the
+   * marker-scoped prune, the self-conflict retake) is document-driven and
+   * behaves identically.
+   */
+  documents?: K8sObject[];
   /**
    * kubectl context name. Uses the ambient context if omitted. To target the
    * same cluster the read path (`describeResources`) resolved for an
@@ -285,7 +298,7 @@ export async function applyManifest(
   signal?: AbortSignal,
   connect: K8sConnector = defaultK8sConnector,
 ): Promise<ApplyManifestResult> {
-  const documents = readManifestDocuments(args.manifest);
+  const documents = args.documents ?? readManifestDocuments(args.manifest);
   const { fieldManager, stack } = await resolveApplyIdentity(args);
   const heartbeatInterval = setInterval(() => {
     safeHeartbeat({ step: "kubectl apply", manifest: args.manifest });

package/src/op/activities/wait-for-ready.test.ts

@@ -49,6 +49,33 @@ describe("readiness model", () => {
     expect(isReady(obj, DEFAULT_READINESS)).toBe(true);
   });
 
+  test("Flux overrides fail fast on Ready=False wedge reasons, wait on ordinary progress (#1549)", () => {
+    // A Flux wedge (bad build, failed upgrade, unreachable source) keeps
+    // Ready=False forever — before these entries the generic poll waited out
+    // its whole timeout. The ready half is still the kstatus default.
+    const spec = readinessFor("kustomize.toolkit.fluxcd.io", "Kustomization");
+    expect(spec).not.toBe(DEFAULT_READINESS);
+    expect(isReady(ready([{ type: "Ready", status: "True" }]), spec)).toBe(true);
+
+    const wedged = ready([{ type: "Ready", status: "False", reason: "BuildFailed" } as never]);
+    expect(isReady(wedged, spec)).toBe(false);
+    expect(firstTerminal(wedged, spec)).toBeDefined();
+
+    // Ready=False with a PROGRESS reason (a reconcile in flight) is not a
+    // wedge — keep polling.
+    const progressing = ready([{ type: "Ready", status: "False", reason: "Progressing" } as never]);
+    expect(firstTerminal(progressing, spec)).toBeUndefined();
+
+    // A reason on a TRUE condition is vocabulary, never terminal.
+    const healthyWithReason = ready([{ type: "Ready", status: "True", reason: "ReconciliationSucceeded" } as never]);
+    expect(firstTerminal(healthyWithReason, spec)).toBeUndefined();
+
+    const hr = readinessFor("helm.toolkit.fluxcd.io", "HelmRelease");
+    expect(firstTerminal(ready([{ type: "Ready", status: "False", reason: "UpgradeFailed" } as never]), hr)).toBeDefined();
+    const git = readinessFor("source.toolkit.fluxcd.io", "GitRepository");
+    expect(firstTerminal(ready([{ type: "Ready", status: "False", reason: "AuthenticationFailed" } as never]), git)).toBeDefined();
+  });
+
   test("Argo override uses health/sync, not a Ready condition", () => {
     const spec = readinessFor("argoproj.io", "Application");
     expect(spec).not.toBe(DEFAULT_READINESS);

package/src/op/activities/wait-for-ready.ts

@@ -40,7 +40,23 @@ export interface PathMatch {
   // With neither `equals` nor `oneOf`, holds when the value is present (non-null).
 }
 
-export type ReadinessMatch = ConditionMatch | PathMatch;
+/**
+ * Match a `status.conditions[]` entry by `type` AND its `reason` (#1549).
+ * The dot-path walk can't index into a conditions array, and the Flux
+ * toolkit's failure signal is exactly `conditions[type=Ready].reason` — a
+ * wedge like `BuildFailed` keeps `Ready=False` forever while the generic
+ * poll waits out its whole timeout. `status` defaults to "False": a reason
+ * on a True condition is progress vocabulary, not a wedge.
+ */
+export interface ConditionReasonMatch {
+  conditionType: string;
+  /** Required `status` of the condition (default "False"). */
+  status?: string;
+  /** Holds when the condition's `reason` is one of these. */
+  reasonOneOf: string[];
+}
+
+export type ReadinessMatch = ConditionMatch | PathMatch | ConditionReasonMatch;
 
 export interface ReadinessSpec {
   /** All must hold for the resource to be ready. */
@@ -69,6 +85,19 @@ export const DEFAULT_READINESS: ReadinessSpec = {
  * reports `health`/`sync`, not a `Ready` condition — the case that proves the
  * override is necessary (#365).
  */
+/**
+ * Flux toolkit wedge reasons (#1549): a `Ready=False` with one of these
+ * `reason`s does not heal by waiting — a bad build, a failed install, an
+ * unreachable or invalid source. The toolkit is kstatus-conformant, so the
+ * READY half of every entry below is just the default; the value added is
+ * failing fast instead of polling out the full timeout.
+ */
+const FLUX_TERMINAL = (reasons: string[]): ReadinessSpec => ({
+  ready: [{ conditionType: "Ready", status: "True" }],
+  terminal: [{ conditionType: "Ready", reasonOneOf: reasons }],
+  observedGeneration: true,
+});
+
 export const READINESS_OVERRIDES: Record<string, ReadinessSpec> = {
   "argoproj.io/Application": {
     ready: [
@@ -78,6 +107,38 @@ export const READINESS_OVERRIDES: Record<string, ReadinessSpec> = {
     terminal: [{ path: "status.health.status", oneOf: ["Degraded", "Missing"] }],
     observedGeneration: false,
   },
+  "kustomize.toolkit.fluxcd.io/Kustomization": FLUX_TERMINAL([
+    "BuildFailed",
+    "HealthCheckFailed",
+    "ReconciliationFailed",
+    "ArtifactFailed",
+    "PruneFailed",
+  ]),
+  "helm.toolkit.fluxcd.io/HelmRelease": FLUX_TERMINAL([
+    "InstallFailed",
+    "UpgradeFailed",
+    "RollbackFailed",
+    "UninstallFailed",
+    "ArtifactFailed",
+    "ChartPullError",
+  ]),
+  "source.toolkit.fluxcd.io/GitRepository": FLUX_TERMINAL([
+    "AuthenticationFailed",
+    "GitOperationFailed",
+    "URLInvalid",
+    "StorageOperationFailed",
+  ]),
+  "source.toolkit.fluxcd.io/OCIRepository": FLUX_TERMINAL([
+    "AuthenticationFailed",
+    "OCIPullFailed",
+    "URLInvalid",
+    "StorageOperationFailed",
+  ]),
+  "source.toolkit.fluxcd.io/HelmChart": FLUX_TERMINAL([
+    "ChartPullError",
+    "ChartPackageError",
+    "StorageOperationFailed",
+  ]),
 };
 
 /** Resolve the readiness spec for a resource: registry override, else default. */
@@ -94,15 +155,31 @@ function getPath(obj: unknown, path: string): unknown {
   );
 }
 
+function isConditionReason(m: ReadinessMatch): m is ConditionReasonMatch {
+  return (m as ConditionReasonMatch).reasonOneOf !== undefined;
+}
+
 function isCondition(m: ReadinessMatch): m is ConditionMatch {
-  return (m as ConditionMatch).conditionType !== undefined;
+  return (m as ConditionMatch).conditionType !== undefined && !isConditionReason(m);
 }
 
-function matchCondition(obj: unknown, m: ConditionMatch): boolean {
+function findCondition(obj: unknown, conditionType: string): Record<string, unknown> | undefined {
   const conds = getPath(obj, "status.conditions");
-  if (!Array.isArray(conds)) return false;
-  const c = conds.find((x) => x && typeof x === "object" && (x as Record<string, unknown>).type === m.conditionType);
-  return !!c && String((c as Record<string, unknown>).status) === (m.status ?? "True");
+  if (!Array.isArray(conds)) return undefined;
+  return conds.find((x) => x && typeof x === "object" && (x as Record<string, unknown>).type === conditionType) as
+    | Record<string, unknown>
+    | undefined;
+}
+
+function matchCondition(obj: unknown, m: ConditionMatch): boolean {
+  const c = findCondition(obj, m.conditionType);
+  return !!c && String(c.status) === (m.status ?? "True");
+}
+
+function matchConditionReason(obj: unknown, m: ConditionReasonMatch): boolean {
+  const c = findCondition(obj, m.conditionType);
+  if (!c || String(c.status) !== (m.status ?? "False")) return false;
+  return typeof c.reason === "string" && m.reasonOneOf.includes(c.reason);
 }
 
 function matchPath(obj: unknown, m: PathMatch): boolean {
@@ -113,6 +190,7 @@ function matchPath(obj: unknown, m: PathMatch): boolean {
 }
 
 function matches(obj: unknown, m: ReadinessMatch): boolean {
+  if (isConditionReason(m)) return matchConditionReason(obj, m);
   return isCondition(m) ? matchCondition(obj, m) : matchPath(obj, m);
 }