@intentius/chant-lexicon-helm 0.124.31 → 0.124.32

package/dist/list-artifacts.js

@@ -0,0 +1,134 @@
+/**
+ * Live introspection of Helm releases via `helm list -A -o json`.
+ *
+ * The Helm lexicon's chant entities describe chart-authoring primitives
+ * (Chart.yaml, templates/, values.yaml). The runtime concept — a Helm
+ * release installed in a kubeconfig context — is created by `helm install`
+ * outside chant's entity model. This implementation reports those releases
+ * as artifacts so `state diff --live` / `WatchOp` can detect manual
+ * installs/upgrades/rollbacks that slip past CI.
+ *
+ * Helm-not-installed (binary missing) → returns `{}` cleanly so other
+ * lexicons' snapshots aren't blocked.
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { loadChantConfigUpward } from "@intentius/chant/config";
+import { resolveClusterTarget } from "@intentius/chant/kubectl-context";
+import { readReleaseLedger, latestPerComponent } from "@intentius/chant/lifecycle/release-ledger";
+const execAsync = promisify(exec);
+/**
+ * The render identity a chant deploy recorded for a release (#2031). `helm
+ * list` cannot know which bytes a release was installed from — but the
+ * release ledger already records it on deploy (#1243): the input digest for
+ * an unpinned deploy, contentDigest + inputDigest for a pinned one. This
+ * reads that record back, so an observed release joins `helm renders` /
+ * `helm diff` by digest instead of by chart-name prefix matching.
+ *
+ * The join key is the ledger record's `component`, which the helm deploy
+ * activity defaults to the release name (`args.component ?? args.name`,
+ * ./op/activities/helm.ts). Deliberately best-effort and honest about
+ * absence:
+ *
+ *  - a release deployed outside chant has no record, and reports nothing;
+ *  - a ledger that cannot be read (no repo, no lifecycle branch) joins
+ *    nothing rather than failing the snapshot;
+ *  - two observed releases sharing one name (different namespaces) are
+ *    ambiguous — the record does not carry a namespace — so neither joins;
+ *  - a record whose `component` was overridden away from the release name
+ *    does not join (the honest miss, same as today).
+ */
+function renderIdentityOf(record) {
+    if (!record)
+        return {};
+    if (record.inputDigest) {
+        // Pinned deploy (#1242): `digest` is the render's contentDigest, the
+        // input identity rides alongside.
+        return { inputDigest: record.inputDigest, contentDigest: record.digest };
+    }
+    // Unpinned deploy: the record is keyed by the input digest itself
+    // (`ReleaseRecord.inputDigest` is "absent when digest is already input-side").
+    return { inputDigest: record.digest };
+}
+function pruneUndefined(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+export async function listArtifacts(options) {
+    const result = {};
+    // The same cluster binding every other helm read resolves (chant#1488 —
+    // `k8s.profiles.<env>.context`, shared with the k8s lexicon). Listing on
+    // the AMBIENT context read whichever cluster the operator's shell last
+    // pointed at: verified live on kubemicrovm-ops, whose releases came back
+    // `{}` because the shell's current-context was an unrelated EKS cluster.
+    // Unresolvable → ambient, which is chant's own fallback when no profile is
+    // declared.
+    let context;
+    try {
+        const { config } = await loadChantConfigUpward(process.cwd());
+        context = (await resolveClusterTarget(config, options.environment, "helm")).context;
+    }
+    catch {
+        context = undefined;
+    }
+    let stdout;
+    try {
+        ({ stdout } = await execAsync(`helm list -A -o json${context ? ` --kube-context '${context.replace(/'/g, "'\\''")}'` : ""}`));
+    }
+    catch {
+        // Binary not installed, no kubeconfig, or some other error — return
+        // empty rather than blocking the whole snapshot.
+        return result;
+    }
+    let entries;
+    try {
+        entries = JSON.parse(stdout);
+    }
+    catch {
+        return result;
+    }
+    // The environment's latest release record per component (#2031) — the
+    // deploy-side identity read back. Best-effort: an unreadable ledger joins
+    // nothing rather than blocking the snapshot.
+    let recorded = new Map();
+    try {
+        const { records } = await readReleaseLedger(options.environment);
+        recorded = latestPerComponent(records);
+    }
+    catch {
+        recorded = new Map();
+    }
+    // A name observed in several namespaces is ambiguous against a record that
+    // carries no namespace — neither joins.
+    const nameCounts = new Map();
+    for (const entry of entries) {
+        if (entry.name)
+            nameCounts.set(entry.name, (nameCounts.get(entry.name) ?? 0) + 1);
+    }
+    for (const entry of entries) {
+        if (!entry.name || !entry.namespace)
+            continue;
+        const key = `release/${entry.namespace}/${entry.name}`;
+        const record = nameCounts.get(entry.name) === 1 ? recorded.get(entry.name) : undefined;
+        const { inputDigest, contentDigest } = renderIdentityOf(record);
+        result[key] = {
+            type: "Helm::Release",
+            physicalId: `${entry.namespace}/${entry.name}`,
+            status: entry.status ?? "unknown",
+            lastUpdated: entry.updated,
+            attributes: pruneUndefined({
+                chart: entry.chart,
+                revision: entry.revision,
+                appVersion: entry.app_version,
+                namespace: entry.namespace,
+                inputDigest,
+                contentDigest,
+            }),
+        };
+    }
+    return result;
+}

package/dist/lsp/completions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"completions.d.ts","sourceRoot":"","sources":["../../src/lsp/completions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAapF;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,iBAAiB,GAAG,cAAc,EAAE,CAExE"}
+{"version":3,"file":"completions.d.ts","sourceRoot":"","sources":["../../src/lsp/completions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAapF;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,iBAAiB,GAAG,cAAc,EAAE,CAExE"}

package/dist/lsp/completions.js

@@ -0,0 +1,18 @@
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+import { LexiconIndex, lexiconCompletions } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(moduleSourceUrl(import.meta.url));
+let cachedIndex = null;
+function getIndex() {
+    if (cachedIndex)
+        return cachedIndex;
+    const data = require("../generated/lexicon-helm.json");
+    cachedIndex = new LexiconIndex(data);
+    return cachedIndex;
+}
+/**
+ * Provide Helm resource completions based on context.
+ */
+export function helmCompletions(ctx) {
+    return lexiconCompletions(ctx, getIndex(), "Helm chart resource");
+}

package/dist/lsp/hover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hover.d.ts","sourceRoot":"","sources":["../../src/lsp/hover.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAa1E;;GAEG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAElE"}
+{"version":3,"file":"hover.d.ts","sourceRoot":"","sources":["../../src/lsp/hover.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAa1E;;GAEG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAElE"}

package/dist/lsp/hover.js

@@ -0,0 +1,40 @@
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+import { LexiconIndex, lexiconHover } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(moduleSourceUrl(import.meta.url));
+let cachedIndex = null;
+function getIndex() {
+    if (cachedIndex)
+        return cachedIndex;
+    const data = require("../generated/lexicon-helm.json");
+    cachedIndex = new LexiconIndex(data);
+    return cachedIndex;
+}
+/**
+ * Provide hover information for Helm resource types.
+ */
+export function helmHover(ctx) {
+    return lexiconHover(ctx, getIndex(), resourceHover);
+}
+function resourceHover(className, entry) {
+    const lines = [];
+    lines.push(`**${className}**`);
+    lines.push("");
+    lines.push(`Helm type: \`${entry.resourceType}\``);
+    if (entry.kind === "resource") {
+        lines.push("");
+        lines.push("*Resource — serialized as a top-level Helm chart artifact*");
+    }
+    else {
+        lines.push("");
+        lines.push("*Property — used as a nested value in Helm resources*");
+    }
+    if (entry.attrs && Object.keys(entry.attrs).length > 0) {
+        lines.push("");
+        lines.push("**Attributes:**");
+        for (const [key, value] of Object.entries(entry.attrs)) {
+            lines.push(`- \`${key}\` \u2192 \`${value}\``);
+        }
+    }
+    return { contents: lines.join("\n") };
+}

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "helm",
-  "version": "0.124.31",
+  "version": "0.124.32",
   "chantVersion": ">=0.1.0",
   "namespace": "Helm",
   "intrinsics": [

package/dist/op/activities/cluster-probe.js

@@ -0,0 +1,116 @@
+/**
+ * Live-cluster capability probe for the deploy-time profile assertion
+ * (#1244, epic #1228 phase 4).
+ *
+ * A render pinned for one capability profile and deployed to a cluster with
+ * another is silently skewed: the bytes were computed against a declared
+ * `kubeVersion` and `apiVersions` set, and nothing at deploy time checked
+ * the target actually matches. This module reads the target cluster's real
+ * capabilities — `kubectl version -o json` for the server version,
+ * `kubectl api-versions` for the served API set — through the same
+ * exec-and-ambient-kubeconfig convention `helmInstall` already uses for the
+ * helm binary, and names every divergence from a declared profile.
+ *
+ * The comparison tolerance is deliberate: kubeVersion matches on
+ * major.minor. A profile declaring `1.33.6` matches a live `v1.33.4+k3s1` —
+ * the capability surface helm renders against (`.Capabilities.KubeVersion`)
+ * is a major.minor fact, and patch skew within a minor changes no API
+ * surface a chart can probe. Declared apiVersions are exact-match: each one
+ * the profile names must be served by the cluster.
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+/**
+ * Thrown when the cluster's capabilities cannot be read at all — kubectl
+ * missing, cluster unreachable, or unparseable output. A deploy that
+ * declared a profile cannot verify its guarantee through this error, so the
+ * caller must refuse to proceed rather than deploy blind.
+ */
+export class ClusterProbeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ClusterProbeError";
+    }
+}
+/** `major.minor` from a declared or live version string (`1.33`, `1.33.6`, `v1.33.6+k3s1`). Undefined when the string has no parseable major.minor. */
+export function majorMinorOf(version) {
+    const match = /^v?(\d+)\.(\d+)/.exec(version.trim());
+    return match ? `${match[1]}.${match[2]}` : undefined;
+}
+function parseServerVersion(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new ClusterProbeError(`kubectl version -o json produced unparseable output: ${raw.slice(0, 200)}`);
+    }
+    const server = parsed.serverVersion;
+    if (!server) {
+        throw new ClusterProbeError("kubectl version -o json reported no serverVersion — the cluster did not answer");
+    }
+    const gitVersion = typeof server.gitVersion === "string" ? server.gitVersion : "";
+    // major/minor are the authoritative fields; minor can carry a vendor
+    // suffix (GKE reports "33+"), so digits are extracted rather than trusted.
+    const major = typeof server.major === "string" ? /\d+/.exec(server.major)?.[0] : undefined;
+    const minor = typeof server.minor === "string" ? /\d+/.exec(server.minor)?.[0] : undefined;
+    const majorMinor = major && minor ? `${major}.${minor}` : gitVersion ? majorMinorOf(gitVersion) : undefined;
+    if (!majorMinor) {
+        throw new ClusterProbeError(`kubectl version -o json reported no usable server version (gitVersion: ${gitVersion || "<absent>"})`);
+    }
+    return { kubeVersion: gitVersion || majorMinor, majorMinor };
+}
+/**
+ * Read the target cluster's capabilities. Uses whatever kubeconfig/context
+ * the process environment provides — the same ambient target `helm upgrade`
+ * itself will act on, so the probe and the deploy see one cluster.
+ */
+export async function probeClusterCapabilities(signal) {
+    let versionRaw;
+    let apiVersionsRaw;
+    try {
+        const [versionResult, apiResult] = await Promise.all([
+            execAsync("kubectl version -o json", { signal }),
+            execAsync("kubectl api-versions", { signal }),
+        ]);
+        versionRaw = versionResult.stdout;
+        apiVersionsRaw = apiResult.stdout;
+    }
+    catch (err) {
+        throw new ClusterProbeError(`could not read the target cluster's capabilities: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const { kubeVersion, majorMinor } = parseServerVersion(versionRaw);
+    const apiVersions = apiVersionsRaw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    return { kubeVersion, majorMinor, apiVersions };
+}
+/**
+ * Every way `live` diverges from what `profile` declares, one message per
+ * divergence, each naming the declared and the live value. Empty when the
+ * cluster matches the profile.
+ *
+ * kubeVersion compares on major.minor (see module doc). apiVersions is a
+ * subset check: everything the profile declares must be served; extra API
+ * versions on the cluster are not a divergence, since a render only ever
+ * probed the declared set.
+ */
+export function compareCapabilityProfile(profile, live) {
+    const divergences = [];
+    if (profile.kubeVersion) {
+        const declared = majorMinorOf(profile.kubeVersion);
+        if (declared !== live.majorMinor) {
+            divergences.push(`kubeVersion: profile declares ${profile.kubeVersion} (${declared ?? "unparseable"}), ` +
+                `cluster runs ${live.kubeVersion} (${live.majorMinor})`);
+        }
+    }
+    const served = new Set(live.apiVersions);
+    for (const apiVersion of profile.apiVersions ?? []) {
+        if (!served.has(apiVersion)) {
+            divergences.push(`apiVersion ${apiVersion}: declared by the profile, not served by the cluster`);
+        }
+    }
+    return divergences;
+}