@intentius/chant-lexicon-helm 0.1.8 → 0.1.10

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "d4a9a8168563da87916d1ff56334f061b9e7f573dd37a4b34714863a8570df1e",
+    "manifest.json": "ef5f7e294c0c8b6ca190fe59db119c9a09a62a7707c2b1aa70de6897f7c0fc0a",
     "meta.json": "14243c5730a07c6a6edc35ddd351438547d58df5cf345f2233a355b0c7611ccc",
     "types/index.d.ts": "5377696ca8698cd2999e4680feb8e8e4b54a7b49fb603a87b2f27356114d1794",
     "rules/chart-metadata.ts": "8f3377e893d5e2828460b7fe5924fca098334245a9a2fdb90f6b67e490eaf091",
@@ -34,5 +34,5 @@
     "skills/chant-helm-patterns.md": "9e79e6a46391da46709d8aa57e2825a7cd9eb981cd923f02ad60836c49b2561e",
     "skills/chant-helm-security.md": "bfc367eabceed2e84f1cf94501b407df78aeed963cec104f24a321d0962063c9"
   },
-  "composite": "ca5dd2d974996391ad2e74466d0b3e8d2c879212cbf72b56ebe1499d6bb7d897"
+  "composite": "794ebe6ec1f86321a5a64cecbd8e8c0fcaa64dd4cb85d7c93562eaff8cd64cf7"
 }

package/dist/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-helm",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Helm chart lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/codegen/docs.ts

@@ -479,6 +479,6 @@ When you scaffold a new project with \`chant init --lexicon helm\`, the skill is
   writeDocsSite(config, result);
 
   if (opts?.verbose) {
-    console.error(`Generated ${result.pages.length} documentation pages`);
+    console.error(`Generated ${result.pages.size} documentation pages`);
   }
 }

package/src/composites/helm-monitored-service.ts

@@ -228,7 +228,7 @@ export const HelmMonitoredService = Composite<HelmMonitoredServiceProps>((props)
           interval: values.monitoring.scrapeInterval,
         }],
       },
-    }) as Record<string, unknown>,
+    }) as unknown as Record<string, unknown>,
     defs?.serviceMonitor,
   ));
 
@@ -267,7 +267,7 @@ export const HelmMonitoredService = Composite<HelmMonitoredServiceProps>((props)
             rules: toYaml(values.alerting.rules),
           }],
         },
-      }) as Record<string, unknown>,
+      }) as unknown as Record<string, unknown>,
       defs?.prometheusRule,
     ));
   }

package/src/composites/helm-namespace-env.ts

@@ -134,7 +134,7 @@ export const HelmNamespaceEnv = Composite<HelmNamespaceEnvProps>((props) => {
         spec: {
           hard: toYaml(values.resourceQuota.hard),
         },
-      }) as Record<string, unknown>,
+      }) as unknown as Record<string, unknown>,
       defs?.resourceQuota,
     ));
   }
@@ -155,7 +155,7 @@ export const HelmNamespaceEnv = Composite<HelmNamespaceEnvProps>((props) => {
             defaultRequest: toYaml(values.limitRange.defaultRequest),
           }],
         },
-      }) as Record<string, unknown>,
+      }) as unknown as Record<string, unknown>,
       defs?.limitRange,
     ));
   }
@@ -173,7 +173,7 @@ export const HelmNamespaceEnv = Composite<HelmNamespaceEnvProps>((props) => {
           podSelector: {},
           policyTypes: ["Ingress", "Egress"],
         },
-      }) as Record<string, unknown>,
+      }) as unknown as Record<string, unknown>,
       defs?.networkPolicy,
     ));
   }

package/src/composites/helm-secure-ingress.ts

@@ -96,7 +96,7 @@ export const HelmSecureIngress = Composite<HelmSecureIngressProps>((props) => {
           },
         }),
       },
-    }) as Record<string, unknown>,
+    }) as unknown as Record<string, unknown>,
     defs?.ingress,
   ));
 
@@ -117,7 +117,7 @@ export const HelmSecureIngress = Composite<HelmSecureIngressProps>((props) => {
         },
         dnsNames: values.ingress.hosts,
       },
-    }) as Record<string, unknown>,
+    }) as unknown as Record<string, unknown>,
     defs?.certificate,
   ));
 

package/src/index.ts

@@ -7,6 +7,10 @@ export { helmPlugin } from "./plugin";
 // Resources
 export { Chart, Values, ValuesOverride, HelmTest, HelmNotes, HelmHook, HelmDependency, HelmMaintainer, HelmCRD } from "./resources";
 
+// HelmRender — render an upstream chart at chant build time
+export { HelmRender } from "./render";
+export type { HelmRenderProps } from "./render";
+
 // Intrinsics
 export {
   HelmTpl,

package/src/intrinsics.ts

@@ -308,7 +308,9 @@ export function quote(val: HelmTpl): HelmTpl {
  * `printf("%s:%s", values.image.repository, values.image.tag)`
  * → `{{ printf "%s:%s" .Values.image.repository .Values.image.tag }}`
  */
-export function printf(fmt: string, ...args: HelmTpl[]): HelmTpl {
+export function printf(fmt: string, ...args: (HelmTpl | string)[]): HelmTpl {
+  // extractExpr already accepts both HelmTpl and string; widening here is
+  // purely additive (existing callers passing HelmTpl[] keep working).
   const argExprs = args.map(extractExpr).join(" ");
   return new HelmTpl(`{{ printf "${fmt}" ${argExprs} }}`);
 }

package/src/render.test.ts

@@ -0,0 +1,173 @@
+import { describe, test, expect, beforeAll } from "vitest";
+import { mkdirSync, writeFileSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { tmpdir } from "node:os";
+
+import { HelmRender } from "./render";
+
+const FIXTURE_DIR = join(tmpdir(), "chant-helm-render-fixture");
+const CHART_DIR = join(FIXTURE_DIR, "tiny-chart");
+const REPO_DIR = join(FIXTURE_DIR, "repo");
+
+/**
+ * Builds a tiny self-contained chart that emits one Deployment + one
+ * Service, packages it as a local chart repo, and serves it via file://.
+ * Avoids network access in tests.
+ */
+function maybeSetupFixture(): boolean {
+  // If helm isn't on PATH, the test will be skipped at the call site.
+  try {
+    execFileSync("helm", ["version"], { stdio: "ignore" });
+  } catch {
+    return false;
+  }
+
+  if (existsSync(FIXTURE_DIR)) {
+    rmSync(FIXTURE_DIR, { recursive: true, force: true });
+  }
+  mkdirSync(join(CHART_DIR, "templates"), { recursive: true });
+  mkdirSync(REPO_DIR, { recursive: true });
+
+  writeFileSync(
+    join(CHART_DIR, "Chart.yaml"),
+    `apiVersion: v2
+name: tiny-chart
+description: Minimal chart for chant-lexicon-helm HelmRender tests
+type: application
+version: 0.1.0
+appVersion: "1.0"
+`,
+  );
+
+  writeFileSync(
+    join(CHART_DIR, "values.yaml"),
+    `replicaCount: 1
+image:
+  repository: nginx
+  tag: "latest"
+service:
+  port: 80
+`,
+  );
+
+  writeFileSync(
+    join(CHART_DIR, "templates", "deployment.yaml"),
+    `apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ .Release.Name }}-tiny
+spec:
+  replicas: {{ .Values.replicaCount }}
+  selector:
+    matchLabels:
+      app: {{ .Release.Name }}
+  template:
+    metadata:
+      labels:
+        app: {{ .Release.Name }}
+    spec:
+      containers:
+      - name: app
+        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
+`,
+  );
+
+  writeFileSync(
+    join(CHART_DIR, "templates", "service.yaml"),
+    `apiVersion: v1
+kind: Service
+metadata:
+  name: {{ .Release.Name }}-tiny
+spec:
+  selector:
+    app: {{ .Release.Name }}
+  ports:
+  - port: {{ .Values.service.port }}
+`,
+  );
+
+  // Package the chart into a .tgz and create a repo index.yaml.
+  execFileSync("helm", ["package", CHART_DIR, "-d", REPO_DIR], { stdio: "ignore" });
+  execFileSync("helm", ["repo", "index", REPO_DIR], { stdio: "ignore" });
+  return true;
+}
+
+const fixtureAvailable = maybeSetupFixture();
+
+describe.skipIf(!fixtureAvailable)("HelmRender", () => {
+  beforeAll(() => {
+    // Ensure fixture is fresh for the suite.
+    expect(fixtureAvailable).toBe(true);
+  });
+
+  test("renders a local chart into K8s declarables (Deployment + Service)", () => {
+    const result = HelmRender({
+      name: "rel",
+      chart: CHART_DIR,
+      noCache: true,
+    });
+
+    // Composite returns its members under .members; iterate keys.
+    const members = result.members as Record<string, unknown>;
+    const keys = Object.keys(members);
+    expect(keys.length).toBeGreaterThanOrEqual(2);
+    const deployment = keys.find((k) => k.startsWith("Deployment_"));
+    const service = keys.find((k) => k.startsWith("Service_"));
+    expect(deployment).toBeDefined();
+    expect(service).toBeDefined();
+  });
+
+  test("createNamespace adds a Namespace declarable", () => {
+    const result = HelmRender({
+      name: "rel",
+      chart: CHART_DIR,
+      namespace: "myns",
+      createNamespace: true,
+      noCache: true,
+    });
+    const keys = Object.keys(result.members as Record<string, unknown>);
+    expect(keys).toContain("__namespace");
+  });
+
+  test("values overrides are applied (replicaCount: 3)", () => {
+    const result = HelmRender({
+      name: "rel",
+      chart: CHART_DIR,
+      values: { replicaCount: 3 },
+      noCache: true,
+    });
+    const members = result.members as Record<string, unknown>;
+    const deploymentKey = Object.keys(members).find((k) => k.startsWith("Deployment_"));
+    expect(deploymentKey).toBeDefined();
+    const dep = members[deploymentKey!] as {
+      props: { spec: { replicas: number } };
+    };
+    expect(dep.props.spec.replicas).toBe(3);
+  });
+
+  test("cache reuse: second render with same args skips helm CLI", () => {
+    // First, render with cache enabled.
+    const first = HelmRender({
+      name: "rel",
+      chart: CHART_DIR,
+    });
+    expect(Object.keys(first.members as Record<string, unknown>).length).toBeGreaterThanOrEqual(2);
+
+    // Now sabotage `helm` by pointing PATH at an empty dir — if cache is used,
+    // the second call should still succeed.
+    const emptyDir = join(tmpdir(), "chant-helm-render-empty-path");
+    if (!existsSync(emptyDir)) mkdirSync(emptyDir);
+    const origPath = process.env.PATH;
+    process.env.PATH = emptyDir;
+    try {
+      const second = HelmRender({
+        name: "rel",
+        chart: CHART_DIR,
+      });
+      expect(Object.keys(second.members as Record<string, unknown>).length).toBeGreaterThanOrEqual(2);
+    } finally {
+      process.env.PATH = origPath;
+    }
+  });
+});

package/src/render.ts

@@ -0,0 +1,198 @@
+/**
+ * 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 { homedir, 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 yaml from "js-yaml";
+
+export interface HelmRenderProps {
+  /** Logical name for the render (used in cache key + composite name). */
+  name: string;
+  /** Chart repo URL, e.g. https://charts.external-secrets.io */
+  repo: string;
+  /** Chart name, e.g. "external-secrets" */
+  chart: string;
+  /** Pinned chart version, e.g. "0.10.4" */
+  version: string;
+  /** Target namespace passed to `helm template --namespace`. */
+  namespace?: string;
+  /** Also emit a Namespace manifest. Default: false. */
+  createNamespace?: boolean;
+  /** Helm values overrides (written to a values.yaml then passed via -f). */
+  values?: Record<string, unknown>;
+  /**
+   * Skip the on-disk cache. Default: false. Tests pass `true` to force a
+   * fresh render.
+   */
+  noCache?: boolean;
+}
+
+interface RenderedDoc {
+  apiVersion?: string;
+  kind?: string;
+  metadata?: { name?: string; namespace?: string; [k: string]: unknown };
+  [k: string]: unknown;
+}
+
+const CACHE_ROOT = join(homedir(), ".chant", "helm-renders");
+
+function cacheKey(props: HelmRenderProps): string {
+  const stable = JSON.stringify({
+    repo: props.repo,
+    chart: props.chart,
+    version: props.version,
+    namespace: props.namespace ?? null,
+    values: props.values ?? null,
+  });
+  return createHash("sha256").update(stable).digest("hex").slice(0, 16);
+}
+
+function renderViaHelm(props: HelmRenderProps): string {
+  // Write values overrides to a tempfile if any.
+  let valuesArgs: string[] = [];
+  if (props.values && Object.keys(props.values).length > 0) {
+    const valuesPath = join(tmpdir(), `chant-helm-values-${cacheKey(props)}.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: string[] = [];
+  if (props.repo) {
+    fetchArgs.push("--repo", props.repo);
+    if (props.version) fetchArgs.push("--version", props.version);
+  }
+
+  const args = [
+    "template",
+    props.name,
+    props.chart,
+    ...fetchArgs,
+    ...(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 as { stderr: unknown }).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: HelmRenderProps): string {
+  if (props.noCache) {
+    return renderViaHelm(props);
+  }
+  const cacheDir = join(CACHE_ROOT, cacheKey(props));
+  const cachePath = join(cacheDir, "manifests.yaml");
+  if (existsSync(cachePath)) {
+    return readFileSync(cachePath, "utf8");
+  }
+  const out = renderViaHelm(props);
+  try {
+    mkdirSync(cacheDir, { recursive: true });
+    writeFileSync(cachePath, out);
+  } catch {
+    // Cache write failure is non-fatal — the render is still in memory.
+  }
+  return out;
+}
+
+function parseMultiDoc(text: string): RenderedDoc[] {
+  const docs = yaml.loadAll(text);
+  return docs
+    .filter((d): d is RenderedDoc => 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: string): string {
+  return input.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+
+export const HelmRender = Composite<HelmRenderProps>((props) => {
+  const yamlText = loadOrRender(props);
+  const docs = parseMultiDoc(yamlText);
+
+  const out: Record<string, InstanceType<typeof Deployment>> = {};
+
+  if (props.createNamespace && props.namespace) {
+    out["__namespace"] = new Deployment({
+      apiVersion: "v1",
+      kind: "Namespace",
+      metadata: { name: props.namespace },
+    } as Record<string, unknown>);
+  }
+
+  const usedKeys = new Set<string>();
+  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 as Record<string, unknown>);
+  }
+
+  return out;
+}, "HelmRender");

package/src/serializer.ts

@@ -111,7 +111,7 @@ function emitHelmYAML(value: unknown, indent: number, valuesContext: boolean = f
 
   // Detect HelmTpl / Intrinsic objects via INTRINSIC_MARKER before string check
   if (typeof value === "object" && value !== null && INTRINSIC_MARKER in value) {
-    const tplObj = value as { toJSON(): unknown };
+    const tplObj = value as unknown as { toJSON(): unknown };
     if (valuesContext) {
       // In values.yaml context: emit empty placeholder — actual value comes from override files
       return "''";