@intentius/chant-lexicon-helm 0.124.31 → 0.124.32

package/dist/validate-cli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for Helm lexicon validation.
+ */
+import { validate } from "./validate.js";
+import { printValidationResult } from "@intentius/chant/codegen/validate";
+async function main() {
+    const result = await validate();
+    printValidationResult(result);
+    if (!result.success) {
+        process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error("Validation failed:", err);
+    process.exit(1);
+});

package/dist/validate.js

@@ -0,0 +1,30 @@
+/**
+ * Validate generated lexicon-helm artifacts.
+ *
+ * Thin wrapper around the core validation framework
+ * with Helm-specific configuration.
+ */
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts } from "@intentius/chant/codegen/validate";
+const REQUIRED_NAMES = [
+    "Chart",
+    "Values",
+    "HelmTest",
+    "HelmNotes",
+    "HelmHook",
+    "HelmDependency",
+    "HelmMaintainer",
+    "HelmCRD",
+];
+/**
+ * Validate the generated lexicon-helm artifacts.
+ */
+export async function validate(opts) {
+    const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+    return validateLexiconArtifacts({
+        lexiconJsonFilename: "lexicon-helm.json",
+        requiredNames: REQUIRED_NAMES,
+        basePath,
+    });
+}

package/dist/values-probe.js

@@ -0,0 +1,504 @@
+/**
+ * Build-time coalesced-values probe (#1251, epic #1228 Phase 7) and the
+ * provenance derived from it (#1252).
+ *
+ * `helm template --debug` does not print coalesced values on either major
+ * version, and `helm get values --all` needs an installed release — the
+ * wrong side of the build/deploy line. So the probe extracts them from helm
+ * itself: copy the chart, replace every (sub)chart's `templates/` with a
+ * single `chant-values-probe.yaml` template containing `{{ toYaml .Values }}`,
+ * render, lift the probe documents out, discard the copy. Coalescing —
+ * parent-overrides-child, `global` propagation, alias scoping,
+ * `import-values`, tags — is delegated to helm rather than reimplemented
+ * (the approximation in `pinnability/values.ts` remains only as the
+ * classifier's offline fallback).
+ *
+ * The probe filename must NOT begin with `_`: helm treats underscore-prefixed
+ * template files as partials and skips them without error.
+ *
+ * The probe runs against a private copy in a temp directory, so the probe
+ * document can never appear in a real render of the chart — the pinned
+ * artifact path (#1237/#1242) never sees the injected template.
+ *
+ * A dependency disabled by a `condition:` (or tags) is pruned by helm before
+ * rendering, so it yields no probe document. Those instances are reported in
+ * `disabled` instead, with the condition path where determinable. Note the
+ * ROOT probe document still carries the values subtree a disabled dependency
+ * would have received — an installed release omits it (epic findings 14, 15).
+ *
+ * On the probe output, three provenance products (#1252):
+ *
+ * - `digest` — `sha256:` over the canonical JSON (core's `canonicalJson`,
+ *   the #1237 convention) of the per-instance coalesced trees, keyed by
+ *   scope path. Same inputs, same coalesced values, same digest.
+ * - `valueSources` — each coalesced path attributed to its winning layer:
+ *   chart default / parent override / supplied file / --set.
+ * - `deadAssignments` — supplied values that never survive coalescing:
+ *   shadowed by a later supplied layer, or targeting a disabled or unknown
+ *   subchart path. WHM504 turns these into lint diagnostics.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { canonicalJson } from "@intentius/chant/effect-receipt";
+import yaml from "js-yaml";
+import { splitDocuments } from "./pinnability/render-stream.js";
+import { readChartMeta, readYamlFile, valueAtPath } from "./pinnability/values.js";
+/**
+ * The probe template. Renders one document per chart instance carrying the
+ * exact `.Values` that instance coalesced. For an aliased dependency helm
+ * sets `.Chart.Name` (and the `# Source:` path segment) to the alias, so two
+ * instances over the same chart directory stay distinguishable.
+ */
+const PROBE_TEMPLATE = "chantValuesProbe: v1\nchart: {{ .Chart.Name }}\nvalues:\n{{ .Values | toYaml | nindent 2 }}\n";
+/** Must not start with `_` — helm skips underscore-prefixed files as partials. */
+const PROBE_FILENAME = "chant-values-probe.yaml";
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function deepEqual(a, b) {
+    return canonicalJson(a ?? null) === canonicalJson(b ?? null);
+}
+/**
+ * Leaf paths of a values tree. Arrays and empty maps are leaves — helm
+ * replaces arrays wholesale and an empty map carries no mergeable children.
+ */
+function leafPaths(v, prefix = []) {
+    if (isPlainObject(v) && Object.keys(v).length > 0) {
+        const out = [];
+        for (const [k, child] of Object.entries(v))
+            out.push(...leafPaths(child, [...prefix, k]));
+        return out;
+    }
+    return prefix.length > 0 ? [prefix] : [];
+}
+const scopeKey = (scope) => scope.join(".");
+/**
+ * Walk the (copied, tgz-extracted) chart tree the way helm's loader does:
+ * declared dependencies under their alias-or-name key, undeclared `charts/`
+ * directories as implicit always-enabled dependencies.
+ */
+function collectScopeNodes(rootDir) {
+    const nodes = [];
+    const visit = (dir, scope) => {
+        const meta = readChartMeta(dir);
+        nodes.push({
+            scope,
+            name: meta.name,
+            dir,
+            parentScope: scope.slice(0, -1),
+            // condition is attached where the dependency is declared, below.
+        });
+        const chartsDir = join(dir, "charts");
+        const childDirs = existsSync(chartsDir)
+            ? readdirSync(chartsDir).filter((e) => {
+                const p = join(chartsDir, e);
+                return statSync(p).isDirectory() && existsSync(join(p, "Chart.yaml"));
+            })
+            : [];
+        const declared = new Set();
+        for (const dep of meta.dependencies) {
+            const childDir = join(chartsDir, dep.name);
+            if (!existsSync(join(childDir, "Chart.yaml")))
+                continue;
+            declared.add(dep.name);
+            const childScope = [...scope, dep.alias ?? dep.name];
+            visit(childDir, childScope);
+            const node = nodes.find((n) => scopeKey(n.scope) === scopeKey(childScope));
+            if (node)
+                node.condition = dep.condition;
+        }
+        for (const name of childDirs) {
+            if (!declared.has(name))
+                visit(join(chartsDir, name), [...scope, name]);
+        }
+    };
+    visit(rootDir, []);
+    return nodes;
+}
+/**
+ * Extract packaged subcharts (`charts/*.tgz`) in place so probes can be
+ * injected into them, then recurse. Uses the system `tar`; a failed
+ * extraction leaves the tgz alone and records a warning — that subchart's
+ * values then appear only through its parents' probe documents.
+ */
+function extractPackagedSubcharts(dir, warnings) {
+    const chartsDir = join(dir, "charts");
+    if (!existsSync(chartsDir))
+        return;
+    for (const entry of readdirSync(chartsDir)) {
+        if (!entry.endsWith(".tgz"))
+            continue;
+        const tgz = join(chartsDir, entry);
+        if (!statSync(tgz).isFile())
+            continue;
+        try {
+            // A chart archive unpacks to a single top-level directory named after
+            // the chart. Skip when that directory already exists.
+            execFileSync("tar", ["-xzf", tgz, "-C", chartsDir], { stdio: "ignore" });
+            rmSync(tgz);
+        }
+        catch {
+            warnings.push(`could not extract packaged subchart ${entry} — its own probe document is skipped`);
+        }
+    }
+    for (const entry of readdirSync(chartsDir)) {
+        const p = join(chartsDir, entry);
+        if (statSync(p).isDirectory() && existsSync(join(p, "Chart.yaml"))) {
+            extractPackagedSubcharts(p, warnings);
+        }
+    }
+}
+/**
+ * Replace each (sub)chart's `templates/` with the single probe template.
+ * Deleting the real templates sidesteps render-time failures (`required`,
+ * missing capabilities) — values coalescing does not depend on them.
+ * Library charts are left alone: helm never renders their templates.
+ */
+function injectProbes(dir, warnings) {
+    const chartYaml = readYamlFile(join(dir, "Chart.yaml"));
+    if (chartYaml?.type === "library") {
+        warnings.push(`${dir} is a library chart — helm renders no templates for it, so it yields no probe document`);
+    }
+    else {
+        const templatesDir = join(dir, "templates");
+        rmSync(templatesDir, { recursive: true, force: true });
+        mkdirSync(templatesDir, { recursive: true });
+        writeFileSync(join(templatesDir, PROBE_FILENAME), PROBE_TEMPLATE);
+    }
+    const chartsDir = join(dir, "charts");
+    if (!existsSync(chartsDir))
+        return;
+    for (const entry of readdirSync(chartsDir)) {
+        const p = join(chartsDir, entry);
+        if (statSync(p).isDirectory() && existsSync(join(p, "Chart.yaml")))
+            injectProbes(p, warnings);
+    }
+}
+function defaultRunHelm(args) {
+    try {
+        return execFileSync("helm", args, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            maxBuffer: 64 * 1024 * 1024,
+        });
+    }
+    catch (err) {
+        const stderr = err && typeof err === "object" && "stderr" in err ? String(err.stderr) : String(err);
+        throw new Error(`coalesced-values probe render failed:\n${stderr}\n` +
+            `Hint: ensure the 'helm' CLI is on PATH and the chart's dependencies are vendored under charts/.`);
+    }
+}
+/** Scope of a probe document, from its `# Source:` path — every segment following a `charts/`. */
+function scopeFromSource(sourceLine) {
+    const m = sourceLine.match(/^# Source: (\S+)$/m);
+    if (!m)
+        return undefined;
+    const segments = m[1].split("/");
+    if (segments[segments.length - 1] !== PROBE_FILENAME)
+        return undefined;
+    const scope = [];
+    for (let i = 1; i < segments.length - 2; i += 2) {
+        if (segments[i] !== "charts")
+            return undefined;
+        scope.push(segments[i + 1]);
+    }
+    return scope;
+}
+/**
+ * The coalesced-values identity: `sha256:` over the canonical JSON of the
+ * per-instance trees keyed by scope path — the #1237 digest conventions
+ * (core `canonicalJson`, `sha256:` prefix). Two renders that coalesce the
+ * same values for every instance share it; any value, in any subchart,
+ * changing breaks it.
+ */
+export function coalescedValuesDigest(instances) {
+    const tree = {};
+    for (const i of instances)
+        tree[scopeKey(i.scope)] = i.values;
+    return `sha256:${createHash("sha256").update(canonicalJson(tree), "utf8").digest("hex")}`;
+}
+/**
+ * Attribute each coalesced path to the layer that won it.
+ *
+ * Keys are dot-joined root-coordinate paths: a subchart instance's paths are
+ * prefixed with its scope, so `kidtwo.replicas` is the `replicas` the
+ * `kidtwo` instance actually sees. A key of an instance's tree that is
+ * itself an enabled child scope is skipped — helm pushes the child's
+ * coalesced tree back into the parent's `.Values`, and the child instance
+ * owns those paths.
+ *
+ * Layer precedence mirrors helm: supplied layers (last first), then ancestor
+ * chart defaults (root outranks intermediates — "parent override"), then the
+ * instance's own defaults ("chart default"). A path no layer explains — an
+ * `import-values` product, a helm-computed merge — reports `computed`.
+ * Attribution matches on value equality, so a layer that assigned a path but
+ * lost it reports as the layer that actually won.
+ */
+export function computeValueSources(input) {
+    const out = {};
+    const instanceScopes = new Set(input.instances.map((i) => scopeKey(i.scope)));
+    for (const instance of input.instances) {
+        for (const path of leafPaths(instance.values)) {
+            // Skip paths under an enabled child scope — the child instance owns them.
+            if (instanceScopes.has(scopeKey([...instance.scope, path[0]])))
+                continue;
+            const coalesced = valueAtPath(instance.values, path);
+            out[scopeKey([...instance.scope, ...path])] = attributePath(instance, path, coalesced, input);
+        }
+    }
+    return out;
+}
+function attributePath(instance, path, coalesced, input) {
+    const rootPath = [...instance.scope, ...path];
+    const isGlobal = path[0] === "global" && instance.scope.length > 0;
+    // 1. Supplied layers, highest precedence first. A subchart's `global.*`
+    //    can be fed either scoped (`<scope>.global.*`) or from the root
+    //    `global.*` — scoped wins, so check it first.
+    for (let i = input.supplied.length - 1; i >= 0; i--) {
+        const layer = input.supplied[i];
+        let candidate = valueAtPath(layer.values, rootPath);
+        if (candidate === undefined && isGlobal)
+            candidate = valueAtPath(layer.values, path);
+        if (candidate !== undefined && deepEqual(candidate, coalesced))
+            return layer.origin;
+    }
+    // 2. Ancestor chart defaults — the top parent outranks intermediates.
+    for (let prefixLen = 0; prefixLen < instance.scope.length; prefixLen++) {
+        const ancestorScope = instance.scope.slice(0, prefixLen);
+        const defaults = input.defaultsFor(ancestorScope);
+        if (defaults === undefined)
+            continue;
+        const rel = [...instance.scope.slice(prefixLen), ...path];
+        let candidate = valueAtPath(defaults, rel);
+        if (candidate === undefined && isGlobal)
+            candidate = valueAtPath(defaults, path);
+        if (candidate !== undefined && deepEqual(candidate, coalesced))
+            return "parent override";
+    }
+    // 3. The instance's own values.yaml.
+    const own = input.defaultsFor(instance.scope);
+    if (own !== undefined) {
+        const candidate = valueAtPath(own, path);
+        if (candidate !== undefined && deepEqual(candidate, coalesced))
+            return "chart default";
+    }
+    return "computed";
+}
+const layerLabel = (layer) => layer.name !== undefined ? `${layer.origin} (${layer.name})` : layer.origin;
+/**
+ * Supplied values that never survive coalescing:
+ *
+ * - `shadowed` — a later supplied layer assigns the same path (a map merging
+ *   into a map is not a shadow; anything else replaces).
+ * - `disabled-subchart` — the path targets a dependency a `condition:` (or
+ *   tags) disabled, so no rendered chart ever reads it.
+ * - `unknown-subchart` — a map supplied under a top-level key that matches
+ *   no dependency, no root default, and not `global`, on a chart that HAS
+ *   dependencies: the classic silently-ignored typo of a subchart name.
+ *   Reported once per top-level key per layer.
+ */
+export function findDeadAssignments(input, disabled) {
+    const out = [];
+    const rootDefaults = input.defaultsFor([]) ?? {};
+    const knownFirstSegments = new Set(["global", ...Object.keys(rootDefaults)]);
+    let hasDependencies = false;
+    for (const i of input.instances) {
+        if (i.scope.length > 0) {
+            knownFirstSegments.add(i.scope[0]);
+            hasDependencies = true;
+        }
+    }
+    for (const d of disabled) {
+        knownFirstSegments.add(d.scope[0]);
+        if (d.name !== d.scope[0])
+            knownFirstSegments.add(d.name);
+        hasDependencies = true;
+    }
+    for (let i = 0; i < input.supplied.length; i++) {
+        const layer = input.supplied[i];
+        const flaggedUnknown = new Set();
+        for (const path of leafPaths(layer.values)) {
+            const value = valueAtPath(layer.values, path);
+            // Shadowed by a later supplied layer?
+            const shadow = input.supplied.slice(i + 1).find((later) => {
+                const laterValue = valueAtPath(later.values, path);
+                if (laterValue === undefined)
+                    return false;
+                return !(isPlainObject(value) && isPlainObject(laterValue));
+            });
+            if (shadow) {
+                out.push({
+                    path: scopeKey(path),
+                    origin: layerLabel(layer),
+                    reason: "shadowed",
+                    shadowedBy: layerLabel(shadow),
+                });
+                continue;
+            }
+            // Targeting a disabled dependency?
+            const disabledHit = disabled.find((d) => d.scope.length <= path.length && scopeKey(path.slice(0, d.scope.length)) === scopeKey(d.scope));
+            if (disabledHit) {
+                out.push({
+                    path: scopeKey(path),
+                    origin: layerLabel(layer),
+                    reason: "disabled-subchart",
+                    shadowedBy: disabledHit.condition !== undefined
+                        ? `disabled subchart ${scopeKey(disabledHit.scope)} (condition ${disabledHit.condition} is false)`
+                        : `disabled subchart ${scopeKey(disabledHit.scope)}`,
+                });
+                continue;
+            }
+            // A map under an unknown top-level key on a chart with dependencies?
+            if (hasDependencies &&
+                path.length > 1 &&
+                !knownFirstSegments.has(path[0]) &&
+                isPlainObject(layer.values[path[0]]) &&
+                !flaggedUnknown.has(path[0])) {
+                flaggedUnknown.add(path[0]);
+                out.push({
+                    path: path[0],
+                    origin: layerLabel(layer),
+                    reason: "unknown-subchart",
+                    shadowedBy: `no dependency, chart default, or global named "${path[0]}"`,
+                });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Run the probe: copy the chart, inject probe templates, render, lift the
+ * probe documents out, analyze, discard the copy. The source chart is never
+ * touched. Every run is recorded for WHM504 (`getValuesProbeRecords`).
+ */
+export function probeCoalescedValues(options) {
+    if (!existsSync(join(options.chartDir, "Chart.yaml"))) {
+        throw new Error(`coalesced-values probe: ${options.chartDir} has no Chart.yaml`);
+    }
+    const warnings = [];
+    const supplied = options.supplied ?? [];
+    const workRoot = mkdtempSync(join(tmpdir(), "chant-values-probe-"));
+    try {
+        const chartCopy = join(workRoot, "chart");
+        cpSync(options.chartDir, chartCopy, { recursive: true });
+        extractPackagedSubcharts(chartCopy, warnings);
+        injectProbes(chartCopy, warnings);
+        const scopeNodes = collectScopeNodes(chartCopy);
+        const releaseName = options.releaseName ?? "chant-values-probe";
+        const args = ["template", releaseName, chartCopy];
+        if (options.namespace !== undefined)
+            args.push("--namespace", options.namespace);
+        supplied.forEach((layer, i) => {
+            const layerPath = join(workRoot, `supplied-${i}.yaml`);
+            writeFileSync(layerPath, yaml.dump(layer.values, { lineWidth: -1, noRefs: true }));
+            args.push("--values", layerPath);
+        });
+        const rendered = (options.runHelm ?? defaultRunHelm)(args);
+        // Lift the probe documents out.
+        const instances = [];
+        for (const doc of splitDocuments(rendered)) {
+            if (!doc.includes("chantValuesProbe:"))
+                continue;
+            let parsed;
+            try {
+                parsed = yaml.load(doc);
+            }
+            catch {
+                warnings.push("a probe document failed to parse as YAML — skipped");
+                continue;
+            }
+            if (!isPlainObject(parsed) || parsed.chantValuesProbe !== "v1")
+                continue;
+            const scope = scopeFromSource(doc);
+            if (scope === undefined) {
+                warnings.push("a probe document carried no usable # Source: header — skipped");
+                continue;
+            }
+            instances.push({
+                scope,
+                chartName: typeof parsed.chart === "string" ? parsed.chart : "",
+                values: isPlainObject(parsed.values) ? parsed.values : {},
+            });
+        }
+        instances.sort((a, b) => a.scope.length - b.scope.length || scopeKey(a.scope).localeCompare(scopeKey(b.scope)));
+        if (instances.length === 0) {
+            throw new Error(`coalesced-values probe: render of ${options.chartDir} produced no probe document — is the chart renderable?`);
+        }
+        const root = instances[0];
+        // Declared dependencies with no probe document were pruned by helm —
+        // disabled by a condition (evaluated here against the EXACT coalesced
+        // root values) or by tags. Only nodes whose parent rendered are
+        // reported; a disabled subtree's descendants are unreachable anyway.
+        const probedScopes = new Set(instances.map((i) => scopeKey(i.scope)));
+        const disabled = [];
+        for (const node of scopeNodes) {
+            if (node.scope.length === 0 || probedScopes.has(scopeKey(node.scope)))
+                continue;
+            if (!probedScopes.has(scopeKey(node.parentScope)))
+                continue;
+            let condition;
+            for (const rawPath of (node.condition ?? "").split(",")) {
+                const path = rawPath.trim();
+                if (path === "")
+                    continue;
+                const v = valueAtPath(root.values, path.split("."));
+                if (v === undefined)
+                    continue;
+                if (v === false)
+                    condition = path;
+                break;
+            }
+            disabled.push({ scope: node.scope, name: node.name, condition });
+        }
+        const defaultsCache = new Map();
+        const defaultsFor = (scope) => {
+            const key = scopeKey(scope);
+            if (!defaultsCache.has(key)) {
+                const node = scopeNodes.find((n) => scopeKey(n.scope) === key);
+                const loaded = node ? readYamlFile(join(node.dir, "values.yaml")) : undefined;
+                defaultsCache.set(key, isPlainObject(loaded) ? loaded : undefined);
+            }
+            return defaultsCache.get(key);
+        };
+        const attribution = { instances, supplied, defaultsFor };
+        const probe = {
+            instances,
+            disabled,
+            digest: coalescedValuesDigest(instances),
+            valueSources: computeValueSources(attribution),
+            deadAssignments: findDeadAssignments(attribution, disabled),
+            warnings,
+        };
+        probeRecords.push({ name: options.name ?? releaseName, chartDir: options.chartDir, probe });
+        return probe;
+    }
+    finally {
+        rmSync(workRoot, { recursive: true, force: true });
+    }
+}
+const probeRecords = [];
+/** Every probe recorded in this process, in invocation order. */
+export function getValuesProbeRecords() {
+    return probeRecords;
+}
+/** Record a probe computed elsewhere (the render path integration point). */
+export function recordValuesProbe(record) {
+    probeRecords.push(record);
+}
+/** Reset the record list (test isolation). */
+export function clearValuesProbeRecords() {
+    probeRecords.length = 0;
+}
+/**
+ * The values gap between the probe and an installed release: an installed
+ * release's `helm get values --all` omits subtrees for disabled
+ * dependencies; the probe's root document keeps them (epic findings 14, 15).
+ * On shared keys the two agree — this helper names the shared-key view for
+ * comparisons against a live release.
+ */
+export function rootCoalescedValues(probe) {
+    return probe.instances[0]?.values ?? {};
+}

package/dist/wrapper-chart.js

@@ -0,0 +1,95 @@
+/**
+ * Wrapper-chart materialization for the pinned install path (#1242, epic
+ * #1228 Phase 4).
+ *
+ * Turns a `RoutedRender` (#1239) into an installable helm chart on disk.
+ * The wrapper preserves the recorded bytes exactly:
+ *
+ * - CRD-group documents are written verbatim into the wrapper's `crds/`,
+ *   which is what keeps `helm uninstall` from deleting them — the A/B test
+ *   behind epic finding 4 showed a flat wrap converts uninstall from safe
+ *   to data-destroying.
+ * - Every other document (main and hook groups) is written verbatim into
+ *   `manifests/`, and each gets a one-line shim in `templates/` that reads
+ *   it back with `.Files.Get`. The shim exists because rendered output can
+ *   legitimately contain template-looking text — a ConfigMap carrying
+ *   alertmanager notification templates renders `{{ $labels }}` as literal
+ *   bytes — and a document placed directly in `templates/` would be run
+ *   through the template engine a second time, mangling or failing on
+ *   exactly those bytes. `.Files.Get` returns file content untemplated, so
+ *   what helm installs is what the render store recorded.
+ * - Hook documents go through the same shim; their `helm.sh/hook`
+ *   annotations are part of the recorded bytes, so helm registers and runs
+ *   them from the rendered output unchanged (epic finding 5).
+ *
+ * The wrapper inherits the source chart's name and version (epic
+ * Decisions), keeping `helm history` continuous across the pinned
+ * migration. A local chart path becomes its sanitized basename — helm
+ * requires a bare chart name — and a render recorded without a version
+ * falls back to `0.0.0`.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * A valid helm chart name from a chart reference that may be a local path
+ * (`./charts/web`) or a repo-qualified name. Takes the last path segment,
+ * lowercases it, and collapses anything outside `[a-z0-9-]` to `-` — helm
+ * chart names are DNS-label-shaped. Falls back to `pinned-chart` when
+ * nothing survives.
+ */
+export function wrapperChartName(chart) {
+    const base = chart.split("/").filter((s) => s.length > 0).pop() ?? "";
+    const sanitized = base
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return sanitized.length > 0 ? sanitized : "pinned-chart";
+}
+/** `doc-0007-my-deployment` — a stable, ordered, filesystem-safe stem for one routed document. */
+function fileStem(prefix, index, doc) {
+    const label = (doc.name ?? doc.kind ?? "document")
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40);
+    return `${prefix}-${String(index).padStart(4, "0")}${label ? `-${label}` : ""}`;
+}
+/**
+ * Write `routed` as an installable wrapper chart under `dir` (which must
+ * exist and should be empty). Document text is written byte-for-byte; the
+ * only authored files are `Chart.yaml` and the `.Files.Get` shims.
+ */
+export function materializeWrapperChart(routed, dir) {
+    const chartName = wrapperChartName(routed.chart);
+    const chartVersion = routed.chartVersion ?? "0.0.0";
+    writeFileSync(join(dir, "Chart.yaml"), [
+        "apiVersion: v2",
+        `name: ${chartName}`,
+        `version: ${chartVersion}`,
+        "description: chant pinned render wrapper (epic #1228) — installs recorded bytes; templates are .Files.Get shims and are never re-rendered",
+        "",
+    ].join("\n"));
+    const crdFiles = [];
+    if (routed.crds.length > 0) {
+        mkdirSync(join(dir, "crds"), { recursive: true });
+        routed.crds.forEach((doc, i) => {
+            const rel = `crds/${fileStem("crd", i, doc)}.yaml`;
+            writeFileSync(join(dir, rel), doc.text.endsWith("\n") ? doc.text : `${doc.text}\n`);
+            crdFiles.push(rel);
+        });
+    }
+    const manifestFiles = [];
+    const docs = [...routed.main, ...routed.hooks];
+    if (docs.length > 0) {
+        mkdirSync(join(dir, "manifests"), { recursive: true });
+        mkdirSync(join(dir, "templates"), { recursive: true });
+        docs.forEach((doc, i) => {
+            const stem = fileStem("doc", i, doc);
+            const rel = `manifests/${stem}.yaml`;
+            writeFileSync(join(dir, rel), doc.text.endsWith("\n") ? doc.text : `${doc.text}\n`);
+            writeFileSync(join(dir, `templates/${stem}.yaml`), `{{ .Files.Get "${rel}" }}\n`);
+            manifestFiles.push(rel);
+        });
+    }
+    return { dir, chartName, chartVersion, crdFiles, manifestFiles, hookCount: routed.hooks.length };
+}