@intentius/chant-lexicon-k8s 0.124.31 → 0.124.33

package/dist/crd/loader.js

@@ -0,0 +1,181 @@
+/**
+ * CRD loader — loads Custom Resource Definitions from various sources.
+ *
+ * Supports loading from local files, remote URLs, and (placeholder)
+ * live cluster introspection via kubectl.
+ */
+import { existsSync, readFileSync } from "fs";
+import { fetchWithRetry } from "@intentius/chant/codegen/fetch";
+import { parseCRD } from "./parser.js";
+import { chartYamlFiles, pullOciChart, readTarGz } from "./oci-chart.js";
+/**
+ * Load CRDs from a source and return parsed K8sParseResult entries.
+ */
+export async function loadCRDs(source) {
+    const content = await fetchCRDContent(source);
+    const parsed = parseCRD(content);
+    if (source.kinds && source.kinds.length > 0) {
+        const allow = new Set(source.kinds);
+        return parsed.filter((r) => allow.has(r.gvk.kind));
+    }
+    return parsed;
+}
+/**
+ * Load CRDs from multiple sources and merge results.
+ */
+export async function loadMultipleCRDs(sources) {
+    const results = [];
+    for (const source of sources) {
+        const parsed = await loadCRDs(source);
+        results.push(...parsed);
+    }
+    return results;
+}
+/**
+ * Fetch raw CRD YAML content from a source.
+ */
+export async function fetchCRDContent(source) {
+    switch (source.type) {
+        case "file":
+            return loadFromFile(source);
+        case "url":
+            return loadFromURL(source);
+        case "cluster":
+            return loadFromCluster(source);
+        case "helm":
+            return loadFromHelmChart(source);
+        default:
+            throw new Error(`Unsupported CRD source type: ${source.type}`);
+    }
+}
+/**
+ * Load CRD YAML from a local file.
+ */
+async function loadFromFile(source) {
+    if (!source.path) {
+        throw new Error("CRD source type 'file' requires a 'path' property");
+    }
+    if (!existsSync(source.path)) {
+        throw new Error(`CRD file not found: ${source.path}`);
+    }
+    return readFileSync(source.path, "utf8");
+}
+/**
+ * Load CRD YAML from a remote URL.
+ */
+async function loadFromURL(source) {
+    if (!source.url) {
+        throw new Error("CRD source type 'url' requires a 'url' property");
+    }
+    // fetchWithRetry retries transient failures and throws on a permanent
+    // status (or after exhausting retries); the returned response is `ok`.
+    const response = await fetchWithRetry(source.url);
+    return response.text();
+}
+/**
+ * Load CRDs out of a Helm chart, by pulling and unpacking it.
+ *
+ * Helm's own convention is that CRDs live in a chart's `crds/` directory and
+ * are applied before templates, so that is the default place to look. Every
+ * YAML document found there is concatenated into one multi-doc string, which
+ * the parser already handles, and the existing `kinds` allowlist then applies
+ * unchanged — a chart carrying more CRDs than a consumer wants is the same
+ * situation as Flux's install bundle.
+ *
+ * An `oci://` chart is pulled over the registry's HTTP API and unpacked in
+ * process, so generation does not depend on `helm` being on PATH. Before,
+ * a host without helm dropped the chart's kinds with only a warning and the
+ * generated surface changed with the machine. Only a classic `https://` chart
+ * repository still shells out to `helm pull`.
+ */
+async function loadFromHelmChart(source) {
+    if (!source.chart) {
+        throw new Error("CRD source type 'helm' requires a 'chart' property");
+    }
+    if (!source.version) {
+        throw new Error(`CRD source type 'helm' requires a 'version' property (chart: ${source.chart}). ` +
+            "An unpinned chart makes generated output depend on when it was generated.");
+    }
+    const subdir = source.chartSubdir ?? "crds";
+    if (source.chart.startsWith("oci://")) {
+        let tgz;
+        try {
+            tgz = await pullOciChart(source.chart, source.version, source.digest);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`could not pull chart ${source.chart} ${source.version}: ${msg}`);
+        }
+        const files = chartYamlFiles(readTarGz(tgz), subdir);
+        if (files.length === 0) {
+            throw new Error(`chart ${source.chart} ${source.version} has no CRD YAML in '${subdir}'. ` +
+                "Charts that template their CRDs instead of shipping them in crds/ need 'chartSubdir'.");
+        }
+        return files.map(([, text]) => text).join("\n---\n");
+    }
+    const { execFile } = await import("child_process");
+    const { promisify } = await import("util");
+    const { mkdtempSync, rmSync, readdirSync, readFileSync: read } = await import("fs");
+    const { join } = await import("path");
+    const { tmpdir } = await import("os");
+    const execFileAsync = promisify(execFile);
+    const workdir = mkdtempSync(join(tmpdir(), "chant-crd-helm-"));
+    try {
+        await execFileAsync("helm", [
+            "pull", source.chart,
+            "--version", source.version,
+            "--untar",
+            "--untardir", workdir,
+        ]).catch((err) => {
+            if (err.code === "ENOENT") {
+                throw new Error(`helm not found on PATH, needed to read CRDs from ${source.chart}. ` +
+                    "Install helm, or vendor the CRDs and use a 'file' source.");
+            }
+            throw new Error(`helm pull failed for ${source.chart} ${source.version}: ${err.stderr?.trim() || err.message}`);
+        });
+        // --untar writes a single directory named after the chart, which need not
+        // match the last segment of the reference, so read it rather than guess.
+        const unpacked = readdirSync(workdir, { withFileTypes: true }).filter((e) => e.isDirectory());
+        if (unpacked.length !== 1) {
+            throw new Error(`expected one unpacked chart directory in ${workdir}, found ${unpacked.length}`);
+        }
+        const crdDir = join(workdir, unpacked[0].name, subdir);
+        let entries;
+        try {
+            entries = readdirSync(crdDir).filter((f) => f.endsWith(".yaml") || f.endsWith(".yml")).sort();
+        }
+        catch {
+            throw new Error(`chart ${source.chart} ${source.version} has no '${subdir}' directory. ` +
+                "Charts that template their CRDs instead of shipping them in crds/ need 'chartSubdir'.");
+        }
+        if (entries.length === 0) {
+            throw new Error(`chart ${source.chart} ${source.version} has no CRD YAML in '${subdir}'`);
+        }
+        return entries.map((f) => read(join(crdDir, f), "utf8")).join("\n---\n");
+    }
+    finally {
+        rmSync(workdir, { recursive: true, force: true });
+    }
+}
+/**
+ * Load CRDs from a live Kubernetes cluster via kubectl.
+ *
+ * This is a placeholder implementation. Full cluster introspection
+ * requires kubectl access and proper authentication.
+ */
+async function loadFromCluster(source) {
+    const { execFile } = await import("child_process");
+    const { promisify } = await import("util");
+    const execFileAsync = promisify(execFile);
+    const args = ["get", "crds", "-o", "yaml"];
+    if (source.context)
+        args.push(`--context=${source.context}`);
+    if (source.namespace)
+        args.push(`--namespace=${source.namespace}`);
+    const { stdout, stderr } = await execFileAsync("kubectl", args).catch((err) => {
+        throw new Error(`kubectl failed: ${err.stderr?.trim() || err.message}. ` +
+            "Ensure kubectl is installed and configured with access to the target cluster.");
+    });
+    void stderr;
+    return stdout;
+}

package/dist/crd/oci-chart.js

@@ -0,0 +1,144 @@
+/**
+ * Pull a Helm chart out of an OCI registry over plain HTTP, and read its files.
+ *
+ * Generation used to shell out to `helm pull` for these. A machine without
+ * helm on PATH (a fresh CI runner, a container) then dropped the chart's kinds
+ * with only a warning, and the generated surface depended on which tools the
+ * host happened to have. The registry API is three requests, and a chart is a
+ * small gzipped tarball, so neither needs the binary.
+ */
+import { createHash } from "crypto";
+import { gunzipSync } from "zlib";
+import { fetchWithRetry } from "@intentius/chant/codegen/fetch";
+/** The layer media type Helm pushes a chart's content under. */
+export const HELM_CHART_LAYER = "application/vnd.cncf.helm.chart.content.v1.tar+gzip";
+const MANIFEST_ACCEPT = [
+    "application/vnd.oci.image.manifest.v1+json",
+    "application/vnd.docker.distribution.manifest.v2+json",
+].join(", ");
+const defaultHttp = {
+    probe: (url, init) => fetch(url, init),
+    get: (url, init) => fetchWithRetry(url, undefined, undefined, init),
+};
+/** Split an `oci://host/repo/path` chart reference. */
+export function parseOciRef(chart) {
+    const m = /^oci:\/\/([^/]+)\/(.+)$/.exec(chart);
+    if (!m)
+        throw new Error(`not an oci:// chart reference: ${chart}`);
+    return { host: m[1], repository: m[2].replace(/\/+$/, "") };
+}
+/**
+ * Get an anonymous pull token, following the registry's own challenge
+ * (`WWW-Authenticate: Bearer realm=...,service=...`). Returns undefined when
+ * the registry does not ask for one.
+ */
+async function anonymousToken(ref, http) {
+    const probe = await http.probe(`https://${ref.host}/v2/`);
+    if (probe.status !== 401)
+        return undefined;
+    const challenge = probe.headers.get("www-authenticate") ?? "";
+    const params = Object.fromEntries([...challenge.matchAll(/(\w+)="([^"]*)"/g)].map((m) => [m[1], m[2]]));
+    if (!/^bearer/i.test(challenge) || !params.realm) {
+        throw new Error(`registry ${ref.host} asks for auth this loader does not speak: ${challenge || "(no challenge)"}`);
+    }
+    const url = new URL(params.realm);
+    if (params.service)
+        url.searchParams.set("service", params.service);
+    url.searchParams.set("scope", `repository:${ref.repository}:pull`);
+    const res = await http.get(url.toString());
+    const body = (await res.json());
+    const token = body.token ?? body.access_token;
+    if (!token)
+        throw new Error(`registry ${ref.host} returned no token for ${ref.repository}`);
+    return token;
+}
+/**
+ * Download a chart's content layer (the .tgz `helm pull` would fetch).
+ *
+ * @param digest  When given ("sha256:..."), the layer must have this digest.
+ *                Pinning it makes the source content-addressed: a re-pushed
+ *                tag fails loudly instead of changing generated output.
+ */
+export async function pullOciChart(chart, version, digest, http = defaultHttp) {
+    const ref = parseOciRef(chart);
+    const token = await anonymousToken(ref, http);
+    const auth = token ? { Authorization: `Bearer ${token}` } : {};
+    const base = `https://${ref.host}/v2/${ref.repository}`;
+    const manifestRes = await http.get(`${base}/manifests/${version}`, {
+        headers: { ...auth, Accept: MANIFEST_ACCEPT },
+    });
+    const manifest = (await manifestRes.json());
+    const layer = manifest.layers?.find((l) => l.mediaType === HELM_CHART_LAYER);
+    if (!layer) {
+        throw new Error(`${chart}:${version} has no layer of type ${HELM_CHART_LAYER}; is it a Helm chart?`);
+    }
+    if (digest && layer.digest !== digest) {
+        throw new Error(`${chart}:${version} chart layer is ${layer.digest}, but the source pins ${digest}. ` +
+            "The tag was re-pushed; review the new chart and update the pin.");
+    }
+    const blobRes = await http.get(`${base}/blobs/${layer.digest}`, { headers: auth });
+    const blob = Buffer.from(await blobRes.arrayBuffer());
+    const actual = `sha256:${createHash("sha256").update(blob).digest("hex")}`;
+    if (actual !== layer.digest) {
+        throw new Error(`${chart}:${version} chart layer downloaded as ${actual}, expected ${layer.digest}`);
+    }
+    return blob;
+}
+/**
+ * Read the regular files out of a gzipped tarball, as path to content.
+ * Handles ustar, plus the pax (`x`) and GNU (`L`) long-name records Helm's
+ * Go archiver may write.
+ */
+export function readTarGz(tgz) {
+    const tar = gunzipSync(tgz);
+    const files = new Map();
+    let offset = 0;
+    let longName;
+    const field = (start, len) => {
+        const raw = tar.subarray(offset + start, offset + start + len);
+        const nul = raw.indexOf(0);
+        return raw.subarray(0, nul === -1 ? raw.length : nul).toString("utf8");
+    };
+    while (offset + 512 <= tar.length) {
+        // Two zero blocks end the archive; one is enough to stop reading.
+        if (tar.subarray(offset, offset + 512).every((b) => b === 0))
+            break;
+        const size = parseInt(field(124, 12).trim() || "0", 8);
+        const type = field(156, 1) || "0";
+        const prefix = field(345, 155);
+        const name = longName ?? (prefix ? `${prefix}/${field(0, 100)}` : field(0, 100));
+        const data = tar.subarray(offset + 512, offset + 512 + size);
+        longName = undefined;
+        if (type === "x") {
+            const path = /(?:^|\n)\d+ path=([^\n]*)\n/.exec(data.toString("utf8"));
+            if (path)
+                longName = path[1];
+        }
+        else if (type === "L") {
+            longName = data.toString("utf8").replace(/\0+$/, "");
+        }
+        else if (type === "0" || type === "\0") {
+            files.set(name, Buffer.from(data));
+        }
+        offset += 512 + Math.ceil(size / 512) * 512;
+    }
+    return files;
+}
+/**
+ * The YAML files directly inside `<chart dir>/<subdir>/`, sorted by path so
+ * the concatenation does not depend on archive order.
+ */
+export function chartYamlFiles(files, subdir) {
+    const dir = subdir.replace(/^\/+|\/+$/g, "");
+    return [...files.entries()]
+        .filter(([path]) => {
+        // Strip the single top-level chart directory, whatever it is named.
+        const rest = path.split("/").slice(1).join("/");
+        if (!rest.startsWith(`${dir}/`))
+            return false;
+        const leaf = rest.slice(dir.length + 1);
+        return !leaf.includes("/") && (leaf.endsWith(".yaml") || leaf.endsWith(".yml"));
+    })
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([path, buf]) => [path, buf.toString("utf8")]);
+}