@intentius/chant-lexicon-helm 0.124.31 → 0.124.33

package/dist/render.js

@@ -0,0 +1,394 @@
+/**
+ * HelmRender — render an upstream Helm chart at chant build time.
+ *
+ * Most chant projects that want to install third-party operators (ESO,
+ * cert-manager, ingress-nginx, etc.) ran `helm template` or `helm install`
+ * as a separate deploy phase. That meant the chant build output was
+ * incomplete — `kubectl apply -f dist/...yaml` didn't carry those operators.
+ *
+ * `HelmRender({ repo, chart, version, values })` resolves at synth time:
+ *   1. Shells out to `helm template` (requires the `helm` binary in PATH).
+ *   2. Parses the resulting multi-document YAML.
+ *   3. Emits each rendered K8s manifest as a Declarable in the build output.
+ *   4. Caches the rendered output under `~/.chant/helm-renders/<hash>/`
+ *      keyed by (repo, chart, version, values) so subsequent builds skip
+ *      network access.
+ *
+ * The lexicon must include both `helm` and `k8s` (since rendered manifests
+ * are k8s resources).
+ *
+ * @example
+ * import { HelmRender } from "@intentius/chant-lexicon-helm";
+ *
+ * export const eso = HelmRender({
+ *   name: "external-secrets",
+ *   repo: "https://charts.external-secrets.io",
+ *   chart: "external-secrets",
+ *   version: "0.10.4",
+ *   namespace: "external-secrets",
+ *   createNamespace: true,
+ *   values: { installCRDs: true },
+ * });
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Composite } from "@intentius/chant";
+// Use the k8s lexicon's Deployment as a generic Declarable wrapper for
+// arbitrary K8s manifests. The k8s serializer reads props.apiVersion and
+// props.kind verbatim when set, so the actual class doesn't matter.
+import { Deployment } from "@intentius/chant-lexicon-k8s/generated/index";
+import { applyRenderedPatches } from "@intentius/chant-lexicon-k8s/patch/rendered-patch";
+import yaml from "js-yaml";
+import { resolveCapabilityProfile } from "./config.js";
+import { helmContentDigest, helmInputDigest } from "./render-digest.js";
+import { findRenderByCacheKey, loadRenderContent, persistHelmRender, renderCacheKey, renderStoreRoot, } from "./render-store.js";
+import { probeCoalescedValues } from "./values-probe.js";
+import { recordHelmRender } from "./render-records.js";
+// The invocation-record ledger lives in ./render-records.ts — a module with
+// no runtime imports — so WHM503 (edge-imported via the post-synth barrel)
+// can read it without pulling this module's heavy static graph. Re-exported
+// here to keep the lexicon's public surface unchanged.
+export { getHelmRenderRecords, clearHelmRenderRecords } from "./render-records.js";
+/**
+ * Root of the legacy unpinned cache — the same directory (and the same
+ * `CHANT_HELM_RENDER_ROOT` override) as the content-addressed render store
+ * (#2035). Before this the unprofiled path hardcoded `~/.chant/helm-renders`
+ * and honoured no environment variable, so a hermetic or air-gapped build
+ * had no way to hand it a pre-rendered chart short of pre-warming `$HOME`.
+ * A function, not a module-level constant, so the override is read when a
+ * render happens rather than when this module loaded.
+ */
+function cacheRoot() {
+    return renderStoreRoot();
+}
+/**
+ * Legacy cache key — truncated, unprefixed, input-derived. Since #1238 this
+ * keys only *unpinned* renders (and names the values tempfile): pinned
+ * renders live in the content-addressed store (./render-store.ts) under
+ * their full `sha256:` contentDigest, with the inputs index providing cache
+ * hits. Existing truncated-hash entries stay where they are — a new root,
+ * not a migration.
+ */
+function cacheKey(props, profile) {
+    const stable = JSON.stringify({
+        repo: props.repo,
+        chart: props.chart,
+        version: props.version,
+        namespace: props.namespace ?? null,
+        values: props.values ?? null,
+        // Only present for pinned renders (which no longer read this cache but
+        // still name their values tempfile with this key). A pinned render must
+        // never reuse an unpinned render's bytes (or another profile's) — the
+        // profile is a real render input (#1235).
+        ...(profile
+            ? {
+                capabilityProfile: {
+                    name: profile.name,
+                    kubeVersion: profile.kubeVersion,
+                    apiVersions: profile.apiVersions ?? [],
+                },
+            }
+            : {}),
+    });
+    return createHash("sha256").update(stable).digest("hex").slice(0, 16);
+}
+/**
+ * Version of the local helm binary, for the persisted `RenderManifest`.
+ * Load-bearing there — the defaulted kube version is a property of the
+ * binary, so this field explains a digest mismatch between machines. Never
+ * fails a build: `"unknown"` when helm cannot answer.
+ */
+function helmBinaryVersion() {
+    try {
+        const out = execFileSync("helm", ["version", "--template", "{{.Version}}"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return out.trim().split("\n")[0] || "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function renderViaHelm(props, profile) {
+    // Write values overrides to a tempfile if any.
+    let valuesArgs = [];
+    if (props.values && Object.keys(props.values).length > 0) {
+        const valuesPath = join(tmpdir(), `chant-helm-values-${cacheKey(props, profile)}.yaml`);
+        writeFileSync(valuesPath, yaml.dump(props.values));
+        valuesArgs = ["--values", valuesPath];
+    }
+    // When `repo` is set, helm fetches the chart by name+version from the repo.
+    // When `repo` is absent, treat `chart` as a local path.
+    const fetchArgs = [];
+    if (props.repo) {
+        fetchArgs.push("--repo", props.repo);
+        if (props.version)
+            fetchArgs.push("--version", props.version);
+    }
+    // When --repo is set, isolate helm's repository config + cache to a
+    // chant-private directory. Without this, helm tries to refresh ALL of the
+    // user's existing repo indexes (eks, jetstack, etc.) and fails with
+    // "no cached repo found" if any one has gone stale — even though we
+    // only care about the single repo the consumer asked for.
+    const isolationArgs = props.repo
+        ? [
+            "--repository-config",
+            "/dev/null",
+            "--repository-cache",
+            join(cacheRoot(), "_helm-repo-cache"),
+        ]
+        : [];
+    const args = [
+        "template",
+        props.name,
+        props.chart,
+        // Without this, `helm template` silently drops manifests shipped in the
+        // chart's (or a subchart's) crds/ directory.
+        "--include-crds",
+        // Pin .Capabilities to the declared cluster profile. Without these, the
+        // kube version defaults to one baked into the helm binary and APIVersions
+        // is empty — both silently, both making the rendered bytes a function of
+        // the local toolchain (#1235).
+        ...(profile
+            ? [
+                "--kube-version",
+                profile.kubeVersion,
+                ...(profile.apiVersions ?? []).flatMap((v) => ["--api-versions", v]),
+            ]
+            : []),
+        ...fetchArgs,
+        ...isolationArgs,
+        ...(props.namespace ? ["--namespace", props.namespace] : []),
+        ...valuesArgs,
+    ];
+    try {
+        const out = execFileSync("helm", args, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        return out;
+    }
+    catch (err) {
+        const stderr = err && typeof err === "object" && "stderr" in err
+            ? String(err.stderr)
+            : String(err);
+        throw new Error(`HelmRender failed for ${props.repo}/${props.chart}@${props.version}:\n${stderr}\n` +
+            `Hint: ensure the 'helm' CLI is on PATH (helm version) and the chart is reachable.`);
+    }
+}
+function loadOrRender(props, profile) {
+    if (props.noCache) {
+        return renderViaHelm(props, profile);
+    }
+    const cacheDir = join(cacheRoot(), cacheKey(props, profile));
+    const cachePath = join(cacheDir, "manifests.yaml");
+    if (existsSync(cachePath)) {
+        return readFileSync(cachePath, "utf8");
+    }
+    const out = renderViaHelm(props, profile);
+    try {
+        mkdirSync(cacheDir, { recursive: true });
+        writeFileSync(cachePath, out);
+    }
+    catch {
+        // Cache write failure is non-fatal — the render is still in memory.
+    }
+    return out;
+}
+/**
+ * Best-effort coalesced-values probe (#1251) for a `HelmRender` invocation.
+ *
+ * The probe (`./values-probe.ts`) needs the chart source on disk — the same
+ * requirement the pinnability classifier (#1234) has — so it only runs for
+ * a local chart (`props.repo` unset, `props.chart` a directory with a
+ * `Chart.yaml`). A repo-fetched chart's source is never kept on disk here,
+ * so it gets no probe, the same v1 gate `render.ts`'s digest recording
+ * already documents.
+ *
+ * Never fatal: a probe failure (a chart the probe's template injection
+ * can't render, `helm` briefly unavailable, ...) must not break the actual
+ * render it is only observing. `undefined` means "no probe result" — never
+ * fabricated, and WHM504 simply has nothing to report for this render.
+ */
+function runValuesProbeBestEffort(props) {
+    if (props.repo)
+        return undefined;
+    if (!existsSync(join(props.chart, "Chart.yaml")))
+        return undefined;
+    try {
+        return probeCoalescedValues({
+            chartDir: props.chart,
+            name: props.name,
+            releaseName: props.name,
+            namespace: props.namespace,
+            supplied: props.values && Object.keys(props.values).length > 0
+                ? [{ origin: "supplied file", values: props.values }]
+                : [],
+        });
+    }
+    catch {
+        // Non-fatal — see the docstring above. The main render already ran (or
+        // is about to) via its own `helm template` invocation; this extra,
+        // probe-only render observing the same chart is never load-bearing.
+        return undefined;
+    }
+}
+/**
+ * The pinned render path (#1238): the content-addressed store is both the
+ * cache and the durable record.
+ *
+ * Read: unless `noCache` (or `persist: false`) is set, the full-inputs
+ * cache key resolves through the store's inputs index to canonical bytes a
+ * previous identical render stored — semantically identical to helm's
+ * output (canonicalization only normalizes render noise) and byte-stable
+ * under re-canonicalization, so digests recompute identically.
+ *
+ * Write: a fresh render persists { canonical bytes, RenderManifest } unless
+ * the caller opted out — the manifest is written alongside every pinned
+ * render by default. `persist: true` with `noCache` still persists (a
+ * forced-fresh render is still a durable artifact); a persist failure on
+ * the default path is non-fatal like a legacy cache-write failure, but an
+ * explicit `persist: true` surfaces it.
+ */
+function loadOrRenderPinned(props, profile, valuesProbe) {
+    const chartRef = props.repo ? `${props.repo}/${props.chart}` : props.chart;
+    const storeRead = !props.noCache && props.persist !== false;
+    const storeWrite = props.persist === true || (!props.noCache && props.persist !== false);
+    const key = renderCacheKey({
+        chart: chartRef,
+        chartVersion: props.version,
+        releaseName: props.name,
+        namespace: props.namespace,
+        values: props.values,
+        capabilityProfile: profile,
+    });
+    if (storeRead) {
+        const hit = findRenderByCacheKey(key);
+        if (hit) {
+            const content = loadRenderContent(hit.contentDigest);
+            if (content !== undefined)
+                return content;
+            // Index points at pruned/corrupt content — fall through and re-render.
+        }
+    }
+    const out = renderViaHelm(props, profile);
+    if (storeWrite) {
+        try {
+            persistHelmRender({
+                rendered: out,
+                releaseName: props.name,
+                chart: props.chart,
+                repo: props.repo || undefined,
+                chartVersion: props.version,
+                namespace: props.namespace,
+                values: props.values,
+                capabilityProfile: profile,
+                helmVersion: helmBinaryVersion(),
+                sourceRef: props.sourceRef,
+                coalescedValuesDigest: valuesProbe?.digest,
+                valueSources: valuesProbe?.valueSources,
+            });
+        }
+        catch (err) {
+            if (props.persist === true)
+                throw err;
+            // Default-on persistence degrades like a legacy cache-write failure:
+            // the render is still in memory and the build goes on.
+        }
+    }
+    return out;
+}
+function parseMultiDoc(text) {
+    const docs = yaml.loadAll(text);
+    return docs
+        .filter((d) => d !== null && typeof d === "object")
+        .filter((d) => d.kind && d.apiVersion);
+}
+/**
+ * Sanitize an arbitrary string into a valid TS/JS identifier suffix.
+ * Used to derive Composite Members keys from manifest kind+name pairs.
+ */
+function safeKey(input) {
+    return input.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+export const HelmRender = Composite((props) => {
+    // Resolve first: a named profile the config does not declare must fail the
+    // build here, before any helm invocation could silently render against the
+    // binary's default capabilities.
+    const profile = props.capabilityProfile !== undefined ? resolveCapabilityProfile(props.capabilityProfile) : undefined;
+    if (!profile && props.persist === true) {
+        throw new Error(`HelmRender "${props.name}": persist requires a pinned render, and this one is unpinned ` +
+            `(no capabilityProfile declared). An unpinned render's bytes are a function of the local ` +
+            `helm binary's defaulted capabilities, so they have no stable content identity to store ` +
+            `under. Declare capabilityProfile to pin the render (#1235), or drop persist.`);
+    }
+    // Build-time coalesced-values probe (#1251/#1252). Runs (best-effort) for
+    // a pinned render of a local chart — the same gate the digests below use,
+    // since the probe needs the chart source on disk and only a pinned render
+    // has a RenderManifest to carry its digest. `probeCoalescedValues` records
+    // itself into the WHM504 surface (`getValuesProbeRecords`) as part of
+    // running — no separate `recordValuesProbe` call needed here, and any
+    // dead assignment it found is worth reporting whether or not this render
+    // ultimately persists.
+    const valuesProbe = profile ? runValuesProbeBestEffort(props) : undefined;
+    const yamlText = profile ? loadOrRenderPinned(props, profile, valuesProbe) : loadOrRender(props, undefined);
+    const docs = applyRenderedPatches(parseMultiDoc(yamlText), props.patches, `HelmRender "${props.name}" (${props.chart}${props.version ? `@${props.version}` : ""})`);
+    // Digests are recorded only for pinned renders (#1237). Profile presence
+    // is the v1 gate: the classifier (#1234) needs the chart source on disk,
+    // which a repo-fetched render does not keep, so the gate here is the
+    // declared-inputs property, not a template analysis. An unpinned render's
+    // digest would be a function of the local helm binary — meaningless as an
+    // identity — so unpinned renders record neither digest.
+    const digests = profile
+        ? {
+            inputDigest: helmInputDigest({
+                // Same chart-reference convention helmInstall digests: a local
+                // path stays itself; a repo-fetched chart is `<repo-url>/<chart>`.
+                chart: props.repo ? `${props.repo}/${props.chart}` : props.chart,
+                chartVersion: props.version,
+                values: props.values ?? {},
+                capabilityProfile: {
+                    kubeVersion: profile.kubeVersion,
+                    apiVersions: profile.apiVersions,
+                },
+            }),
+            contentDigest: helmContentDigest(yamlText),
+            ...(valuesProbe ? { coalescedValuesDigest: valuesProbe.digest } : {}),
+        }
+        : {};
+    recordHelmRender({
+        name: props.name,
+        chart: props.chart,
+        version: props.version,
+        capabilityProfile: profile,
+        ...digests,
+    });
+    const out = {};
+    if (props.createNamespace && props.namespace) {
+        out["__namespace"] = new Deployment({
+            apiVersion: "v1",
+            kind: "Namespace",
+            metadata: { name: props.namespace },
+        });
+    }
+    const usedKeys = new Set();
+    for (let i = 0; i < docs.length; i++) {
+        const doc = docs[i];
+        const kind = doc.kind ?? "Unknown";
+        const name = doc.metadata?.name ?? `doc${i}`;
+        let key = safeKey(`${kind}_${name}`);
+        // Disambiguate on collision (e.g. same kind+name across docs).
+        let collisionN = 2;
+        while (usedKeys.has(key)) {
+            key = `${safeKey(`${kind}_${name}`)}_${collisionN++}`;
+        }
+        usedKeys.add(key);
+        out[key] = new Deployment(doc);
+    }
+    return out;
+}, "HelmRender");

package/dist/resources.js

@@ -0,0 +1,109 @@
+/**
+ * Helm-specific resource and property types.
+ *
+ * Created via createResource/createProperty from @intentius/chant/runtime.
+ * These are static types (no upstream schema to fetch).
+ */
+import { createResource, createProperty } from "@intentius/chant/runtime";
+const LEXICON = "helm";
+// ── Resources ─────────────────────────────────────────────
+/**
+ * Helm::Chart — Chart.yaml metadata.
+ *
+ * Defines the chart's identity: apiVersion, name, version, appVersion,
+ * description, type (application|library), keywords, maintainers, dependencies.
+ */
+export const Chart = createResource("Helm::Chart", LEXICON, {});
+/**
+ * Helm::Values — Typed values definition.
+ *
+ * The props passed to the constructor become the default values emitted
+ * in values.yaml. The serializer also generates values.schema.json from
+ * the value types.
+ */
+export const Values = createResource("Helm::Values", LEXICON, {});
+/**
+ * Helm::Test — Helm test pod.
+ *
+ * Annotated with `helm.sh/hook: test` in the serialized output.
+ * Props should contain a K8s Pod spec.
+ */
+export const HelmTest = createResource("Helm::Test", LEXICON, {});
+/**
+ * Helm::Notes — NOTES.txt template content.
+ *
+ * The `content` prop is emitted as templates/NOTES.txt.
+ */
+export const HelmNotes = createResource("Helm::Notes", LEXICON, {});
+// ── Property types ────────────────────────────────────────
+/**
+ * Helm::Hook — Lifecycle hook annotation.
+ *
+ * Wraps a K8s resource with helm.sh/hook annotations.
+ * Props: { hook: string, weight?: number, deletePolicy?: string, resource: Declarable }
+ */
+export const HelmHook = createProperty("Helm::Hook", LEXICON);
+/**
+ * Helm::Dependency — Chart dependency entry.
+ *
+ * Props: { name, version, repository, condition?, tags?, enabled?, importValues?, alias? }
+ */
+export const HelmDependency = createProperty("Helm::Dependency", LEXICON);
+/**
+ * Helm::Maintainer — Chart maintainer entry.
+ *
+ * Props: { name, email?, url? }
+ */
+export const HelmMaintainer = createProperty("Helm::Maintainer", LEXICON);
+/**
+ * Helm::ValuesOverride — Generate a named YAML override file.
+ *
+ * Emits a standalone YAML file inside the chart directory, intended to be
+ * passed as `helm upgrade -f chart-dir/values-base.yaml`. Use this for
+ * static configuration shared across all deployments (disabled bundled
+ * services, shared secret references, etc.).
+ *
+ * Props: { filename: string, values: Record<string, unknown> }
+ *
+ * ```ts
+ * new ValuesOverride({
+ *   filename: "values-base",
+ *   values: { postgresql: { install: false }, redis: { install: false } },
+ * })
+ * // → generates chart-dir/values-base.yaml
+ * ```
+ */
+export const ValuesOverride = createResource("Helm::ValuesOverride", LEXICON, {});
+// ── CRD ──────────────────────────────────────────────────
+/**
+ * Helm::CRD — Custom Resource Definition placed in the crds/ directory.
+ *
+ * Props: { content: string, filename?: string }
+ */
+export const HelmCRD = createResource("Helm::CRD", LEXICON, {});
+// ── K8s resource types used by composites ────────────────
+// These are thin wrappers so composite members are Declarable.
+const K8S = "k8s";
+export const Deployment = createResource("K8s::Apps::Deployment", K8S, {});
+export const StatefulSet = createResource("K8s::Apps::StatefulSet", K8S, {});
+export const DaemonSet = createResource("K8s::Apps::DaemonSet", K8S, {});
+export const Service = createResource("K8s::Core::Service", K8S, {});
+export const ServiceAccount = createResource("K8s::Core::ServiceAccount", K8S, {});
+export const ConfigMap = createResource("K8s::Core::ConfigMap", K8S, {});
+export const Namespace = createResource("K8s::Core::Namespace", K8S, {});
+export const Job = createResource("K8s::Batch::Job", K8S, {});
+export const CronJob = createResource("K8s::Batch::CronJob", K8S, {});
+export const Ingress = createResource("K8s::Networking::Ingress", K8S, {});
+export const NetworkPolicy = createResource("K8s::Networking::NetworkPolicy", K8S, {});
+export const HPA = createResource("K8s::Autoscaling::HorizontalPodAutoscaler", K8S, {});
+export const PDB = createResource("K8s::Policy::PodDisruptionBudget", K8S, {});
+export const ResourceQuota = createResource("K8s::Core::ResourceQuota", K8S, {});
+export const LimitRange = createResource("K8s::Core::LimitRange", K8S, {});
+export const ClusterRole = createResource("K8s::Rbac::ClusterRole", K8S, {});
+export const ClusterRoleBinding = createResource("K8s::Rbac::ClusterRoleBinding", K8S, {});
+export const Role = createResource("K8s::Rbac::Role", K8S, {});
+export const RoleBinding = createResource("K8s::Rbac::RoleBinding", K8S, {});
+export const ExternalSecret = createResource("K8s::ExternalSecrets::ExternalSecret", K8S, {});
+export const ServiceMonitor = createResource("K8s::Monitoring::ServiceMonitor", K8S, {});
+export const PrometheusRule = createResource("K8s::Monitoring::PrometheusRule", K8S, {});
+export const Certificate = createResource("K8s::CertManager::Certificate", K8S, {});