@intentius/chant-lexicon-helm 0.0.18 → 0.0.24

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "xxhash64",
   "artifacts": {
-    "manifest.json": "a843f902eae9b442",
+    "manifest.json": "2557e415419da552",
     "meta.json": "b7aab243e162dfaf",
     "types/index.d.ts": "e8011da51963f058",
     "rules/no-hardcoded-image.ts": "c75aa9c33016c3b9",
@@ -28,9 +28,9 @@
     "rules/whm405.ts": "ec82442f9120e5e0",
     "rules/whm202.ts": "dbe1cbb3237be84f",
     "rules/whm501.ts": "e9a9f2b4e034a51f",
-    "skills/chant-helm-chart-patterns.md": "7a2163247f44bf6d",
-    "skills/chant-helm-chart-security-patterns.md": "a7b950513dac7d37",
-    "skills/chant-helm-create-chart.md": "d2cb222caa70736e"
+    "skills/chant-helm.md": "8ccf71feddc9536c",
+    "skills/chant-helm-patterns.md": "7a2163247f44bf6d",
+    "skills/chant-helm-security.md": "a7b950513dac7d37"
   },
-  "composite": "36daf1691f70425f"
+  "composite": "43682c36509928ac"
 }

package/dist/manifest.json

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

package/dist/skills/chant-helm.md

@@ -0,0 +1,447 @@
+---
+skill: chant-helm
+description: Build, validate, and deploy Helm charts from a chant project
+user-invocable: true
+---
+
+# Helm Chart Operational Playbook
+
+## How chant and Helm relate
+
+chant is a **synthesis compiler** — it compiles TypeScript source files into a complete Helm chart directory (Chart.yaml, values.yaml, templates/, etc.). `chant build` does not call the Helm CLI; synthesis is pure and deterministic. Your job as an agent is to bridge synthesis and deployment:
+
+- Use **chant** for: build, lint, diff (local chart comparison)
+- Use **helm** for: install, upgrade, rollback, test, dependency update
+
+The source of truth is the TypeScript in `src/`. The generated chart directory is an intermediate artifact — never edit it by hand.
+
+## Scaffolding a new project
+
+### Initialize with a template
+
+```bash
+chant init --lexicon helm                          # default: Deployment + Service chart
+```
+
+### Project structure after init
+
+```
+my-chart/
+  src/
+    chart.ts      ← Chart metadata, Values, K8s resources with Helm intrinsics
+  chant.json      ← project configuration
+  package.json
+```
+
+## Key concepts
+
+### Values proxy
+
+The `values` proxy creates `{{ .Values.x }}` template directives:
+
+```typescript
+import { values } from "@intentius/chant-lexicon-helm";
+
+// values.replicaCount → {{ .Values.replicaCount }}
+// values.image.repository → {{ .Values.image.repository }}
+```
+
+### Template functions
+
+```typescript
+import { include, printf, toYaml, quote, required, helmDefault } from "@intentius/chant-lexicon-helm";
+
+include("my-app.fullname")           // {{ include "my-app.fullname" . }}
+printf("%s:%s", values.image.repo, values.image.tag)  // {{ printf "%s:%s" ... }}
+toYaml(values.resources, 12)         // {{ toYaml .Values.resources | nindent 12 }}
+```
+
+### Conditional resources
+
+```typescript
+import { If, values } from "@intentius/chant-lexicon-helm";
+
+// Wrap an entire resource in {{- if .Values.ingress.enabled }}
+export const ingress = If(values.ingress.enabled, new Ingress({ ... }));
+```
+
+### Built-in objects
+
+```typescript
+import { Release, ChartRef } from "@intentius/chant-lexicon-helm";
+
+Release.Name       // {{ .Release.Name }}
+Release.Namespace  // {{ .Release.Namespace }}
+ChartRef.Version   // {{ .Chart.Version }}
+```
+
+## Build and validate workflow
+
+### Build the chart
+
+```bash
+chant build                              # synthesize TypeScript → dist/
+chant build --watch                      # rebuild on source changes
+chant build --output my-chart/           # write to a custom directory
+```
+
+`chant build` produces a complete Helm chart directory:
+- `dist/Chart.yaml` — chart metadata (name, version, apiVersion v2)
+- `dist/values.yaml` — default values extracted from `values` proxy usage
+- `dist/templates/*.yaml` — rendered K8s manifests with Go template directives
+- `dist/templates/_helpers.tpl` — named templates (fullname, labels, etc.)
+- `dist/templates/NOTES.txt` — post-install instructions
+
+### Lint and validate
+
+```bash
+# Lint the TypeScript (pre-synth rules)
+chant lint
+
+# Validate the generated chart (post-synth checks)
+chant check
+
+# Validate with helm CLI
+helm lint dist/
+helm template test dist/
+```
+
+### What each step catches
+
+| Step | Catches | When to run |
+|------|---------|-------------|
+| `chant lint` | Pre-synth: missing chart metadata, bare secrets in values, hardcoded images | Every edit |
+| `chant check` | Post-synth: unbalanced template braces, missing _helpers.tpl, deprecated APIs, security issues | After build |
+| `helm lint dist/` | Chart structure validation, values schema, template rendering errors | Before publish |
+| `helm template test dist/` | Full template rendering with default values — catches nil pointer panics in Go templates | Before publish |
+| `helm template test dist/ -f values-prod.yaml` | Template rendering with environment-specific overrides | Before deploy |
+
+## Common patterns
+
+### Deployment with parameterized image
+
+```typescript
+export const deployment = new Deployment({
+  metadata: {
+    name: include("my-app.fullname"),
+    labels: include("my-app.labels"),
+  },
+  spec: {
+    replicas: values.replicaCount,
+    template: {
+      spec: {
+        containers: [{
+          name: "my-app",
+          image: printf("%s:%s", values.image.repository, values.image.tag),
+          resources: toYaml(values.resources),
+        }],
+      },
+    },
+  },
+});
+```
+
+### Composites for common patterns
+
+```typescript
+import { HelmWebApp, HelmMicroservice, HelmDaemonSet, HelmWorker } from "@intentius/chant-lexicon-helm";
+
+// Quick scaffold: Deployment + Service + Ingress + HPA + ServiceAccount
+const result = HelmWebApp({ name: "my-app", port: 3000, replicas: 3 });
+
+// Full microservice: + PDB + ConfigMap + health probes + resource limits
+const msvc = HelmMicroservice({ name: "api", port: 8080 });
+
+// DaemonSet for node-level agents (logging, monitoring)
+const agent = HelmDaemonSet({ name: "log-agent", imageRepository: "fluent/fluent-bit" });
+
+// Worker for background processors (no Service, exec probes, queue config)
+const worker = HelmWorker({ name: "job-processor", replicas: 4 });
+```
+
+### Composites reference
+
+| Need | Composite | Resources |
+|------|-----------|-----------|
+| Stateless web app | **HelmWebApp** | Deployment + Service + optional Ingress + HPA + ServiceAccount |
+| Production microservice | **HelmMicroservice** | Deployment + Service + HPA + PDB + ConfigMap + probes + limits |
+| Stateful database/cache | **HelmStatefulService** | StatefulSet + headless Service + PVC + optional PDB |
+| Background workers | **HelmWorker** | Deployment + optional HPA (no Service, exec probes) |
+| Node-level agent | **HelmDaemonSet** | DaemonSet + ServiceAccount + RBAC |
+| Scheduled jobs | **HelmCronJob** | CronJob + ServiceAccount + RBAC |
+| One-shot batch jobs | **HelmBatchJob** | Job + ServiceAccount + optional RBAC |
+| App with Prometheus monitoring | **HelmMonitoredService** | Deployment + Service + ServiceMonitor + optional PrometheusRule |
+| TLS Ingress (cert-manager) | **HelmSecureIngress** | Ingress + optional Certificate |
+| External secrets (Vault, AWS SM) | **HelmExternalSecret** | ExternalSecret + SecretStore ref |
+| CRD lifecycle hooks | **HelmCRDLifecycle** | pre-install/upgrade Job for CRD apply |
+| Library chart (no templates) | **HelmLibrary** | Chart.yaml with `type: library` + _helpers.tpl |
+| Namespace with quotas | **HelmNamespaceEnv** | Namespace + ResourceQuota + LimitRange + NetworkPolicy |
+
+### Secret management with ExternalSecret
+
+```typescript
+import { HelmExternalSecret } from "@intentius/chant-lexicon-helm";
+
+const secrets = HelmExternalSecret({
+  name: "app-secrets",
+  secretStoreName: "vault",
+  data: {
+    DB_PASSWORD: "secret/data/db-password",
+    API_KEY: "secret/data/api-key",
+  },
+});
+```
+
+### Resource ordering
+
+```typescript
+import { withOrder, argoWave } from "@intentius/chant-lexicon-helm";
+
+// Helm hook ordering (lower weight = runs first)
+metadata: { annotations: { ...withOrder(-5) } }
+
+// Argo CD sync waves
+metadata: { annotations: { ...argoWave(2) } }
+```
+
+### CRD lifecycle management
+
+```typescript
+import { HelmCRDLifecycle } from "@intentius/chant-lexicon-helm";
+
+// Managed CRD lifecycle via Helm hooks (solves Helm's CRD limitation)
+const lifecycle = HelmCRDLifecycle({
+  name: "my-operator",
+  crdContent: crdYaml,
+});
+```
+
+## Lint rules
+
+| Rule | Description |
+|------|-------------|
+| WHM001 | Chart must have name, version, apiVersion |
+| WHM002 | Values should not contain bare secrets |
+| WHM003 | Container images should use values references |
+| WHM101 | Chart.yaml has valid apiVersion (v2) |
+| WHM102 | values.schema.json present when Values used |
+| WHM103 | Go template syntax valid (balanced braces) |
+| WHM104 | NOTES.txt exists for application charts |
+| WHM105 | _helpers.tpl exists |
+| WHM201 | Resources have standard Helm labels |
+| WHM301 | At least one test for application charts |
+| WHM302 | Resource limits set |
+| WHM401 | Image uses :latest tag or no tag |
+| WHM402 | runAsNonRoot not set |
+| WHM403 | readOnlyRootFilesystem not set |
+| WHM404 | privileged: true detected |
+| WHM405 | Resource spec missing cpu/memory |
+| WHM406 | CRD lifecycle limitation |
+| WHM407 | Secret with inline data |
+| WHM501 | Unused values keys |
+| WHM502 | Deprecated K8s API versions |
+
+## OCI registry workflow
+
+Helm 3.8+ supports OCI registries as first-class chart repositories.
+
+```bash
+# Login to an OCI registry
+helm registry login ghcr.io -u <user>
+helm registry login <account>.dkr.ecr.<region>.amazonaws.com --username AWS --password $(aws ecr get-login-password)
+
+# Package the chart
+helm package dist/
+
+# Push to OCI registry
+helm push my-app-1.0.0.tgz oci://ghcr.io/my-org/charts
+helm push my-app-1.0.0.tgz oci://<account>.dkr.ecr.<region>.amazonaws.com/charts
+
+# Pull from OCI registry
+helm pull oci://ghcr.io/my-org/charts/my-app --version 1.0.0
+
+# Install directly from OCI
+helm install my-app oci://ghcr.io/my-org/charts/my-app --version 1.0.0
+```
+
+## Chart testing
+
+### helm test
+
+Helm tests are pods defined in `templates/tests/` with the `helm.sh/hook: test` annotation. They run after install/upgrade.
+
+```bash
+helm install my-app dist/
+helm test my-app                          # run test pods
+helm test my-app --logs                   # show test pod logs
+```
+
+### chart-testing (ct)
+
+The `ct` tool validates charts against a set of rules and optionally installs them in a Kind cluster.
+
+```bash
+# Lint all changed charts
+ct lint --charts dist/
+
+# Lint + install (requires a running cluster)
+ct install --charts dist/
+
+# CI-oriented: lint and install only changed charts
+ct lint-and-install --chart-dirs dist/
+```
+
+## Deploy lifecycle
+
+### Install a release
+
+```bash
+# Build the chart first
+chant build
+
+# Install with default values
+helm install my-app dist/
+
+# Install with overrides
+helm install my-app dist/ -f values-prod.yaml
+helm install my-app dist/ --set replicaCount=3 --set image.tag=v2.0.0
+
+# Install in a specific namespace (create if missing)
+helm install my-app dist/ -n production --create-namespace
+
+# Dry run (renders templates, validates against cluster)
+helm install my-app dist/ --dry-run
+```
+
+### Upgrade a release
+
+```bash
+# Upgrade with new chart
+chant build
+helm upgrade my-app dist/
+
+# Upgrade with value overrides
+helm upgrade my-app dist/ -f values-prod.yaml --set image.tag=v2.1.0
+
+# Atomic upgrade (auto-rollback on failure)
+helm upgrade my-app dist/ --atomic --timeout 5m
+
+# Install or upgrade (idempotent)
+helm upgrade --install my-app dist/ -f values-prod.yaml
+```
+
+### Rollback a release
+
+```bash
+# View release history
+helm history my-app
+
+# Rollback to previous revision
+helm rollback my-app
+
+# Rollback to a specific revision
+helm rollback my-app 3
+
+# Rollback with timeout
+helm rollback my-app 3 --timeout 5m
+```
+
+### Uninstall
+
+```bash
+helm uninstall my-app
+helm uninstall my-app --keep-history      # preserve history for rollback
+```
+
+## Troubleshooting
+
+### Common errors
+
+#### "apiVersion must be v2"
+Helm 3 requires `apiVersion: v2` in Chart.yaml. Update your Chart metadata.
+
+#### "unbalanced template braces"
+A Go template expression has mismatched `{{` / `}}`. Check your intrinsic usage.
+
+#### "hardcoded image tag"
+Use `printf("%s:%s", values.image.repository, values.image.tag)` instead of literal strings for container images.
+
+#### "UPGRADE FAILED: another operation is in progress"
+A previous install/upgrade was interrupted. Fix with:
+```bash
+helm history my-app
+helm rollback my-app <last-good-revision>
+```
+If stuck in `pending-install`, uninstall and reinstall:
+```bash
+helm uninstall my-app
+helm install my-app dist/
+```
+
+#### "rendered manifests contain a resource that already exists"
+Another release or kubectl owns the resource. Add `--force` or use `kubectl annotate` to transfer ownership:
+```bash
+kubectl annotate <resource> meta.helm.sh/release-name=my-app --overwrite
+kubectl annotate <resource> meta.helm.sh/release-namespace=default --overwrite
+kubectl label <resource> app.kubernetes.io/managed-by=Helm --overwrite
+```
+
+### Troubleshooting decision tree
+
+```
+helm install/upgrade failed?
+├─ "INSTALLATION FAILED: cannot re-use a name"
+│  └─ Release name in use → helm uninstall <name> or pick a new name
+├─ "UPGRADE FAILED: another operation is in progress"
+│  └─ Stuck release → helm rollback to last good revision
+├─ "rendered manifests contain a resource that already exists"
+│  └─ Ownership conflict → annotate existing resources with Helm metadata
+├─ Template rendering error
+│  ├─ "nil pointer evaluating interface"
+│  │  └─ Missing values → add defaults in values.yaml or guard with {{- if }}
+│  ├─ "function X not defined"
+│  │  └─ Missing _helpers.tpl → ensure include() references defined templates
+│  └─ "wrong type for value"
+│     └─ Type mismatch → check values.yaml types match template expectations
+├─ Pods not starting after deploy
+│  └─ See kubectl debugging: kubectl get pods, describe, logs --previous
+└─ Helm test failing
+   ├─ Test pod CrashLoopBackOff → check test script, endpoint connectivity
+   └─ Timeout → increase --timeout or fix service readiness
+```
+
+## Quick reference
+
+```bash
+# Build
+chant build                               # synthesize chart
+chant lint                                # pre-synth lint
+chant check                              # post-synth checks
+
+# Validate
+helm lint dist/                           # chart structure
+helm template test dist/                  # render templates
+helm template test dist/ -f values-prod.yaml  # render with overrides
+
+# Deploy
+helm install my-app dist/                 # install
+helm upgrade my-app dist/                 # upgrade
+helm upgrade --install my-app dist/       # idempotent install/upgrade
+helm rollback my-app                      # rollback to previous
+
+# Inspect
+helm list                                 # list releases
+helm history my-app                       # release history
+helm get values my-app                    # current values
+helm get manifest my-app                  # current manifests
+
+# Test
+helm test my-app --logs                   # run chart tests
+
+# Package and publish
+helm package dist/                        # create .tgz
+helm push my-app-1.0.0.tgz oci://registry/charts  # push to OCI
+
+# Cleanup
+helm uninstall my-app                     # remove release
+```

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@intentius/chant-lexicon-helm",
-  "version": "0.0.18",
+  "version": "0.0.24",
+  "description": "Helm chart lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
+  "homepage": "https://intentius.io/chant",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/intentius/chant.git",
+    "directory": "lexicons/helm"
+  },
+  "bugs": {
+    "url": "https://github.com/intentius/chant/issues"
+  },
+  "keywords": [
+    "infrastructure-as-code",
+    "iac",
+    "typescript",
+    "helm",
+    "kubernetes",
+    "chant"
+  ],
   "type": "module",
   "files": [
     "src/",
@@ -25,8 +43,8 @@
     "prepack": "bun run generate && bun run bundle && bun run validate"
   },
   "dependencies": {
-    "@intentius/chant": "0.0.18",
-    "@intentius/chant-lexicon-k8s": "0.0.18"
+    "@intentius/chant": "0.0.22",
+    "@intentius/chant-lexicon-k8s": "0.0.22"
   },
   "devDependencies": {
     "typescript": "^5.9.3"

package/src/codegen/docs.test.ts

@@ -0,0 +1,14 @@
+import { describe, test, expect } from "bun:test";
+
+describe("Helm docs generation", () => {
+  test("docs module is importable", async () => {
+    const mod = await import("./docs");
+    expect(mod.generateDocs).toBeFunction();
+  });
+
+  test("generateDocs function signature accepts options", async () => {
+    const mod = await import("./docs");
+    // Verify the function exists and has the expected shape
+    expect(typeof mod.generateDocs).toBe("function");
+  });
+});

package/src/codegen/generate.test.ts

@@ -0,0 +1,71 @@
+import { describe, test, expect } from "bun:test";
+import { generate } from "./generate";
+
+describe("Helm generate pipeline", () => {
+  test("generate module is importable", async () => {
+    const mod = await import("./generate");
+    expect(mod.generate).toBeFunction();
+    expect(mod.writeGeneratedFiles).toBeFunction();
+  });
+
+  test("generates lexicon JSON, types, and index", async () => {
+    const result = await generate();
+    expect(result.lexiconJSON).toBeTruthy();
+    expect(result.typesDTS).toBeTruthy();
+    expect(result.indexTS).toBeTruthy();
+  });
+
+  test("lexicon JSON contains known resource types", async () => {
+    const result = await generate();
+    const registry = JSON.parse(result.lexiconJSON);
+    expect(registry.Chart).toBeDefined();
+    expect(registry.Chart.resourceType).toBe("Helm::Chart");
+    expect(registry.Chart.kind).toBe("resource");
+    expect(registry.Values).toBeDefined();
+    expect(registry.HelmHook).toBeDefined();
+    expect(registry.HelmHook.kind).toBe("property");
+  });
+
+  test("types DTS contains class declarations", async () => {
+    const result = await generate();
+    expect(result.typesDTS).toContain("export interface ChartProps");
+    expect(result.typesDTS).toContain("export declare const Chart");
+    expect(result.typesDTS).toContain("export interface ValuesProps");
+    expect(result.typesDTS).toContain("export declare const Values");
+  });
+
+  test("runtime index contains createResource calls", async () => {
+    const result = await generate();
+    expect(result.indexTS).toContain('createResource("Helm::Chart"');
+    expect(result.indexTS).toContain('createResource("Helm::Values"');
+    expect(result.indexTS).toContain('createProperty("Helm::Hook"');
+  });
+
+  test("resource and property counts are correct", async () => {
+    const result = await generate();
+    expect(result.resources).toBeGreaterThan(0);
+    expect(result.properties).toBeGreaterThan(0);
+    expect(result.enums).toBe(0);
+    expect(result.warnings).toHaveLength(0);
+  });
+
+  test("lexicon JSON contains all Helm types", async () => {
+    const result = await generate();
+    const registry = JSON.parse(result.lexiconJSON);
+    expect(registry.HelmTest).toBeDefined();
+    expect(registry.HelmNotes).toBeDefined();
+    expect(registry.HelmDependency).toBeDefined();
+    expect(registry.HelmMaintainer).toBeDefined();
+    expect(registry.HelmCRD).toBeDefined();
+  });
+
+  test("Chart props include required fields", async () => {
+    const result = await generate();
+    const registry = JSON.parse(result.lexiconJSON);
+    const chartProps = registry.Chart.props;
+    expect(chartProps.apiVersion).toBeDefined();
+    expect(chartProps.apiVersion.required).toBe(true);
+    expect(chartProps.name.required).toBe(true);
+    expect(chartProps.version.required).toBe(true);
+  });
+});

package/src/codegen/package.test.ts

@@ -0,0 +1,36 @@
+import { describe, test, expect } from "bun:test";
+import { packageLexicon } from "./package";
+
+describe("Helm package pipeline", () => {
+  test("packageLexicon is importable", async () => {
+    const mod = await import("./package");
+    expect(mod.packageLexicon).toBeFunction();
+  });
+
+  test("packageLexicon returns a valid result", async () => {
+    const result = await packageLexicon({ verbose: false });
+    expect(result).toBeDefined();
+    expect(result.spec).toBeDefined();
+    expect(result.spec.manifest).toBeDefined();
+    expect(result.spec.manifest.name).toBe("helm");
+    expect(result.spec.manifest.namespace).toBe("Helm");
+    expect(result.spec.manifest.chantVersion).toBeTruthy();
+  });
+
+  test("manifest contains intrinsics", async () => {
+    const result = await packageLexicon();
+    const intrinsics = result.spec.manifest.intrinsics;
+    expect(intrinsics).toBeDefined();
+    expect(intrinsics!.length).toBeGreaterThan(0);
+    const names = intrinsics!.map((i: { name: string }) => i.name);
+    expect(names).toContain("values");
+    expect(names).toContain("Release");
+    expect(names).toContain("include");
+  });
+
+  test("stats have resource and property counts", async () => {
+    const result = await packageLexicon();
+    expect(result.stats.resources).toBeGreaterThan(0);
+    expect(result.stats.properties).toBeGreaterThan(0);
+  });
+});