@intentius/chant-lexicon-helm 0.0.16

package/dist/skills/chant-helm-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/dist/types/index.d.ts

@@ -0,0 +1,132 @@
+// Auto-generated Helm lexicon type declarations
+// Do not edit manually
+
+/** Minimal Declarable interface for generated types. */
+interface Declarable { [key: string]: unknown; }
+
+/** Chart.yaml metadata — defines the chart identity, version, and type. */
+export interface ChartProps {
+  /** Chart API version (v2) */
+  apiVersion: string;
+  /** Chart name */
+  name: string;
+  /** Chart version (SemVer) */
+  version: string;
+  /** Version of the app deployed by this chart */
+  appVersion?: string;
+  /** A single-sentence description of this chart */
+  description?: string;
+  /** Chart type: application or library */
+  type?: string;
+  /** Keywords for chart search */
+  keywords?: string[];
+  /** URL of the project home page */
+  home?: string;
+  /** URL to an SVG or PNG image for the chart */
+  icon?: string;
+  /** Whether this chart is deprecated */
+  deprecated?: boolean;
+  /** URLs to source code for this chart */
+  sources?: string[];
+  /** List of chart maintainers */
+  maintainers?: HelmMaintainerProps[];
+  /** Arbitrary key-value annotations */
+  annotations?: Record<string, string>;
+  /** SemVer range of compatible Kubernetes versions */
+  kubeVersion?: string;
+  /** YAML path for chart enablement (subcharts) */
+  condition?: string;
+  /** Tags for grouping charts for enabling/disabling */
+  tags?: string;
+}
+
+/** Chart.yaml metadata — defines the chart identity, version, and type. */
+export declare const Chart: new (props: ChartProps) => Declarable;
+
+/** Typed values definition — emits values.yaml and values.schema.json. */
+export interface ValuesProps {
+  [key: string]: unknown;
+}
+
+/** Typed values definition — emits values.yaml and values.schema.json. */
+export declare const Values: new (props: ValuesProps) => Declarable;
+
+/** Helm test pod — annotated with helm.sh/hook: test. */
+export interface HelmTestProps {
+  /** K8s Pod resource to use as the test */
+  resource?: object;
+}
+
+/** Helm test pod — annotated with helm.sh/hook: test. */
+export declare const HelmTest: new (props: HelmTestProps) => Declarable;
+
+/** NOTES.txt template content — displayed after helm install. */
+export interface HelmNotesProps {
+  /** NOTES.txt content (may contain Go template expressions) */
+  content: string;
+}
+
+/** NOTES.txt template content — displayed after helm install. */
+export declare const HelmNotes: new (props: HelmNotesProps) => Declarable;
+
+/** Lifecycle hook annotation — wraps a K8s resource with helm.sh/hook annotations. */
+export interface HelmHookProps {
+  /** Hook type: pre-install, post-install, pre-upgrade, post-upgrade, pre-delete, post-delete, pre-rollback, post-rollback, test */
+  hook: string;
+  /** Hook execution order weight */
+  weight?: number;
+  /** Hook delete policy: before-hook-creation, hook-succeeded, hook-failed */
+  deletePolicy?: string;
+  /** K8s resource to annotate with the hook */
+  resource: object;
+}
+
+/** Lifecycle hook annotation — wraps a K8s resource with helm.sh/hook annotations. */
+export declare const HelmHook: new (props: HelmHookProps) => Declarable;
+
+/** Chart dependency entry for Chart.yaml dependencies. */
+export interface HelmDependencyProps {
+  /** Dependency chart name */
+  name: string;
+  /** Dependency version range (SemVer) */
+  version: string;
+  /** Repository URL */
+  repository: string;
+  /** YAML path that enables/disables this dependency */
+  condition?: string;
+  /** Tags for grouping dependencies */
+  tags?: string[];
+  /** Whether this dependency is enabled */
+  enabled?: boolean;
+  /** Values to import from dependency (import-values in Chart.yaml) */
+  importValues?: unknown[];
+  /** Alias for the dependency */
+  alias?: string;
+}
+
+/** Chart dependency entry for Chart.yaml dependencies. */
+export declare const HelmDependency: new (props: HelmDependencyProps) => Declarable;
+
+/** Chart maintainer entry for Chart.yaml maintainers. */
+export interface HelmMaintainerProps {
+  /** Maintainer name */
+  name: string;
+  /** Maintainer email */
+  email?: string;
+  /** Maintainer URL */
+  url?: string;
+}
+
+/** Chart maintainer entry for Chart.yaml maintainers. */
+export declare const HelmMaintainer: new (props: HelmMaintainerProps) => Declarable;
+
+/** Custom Resource Definition — placed in the crds/ directory. */
+export interface HelmCRDProps {
+  /** CRD YAML content */
+  content: string;
+  /** CRD filename (e.g. mycrd.yaml) */
+  filename?: string;
+}
+
+/** Custom Resource Definition — placed in the crds/ directory. */
+export declare const HelmCRD: new (props: HelmCRDProps) => Declarable;

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@intentius/chant-lexicon-helm",
+  "version": "0.0.16",
+  "license": "Apache-2.0",
+  "type": "module",
+  "files": [
+    "src/",
+    "dist/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts",
+    "./manifest": "./dist/manifest.json",
+    "./meta": "./dist/meta.json",
+    "./types": "./dist/types/index.d.ts"
+  },
+  "scripts": {
+    "generate": "bun run src/codegen/generate-cli.ts",
+    "bundle": "bun run src/package-cli.ts",
+    "validate": "bun run src/validate-cli.ts",
+    "docs": "bun run src/codegen/docs-cli.ts",
+    "prepack": "bun run generate && bun run bundle && bun run validate"
+  },
+  "dependencies": {
+    "@intentius/chant": "0.0.15",
+    "@intentius/chant-lexicon-k8s": "0.0.15"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/codegen/docs-cli.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { generateDocs } from "./docs";
+
+await generateDocs({ verbose: true });