@intentius/chant-lexicon-k3s 0.44.3

package/src/plugin.ts

@@ -0,0 +1,129 @@
+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 { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { k3sSerializer } from "./serializer";
+import { rules } from "./lint/rules";
+import { postSynthChecks } from "./lint/post-synth";
+import { k3sAuditCatalog } from "./lint/audit-catalog";
+import { completions } from "./lsp/completions";
+import { hover } from "./lsp/hover";
+
+/**
+ * k3s lexicon plugin.
+ *
+ * Implements all required LexiconPlugin lifecycle methods.
+ */
+export const k3sPlugin: LexiconPlugin = {
+  name: "k3s",
+  serializer: k3sSerializer,
+
+  /**
+   * Where the upstream pin lives and where to look for a newer one, for
+   * the self-upgrade tooling (#523). k3s releases carry a `+k3s1` build
+   * suffix; the release tag is the version constant verbatim.
+   */
+  upstreamPin: {
+    file: "src/spec/fetch.ts",
+    pattern: /export const K3S_VERSION\s*=\s*"([^"]+)"/,
+    replace: (v: string, line: string) => line.replace(/= "[^"]+"/, `= "${v}"`),
+    upstream: { owner: "k3s-io", repo: "k3s", kind: "releases" },
+  },
+
+  // ── 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 k3sAuditCatalog;
+  },
+
+  skills() {
+    const skills: SkillDefinition[] = [];
+    const dir = dirname(fileURLToPath(import.meta.url));
+    const entries = [
+      {
+        file: "chant-k3s.md",
+        name: "chant-k3s",
+        description:
+          "Declare k3s host configuration — server/agent config.yaml and registries.yaml — as typed chant source",
+      },
+    ];
+    for (const entry of entries) {
+      try {
+        const content = readFileSync(join(dir, "skills", entry.file), "utf-8");
+        skills.push({ name: entry.name, description: entry.description, content });
+      } catch {
+        // skill file missing from a partial checkout — skip rather than throw
+      }
+    }
+    return 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,137 @@
+/**
+ * The acceptance test is k3s, not a fixture (#1600).
+ *
+ * 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, mount the output into the pinned rancher/k3s
+ * image, and assert `k3s server --config` comes up far enough to accept it
+ * — the apiserver answering on the containerized cluster is the pass.
+ *
+ * A config k3s rejects must fail: the negative case feeds a config with an
+ * unknown key and asserts the process exits with the flag-parse error
+ * rather than starting.
+ *
+ * Skipped, with the reason visible in the runner, when Docker is absent —
+ * CI may not have it. On-demand, like the gitlab/forgejo runtime E2Es.
+ */
+
+import { execSync, spawnSync } 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 { k3sSerializer } from "./serializer";
+import { Server } from "./generated/index";
+import { K3S_IMAGE_TAG } from "./spec/fetch";
+
+function available(cmd: string): boolean {
+  try {
+    execSync(cmd, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const hasDocker = available("docker info");
+const skipReason = hasDocker ? "" : "Docker is not running";
+
+const IMAGE = `rancher/k3s:${K3S_IMAGE_TAG}`;
+const CONTAINER = `chant-k3s-accept-${process.pid}`;
+
+function emit(entities: Map<string, unknown>): string {
+  const result = k3sSerializer.serialize(entities as never);
+  return typeof result === "string" ? result : result.primary;
+}
+
+describe.skipIf(!hasDocker)(
+  `k3s accepts the emitted config${skipReason ? ` (skipped: ${skipReason})` : ""}`,
+  () => {
+    afterAll(() => {
+      try {
+        execSync(`docker rm -f ${CONTAINER}`, { stdio: "ignore" });
+      } catch {
+        // already gone
+      }
+    });
+
+    it(
+      "boots a server from serializer output until the apiserver answers",
+      { timeout: 180_000 },
+      () => {
+        const yaml = emit(
+          new Map([
+            [
+              "acceptance",
+              new Server({
+                "write-kubeconfig-mode": "0644",
+                disable: ["traefik", "metrics-server"],
+                "node-label": ["chant-acceptance=true"],
+              }),
+            ],
+          ]),
+        );
+
+        const dir = mkdtempSync(join(tmpdir(), "chant-k3s-accept-"));
+        const configPath = join(dir, "config.yaml");
+        writeFileSync(configPath, yaml);
+
+        try {
+          execSync(
+            `docker run -d --privileged --name ${CONTAINER} ` +
+              `-v ${configPath}:/etc/rancher/k3s/config.yaml ` +
+              `${IMAGE} server`,
+            { stdio: "ignore" },
+          );
+
+          // Ready when the node registers with the label the config declared.
+          const deadline = Date.now() + 150_000;
+          let ready = false;
+          let lastOut = "";
+          while (Date.now() < deadline) {
+            const probe = spawnSync(
+              "docker",
+              ["exec", CONTAINER, "kubectl", "get", "nodes", "-l", "chant-acceptance=true", "--no-headers"],
+              { encoding: "utf-8" },
+            );
+            lastOut = probe.stdout ?? "";
+            if (probe.status === 0 && /\sReady\s/.test(lastOut)) {
+              ready = true;
+              break;
+            }
+            execSync("sleep 3");
+          }
+          expect(ready, `node never became Ready; last output: ${lastOut}`).toBe(true);
+        } finally {
+          rmSync(dir, { recursive: true, force: true });
+        }
+      },
+    );
+
+    it("fails fast on a config k3s rejects", { timeout: 60_000 }, () => {
+      const dir = mkdtempSync(join(tmpdir(), "chant-k3s-reject-"));
+      const configPath = join(dir, "config.yaml");
+      writeFileSync(configPath, "not-a-real-k3s-flag: true\n");
+
+      try {
+        const run = spawnSync(
+          "docker",
+          [
+            "run",
+            "--rm",
+            "--privileged",
+            "-v",
+            `${configPath}:/etc/rancher/k3s/config.yaml`,
+            IMAGE,
+            "server",
+          ],
+          { encoding: "utf-8", timeout: 45_000 },
+        );
+        expect(run.status).not.toBe(0);
+        expect(`${run.stdout}\n${run.stderr}`).toMatch(/not-a-real-k3s-flag|flag provided|unknown flag|invalid/i);
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+  },
+);

package/src/serializer.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, it } from "vitest";
+import { load } from "js-yaml";
+import { k3sSerializer } from "./serializer";
+import { Agent, Mirror, Registries, RegistryAuth, RegistryConfig, RegistryTLS, Server } from "./generated/index";
+import type { Declarable } from "@intentius/chant/declarable";
+import type { SerializerResult } from "@intentius/chant/serializer";
+
+function serializeOne(entities: Record<string, Declarable>): {
+  text: string;
+  doc: Record<string, unknown>;
+} {
+  const result = k3sSerializer.serialize(new Map(Object.entries(entities)));
+  const text = typeof result === "string" ? result : result.primary;
+  return { text, doc: load(text) as Record<string, unknown> };
+}
+
+describe("k3s serializer", () => {
+  it("has the k3s name and K3S rule prefix", () => {
+    expect(k3sSerializer.name).toBe("k3s");
+    expect(k3sSerializer.rulePrefix).toBe("K3S");
+  });
+
+  it("serializes an empty map to an empty string", () => {
+    expect(k3sSerializer.serialize(new Map())).toBe("");
+  });
+
+  it("emits a server config k3s consumes verbatim — flag names as keys", () => {
+    const { doc } = serializeOne({
+      server: new Server({
+        "cluster-init": true,
+        "tls-san": ["10.0.0.10", "cp.example.com"],
+        "disable": ["traefik"],
+        "write-kubeconfig-mode": "0644",
+      }),
+    });
+    expect(doc["cluster-init"]).toBe(true);
+    expect(doc["tls-san"]).toEqual(["10.0.0.10", "cp.example.com"]);
+    expect(doc.disable).toEqual(["traefik"]);
+    expect(doc["write-kubeconfig-mode"]).toBe("0644");
+  });
+
+  it("leads with the identity-and-join block, then alphabetical", () => {
+    const { text } = serializeOne({
+      agent: new Agent({
+        "node-label": ["tier=edge"],
+        server: "https://cp.example.com:6443",
+        "token-file": "/etc/rancher/k3s/token",
+        "data-dir": "/var/lib/rancher/k3s",
+      }),
+    });
+    const keys = text
+      .split("\n")
+      .filter((l) => /^[a-z]/.test(l))
+      .map((l) => l.split(":")[0]);
+    expect(keys).toEqual(["server", "token-file", "data-dir", "node-label"]);
+  });
+
+  it("keeps booleans and zero — 0 is a value, not an absence", () => {
+    const { doc } = serializeOne({
+      server: new Server({ "disable-agent": false, "lb-server-port": 0 }),
+    });
+    expect(doc["disable-agent"]).toBe(false);
+    expect(doc["lb-server-port"]).toBe(0);
+  });
+
+  it("accepts a single string where the flag takes a list", () => {
+    const { doc } = serializeOne({
+      server: new Server({ "tls-san": "cp.example.com" }),
+    });
+    expect(doc["tls-san"]).toBe("cp.example.com");
+  });
+
+  it("emits one document per config: first primary, the rest in files", () => {
+    const result = k3sSerializer.serialize(
+      new Map<string, Declarable>([
+        ["cp", new Server({ "cluster-init": true })],
+        ["worker", new Agent({ server: "https://cp:6443" })],
+      ]),
+    ) as SerializerResult;
+    expect(typeof result).toBe("object");
+    expect(result.primary).toContain("cluster-init: true");
+    expect(Object.keys(result.files ?? {})).toEqual(["worker.config.yaml"]);
+    expect(result.files?.["worker.config.yaml"]).toContain("server:");
+  });
+
+  it("emits registries.yaml beside a config, and as primary when alone", () => {
+    const registries = new Registries({
+      mirrors: { "docker.io": new Mirror({ endpoint: ["https://mirror.example.com"] }) },
+    });
+    const beside = k3sSerializer.serialize(
+      new Map<string, Declarable>([
+        ["cp", new Server({ "cluster-init": true })],
+        ["registries", registries],
+      ]),
+    ) as SerializerResult;
+    expect(Object.keys(beside.files ?? {})).toEqual(["registries.yaml"]);
+    const regDoc = load(beside.files!["registries.yaml"]) as Record<string, unknown>;
+    expect((regDoc.mirrors as Record<string, unknown>)["docker.io"]).toEqual({
+      endpoint: ["https://mirror.example.com"],
+    });
+
+    const { doc } = serializeOne({ registries });
+    expect(doc.mirrors).toBeDefined();
+  });
+
+  it("walks nested property entities into plain maps", () => {
+    const { doc } = serializeOne({
+      registries: new Registries({
+        configs: {
+          "registry.example.com": new RegistryConfig({
+            auth: new RegistryAuth({ username: "puller" }),
+            tls: new RegistryTLS({ ca_file: "/etc/ssl/registry-ca.pem" }),
+          }),
+        },
+      }),
+    });
+    const config = (doc.configs as Record<string, Record<string, unknown>>)["registry.example.com"];
+    expect(config.auth).toEqual({ username: "puller" });
+    expect(config.tls).toEqual({ ca_file: "/etc/ssl/registry-ca.pem" });
+  });
+
+  it("skips property entities as standalone documents", () => {
+    const result = k3sSerializer.serialize(
+      new Map<string, Declarable>([
+        ["cp", new Server({ "cluster-init": true })],
+        ["stray", new RegistryAuth({ username: "puller" }) as unknown as Declarable],
+      ]),
+    );
+    const text = typeof result === "string" ? result : (result as SerializerResult).primary;
+    expect(text).not.toContain("username");
+  });
+
+  it("stamps ownership into node-label when the build carries a marker", () => {
+    const result = k3sSerializer.serialize(
+      new Map<string, Declarable>([["cp", new Server({ "cluster-init": true })]]),
+      undefined,
+      { ownership: { stack: "fountain", env: "local" } },
+    );
+    const text = typeof result === "string" ? result : (result as SerializerResult).primary;
+    const doc = load(text) as Record<string, unknown>;
+    expect(doc["node-label"]).toEqual(
+      expect.arrayContaining([
+        "app.kubernetes.io/managed-by=chant",
+        "chant.intentius.io/stack=fountain",
+        "chant.intentius.io/env=local",
+      ]),
+    );
+  });
+
+  it("never overwrites an author's own label with the marker", () => {
+    const result = k3sSerializer.serialize(
+      new Map<string, Declarable>([
+        ["cp", new Server({ "node-label": ["chant.intentius.io/stack=mine"] })],
+      ]),
+      undefined,
+      { ownership: { stack: "fountain", env: "local" } },
+    );
+    const text = typeof result === "string" ? result : (result as SerializerResult).primary;
+    const doc = load(text) as Record<string, unknown>;
+    const stackLabels = (doc["node-label"] as string[]).filter((l) =>
+      l.startsWith("chant.intentius.io/stack="),
+    );
+    expect(stackLabels).toEqual(["chant.intentius.io/stack=mine"]);
+  });
+
+  it("quotes scalars YAML would otherwise mangle", () => {
+    const { doc } = serializeOne({
+      agent: new Agent({ server: "https://cp.example.com:6443" }),
+    });
+    expect(doc.server).toBe("https://cp.example.com:6443");
+  });
+});

package/src/serializer.ts

@@ -0,0 +1,191 @@
+/**
+ * k3s config YAML serializer.
+ *
+ * Emits the files k3s consumes verbatim — the walk-away artifacts that
+ * justify a lexicon here at all (#1600):
+ *
+ *   K3s::Server / K3s::Agent → config.yaml   (`k3s server --config <file>`)
+ *   K3s::Registries          → registries.yaml
+ *
+ * One document per declared entity: the first config is the primary
+ * output, every further entity lands in files[] keyed `<name>.config.yaml`
+ * / `<name>.registries.yaml`. A config.yaml's keys are exactly the CLI
+ * flag names, so the emitted file diffs cleanly against any hand-written
+ * one and `k3s check-config` style tooling sees nothing unusual.
+ *
+ * ## Ownership rides node-label (#1603)
+ *
+ * config.yaml has no free-form metadata channel, but `node-label` is a
+ * first-class key on both server and agent and lands on the registered
+ * Node as ordinary Kubernetes labels. When a build carries ownership,
+ * the serializer appends the chant label pair to `node-label` — readable
+ * back through any kubectl against the cluster, and inert to k3s itself.
+ * An author's own label with the same key wins.
+ *
+ * ## What never appears
+ *
+ * `token` / `agent-token` literals are not part of the typed surface
+ * (#1601), and K3SC001 fails the build if one arrives through untyped
+ * props anyway. The file k3s reads secrets from is the file's business
+ * (`token-file`), not the artifact's.
+ */
+
+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";
+
+export const SERVER_TYPE = "K3s::Server";
+export const AGENT_TYPE = "K3s::Agent";
+export const REGISTRIES_TYPE = "K3s::Registries";
+
+/**
+ * Keys that lead the document; everything else follows alphabetically.
+ * The identity-and-join block first is how the documented examples read,
+ * so a chant emission diffs cleanly against them.
+ */
+const KEY_PRIORITY = [
+  "cluster-init",
+  "server",
+  "token-file",
+  "agent-token-file",
+  "data-dir",
+  "node-name",
+];
+
+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;
+  },
+};
+
+function orderedKeys(props: Record<string, unknown>): string[] {
+  const rest = Object.keys(props)
+    .filter((k) => !KEY_PRIORITY.includes(k))
+    .sort();
+  return [...KEY_PRIORITY.filter((k) => props[k] !== undefined), ...rest];
+}
+
+/**
+ * Append the ownership marker to `node-label`. The key survives into the
+ * registered Node's labels, which is the only durable channel a host
+ * config file has. An author-set key of the same name wins.
+ */
+function stampOwnership(
+  props: Record<string, unknown>,
+  ownership: NonNullable<SerializeContext["ownership"]>,
+): void {
+  const existing = props["node-label"];
+  const labels: string[] =
+    existing === undefined ? [] : Array.isArray(existing) ? [...(existing as string[])] : [String(existing)];
+  const present = new Set(labels.map((l) => String(l).split("=")[0]));
+  for (const [key, value] of Object.entries(ownershipEntries(LABEL_OWNERSHIP_KEYS, ownership))) {
+    if (present.has(key)) continue;
+    labels.push(`${key}=${value}`);
+  }
+  props["node-label"] = labels;
+}
+
+function configDocument(
+  entity: Declarable,
+  entityNames: Map<Declarable, string>,
+  context?: SerializeContext,
+): Record<string, unknown> {
+  const raw = (isResourceDeclarable(entity) ? entity.props : {}) as Record<string, unknown>;
+  const props = (walkValue(raw, entityNames, visitor) ?? {}) as Record<string, unknown>;
+  if (context?.ownership) stampOwnership(props, context.ownership);
+
+  const doc: Record<string, unknown> = {};
+  for (const key of orderedKeys(props)) {
+    if (props[key] !== undefined) doc[key] = props[key];
+  }
+  return doc;
+}
+
+function registriesDocument(
+  entity: Declarable,
+  entityNames: Map<Declarable, string>,
+): Record<string, unknown> {
+  const raw = (isResourceDeclarable(entity) ? entity.props : {}) as Record<string, unknown>;
+  const props = (walkValue(raw, entityNames, visitor) ?? {}) as Record<string, unknown>;
+  const doc: Record<string, unknown> = {};
+  // mirrors before configs, matching the documented examples.
+  if (props.mirrors !== undefined) doc.mirrors = props.mirrors;
+  if (props.configs !== undefined) doc.configs = props.configs;
+  for (const [key, value] of Object.entries(props)) {
+    if (key === "mirrors" || key === "configs" || 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 k3sSerializer: Serializer = {
+  name: "k3s",
+  rulePrefix: "K3S",
+
+  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 configs = [...entities].filter(
+      ([, e]) => e.entityType === SERVER_TYPE || e.entityType === AGENT_TYPE,
+    );
+    const registries = [...entities].filter(([, e]) => e.entityType === REGISTRIES_TYPE);
+
+    let primary = "";
+    const files: Record<string, string> = {};
+
+    configs.forEach(([name, entity], i) => {
+      const content = emitDocument(configDocument(entity, entityNames, context));
+      if (i === 0) primary = content;
+      else files[`${name}.config.yaml`] = content;
+    });
+
+    registries.forEach(([name, entity], i) => {
+      const content = emitDocument(registriesDocument(entity, entityNames));
+      if (primary === "" && i === 0 && configs.length === 0) primary = content;
+      else files[i === 0 && configs.length > 0 ? "registries.yaml" : `${name}.registries.yaml`] = content;
+    });
+
+    return Object.keys(files).length > 0 ? { primary, files } : primary;
+  },
+};