@intentius/chant-lexicon-k8s 0.30.0 → 0.32.0

package/src/kube/top.ts

@@ -0,0 +1,120 @@
+/**
+ * `chant kube top pods|nodes` (chant #1079).
+ *
+ * `metrics.k8s.io` is not part of the standard Kubernetes OpenAPI schema chant's
+ * codegen ingests — it is an aggregated API a cluster may or may not be running
+ * (metrics-server). It needs no entry in the generated operation surface either
+ * way: the typed client's kubectl-style selector (`{ resource, group }`) resolves
+ * purely off the *cluster's own* discovery, the same path `waitForReady`'s `kind`
+ * argument already uses for CRDs — so this needs no client change, only the
+ * right selector.
+ *
+ * Kubectl's own `top` sums each Pod's per-container usage into one CPU/memory
+ * figure, which needs real quantity-unit arithmetic (`250m` + `100m`, `128Mi` +
+ * `64Mi`). That normalization is not implemented here — each container's raw
+ * usage string is shown as the API reported it, unsummed. Good enough for "is
+ * anything obviously starved", not a replacement for `kubectl top --containers`.
+ */
+
+import { formatUnobserved } from "@intentius/chant/observation";
+import { defaultK8sConnector, type K8sConnector } from "../api/connect";
+import { classifyApiFailure } from "../api/classify";
+import { kubeConnect } from "./connect";
+import { parseKubeFlags, connectOptionsFrom } from "./flags";
+import { renderTable } from "./render";
+
+export interface TopDeps {
+  connect?: K8sConnector;
+}
+
+const RESOURCE_ALIASES: Record<string, "pods" | "nodes"> = {
+  pod: "pods",
+  pods: "pods",
+  po: "pods",
+  node: "nodes",
+  nodes: "nodes",
+  no: "nodes",
+};
+
+export async function runTop(rawArgs: string[], deps: TopDeps = {}): Promise<number> {
+  const connect = deps.connect ?? defaultK8sConnector;
+
+  let flags;
+  try {
+    flags = parseKubeFlags(rawArgs);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+
+  const resource = RESOURCE_ALIASES[flags.positional[0] ?? "pods"];
+  if (!resource) {
+    console.error(`error: unknown resource "${flags.positional[0]}" — chant kube top supports "pods" and "nodes"`);
+    return 1;
+  }
+
+  const connected = await kubeConnect(connectOptionsFrom(flags.values), connect);
+  if (connected.kind === "unobserved") {
+    console.error(formatUnobserved(resource, { reason: connected.reason, detail: connected.detail }));
+    return 1;
+  }
+  const { client } = connected;
+
+  let info;
+  try {
+    info = await client.resolve({ resource, group: "metrics.k8s.io" });
+  } catch (err) {
+    const outcome = classifyApiFailure(err);
+    console.error(
+      formatUnobserved(resource, {
+        reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+        detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+      }),
+    );
+    return 1;
+  }
+  if (!info) {
+    console.error(
+      "error: the metrics API (metrics.k8s.io) is not available in this cluster — is metrics-server installed?",
+    );
+    return 1;
+  }
+
+  const namespace = resource === "pods" && !flags.flags.allNamespaces ? (flags.values.namespace ?? client.defaultNamespace) : undefined;
+
+  let items;
+  try {
+    items = await client.list(
+      { apiVersion: info.apiVersion, kind: info.kind },
+      { ...(namespace ? { namespace } : {}) },
+    );
+  } catch (err) {
+    const outcome = classifyApiFailure(err);
+    console.error(
+      formatUnobserved(resource, {
+        reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+        detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+      }),
+    );
+    return 1;
+  }
+
+  if (resource === "nodes") {
+    const rows = items.map((n) => [
+      n.metadata?.name ?? "",
+      String((n.usage as Record<string, unknown> | undefined)?.cpu ?? "<unknown>"),
+      String((n.usage as Record<string, unknown> | undefined)?.memory ?? "<unknown>"),
+    ]);
+    console.log(renderTable(["NAME", "CPU", "MEMORY"], rows));
+    return 0;
+  }
+
+  const rows = items.map((p) => {
+    const containers = (p.containers as Array<{ name?: string; usage?: Record<string, unknown> }> | undefined) ?? [];
+    const cpu = containers.map((c) => `${c.name}:${c.usage?.cpu ?? "?"}`).join(",") || "<none>";
+    const memory = containers.map((c) => `${c.name}:${c.usage?.memory ?? "?"}`).join(",") || "<none>";
+    return [p.metadata?.namespace ?? "", p.metadata?.name ?? "", cpu, memory];
+  });
+  console.log(renderTable(["NAMESPACE", "NAME", "CPU (per container)", "MEMORY (per container)"], rows));
+  return 0;
+}

package/src/kube/verdict.test.ts

@@ -0,0 +1,48 @@
+import { describe, test, expect } from "vitest";
+import { verdictFor, declaredSubsetMatches } from "./verdict";
+import type { K8sObject } from "@intentius/chant-k8s-client";
+import type { DeclaredMatch } from "./project";
+import { fakeDeclarable } from "./testing";
+
+function match(props: Record<string, unknown>): DeclaredMatch {
+  return { entityName: "web", entity: fakeDeclarable("K8s::Apps::Deployment", props), props };
+}
+
+describe("declaredSubsetMatches", () => {
+  test("extra live fields (server defaults, status) are not drift", () => {
+    expect(
+      declaredSubsetMatches({ spec: { replicas: 2 } }, { spec: { replicas: 2, strategy: "RollingUpdate" }, status: { readyReplicas: 2 } }),
+    ).toBe(true);
+  });
+
+  test("a declared field the live object disagrees on is drift", () => {
+    expect(declaredSubsetMatches({ spec: { replicas: 2 } }, { spec: { replicas: 9 } })).toBe(false);
+  });
+
+  test("arrays must match length and every element", () => {
+    expect(declaredSubsetMatches({ a: [1, 2] }, { a: [1, 2, 3] })).toBe(false);
+    expect(declaredSubsetMatches({ a: [1, 2] }, { a: [1, 2] })).toBe(true);
+  });
+});
+
+describe("verdictFor", () => {
+  test("a matched entity with an agreeing live object is declared", () => {
+    const live = { metadata: { name: "web" }, spec: { replicas: 2 } } as unknown as K8sObject;
+    expect(verdictFor(live, match({ metadata: { name: "web" }, spec: { replicas: 2 } }))).toBe("declared");
+  });
+
+  test("a matched entity whose live spec disagrees is drifted", () => {
+    const live = { metadata: { name: "web" }, spec: { replicas: 9 } } as unknown as K8sObject;
+    expect(verdictFor(live, match({ metadata: { name: "web" }, spec: { replicas: 2 } }))).toBe("drifted");
+  });
+
+  test("no match + chant's marker label is owned", () => {
+    const live = { metadata: { name: "x", labels: { "app.kubernetes.io/managed-by": "chant" } } } as unknown as K8sObject;
+    expect(verdictFor(live, undefined)).toBe("owned");
+  });
+
+  test("no match + no marker is foreign-owned", () => {
+    const live = { metadata: { name: "x" } } as unknown as K8sObject;
+    expect(verdictFor(live, undefined)).toBe("foreign-owned");
+  });
+});

package/src/kube/verdict.ts

@@ -0,0 +1,77 @@
+/**
+ * The chant verdict column `chant kube get` carries on every row (chant
+ * #1079's acceptance criterion: "get annotates each row with the declared /
+ * owned / drifted / foreign-owned verdict").
+ *
+ * Four states:
+ *
+ * - `declared` — this project's source names an entity at this exact
+ *   apiVersion/kind/name(/namespace), and the live object agrees with it on
+ *   every field the source declares.
+ * - `drifted` — same match, but the live object disagrees with the source on
+ *   at least one declared field.
+ * - `owned` — no declared match, but the live object carries chant's
+ *   ownership marker (`app.kubernetes.io/managed-by=chant`) — something
+ *   chant applied that source no longer declares, or a stack/entity this
+ *   project's build didn't resolve.
+ * - `foreign-owned` — no declared match and no marker: chant does not
+ *   consider this object its own.
+ *
+ * `unavailable` is not a verdict about the object; it is what every row gets
+ * when the project context could not be loaded at all (chant #1079's
+ * "degrades gracefully outside a chant project" — `get` and `describe` still
+ * work, this column just has nothing to say).
+ *
+ * The drift check here is a fast, best-effort *declared-subset* comparison —
+ * every path the source sets must agree on the live object — not the
+ * managed-fields-precise diff `chant lifecycle diff --live --deep` computes
+ * (chant #1076). It exists for a table column that must render for dozens of
+ * rows in one `get` call; the deep, field-ownership-aware answer stays the
+ * lifecycle command's job. A live object can disagree with the source on a
+ * field a controller owns (Kubernetes rewriting `spec.replicas` under an
+ * HPA, say) and still show `drifted` here — reach for the deep diff before
+ * treating this column as a verdict rather than a hint.
+ */
+
+import type { K8sObject } from "@intentius/chant-k8s-client";
+import { hasOwnershipMarker, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+import type { DeclaredMatch } from "./project";
+
+export type KubeVerdict = "declared" | "owned" | "drifted" | "foreign-owned" | "unavailable";
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * True when every path `declared` sets is present and equal on `live`.
+ * Extra fields on `live` (server defaults, status, anything the source never
+ * mentions) are not drift — chant never declared an opinion about them.
+ */
+export function declaredSubsetMatches(declared: unknown, live: unknown): boolean {
+  if (Array.isArray(declared)) {
+    if (!Array.isArray(live) || declared.length !== live.length) return false;
+    return declared.every((item, i) => declaredSubsetMatches(item, live[i]));
+  }
+  if (isPlainObject(declared)) {
+    if (!isPlainObject(live)) return false;
+    return Object.entries(declared).every(([key, value]) => declaredSubsetMatches(value, live[key]));
+  }
+  return declared === live;
+}
+
+/** The declared fields worth comparing — everything but the name/namespace identity itself. */
+function declaredComparable(props: Record<string, unknown> | undefined): Record<string, unknown> {
+  if (!props) return {};
+  const { metadata, ...rest } = props;
+  if (!isPlainObject(metadata)) return rest;
+  const { name: _name, namespace: _namespace, ...restMetadata } = metadata;
+  return { ...rest, ...(Object.keys(restMetadata).length > 0 ? { metadata: restMetadata } : {}) };
+}
+
+export function verdictFor(live: K8sObject, match: DeclaredMatch | undefined): KubeVerdict {
+  if (match) {
+    return declaredSubsetMatches(declaredComparable(match.props), live) ? "declared" : "drifted";
+  }
+  return hasOwnershipMarker(live.metadata?.labels, LABEL_OWNERSHIP_KEYS) ? "owned" : "foreign-owned";
+}

package/src/kube/wait.test.ts

@@ -0,0 +1,125 @@
+import { describe, test, expect, vi, afterEach } from "vitest";
+import { ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+import { fakeCluster, objectKey } from "../api/fake-cluster";
+import { runWait } from "./wait";
+
+afterEach(() => vi.restoreAllMocks());
+
+function spyConsole() {
+  const log = vi.spyOn(console, "log").mockImplementation(() => {});
+  const error = vi.spyOn(console, "error").mockImplementation(() => {});
+  return { log, error };
+}
+
+function certificate(ready: boolean) {
+  return {
+    apiVersion: "cert-manager.io/v1",
+    kind: "Certificate",
+    metadata: { name: "web-tls", namespace: "prod", uid: "u1" },
+    status: { conditions: ready ? [{ type: "Ready", status: "True" }] : [{ type: "Ready", status: "False" }] },
+  };
+}
+
+describe("chant kube wait (#1079)", () => {
+  test("happy path: the registry's default Ready condition is satisfied immediately", async () => {
+    const cluster = fakeCluster({
+      objects: { [objectKey("cert-manager.io/v1", "Certificate", "web-tls", "prod")]: certificate(true) },
+    });
+    const { log } = spyConsole();
+
+    const code = await runWait(["certificate", "web-tls", "-n", "prod"], { connect: cluster.connector });
+
+    expect(code).toBe(0);
+    expect(log.mock.calls[0][0]).toContain("condition met");
+  });
+
+  test("--for=condition=<Type>=<Status> overrides the registry", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web", "prod")]: {
+          apiVersion: "apps/v1",
+          kind: "Deployment",
+          metadata: { name: "web", namespace: "prod", uid: "u1" },
+          status: { conditions: [{ type: "Available", status: "True" }] },
+        },
+      },
+    });
+    const { log } = spyConsole();
+
+    const code = await runWait(["deployment", "web", "-n", "prod", "--for=condition=Available"], {
+      connect: cluster.connector,
+    });
+
+    expect(code).toBe(0);
+    expect(log.mock.calls[0][0]).toContain("condition met");
+  });
+
+  test("--for=delete polls for absence", async () => {
+    const cluster = fakeCluster({});
+    const { log } = spyConsole();
+
+    const code = await runWait(["deployment", "ghost", "-n", "prod", "--for=delete", "--timeout=5s"], {
+      connect: cluster.connector,
+    });
+
+    expect(code).toBe(0);
+    expect(log.mock.calls[0][0]).toContain("deleted");
+  });
+
+  test("a resource that never becomes ready times out honestly", async () => {
+    const cluster = fakeCluster({
+      objects: { [objectKey("cert-manager.io/v1", "Certificate", "web-tls", "prod")]: certificate(false) },
+    });
+    const { error } = spyConsole();
+
+    const code = await runWait(["certificate", "web-tls", "-n", "prod", "--timeout=1s"], { connect: cluster.connector });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("timed out");
+  }, 10_000);
+
+  test("binding mismatch refuses loudly, before any wait loop starts", async () => {
+    const { error } = spyConsole();
+    const connect = async () => {
+      throw new ClusterBindingMismatchError("prod", "prod-eks", "dev-eks");
+    };
+
+    const code = await runWait(["deployment", "web", "--env", "prod"], { connect });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("no binding for this environment");
+  });
+
+  test("unknown flag is rejected before any connection", async () => {
+    const { error } = spyConsole();
+    const connect = vi.fn();
+
+    const code = await runWait(["deployment", "web", "--bogus"], { connect });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("Unknown flag");
+    expect(connect).not.toHaveBeenCalled();
+  });
+
+  test("wait requires a single named resource", async () => {
+    const { error } = spyConsole();
+    const connect = vi.fn();
+
+    const code = await runWait(["deployment"], { connect });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("requires a single named resource");
+    expect(connect).not.toHaveBeenCalled();
+  });
+
+  test("tri-state: a kind the cluster does not serve renders an explicit error", async () => {
+    const cluster = fakeCluster({ serves: [] });
+    const { error, log } = spyConsole();
+
+    const code = await runWait(["widgets", "gizmo"], { connect: cluster.connector });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain(`doesn't have a resource type "widgets"`);
+    expect(log).not.toHaveBeenCalled();
+  });
+});

package/src/kube/wait.ts

@@ -0,0 +1,160 @@
+/**
+ * `chant kube wait` (chant #1079) — the issue names this one explicitly:
+ * "`wait` should use the existing readiness-spec registry in
+ * `op/activities/wait-for-ready.ts`, which already handles the Argo case
+ * where health and sync replace a `Ready` condition — something `kubectl
+ * wait --for` cannot express without jsonpath gymnastics." This verb is a
+ * thin CLI shell around that exact registry (`readinessFor`/`isReady`/
+ * `firstTerminal`/`waitForReady`) — not a second implementation of it.
+ *
+ * `--for=condition=<Type>[=<Status>]` overrides the registry with a single
+ * condition check, matching kubectl's own flag. `--for=delete` polls for
+ * absence instead. Neither given falls back to the registry: the generic
+ * `Ready` condition, or a resource-specific override (Argo's `Application`
+ * today).
+ */
+
+import { formatUnobserved } from "@intentius/chant/observation";
+import { defaultK8sConnector, type K8sConnector } from "../api/connect";
+import { classifyApiFailure } from "../api/classify";
+import {
+  waitForReady,
+  readinessFor,
+  ReadinessFailedError,
+  type ReadinessSpec,
+  type ResourceFetcher,
+} from "../op/activities/wait-for-ready";
+import { kubeConnect } from "./connect";
+import { parseKubeFlags, connectOptionsFrom, parseDurationMs } from "./flags";
+import { loadKubeProjectContext, type KubeProjectContext } from "./project";
+import { resolveKubeTarget, isTargetError, type KubeTarget } from "./target";
+
+export interface WaitDeps {
+  connect?: K8sConnector;
+  loadProject?: (cwd?: string) => Promise<KubeProjectContext | undefined>;
+}
+
+type ForSpec = { kind: "delete" } | { kind: "spec"; spec: ReadinessSpec };
+
+function parseFor(value: string | undefined): ForSpec | undefined {
+  if (value === undefined) return undefined;
+  if (value === "delete") return { kind: "delete" };
+  const match = /^condition=([^=]+)(?:=(.+))?$/.exec(value);
+  if (!match) {
+    throw new Error(`--for expects "condition=<Type>[=<Status>]" or "delete", got "${value}"`);
+  }
+  return { kind: "spec", spec: { ready: [{ conditionType: match[1], status: match[2] ?? "True" }] } };
+}
+
+function targetLabel(target: KubeTarget): string {
+  return "apiVersion" in target.selector ? target.selector.kind : target.selector.resource;
+}
+
+export async function runWait(rawArgs: string[], deps: WaitDeps = {}): Promise<number> {
+  const connect = deps.connect ?? defaultK8sConnector;
+  const loadProject = deps.loadProject ?? loadKubeProjectContext;
+
+  let flags;
+  let forSpec: ForSpec | undefined;
+  let timeoutMs: number;
+  try {
+    flags = parseKubeFlags(rawArgs, { value: { "--for": "for", "--timeout": "timeout" } });
+    forSpec = parseFor(flags.values.for);
+    timeoutMs = flags.values.timeout !== undefined ? parseDurationMs(flags.values.timeout) : 30_000;
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+
+  const project = await loadProject();
+  const target = resolveKubeTarget(flags.positional, flags.values.namespace, project);
+  if (isTargetError(target)) {
+    console.error(`error: ${target.error}`);
+    return 1;
+  }
+  if (!target.name) {
+    console.error("error: chant kube wait requires a single named resource, e.g. `chant kube wait deployment web`");
+    return 1;
+  }
+
+  const connected = await kubeConnect(connectOptionsFrom(flags.values), connect);
+  if (connected.kind === "unobserved") {
+    console.error(formatUnobserved(targetLabel(target), { reason: connected.reason, detail: connected.detail }));
+    return 1;
+  }
+  const { client } = connected;
+
+  let info;
+  try {
+    info = await client.resolve(target.selector);
+  } catch (err) {
+    const outcome = classifyApiFailure(err);
+    console.error(
+      formatUnobserved(targetLabel(target), {
+        reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+        detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+      }),
+    );
+    return 1;
+  }
+  if (!info) {
+    console.error(`error: the server doesn't have a resource type "${targetLabel(target)}"`);
+    return 1;
+  }
+
+  const namespace = target.namespace ?? client.defaultNamespace;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    if (forSpec?.kind === "delete") {
+      await waitForDeletion(client, { apiVersion: info.apiVersion, kind: info.kind, name: target.name, namespace }, controller.signal);
+      console.log(`${info.kind}/${target.name} deleted`);
+      return 0;
+    }
+
+    const spec = forSpec?.kind === "spec" ? forSpec.spec : readinessFor(info.group, info.kind);
+    const fetcher: ResourceFetcher = async (args, signal) =>
+      (await client.read(
+        { apiVersion: info.apiVersion, kind: info.kind, name: args.name, ...(args.namespace ? { namespace: args.namespace } : {}) },
+        { signal },
+      )) as Record<string, unknown>;
+
+    await waitForReady({ kind: info.kind, name: target.name, namespace, group: info.group, spec }, controller.signal, fetcher);
+    console.log(`${info.kind}/${target.name} condition met`);
+    return 0;
+  } catch (err) {
+    if (err instanceof ReadinessFailedError) {
+      console.error(err.message);
+      return 1;
+    }
+    if (controller.signal.aborted) {
+      console.error(`error: timed out after ${timeoutMs}ms waiting for ${info.kind}/${target.name}`);
+      return 1;
+    }
+    const outcome = classifyApiFailure(err);
+    console.error(
+      formatUnobserved(`${info.kind}/${target.name}`, {
+        reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+        detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+      }),
+    );
+    return 1;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function waitForDeletion(
+  client: { readIfPresent: (ref: { apiVersion: string; kind: string; name: string; namespace?: string }, opts: { signal?: AbortSignal }) => Promise<unknown> },
+  ref: { apiVersion: string; kind: string; name: string; namespace?: string },
+  signal: AbortSignal,
+  intervalMs = 5_000,
+): Promise<void> {
+  while (true) {
+    if (signal.aborted) throw new Error("wait --for=delete aborted");
+    const obj = await client.readIfPresent(ref, { signal });
+    if (!obj) return;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+}