@intentius/chant-lexicon-k3s 0.124.31 → 0.124.32

package/dist/describe-resources.js

@@ -0,0 +1,200 @@
+/**
+ * Live observation for declared k3s Server/Agent entities (#1603).
+ *
+ * Mirrors the #1412 k3d answer for the k3s shape, and reuses the same
+ * `k8s.profiles.<env>.context` binding helm and the k8s lexicon read
+ * (`@intentius/chant/kubectl-context`, #1488): the kubectl context is a
+ * property of the cluster chant talks to, not of any one lexicon, so k3s
+ * does not invent a second binding namespace for the same thing.
+ *
+ * ## What this can honestly say
+ *
+ * A declared `K3s::Server` / `K3s::Agent` is chant's description of one node
+ * joining a cluster. From where chant runs — never the host itself — the
+ * only observables are ones the apiserver answers:
+ *
+ *   - the declared kubectl context exists and answers at all (`kubectl
+ *     version`), which also reports the live k3s build so a caller can see
+ *     it against the pin (`K3S_VERSION`);
+ *   - the node the entity names is registered and its `Ready` condition.
+ *
+ * Everything that would require reaching the host directly — whether the
+ * `k3s` systemd unit is up, what `/etc/rancher/k3s/config.yaml` currently
+ * holds on disk — is out of scope. That is the provisioning boundary #1598
+ * draws, and this reader never crosses it.
+ *
+ * `K3s::Registries` has no live counterpart at all: `registries.yaml` is
+ * consumed once at containerd startup and leaves no object an apiserver
+ * serves, so it reads `unsupported-kind` — honest, not a gap to close here.
+ *
+ * ## Node identity
+ *
+ * The only address chant can back up is a declared `node-name`. Unset, k3s
+ * registers the node under the host's own hostname — which chant, running
+ * off the host, cannot know or guess. An entity with no `node-name` is
+ * `read-failed`, never a guessed address and never `absent`.
+ *
+ * ## Ownership rides node-label (#1603)
+ *
+ * The serializer stamps chant's marker into `node-label` when a build carries
+ * ownership (`./serializer.ts`), which lands on the registered Node as
+ * ordinary Kubernetes labels — the durable channel a host config file has no
+ * other way to carry. Read back here the same way every label-based lexicon
+ * does (`LABEL_OWNERSHIP_KEYS`).
+ *
+ * ## Tri-state (#1089, and the #1488 lesson)
+ *
+ * An unreachable apiserver — context missing, connection refused, no
+ * credentials — is `read-failed`/`no-credentials`/`no-binding` for every
+ * declared entity, naming the context that was actually read, never
+ * `absent`. Only a genuine per-node `NotFound` is absence.
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { observeEntities, } from "@intentius/chant/observation";
+import { classifyOwnership, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+import { loadChantConfigUpward } from "@intentius/chant/config";
+import { resolveClusterTarget, classifyKubectlFailure } from "@intentius/chant/kubectl-context";
+import { SERVER_TYPE, AGENT_TYPE } from "./serializer.js";
+import { K3S_VERSION } from "./spec/fetch.js";
+const execAsync = promisify(exec);
+/** Shell-quote one argv element (same convention as helm's release-observe). */
+function q(arg) {
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * The environment's kube context (#1488): the declared `k8s.profiles.<env>`
+ * binding when present, ambient otherwise. This is deliberately the SAME
+ * binding the k8s and helm lexicons read — a cluster is one target however
+ * many lexicons observe it — not a `k3s.profiles` of its own.
+ */
+export async function resolveK3sContext(environment) {
+    try {
+        const { config } = await loadChantConfigUpward(process.cwd());
+        return (await resolveClusterTarget(config, environment, "k3s")).context;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The declared node identity: the `node-name` flag, chant's only honest
+ * source. Absent means k3s will name the node after the host's own hostname
+ * — unknowable from here, so there is nothing to query by. */
+export function declaredNodeName(entity) {
+    const name = entity.props?.["node-name"];
+    return typeof name === "string" && name.length > 0 ? name : undefined;
+}
+/** The node's `Ready` condition as a status word: no condition at all reads
+ * `unknown` (asked, and the object said nothing) rather than a guess. */
+function nodeReadyStatus(node) {
+    const ready = node.status?.conditions?.find((c) => c.type === "Ready");
+    if (!ready)
+        return "unknown";
+    if (ready.status === "True")
+        return "Ready";
+    return ready.reason && ready.reason.length > 0 ? ready.reason : "NotReady";
+}
+function pruneUndefined(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+function adapter(execFn, environment) {
+    // Captured so a bind() failure can name the exact context it tried,
+    // per the #1488 lesson — a bare kubectl error rarely does.
+    let contextTried;
+    return {
+        async bind() {
+            const context = await resolveK3sContext(environment);
+            contextTried = context;
+            const ctxFlag = context ? ` --context ${q(context)}` : "";
+            const { stdout } = await execFn(`kubectl version -o json${ctxFlag}`);
+            const parsed = JSON.parse(stdout);
+            return { exec: execFn, ctxFlag, k3sVersion: parsed.serverVersion?.gitVersion };
+        },
+        classifyBindFailure(err) {
+            const outcome = classifyKubectlFailure(err);
+            const named = contextTried
+                ? `context "${contextTried}" (from k8s.profiles.${environment}.context)`
+                : "the ambient kubectl context (no k8s.profiles binding declared)";
+            const raw = outcome.kind === "unobserved" ? outcome.detail : err instanceof Error ? err.message.split("\n")[0] : String(err);
+            const reason = outcome.kind === "unobserved" ? outcome.reason : "read-failed";
+            return { reason, detail: `${named}: ${raw}` };
+        },
+        async read(client, entity) {
+            if (entity.type !== SERVER_TYPE && entity.type !== AGENT_TYPE) {
+                return { unobserved: { reason: "unsupported-kind", detail: entity.type } };
+            }
+            const name = declaredNodeName(entity);
+            if (!name) {
+                return {
+                    unobserved: {
+                        reason: "read-failed",
+                        detail: "no `node-name` declared — unset, k3s names the node after the host's own hostname, which chant cannot know from here",
+                    },
+                };
+            }
+            const command = `kubectl get node ${q(name)} -o json${client.ctxFlag}`;
+            try {
+                const { stdout } = await client.exec(command);
+                const node = JSON.parse(stdout);
+                const ownership = classifyOwnership(node.metadata?.labels, LABEL_OWNERSHIP_KEYS);
+                return {
+                    present: {
+                        type: entity.type,
+                        physicalId: node.metadata?.uid ?? name,
+                        status: nodeReadyStatus(node),
+                        lastUpdated: node.metadata?.creationTimestamp,
+                        ownership,
+                        attributes: pruneUndefined({
+                            nodeName: name,
+                            kubeletVersion: node.status?.nodeInfo?.kubeletVersion,
+                            k3sVersion: client.k3sVersion,
+                            versionMatchesPin: client.k3sVersion ? client.k3sVersion === K3S_VERSION : undefined,
+                            labels: node.metadata?.labels,
+                        }),
+                    },
+                    queried: command,
+                };
+            }
+            catch (err) {
+                const outcome = classifyKubectlFailure(err);
+                if (outcome.kind === "absent")
+                    return { absent: true, queried: command };
+                return { unobserved: { reason: outcome.reason, detail: outcome.detail }, queried: command };
+            }
+        },
+    };
+}
+export async function describeResources(options, execFn = execAsync) {
+    const declared = options.entityNames.map((name) => {
+        const entity = options.entities.get(name);
+        return {
+            name,
+            type: entity?.entityType ?? "",
+            props: entity?.props ?? {},
+        };
+    });
+    const result = await observeEntities(declared, adapter(execFn, options.environment));
+    if (!options.owned)
+        return result;
+    // `--owned`: withhold a node that is present but carries no chant marker.
+    // Withheld is `filtered`, never absent — a foreign node still exists.
+    const resources = { ...result.resources };
+    const unobserved = { ...result.unobserved };
+    for (const [name, meta] of Object.entries(result.resources)) {
+        if (meta.ownership === "owned")
+            continue;
+        delete resources[name];
+        unobserved[name] = {
+            type: meta.type,
+            reason: "filtered",
+            detail: "live node carries no chant ownership marker and --owned was requested",
+            ...(result.queried?.[name] ? { queried: result.queried[name] } : {}),
+        };
+    }
+    return { ...result, resources, unobserved };
+}

package/dist/generated/index.js

@@ -0,0 +1,10 @@
+// Code generated by chant generate. DO NOT EDIT.
+import { createResource, createProperty } from "./runtime.js";
+export const Agent = /* @__PURE__ */ createResource("K3s::Agent", "k3s", {});
+export const Registries = /* @__PURE__ */ createResource("K3s::Registries", "k3s", {});
+export const Server = /* @__PURE__ */ createResource("K3s::Server", "k3s", {});
+export const Mirror = /* @__PURE__ */ createProperty("K3s::Mirror", "k3s");
+export const RegistryAuth = /* @__PURE__ */ createProperty("K3s::RegistryAuth", "k3s");
+export const RegistryConfig = /* @__PURE__ */ createProperty("K3s::RegistryConfig", "k3s");
+export const RegistryTLS = /* @__PURE__ */ createProperty("K3s::RegistryTLS", "k3s");
+// Re-exports for convenience

package/dist/generated/runtime.js

@@ -0,0 +1,4 @@
+/**
+ * Runtime factory constructors — re-exported from core.
+ */
+export { createResource, createProperty } from "@intentius/chant/runtime";

package/dist/index.js

@@ -0,0 +1,14 @@
+// Typed Op step-builder wrappers (chant #1288 Stage 2) — k3sInstall/
+// k3sUninstall with authoring-time types derived from this lexicon's own
+// *Args interfaces (see ./op/builders.ts's module doc). Opt-in:
+// `@intentius/chant/op`'s same-named exports are core's original untyped
+// builders, unchanged.
+export { k3sInstall, k3sUninstall } from "./op/builders.js";
+// Plugin
+export { k3sPlugin } from "./plugin.js";
+// Serializer
+export { k3sSerializer } from "./serializer.js";
+// Generated resources — export everything from generated index
+export * from "./generated/index.js";
+// The pinned upstream release and its Docker image tag form
+export { K3S_VERSION, K3S_IMAGE_TAG } from "./spec/fetch.js";

package/dist/lint/audit-catalog.js

@@ -0,0 +1,16 @@
+import { k3sAuditLineage } from "./audit-lineage.js";
+import { applyLineage } from "@intentius/chant/audit/catalog";
+function entityRule(id, category, title, remediation) {
+    return { id, tier: "merge-worthy", fixKind: "guidance", category, title, remediation, yamlBased: false };
+}
+export const k3sAuditCatalog = {
+    K3S101: entityRule("K3S101", "security", "Literal join token in a k3s config", "Remove the `token` value; point `token-file` at a path on the host instead."),
+    K3S102: entityRule("K3S102", "security", "Literal registry credential in registries.yaml", "Remove the credential from the declaration; configure registry auth on the host."),
+    K3S103: entityRule("K3S103", "correctness", "Agent config with no server to join", "Set `server: https://<server-host>:6443` on the agent declaration."),
+    K3S104: entityRule("K3S104", "security", "Kubeconfig written wider than 0644", "Drop `write-kubeconfig-mode`, or keep it at 0600/0644."),
+    K3S105: entityRule("K3S105", "security", "Registry TLS verification disabled", "Remove `insecure_skip_verify`; pin the registry CA via `ca_file`."),
+    K3S106: entityRule("K3S106", "correctness", "tls-san missing for a declared bind/advertise address", "Add the bind-address / advertise-address value to `tls-san`."),
+    K3S107: entityRule("K3S107", "correctness", "Disabled component still configured", "Remove the component's config key, or drop it from `disable`."),
+};
+// Prior art credits live beside the rules in ./audit-lineage.ts (see core audit/prior-art.ts).
+applyLineage(k3sAuditCatalog, k3sAuditLineage);

package/dist/lint/audit-lineage.js

@@ -0,0 +1,5 @@
+export const k3sAuditLineage = {
+    K3S104: [
+        { tool: "kube-bench", rule: "k3s-cis-1.8 1.1.13", url: "https://raw.githubusercontent.com/aquasecurity/kube-bench/main/cfg/k3s-cis-1.8/master.yaml", relation: "overlaps" },
+    ],
+};

package/dist/lint/post-synth/index.js

@@ -0,0 +1,16 @@
+import { k3s101 } from "./k3s101.js";
+import { k3s102 } from "./k3s102.js";
+import { k3s103 } from "./k3s103.js";
+import { k3s104 } from "./k3s104.js";
+import { k3s105 } from "./k3s105.js";
+import { k3s106 } from "./k3s106.js";
+import { k3s107 } from "./k3s107.js";
+export const postSynthChecks = [
+    k3s101,
+    k3s102,
+    k3s103,
+    k3s104,
+    k3s105,
+    k3s106,
+    k3s107,
+];

package/dist/lint/post-synth/k3s-helpers.js

@@ -0,0 +1,24 @@
+/**
+ * Shared helpers for the k3s post-synth checks.
+ *
+ * These checks read the chant model (`ctx.entities`), not the emitted
+ * YAML: an emitted config.yaml carries no marker naming its own role, so
+ * the entity type is the only honest way to know a document is a server
+ * config, an agent config, or a registries file. The audit catalog marks
+ * every entity-based check `yamlBased: false` accordingly.
+ */
+/** Every declared k3s entity of one type, with its props. */
+export function entitiesOfType(ctx, entityType) {
+    const out = [];
+    for (const [name, entity] of ctx.entities) {
+        const e = entity;
+        if (e.entityType !== entityType)
+            continue;
+        const props = typeof e.props === "object" && e.props !== null ? e.props : {};
+        out.push({ name, entityType, props });
+    }
+    return out;
+}
+export function configEntities(ctx) {
+    return [...entitiesOfType(ctx, "K3s::Server"), ...entitiesOfType(ctx, "K3s::Agent")];
+}

package/dist/lint/post-synth/k3s101.js

@@ -0,0 +1,48 @@
+/**
+ * K3S101: a literal join token reached the build.
+ *
+ * The typed surface omits `token` / `agent-token` (#1601) and K3S001
+ * catches the literal at source. This is the backstop for the path both
+ * miss: a raw prop object built at runtime, spread in, or emitted by a
+ * composite. If the key is present with a non-empty string value in the
+ * entity the build serialized, the emitted config.yaml carries the
+ * cluster's join secret, and the build fails.
+ */
+import { configEntities } from "./k3s-helpers.js";
+/**
+ * `token`/`agent-token`/`cluster-secret` are the join secret. The etcd S3
+ * pair are snapshot-store credentials the flag surface types as plain
+ * strings — k3s's own docs point at `etcd-s3-config-secret` (a Secret on
+ * the cluster) for exactly this reason.
+ */
+const SECRET_KEYS = [
+    "token",
+    "agent-token",
+    "cluster-secret",
+    "etcd-s3-secret-key",
+    "etcd-s3-session-token",
+];
+export const k3s101 = {
+    id: "K3S101",
+    description: "A k3s config entity carries a literal join token",
+    check(ctx) {
+        const diagnostics = [];
+        for (const entity of configEntities(ctx)) {
+            for (const key of SECRET_KEYS) {
+                const value = entity.props[key];
+                if (typeof value === "string" && value.length > 0) {
+                    diagnostics.push({
+                        checkId: "K3S101",
+                        severity: "error",
+                        message: `"${entity.name}" carries a literal \`${key}\` — the emitted config.yaml would ` +
+                            "contain the secret. Use the file/Secret reference form instead " +
+                            "(`token-file`, `etcd-s3-config-secret`).",
+                        entity: entity.name,
+                        lexicon: "k3s",
+                    });
+                }
+            }
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/k3s102.js

@@ -0,0 +1,52 @@
+/**
+ * K3S102: registry credentials as literals.
+ *
+ * registries.yaml supports inline `auth.password` / `auth.token`, and a
+ * committed estate that uses them has published its registry credentials.
+ * The TLS file paths beside them are host paths — those are fine; it is
+ * the credential values that must come from somewhere else.
+ */
+import { entitiesOfType } from "./k3s-helpers.js";
+export const k3s102 = {
+    id: "K3S102",
+    description: "registries.yaml carries a literal registry credential",
+    check(ctx) {
+        const diagnostics = [];
+        for (const entity of entitiesOfType(ctx, "K3s::Registries")) {
+            const configs = entity.props.configs;
+            if (typeof configs !== "object" || configs === null)
+                continue;
+            for (const [registry, config] of Object.entries(configs)) {
+                const auth = resolveProps(config)?.auth;
+                const authProps = resolveProps(auth);
+                if (!authProps)
+                    continue;
+                for (const key of ["password", "token"]) {
+                    const value = authProps[key];
+                    if (typeof value === "string" && value.length > 0) {
+                        diagnostics.push({
+                            checkId: "K3S102",
+                            severity: "error",
+                            message: `"${entity.name}" carries a literal \`${key}\` for registry "${registry}" — ` +
+                                "a committed registries.yaml is a leaked credential. Configure registry auth " +
+                                "on the host outside the declaration.",
+                            entity: entity.name,
+                            lexicon: "k3s",
+                        });
+                    }
+                }
+            }
+        }
+        return diagnostics;
+    },
+};
+/** A nested value may be a plain object or a property declarable carrying props. */
+function resolveProps(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const obj = value;
+    if (typeof obj.props === "object" && obj.props !== null && "entityType" in obj) {
+        return obj.props;
+    }
+    return obj;
+}

package/dist/lint/post-synth/k3s103.js

@@ -0,0 +1,30 @@
+/**
+ * K3S103: an agent that joins nothing.
+ *
+ * An agent config without `server` is a node with no cluster to join —
+ * `k3s agent` refuses to start without it (or K3S_URL in the service
+ * environment). Declaring the agent while leaving the join out of band
+ * defeats the declaration, so this asks for it in the config.
+ */
+import { entitiesOfType } from "./k3s-helpers.js";
+export const k3s103 = {
+    id: "K3S103",
+    description: "An agent config declares no server to join",
+    check(ctx) {
+        const diagnostics = [];
+        for (const entity of entitiesOfType(ctx, "K3s::Agent")) {
+            const server = entity.props.server;
+            if (typeof server === "string" && server.length > 0)
+                continue;
+            diagnostics.push({
+                checkId: "K3S103",
+                severity: "error",
+                message: `"${entity.name}" declares no \`server\` — the agent has no cluster to join. ` +
+                    "Set `server: https://<server-host>:6443` in the declaration.",
+                entity: entity.name,
+                lexicon: "k3s",
+            });
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/k3s104.js

@@ -0,0 +1,37 @@
+/**
+ * K3S104: kubeconfig written wider than 0644.
+ *
+ * `write-kubeconfig-mode` widens /etc/rancher/k3s/k3s.yaml — the file
+ * carrying the cluster's admin credential. k3s's own default is 0600;
+ * 0644 is the documented convenience for a single-user host. Anything
+ * granting write to group/other, or beyond read to other, hands the
+ * admin kubeconfig to every local account.
+ */
+import { entitiesOfType } from "./k3s-helpers.js";
+export const k3s104 = {
+    id: "K3S104",
+    description: "write-kubeconfig-mode is wider than 0644",
+    check(ctx) {
+        const diagnostics = [];
+        for (const entity of entitiesOfType(ctx, "K3s::Server")) {
+            const raw = entity.props["write-kubeconfig-mode"];
+            if (raw === undefined)
+                continue;
+            const mode = parseInt(String(raw), 8);
+            if (Number.isNaN(mode))
+                continue;
+            // Bits outside rw-r--r-- mean group/other write, or execute anywhere.
+            if ((mode & ~0o644) !== 0) {
+                diagnostics.push({
+                    checkId: "K3S104",
+                    severity: "warning",
+                    message: `"${entity.name}" sets write-kubeconfig-mode ${String(raw)} — wider than 0644. ` +
+                        "The kubeconfig carries the cluster admin credential; keep it 0600, or 0644 at most.",
+                    entity: entity.name,
+                    lexicon: "k3s",
+                });
+            }
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/k3s105.js

@@ -0,0 +1,44 @@
+/**
+ * K3S105: a registry mirror that skips TLS verification.
+ *
+ * `insecure_skip_verify: true` in registries.yaml turns every image pull
+ * through that registry into an unauthenticated trust decision. Legitimate
+ * for a lab pull-through cache; worth a flag anywhere, because the estate
+ * that sets it for the lab keeps it when the registry moves.
+ */
+import { entitiesOfType } from "./k3s-helpers.js";
+export const k3s105 = {
+    id: "K3S105",
+    description: "registries.yaml disables TLS verification for a registry",
+    check(ctx) {
+        const diagnostics = [];
+        for (const entity of entitiesOfType(ctx, "K3s::Registries")) {
+            const configs = entity.props.configs;
+            if (typeof configs !== "object" || configs === null)
+                continue;
+            for (const [registry, config] of Object.entries(configs)) {
+                const tls = resolveProps(resolveProps(config)?.tls);
+                if (tls?.insecure_skip_verify === true) {
+                    diagnostics.push({
+                        checkId: "K3S105",
+                        severity: "warning",
+                        message: `"${entity.name}" disables TLS verification for registry "${registry}" — ` +
+                            "every pull through it is unauthenticated. Pin the registry CA via `ca_file` instead.",
+                        entity: entity.name,
+                        lexicon: "k3s",
+                    });
+                }
+            }
+        }
+        return diagnostics;
+    },
+};
+function resolveProps(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const obj = value;
+    if (typeof obj.props === "object" && obj.props !== null && "entityType" in obj) {
+        return obj.props;
+    }
+    return obj;
+}

package/dist/lint/post-synth/k3s106.js

@@ -0,0 +1,47 @@
+/**
+ * K3S106: tls-san missing when the server is reachable at a declared
+ * address beyond the implicit default.
+ *
+ * The kube-apiserver certificate is only valid for the addresses baked
+ * into it. `bind-address` and `advertise-address` both say "clients reach
+ * this server somewhere other than its bare node-ip" — a fixed bind
+ * address, or a front-door address for an HA load balancer / VIP. Either
+ * one without a matching `tls-san` entry means the first connection
+ * through that address hits a certificate mismatch.
+ */
+import { entitiesOfType } from "./k3s-helpers.js";
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+export const k3s106 = {
+    id: "K3S106",
+    description: "tls-san is missing while bind-address or advertise-address is declared",
+    check(ctx) {
+        const diagnostics = [];
+        for (const entity of entitiesOfType(ctx, "K3s::Server")) {
+            const tlsSan = entity.props["tls-san"];
+            const hasTlsSan = isNonEmptyString(tlsSan) || (Array.isArray(tlsSan) && tlsSan.length > 0);
+            if (hasTlsSan)
+                continue;
+            const bindAddress = entity.props["bind-address"];
+            const advertiseAddress = entity.props["advertise-address"];
+            const declaredField = isNonEmptyString(bindAddress)
+                ? "bind-address"
+                : isNonEmptyString(advertiseAddress)
+                    ? "advertise-address"
+                    : undefined;
+            if (!declaredField)
+                continue;
+            diagnostics.push({
+                checkId: "K3S106",
+                severity: "warning",
+                message: `"${entity.name}" sets \`${declaredField}\` but declares no \`tls-san\` — ` +
+                    "the apiserver certificate won't cover that address, and the first client to reach " +
+                    "it there hits a TLS mismatch. Add it to `tls-san`.",
+                entity: entity.name,
+                lexicon: "k3s",
+            });
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/post-synth/k3s107.js

@@ -0,0 +1,58 @@
+/**
+ * K3S107: a packaged component is disabled but also configured.
+ *
+ * `disable` removes a packaged component entirely — the flags that
+ * configure it (`cluster-dns` for coredns, `servicelb-namespace` for
+ * servicelb, `default-local-storage-path` for local-storage) then land in
+ * config.yaml for a component that never starts. Dead config, and a
+ * signal the `disable` and the config drifted out of sync rather than
+ * being written together.
+ */
+import { entitiesOfType } from "./k3s-helpers.js";
+/**
+ * Packaged component name (as it appears in `disable`) to the config keys
+ * that only make sense while that component runs. Limited to the
+ * components the k3s server flag surface actually has dedicated
+ * configuration for — traefik and metrics-server are configured via Helm
+ * chart manifests, not server flags, so there is nothing here to conflict.
+ */
+const COMPONENT_CONFIG_KEYS = {
+    coredns: ["cluster-dns"],
+    servicelb: ["servicelb-namespace"],
+    "local-storage": ["default-local-storage-path"],
+};
+export const k3s107 = {
+    id: "K3S107",
+    description: "disable names a component the config also configures",
+    check(ctx) {
+        const diagnostics = [];
+        for (const entity of entitiesOfType(ctx, "K3s::Server")) {
+            const raw = entity.props.disable;
+            const disabled = typeof raw === "string" ? [raw] : Array.isArray(raw) ? raw : [];
+            for (const component of disabled) {
+                if (typeof component !== "string")
+                    continue;
+                const configKeys = COMPONENT_CONFIG_KEYS[component];
+                if (!configKeys)
+                    continue;
+                for (const key of configKeys) {
+                    const value = entity.props[key];
+                    const isSet = (typeof value === "string" && value.length > 0) ||
+                        (Array.isArray(value) && value.length > 0);
+                    if (!isSet)
+                        continue;
+                    diagnostics.push({
+                        checkId: "K3S107",
+                        severity: "warning",
+                        message: `"${entity.name}" disables \`${component}\` but also sets \`${key}\` — ` +
+                            `that config has no effect on a component that never starts. Remove \`${key}\`, ` +
+                            `or drop \`${component}\` from \`disable\`.`,
+                        entity: entity.name,
+                        lexicon: "k3s",
+                    });
+                }
+            }
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/rules/index.js

@@ -0,0 +1,4 @@
+import { tokenLiteralRule } from "./token-literal.js";
+export { tokenLiteralRule } from "./token-literal.js";
+/** All lint rules provided by this lexicon (imported by plugin.ts's lintRules()). */
+export const rules = [tokenLiteralRule];