@intentius/chant-lexicon-k8s 0.124.31 → 0.124.32

package/dist/plugin.js

@@ -0,0 +1,741 @@
+/**
+ * Kubernetes lexicon plugin.
+ *
+ * Provides serializer, template detection, code generation,
+ * lint rules, and LSP/MCP integration for Kubernetes manifests.
+ */
+import { compositeCatalog } from "./composites/catalog.js";
+import { k8sBehaviourKinds } from "./behaviour-kinds.js";
+import { kubeCommandGroup } from "./kube/group.js";
+import { detectTemplate } from "./detect.js";
+import { postSynthChecks as postSynthCheckList } from "./lint/post-synth/index.js";
+import { k8sAuditCatalog } from "./lint/audit-catalog.js";
+import { createSkillsLoader, createDiffTool, createCatalogResource } from "@intentius/chant/lexicon-plugin-helpers";
+import { k8sSerializer } from "./serializer.js";
+import { hardcodedNamespaceRule } from "./lint/rules/hardcoded-namespace.js";
+import { latestImageTagRule } from "./lint/rules/latest-image-tag.js";
+import { missingResourceLimitsRule } from "./lint/rules/missing-resource-limits.js";
+import { argoAutomatedPruneRule } from "./lint/rules/argo-automated-prune.js";
+import { argoAppSetSingleProjectRule } from "./lint/rules/argo-appset-single-project.js";
+import { fluxSourceRefPinRule } from "./lint/rules/flux-source-ref-pin.js";
+import { k8sCompletions } from "./lsp/completions.js";
+import { k8sHover } from "./lsp/hover.js";
+import { K8sParser } from "./import/parser.js";
+import { K8sGenerator } from "./import/generator.js";
+import { k8sDeepNormalizationHooks } from "./deep-observe-hooks.js";
+import { LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+import { k8sConfigSchema } from "./config-schema.js";
+import { renderKustomizeRoots } from "./kustomize/root.js";
+import { encryptedSecretBuildRoot } from "./sops/encrypted-secret-file.js";
+import { k8sProjectCodegen } from "./crd/project-codegen.js";
+import { includeBuildRoot } from "./include/resolve.js";
+export const k8sPlugin = {
+    behaviourKinds: k8sBehaviourKinds,
+    name: "k8s",
+    ownershipChannel: { keys: LABEL_OWNERSHIP_KEYS, reads: ["describeResources", "observeResourcesDeep", "exportResources"] },
+    configSchema: k8sConfigSchema,
+    auditCatalog: () => k8sAuditCatalog,
+    serializer: k8sSerializer,
+    // Self-upgrade: where the pinned Kubernetes schema version lives + its upstream (#685).
+    upstreamPin: {
+        file: "src/spec/fetch.ts",
+        pattern: /export const K8S_SCHEMA_VERSION\s*=\s*"([^"]+)"/,
+        replace: (v, line) => line.replace(/export const K8S_SCHEMA_VERSION\s*=\s*"[^"]+"/, `export const K8S_SCHEMA_VERSION = "${v}"`),
+        upstream: { owner: "kubernetes", repo: "kubernetes", kind: "releases" },
+    },
+    // chant #1078/#1079 — the command-group seam's tenant. `kube` mounts the
+    // terminal surface over the typed client: kubectl-compatible reads (get,
+    // describe, logs, events, top, wait), chant's own additions (source, the
+    // `get` verdict column, -o chant), and gated writes (apply, delete) that
+    // route through the exact same machinery the Op activities use — never a
+    // parallel implementation. See ./kube/group.ts for the full verb list;
+    // this plugin only mounts it.
+    commands() {
+        return kubeCommandGroup();
+    },
+    lintRules() {
+        return [
+            hardcodedNamespaceRule,
+            latestImageTagRule,
+            missingResourceLimitsRule,
+            argoAutomatedPruneRule,
+            argoAppSetSingleProjectRule,
+            fluxSourceRefPinRule,
+        ];
+    },
+    postSynthChecks() {
+        return postSynthCheckList;
+    },
+    // Typed classes for the project's own CRDs (`k8s.crds`), written by
+    // `chant generate` and checked for drift by every build. See
+    // ./crd/project-codegen.ts.
+    projectCodegen() {
+        return k8sProjectCodegen();
+    },
+    // #1548 piece 3 — kustomization dirs declared as build roots. Each entry in
+    // `k8s.kustomize.roots` renders at build time (same injectable runner as
+    // the kustomize-apply capability: `kustomize build`, `kubectl kustomize`
+    // fallback) and the documents join the build as verbatim manifest entities:
+    // serialized with ownership stamping, checked post-synth, observed by
+    // `lifecycle diff --live`. See ./kustomize/root.ts.
+    //
+    // The same hook also resolves committed-encrypted `declareSecret()`
+    // declarations: it reads the ciphertext each one names and contributes it
+    // as a verbatim sidecar entity (see ./sops/encrypted-secret-file.ts), and
+    // `k8sInclude()` declarations: it reads or fetches each declared YAML and
+    // contributes its documents as verbatim manifest entities (see
+    // ./include/resolve.ts). All three read at the one sanctioned impure seam.
+    async buildRoots(ctx) {
+        const entities = new Map();
+        const warnings = [];
+        const roots = ctx.config.k8s?.kustomize?.roots ?? [];
+        if (roots.length > 0) {
+            const rendered = await renderKustomizeRoots({ projectRoot: ctx.projectRoot, roots });
+            for (const [name, entity] of rendered.entities)
+                entities.set(name, entity);
+            warnings.push(...rendered.warnings);
+        }
+        const included = await includeBuildRoot(ctx);
+        for (const [name, entity] of included.entities)
+            entities.set(name, entity);
+        const encrypted = await encryptedSecretBuildRoot(ctx);
+        for (const [name, entity] of encrypted.entities)
+            entities.set(name, entity);
+        warnings.push(...(encrypted.warnings ?? []));
+        return { entities, warnings };
+    },
+    // K8s YAML has no template interpolation functions like CloudFormation's
+    // Fn::Sub or GitLab's !reference. Cross-resource references are handled by
+    // the AttrRef system in the serializer (resolves to metadata.name).
+    // ConfigMap/Secret valueFrom references are expressed as plain property
+    // values, not intrinsics.
+    intrinsics() {
+        return [];
+    },
+    initTemplates(template) {
+        if (template === "microservice") {
+            return {
+                src: {
+                    "infra.ts": `import { Deployment, Service, HorizontalPodAutoscaler, PodDisruptionBudget, Container, Probe, ResourceRequirements } from "@intentius/chant-lexicon-k8s";
+
+export const deployment = new Deployment({
+  metadata: { name: "my-service", labels: { "app.kubernetes.io/name": "my-service" } },
+  spec: {
+    replicas: 2,
+    selector: { matchLabels: { "app.kubernetes.io/name": "my-service" } },
+    template: {
+      metadata: { labels: { "app.kubernetes.io/name": "my-service" } },
+      spec: {
+        containers: [
+          new Container({
+            name: "app",
+            image: "my-service:latest",
+            ports: [{ containerPort: 8080, name: "http" }],
+            resources: new ResourceRequirements({
+              limits: { cpu: "500m", memory: "256Mi" },
+              requests: { cpu: "100m", memory: "128Mi" },
+            }),
+            livenessProbe: new Probe({ httpGet: { path: "/healthz", port: 8080 }, initialDelaySeconds: 10 }),
+            readinessProbe: new Probe({ httpGet: { path: "/readyz", port: 8080 }, initialDelaySeconds: 5 }),
+          }),
+        ],
+      },
+    },
+  },
+});
+
+export const service = new Service({
+  metadata: { name: "my-service", labels: { "app.kubernetes.io/name": "my-service" } },
+  spec: {
+    selector: { "app.kubernetes.io/name": "my-service" },
+    ports: [{ port: 80, targetPort: 8080, protocol: "TCP", name: "http" }],
+  },
+});
+
+export const hpa = new HorizontalPodAutoscaler({
+  metadata: { name: "my-service" },
+  spec: {
+    scaleTargetRef: { apiVersion: "apps/v1", kind: "Deployment", name: "my-service" },
+    minReplicas: 2,
+    maxReplicas: 10,
+    metrics: [{ type: "Resource", resource: { name: "cpu", target: { type: "Utilization", averageUtilization: 70 } } }],
+  },
+});
+
+export const pdb = new PodDisruptionBudget({
+  metadata: { name: "my-service" },
+  spec: {
+    minAvailable: 1,
+    selector: { matchLabels: { "app.kubernetes.io/name": "my-service" } },
+  },
+});
+`,
+                },
+            };
+        }
+        if (template === "stateful") {
+            return {
+                src: {
+                    "infra.ts": `import { StatefulSet, Service } from "@intentius/chant-lexicon-k8s";
+
+export const statefulSet = new StatefulSet({
+  metadata: { name: "my-db", labels: { "app.kubernetes.io/name": "my-db" } },
+  spec: {
+    serviceName: "my-db",
+    replicas: 3,
+    selector: { matchLabels: { "app.kubernetes.io/name": "my-db" } },
+    template: {
+      metadata: { labels: { "app.kubernetes.io/name": "my-db" } },
+      spec: {
+        containers: [
+          {
+            name: "db",
+            image: "postgres:16",
+            ports: [{ containerPort: 5432, name: "postgres" }],
+            volumeMounts: [{ name: "data", mountPath: "/var/lib/postgresql/data" }],
+            env: [
+              { name: "POSTGRES_DB", value: "mydb" },
+            ],
+          },
+        ],
+      },
+    },
+    volumeClaimTemplates: [
+      {
+        metadata: { name: "data" },
+        spec: {
+          accessModes: ["ReadWriteOnce"],
+          resources: { requests: { storage: "10Gi" } },
+        },
+      },
+    ],
+  },
+});
+
+export const service = new Service({
+  metadata: { name: "my-db", labels: { "app.kubernetes.io/name": "my-db" } },
+  spec: {
+    selector: { "app.kubernetes.io/name": "my-db" },
+    ports: [{ port: 5432, targetPort: 5432, name: "postgres" }],
+    clusterIP: "None",
+  },
+});
+`,
+                },
+            };
+        }
+        // Default template — Deployment + Service
+        return {
+            src: {
+                "infra.ts": `import { Deployment, Service, Container, Probe } from "@intentius/chant-lexicon-k8s";
+
+export const deployment = new Deployment({
+  metadata: { name: "my-app", labels: { "app.kubernetes.io/name": "my-app" } },
+  spec: {
+    replicas: 2,
+    selector: { matchLabels: { "app.kubernetes.io/name": "my-app" } },
+    template: {
+      metadata: { labels: { "app.kubernetes.io/name": "my-app" } },
+      spec: {
+        containers: [
+          new Container({
+            name: "app",
+            image: "my-app:latest",
+            ports: [{ containerPort: 8080, name: "http" }],
+            livenessProbe: new Probe({ httpGet: { path: "/healthz", port: 8080 } }),
+            readinessProbe: new Probe({ httpGet: { path: "/readyz", port: 8080 } }),
+          }),
+        ],
+      },
+    },
+  },
+});
+
+export const service = new Service({
+  metadata: { name: "my-app", labels: { "app.kubernetes.io/name": "my-app" } },
+  spec: {
+    selector: { "app.kubernetes.io/name": "my-app" },
+    ports: [{ port: 80, targetPort: 8080, protocol: "TCP", name: "http" }],
+  },
+});
+`,
+            },
+        };
+    },
+    detectTemplate,
+    completionProvider(ctx) {
+        return k8sCompletions(ctx);
+    },
+    hoverProvider(ctx) {
+        return k8sHover(ctx);
+    },
+    templateParser() {
+        return new K8sParser();
+    },
+    templateGenerator() {
+        return new K8sGenerator();
+    },
+    async docs(options) {
+        const { generateDocs } = await import("./codegen/docs.js");
+        await generateDocs(options);
+    },
+    async generate(options) {
+        const { generate, writeGeneratedFiles } = await import("./codegen/generate.js");
+        const { dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const result = await generate({ verbose: options?.verbose ?? true });
+        const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+        writeGeneratedFiles(result, pkgDir);
+        console.error(`Generated ${result.resources} resources, ${result.properties} property types, ${result.enums} enums`);
+        if (result.warnings.length > 0) {
+            console.error(`${result.warnings.length} warnings`);
+        }
+    },
+    async validate(options) {
+        const { validate } = await import("./validate.js");
+        const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+        const result = await validate();
+        printValidationResult(result);
+    },
+    async coverage(options) {
+        const { analyzeK8sCoverage } = await import("./coverage.js");
+        await analyzeK8sCoverage({
+            verbose: options?.verbose,
+            minOverall: options?.minOverall,
+        });
+    },
+    async package(options) {
+        const { packageLexicon } = await import("./codegen/package.js");
+        const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+        const { join, dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const { spec, stats } = await packageLexicon({ verbose: options?.verbose, force: options?.force });
+        const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+        const distDir = join(pkgDir, "dist");
+        writeBundleSpec(spec, distDir);
+        console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+    },
+    composites() {
+        return compositeCatalog;
+    },
+    mcpTools() {
+        return [createDiffTool(k8sSerializer, "Compare current build output against previous output for Kubernetes manifests", "k8s")];
+    },
+    mcpResources() {
+        return [
+            createCatalogResource(import.meta.url, "Kubernetes Resource Catalog", "JSON list of all supported Kubernetes resource types", "lexicon-k8s.json", "k8s"),
+            {
+                uri: "examples/basic-deployment",
+                name: "Basic Deployment Example",
+                description: "A basic Kubernetes Deployment with Service",
+                mimeType: "text/typescript",
+                async handler() {
+                    return `import { Deployment, Service, Container, Probe } from "@intentius/chant-lexicon-k8s";
+
+export const deployment = new Deployment({
+  metadata: { name: "my-app", labels: { "app.kubernetes.io/name": "my-app" } },
+  spec: {
+    replicas: 2,
+    selector: { matchLabels: { "app.kubernetes.io/name": "my-app" } },
+    template: {
+      metadata: { labels: { "app.kubernetes.io/name": "my-app" } },
+      spec: {
+        containers: [
+          new Container({
+            name: "app",
+            image: "my-app:1.0",
+            ports: [{ containerPort: 8080, name: "http" }],
+            livenessProbe: new Probe({ httpGet: { path: "/healthz", port: 8080 } }),
+            readinessProbe: new Probe({ httpGet: { path: "/readyz", port: 8080 } }),
+          }),
+        ],
+      },
+    },
+  },
+});
+
+export const service = new Service({
+  metadata: { name: "my-app" },
+  spec: {
+    selector: { "app.kubernetes.io/name": "my-app" },
+    ports: [{ port: 80, targetPort: 8080, name: "http" }],
+  },
+});
+`;
+                },
+            },
+        ];
+    },
+    skills: createSkillsLoader(import.meta.url, [
+        {
+            file: "chant-k8s.md",
+            name: "chant-k8s",
+            description: "Kubernetes manifest lifecycle — scaffold, generate, lint, build, apply, troubleshoot, rollback",
+            triggers: [
+                { type: "file-pattern", value: "**/*.k8s.ts" },
+                { type: "file-pattern", value: "**/k8s/**/*.ts" },
+                { type: "context", value: "kubernetes" },
+                { type: "context", value: "k8s" },
+                { type: "context", value: "kubectl" },
+                { type: "context", value: "deployment" },
+                { type: "context", value: "pod" },
+                { type: "context", value: "composite" },
+                { type: "context", value: "autoscaled" },
+                { type: "context", value: "workerpool" },
+                { type: "context", value: "namespace-env" },
+                { type: "context", value: "node-agent" },
+            ],
+            preConditions: [
+                "chant CLI is installed (chant --version succeeds)",
+                "kubectl is configured and can access the cluster",
+                "Project has chant source files in src/",
+            ],
+            postConditions: [
+                "All pods are in Running state",
+                "No CrashLoopBackOff or Error pods",
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Basic deployment",
+                    description: "Create a Deployment with Service",
+                    input: "Create a web app deployment",
+                    output: `new Deployment({
+  metadata: { name: "my-app", labels: { "app.kubernetes.io/name": "my-app" } },
+  spec: {
+    replicas: 2,
+    selector: { matchLabels: { "app.kubernetes.io/name": "my-app" } },
+    template: {
+      metadata: { labels: { "app.kubernetes.io/name": "my-app" } },
+      spec: {
+        containers: [{
+          name: "app",
+          image: "my-app:1.0",
+          ports: [{ containerPort: 8080 }],
+        }],
+      },
+    },
+  },
+})`,
+                },
+                {
+                    title: "Deploy to cluster",
+                    description: "Build and apply manifests",
+                    input: "Deploy my app to the cluster",
+                    output: `chant build src/ --output manifests.yaml
+kubectl apply -f manifests.yaml --dry-run=server
+kubectl apply -f manifests.yaml
+kubectl rollout status deployment/my-app`,
+                },
+                {
+                    title: "AutoscaledService composite",
+                    description: "Production HTTP service with HPA, PDB, and zone spreading",
+                    input: "Create an autoscaled API service",
+                    output: `import { AutoscaledService } from "@intentius/chant-lexicon-k8s";
+
+const { deployment, service, hpa, pdb } = AutoscaledService({
+  name: "api",
+  image: "api:1.0",
+  port: 8080,
+  maxReplicas: 10,
+  cpuRequest: "100m",
+  memoryRequest: "128Mi",
+  topologySpread: true,
+});`,
+                },
+                {
+                    title: "BatchJob composite",
+                    description: "One-shot batch job with RBAC",
+                    input: "Run a database migration job",
+                    output: `import { BatchJob } from "@intentius/chant-lexicon-k8s";
+
+const { job, serviceAccount, role, roleBinding } = BatchJob({
+  name: "db-migrate",
+  image: "api:1.0",
+  command: ["python", "manage.py", "migrate"],
+  backoffLimit: 3,
+  ttlSecondsAfterFinished: 3600,
+});`,
+                },
+            ],
+        },
+        {
+            file: "chant-k8s-patterns.md",
+            name: "chant-k8s-patterns",
+            description: "Advanced K8s patterns — sidecars, observability, TLS, network isolation, config/secret mounting",
+            triggers: [
+                { type: "context", value: "sidecar" },
+                { type: "context", value: "init-container" },
+                { type: "context", value: "prometheus" },
+                { type: "context", value: "cert-manager" },
+                { type: "context", value: "tls" },
+                { type: "context", value: "network-policy" },
+                { type: "context", value: "canary" },
+                { type: "context", value: "blue-green" },
+                { type: "context", value: "configmap-mount" },
+                { type: "context", value: "secret-mount" },
+            ],
+            preConditions: [
+                "chant CLI is installed (chant --version succeeds)",
+                "kubectl is configured and can access the cluster",
+            ],
+            postConditions: [
+                "Pattern resources are deployed and functional",
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Sidecar with envoy proxy",
+                    description: "Deploy an app with an Envoy sidecar",
+                    input: "Add an envoy sidecar proxy to my API",
+                    output: `import { SidecarApp } from "@intentius/chant-lexicon-k8s";
+
+const { deployment, service } = SidecarApp({
+  name: "api",
+  image: "api:1.0",
+  port: 8080,
+  sidecars: [{ name: "envoy", image: "envoyproxy/envoy:v1.28", ports: [{ containerPort: 9901 }] }],
+});`,
+                },
+                {
+                    title: "Monitored service with alerts",
+                    description: "Deploy a service with Prometheus monitoring and alerting",
+                    input: "Set up monitoring for my API with error rate alerts",
+                    output: `import { MonitoredService } from "@intentius/chant-lexicon-k8s";
+
+const { deployment, service, serviceMonitor, prometheusRule } = MonitoredService({
+  name: "api",
+  image: "api:1.0",
+  metricsPort: 9090,
+  alertRules: [{ name: "HighErrorRate", expr: 'rate(http_errors[5m]) > 0.1', severity: "critical" }],
+});`,
+                },
+            ],
+        },
+        {
+            file: "chant-k8s-deployment-strategies.md",
+            name: "chant-k8s-deployment-strategies",
+            description: "Kubernetes deployment strategies, stateful workloads, RBAC, and networking patterns",
+            triggers: [
+                { type: "context", value: "deployment strategy" },
+                { type: "context", value: "statefulset" },
+                { type: "context", value: "rbac" },
+                { type: "context", value: "network policy" },
+                { type: "context", value: "rolling update" },
+                { type: "context", value: "blue green" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Blue/Green Deployment",
+                    input: "Set up a blue/green deployment for my app",
+                    output: "import { WebApp } from \"@intentius/chant-lexicon-k8s\";\n\nconst blue = WebApp({ name: \"app-blue\", image: \"app:1.0\" });\nconst green = WebApp({ name: \"app-green\", image: \"app:2.0\" });",
+                },
+            ],
+        },
+        {
+            file: "chant-k8s-security.md",
+            name: "chant-k8s-security",
+            description: "Kubernetes pod security, image scanning, network policies, and secrets management",
+            triggers: [
+                { type: "context", value: "k8s security" },
+                { type: "context", value: "pod security" },
+                { type: "context", value: "image security" },
+                { type: "context", value: "k8s secrets" },
+                { type: "context", value: "security context" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Hardened Container",
+                    input: "Create a hardened container with security context",
+                    output: "WebApp({ name: \"api\", image: \"api:1.0\", securityContext: { runAsNonRoot: true, readOnlyRootFilesystem: true, capabilities: { drop: [\"ALL\"] } } })",
+                },
+            ],
+        },
+        {
+            file: "chant-k8s-eks.md",
+            name: "chant-k8s-eks",
+            description: "EKS-specific Kubernetes composites — IRSA, ALB, EBS/EFS, Fluent Bit, ExternalDNS, ADOT",
+            triggers: [
+                { type: "context", value: "eks composites" },
+                { type: "context", value: "irsa" },
+                { type: "context", value: "alb ingress" },
+                { type: "context", value: "ebs storage" },
+                { type: "context", value: "karpenter" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "IRSA ServiceAccount",
+                    input: "Create an IRSA ServiceAccount for my app",
+                    output: "import { IrsaServiceAccount } from \"@intentius/chant-lexicon-k8s\";\n\nconst { serviceAccount } = IrsaServiceAccount({ name: \"app-sa\", iamRoleArn: \"arn:aws:iam::123456789012:role/app-role\" });",
+                },
+            ],
+        },
+        {
+            file: "chant-k8s-gke.md",
+            name: "chant-k8s-gke",
+            description: "GKE-specific Kubernetes composites — Workload Identity, GCE PD, Filestore, FluentBit, OTel, ExternalDNS, Gateway",
+            triggers: [
+                { type: "context", value: "gke composites" },
+                { type: "context", value: "workload identity gke" },
+                { type: "context", value: "config connector k8s" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "GKE Workload Identity",
+                    input: "Create a ServiceAccount with GKE Workload Identity",
+                    output: "import { WorkloadIdentityServiceAccount } from \"@intentius/chant-lexicon-k8s\";\n\nconst { serviceAccount } = WorkloadIdentityServiceAccount({ name: \"app-sa\", gcpServiceAccountEmail: \"app@project.iam.gserviceaccount.com\" });",
+                },
+            ],
+        },
+        {
+            file: "chant-k8s-aks.md",
+            name: "chant-k8s-aks",
+            description: "AKS-specific Kubernetes composites — Workload Identity, AGIC, Azure Disk/File, ExternalDNS, Azure Monitor",
+            triggers: [
+                { type: "context", value: "aks composites" },
+                { type: "context", value: "workload identity aks" },
+                { type: "context", value: "agic ingress" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "AKS Workload Identity",
+                    input: "Create a ServiceAccount with AKS Workload Identity",
+                    output: "import { AksWorkloadIdentityServiceAccount } from \"@intentius/chant-lexicon-k8s\";\n\nconst { serviceAccount } = AksWorkloadIdentityServiceAccount({ name: \"app-sa\", clientId: \"12345678-abcd-1234-abcd-123456789012\" });",
+                },
+            ],
+        },
+        {
+            file: "chant-k8s-argo.md",
+            name: "chant-k8s-argo",
+            description: "Argo CD composites — ArgoAppFor, ArgoAppSetForRegions, AppProject scoping, cluster registration, and how a deploy splits between Argo and a chant Op",
+            triggers: [
+                { type: "context", value: "argo" },
+                { type: "context", value: "argo cd" },
+                { type: "context", value: "argocd" },
+                { type: "context", value: "gitops" },
+                { type: "context", value: "application" },
+                { type: "context", value: "applicationset" },
+                { type: "context", value: "appproject" },
+                { type: "context", value: "reconcile" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Application from a build target",
+                    description: "Reconcile a Chant build target with Argo CD",
+                    input: "Deploy my api target through Argo CD",
+                    output: "import { ArgoAppFor } from \"@intentius/chant-lexicon-k8s\";\n\nexport const api = ArgoAppFor(\"api\", {\n  repo: \"https://github.com/acme/infra\",\n  path: \"dist/api\",\n  destination: { server: \"https://kubernetes.default.svc\", namespace: \"api\" },\n});",
+                },
+                {
+                    title: "Per-region ApplicationSet",
+                    description: "Fan one app out across regional clusters",
+                    input: "Deploy crdb to east, central, and west clusters via Argo",
+                    output: "import { ArgoAppSetForRegions } from \"@intentius/chant-lexicon-k8s\";\n\nexport const crdb = ArgoAppSetForRegions(\n  [\"east\", \"central\", \"west\"],\n  (region) => ({ server: servers[region], namespace: `crdb-${region}`, path: `dist/${region}` }),\n  { name: \"crdb\", repo: \"https://github.com/acme/infra\", project: \"crdb\" },\n);",
+                },
+            ],
+        },
+        {
+            file: "chant-k8s-flux.md",
+            name: "chant-k8s-flux",
+            description: "Flux CD composites — FluxGitSource + FluxAppFor, the one-source-many-apps shape, dependsOn ordering, the FLUX rules, and the flux-reconcile deploy step",
+            triggers: [
+                { type: "context", value: "flux" },
+                { type: "context", value: "fluxcd" },
+                { type: "context", value: "flux cd" },
+                { type: "context", value: "gitops" },
+                { type: "context", value: "gitrepository" },
+                { type: "context", value: "kustomization" },
+                { type: "context", value: "source-controller" },
+                { type: "context", value: "kustomize-controller" },
+                { type: "context", value: "reconcile" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Source + Kustomization from a build target",
+                    description: "Reconcile a Chant build target with Flux",
+                    input: "Deploy my app through Flux",
+                    output: "import { FluxGitSource, FluxAppFor } from \"@intentius/chant-lexicon-k8s\";\n\nexport const source = FluxGitSource(\"infra\", {\n  url: \"https://github.com/acme/infra\",\n  branch: \"main\",\n});\n\nexport const app = FluxAppFor(\"app\", {\n  source,\n  path: \"./dist/apps/app\",\n  dependsOn: [\"platform\"],\n});",
+                },
+                {
+                    title: "One source, many apps",
+                    description: "The multi-app repo shape — one GitRepository shared by every Kustomization",
+                    input: "Reconcile platform, api, and web from one repo with ordering",
+                    output: "import { FluxGitSource, FluxAppFor } from \"@intentius/chant-lexicon-k8s\";\n\nconst source = FluxGitSource(\"infra\", { url: \"https://github.com/acme/infra\" });\n\nexport const platform = FluxAppFor(\"platform\", { source, path: \"./dist/platform\" });\nexport const api = FluxAppFor(\"api\", { source, path: \"./dist/apps/api\", dependsOn: [\"platform\"] });\nexport const web = FluxAppFor(\"web\", { source, path: \"./dist/apps/web\", dependsOn: [\"platform\", \"api\"] });",
+                },
+            ],
+        },
+    ]),
+    async describeResources(options) {
+        const { describeResources } = await import("./describe-resources.js");
+        return describeResources(options);
+    },
+    /**
+     * Who chant would act as in this cluster, before it acts (#1982) — the
+     * connector's own context/credential resolution plus the API server's
+     * `SelfSubjectReview`, reported through the same connect path the read uses
+     * so the cluster named is the cluster read. Implementation in ./whoami.ts.
+     */
+    async describeIdentity(options) {
+        const { describeIdentity } = await import("./whoami.js");
+        return describeIdentity(options);
+    },
+    // Env teardown (#1222): enumeration + execution over the marker label
+    // selector (managed-by + stack + env), through the same typed client the
+    // prune uses. Execution deletes namespaces last. See ./teardown.ts.
+    async teardownOwned(options) {
+        const { teardownOwned } = await import("./teardown.js");
+        return teardownOwned(options);
+    },
+    async executeTeardown(options) {
+        const { executeTeardown } = await import("./teardown.js");
+        return executeTeardown(options);
+    },
+    /**
+     * Deploy-unit presence + health for `chant components status --live`
+     * (#1495 piece 3): a Kubernetes deploy unit is the label selector chant's
+     * own serializer stamps, so this reads back
+     * `app.kubernetes.io/managed-by=chant, chant.intentius.io/stack=<stack>`
+     * and rolls readiness up from the matching workloads' controllers.
+     */
+    async describeStackStatus(options) {
+        const { describeStackStatus } = await import("./describe-stack-status.js");
+        return describeStackStatus(options);
+    },
+    async exportResources(options) {
+        const { exportResources } = await import("./export-resources.js");
+        return exportResources(options);
+    },
+    /**
+     * The change signal (#1981). A Watch on every declared kind, reported as a
+     * bare `onChange()` that wakes an operator tick early. Nothing a frame
+     * carries reaches the tick: the seam has no payload, and the tick that runs
+     * is the tick the timer would have run. Kubernetes is the one substrate
+     * chant reaches whose change stream needs nothing deployed into the observed
+     * cluster; see the verdict table in the operator guide. Implementation in
+     * ./subscribe-changes.ts, dynamically imported for the same reason
+     * describeResources is.
+     */
+    async subscribeChanges(options) {
+        const { subscribeChanges } = await import("./subscribe-changes.js");
+        return subscribeChanges(options);
+    },
+    // Property-level live drift via SSA managed-fields (#1076, epic #1073).
+    // The reader lives in ./deep-observe.ts, loaded only through this dynamic
+    // import — same reason describeResources/exportResources are — so the API
+    // client never becomes reachable from the build path (chant #1074,
+    // examples/k8s-client-boundary.test.ts). deepNormalizationHooks is plain
+    // data with no client dependency (./deep-observe-hooks.ts) and is imported
+    // statically above, because core applies it to the *declared* tree whether
+    // or not a live read ever happens.
+    async observeResourcesDeep(options) {
+        const { observeResourcesDeepK8s } = await import("./deep-observe.js");
+        return observeResourcesDeepK8s(options);
+    },
+    deepNormalizationHooks: k8sDeepNormalizationHooks,
+};