@intentius/chant-lexicon-k3d 0.0.1

package/src/plugin.ts

@@ -0,0 +1,114 @@
+import type { LexiconPlugin, SkillDefinition, IntrinsicDef } from "@intentius/chant/lexicon";
+import type { LintRule } from "@intentius/chant/lint/rule";
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+import type { CompletionContext, CompletionItem, HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import type { McpToolContribution, McpResourceContribution } from "@intentius/chant/mcp/types";
+import { LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+import { k3dSerializer } from "./serializer";
+import { rules } from "./lint/rules";
+import { postSynthChecks } from "./lint/post-synth";
+import { k3dAuditCatalog } from "./lint/audit-catalog";
+import { completions } from "./lsp/completions";
+import { hover } from "./lsp/hover";
+
+/**
+ * k3d lexicon plugin.
+ *
+ * Implements all required LexiconPlugin lifecycle methods.
+ */
+export const k3dPlugin: LexiconPlugin = {
+  name: "k3d",
+  serializer: k3dSerializer,
+
+  /**
+   * The marker is stamped as Docker labels on every node via
+   * `options.runtime.labels` (the serializer does this when a build carries
+   * ownership) and read back through `docker inspect` — k3d's own list
+   * output does not expose custom labels (#1412, verified live). Labels
+   * survive `k3d cluster stop`/`start`.
+   */
+  ownershipChannel: {
+    keys: LABEL_OWNERSHIP_KEYS,
+    reads: ["describeResources"],
+  },
+
+  async describeResources(options) {
+    const { describeResources } = await import("./describe-resources");
+    return describeResources(options);
+  },
+
+  // ── Required lifecycle methods ────────────────────────────────
+
+  async generate(options?: { verbose?: boolean }): Promise<void> {
+    const { generate } = await import("./codegen/generate");
+    await generate(options);
+  },
+
+  async validate(options?: { verbose?: boolean }): Promise<void> {
+    const { validate } = await import("./validate");
+    const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+    const result = await validate();
+    printValidationResult(result);
+  },
+
+  async coverage(options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
+    // TODO: Implement coverage analysis
+    console.error("Coverage analysis not yet implemented");
+  },
+
+  async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
+    const { packageLexicon } = await import("./codegen/package");
+    const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+    const { join, dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+
+    const { spec, stats } = await packageLexicon(options);
+    const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    writeBundleSpec(spec, join(pkgDir, "dist"));
+
+    console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+  },
+
+  // ── Optional extensions ────────────────────────────────────
+
+  lintRules() {
+    return rules;
+  },
+
+  postSynthChecks() {
+    return postSynthChecks;
+  },
+
+  auditCatalog() {
+    return k3dAuditCatalog;
+  },
+
+  skills() {
+    return []; // TODO: Add skills
+  },
+
+  mcpTools() {
+    return []; // TODO: Implement MCP tools
+  },
+
+  mcpResources() {
+    return []; // TODO: Implement MCP resources
+  },
+
+  detectTemplate(data: unknown) {
+    return false; // TODO: Detect if a template belongs to this lexicon
+  },
+
+  completionProvider(ctx: CompletionContext) {
+    return completions(ctx);
+  },
+
+  hoverProvider(ctx: HoverContext) {
+    return hover(ctx);
+  },
+
+  async docs(options?) {
+    const { generateDocs } = await import("./codegen/docs");
+    return generateDocs(options);
+  },
+};

package/src/serializer.acceptance.test.ts

@@ -0,0 +1,94 @@
+/**
+ * The acceptance test is k3d, not a fixture (#1408).
+ *
+ * A fixture comparison proves the serializer matches what someone wrote down.
+ * This proves the artifact is a file the native tool consumes: build a
+ * declaration, serialize it, hand the output to `k3d cluster create --config`,
+ * assert a cluster comes up, delete it.
+ *
+ * Skipped, with the reason visible in the runner, when Docker or k3d is
+ * absent — CI may have neither. The test's own config pins the safe
+ * kubeconfig options regardless of serializer defaults: a test that switches
+ * the developer's active context is exactly the surprise this lexicon exists
+ * to make explicit.
+ */
+
+import { execSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, it } from "vitest";
+import { k3dSerializer } from "./serializer";
+import { Cluster, K3dOptions, KubeconfigOptions, Options } from "./generated/index";
+
+function available(cmd: string): boolean {
+  try {
+    execSync(cmd, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const hasK3d = available("k3d version");
+const hasDocker = available("docker info");
+const enabled = hasK3d && hasDocker;
+const skipReason = !hasK3d ? "k3d is not installed" : !hasDocker ? "Docker is not running" : "";
+
+// Distinctive name; the deletes below run even on failure so a failed run
+// does not leave a Docker network and containers behind on someone's laptop.
+const CLUSTER = `chant-k3d-accept-${process.pid}`;
+
+describe.skipIf(!enabled)(`k3d accepts the emitted config${skipReason ? ` (skipped: ${skipReason})` : ""}`, () => {
+  afterAll(() => {
+    try {
+      execSync(`k3d cluster delete ${CLUSTER}`, { stdio: "ignore" });
+    } catch {
+      // already gone — deletion is the success case here
+    }
+  });
+
+  it("creates a working cluster from serializer output, then tears it down", () => {
+    const declaration = new Cluster({
+      metadata: { name: CLUSTER },
+      servers: 1,
+      agents: 0,
+      options: new Options({
+        k3d: new K3dOptions({ disableLoadbalancer: true, wait: true }),
+        kubeconfig: new KubeconfigOptions({
+          updateDefaultKubeconfig: false,
+          switchCurrentContext: false,
+        }),
+      }),
+    });
+
+    const result = k3dSerializer.serialize(new Map([["acceptance", declaration]]));
+    const yaml = typeof result === "string" ? result : result.primary;
+
+    const dir = mkdtempSync(join(tmpdir(), "chant-k3d-accept-"));
+    const configPath = join(dir, "cluster.yaml");
+    writeFileSync(configPath, yaml);
+
+    try {
+      const before = execSync("kubectl config current-context 2>/dev/null || true").toString().trim();
+
+      execSync(`k3d cluster create --config ${configPath}`, {
+        stdio: "pipe",
+        timeout: 240_000,
+      });
+
+      const listed = execSync(`k3d cluster list ${CLUSTER} --no-headers`).toString();
+      expect(listed).toContain(CLUSTER);
+
+      // The safe kubeconfig options held: the active context is what it was.
+      const after = execSync("kubectl config current-context 2>/dev/null || true").toString().trim();
+      expect(after).toBe(before);
+
+      execSync(`k3d cluster delete ${CLUSTER}`, { stdio: "pipe", timeout: 120_000 });
+      const gone = execSync(`k3d cluster list -o json`).toString();
+      expect(gone).not.toContain(`"${CLUSTER}"`);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }, 300_000);
+});

package/src/serializer.test.ts

@@ -0,0 +1,189 @@
+import { describe, expect, it } from "vitest";
+import { load } from "js-yaml";
+import { k3dSerializer } from "./serializer";
+import {
+  Cluster,
+  KubeconfigOptions,
+  Options,
+  Port,
+  RuntimeOptions,
+  Volume,
+} from "./generated/index";
+import type { Declarable } from "@intentius/chant/declarable";
+
+function serializeOne(entities: Record<string, Declarable>): {
+  text: string;
+  doc: Record<string, unknown>;
+} {
+  const result = k3dSerializer.serialize(new Map(Object.entries(entities)));
+  const text = typeof result === "string" ? result : result.primary;
+  return { text, doc: load(text) as Record<string, unknown> };
+}
+
+describe("k3d serializer", () => {
+  it("has the k3d name and K3D rule prefix", () => {
+    expect(k3dSerializer.name).toBe("k3d");
+    expect(k3dSerializer.rulePrefix).toBe("K3D");
+  });
+
+  it("emits apiVersion and kind literals even when undeclared", () => {
+    const { doc } = serializeOne({ probe: new Cluster({ servers: 1 }) });
+    expect(doc.apiVersion).toBe("k3d.io/v1alpha5");
+    expect(doc.kind).toBe("Simple");
+  });
+
+  it("defaults metadata.name from the entity name and never overrides an explicit one", () => {
+    const { doc } = serializeOne({ "my-cluster": new Cluster({ servers: 1 }) });
+    expect((doc.metadata as Record<string, unknown>).name).toBe("my-cluster");
+
+    const { doc: explicit } = serializeOne({
+      probe: new Cluster({ servers: 1, metadata: { name: "elsewhere" } }),
+    });
+    expect((explicit.metadata as Record<string, unknown>).name).toBe("elsewhere");
+  });
+
+  it("keeps agents: 0 — zero is meaningful, not falsy", () => {
+    const { text, doc } = serializeOne({ probe: new Cluster({ servers: 1, agents: 0 }) });
+    expect(doc.agents).toBe(0);
+    expect(text).toMatch(/^agents: 0$/m);
+  });
+
+  it("keeps booleans booleans", () => {
+    const { text } = serializeOne({
+      probe: new Cluster({
+        servers: 1,
+        options: new Options({
+          kubeconfig: new KubeconfigOptions({
+            updateDefaultKubeconfig: false,
+            switchCurrentContext: false,
+          }),
+        }),
+      }),
+    });
+    expect(text).toContain("updateDefaultKubeconfig: false");
+    expect(text).not.toContain('"false"');
+    expect(text).not.toContain("'false'");
+  });
+
+  it("injects chant's safe kubeconfig defaults when the declaration says nothing", () => {
+    const { doc } = serializeOne({ probe: new Cluster({ servers: 1 }) });
+    const options = doc.options as Record<string, Record<string, unknown>>;
+    expect(options.kubeconfig).toEqual({
+      updateDefaultKubeconfig: false,
+      switchCurrentContext: false,
+    });
+  });
+
+  it("passes a declared kubeconfig block through exactly as written", () => {
+    const { doc } = serializeOne({
+      probe: new Cluster({
+        servers: 1,
+        options: new Options({
+          kubeconfig: new KubeconfigOptions({ updateDefaultKubeconfig: true }),
+        }),
+      }),
+    });
+    const options = doc.options as Record<string, Record<string, unknown>>;
+    expect(options.kubeconfig).toEqual({ updateDefaultKubeconfig: true });
+  });
+
+  it("passes nodeFilters through untouched, k3d syntax and all", () => {
+    const { doc } = serializeOne({
+      probe: new Cluster({
+        servers: 1,
+        ports: [new Port({ port: "8080:80", nodeFilters: ["loadbalancer"] })],
+        volumes: [new Volume({ volume: "/tmp/x:/x", nodeFilters: ["server:0", "agent:*"] })],
+      }),
+    });
+    const ports = doc.ports as Array<Record<string, unknown>>;
+    expect(ports[0].nodeFilters).toEqual(["loadbalancer"]);
+    const volumes = doc.volumes as Array<Record<string, unknown>>;
+    expect(volumes[0].nodeFilters).toEqual(["server:0", "agent:*"]);
+  });
+
+  it("round-trips: emitted YAML parses back to the declared values", () => {
+    const declared = {
+      servers: 3,
+      agents: 2,
+      image: "rancher/k3s:v1.31.4-k3s1",
+      options: new Options({
+        k3d: { disableLoadbalancer: true },
+        runtime: new RuntimeOptions({
+          labels: [
+            { label: "app.kubernetes.io/managed-by=chant", nodeFilters: ["server:*"] },
+          ],
+        }),
+      }),
+    };
+    const { doc } = serializeOne({ probe: new Cluster(declared) });
+    expect(doc.servers).toBe(3);
+    expect(doc.agents).toBe(2);
+    expect(doc.image).toBe("rancher/k3s:v1.31.4-k3s1");
+    const options = doc.options as Record<string, unknown>;
+    expect((options.k3d as Record<string, unknown>).disableLoadbalancer).toBe(true);
+    const runtime = options.runtime as Record<string, unknown>;
+    expect(runtime.labels).toEqual([
+      { label: "app.kubernetes.io/managed-by=chant", nodeFilters: ["server:*"] },
+    ]);
+  });
+
+  it("stamps ownership as runtime labels on every node when the build carries a marker", () => {
+    const result = k3dSerializer.serialize(
+      new Map<string, Declarable>([["probe", new Cluster({ servers: 1 })]]),
+      undefined,
+      { ownership: { stack: "fountain", env: "local" } },
+    );
+    const text = typeof result === "string" ? result : result.primary;
+    const doc = load(text) as Record<string, unknown>;
+    const runtime = (doc.options as Record<string, Record<string, unknown>>).runtime;
+    expect(runtime.labels).toEqual(
+      expect.arrayContaining([
+        { label: "app.kubernetes.io/managed-by=chant", nodeFilters: ["all"] },
+        { label: "chant.intentius.io/stack=fountain", nodeFilters: ["all"] },
+        { label: "chant.intentius.io/env=local", nodeFilters: ["all"] },
+      ]),
+    );
+  });
+
+  it("an author's own label with the marker key wins over the stamp", () => {
+    const result = k3dSerializer.serialize(
+      new Map<string, Declarable>([
+        [
+          "probe",
+          new Cluster({
+            servers: 1,
+            options: new Options({
+              runtime: new RuntimeOptions({
+                labels: [{ label: "chant.intentius.io/stack=mine", nodeFilters: ["server:0"] }],
+              }),
+            }),
+          }),
+        ],
+      ]),
+      undefined,
+      { ownership: { stack: "fountain", env: "local" } },
+    );
+    const text = typeof result === "string" ? result : result.primary;
+    const doc = load(text) as Record<string, unknown>;
+    const labels = (doc.options as Record<string, Record<string, unknown>>).runtime.labels as Array<
+      Record<string, unknown>
+    >;
+    const stackLabels = labels.filter((l) => String(l.label).startsWith("chant.intentius.io/stack="));
+    expect(stackLabels).toEqual([{ label: "chant.intentius.io/stack=mine", nodeFilters: ["server:0"] }]);
+  });
+
+  it("emits one document per cluster: first primary, the rest in files", () => {
+    const result = k3dSerializer.serialize(
+      new Map<string, Declarable>([
+        ["first", new Cluster({ servers: 1 })],
+        ["second", new Cluster({ servers: 1 })],
+      ]),
+    );
+    expect(typeof result).not.toBe("string");
+    if (typeof result !== "string") {
+      expect(result.primary).toContain("name: first");
+      expect(Object.keys(result.files ?? {})).toEqual(["second.k3d.yaml"]);
+      expect(result.files?.["second.k3d.yaml"]).toContain("name: second");
+    }
+  });
+});

package/src/serializer.ts

@@ -0,0 +1,202 @@
+/**
+ * k3d SimpleConfig YAML serializer.
+ *
+ * Emits the config file `k3d cluster create --config` consumes verbatim —
+ * the walk-away artifact that justifies a lexicon here at all. One YAML
+ * document per declared Cluster: the first is the primary output, any
+ * further clusters land in files[] keyed `<name>.k3d.yaml`.
+ *
+ * Three things are non-negotiable in the output (#1408):
+ *
+ *   - `apiVersion` and `kind` are literal schema properties, not derived
+ *     from a type name. They default when undeclared and are never dropped.
+ *   - Booleans stay booleans and zero stays zero. `agents: 0` is the normal
+ *     local shape and `updateDefaultKubeconfig: "false"` is truthy.
+ *   - `nodeFilters` pass through untouched — they are k3d's own syntax
+ *     (`server:0`, `agent:*`, `loadbalancer`) and rewriting them here would
+ *     be inventing a dialect.
+ *
+ * ## The kubeconfig default is chant's, not upstream's
+ *
+ * When a declaration says nothing about `options.kubeconfig`, the emitted
+ * config pins `updateDefaultKubeconfig: false` and `switchCurrentContext:
+ * false` — the opposite of k3d's own defaults, chosen deliberately (#1411):
+ * a tool that reconciles infrastructure must not rewrite ~/.kube/config or
+ * repoint the caller's shell as a side effect. Injecting the values into the
+ * artifact rather than relying on activity flags means the emitted YAML says
+ * on its face what creating the cluster will do, and `k3d --config` applied
+ * by hand behaves identically. A declaration that sets `options.kubeconfig`
+ * itself — either key — is passed through exactly as written; upstream
+ * defaults then apply to whatever it left unset, because a partially
+ * explicit block is the author taking the wheel.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import type { Serializer, SerializerResult, SerializeContext } from "@intentius/chant/serializer";
+import type { LexiconOutput } from "@intentius/chant/lexicon-output";
+import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
+import { emitYAML } from "@intentius/chant/yaml";
+import { ownershipEntries, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+
+const CLUSTER_TYPE = "K3d::Cluster";
+const API_VERSION = "k3d.io/v1alpha5";
+const KIND = "Simple";
+
+/**
+ * Top-level key order, matching the schema's own property order so a chant
+ * emission diffs cleanly against upstream's documented examples.
+ */
+const KEY_ORDER = [
+  "apiVersion",
+  "kind",
+  "metadata",
+  "servers",
+  "agents",
+  "kubeAPI",
+  "image",
+  "network",
+  "subnet",
+  "token",
+  "volumes",
+  "ports",
+  "files",
+  "env",
+  "registries",
+  "hostAliases",
+  "options",
+];
+
+const visitor: SerializerVisitor = {
+  attrRef: (name) => name,
+  resourceRef: (name) => name,
+  propertyDeclarable: (entity, walk) => {
+    if (!isResourceDeclarable(entity) || typeof entity.props !== "object" || entity.props === null) {
+      return undefined;
+    }
+    const props = entity.props as Record<string, unknown>;
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(props)) {
+      if (value !== undefined) result[key] = walk(value);
+    }
+    return result;
+  },
+};
+
+/**
+ * Stamp the ownership marker as Docker labels on every node, via
+ * `options.runtime.labels` (#1412). The labels survive `k3d cluster stop`/
+ * `start` and are readable back through `docker inspect` — verified live;
+ * `k3d cluster list -o json` does not expose custom labels, so the read
+ * side goes to Docker. An author's own label with the same key wins.
+ */
+function stampOwnership(
+  options: Record<string, unknown>,
+  ownership: NonNullable<SerializeContext["ownership"]>,
+): void {
+  const runtime = { ...((options.runtime as Record<string, unknown> | undefined) ?? {}) };
+  const labels = Array.isArray(runtime.labels) ? [...(runtime.labels as unknown[])] : [];
+  const present = new Set(
+    labels
+      .map((l) => (typeof l === "object" && l !== null ? (l as Record<string, unknown>).label : undefined))
+      .filter((l): l is string => typeof l === "string")
+      .map((l) => l.split("=")[0]),
+  );
+  for (const [key, value] of Object.entries(ownershipEntries(LABEL_OWNERSHIP_KEYS, ownership))) {
+    if (present.has(key)) continue;
+    labels.push({ label: `${key}=${value}`, nodeFilters: ["all"] });
+  }
+  runtime.labels = labels;
+  options.runtime = runtime;
+}
+
+function clusterDocument(
+  name: string,
+  cluster: Declarable,
+  entityNames: Map<Declarable, string>,
+  context?: SerializeContext,
+): Record<string, unknown> {
+  const raw = (isResourceDeclarable(cluster) ? cluster.props : {}) as Record<string, unknown>;
+  const props = (walkValue(raw, entityNames, visitor) ?? {}) as Record<string, unknown>;
+
+  const doc: Record<string, unknown> = {};
+  doc.apiVersion = props.apiVersion ?? API_VERSION;
+  doc.kind = props.kind ?? KIND;
+
+  // metadata.name defaults from the entity's declared name — the schema wants
+  // a hostname there and the export name is the one identity the author has
+  // already chosen. An explicit metadata wins untouched.
+  const metadata = props.metadata as Record<string, unknown> | undefined;
+  doc.metadata = metadata?.name !== undefined ? metadata : { ...(metadata ?? {}), name: name };
+
+  for (const key of KEY_ORDER) {
+    if (key === "apiVersion" || key === "kind" || key === "metadata" || key === "options") continue;
+    if (props[key] !== undefined) doc[key] = props[key];
+  }
+
+  const options = { ...((props.options as Record<string, unknown> | undefined) ?? {}) };
+  if (options.kubeconfig === undefined) {
+    // chant's deliberate inversion of upstream's true/true — see module doc.
+    options.kubeconfig = { updateDefaultKubeconfig: false, switchCurrentContext: false };
+  }
+  if (context?.ownership) stampOwnership(options, context.ownership);
+  doc.options = options;
+
+  // Anything declared outside the known order still emits — the schema is
+  // additionalProperties: false, so this only ever carries what a future
+  // schema version adds before KEY_ORDER learns about it.
+  for (const [key, value] of Object.entries(props)) {
+    if (KEY_ORDER.includes(key) || value === undefined) continue;
+    doc[key] = value;
+  }
+
+  return doc;
+}
+
+function emitDocument(doc: Record<string, unknown>): string {
+  const sections: string[] = [];
+  for (const [key, value] of Object.entries(doc)) {
+    if (value === undefined) continue;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      sections.push(`${key}: ${scalar(value)}`);
+    } else {
+      sections.push(`${key}:` + emitYAML(value, 1));
+    }
+  }
+  return sections.join("\n") + "\n";
+}
+
+function scalar(value: string | number | boolean): string {
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return String(value);
+  if (/[:#\[\]{}|>&*!%@`'"]|^[\s\d]|\s$|^$|^(true|false|null|yes|no|on|off)$/i.test(value)) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
+
+export const k3dSerializer: Serializer = {
+  name: "k3d",
+  rulePrefix: "K3D",
+
+  serialize(
+    entities: Map<string, Declarable>,
+    _outputs?: LexiconOutput[],
+    context?: SerializeContext,
+  ): string | SerializerResult {
+    const entityNames = new Map<Declarable, string>();
+    for (const [name, entity] of entities) entityNames.set(entity, name);
+
+    const clusters = [...entities].filter(([, e]) => e.entityType === CLUSTER_TYPE);
+
+    let primary = "";
+    const files: Record<string, string> = {};
+    clusters.forEach(([name, cluster], i) => {
+      const content = emitDocument(clusterDocument(name, cluster, entityNames, context));
+      if (i === 0) primary = content;
+      else files[`${name}.k3d.yaml`] = content;
+    });
+
+    return Object.keys(files).length > 0 ? { primary, files } : primary;
+  },
+};

package/src/spec/fetch.ts

@@ -0,0 +1,66 @@
+/**
+ * k3d SimpleConfig schema fetching — downloads the JSON Schema and
+ * caches it locally.
+ */
+
+import { join } from "path";
+import { homedir } from "os";
+import { fetchWithCache, clearCacheFile } from "@intentius/chant/codegen/fetch";
+
+/**
+ * Pinned upstream k3d release.
+ *
+ * The schema is fetched from the tagged source tree, not a moving branch:
+ * https://raw.githubusercontent.com/k3d-io/k3d/v5.9.0/pkg/config/v1alpha5/schema.json
+ *
+ * v1alpha5 is the config apiVersion this lexicon models. Older config
+ * versions (v1alpha2..v1alpha4) each ship their own migrate.go upstream —
+ * k3d migrates old configs itself, so modelling superseded versions here
+ * would duplicate upstream's job. Bump this constant (and re-generate)
+ * when adopting a newer k3d release.
+ */
+export const K3D_VERSION = "v5.9.0";
+
+const SCHEMA_URL = `https://raw.githubusercontent.com/k3d-io/k3d/${K3D_VERSION}/pkg/config/v1alpha5/schema.json`;
+
+/**
+ * Get the cache file path for the k3d schema.
+ */
+export function getCachePath(): string {
+  return join(homedir(), ".chant", `k3d-schema-${K3D_VERSION}.json`);
+}
+
+/**
+ * Fetch the k3d SimpleConfig JSON Schema.
+ * Uses local file caching with 24-hour TTL.
+ */
+export async function fetchConfigSchema(force?: boolean): Promise<Buffer> {
+  return fetchWithCache(
+    {
+      url: SCHEMA_URL,
+      cacheFile: getCachePath(),
+    },
+    force,
+  );
+}
+
+/**
+ * Fetch the config schema as a Map<typeName, Buffer> compatible with the
+ * generatePipeline fetchSchemas callback.
+ *
+ * Single document keyed by "K3d::Cluster" — the parse step splits it into
+ * multiple entities.
+ */
+export async function fetchSchemas(force?: boolean): Promise<Map<string, Buffer>> {
+  const data = await fetchConfigSchema(force);
+  const schemas = new Map<string, Buffer>();
+  schemas.set("K3d::Cluster", data);
+  return schemas;
+}
+
+/**
+ * Clear the cached schema file.
+ */
+export function clearCache(): void {
+  clearCacheFile(getCachePath());
+}