@intentius/chant-lexicon-k8s 0.124.30 → 0.124.32

package/dist/op/activities/kubectl.js

@@ -0,0 +1,517 @@
+/**
+ * `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) because an Op step names the activity by its export
+ * name and core's registry resolves it there; what changed is underneath. The
+ * name is kept for the same reason.
+ *
+ * chant #1075 finished the job on two axes:
+ *
+ * - **Identity.** The field manager is no longer the bare `chant` but
+ *   `chant:<stack>`, derived from the project's `ownership.stack` — the same
+ *   identity the ownership label already carries. See
+ *   `@intentius/chant-k8s-client`'s `field-manager.ts`.
+ * - **Deletes.** `nativeApply`'s kubectl branch used to shell
+ *   `kubectl apply --prune --selector <marker>`; that branch now routes here,
+ *   so the prune had to come with it. {@link applyManifest} implements it
+ *   against the typed client, scoped to the ownership marker exactly as the
+ *   shelled prune was, and never touching an object that does not carry it.
+ *
+ * Consequences worth knowing:
+ *
+ * - **A worker image needs no `kubectl` binary.** That was the point.
+ * - **It is a server-side apply**, rather than the client-side three-way merge
+ *   `kubectl apply` performs by default. A conflict with another field manager
+ *   arrives as a `FieldManagerConflictError` naming the competing manager and
+ *   the contested paths — never as a silent overwrite, and never force-resolved
+ *   on chant's initiative.
+ * - **Documents apply in file order**, as `kubectl apply -f` does, and a
+ *   directory's files are read in sorted order.
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { loadAll } from "js-yaml";
+import { loadChantConfig, resolveOwnershipStack } from "@intentius/chant/config";
+import { hasOwnershipMarker, LABEL_OWNERSHIP_KEYS, OWNERSHIP_MANAGED_BY_VALUE, } from "@intentius/chant/ownership";
+import { defaultK8sConnector } from "../../api/connect.js";
+import { operationFor } from "../../api/operation-surface.js";
+import { DEFAULT_IMPORT_TYPES } from "../../api/sweep-types.js";
+import { isGeneratedOnce } from "../../secret-labels.js";
+import { isEffectReceiptObject } from "../../effect-receipt-row.js";
+import { diffFields, normalizeServerObject } from "./apply-diff.js";
+/** Read a manifest path — one file, or every YAML/JSON file in a directory. */
+export function readManifestDocuments(path) {
+    const files = statSync(path).isDirectory()
+        ? readdirSync(path)
+            .filter((f) => /\.(ya?ml|json)$/i.test(f))
+            .sort()
+            .map((f) => join(path, f))
+        : [path];
+    const documents = [];
+    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);
+        }
+    }
+    return documents;
+}
+/**
+ * The field manager to apply as: an explicit one, else `chant:<stack>` from a
+ * caller-supplied stack, else `chant:<stack>` from the project's `ownership`
+ * config, else the bare `chant`.
+ *
+ * A project config that cannot be read falls back to the bare `chant` with a
+ * warning rather than failing the apply — an activity handed a manifest path
+ * and nothing else is a supported way to call this, and its cwd need not be a
+ * chant project at all. The warning is there because a *silent* downgrade
+ * would change which fields chant owns without saying so.
+ */
+export async function resolveFieldManager(args) {
+    return (await resolveApplyIdentity(args)).fieldManager;
+}
+/**
+ * The stack and the field manager together, resolved once. The prune needs the
+ * stack for its selector and the apply needs the manager; reading the project
+ * config twice for one apply would be silly, and could disagree with itself if
+ * the file changed in between.
+ */
+async function resolveApplyIdentity(args) {
+    const { fieldManagerFor, assertValidFieldManager } = await import("@intentius/chant-k8s-client");
+    let stack = args.stack;
+    if (stack === undefined) {
+        try {
+            const { config } = await loadChantConfig(args.cwd ?? process.cwd());
+            stack = resolveOwnershipStack(config);
+        }
+        catch (err) {
+            console.warn(`[k8s] could not read the project config to derive a field manager ` +
+                `(${err instanceof Error ? err.message : String(err)}); applying as the unqualified "chant"`);
+        }
+    }
+    if (args.fieldManager !== undefined) {
+        assertValidFieldManager(args.fieldManager);
+        return { fieldManager: args.fieldManager, ...(stack !== undefined ? { stack } : {}) };
+    }
+    return {
+        fieldManager: fieldManagerFor(stack !== undefined ? { stack } : undefined),
+        ...(stack !== undefined ? { stack } : {}),
+    };
+}
+/** chant's reserved label channel — the `chant.intentius.io/*` keys the
+ * ownership marker lives under, as a conflict-cause field-path prefix. */
+const MARKER_FIELD_PREFIX = `.metadata.labels.${LABEL_OWNERSHIP_KEYS.stack.split("/")[0]}/`;
+/**
+ * Is this conflict one chant may retake without a human? Two shapes qualify,
+ * per contested field:
+ *
+ * - the owning manager is chant itself (`chant` bare or `chant:<stack>`) —
+ *   the ownership-stack → unit-stack migration, or a renamed deploy unit; or
+ * - the field lives in chant's OWN reserved label channel
+ *   (`chant.intentius.io/*`). A controller that reconciles whole objects
+ *   echoes existing labels and becomes their SSA owner as a side effect
+ *   (observed live: kubemicrovm's `microvmimagereconciler` owning
+ *   `.metadata.labels.chant.intentius.io/stack`) — it never chose that value,
+ *   and chant is the authority for its marker namespace no matter who last
+ *   echoed it.
+ *
+ * Any contested field outside both shapes — a spec field, an app label —
+ * keeps the presented refusal: that IS a dispute with another tool.
+ */
+function isChantSelfConflict(err) {
+    const e = err;
+    if (!e || e.name !== "FieldManagerConflictError" || !Array.isArray(e.conflicts) || e.conflicts.length === 0)
+        return false;
+    return e.conflicts.every((c) => {
+        const chantManager = typeof c.manager === "string" && (c.manager === "chant" || c.manager.startsWith("chant:"));
+        const markerField = typeof c.field === "string" && c.field.startsWith(MARKER_FIELD_PREFIX);
+        return chantManager || markerField;
+    });
+}
+/**
+ * Stamp the apply's own stack identity onto a document's labels.
+ *
+ * The serializer bakes `ownership.stack` — the *project* identity from
+ * `chant.config.ts` — into every manifest it emits. But the apply's identity
+ * is the *stack argument it resolved* (a component's `kubectl-apply` step
+ * names its own deploy unit, e.g. `kmv-workload`), and that is the value both
+ * consumers of the label query for: the owned-only prune's selector and
+ * `describeStackStatus`'s presence sweep. Applying the manifest verbatim left
+ * the label saying `kubemicrovm-ops` while both readers asked for
+ * `kmv-workload` — the prune silently matched nothing and every kubectl-apply
+ * unit read absent in `components status --live` (a green estate painted
+ * dead). A manifest chant never serialized (upstream CRDs pinned into a
+ * `crds` unit) carried no marker at all, with the same two failures.
+ *
+ * So the apply now re-stamps what it applies: `managed-by=chant` plus the
+ * resolved stack. The ownership *verdict* keys on `managed-by` alone
+ * (core/ownership.ts `hasOwnershipMarker`), so overlay classification is
+ * unchanged; the env label is the serializer's to write and is left as-is.
+ * No stack resolved (no explicit arg, no project ownership) applies verbatim,
+ * exactly as before.
+ */
+function stampOwnership(document, stack) {
+    if (stack === undefined)
+        return document;
+    const metadata = (document.metadata ?? {});
+    return {
+        ...document,
+        metadata: {
+            ...metadata,
+            labels: {
+                ...(metadata.labels ?? {}),
+                [LABEL_OWNERSHIP_KEYS.managedBy]: OWNERSHIP_MANAGED_BY_VALUE,
+                [LABEL_OWNERSHIP_KEYS.stack]: stack,
+            },
+        },
+    };
+}
+/**
+ * Apply every document in `args.manifest`, then prune when asked.
+ *
+ * Returns what it did. `kubectlApply` is the registered activity and keeps its
+ * `Promise<void>` contract; this is the function `nativeApply` calls, because a
+ * dispatcher that reports "applied 12, pruned 2" is worth more than one that
+ * reports the shell command it ran.
+ */
+export async function applyManifest(args, signal, connect = defaultK8sConnector) {
+    const documents = args.documents ?? readManifestDocuments(args.manifest);
+    const { fieldManager, stack } = await resolveApplyIdentity(args);
+    const { client } = await connect({
+        ...(args.environment !== undefined ? { environment: args.environment } : {}),
+        ...(args.context !== undefined ? { context: args.context } : {}),
+        ...(args.cwd !== undefined ? { cwd: args.cwd } : {}),
+    });
+    const applied = [];
+    for (const document of documents) {
+        const stamped = stampOwnership(document, stack);
+        let result;
+        try {
+            result = await client.apply(stamped, {
+                fieldManager,
+                force: args.force ?? false,
+                dryRun: args.dryRun,
+                signal,
+            });
+        }
+        catch (err) {
+            // "chant never forces a conflict on its own" is about taking fields
+            // from ANOTHER tool. A conflict where every contested field is owned
+            // by another `chant:*` manager is chant contesting itself — the
+            // ownership-stack → unit-stack label migration, or a renamed deploy
+            // unit — and refusing that forever would strand every estate applied
+            // before the rename with no non-force path back. Retake those fields
+            // deliberately, once, and only when no foreign manager is involved.
+            if (!isChantSelfConflict(err))
+                throw err;
+            result = await client.apply(stamped, { fieldManager, force: true, dryRun: args.dryRun, signal });
+        }
+        const ref = {
+            apiVersion: String(result.apiVersion ?? document.apiVersion ?? ""),
+            kind: String(result.kind ?? document.kind ?? ""),
+            name: String(result.metadata?.name ?? ""),
+            ...(result.metadata?.namespace !== undefined
+                ? { namespace: String(result.metadata.namespace) }
+                : {}),
+        };
+        applied.push(ref);
+        console.log(`${ref.apiVersion} ${ref.kind}/${ref.name} applied${args.dryRun ? " (dry run — nothing persisted)" : ""}`);
+    }
+    const deleteMode = args.deleteMode ?? "never";
+    const { pruned, retained } = deleteMode === "never" || args.dryRun
+        ? { pruned: [], retained: [] }
+        : await pruneOrphans(client, applied, {
+            ...(stack !== undefined ? { stack } : {}),
+            signal,
+        });
+    return { fieldManager, applied, pruned, retained };
+}
+/** A 404 from the API server, matched by shape. */
+function isNotFound(err) {
+    const e = err;
+    return !!e && e.name === "K8sApiError" && e.statusCode === 404;
+}
+/** A 422 from the API server whose message says a field is immutable. Matched by shape, as {@link isChantSelfConflict} is. */
+function immutableRefusal(err) {
+    const e = err;
+    if (!e || e.name !== "K8sApiError" || e.statusCode !== 422)
+        return undefined;
+    const message = typeof e.apiMessage === "string" && e.apiMessage !== "" ? e.apiMessage : String(e.message ?? "");
+    return /immutable/i.test(message) ? message : undefined;
+}
+/**
+ * Say what {@link applyManifest} would do, without changing anything (#3998).
+ *
+ * Every document is stamped and dry-run applied exactly as the apply sends
+ * it: the same field manager, `force: false`, and the same retake of a
+ * conflict chant has only with itself. The live object is read first and
+ * compared with the dry-run result through `./apply-diff.ts`, so a field the
+ * server defaults counts as unchanged when the live object already has it.
+ *
+ * An object in a namespace an earlier document of the same plan creates
+ * cannot be dry-run (the server answers 404, as the namespace was never
+ * persisted), so it plans as a create of the document as sent.
+ *
+ * Deletes come from the apply's own prune scope (`findOrphans`): marker
+ * scoped, in the namespaces the apply set touches, generated-once Secrets
+ * and effect receipts kept. They are found only when `deleteMode` is not
+ * `never`, as the apply prunes only then.
+ */
+export async function planManifest(args, signal, connect = defaultK8sConnector) {
+    const documents = args.documents ?? readManifestDocuments(args.manifest);
+    const { fieldManager, stack } = await resolveApplyIdentity(args);
+    const { client } = await connect({
+        ...(args.environment !== undefined ? { environment: args.environment } : {}),
+        ...(args.context !== undefined ? { context: args.context } : {}),
+        ...(args.cwd !== undefined ? { cwd: args.cwd } : {}),
+    });
+    const objects = [];
+    /** Namespaces this plan creates. A dry run cannot place an object in one, since nothing persisted it. */
+    const creating = new Set();
+    for (const document of documents) {
+        const stamped = stampOwnership(document, stack);
+        const declaredRef = {
+            apiVersion: String(stamped.apiVersion ?? ""),
+            kind: String(stamped.kind ?? ""),
+            name: String(stamped.metadata?.name ?? ""),
+            ...(stamped.metadata?.namespace !== undefined ? { namespace: String(stamped.metadata.namespace) } : {}),
+        };
+        const live = await client.readIfPresent(declaredRef, signal ? { signal } : {});
+        let result;
+        try {
+            try {
+                result = await client.apply(stamped, { fieldManager, force: args.force ?? false, dryRun: true, signal });
+            }
+            catch (err) {
+                if (!isChantSelfConflict(err))
+                    throw err;
+                result = await client.apply(stamped, { fieldManager, force: true, dryRun: true, signal });
+            }
+        }
+        catch (err) {
+            if (!live && declaredRef.namespace !== undefined && creating.has(declaredRef.namespace) && isNotFound(err)) {
+                objects.push({ ref: declaredRef, action: "create", object: stamped, changes: [] });
+                continue;
+            }
+            const refused = live ? immutableRefusal(err) : undefined;
+            if (refused === undefined)
+                throw err;
+            objects.push({ ref: refOf(live, document), action: "update", changes: [], refused });
+            continue;
+        }
+        const ref = refOf(result, document);
+        if (!live) {
+            if (ref.kind === "Namespace" && ref.apiVersion === "v1")
+                creating.add(ref.name);
+            objects.push({ ref, action: "create", object: stamped, changes: [] });
+            continue;
+        }
+        const changes = diffFields(normalizeServerObject(live), normalizeServerObject(result));
+        objects.push({ ref, action: changes.length === 0 ? "no-op" : "update", changes });
+    }
+    const deleteMode = args.deleteMode ?? "never";
+    const { candidates, retained } = deleteMode === "never"
+        ? { candidates: [], retained: [] }
+        : await findOrphans(client, objects.map((o) => o.ref), { ...(stack !== undefined ? { stack } : {}), ...(signal ? { signal } : {}) });
+    return { fieldManager, ...(stack !== undefined ? { stack } : {}), objects, deletes: candidates, retained };
+}
+/**
+ * Read each of `refs` as the cluster holds it now, `undefined` for one that
+ * does not exist (#3999). `kubectl-apply` reads the fields its step names as
+ * outputs from these.
+ */
+export async function readLiveObjects(args, signal, connect = defaultK8sConnector) {
+    if (args.refs.length === 0)
+        return [];
+    const { client } = await connect({
+        ...(args.environment !== undefined ? { environment: args.environment } : {}),
+        ...(args.context !== undefined ? { context: args.context } : {}),
+        ...(args.cwd !== undefined ? { cwd: args.cwd } : {}),
+    });
+    const out = [];
+    for (const ref of args.refs)
+        out.push((await client.readIfPresent(ref, signal ? { signal } : {})));
+    return out;
+}
+/** The ref an applied or dry-run object answers with, as {@link applyManifest} records it. */
+function refOf(result, document) {
+    return {
+        apiVersion: String(result.apiVersion ?? document.apiVersion ?? ""),
+        kind: String(result.kind ?? document.kind ?? ""),
+        name: String(result.metadata?.name ?? ""),
+        ...(result.metadata?.namespace !== undefined ? { namespace: String(result.metadata.namespace) } : {}),
+    };
+}
+/**
+ * Apply every document in `args.manifest`.
+ * Uses the longInfra profile: 20m timeout, three attempts backing off from 30s.
+ */
+export async function kubectlApply(args, signal, connect = defaultK8sConnector) {
+    await applyManifest(args, signal, connect);
+}
+/**
+ * Delete chant-owned objects that the apply set no longer declares.
+ *
+ * This replaces `kubectl apply --prune --selector <marker>=chant`, and keeps
+ * its two safety properties exactly:
+ *
+ * - **Marker-scoped.** Only objects carrying chant's managed-by label are
+ *   candidates; the label selector is sent to the server, and the marker is
+ *   re-checked on every object before it is deleted. An unmarked resource is
+ *   never a candidate, so a hand-made object in the same namespace is safe.
+ * - **Namespace-scoped to the apply.** Namespaced kinds are swept only in the
+ *   namespaces the apply set touched (the context's default namespace when it
+ *   named none), which is what kubectl's prune does. A manifest that mentions
+ *   `prod` never reaches into `staging`. Whether a kind *is* namespaced comes
+ *   from the cluster's own discovery, never from whether a document happened
+ *   to name a namespace — guessing that wrong is the one way this could widen
+ *   into a cluster-wide sweep.
+ *
+ * Which *kinds* get swept is the union of the kinds the apply set contains and
+ * chant's default sweep set (`DEFAULT_IMPORT_TYPES` — the same list `chant
+ * import` uses when nothing narrows it). The union matters: a kind removed
+ * from source entirely appears nowhere in the apply set, and pruning only what
+ * is still declared would leave it behind forever. Per-namespace lists rather
+ * than one cluster-wide list per kind, so a namespace-scoped service account
+ * can still prune.
+ */
+async function pruneOrphans(client, applied, options) {
+    const { candidates, retained } = await findOrphans(client, applied, options);
+    for (const ref of retained) {
+        console.log(ref.kind === "Secret"
+            ? `${ref.apiVersion} ${ref.kind}/${ref.name} retained (generated-once — owned and no longer declared, ` +
+                `but never pruned; delete it explicitly if you mean to)`
+            : `${ref.apiVersion} ${ref.kind}/${ref.name} retained (effect receipt: owned and never declared ` +
+                `in an apply set, but never pruned; the effect() step is its sole writer)`);
+    }
+    const pruned = [];
+    for (const ref of candidates) {
+        await client.delete(ref, { ...(options.signal ? { signal: options.signal } : {}) });
+        pruned.push(ref);
+        console.log(`${ref.apiVersion} ${ref.kind}/${ref.name} pruned (chant-owned, no longer declared)`);
+    }
+    return { pruned, retained };
+}
+/**
+ * The objects {@link pruneOrphans} would delete (`candidates`) and the owned,
+ * undeclared ones it keeps (`retained`), found without deleting anything. A
+ * plan (#3998) asks this for its delete entries, so the plan and the apply
+ * share one prune scope.
+ */
+async function findOrphans(client, applied, options) {
+    const stack = options.stack;
+    const selector = [
+        `${LABEL_OWNERSHIP_KEYS.managedBy}=${OWNERSHIP_MANAGED_BY_VALUE}`,
+        ...(stack ? [`${LABEL_OWNERSHIP_KEYS.stack}=${stack}`] : []),
+    ].join(",");
+    const namespaces = [...new Set(applied.map((a) => a.namespace).filter((n) => !!n))];
+    if (namespaces.length === 0 && applied.length > 0)
+        namespaces.push(client.defaultNamespace);
+    const declared = new Set(applied.map(refKey));
+    // Every kind that could hold an orphan: the apply set's own, plus the
+    // default sweep set so a kind deleted from source entirely is still reached.
+    const sweeps = new Map();
+    for (const entityType of DEFAULT_IMPORT_TYPES) {
+        const operation = operationFor(entityType);
+        if (!operation)
+            continue;
+        sweeps.set(`${operation.apiVersion}/${operation.kind}`, {
+            apiVersion: operation.apiVersion,
+            kind: operation.kind,
+        });
+    }
+    for (const ref of applied) {
+        if (!ref.apiVersion || !ref.kind)
+            continue;
+        sweeps.set(`${ref.apiVersion}/${ref.kind}`, { apiVersion: ref.apiVersion, kind: ref.kind });
+    }
+    // (kind, namespace) pairs to list. Scope comes from the cluster's discovery,
+    // which is the only thing that knows it for the version this cluster serves;
+    // a kind discovery does not report is dropped rather than swept blindly.
+    const resolved = await client.concurrently([...sweeps.values()], async (sweep) => {
+        const info = await client
+            .resolve({ apiVersion: sweep.apiVersion, kind: sweep.kind }, options.signal)
+            .catch(() => undefined);
+        return info ? { ...sweep, namespaced: info.namespaced } : undefined;
+    });
+    const targets = [];
+    for (const sweep of resolved) {
+        if (!sweep)
+            continue;
+        if (!sweep.namespaced) {
+            targets.push({ apiVersion: sweep.apiVersion, kind: sweep.kind });
+            continue;
+        }
+        for (const namespace of namespaces) {
+            targets.push({ apiVersion: sweep.apiVersion, kind: sweep.kind, namespace });
+        }
+    }
+    const found = await client.concurrently(targets, async (target) => {
+        try {
+            const items = await client.list({ apiVersion: target.apiVersion, kind: target.kind }, {
+                labelSelector: selector,
+                ...(target.namespace !== undefined ? { namespace: target.namespace } : {}),
+                ...(options.signal ? { signal: options.signal } : {}),
+            });
+            return items.map((item) => ({ target, item }));
+        }
+        catch {
+            // Kind not served here, or the read was denied. Neither is evidence that
+            // something should be deleted, so the sweep skips it rather than failing
+            // the apply that already succeeded.
+            return [];
+        }
+    });
+    const candidates = [];
+    const retained = [];
+    const seen = new Set();
+    for (const { target, item } of found.flat()) {
+        const name = item.metadata?.name;
+        if (!name)
+            continue;
+        // The server filtered by label already; this re-check is the one that
+        // matters, because a delete is not undoable.
+        if (!hasOwnershipMarker(item.metadata?.labels, LABEL_OWNERSHIP_KEYS))
+            continue;
+        // Already terminating — deleting again is noise, not progress.
+        if (item.metadata?.deletionTimestamp !== undefined)
+            continue;
+        const ref = {
+            apiVersion: target.apiVersion,
+            kind: target.kind,
+            name,
+            ...(item.metadata?.namespace !== undefined ? { namespace: item.metadata.namespace } : {}),
+        };
+        const key = refKey(ref);
+        if (declared.has(key) || seen.has(key))
+            continue;
+        seen.add(key);
+        // A generated-once Secret never enters the prunable set (#1830, epic
+        // #1365 decision 5): its bytes are the only copy of material chant never
+        // held, so no sweep may destroy them. Kept, and said loudly — deletion is
+        // an explicit act (`kubectl delete`, or a future gated op).
+        if (target.kind === "Secret" && isGeneratedOnce(item.metadata?.labels)) {
+            retained.push(ref);
+            continue;
+        }
+        // An effect receipt never enters the prunable set either (#2074, epic
+        // #1703 decision 3). It is chant-owned and is never in ANY apply set,
+        // the `effect()` step being its sole writer, which is exactly the shape
+        // this sweep deletes. Pruning one would tell the next plan that an effect
+        // never ran and re-fire it, or worse, be re-stamped by nothing and leave
+        // the estate re-running a migration on every apply.
+        if (target.kind === "ConfigMap" && isEffectReceiptObject(item.metadata?.labels)) {
+            retained.push(ref);
+            continue;
+        }
+        candidates.push(ref);
+    }
+    return { candidates, retained };
+}
+function refKey(ref) {
+    return `${ref.apiVersion}/${ref.kind}/${ref.namespace ?? ""}/${ref.name}`;
+}