@intentius/chant-lexicon-k8s 0.124.30 → 0.124.32

package/dist/kube/source.js

@@ -0,0 +1,122 @@
+/**
+ * `chant kube source` (chant #1079) — resolve a live object back to the
+ * `.ts` file and composite that declared it, reusing the exact build
+ * provenance the gitlab/forgejo lexicons' own `:source` context tools already
+ * expose (`@intentius/chant/provenance`, stamped during discovery — chant
+ * #1064). That precedent is explicit that provenance here is **entity-level
+ * (file + composite), not a YAML-line source map** — chant does not carry
+ * one, for k8s or for anything else — so this verb reports the same two
+ * facts (never a fabricated line number) and says so plainly rather than
+ * silently coming up one field short of the issue's wording.
+ */
+import { formatUnobserved } from "@intentius/chant/observation";
+import { defaultK8sConnector } from "../api/connect.js";
+import { classifyApiFailure } from "../api/classify.js";
+import { kubeConnect } from "./connect.js";
+import { parseKubeFlags, connectOptionsFrom } from "./flags.js";
+import { loadKubeProjectContext, relativeProvenance } from "./project.js";
+import { resolveKubeTarget, matchLiveObject, isTargetError } from "./target.js";
+function targetLabel(target) {
+    return "apiVersion" in target.selector ? target.selector.kind : target.selector.resource;
+}
+export async function runSource(rawArgs, deps = {}) {
+    const connect = deps.connect ?? defaultK8sConnector;
+    const loadProject = deps.loadProject ?? loadKubeProjectContext;
+    let flags;
+    try {
+        flags = parseKubeFlags(rawArgs);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    const json = flags.values.output === "json";
+    const project = await loadProject();
+    if (!project) {
+        if (json)
+            console.log(JSON.stringify({ available: false, note: "not running inside a chant project (no chant.config.ts, or the project has build errors)" }));
+        else
+            console.log("chant source: unavailable — not running inside a chant project (no chant.config.ts, or the project has build errors)");
+        return 1;
+    }
+    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 source requires a single named resource, e.g. `chant kube source 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;
+    let obj;
+    try {
+        obj = await client.readIfPresent({ apiVersion: info.apiVersion, kind: info.kind, name: target.name, namespace });
+    }
+    catch (err) {
+        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;
+    }
+    if (!obj) {
+        console.error(`Error from server (NotFound): ${info.name} "${target.name}" not found`);
+        return 1;
+    }
+    const match = target.declaredMatch ??
+        matchLiveObject(project, {
+            apiVersion: obj.apiVersion ?? info.apiVersion,
+            kind: obj.kind ?? info.kind,
+            name: obj.metadata?.name ?? target.name,
+            namespace: obj.metadata?.namespace ?? namespace,
+        });
+    if (!match) {
+        const note = `no declared entity in this project names ${info.kind}/${target.name}`;
+        if (json)
+            console.log(JSON.stringify({ found: false, note }));
+        else
+            console.log(`${info.kind}/${target.name}: ${note}`);
+        return 0;
+    }
+    const prov = relativeProvenance(project, match.entity);
+    if (json) {
+        console.log(JSON.stringify({
+            found: true,
+            entity: match.entityName,
+            file: prov?.sourceFile ?? null,
+            composite: prov?.composite ?? null,
+            compositeInstance: prov?.compositeInstance ?? null,
+        }));
+    }
+    else {
+        console.log(`${info.kind}/${target.name} <- ${match.entityName}`);
+        console.log(`  file:      ${prov?.sourceFile ?? "(unknown)"}`);
+        console.log(`  composite: ${prov?.composite ?? "(none — declared directly)"}`);
+        console.log(`  line:      not tracked — chant's build provenance is entity-level (file + composite), not a source map`);
+    }
+    return 0;
+}

package/dist/kube/target.js

@@ -0,0 +1,63 @@
+/**
+ * Resolving `chant kube <verb> <target...>`'s positional arguments to an
+ * addressable resource (chant #1079).
+ *
+ * "Every verb resolves entity names through chant's own vocabulary where
+ * applicable ... while also accepting raw kind/name kubectl-style." Both
+ * forms share one positional shape, disambiguated by arity:
+ *
+ * - One token, and it names a declared entity in this project → chant's own
+ *   vocabulary: the entity's `metadata.name`(/`namespace`) is looked up in
+ *   its own source, not typed twice.
+ * - One or two tokens otherwise → kubectl's own shape, `<kind> [name]`; a
+ *   bare kind with no name is a list, matching `kubectl get <kind>`.
+ *
+ * `<kind>` is never parsed here beyond splitting the `.group` suffix — that
+ * job belongs to the typed client's own `resolve()` (kubectl's own
+ * plural/singular/kind/short-name precedence, `packages/k8s-client/src/client.ts`),
+ * so a raw kind string reaches the cluster exactly as `kubectl get raycluster.ray.io`
+ * would.
+ */
+import { findDeclaredMatch } from "./project.js";
+import { operationFor } from "../api/operation-surface.js";
+export function isTargetError(t) {
+    return "error" in t;
+}
+/**
+ * Resolve `positional` (whatever's left after flags) plus an explicit
+ * `-n/--namespace`, against `project`'s declared entities when available.
+ */
+export function resolveKubeTarget(positional, namespaceFlag, project) {
+    if (positional.length === 0) {
+        return { error: "a resource kind (and, usually, a name) is required — e.g. `chant kube get deployments` or `chant kube get deployment web`" };
+    }
+    const [first, second] = positional;
+    if (project && second === undefined) {
+        const entity = project.entities.get(first);
+        if (entity && entity.lexicon === "k8s") {
+            const operation = operationFor(entity.entityType);
+            const props = "props" in entity ? entity.props : undefined;
+            const metadata = props?.metadata;
+            if (operation && metadata?.name) {
+                return {
+                    selector: { apiVersion: operation.apiVersion, kind: operation.kind },
+                    name: metadata.name,
+                    namespace: namespaceFlag ?? metadata.namespace,
+                    declaredMatch: { entityName: first, entity, props },
+                };
+            }
+        }
+    }
+    return { selector: { resource: first }, name: second, namespace: namespaceFlag };
+}
+/**
+ * After a live read resolves an object's real `apiVersion`/`kind` (a kubectl
+ * kind string like `deploy` isn't one), reverse-map it against the project
+ * for the verdict column / `source` — reusing the exact match `resolveKubeTarget`
+ * would have made had the caller spelled out the entity name.
+ */
+export function matchLiveObject(project, ref) {
+    if (!project)
+        return undefined;
+    return findDeclaredMatch(project.entities, ref);
+}

package/dist/kube/testing.js

@@ -0,0 +1,28 @@
+/**
+ * Test doubles for `chant kube` (chant #1079).
+ *
+ * `./project.ts`'s real `loadKubeProjectContext` builds an actual project
+ * (`chant.config.ts` read, source discovered, serialized) — every verb takes
+ * it as an injectable dependency for exactly this reason: a unit test builds
+ * a `KubeProjectContext` by hand instead, the same way `../api/fake-cluster.ts`
+ * lets a test build a client without a socket.
+ */
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+import { setProvenance } from "@intentius/chant/provenance";
+/** A minimal `Declarable` carrying `props`, optionally stamped with build provenance. */
+export function fakeDeclarable(entityType, props, provenance) {
+    const entity = {
+        lexicon: "k8s",
+        entityType,
+        kind: "resource",
+        props,
+        [DECLARABLE_MARKER]: true,
+    };
+    if (provenance)
+        setProvenance(entity, provenance);
+    return entity;
+}
+/** A `KubeProjectContext` built from a plain name → entity map, no disk I/O. */
+export function fakeProjectContext(entities, config = {}, cwd = "/project") {
+    return { cwd, config, entities: new Map(Object.entries(entities)) };
+}

package/dist/kube/top.js

@@ -0,0 +1,99 @@
+/**
+ * `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 } from "../api/connect.js";
+import { classifyApiFailure } from "../api/classify.js";
+import { kubeConnect } from "./connect.js";
+import { parseKubeFlags, connectOptionsFrom } from "./flags.js";
+import { renderTable } from "./render.js";
+const RESOURCE_ALIASES = {
+    pod: "pods",
+    pods: "pods",
+    po: "pods",
+    node: "nodes",
+    nodes: "nodes",
+    no: "nodes",
+};
+export async function runTop(rawArgs, deps = {}) {
+    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?.cpu ?? "<unknown>"),
+            String(n.usage?.memory ?? "<unknown>"),
+        ]);
+        console.log(renderTable(["NAME", "CPU", "MEMORY"], rows));
+        return 0;
+    }
+    const rows = items.map((p) => {
+        const containers = p.containers ?? [];
+        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/dist/kube/verdict.js

@@ -0,0 +1,72 @@
+/**
+ * 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 { hasOwnershipMarker, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+function isPlainObject(v) {
+    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, live) {
+    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) {
+    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, match) {
+    if (match) {
+        return declaredSubsetMatches(declaredComparable(match.props), live) ? "declared" : "drifted";
+    }
+    return hasOwnershipMarker(live.metadata?.labels, LABEL_OWNERSHIP_KEYS) ? "owned" : "foreign-owned";
+}

package/dist/kube/wait.js

@@ -0,0 +1,129 @@
+/**
+ * `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 } from "../api/connect.js";
+import { classifyApiFailure } from "../api/classify.js";
+import { waitForReady, readinessFor, ReadinessFailedError, } from "../op/activities/wait-for-ready.js";
+import { kubeConnect } from "./connect.js";
+import { parseKubeFlags, connectOptionsFrom, parseDurationMs } from "./flags.js";
+import { loadKubeProjectContext } from "./project.js";
+import { resolveKubeTarget, isTargetError } from "./target.js";
+function parseFor(value) {
+    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) {
+    return "apiVersion" in target.selector ? target.selector.kind : target.selector.resource;
+}
+export async function runWait(rawArgs, deps = {}) {
+    const connect = deps.connect ?? defaultK8sConnector;
+    const loadProject = deps.loadProject ?? loadKubeProjectContext;
+    let flags;
+    let forSpec;
+    let timeoutMs;
+    try {
+        flags = parseKubeFlags(rawArgs, { value: { "--for": "for", "--timeout": "timeout" } });
+        forSpec = parseFor(flags.values.for);
+        timeoutMs = flags.values.timeout !== undefined ? parseDurationMs(flags.values.timeout) : 30000;
+    }
+    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 = async (args, signal) => (await client.read({ apiVersion: info.apiVersion, kind: info.kind, name: args.name, ...(args.namespace ? { namespace: args.namespace } : {}) }, { signal }));
+        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, ref, signal, intervalMs = 5000) {
+    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));
+    }
+}

package/dist/kustomize/render.js

@@ -0,0 +1,73 @@
+/**
+ * The kustomize renderer (#1548) — one implementation, two consumers.
+ *
+ * Piece 1 (`components/kustomize-apply.ts`) renders at DEPLOY time in front
+ * of the server-side applier; piece 3 (`./root.ts`) renders at BUILD time to
+ * give an overlay estate a declared side. Both run the same command with the
+ * same fallback through the same injectable runner, so a test asserts the
+ * exact invocation without either binary installed and the two paths cannot
+ * drift apart on how an overlay is rendered.
+ *
+ * Renderer resolution: `kustomize build`, falling back to `kubectl
+ * kustomize` (the same renderer vendored into kubectl) when the standalone
+ * binary is absent. When NEITHER binary exists the failure names both — a
+ * missing renderer is an environment problem the operator can fix in one
+ * install, and it must read as that, not as a stack trace. A render failure
+ * from an existing binary (a broken overlay, a missing base) propagates
+ * untouched: that error text is kustomize's own diagnosis and is strictly
+ * better than anything this module could wrap it in.
+ *
+ * The 64MiB maxBuffer mirrors helm-upgrade's — a big overlay renders
+ * megabytes.
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { loadAll } from "js-yaml";
+const execAsync = promisify(exec);
+export const defaultKustomizeRunner = (command) => execAsync(command, { maxBuffer: 64 * 1024 * 1024 });
+/** Single-quote shell escaping, as helm-upgrade quotes its argv. */
+function q(v) {
+    return `'${v.replace(/'/g, "'\\''")}'`;
+}
+/** The exact render command, standalone binary first. Pure; exported for tests. */
+export function renderCommand(dir, tool = "kustomize") {
+    return tool === "kustomize" ? `kustomize build ${q(dir)}` : `kubectl kustomize ${q(dir)}`;
+}
+/** Does this error mean "the binary is not installed" (vs "the render failed")? */
+function isMissingBinary(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return /ENOENT|not found|command not found|127/.test(message);
+}
+/**
+ * Render the kustomization at `dir` and parse the emitted YAML into document
+ * objects. Falls back to kubectl's vendored kustomize when the standalone
+ * binary is missing; when both binaries are missing, fails with a message
+ * naming them.
+ */
+export async function renderKustomizeDocuments(dir, run = defaultKustomizeRunner) {
+    let stdout;
+    try {
+        ({ stdout } = await run(renderCommand(dir, "kustomize")));
+    }
+    catch (err) {
+        if (!isMissingBinary(err))
+            throw err;
+        try {
+            ({ stdout } = await run(renderCommand(dir, "kubectl")));
+        }
+        catch (err2) {
+            if (isMissingBinary(err2)) {
+                throw new Error(`Cannot render kustomization "${dir}": neither the \`kustomize\` binary nor \`kubectl\` ` +
+                    `(whose vendored \`kubectl kustomize\` is the fallback) was found on PATH. ` +
+                    `Install kustomize or kubectl and retry.`);
+            }
+            throw err2;
+        }
+    }
+    const documents = [];
+    for (const doc of loadAll(stdout)) {
+        if (doc && typeof doc === "object" && !Array.isArray(doc))
+            documents.push(doc);
+    }
+    return documents;
+}

package/dist/kustomize/rendered-entity.js

@@ -0,0 +1,67 @@
+/**
+ * A rendered kustomize document as a chant entity (#1548 piece 3).
+ *
+ * A kustomize build root's output is a set of finished manifests, not typed
+ * chant source — the overlay already decided every field. The entity that
+ * carries one into the build is therefore the verbatim manifest entity
+ * (`../manifest-entity`), shared since #999 with `chant carve emit`'s adoption
+ * of a Terraform `kubernetes_manifest`: `props` IS the document, and the
+ * serializer emits it as-is.
+ *
+ * Provenance: every rendered document is stamped with an annotation naming
+ * the overlay dir it came from, so a consumer (behold#171's overlay boxes)
+ * can group by declared origin instead of guessing from paths — the one thing
+ * this adds over a plain manifest entity.
+ */
+import { manifestEntity, RENDERED_MANIFEST_MARKER, isRenderedManifestEntity } from "../manifest-entity.js";
+export { RENDERED_MANIFEST_MARKER, isRenderedManifestEntity };
+/** Annotation stamped on every rendered document, valued with the root dir. */
+export const KUSTOMIZE_ROOT_ANNOTATION = "chant.intentius.io/kustomize-root";
+/**
+ * Wrap one rendered document. Returns null when the document has no string
+ * `apiVersion`/`kind` — not a Kubernetes object, nothing to declare.
+ *
+ * `annotation` is the provenance key: the kustomize root annotation by
+ * default, `k8sInclude`'s source annotation for an included file (#3566).
+ */
+export function renderedManifestEntity(doc, root, annotation = KUSTOMIZE_ROOT_ANNOTATION) {
+    const metadata = { ...(doc.metadata ?? {}) };
+    metadata.annotations = {
+        ...(metadata.annotations ?? {}),
+        [annotation]: root,
+    };
+    return manifestEntity({ ...doc, metadata });
+}
+/** `Deployment` + `my-app` → `deploymentMyApp`, the import path's naming. */
+export function renderedLogicalId(kind, name) {
+    const prefix = kind.charAt(0).toLowerCase() + kind.slice(1);
+    if (!name)
+        return prefix;
+    const pascal = name
+        .split(/[^a-zA-Z0-9]+/)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join("");
+    return `${prefix}${pascal}`;
+}
+/**
+ * Add a rendered entity under a deterministic, human-readable key:
+ * `<prefix>/<kindName>`. Two documents can share kind+name (different
+ * namespaces, or different API groups with the same kind word), so a
+ * collision is qualified by namespace first, then numbered in document
+ * order. Returns the key used.
+ */
+export function addRenderedEntity(entities, prefix, entity) {
+    const metadata = entity.props.metadata;
+    const kind = entity.props.kind;
+    const name = typeof metadata.name === "string" ? metadata.name : undefined;
+    const namespace = typeof metadata.namespace === "string" ? metadata.namespace : undefined;
+    const base = `${prefix}/${renderedLogicalId(kind, name)}`;
+    let key = base;
+    if (entities.has(key) && namespace)
+        key = `${base}.${namespace}`;
+    for (let n = 2; entities.has(key); n++)
+        key = `${base}~${n}`;
+    entities.set(key, entity);
+    return key;
+}