@intentius/chant-lexicon-k8s 0.42.1 → 0.44.2

package/src/composites/composites.test.ts

@@ -9,6 +9,7 @@ function p(member: unknown): Record<string, unknown> {
 }
 import { StatefulApp } from "./stateful-app";
 import { ArgoAppFor, ArgoAppSetForRegions, registerArgoCluster } from "./argo-app";
+import { FluxGitSource, FluxAppFor } from "./flux-app";
 import { CronWorkload } from "./cron-workload";
 import { AutoscaledService } from "./autoscaled-service";
 import { WorkerPool } from "./worker-pool";
@@ -3359,6 +3360,121 @@ describe("registerArgoCluster", () => {
   });
 });
 
+describe("FluxGitSource", () => {
+  test("returns a single GitRepository", () => {
+    const result = FluxGitSource("home-chant", { url: "https://github.com/jhgaylor/home-chant" });
+    expect(result.gitRepository).toBeDefined();
+    expect((result.gitRepository as any).entityType).toBe("K8s::Flux::GitRepository");
+  });
+
+  test("defaults: 5m interval, main branch, flux-system namespace", () => {
+    const result = FluxGitSource("home-chant", { url: "https://github.com/jhgaylor/home-chant" });
+    const meta = p(result.gitRepository).metadata as any;
+    const spec = p(result.gitRepository).spec as any;
+    expect(meta.namespace).toBe("flux-system");
+    expect(meta.labels["app.kubernetes.io/managed-by"]).toBe("chant");
+    expect(spec.interval).toBe("5m");
+    expect(spec.url).toBe("https://github.com/jhgaylor/home-chant");
+    expect(spec.ref).toEqual({ branch: "main" });
+  });
+
+  test("a tag pin wins over the branch default", () => {
+    const spec = p(FluxGitSource("app", { url: "u", tag: "v1.2.3" }).gitRepository).spec as any;
+    expect(spec.ref).toEqual({ tag: "v1.2.3" });
+  });
+
+  test("secretRef renders as a name reference", () => {
+    const spec = p(FluxGitSource("app", { url: "u", secretRef: "git-creds" }).gitRepository).spec as any;
+    expect(spec.secretRef).toEqual({ name: "git-creds" });
+  });
+});
+
+describe("FluxAppFor", () => {
+  const source = () => FluxGitSource("home-chant", { url: "https://github.com/jhgaylor/home-chant" });
+
+  test("returns a single Kustomization (the source is not duplicated)", () => {
+    const result = FluxAppFor("hello-chant", { source: source(), path: "./apps/hello-chant/k8s" });
+    expect(result.kustomization).toBeDefined();
+    expect((result.kustomization as any).entityType).toBe("K8s::Flux::Kustomization");
+    expect((result as any).gitRepository).toBeUndefined();
+  });
+
+  test("defaults: 10m interval, prune, wait, flux-system namespace", () => {
+    const result = FluxAppFor("hello-chant", { source: source(), path: "./apps/hello-chant/k8s" });
+    const meta = p(result.kustomization).metadata as any;
+    const spec = p(result.kustomization).spec as any;
+    expect(meta.name).toBe("hello-chant");
+    expect(meta.namespace).toBe("flux-system");
+    expect(spec.interval).toBe("10m");
+    expect(spec.prune).toBe(true);
+    expect(spec.wait).toBe(true);
+    expect(spec.path).toBe("./apps/hello-chant/k8s");
+  });
+
+  test("derives sourceRef from a FluxGitSource result", () => {
+    const spec = p(FluxAppFor("hello", { source: source(), path: "./k8s" }).kustomization).spec as any;
+    expect(spec.sourceRef).toEqual({ kind: "GitRepository", name: "home-chant", namespace: "flux-system" });
+  });
+
+  test("many apps share one source", () => {
+    const shared = source();
+    const a = FluxAppFor("mealie", { source: shared, path: "./apps/mealie/k8s" });
+    const b = FluxAppFor("ntfy", { source: shared, path: "./apps/ntfy/k8s" });
+    expect((p(a.kustomization).spec as any).sourceRef.name).toBe("home-chant");
+    expect((p(b.kustomization).spec as any).sourceRef.name).toBe("home-chant");
+  });
+
+  test("a string source names an existing GitRepository (flux-system)", () => {
+    const spec = p(FluxAppFor("mealie", { source: "flux-system", path: "./apps/mealie/generated" }).kustomization)
+      .spec as any;
+    expect(spec.sourceRef).toEqual({ kind: "GitRepository", name: "flux-system" });
+  });
+
+  test("an explicit ref carries a non-git source kind", () => {
+    const spec = p(
+      FluxAppFor("fountain", { source: { kind: "OCIRepository", name: "fountain" }, path: "./k8s" }).kustomization,
+    ).spec as any;
+    expect(spec.sourceRef).toEqual({ kind: "OCIRepository", name: "fountain" });
+  });
+
+  test("dependsOn is a plain name list rendered to name objects", () => {
+    const spec = p(
+      FluxAppFor("hello", {
+        source: "flux-system",
+        path: "./k8s",
+        dependsOn: ["cert-manager", "traefik"],
+      }).kustomization,
+    ).spec as any;
+    expect(spec.dependsOn).toEqual([{ name: "cert-manager" }, { name: "traefik" }]);
+  });
+
+  test("omits dependsOn when the list is empty", () => {
+    const spec = p(FluxAppFor("hello", { source: "flux-system", path: "./k8s" }).kustomization).spec as any;
+    expect(spec.dependsOn).toBeUndefined();
+  });
+
+  test("maps targetNamespace and opt-outs onto the spec", () => {
+    const spec = p(
+      FluxAppFor("cloudflared", {
+        source: "flux-system",
+        path: "./apps/cloudflared/generated",
+        targetNamespace: "cloudflared",
+        wait: false,
+        prune: false,
+        suspend: true,
+        timeout: "3m",
+        serviceAccountName: "flux-applier",
+      }).kustomization,
+    ).spec as any;
+    expect(spec.targetNamespace).toBe("cloudflared");
+    expect(spec.wait).toBe(false);
+    expect(spec.prune).toBe(false);
+    expect(spec.suspend).toBe(true);
+    expect(spec.timeout).toBe("3m");
+    expect(spec.serviceAccountName).toBe("flux-applier");
+  });
+});
+
 describe("package index re-exports (regression guard)", () => {
   test("Argo composites are reachable from the package entry", async () => {
     const pkg: any = await import("../index");
@@ -3366,4 +3482,10 @@ describe("package index re-exports (regression guard)", () => {
     expect(typeof pkg.ArgoAppSetForRegions).toBe("function");
     expect(typeof pkg.registerArgoCluster).toBe("function");
   });
+
+  test("Flux composites are reachable from the package entry", async () => {
+    const pkg: any = await import("../index");
+    expect(typeof pkg.FluxGitSource).toBe("function");
+    expect(typeof pkg.FluxAppFor).toBe("function");
+  });
 });

package/src/composites/flux-app.ts

@@ -0,0 +1,274 @@
+/**
+ * Flux CD composites — turn Chant build targets into Flux sources and
+ * `Kustomization`s.
+ *
+ * The k8s lexicon stays runtime-agnostic: it only emits manifests. These
+ * composites are the opt-in bridge to Flux's reconciliation layer, the
+ * `ArgoAppFor` analogue for the source-controller/kustomize-controller pair.
+ * Authoring a `GitRepository` + `Kustomization` by hand is ~40 lines of YAML
+ * per app; `FluxAppFor` collapses the pair to one call with defaults taken
+ * from real Flux estates.
+ *
+ * - FluxGitSource(name, opts) → a single K8s::Flux::GitRepository
+ * - FluxAppFor(target, opts)  → a single K8s::Flux::Kustomization
+ *
+ * The two are split deliberately: the common estate shape is one source
+ * shared by many Kustomizations. A `GitRepository` per app is the mistake
+ * this split makes hard — declare the source once, hand its result to every
+ * `FluxAppFor` that reconciles a path out of it.
+ */
+
+import { Composite, mergeDefaults } from "@intentius/chant";
+import {
+  GitRepository as GitRepositoryResource,
+  Kustomization as KustomizationResource,
+} from "../generated";
+
+// ── Shared types ─────────────────────────────────────────────────────────────
+
+/** The namespace the Flux controllers run in and watch by default. */
+const FLUX_NAMESPACE = "flux-system";
+
+/** Source kinds a Kustomization can reconcile from. */
+export type FluxSourceKind = "GitRepository" | "OCIRepository" | "Bucket";
+
+/** An explicit reference to a source declared elsewhere. */
+export interface FluxSourceRef {
+  /** Source kind (default "GitRepository"). */
+  kind?: FluxSourceKind;
+  /** Name of the source object. */
+  name: string;
+  /** Namespace of the source, when it differs from the Kustomization's. */
+  namespace?: string;
+}
+
+// ── FluxGitSource ────────────────────────────────────────────────────────────
+
+export interface FluxGitSourceOptions {
+  /** Git repository URL the source-controller fetches. */
+  url: string;
+  /** Branch to track (default "main"). Ignored when `tag` is set. */
+  branch?: string;
+  /** Tag to pin instead of a branch. */
+  tag?: string;
+  /** Fetch interval (default "5m"). */
+  interval?: string;
+  /** Name of the Secret holding git credentials, for private repos. */
+  secretRef?: string;
+  /** Namespace the GitRepository lives in (default "flux-system"). */
+  fluxNamespace?: string;
+  /** Extra labels applied to the GitRepository. */
+  labels?: Record<string, string>;
+  defaults?: { gitRepository?: Partial<Record<string, unknown>> };
+}
+
+export type FluxGitSourceResult = {
+  gitRepository: InstanceType<typeof GitRepositoryResource>;
+}
+
+const FluxGitRepository = Composite<{ name: string } & FluxGitSourceOptions, FluxGitSourceResult>(
+  (props) => {
+    const {
+      name,
+      url,
+      branch = "main",
+      tag,
+      interval = "5m",
+      secretRef,
+      fluxNamespace = FLUX_NAMESPACE,
+      labels = {},
+      defaults,
+    } = props;
+
+    const gitRepository = new GitRepositoryResource(mergeDefaults({
+      metadata: {
+        name,
+        namespace: fluxNamespace,
+        labels: {
+          "app.kubernetes.io/name": name,
+          "app.kubernetes.io/managed-by": "chant",
+          ...labels,
+        },
+      },
+      spec: {
+        interval,
+        url,
+        // An unset spec.ref falls back to `master` — always pin (FLUX001).
+        ref: tag !== undefined ? { tag } : { branch },
+        ...(secretRef !== undefined && { secretRef: { name: secretRef } }),
+      },
+    }, defaults?.gitRepository));
+
+    return { gitRepository };
+  },
+  "FluxGitRepository",
+);
+
+/**
+ * Declare a Flux `GitRepository` source in one call.
+ *
+ * Declare it once and share it: every `FluxAppFor` that reconciles a path out
+ * of the same repo should take this result as its `source`.
+ *
+ * @example
+ * ```ts
+ * import { FluxGitSource } from "@intentius/chant-lexicon-k8s";
+ *
+ * export const source = FluxGitSource("home-chant", {
+ *   url: "https://github.com/jhgaylor/home-chant",
+ *   branch: "main",
+ * });
+ * ```
+ */
+export function FluxGitSource(name: string, options: FluxGitSourceOptions): FluxGitSourceResult {
+  return FluxGitRepository({ name, ...options });
+}
+
+// ── FluxAppFor ───────────────────────────────────────────────────────────────
+
+export interface FluxAppForOptions {
+  /**
+   * The source to reconcile from — a `FluxGitSource` result, the name of an
+   * existing `GitRepository` (e.g. the bootstrap-created "flux-system"), or an
+   * explicit `{ kind, name }` reference for OCIRepository/Bucket sources.
+   */
+  source: FluxGitSourceResult | FluxSourceRef | string;
+  /** Path within the source holding the manifests (e.g. "./apps/api/k8s"). */
+  path: string;
+  /** Namespace the reconciled resources land in (sets spec.targetNamespace). */
+  targetNamespace?: string;
+  /** Reconcile interval (default "10m"). */
+  interval?: string;
+  /** Delete resources that disappear from the source (default true). */
+  prune?: boolean;
+  /** Wait for reconciled resources to become ready (default true). */
+  wait?: boolean;
+  /**
+   * Names of Kustomizations that must be ready first, as a plain name list
+   * (rendered to spec.dependsOn). Validated against the build by FLUX003.
+   */
+  dependsOn?: string[];
+  /** Timeout for health checks and apply operations. */
+  timeout?: string;
+  /** Pause reconciliation without deleting anything. */
+  suspend?: boolean;
+  /** ServiceAccount the kustomize-controller impersonates for this app. */
+  serviceAccountName?: string;
+  /** Namespace the Kustomization object itself lives in (default "flux-system"). */
+  fluxNamespace?: string;
+  /** Extra labels applied to the Kustomization. */
+  labels?: Record<string, string>;
+  defaults?: { kustomization?: Partial<Record<string, unknown>> };
+}
+
+export type FluxAppForResult = {
+  kustomization: InstanceType<typeof KustomizationResource>;
+}
+
+/** Resolve the `source` option to a rendered sourceRef. */
+function resolveSourceRef(
+  target: string,
+  source: FluxGitSourceResult | FluxSourceRef | string,
+): Record<string, unknown> {
+  if (typeof source === "string") {
+    return { kind: "GitRepository", name: source };
+  }
+  if ("gitRepository" in source && source.gitRepository !== undefined) {
+    const metadata = (source.gitRepository as { props?: { metadata?: { name?: unknown; namespace?: unknown } } })
+      .props?.metadata;
+    const name = metadata?.name;
+    if (typeof name !== "string" || name === "") {
+      throw new Error(
+        `FluxAppFor("${target}"): the supplied FluxGitSource result has no metadata.name to reference.`,
+      );
+    }
+    return {
+      kind: "GitRepository",
+      name,
+      ...(typeof metadata?.namespace === "string" && { namespace: metadata.namespace }),
+    };
+  }
+  const ref = source as FluxSourceRef;
+  return {
+    kind: ref.kind ?? "GitRepository",
+    name: ref.name,
+    ...(ref.namespace !== undefined && { namespace: ref.namespace }),
+  };
+}
+
+const FluxKustomization = Composite<{ target: string } & FluxAppForOptions, FluxAppForResult>(
+  (props) => {
+    const {
+      target,
+      source,
+      path,
+      targetNamespace,
+      interval = "10m",
+      prune = true,
+      wait = true,
+      dependsOn = [],
+      timeout,
+      suspend,
+      serviceAccountName,
+      fluxNamespace = FLUX_NAMESPACE,
+      labels = {},
+      defaults,
+    } = props;
+
+    const sourceRef = resolveSourceRef(target, source);
+
+    // The Kustomization's namespace also scopes the sourceRef: an in-spec
+    // sourceRef without a namespace resolves in the Kustomization's own.
+    const kustomization = new KustomizationResource(mergeDefaults({
+      metadata: {
+        name: target,
+        namespace: fluxNamespace,
+        labels: {
+          "app.kubernetes.io/name": target,
+          "app.kubernetes.io/managed-by": "chant",
+          ...labels,
+        },
+      },
+      spec: {
+        interval,
+        path,
+        prune,
+        wait,
+        sourceRef,
+        ...(targetNamespace !== undefined && { targetNamespace }),
+        ...(dependsOn.length > 0 && { dependsOn: dependsOn.map((name) => ({ name })) }),
+        ...(timeout !== undefined && { timeout }),
+        ...(suspend !== undefined && { suspend }),
+        ...(serviceAccountName !== undefined && { serviceAccountName }),
+      },
+    }, defaults?.kustomization));
+
+    return { kustomization };
+  },
+  "FluxKustomization",
+);
+
+/**
+ * Reconcile a Chant build target with Flux in one call — the `Kustomization`
+ * half of the GitRepository + Kustomization pair. The source is passed in,
+ * not created here, so many apps share one repo declaration.
+ *
+ * @example
+ * ```ts
+ * import { FluxGitSource, FluxAppFor } from "@intentius/chant-lexicon-k8s";
+ *
+ * export const source = FluxGitSource("home-chant", {
+ *   url: "https://github.com/jhgaylor/home-chant",
+ * });
+ *
+ * export const hello = FluxAppFor("hello-chant", {
+ *   source,
+ *   path: "./apps/hello-chant/k8s",
+ *   targetNamespace: "default",
+ *   dependsOn: ["cert-manager", "traefik"],
+ * });
+ * ```
+ */
+export function FluxAppFor(target: string, options: FluxAppForOptions): FluxAppForResult {
+  return FluxKustomization({ target, ...options });
+}

package/src/composites/index.ts

@@ -93,3 +93,12 @@ export type {
   RegisterArgoClusterOptions,
   RegisterArgoClusterResult,
 } from "./argo-app";
+export { FluxGitSource, FluxAppFor } from "./flux-app";
+export type {
+  FluxSourceKind,
+  FluxSourceRef,
+  FluxGitSourceOptions,
+  FluxGitSourceResult,
+  FluxAppForOptions,
+  FluxAppForResult,
+} from "./flux-app";

package/src/config-augmentation.test.ts

@@ -0,0 +1,72 @@
+/**
+ * The `k8s` cluster-binding block typechecks under `satisfies ChantConfig`
+ * (#1455), and its schema rejects the typos that land a read on the wrong
+ * cluster (#1344).
+ *
+ * #1455's reproduction is the first test, verbatim: `ChantConfig` did not
+ * declare the `k8s` key the lexicon reads, so the one block that stops a live
+ * read hitting the wrong cluster was also the one block that could not
+ * typecheck — and the path of least resistance was dropping `satisfies
+ * ChantConfig`, which silently gives up checking on everything else in the
+ * file. The lexicon's module augmentation (declared in `./config.ts` and
+ * `./config-schema.ts`) is what makes it compile; this file is the forgejo
+ * lexicon's `config-augmentation.test.ts` guard, ported.
+ */
+
+import { describe, test, expect } from "vitest";
+import type { ChantConfig } from "@intentius/chant";
+import type { K8sChantConfig } from "./config";
+import { k8sConfigSchema } from "./config-schema";
+
+describe("the k8s config namespace (#1455, #1344)", () => {
+  test("the issue's reproduction typechecks as a ChantConfig", () => {
+    // The compile-time assertion is the point; the runtime one keeps vitest happy.
+    const config = {
+      lexicons: ["k8s"],
+      environments: ["local"],
+      k8s: {
+        profiles: { local: { context: "k3d-fountain-local" } },
+      } satisfies K8sChantConfig,
+    } satisfies ChantConfig;
+    expect(config.k8s.profiles.local.context).toBe("k3d-fountain-local");
+  });
+
+  test("an empty namespace is valid — every key is optional", () => {
+    expect(k8sConfigSchema.safeParse({}).success).toBe(true);
+  });
+
+  test("the schema accepts the documented shape", () => {
+    const parsed = k8sConfigSchema.safeParse({
+      profiles: { prod: { context: "prod-eks" }, staging: { context: "staging-eks" } },
+      execCredentialPlugins: ["aws", "my-org-oidc-helper"],
+    });
+    expect(parsed.success).toBe(true);
+  });
+
+  test("an unknown key at the top of the namespace is rejected, not ignored", () => {
+    // Core applies `.strict()` when validating a declared namespace
+    // (`validateLexiconConfig`), so `profile` instead of `profiles` errors
+    // rather than silently leaving every environment unbound.
+    expect(k8sConfigSchema.strict().safeParse({ profile: { local: { context: "x" } } }).success).toBe(false);
+  });
+
+  test("a typo inside a profile is rejected too — the nesting is strict", () => {
+    // `contxt` used to be accepted and ignored, which meant the ambient
+    // kubectl context won and the wrong cluster was read (#1488's setup).
+    const parsed = k8sConfigSchema.safeParse({ profiles: { prod: { contxt: "prod-eks" } } });
+    expect(parsed.success).toBe(false);
+  });
+
+  test("a wrong value type is rejected", () => {
+    expect(k8sConfigSchema.safeParse({ profiles: { prod: { context: 42 } } }).success).toBe(false);
+    expect(k8sConfigSchema.safeParse({ execCredentialPlugins: "aws" }).success).toBe(false);
+  });
+
+  test("the schema and the exported interface describe the same namespace", () => {
+    const value: K8sChantConfig = {
+      profiles: { local: { context: "k3d-fountain-local" } },
+      execCredentialPlugins: ["aws"],
+    };
+    expect(k8sConfigSchema.safeParse(value).success).toBe(true);
+  });
+});

package/src/config-schema.ts

@@ -23,6 +23,11 @@ export const k8sClusterProfileSchema = z.strictObject({
 export const k8sConfigSchema = z.strictObject({
   profiles: z.record(z.string(), k8sClusterProfileSchema).optional(),
   execCredentialPlugins: z.array(z.string()).optional(),
+  kustomize: z
+    .strictObject({
+      roots: z.array(z.string()).optional(),
+    })
+    .optional(),
 });
 
 declare module "@intentius/chant/config" {

package/src/config.ts

@@ -29,13 +29,15 @@
  * resolves this via `@intentius/chant/kubectl-context`'s
  * `resolveClusterTarget`:
  *
- * - A declared binding is passed explicitly as `kubectl ... --context <bound>`
- *   on every invocation, and checked against the ambient context first — a
- *   mismatch refuses loudly (naming the environment, the expected context,
- *   and the ambient one) instead of silently reading the wrong cluster.
+ * - A declared binding is passed explicitly to the typed client on every
+ *   read and write, regardless of what `kubectl` is ambiently pointed at
+ *   (#1488 — the binding is a selection, not a check). A bound context the
+ *   kubeconfig does not have fails with an error naming the context and the
+ *   `k8s.profiles.<env>.context` binding — never by falling back to ambient.
  * - No binding for the environment keeps today's behavior — the ambient
  *   context — but logs a visible note that nothing is pinned, so the
- *   fallback is never silent.
+ *   fallback is never silent. Read failures name the context that was read
+ *   and the missing binding.
  *
  * `ChantConfig` uses `.passthrough()` in its Zod schema so the `k8s` key is
  * accepted at runtime without core changes, exactly like `temporal.profiles`
@@ -83,6 +85,32 @@ export interface K8sChantConfig {
    * ```
    */
   execCredentialPlugins?: string[];
+
+  /**
+   * Kustomize settings (#1548 piece 3).
+   *
+   * `roots` names kustomization directories that are build roots: each is
+   * rendered (`kustomize build`, `kubectl kustomize` fallback) at build time
+   * and the rendered documents join the manifest set — serialized into the
+   * build output, ownership-stamped, checked by post-synth rules, and
+   * observed by `lifecycle diff --live` like any declared resource. This is
+   * how an estate that keeps its overlay tree gets a declared side without
+   * converting a single manifest to typed source.
+   *
+   * Paths are relative to the project root (the directory holding
+   * `chant.config.*`), NOT `sourceDir` — the overlay tree usually lives
+   * beside the typed source, not inside it.
+   *
+   * ```ts
+   * k8s: {
+   *   kustomize: { roots: ["overlays/prod"] },
+   * } satisfies K8sChantConfig
+   * ```
+   */
+  kustomize?: {
+    /** Kustomization directories to render into the build. */
+    roots?: string[];
+  };
 }
 
 declare module "@intentius/chant/config" {

package/src/crd/crd-sources.ts

@@ -277,6 +277,40 @@ const FLUX_OPERATOR_INSTALL = `https://github.com/controlplaneio-fluxcd/flux-ope
 const KUBEMICROVM_CHART = "oci://ghcr.io/codriverlabs/helm/kube-microvm-operator";
 const KUBEMICROVM_VERSION = "1.0.11";
 
+/**
+ * k3s bundled-controller CRDs — helm.cattle.io/v1 + k3s.cattle.io/v1
+ *
+ * k3s's manifest auto-deploy machinery speaks these CRDs: drop a HelmChart
+ * into /var/lib/rancher/k3s/server/manifests and the embedded helm-controller
+ * installs the chart; every auto-deployed manifest is tracked by an Addon.
+ * Typed here for the same reason the Flux toolkit kinds are — they are what a
+ * k3s estate's GitOps surface is written in.
+ *
+ * Produces (both groups map to the `K3s` namespace — see
+ * GROUP_NAMESPACE_OVERRIDES in crd/parser.ts):
+ *   K8s::K3s::HelmChart        → apiVersion: helm.cattle.io/v1, kind: HelmChart
+ *   K8s::K3s::HelmChartConfig  → apiVersion: helm.cattle.io/v1, kind: HelmChartConfig
+ *   K8s::K3s::Addon            → apiVersion: k3s.cattle.io/v1,  kind: Addon
+ *
+ * The pin is k3s v1.36.3+k3s1 (the release the k3s lexicon pins), but the k3s
+ * repo itself publishes no CRD YAMLs — its manifests/ directory carries only
+ * the bundled charts, and the API types live in dependency repos. The URLs
+ * below point at the exact versions that release vendors in its go.mod:
+ *   github.com/k3s-io/helm-controller v0.17.7  (helm.cattle.io CRDs)
+ *   github.com/k3s-io/api             v0.1.4   (k3s.cattle.io CRDs)
+ * When bumping, re-read go.mod at the new k3s tag and move both pins together.
+ *
+ * k3s-io/api also ships an ETCDSnapshotFile CRD — deliberately left out. It is
+ * status-only controller bookkeeping (the server writes them to describe
+ * snapshots it took); nothing an author would declare.
+ *
+ * Controller install: none — both controllers are embedded in the k3s binary.
+ */
+const K3S_HELM_CONTROLLER_VERSION = "v0.17.7"; // vendored by k3s v1.36.3+k3s1
+const K3S_API_VERSION = "v0.1.4"; // vendored by k3s v1.36.3+k3s1
+const K3S_HELM_CONTROLLER_CRD_BASE = `https://raw.githubusercontent.com/k3s-io/helm-controller/${K3S_HELM_CONTROLLER_VERSION}/pkg/crds/yaml/generated`;
+const K3S_API_CRD_BASE = `https://raw.githubusercontent.com/k3s-io/api/${K3S_API_VERSION}/pkg/crds/yaml/generated`;
+
 export const CRD_SOURCES: CRDSource[] = [
   { type: "url", url: `${KUBERAY_CRD_BASE}/ray.io_rayclusters.yaml` },
   { type: "url", url: `${KUBERAY_CRD_BASE}/ray.io_rayjobs.yaml` },
@@ -335,6 +369,9 @@ export const CRD_SOURCES: CRDSource[] = [
     url: FLUX_OPERATOR_INSTALL,
     kinds: ["FluxInstance", "FluxReport", "ResourceSet", "ResourceSetInputProvider"],
   },
+  { type: "url", url: `${K3S_HELM_CONTROLLER_CRD_BASE}/helm.cattle.io_helmcharts.yaml` },
+  { type: "url", url: `${K3S_HELM_CONTROLLER_CRD_BASE}/helm.cattle.io_helmchartconfigs.yaml` },
+  { type: "url", url: `${K3S_API_CRD_BASE}/k3s.cattle.io_addons.yaml` },
   {
     type: "helm",
     chart: KUBEMICROVM_CHART,

package/src/crd/parser.ts

@@ -52,6 +52,12 @@ const GROUP_NAMESPACE_OVERRIDES: Record<string, string> = {
   // Not `Secrets`: `K8s::Secrets::InfisicalSecret` reads like a core Secret,
   // and `K8s::Core::Secret` is right there to be confused with.
   "secrets.infisical.com": "Infisical",
+  // k3s's bundled controllers ship under two groups but are one thing to an
+  // author — the k3s auto-deploy surface. The first-segment rule would give
+  // `K8s::Helm::HelmChart`, which reads like it belongs to the helm lexicon,
+  // and would split HelmChart from the Addon that tracks its deployment.
+  "helm.cattle.io": "K3s",
+  "k3s.cattle.io": "K3s",
 };
 
 /**