@intentius/chant-lexicon-k8s 0.124.31 → 0.124.32

package/dist/op/activities/wait-for-ready.js

@@ -0,0 +1,229 @@
+import { sleep } from "@intentius/chant/op";
+import { defaultK8sConnector } from "../../api/connect.js";
+/**
+ * The generic default (kstatus-style): a `Ready` condition of `True` and
+ * `observedGeneration` caught up. Covers cert-manager, Gateway API, KubeRay,
+ * and the CockroachDB operator.
+ */
+export const DEFAULT_READINESS = {
+    ready: [{ conditionType: "Ready", status: "True" }],
+    observedGeneration: true,
+};
+/**
+ * Per-resource overrides keyed by `"<group>/<kind>"`. Argo's `Application`
+ * 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) => ({
+    ready: [{ conditionType: "Ready", status: "True" }],
+    terminal: [{ conditionType: "Ready", reasonOneOf: reasons }],
+    observedGeneration: true,
+});
+/**
+ * Config Connector (CNRM) wedge reasons (#1725): CNRM is kstatus-conformant —
+ * `Ready=True` + `observedGeneration` is the correct ready predicate, same as
+ * `DEFAULT_READINESS` — so, like `FLUX_TERMINAL`, the value added here is
+ * failing fast on a `Ready=False` reason that will not heal by waiting.
+ * `UpdateFailed` is CNRM giving up on a reconcile (bad spec, quota, API
+ * error); `ManagementConflict` is two controllers fighting over the same GCP
+ * resource. Neither resolves on its own.
+ *
+ * `DependencyNotReady` is deliberately excluded: it is the normal state while
+ * a resource waits on another one it depends on (e.g. a `ContainerCluster`
+ * waiting on its network) — exactly the "still being created" case this spec
+ * has to distinguish from a real wedge, not fold into it.
+ *
+ * One entry per kind, matching `FLUX_TERMINAL`'s convention, rather than a
+ * group-level key: CNRM's kinds don't share a single apiGroup (`ContainerCluster`
+ * and `ContainerNodePool` are `container.cnrm.cloud.google.com`; `SQLInstance`
+ * would be `sql.cnrm.cloud.google.com`, etc.), so a group-level key would need
+ * prefix matching against `*.cnrm.cloud.google.com` — a real change to
+ * `readinessFor`'s exact-match lookup for a handful of entries. Not worth it
+ * until more CNRM kinds actually need the override.
+ */
+const CNRM_TERMINAL = () => FLUX_TERMINAL(["UpdateFailed", "ManagementConflict"]);
+export const READINESS_OVERRIDES = {
+    "argoproj.io/Application": {
+        ready: [
+            { path: "status.health.status", equals: "Healthy" },
+            { path: "status.sync.status", equals: "Synced" },
+        ],
+        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",
+    ]),
+    "container.cnrm.cloud.google.com/ContainerCluster": CNRM_TERMINAL(),
+    "container.cnrm.cloud.google.com/ContainerNodePool": CNRM_TERMINAL(),
+};
+/** Resolve the readiness spec for a resource: registry override, else default. */
+export function readinessFor(group, kind) {
+    return READINESS_OVERRIDES[`${group ?? ""}/${kind}`] ?? DEFAULT_READINESS;
+}
+// ── Predicate evaluation ────────────────────────────────────────────
+function getPath(obj, path) {
+    return path.split(".").reduce((o, k) => (o != null && typeof o === "object" ? o[k] : undefined), obj);
+}
+function isConditionReason(m) {
+    return m.reasonOneOf !== undefined;
+}
+function isCondition(m) {
+    return m.conditionType !== undefined && !isConditionReason(m);
+}
+function findCondition(obj, conditionType) {
+    const conds = getPath(obj, "status.conditions");
+    if (!Array.isArray(conds))
+        return undefined;
+    return conds.find((x) => x && typeof x === "object" && x.type === conditionType);
+}
+function matchCondition(obj, m) {
+    const c = findCondition(obj, m.conditionType);
+    return !!c && String(c.status) === (m.status ?? "True");
+}
+function matchConditionReason(obj, m) {
+    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, m) {
+    const v = getPath(obj, m.path);
+    if (m.equals !== undefined)
+        return v === m.equals;
+    if (m.oneOf !== undefined)
+        return m.oneOf.includes(v);
+    return v !== undefined && v !== null;
+}
+function matches(obj, m) {
+    if (isConditionReason(m))
+        return matchConditionReason(obj, m);
+    return isCondition(m) ? matchCondition(obj, m) : matchPath(obj, m);
+}
+function observedGenerationReady(obj) {
+    const gen = getPath(obj, "metadata.generation");
+    const obs = getPath(obj, "status.observedGeneration");
+    if (typeof gen === "number" && typeof obs === "number")
+        return obs >= gen;
+    return true; // absent on either side → don't block
+}
+/** True when every `ready` predicate holds (and observedGeneration is caught up). */
+export function isReady(obj, spec) {
+    if (spec.observedGeneration !== false && !observedGenerationReady(obj))
+        return false;
+    return spec.ready.every((m) => matches(obj, m));
+}
+/** The first matching `terminal` predicate, if any — the resource is wedged. */
+export function firstTerminal(obj, spec) {
+    return spec.terminal?.find((m) => matches(obj, m));
+}
+// ── Activity ────────────────────────────────────────────────────────
+/** Thrown when the resource reaches a terminal state. Mark non-retryable. */
+export class ReadinessFailedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ReadinessFailedError";
+    }
+}
+/**
+ * Read the resource through the typed API client.
+ *
+ * A client is built once per `waitForReady` call and reused for every poll, so
+ * a 20-minute wait does not re-parse the kubeconfig or re-invoke an exec
+ * credential plugin on each iteration — and neither does it re-run discovery,
+ * which the client caches per API version.
+ */
+export function apiResourceFetcher(connect = defaultK8sConnector) {
+    let connection;
+    let resolved;
+    return async (args, signal) => {
+        connection ?? (connection = connect({
+            ...(args.environment !== undefined ? { environment: args.environment } : {}),
+            ...(args.context !== undefined ? { context: args.context } : {}),
+        }));
+        const { client } = await connection;
+        if (!resolved) {
+            const info = await client.resolve({ resource: args.kind, ...(args.group ? { group: args.group } : {}) }, signal);
+            if (!info) {
+                throw new Error(`waitForReady: the cluster's API discovery reports no resource matching "${args.kind}"` +
+                    `${args.group ? ` in group "${args.group}"` : ""} — nothing to wait for`);
+            }
+            resolved = { apiVersion: info.apiVersion, kind: info.kind };
+        }
+        return (await client.read({
+            apiVersion: resolved.apiVersion,
+            kind: resolved.kind,
+            name: args.name,
+            ...(args.namespace ? { namespace: args.namespace } : {}),
+        }, { signal }));
+    };
+}
+/**
+ * The production reader. Each call builds its own fetcher, so nothing is
+ * shared between two unrelated waits; a single `waitForReady` passes one
+ * fetcher through all of its polls, which is where the caching matters.
+ */
+export const defaultResourceFetcher = (args, signal) => apiResourceFetcher()(args, signal);
+/**
+ * Poll until the resource satisfies its readiness spec. Throws
+ * `ReadinessFailedError` on a terminal state, which the `k8sWait` profile lists
+ * as non-retryable, so a resource that will never become ready fails on the
+ * first attempt instead of burning the profile's 15m timeout three times.
+ *
+ * @param fetcher injectable reader (defaults to kubectl). Tests pass a fake to
+ *   drive not-ready → ready / terminal transitions.
+ */
+export async function waitForReady(args, signal, fetcher = apiResourceFetcher()) {
+    const spec = args.spec ?? readinessFor(args.group, args.kind);
+    const interval = args.intervalMs ?? 15000;
+    let attempt = 0;
+    while (true) {
+        if (signal?.aborted)
+            throw new Error("waitForReady aborted");
+        attempt++;
+        const obj = await fetcher(args, signal);
+        const term = firstTerminal(obj, spec);
+        if (term) {
+            throw new ReadinessFailedError(`${args.kind}/${args.name} reached a terminal state (${JSON.stringify(term)}) — it will not become ready without intervention.`);
+        }
+        if (isReady(obj, spec))
+            return obj;
+        await sleep(interval, signal);
+    }
+}

package/dist/op/builders.js

@@ -0,0 +1,68 @@
+/**
+ * Typed step-builder wrappers for this lexicon's activities (chant #1288
+ * Stage 2 — "regenerate the step builders as fully typed wrappers"). Core
+ * cannot import a lexicon's `*Args` types (lexicons depend on core, not the
+ * other way around — see `packages/core/src/op/activity-contract.ts`'s module
+ * doc for the same layering constraint on Stage 1's contracts), so a fully
+ * typed `kubectlApply`/`waitForReady`/`ensureSecret` has to live beside the
+ * `*Args` interface it derives from: here, next to `./activities/kubectl.ts`
+ * etc. `opts`'s type in each wrapper below IS the activity's own `*Args`
+ * interface (via `Omit`/`WithStepRefs`) — never a hand-restated mirror — so
+ * `kubectlApply`/`waitForReady`/`ensureSecret`'s full option surface (the
+ * dozen-plus cross-field options on `kubectlApply` that Stage 1's zod
+ * contracts deliberately skipped rather than duplicate) is authoring-time
+ * typed for free, and stays in sync with the implementation by construction.
+ *
+ * Every field also accepts a {@link StepOutputRef} in its place
+ * ({@link WithStepRefs}, chant #1950) — a later step's args can consume an
+ * earlier step's declared output.
+ *
+ * `core`'s own `kubectlApply`/`waitForReady`/`ensureSecret` (in
+ * `@intentius/chant/op`, the lexicon-agnostic single-import barrel) are
+ * UNCHANGED and produce byte-identical `ActivityStep` output for the same
+ * inputs — these are purely additive. Deliberately not swapped into core's
+ * barrel: that would make `@intentius/chant` depend on this package (and on
+ * helm, for `helmInstall`) at runtime, so a project that never touches
+ * Kubernetes would install both just to import anything from `op`. That is
+ * exactly the "core stays product-agnostic" property the
+ * `op/activities/index.ts` module docs across this repo call out on purpose
+ * (activities live in per-product lexicons for this reason; the step-builder
+ * layer shouldn't reintroduce the coupling from the other direction). An
+ * author who wants the typed surface imports it from here —
+ * `@intentius/chant-lexicon-k8s` — which a project using `kubectlApply`
+ * already depends on; existing `@intentius/chant/op` imports keep working
+ * exactly as before, opting in only if the import is changed.
+ */
+import { activity, takeProfileAndId, } from "@intentius/chant/op";
+/**
+ * Run `kubectl apply -f <manifest>` — the fully typed twin of core's
+ * `kubectlApply` step-builder shortcut (chant #1288 Stage 2). `opts` is
+ * {@link KubectlApplyArgs} itself (minus the positional `manifest`) — every
+ * field `applyManifest` accepts, including `deleteMode`, `force`,
+ * `fieldManager`, `documents`, is authoring-time typed here, not just the
+ * subset a hand-written zod mirror would bother restating. Defaults to the
+ * `longInfra` profile (override via `opts.profile`).
+ */
+export const kubectlApply = (manifest, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("kubectlApply", { manifest, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+/**
+ * Poll a Kubernetes resource until it reports ready, driven by a data-only
+ * readiness spec (CRD-aware; #365) — the fully typed twin of core's
+ * `waitForReady`. `opts` is {@link WaitForReadyArgs} itself, minus the
+ * positional `kind`/`name`. Defaults to the `k8sWait` profile.
+ */
+export const waitForReady = (kind, name, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("waitForReady", { kind, name, ...args }, { profile: profile ?? "k8sWait", ...(id ? { id } : {}) });
+};
+/**
+ * Ensure a `generated-once` secret exists in the target store (#1829) — the
+ * fully typed twin of core's `ensureSecret`. `opts` is
+ * {@link EnsureSecretActivityArgs} itself, minus the positional `name`/`keys`.
+ */
+export const ensureSecret = (name, keys, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("ensureSecret", { name, keys, ...args }, { profile, ...(id ? { id } : {}) });
+};

package/dist/package-cli.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for Kubernetes lexicon packaging.
+ */
+import { packageLexicon } from "./codegen/package.js";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+const pkgDir = dirname(fileURLToPath(import.meta.url));
+async function main() {
+    const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+    const force = process.argv.includes("--force") || process.argv.includes("-f");
+    const { spec, stats } = await packageLexicon({ verbose, force });
+    const distDir = join(pkgDir, "..", "dist");
+    writeBundleSpec(spec, distDir);
+    console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+}
+main().catch((err) => {
+    console.error("Packaging failed:", err);
+    process.exit(1);
+});

package/dist/patch/json-patch.js

@@ -0,0 +1,187 @@
+/**
+ * RFC 6902 JSON Patch and RFC 7386 JSON Merge Patch, for rendered documents.
+ *
+ * Core carries an RFC 6902 applier for cfn-lint codegen
+ * (`packages/core/src/codegen/json-patch.ts`), but it skips `test`, `move`
+ * and `copy`, and it works on JSON strings. A patch on a rendered manifest
+ * needs `test` most of all: it is how an author pins the value a chart
+ * upgrade might change underneath them. So this module is a small, complete
+ * applier over plain objects, with no imports, usable from the build path and
+ * from the helm lexicon's `HelmRender`.
+ *
+ * Both appliers return a new document and never mutate their input.
+ */
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function clone(value) {
+    return value === undefined ? value : JSON.parse(JSON.stringify(value));
+}
+/** "" -> [], "/a/b~1c" -> ["a", "b/c"]. */
+function parsePointer(pointer) {
+    if (pointer === "")
+        return [];
+    if (!pointer.startsWith("/"))
+        throw new Error(`"${pointer}" is not a JSON Pointer (it must start with "/")`);
+    return pointer
+        .slice(1)
+        .split("/")
+        .map((t) => t.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+function arrayIndex(arr, token, pointer, allowEnd) {
+    if (!/^(0|[1-9][0-9]*)$/.test(token))
+        throw new Error(`"${token}" in ${pointer} is not an array index`);
+    const idx = Number(token);
+    const max = allowEnd ? arr.length : arr.length - 1;
+    if (idx > max)
+        throw new Error(`index ${idx} in ${pointer} is out of bounds (array length ${arr.length})`);
+    return idx;
+}
+function get(root, pointer) {
+    let current = root;
+    for (const token of parsePointer(pointer)) {
+        if (Array.isArray(current)) {
+            current = current[arrayIndex(current, token, pointer, false)];
+        }
+        else if (isObject(current) && Object.prototype.hasOwnProperty.call(current, token)) {
+            current = current[token];
+        }
+        else {
+            throw new Error(`path ${pointer} does not exist`);
+        }
+    }
+    return current;
+}
+/** The container a pointer's last token addresses, and that token. */
+function parentOf(root, pointer) {
+    const tokens = parsePointer(pointer);
+    if (tokens.length === 0)
+        throw new Error("the root cannot be addressed as a member");
+    const token = tokens.pop();
+    const parentPointer = tokens.length === 0 ? "" : "/" + tokens.map((t) => t.replace(/~/g, "~0").replace(/\//g, "~1")).join("/");
+    const parent = get(root, parentPointer);
+    if (!Array.isArray(parent) && !isObject(parent)) {
+        throw new Error(`path ${pointer} does not exist (its parent is not an object or array)`);
+    }
+    return { parent, token };
+}
+function add(root, pointer, value) {
+    if (pointer === "")
+        return value;
+    const { parent, token } = parentOf(root, pointer);
+    if (Array.isArray(parent)) {
+        if (token === "-")
+            parent.push(value);
+        else
+            parent.splice(arrayIndex(parent, token, pointer, true), 0, value);
+    }
+    else {
+        parent[token] = value;
+    }
+    return root;
+}
+function remove(root, pointer) {
+    if (pointer === "")
+        throw new Error("the document root cannot be removed");
+    const { parent, token } = parentOf(root, pointer);
+    if (Array.isArray(parent)) {
+        parent.splice(arrayIndex(parent, token, pointer, false), 1);
+    }
+    else {
+        if (!Object.prototype.hasOwnProperty.call(parent, token))
+            throw new Error(`path ${pointer} does not exist`);
+        delete parent[token];
+    }
+    return root;
+}
+function replace(root, pointer, value) {
+    if (pointer === "")
+        return value;
+    get(root, pointer); // must exist
+    const { parent, token } = parentOf(root, pointer);
+    if (Array.isArray(parent))
+        parent[arrayIndex(parent, token, pointer, false)] = value;
+    else
+        parent[token] = value;
+    return root;
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (isObject(a) && isObject(b)) {
+        const ka = Object.keys(a);
+        const kb = Object.keys(b);
+        return ka.length === kb.length && ka.every((k) => Object.prototype.hasOwnProperty.call(b, k) && deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+/**
+ * Apply an RFC 6902 patch. Operations apply in order; the first one that
+ * fails (a missing path, a failed `test`) throws with its index, and the
+ * input is left untouched.
+ */
+export function applyJsonPatch(doc, operations) {
+    let root = clone(doc);
+    operations.forEach((operation, i) => {
+        try {
+            switch (operation.op) {
+                case "add":
+                    root = add(root, operation.path, clone(operation.value));
+                    break;
+                case "remove":
+                    root = remove(root, operation.path);
+                    break;
+                case "replace":
+                    root = replace(root, operation.path, clone(operation.value));
+                    break;
+                case "move": {
+                    if (operation.path.startsWith(operation.from + "/")) {
+                        throw new Error(`cannot move ${operation.from} into its own child ${operation.path}`);
+                    }
+                    const value = get(root, operation.from);
+                    root = remove(root, operation.from);
+                    root = add(root, operation.path, value);
+                    break;
+                }
+                case "copy":
+                    root = add(root, operation.path, clone(get(root, operation.from)));
+                    break;
+                case "test": {
+                    const actual = get(root, operation.path);
+                    if (!deepEqual(actual, operation.value)) {
+                        throw new Error(`test failed at ${operation.path}: expected ${JSON.stringify(operation.value)}, found ${JSON.stringify(actual)}`);
+                    }
+                    break;
+                }
+                default:
+                    throw new Error(`unknown op "${operation.op}"`);
+            }
+        }
+        catch (err) {
+            throw new Error(`operation ${i} (${operation.op}): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    return root;
+}
+/**
+ * Apply an RFC 7386 merge patch: objects merge key by key, a `null` value
+ * deletes the key, and anything else (arrays included) replaces the target
+ * whole.
+ */
+export function applyMergePatch(doc, patch) {
+    if (!isObject(patch))
+        return clone(patch);
+    const target = isObject(doc) ? clone(doc) : {};
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined)
+            continue;
+        if (value === null)
+            delete target[key];
+        else
+            target[key] = applyMergePatch(target[key], value);
+    }
+    return target;
+}

package/dist/patch/rendered-patch.js

@@ -0,0 +1,94 @@
+import { applyJsonPatch, applyMergePatch } from "./json-patch.js";
+export { applyJsonPatch, applyMergePatch } from "./json-patch.js";
+/**
+ * Identity helper that infers `kind`, so a `merge` body is checked against
+ * that kind's props:
+ *
+ * ```ts
+ * renderedPatch({ kind: "Deployment", name: "web", merge: { spec: { replicas: 3 } } })
+ * ```
+ *
+ * A plain object literal works anywhere a `RenderedPatch` is taken; it just
+ * types `merge` as an open record.
+ */
+export function renderedPatch(patch) {
+    return patch;
+}
+function describeSelector(sel) {
+    const parts = [`kind ${sel.kind}`, `name ${sel.name}`];
+    if (sel.namespace !== undefined)
+        parts.push(`namespace ${sel.namespace}`);
+    if (sel.apiVersion !== undefined)
+        parts.push(`apiVersion ${sel.apiVersion}`);
+    return parts.join(", ");
+}
+function metadataOf(doc) {
+    const m = doc.metadata;
+    return typeof m === "object" && m !== null && !Array.isArray(m) ? m : {};
+}
+function matches(doc, sel) {
+    if (doc.kind !== sel.kind)
+        return false;
+    if (sel.apiVersion !== undefined && doc.apiVersion !== sel.apiVersion)
+        return false;
+    const metadata = metadataOf(doc);
+    if (metadata.name !== sel.name)
+        return false;
+    if (sel.namespace !== undefined && metadata.namespace !== sel.namespace)
+        return false;
+    return true;
+}
+/**
+ * Apply `patches` in order to `docs` and return the patched documents, in
+ * the same order. `source` names where the documents came from (a chart, a
+ * file, a URL, an overlay dir) and leads every error message.
+ *
+ * Each patch applies to every document its selector matches at that point,
+ * so a later patch sees an earlier one's changes. Throws when a selector
+ * matches nothing, when an operation fails (a `test` included), when a patch
+ * carries both or neither of `jsonPatch` and `merge`, and when a patched
+ * document no longer has a string `apiVersion` and `kind`.
+ */
+export function applyRenderedPatches(docs, patches, source) {
+    const out = [...docs];
+    if (!patches || patches.length === 0)
+        return out;
+    patches.forEach((patch, p) => {
+        const where = `${source}: patch ${p} (${describeSelector(patch)})`;
+        const hasJson = patch.jsonPatch !== undefined;
+        const hasMerge = patch.merge !== undefined;
+        if (hasJson === hasMerge) {
+            throw new Error(`${where} must set exactly one of jsonPatch and merge`);
+        }
+        let matched = 0;
+        for (let i = 0; i < out.length; i++) {
+            if (!matches(out[i], patch))
+                continue;
+            matched++;
+            let next;
+            try {
+                next = hasJson ? applyJsonPatch(out[i], patch.jsonPatch) : applyMergePatch(out[i], patch.merge);
+            }
+            catch (err) {
+                throw new Error(`${where}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (typeof next !== "object" || next === null || typeof next.apiVersion !== "string" || typeof next.kind !== "string") {
+                throw new Error(`${where} left a document without a string apiVersion and kind`);
+            }
+            out[i] = next;
+        }
+        if (matched === 0) {
+            const sameKind = out
+                .filter((d) => d.kind === patch.kind)
+                .map((d) => {
+                const m = metadataOf(d);
+                return typeof m.namespace === "string" ? `${m.namespace}/${String(m.name)}` : String(m.name);
+            });
+            throw new Error(`${where} matched no document. ` +
+                (sameKind.length > 0
+                    ? `${patch.kind} documents present: ${sameKind.join(", ")}.`
+                    : `There are no ${patch.kind} documents.`));
+        }
+    });
+    return out;
+}