@intentius/chant-lexicon-helm 0.124.31 → 0.124.33

package/dist/op/activities/helm.js

@@ -0,0 +1,449 @@
+import { exec } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { load } from "js-yaml";
+import { helmInputDigest } from "../../render-digest.js";
+import { loadRenderContent, loadRenderManifest, renderStoreRoot } from "../../render-store.js";
+import { routeRender } from "../../render-wrapper.js";
+import { materializeWrapperChart } from "../../wrapper-chart.js";
+import { ClusterProbeError, compareCapabilityProfile, probeClusterCapabilities, } from "./cluster-probe.js";
+import { maybeRecordAutoRelease, } from "@intentius/chant/components/auto-release";
+const execAsync = promisify(exec);
+/** Thrown by the pinned path (#1242) when `contentDigest` resolves to nothing in the render store. */
+export class PinnedRenderNotFoundError extends Error {
+    constructor(contentDigest, root) {
+        super(`pinned install refused: render ${contentDigest} is not in the render store at ${root}. ` +
+            `Nothing was deployed. A pinned deploy installs recorded bytes; render and persist the chart ` +
+            `first (HelmRender with a capabilityProfile), or check the digest against \`listRenderManifests\`.`);
+        this.name = "PinnedRenderNotFoundError";
+    }
+}
+/** Thrown by the pinned path (#1242) when the stored bytes no longer hash to their digest — store corruption, caught before any mutation. */
+export class PinnedRenderIntegrityError extends Error {
+    constructor(contentDigest, actual) {
+        super(`pinned install refused: stored bytes for ${contentDigest} hash to ${actual} — the render store ` +
+            `entry is corrupt. Nothing was deployed. Re-render to repopulate the store; a digest that does ` +
+            `not match its bytes must never reach a cluster.`);
+        this.name = "PinnedRenderIntegrityError";
+    }
+}
+/** Thrown by the pinned path (#1242) when the call mixes pinned and unpinned inputs, or targets a release name the bytes were not rendered for. */
+export class PinnedInstallInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PinnedInstallInputError";
+    }
+}
+/**
+ * Thrown by the pinned path (#1242) when the deploy's declared capability
+ * profile disagrees with the profile recorded in the stored render's
+ * manifest. Distinct from `CapabilityProfileMismatchError` (#1244, declared
+ * vs *live cluster*): this is declared vs *recorded*, checked first and
+ * entirely offline.
+ */
+export class PinnedProfileMismatchError extends Error {
+    constructor(release, contentDigest, divergences) {
+        super(`pinned install refused: release "${release}" declares a capability profile that does not match ` +
+            `the one render ${contentDigest} was pinned against:\n` +
+            divergences.map((d) => `  - ${d}`).join("\n") +
+            `\nThe stored bytes are only accurate for the profile they were rendered for. Deploy them ` +
+            `against that profile, or re-render for this one. Nothing was deployed.`);
+        this.name = "PinnedProfileMismatchError";
+    }
+}
+/**
+ * Thrown before any helm mutation when the target cluster does not match the
+ * deploy's declared capability profile (#1244). The message names every
+ * divergence — declared vs live — so the refusal is specific, never a shrug.
+ */
+export class CapabilityProfileMismatchError extends Error {
+    constructor(release, profileName, divergences) {
+        const profile = profileName ? ` "${profileName}"` : "";
+        super(`helm release "${release}": target cluster does not match the declared capability profile${profile}:\n` +
+            divergences.map((d) => `  - ${d}`).join("\n") +
+            `\nThe deploy's identity was pinned against the declared profile; deploying to a diverging cluster ` +
+            `breaks the per-cluster guarantee that the same rendered bytes reach every cluster sharing a profile. ` +
+            `Fix the profile or retarget the deploy — or pass overrideProfileAssertion: true for a deliberate ` +
+            `override, which is recorded in the release record. Nothing was deployed.`);
+        this.divergences = divergences;
+        this.name = "CapabilityProfileMismatchError";
+    }
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Merge one `--set key=value` entry into `values` at its dotted path,
+ * helm's precedence (set wins over the file). Helm's backslash escaping for
+ * literal dots in keys is not interpreted — the digest needs a deterministic
+ * shape, not a re-implementation of helm's parser, and an escaped key still
+ * digests deterministically, just under its split form.
+ */
+function applySetEntry(values, path, value) {
+    const segments = path.split(".");
+    let node = values;
+    for (const segment of segments.slice(0, -1)) {
+        const next = node[segment];
+        if (isRecord(next)) {
+            node = next;
+        }
+        else {
+            const created = {};
+            node[segment] = created;
+            node = created;
+        }
+    }
+    node[segments[segments.length - 1]] = value;
+}
+/**
+ * The resolved values a deploy will hand to helm: the parsed values file
+ * (when given) with `--set` entries applied on top. A values file that does
+ * not parse to a mapping contributes nothing — helm itself rejects such a
+ * file at deploy time, so the digest never sees it succeed.
+ */
+function resolveValues(args) {
+    const parsed = args.values ? load(readFileSync(args.values, "utf8")) : undefined;
+    const values = isRecord(parsed) ? parsed : {};
+    for (const [path, value] of Object.entries(args.set ?? {}))
+        applySetEntry(values, path, value);
+    return values;
+}
+/**
+ * The input-side identity of a helm deploy (#1243): a `sha256:` digest over
+ * the canonical JSON of `{ chart, chartVersion, values, capabilityProfile? }`.
+ * Canonical JSON (core's `canonicalJson`, RFC 8785 shape) sorts object keys,
+ * so the digest is stable across value key order; `apiVersions` is sorted
+ * for the same reason. The digest changes when any actual input changes —
+ * the chart, its version, a value, the declared profile.
+ *
+ * Delegates to `helmInputDigest` (#1237) — the same helper `HelmRender`
+ * records as a pinned render's `inputDigest` — so a deploy and a render of
+ * the same inputs share their identity by construction.
+ */
+export function helmInstallInputDigest(args) {
+    if (!args.chart) {
+        throw new Error(`cannot compute an input digest for release "${args.name}": no chart reference. ` +
+            `A pinned deploy carries its digests in the stored RenderManifest instead.`);
+    }
+    return helmInputDigest({
+        chart: args.chart,
+        chartVersion: args.chartVersion,
+        values: resolveValues(args),
+        capabilityProfile: args.capabilityProfile,
+    });
+}
+/**
+ * Assert the target cluster matches the deploy's declared capability profile
+ * (#1244), before any helm mutation. Returns the assertion outcome, or
+ * `undefined` when there was nothing to assert (no profile, or a profile
+ * declaring no facts) — that path never touches kubectl, keeping the
+ * no-profile deploy exactly what it was.
+ *
+ * A mismatch throws `CapabilityProfileMismatchError` naming every divergence.
+ * An unprobeable cluster throws too — a deploy that cannot verify its
+ * guarantee must not silently proceed. `overrideProfileAssertion: true`
+ * turns both refusals into a warned, recorded override.
+ */
+async function assertCapabilityProfile(args, signal) {
+    const profile = args.capabilityProfile;
+    if (!profile || (!profile.kubeVersion && !(profile.apiVersions?.length)))
+        return undefined;
+    let divergences;
+    try {
+        const live = await probeClusterCapabilities(signal);
+        divergences = compareCapabilityProfile(profile, live);
+    }
+    catch (err) {
+        const why = err instanceof Error ? err.message : String(err);
+        if (!args.overrideProfileAssertion) {
+            throw new ClusterProbeError(`helm release "${args.name}": the deploy declares capability profile` +
+                `${profile.name ? ` "${profile.name}"` : ""} but the target cluster's capabilities could not ` +
+                `be verified — ${why}. A deploy that cannot verify its declared profile does not proceed. ` +
+                `Nothing was deployed. Pass overrideProfileAssertion: true only for a deliberate override.`);
+        }
+        divergences = [`capability probe failed: ${why}`];
+    }
+    if (divergences.length === 0)
+        return { matched: true };
+    if (!args.overrideProfileAssertion) {
+        throw new CapabilityProfileMismatchError(args.name, profile.name, divergences);
+    }
+    console.error(`warning: helm release "${args.name}" deploying despite capability profile` +
+        `${profile.name ? ` "${profile.name}"` : ""} divergence (overrideProfileAssertion):\n` +
+        divergences.map((d) => `  - ${d}`).join("\n") +
+        `\nThe override is recorded in the release record.`);
+    return { matched: false, divergences, overridden: true };
+}
+/**
+ * Append the deploy's release record, best-effort (#1243). Called only after
+ * `helm upgrade --install` succeeded — a failed deploy writes nothing, by
+ * construction, because this function is never reached.
+ *
+ * Reuses `maybeRecordAutoRelease` — the same field resolution the
+ * `chant run --components` post-run step applies (actor from
+ * `GITHUB_ACTOR`/`GITLAB_USER_LOGIN`/`USER`, git sha from `HEAD`, timestamp
+ * taken at record time, append + push to the `chant/lifecycle` orphan
+ * branch). A field that cannot be resolved here (e.g. no git repo in a
+ * worker container) is never faked: the append is skipped and the skip is
+ * warned about, exactly as the convention's error path behaves.
+ */
+async function recordHelmRelease(args, digest, digestError, profileOverride, inputDigest) {
+    if (args.recordRelease === false)
+        return { recorded: false, reason: "opted-out" };
+    if (!digest) {
+        return { recorded: false, reason: "error", error: digestError ?? "input digest unavailable" };
+    }
+    const runId = args.runId ?? process.env.GITHUB_RUN_ID ?? process.env.CI_PIPELINE_ID ?? `local-${Date.now()}`;
+    return maybeRecordAutoRelease({
+        component: args.component ?? args.name,
+        env: args.env ?? "local",
+        success: true,
+        digest,
+        runId,
+        profileOverride,
+        inputDigest,
+    });
+}
+/**
+ * Deploy a helm release and append a `ReleaseRecord` (#1243).
+ *
+ * Two paths, selected by `contentDigest`:
+ *
+ * - **Unpinned** (no `contentDigest`): `helm upgrade --install <name>
+ *   <chart>`, exactly as before #1242 — helm renders at deploy time. The
+ *   ledger record is keyed by the input digest.
+ * - **Pinned** (`contentDigest` set, #1242): the recorded render is loaded
+ *   from the render store, its digest verified, and those exact bytes
+ *   installed as a structure-preserving wrapper chart — no deploy-time
+ *   render. The ledger record is keyed by the content digest and carries
+ *   the stored render's input digest alongside it.
+ *
+ * A ledger-append failure after a successful deploy warns and never throws:
+ * the deploy already happened, so a ledger-write hiccup must not turn a
+ * finished deploy into a failed activity — the record is observability, not
+ * part of the deploy itself.
+ *
+ * Uses the longInfra profile: 20m timeout, three attempts backing off from 30s.
+ */
+export async function helmInstall(args, signal) {
+    if (args.contentDigest)
+        return pinnedHelmInstall(args, args.contentDigest, signal);
+    if (!args.chart) {
+        throw new PinnedInstallInputError(`helm release "${args.name}": no chart reference and no contentDigest — pass \`chart\` for an ` +
+            `unpinned deploy, or \`contentDigest\` to install a recorded pinned render. Nothing was deployed.`);
+    }
+    // The digest is computed over the same bytes the deploy reads, before the
+    // deploy runs. A compute failure (unreadable values file, unrepresentable
+    // value) must not block the deploy — helm gives the authoritative error —
+    // so it is carried into the record outcome instead of thrown here.
+    let inputDigest;
+    let digestError;
+    try {
+        inputDigest = helmInstallInputDigest(args);
+    }
+    catch (err) {
+        digestError = `could not compute input digest: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    // Deploy-time profile assertion (#1244): when a profile is declared, the
+    // live cluster must match it before helm mutates anything. A refusal (or
+    // an unprobeable cluster) throws here, so no helm command has run yet.
+    const profileAssertion = await assertCapabilityProfile(args, signal);
+    const parts = ["helm", "upgrade", "--install", "--wait", args.name, args.chart];
+    if (args.chartVersion)
+        parts.push("--version", args.chartVersion);
+    if (args.namespace)
+        parts.push("--namespace", args.namespace, "--create-namespace");
+    if (args.values)
+        parts.push("-f", args.values);
+    for (const [k, v] of Object.entries(args.set ?? {}))
+        parts.push("--set", `${k}=${v}`);
+    const { stdout, stderr } = await execAsync(parts.join(" "), { signal });
+    if (stdout)
+        console.log(stdout);
+    if (stderr)
+        console.error(stderr);
+    const profileOverride = profileAssertion && !profileAssertion.matched ? profileAssertion.divergences.join("; ") : undefined;
+    const release = await recordHelmRelease(args, inputDigest, digestError, profileOverride);
+    if (!release.recorded && release.reason !== "opted-out") {
+        const why = release.reason === "error"
+            ? release.error
+            : `${release.reason}${release.detail ? ` — ${release.detail}` : ""}`;
+        console.error(`warning: helm release "${args.name}" deployed, but no release record was appended (${why}). ` +
+            `The deploy succeeded; the ledger write is best-effort observability and never fails a finished deploy.`);
+    }
+    return {
+        inputDigest,
+        release,
+        ...(profileAssertion ? { profileAssertion } : {}),
+        releaseName: args.name,
+        namespace: args.namespace ?? null,
+        pinned: false,
+    };
+}
+/**
+ * The pinned install path (#1242): deploy a recorded render's exact bytes.
+ *
+ * Refusals, all before any helm mutation, each with its own error type:
+ * mixed pinned/unpinned inputs (`PinnedInstallInputError`), digest not in
+ * the store (`PinnedRenderNotFoundError`), stored bytes not hashing to
+ * their digest (`PinnedRenderIntegrityError`), a declared profile
+ * disagreeing with the recorded one (`PinnedProfileMismatchError`), a
+ * release name the bytes were not rendered for
+ * (`PinnedInstallInputError` — `.Release.Name` is baked into the bytes),
+ * and the #1244 live-cluster assertion, which on this path always runs
+ * against the *manifest's* profile — a stored render is pinned by
+ * construction, so the deploy always has a profile to verify.
+ *
+ * The install input is a structure-preserving wrapper chart materialized
+ * from the routed render (`routeRender` over the stored bytes — the #1239
+ * seam): CRD-origin documents in `crds/` (uninstall-safe, epic finding 4),
+ * everything else shipped verbatim through `.Files.Get` shims so no byte is
+ * re-templated. `helm history` / `helm rollback` keep working — the wrapper
+ * inherits the source chart's name and version, and the release is a normal
+ * helm release.
+ */
+async function pinnedHelmInstall(args, contentDigest, signal) {
+    const renderInputs = ["chart", "chartVersion", "values"].filter((k) => args[k] !== undefined);
+    if (args.set && Object.keys(args.set).length > 0)
+        renderInputs.push("set");
+    if (renderInputs.length > 0) {
+        throw new PinnedInstallInputError(`pinned install refused: release "${args.name}" passes contentDigest together with ` +
+            `deploy-time render input(s) ${renderInputs.map((k) => `\`${k}\``).join(", ")}. A pinned deploy ` +
+            `installs the recorded bytes of ${contentDigest} — chart, values, set and chartVersion were ` +
+            `closed at render time and cannot be re-opened here. Drop them, or drop contentDigest for an ` +
+            `unpinned deploy. Nothing was deployed.`);
+    }
+    const storeOpts = args.renderStoreRoot ? { root: args.renderStoreRoot } : undefined;
+    const manifest = loadRenderManifest(contentDigest, storeOpts);
+    const content = manifest ? loadRenderContent(contentDigest, storeOpts) : undefined;
+    if (!manifest || content === undefined) {
+        throw new PinnedRenderNotFoundError(contentDigest, args.renderStoreRoot ?? renderStoreRoot());
+    }
+    // Verify before any mutation: the stored bytes are the digest's preimage
+    // (the store writes canonical bytes under their own hash), so a mismatch
+    // means the entry was corrupted or tampered with after it was written.
+    const actual = `sha256:${createHash("sha256").update(content, "utf8").digest("hex")}`;
+    if (actual !== contentDigest)
+        throw new PinnedRenderIntegrityError(contentDigest, actual);
+    if (args.name !== manifest.releaseName) {
+        throw new PinnedInstallInputError(`pinned install refused: render ${contentDigest} was rendered for release ` +
+            `"${manifest.releaseName}" but the deploy targets release "${args.name}". \`.Release.Name\` is ` +
+            `baked into the recorded bytes (labels, resource names), so installing them under another name ` +
+            `deploys bytes that claim a different release. Deploy under "${manifest.releaseName}", or ` +
+            `render for "${args.name}". Nothing was deployed.`);
+    }
+    assertDeclaredProfileMatchesManifest(args, contentDigest, manifest);
+    // The #1244 live-cluster assertion, against the profile the bytes were
+    // actually rendered for — the RenderManifest's, not the caller's (the two
+    // were just proven to agree where the caller declared one).
+    const profileAssertion = await assertCapabilityProfile({
+        ...args,
+        capabilityProfile: {
+            name: manifest.capabilityProfile.cluster,
+            kubeVersion: manifest.capabilityProfile.kubeVersion,
+            apiVersions: manifest.capabilityProfile.apiVersions,
+        },
+    }, signal);
+    const namespace = args.namespace ?? manifest.namespace ?? undefined;
+    if (args.namespace && manifest.namespace && args.namespace !== manifest.namespace) {
+        console.error(`warning: pinned release "${args.name}" deploys to namespace "${args.namespace}" but was ` +
+            `rendered for "${manifest.namespace}" — documents that bake in \`.Release.Namespace\` will ` +
+            `carry the rendered value.`);
+    }
+    const routed = routeRender(content, { chart: manifest.chart, chartVersion: manifest.chartVersion });
+    for (const warning of routed.warnings) {
+        console.error(`warning: pinned release "${args.name}": ${warning.message}`);
+    }
+    const wrapperDir = mkdtempSync(join(tmpdir(), "chant-helm-pinned-"));
+    try {
+        materializeWrapperChart(routed, wrapperDir);
+        const parts = ["helm", "upgrade", "--install", "--wait", args.name, wrapperDir];
+        if (namespace)
+            parts.push("--namespace", namespace, "--create-namespace");
+        const { stdout, stderr } = await execAsync(parts.join(" "), { signal });
+        if (stdout)
+            console.log(stdout);
+        if (stderr)
+            console.error(stderr);
+    }
+    finally {
+        rmSync(wrapperDir, { recursive: true, force: true });
+    }
+    // Revision from helm's own bookkeeping (`helm get metadata -o json`) —
+    // best-effort after a successful install, like the ledger append: a
+    // metadata read hiccup must not fail a finished deploy.
+    let revision;
+    let chartVersion = manifest.chartVersion;
+    try {
+        const metaParts = ["helm", "get", "metadata", args.name, "-o", "json"];
+        if (namespace)
+            metaParts.push("--namespace", namespace);
+        const { stdout } = await execAsync(metaParts.join(" "), { signal });
+        const meta = JSON.parse(stdout);
+        const parsed = Number(meta.revision);
+        if (Number.isFinite(parsed))
+            revision = parsed;
+        if (typeof meta.version === "string" && meta.version.length > 0)
+            chartVersion = meta.version;
+    }
+    catch (err) {
+        console.error(`warning: pinned release "${args.name}" deployed, but \`helm get metadata\` failed ` +
+            `(${err instanceof Error ? err.message : String(err)}); the result carries no revision.`);
+    }
+    const profileOverride = profileAssertion && !profileAssertion.matched ? profileAssertion.divergences.join("; ") : undefined;
+    // Pinned deploys record the content digest — what this cluster actually
+    // received — with the stored render's input digest alongside as the
+    // cross-environment join key (epic Decisions: profiles are per cluster,
+    // so bytes legitimately differ across environments; inputs do not).
+    const release = await recordHelmRelease(args, contentDigest, undefined, profileOverride, manifest.inputDigest);
+    if (!release.recorded && release.reason !== "opted-out") {
+        const why = release.reason === "error"
+            ? release.error
+            : `${release.reason}${release.detail ? ` — ${release.detail}` : ""}`;
+        console.error(`warning: helm release "${args.name}" deployed, but no release record was appended (${why}). ` +
+            `The deploy succeeded; the ledger write is best-effort observability and never fails a finished deploy.`);
+    }
+    return {
+        inputDigest: manifest.inputDigest,
+        release,
+        ...(profileAssertion ? { profileAssertion } : {}),
+        releaseName: args.name,
+        namespace: namespace ?? null,
+        pinned: true,
+        contentDigest,
+        revision,
+        chartVersion,
+        crdsApplied: routed.crds.length,
+        docsApplied: routed.main.length + routed.hooks.length,
+        hooksRun: routed.hooks.length,
+    };
+}
+/**
+ * Offline half of the pinned profile check: when the deploy itself declares
+ * a capability profile, its facts must agree with the profile recorded in
+ * the stored render's manifest — same kubeVersion, declared apiVersions all
+ * among the recorded set. A caller that declares nothing defers entirely to
+ * the manifest.
+ */
+function assertDeclaredProfileMatchesManifest(args, contentDigest, manifest) {
+    const declared = args.capabilityProfile;
+    if (!declared)
+        return;
+    const recorded = manifest.capabilityProfile;
+    const divergences = [];
+    if (declared.kubeVersion && declared.kubeVersion !== recorded.kubeVersion) {
+        divergences.push(`kubeVersion: deploy declares ${declared.kubeVersion}, render was pinned against ${recorded.kubeVersion}`);
+    }
+    const recordedApis = new Set(recorded.apiVersions);
+    for (const apiVersion of declared.apiVersions ?? []) {
+        if (!recordedApis.has(apiVersion)) {
+            divergences.push(`apiVersion ${apiVersion}: declared by the deploy, absent from the render's recorded profile`);
+        }
+    }
+    if (divergences.length > 0) {
+        throw new PinnedProfileMismatchError(args.name, contentDigest, divergences);
+    }
+}

package/dist/op/activities/index.js

@@ -0,0 +1,10 @@
+/**
+ * helm Op activities — resolved by the core activity registry when a project's
+ * `chant.config.ts` lists the `helm` lexicon. `helmInstall` shells out to the
+ * helm CLI, retried under the step's profile; relocated from the hosting
+ * lexicon (#809) so helm's imperative activity lives with its product. The
+ * `helmInstall` step builder stays in core and reaches authors through
+ * `@intentius/chant/op` like the other core builders.
+ */
+export { helmInstall, helmInstallInputDigest, CapabilityProfileMismatchError, PinnedRenderNotFoundError, PinnedRenderIntegrityError, PinnedInstallInputError, PinnedProfileMismatchError, } from "./helm.js";
+export { probeClusterCapabilities, compareCapabilityProfile, ClusterProbeError } from "./cluster-probe.js";

package/dist/op/builders.js

@@ -0,0 +1,45 @@
+/**
+ * Typed step-builder wrappers for this lexicon's `helmInstall` activity
+ * (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), so a fully typed `helmInstall` /
+ * `helmInstallPinned` has to live beside {@link HelmInstallArgs} — here,
+ * next to `./activities/helm.ts`. `opts`'s type in each wrapper below IS
+ * `HelmInstallArgs` itself (via `Omit`/`WithStepRefs`) — never a
+ * hand-restated mirror — so the option surface Stage 1's zod contracts
+ * deliberately skipped (`capabilityProfile`, `set`, `deleteMode`-adjacent
+ * cross-field options) is authoring-time typed for free.
+ *
+ * Every field also accepts a {@link StepOutputRef} in its place
+ * ({@link WithStepRefs}, chant #1950).
+ *
+ * `core`'s own `helmInstall`/`helmInstallPinned` (in `@intentius/chant/op`)
+ * are UNCHANGED and produce byte-identical `ActivityStep` output for the same
+ * inputs — these are purely additive. Deliberately not swapped into core's
+ * barrel (see `lexicons/k8s/src/op/builders.ts`'s module doc for why: it
+ * would make core depend on this package at runtime, undoing the
+ * product-agnostic split #809 did). An author who wants the typed surface
+ * imports it from
+ * here — `@intentius/chant-lexicon-helm` — which a project using
+ * `helmInstall` already depends on.
+ */
+import { activity, takeProfileAndId, } from "@intentius/chant/op";
+/**
+ * Deploy a helm release — the fully typed twin of core's `helmInstall`.
+ * `opts` is {@link HelmInstallArgs} itself, minus the positional `name`/
+ * `chart`. Defaults to the `longInfra` profile.
+ */
+export const helmInstall = (name, chart, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("helmInstall", { name, chart, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+/**
+ * Deploy a recorded pinned render by its `sha256:` content digest (#1242) —
+ * the fully typed twin of core's `helmInstallPinned`. `opts` is
+ * {@link HelmInstallArgs} itself, minus the positional `name`/
+ * `contentDigest`. Defaults to the `longInfra` profile.
+ */
+export const helmInstallPinned = (name, contentDigest, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("helmInstall", { name, contentDigest, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};

package/dist/package-cli.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for Helm 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);
+});