@intentius/chant-lexicon-helm 0.0.16

package/src/skills/chart-patterns.md

@@ -0,0 +1,229 @@
+---
+skill: chant-helm-patterns
+description: Common Helm chart patterns and best practices using chant
+user-invocable: true
+---
+
+# Common Helm Chart Patterns
+
+## Standard Chart Layout
+
+A chant Helm project compiles TypeScript into the standard Helm directory structure:
+
+```
+my-chart/
+  Chart.yaml          ← chart metadata (name, version, apiVersion: v2)
+  values.yaml         ← default configuration values
+  templates/
+    deployment.yaml
+    service.yaml
+    ingress.yaml
+    _helpers.tpl      ← named templates (fullname, labels, etc.)
+    NOTES.txt         ← post-install instructions
+  charts/             ← subcharts (dependencies)
+```
+
+The source of truth is `src/`. Never edit generated files in `templates/` by hand.
+
+## Parameterization via Values Proxy
+
+The `values` proxy turns property access into `{{ .Values.x }}` template directives:
+
+```typescript
+import { values } from "@intentius/chant-lexicon-helm";
+
+// Simple access
+values.replicaCount          // → {{ .Values.replicaCount }}
+
+// Nested access
+values.image.repository      // → {{ .Values.image.repository }}
+values.image.tag             // → {{ .Values.image.tag }}
+
+// Use in resource definitions
+export const deployment = new Deployment({
+  spec: {
+    replicas: values.replicaCount,
+    template: {
+      spec: {
+        containers: [{
+          name: "app",
+          image: printf("%s:%s", values.image.repository, values.image.tag),
+        }],
+      },
+    },
+  },
+});
+```
+
+Default values are set in the `Values` resource, which becomes `values.yaml`.
+
+## Conditional Resources with If()
+
+Wrap resources in `If()` to gate them on a values flag:
+
+```typescript
+import { If, values } from "@intentius/chant-lexicon-helm";
+import { Ingress } from "@intentius/chant-lexicon-k8s";
+
+// Only rendered when .Values.ingress.enabled is true
+export const ingress = If(values.ingress.enabled, new Ingress({
+  metadata: { name: include("my-app.fullname") },
+  spec: {
+    rules: [{ host: values.ingress.hostname }],
+  },
+}));
+```
+
+`If()` wraps the entire template output in `{{- if .Values.ingress.enabled }}...{{- end }}`.
+
+## Helper Templates with include()
+
+Reference named templates from `_helpers.tpl`:
+
+```typescript
+import { include } from "@intentius/chant-lexicon-helm";
+
+export const deployment = new Deployment({
+  metadata: {
+    name: include("my-app.fullname"),
+    labels: include("my-app.labels"),
+  },
+  spec: {
+    selector: {
+      matchLabels: include("my-app.selectorLabels"),
+    },
+  },
+});
+```
+
+The composites (`HelmWebApp`, `HelmMicroservice`, etc.) generate `_helpers.tpl` automatically with standard named templates for fullname, labels, and selector labels.
+
+## Dependency Management with HelmDependency
+
+Declare subchart dependencies that go into `Chart.yaml`:
+
+```typescript
+import { HelmDependency } from "@intentius/chant-lexicon-helm";
+
+export const redisDep = HelmDependency({
+  name: "redis",
+  version: "17.x",
+  repository: "https://charts.bitnami.com/bitnami",
+  condition: "redis.enabled",
+});
+
+export const postgresqlDep = HelmDependency({
+  name: "postgresql",
+  version: "12.x",
+  repository: "https://charts.bitnami.com/bitnami",
+  condition: "postgresql.enabled",
+});
+```
+
+After building, run `helm dependency update` to fetch the subcharts.
+
+## Multi-Environment Configuration
+
+Use separate values files per environment and compose them at deploy time:
+
+```typescript
+// src/infra.ts — base chart with parameterized defaults
+export const app = HelmWebApp({
+  name: "my-app",
+  port: 3000,
+  replicas: 1,              // default for dev
+  imageTag: "latest",       // overridden per env
+});
+```
+
+```bash
+# Deploy with environment-specific overrides
+helm install my-app . -f values.yaml -f values-staging.yaml
+helm install my-app . -f values.yaml -f values-production.yaml
+```
+
+Structure values files as overlays: `values.yaml` (defaults) -> `values-staging.yaml` (overrides) -> `values-production.yaml` (overrides). Later files win.
+
+## Library Charts with HelmLibrary
+
+Create reusable chart libraries that other charts can import:
+
+```typescript
+import { HelmLibrary } from "@intentius/chant-lexicon-helm";
+
+export const library = HelmLibrary({
+  name: "common-templates",
+  version: "1.0.0",
+  templates: {
+    "common.labels": labelsTemplate,
+    "common.annotations": annotationsTemplate,
+    "common.fullname": fullnameTemplate,
+  },
+});
+```
+
+Library charts produce no templates of their own. They are included as dependencies by application charts, which use `include()` to reference the shared named templates.
+
+## Testing Patterns with HelmTest
+
+Add Helm test pods that run on `helm test`:
+
+```typescript
+import { HelmTest } from "@intentius/chant-lexicon-helm";
+
+export const connectivityTest = HelmTest({
+  name: "test-connection",
+  image: "busybox:1.36",
+  command: ["wget", "--spider", "http://my-app:3000/healthz"],
+});
+```
+
+This generates a pod in `templates/tests/` with the `helm.sh/hook: test` annotation. Run tests after install:
+
+```bash
+helm install my-app .
+helm test my-app
+```
+
+**Lint rule WHM301** fires when an application chart has no test resources.
+
+## Composites Quick Reference
+
+| Composite           | Resources created                                           |
+|---------------------|-------------------------------------------------------------|
+| `HelmWebApp`        | Chart, Values, Deployment, Service, Ingress?, HPA?, SA?     |
+| `HelmMicroservice`  | Chart, Values, Deployment, Service, SA, ConfigMap?, PDB?, HPA?, Ingress? |
+| `HelmWorker`        | Chart, Values, Deployment, SA, HPA?, PDB?                   |
+| `HelmCronJob`       | Chart, Values, CronJob                                      |
+| `HelmStatefulSet`   | Chart, Values, StatefulSet, Service                          |
+| `HelmDaemonSet`     | Chart, Values, DaemonSet, SA?                                |
+| `HelmLibrary`       | Chart (type: library), named templates                       |
+
+All composites accept optional `podSecurityContext`, `securityContext`, `nodeSelector`, `tolerations`, `affinity`, and `strategy` fields.
+
+## Built-in Objects
+
+Access Helm's built-in objects in templates:
+
+```typescript
+import { Release, ChartRef, Capabilities } from "@intentius/chant-lexicon-helm";
+
+Release.Name          // {{ .Release.Name }}
+Release.Namespace     // {{ .Release.Namespace }}
+Release.IsUpgrade     // {{ .Release.IsUpgrade }}
+ChartRef.Name         // {{ .Chart.Name }}
+ChartRef.Version      // {{ .Chart.Version }}
+```
+
+## 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", Release.Name, "worker")       // {{ printf "%s-%s" .Release.Name "worker" }}
+toYaml(values.resources, 12)                  // {{ toYaml .Values.resources | nindent 12 }}
+quote(values.annotations)                     // {{ quote .Values.annotations }}
+required("image.tag is required", values.image.tag)  // {{ required "..." .Values.image.tag }}
+helmDefault(values.replicas, 1)               // {{ default 1 .Values.replicas }}
+```

package/src/skills/chart-security-patterns.md

@@ -0,0 +1,192 @@
+---
+skill: chant-helm-security
+description: Security best practices for Helm charts built with chant
+user-invocable: true
+---
+
+# Helm Chart Security Patterns
+
+## Pod Security Context
+
+Always set pod-level security constraints. The `podSecurityContext` field applies to all containers in the pod.
+
+```typescript
+import { HelmWebApp } from "@intentius/chant-lexicon-helm";
+
+const app = HelmWebApp({
+  name: "secure-app",
+  port: 3000,
+  podSecurityContext: {
+    runAsNonRoot: true,
+    runAsUser: 1000,
+    runAsGroup: 1000,
+    fsGroup: 1000,
+    seccompProfile: { type: "RuntimeDefault" },
+  },
+});
+```
+
+**Lint rule WHM402** fires when `runAsNonRoot` is not set on any pod spec.
+
+## Container Security Context
+
+Set per-container restrictions to minimize attack surface:
+
+```typescript
+const app = HelmWebApp({
+  name: "hardened-app",
+  port: 8080,
+  securityContext: {
+    readOnlyRootFilesystem: true,
+    allowPrivilegeEscalation: false,
+    capabilities: { drop: ["ALL"] },
+    runAsUser: 1000,
+  },
+});
+```
+
+- **WHM403**: `readOnlyRootFilesystem` not set
+- **WHM404**: `privileged: true` detected
+
+If the application needs to write temporary files, mount a writable `emptyDir` volume at the specific path rather than disabling `readOnlyRootFilesystem`.
+
+## Image Tagging
+
+Never use `:latest` or omit the tag entirely. Use semver tags or digests.
+
+```typescript
+// Bad — WHM401 fires
+HelmWebApp({ name: "app", imageTag: "latest", port: 3000 });
+
+// Good — pinned semver
+HelmWebApp({ name: "app", imageTag: "v2.4.1", port: 3000 });
+
+// Best — pinned digest
+HelmWebApp({ name: "app", imageTag: "sha256:abc123...", port: 3000 });
+```
+
+**Lint rule WHM401** fires when the image uses `:latest` or has no tag at all.
+
+## Secret Management
+
+Never inline secrets in `values.yaml`. Use External Secrets Operator or Sealed Secrets.
+
+```typescript
+import { HelmExternalSecret } from "@intentius/chant-lexicon-helm";
+
+// External Secrets Operator — fetches secrets from a remote store at runtime
+const secrets = HelmExternalSecret({
+  name: "app-secrets",
+  secretStoreName: "aws-secretsmanager",
+  data: {
+    DB_PASSWORD: "prod/db-password",
+    API_KEY: "prod/api-key",
+  },
+});
+```
+
+**Lint rule WHM407** fires when a Secret resource contains inline `data` or `stringData` values. The fix is always to use an external secret provider.
+
+### What NOT to do
+
+```typescript
+// Bad — WHM407 fires, secret value is in source control
+new Secret({
+  metadata: { name: "db-creds" },
+  stringData: { password: "hunter2" },
+});
+```
+
+## RBAC and ServiceAccount
+
+Every workload should run under a dedicated ServiceAccount with minimal RBAC:
+
+```typescript
+const app = HelmMicroservice({
+  name: "payment-api",
+  port: 8080,
+  serviceAccount: true, // creates a dedicated SA
+});
+```
+
+When the workload needs API access, bind only the required verbs and resources:
+
+```typescript
+import { Role, RoleBinding } from "@intentius/chant-lexicon-k8s";
+
+export const role = new Role({
+  metadata: { name: include("payment-api.fullname") },
+  rules: [{
+    apiGroups: [""],
+    resources: ["configmaps"],
+    verbs: ["get", "watch"],
+  }],
+});
+```
+
+Avoid `ClusterRole` with wildcard resources or verbs. Prefer namespace-scoped `Role` bindings.
+
+## Network Policies
+
+Restrict pod-to-pod traffic to only what is required:
+
+```typescript
+import { NetworkPolicy } from "@intentius/chant-lexicon-k8s";
+
+export const netpol = new NetworkPolicy({
+  metadata: { name: "allow-frontend-to-api" },
+  spec: {
+    podSelector: { matchLabels: { app: "payment-api" } },
+    policyTypes: ["Ingress"],
+    ingress: [{
+      from: [{ podSelector: { matchLabels: { app: "frontend" } } }],
+      ports: [{ protocol: "TCP", port: 8080 }],
+    }],
+  },
+});
+```
+
+Start with a default-deny policy per namespace, then add allow rules for known traffic patterns.
+
+## Resource Limits and Requests
+
+Always set both requests and limits. Without them, a single pod can starve others.
+
+```typescript
+const app = HelmMicroservice({
+  name: "api",
+  port: 8080,
+  // HelmMicroservice sets sensible defaults:
+  //   requests: { cpu: "250m", memory: "128Mi" }
+  //   limits:   { cpu: "500m", memory: "256Mi" }
+});
+```
+
+**Lint rule WHM405** fires when a container spec is missing `cpu` or `memory` in resources. **WHM302** fires when resource limits are not set at all.
+
+## Security Lint Rules Reference
+
+| Rule   | What it checks                              | Severity |
+|--------|---------------------------------------------|----------|
+| WHM401 | Image uses `:latest` tag or no tag          | Warning  |
+| WHM402 | `runAsNonRoot` not set on pod               | Warning  |
+| WHM403 | `readOnlyRootFilesystem` not set            | Warning  |
+| WHM404 | `privileged: true` on a container           | Error    |
+| WHM405 | Missing cpu/memory in resource spec         | Warning  |
+| WHM406 | CRD lifecycle limitation (no auto-upgrade)  | Info     |
+| WHM407 | Secret with inline data in source           | Error    |
+
+## Checklist
+
+When reviewing or building a Helm chart, verify:
+
+1. Pod runs as non-root with a numeric UID (`runAsNonRoot: true`, `runAsUser: 1000`)
+2. Containers drop all capabilities (`capabilities: { drop: ["ALL"] }`)
+3. Root filesystem is read-only (`readOnlyRootFilesystem: true`)
+4. Privilege escalation is blocked (`allowPrivilegeEscalation: false`)
+5. Images use pinned semver or digest tags, never `:latest`
+6. Secrets come from an external provider, never inline
+7. Each workload has a dedicated ServiceAccount
+8. RBAC is namespace-scoped with minimal verbs
+9. Network policies restrict ingress/egress to known peers
+10. CPU and memory requests and limits are set on every container

package/src/skills/create-chart.md

@@ -0,0 +1,211 @@
+---
+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-only** tool — it compiles TypeScript source files into a complete Helm chart directory (Chart.yaml, values.yaml, templates/, etc.). chant does NOT call Helm CLI. Your job as an agent is to bridge the two:
+
+- 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
+
+```bash
+# Build the chart
+chant build
+
+# 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/
+```
+
+## 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 });
+```
+
+### 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 |
+
+## Troubleshooting
+
+### "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.

package/src/validate-cli.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env bun
+/**
+ * CLI entry point for Helm lexicon validation.
+ */
+
+import { validate } from "./validate";
+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/src/validate.test.ts

@@ -0,0 +1,37 @@
+import { describe, test, expect } from "bun:test";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { validate } from "./validate";
+
+const basePath = dirname(dirname(fileURLToPath(import.meta.url)));
+const generatedDir = join(basePath, "src", "generated");
+const hasGenerated = existsSync(join(generatedDir, "lexicon-helm.json"));
+
+describe("validate", () => {
+  test("runs validation checks on current artifacts", async () => {
+    const result = await validate({ basePath });
+    expect(result.checks.length).toBeGreaterThan(0);
+  });
+
+  test.skipIf(!hasGenerated)("checks lexicon JSON exists and parses", async () => {
+    const result = await validate({ basePath });
+    const jsonCheck = result.checks.find((c) => c.name === "lexicon-json-exists");
+    expect(jsonCheck).toBeDefined();
+    expect(jsonCheck?.ok).toBe(true);
+  });
+
+  test.skipIf(!hasGenerated)("checks types exist", async () => {
+    const result = await validate({ basePath });
+    const typesCheck = result.checks.find((c) => c.name === "types-exist");
+    expect(typesCheck).toBeDefined();
+    expect(typesCheck?.ok).toBe(true);
+  });
+
+  test.skipIf(!hasGenerated)("checks required names are present", async () => {
+    const result = await validate({ basePath });
+    const requiredCheck = result.checks.find((c) => c.name === "required-names");
+    expect(requiredCheck).toBeDefined();
+    expect(requiredCheck?.ok).toBe(true);
+  });
+});