@intentius/chant-lexicon-k3s 0.44.3

package/src/skills/chant-k3s.md

@@ -0,0 +1,90 @@
+---
+skill: chant-k3s
+description: Declare k3s host configuration — server/agent config.yaml and registries.yaml — as typed chant source
+user-invocable: true
+---
+
+# k3s with chant
+
+The k3s lexicon declares the files k3s itself consumes: `config.yaml` for
+`k3s server` / `k3s agent`, and `registries.yaml` for the embedded
+containerd. The emitted files are exactly what the native tool accepts —
+drop them at `/etc/rancher/k3s/` (or pass `--config`) and chant is nowhere
+in sight.
+
+Config keys are the CLI flag names, verbatim. If `k3s server --help` shows
+`--write-kubeconfig-mode`, the declaration key is `"write-kubeconfig-mode"`.
+Quoted kebab-case keys are normal here.
+
+## Declaring a server
+
+```typescript
+import { Server } from "@intentius/chant-lexicon-k3s";
+
+export const controlPlane = new Server({
+  "cluster-init": true,                      // embedded etcd, first node
+  "tls-san": ["10.0.0.10", "cp.example.internal"],
+  "write-kubeconfig-mode": "0600",           // wider than 0644 trips K3S104
+  disable: ["traefik"],
+});
+```
+
+## Declaring an agent
+
+```typescript
+import { Agent } from "@intentius/chant-lexicon-k3s";
+
+export const worker = new Agent({
+  server: "https://cp.example.internal:6443", // required — K3S103 without it
+  "token-file": "/etc/rancher/k3s/agent-token",
+});
+```
+
+## The token boundary
+
+There is no `token` property, on purpose. The join secret reaches the node
+as a file (`token-file`, `agent-token-file`) or as `K3S_TOKEN` /
+`K3S_TOKEN_FILE` in the installer's environment — never as a value in
+source. A literal that arrives through raw props anyway fails K3S001 at
+lint and K3S101 at build. The same wall covers `etcd-s3-secret-key` and
+`etcd-s3-session-token`; use `etcd-s3-config-secret` (a Secret on the
+cluster) for snapshot-store credentials.
+
+## Private registries
+
+```typescript
+import { Mirror, Registries, RegistryConfig, RegistryTLS } from "@intentius/chant-lexicon-k3s";
+
+export const registries = new Registries({
+  mirrors: {
+    "docker.io": new Mirror({ endpoint: ["https://mirror.internal:5000"] }),
+  },
+  configs: {
+    "mirror.internal:5000": new RegistryConfig({
+      tls: new RegistryTLS({ ca_file: "/etc/ssl/certs/mirror-ca.pem" }),
+    }),
+  },
+});
+```
+
+Literal `auth.password` / `auth.token` fail K3S102; `insecure_skip_verify`
+warns via K3S105 — pin the CA instead.
+
+## Output shape
+
+One file per declared entity. The first Server/Agent config is the primary
+build output; further configs land beside it as `<name>.config.yaml`, and
+a Registries entity as `registries.yaml`. A build carrying an ownership
+marker stamps it into `node-label`, so the registered Node is attributable
+with any kubectl.
+
+## Rules
+
+| Rule | Severity | What it catches |
+|---|---|---|
+| K3S001 | error | literal `token` / `agent-token` in source |
+| K3S101 | error | a literal secret reaching the build (token, etcd S3 keys) |
+| K3S102 | error | literal registry credentials in registries.yaml |
+| K3S103 | error | an Agent with no `server` to join |
+| K3S104 | warning | kubeconfig written wider than 0644 |
+| K3S105 | warning | registry TLS verification disabled |

package/src/spec/fetch.ts

@@ -0,0 +1,80 @@
+/**
+ * k3s CLI flag-definition fetching — downloads the pinned Go sources that
+ * define the server and agent flag surfaces, and caches them locally.
+ *
+ * k3s publishes no JSON Schema for config.yaml. The config file's keys ARE
+ * the CLI flag names ("Every flag can be a config key", docs.k3s.io), and
+ * the flags are defined as urfave/cli struct literals in pkg/cli/cmds/.
+ * Those literals carry name, usage, default and hidden-ness, so the tagged
+ * source tree is the machine-readable spec (#1599) — the same channel the
+ * k3s binary itself is built from, pinned the same way k3d pins its
+ * schema.json.
+ */
+
+import { join } from "path";
+import { homedir } from "os";
+import { fetchWithCache, clearCacheFile } from "@intentius/chant/codegen/fetch";
+
+/**
+ * Pinned upstream k3s release.
+ *
+ * Bump this constant (and re-generate) when adopting a newer k3s release.
+ * The acceptance test's rancher/k3s image tag derives from it (`+` → `-`).
+ */
+export const K3S_VERSION = "v1.36.3+k3s1";
+
+/** Docker image tag form of the pin: `+` is not legal in a tag. */
+export const K3S_IMAGE_TAG = K3S_VERSION.replace("+", "-");
+
+/**
+ * The files that define flags reachable from the server and agent flag
+ * lists. server.go owns ServerFlags; agent.go owns the agent command's
+ * flags plus the shared node/token flag vars; config.go, root.go and
+ * log.go define the shared vars both lists reference (ConfigFlag,
+ * DebugFlag, VLevel, LogFile, ...).
+ */
+const SPEC_FILES = ["server.go", "agent.go", "config.go", "root.go", "log.go"] as const;
+
+function rawUrl(file: string): string {
+  // '+' must be percent-encoded in the raw.githubusercontent path.
+  const tag = encodeURIComponent(K3S_VERSION);
+  return `https://raw.githubusercontent.com/k3s-io/k3s/${tag}/pkg/cli/cmds/${file}`;
+}
+
+function cachePath(file: string): string {
+  return join(homedir(), ".chant", `k3s-${K3S_VERSION}-${file}`);
+}
+
+/**
+ * Fetch all pinned spec files, keyed by filename.
+ */
+export async function fetchSpecFiles(force?: boolean): Promise<Record<string, string>> {
+  const files: Record<string, string> = {};
+  for (const file of SPEC_FILES) {
+    const data = await fetchWithCache({ url: rawUrl(file), cacheFile: cachePath(file) }, force);
+    files[file] = data.toString("utf-8");
+  }
+  return files;
+}
+
+/**
+ * Fetch the spec as a Map<typeName, Buffer> compatible with the
+ * generatePipeline fetchSchemas callback.
+ *
+ * Single entry keyed "K3s::Config" whose buffer is a JSON envelope of the
+ * fetched files — the parse step needs them together to resolve flag-var
+ * references across files.
+ */
+export async function fetchSchemas(force?: boolean): Promise<Map<string, Buffer>> {
+  const files = await fetchSpecFiles(force);
+  const schemas = new Map<string, Buffer>();
+  schemas.set("K3s::Config", Buffer.from(JSON.stringify(files), "utf-8"));
+  return schemas;
+}
+
+/**
+ * Clear the cached spec files.
+ */
+export function clearCache(): void {
+  for (const file of SPEC_FILES) clearCacheFile(cachePath(file));
+}

package/src/validate-cli.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env tsx
+import { validate } from "./validate";
+
+// `validate` takes an optional { basePath }; defaults to the lexicon root.
+await validate();

package/src/validate.ts

@@ -0,0 +1,41 @@
+/**
+ * Validate generated lexicon-k3s artifacts.
+ *
+ * Thin wrapper around the core validation framework
+ * with k3s-specific configuration.
+ */
+
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts, type ValidateResult } from "@intentius/chant/codegen/validate";
+
+export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
+
+/**
+ * Every entity class, plus load-bearing config keys whose disappearance
+ * from a regeneration would mean the parser silently lost part of the
+ * flag surface (#1599): the join/identity block, the etcd S3 keys the
+ * lint layer references, and one representative per flag type.
+ */
+const REQUIRED_NAMES: string[] = [
+  "Server",
+  "Agent",
+  "Registries",
+  "Mirror",
+  "RegistryConfig",
+  "RegistryAuth",
+  "RegistryTLS",
+];
+
+/**
+ * Validate the generated lexicon-k3s artifacts.
+ */
+export async function validate(opts?: { basePath?: string }): Promise<ValidateResult> {
+  const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+
+  return validateLexiconArtifacts({
+    lexiconJsonFilename: "lexicon-k3s.json",
+    requiredNames: REQUIRED_NAMES,
+    basePath,
+  });
+}