@intentius/chant-lexicon-k3s 0.45.0 → 0.49.0

package/src/op/activities/k3s.test.ts

@@ -0,0 +1,182 @@
+import { describe, test, expect, vi } from "vitest";
+import {
+  k3sInstall,
+  k3sUninstall,
+  k3sInstallCommand,
+  k3sInstallEnv,
+  k3sUninstallCommand,
+  k3sUninstallScript,
+  k3sVersionCommand,
+  parseK3sVersion,
+} from "./k3s";
+import { K3S_VERSION } from "../../spec/fetch";
+
+// Every command below goes through this mock — no real k3s installer, no
+// real host. `execCalls` records the exact (cmd, opts) pairs so the install/
+// uninstall idempotence paths can be asserted precisely.
+const execCalls: Array<{ cmd: string; opts: unknown }> = [];
+let versionReply: { stdout: string; stderr: string } | Error = new Error("k3s: command not found");
+let uninstallReply: { stdout: string; stderr: string } = { stdout: "", stderr: "" };
+
+vi.mock("node:child_process", () => {
+  const custom = Symbol.for("nodejs.util.promisify.custom");
+  const exec = ((_cmd: string, _opts: unknown, cb?: (...a: unknown[]) => void) => {
+    cb?.(new Error("unmocked exec path"));
+  }) as unknown as Record<symbol, unknown>;
+  exec[custom] = async (cmd: string, opts?: unknown) => {
+    execCalls.push({ cmd, opts });
+    if (cmd === "k3s --version") {
+      if (versionReply instanceof Error) throw versionReply;
+      return versionReply;
+    }
+    if (cmd.startsWith("test -x")) return uninstallReply;
+    return { stdout: "", stderr: "" };
+  };
+  return { exec };
+});
+
+describe("k3sInstallCommand (#1601)", () => {
+  test("server role — curl installer piped into `sh -s - server --config <file>`", () => {
+    const cmd = k3sInstallCommand({ role: "server", configFile: "/etc/rancher/k3s/config.yaml" });
+    expect(cmd).toBe(
+      "curl -sfL https://get.k3s.io | sh -s - server --config /etc/rancher/k3s/config.yaml",
+    );
+  });
+
+  test("agent role", () => {
+    const cmd = k3sInstallCommand({ role: "agent", configFile: "/etc/rancher/k3s/config.yaml" });
+    expect(cmd).toContain("sh -s - agent --config");
+  });
+
+  test("never interpolates a token or version into the command string", () => {
+    const cmd = k3sInstallCommand({
+      role: "server",
+      configFile: "/etc/rancher/k3s/config.yaml",
+      version: "v9.9.9+k3s1",
+      tokenFile: "/etc/rancher/k3s/agent-token",
+    });
+    expect(cmd).not.toContain("v9.9.9");
+    expect(cmd).not.toContain("token");
+    expect(cmd).not.toContain("TOKEN");
+  });
+});
+
+describe("k3sInstallEnv — the token boundary (#1601)", () => {
+  test("defaults INSTALL_K3S_VERSION to the lexicon pin, no K3S_TOKEN_FILE without a tokenFile", () => {
+    const env = k3sInstallEnv({ role: "server", configFile: "config.yaml" });
+    expect(env).toEqual({ INSTALL_K3S_VERSION: K3S_VERSION });
+    expect(env.K3S_TOKEN_FILE).toBeUndefined();
+  });
+
+  test("an explicit version overrides the pin", () => {
+    const env = k3sInstallEnv({ role: "server", configFile: "config.yaml", version: "v9.9.9+k3s1" });
+    expect(env.INSTALL_K3S_VERSION).toBe("v9.9.9+k3s1");
+  });
+
+  test("tokenFile becomes K3S_TOKEN_FILE — a path, never a literal secret value", () => {
+    const env = k3sInstallEnv({
+      role: "agent",
+      configFile: "config.yaml",
+      tokenFile: "/etc/rancher/k3s/agent-token",
+    });
+    expect(env.K3S_TOKEN_FILE).toBe("/etc/rancher/k3s/agent-token");
+  });
+
+  test("K3sInstallArgs has no literal-token field at all — a TypeScript surface check", () => {
+    // If a `token` property is ever added to K3sInstallArgs, this object
+    // literal starts compiling and the guard below no longer proves anything.
+    // @ts-expect-error — token is not part of K3sInstallArgs
+    const args: import("./k3s").K3sInstallArgs = { role: "server", configFile: "c.yaml", token: "shhh" };
+    void args;
+  });
+});
+
+describe("k3sUninstallCommand / k3sUninstallScript (#1601)", () => {
+  test("server role runs the server uninstall script, guarded by -x", () => {
+    expect(k3sUninstallScript("server")).toBe("/usr/local/bin/k3s-uninstall.sh");
+    expect(k3sUninstallCommand({ role: "server" })).toBe(
+      'test -x /usr/local/bin/k3s-uninstall.sh && /usr/local/bin/k3s-uninstall.sh || echo "k3s server already uninstalled"',
+    );
+  });
+
+  test("agent role runs the agent uninstall script", () => {
+    expect(k3sUninstallScript("agent")).toBe("/usr/local/bin/k3s-agent-uninstall.sh");
+    expect(k3sUninstallCommand({ role: "agent" })).toContain("k3s-agent-uninstall.sh");
+  });
+});
+
+describe("k3sVersionCommand / parseK3sVersion (#1601)", () => {
+  test("version command", () => {
+    expect(k3sVersionCommand()).toBe("k3s --version");
+  });
+
+  test("parses the version out of `k3s --version` output", () => {
+    const stdout = "k3s version v1.36.3+k3s1 (abc1234)\ngo version go1.23.1\n";
+    expect(parseK3sVersion(stdout)).toBe("v1.36.3+k3s1");
+  });
+
+  test("returns undefined for unrecognized output", () => {
+    expect(parseK3sVersion("bash: k3s: command not found\n")).toBeUndefined();
+  });
+});
+
+describe("k3sInstall (#1601)", () => {
+  test("already-installed matching version: skips install, no INSTALL_K3S_VERSION exec", async () => {
+    execCalls.length = 0;
+    versionReply = { stdout: `k3s version ${K3S_VERSION} (abc1234)\n`, stderr: "" };
+    const result = await k3sInstall({ role: "server", configFile: "/etc/rancher/k3s/config.yaml" });
+    expect(result).toEqual({ version: K3S_VERSION, installed: false });
+    expect(execCalls).toHaveLength(1);
+    expect(execCalls[0].cmd).toBe("k3s --version");
+  });
+
+  test("no k3s present: runs the installer with the version pin in env, not the command string", async () => {
+    execCalls.length = 0;
+    versionReply = new Error("k3s: command not found");
+    const result = await k3sInstall({ role: "server", configFile: "/etc/rancher/k3s/config.yaml" });
+    expect(result).toEqual({ version: K3S_VERSION, installed: true });
+    expect(execCalls).toHaveLength(2);
+    expect(execCalls[0].cmd).toBe("k3s --version");
+    expect(execCalls[1].cmd).toBe(
+      "curl -sfL https://get.k3s.io | sh -s - server --config /etc/rancher/k3s/config.yaml",
+    );
+    const opts = execCalls[1].opts as { env?: Record<string, string> };
+    expect(opts.env?.INSTALL_K3S_VERSION).toBe(K3S_VERSION);
+  });
+
+  test("mismatched version installed: reinstalls to the target version", async () => {
+    execCalls.length = 0;
+    versionReply = { stdout: "k3s version v1.30.0+k3s1 (abc1234)\n", stderr: "" };
+    const result = await k3sInstall({ role: "agent", configFile: "/etc/rancher/k3s/config.yaml" });
+    expect(result).toEqual({ version: K3S_VERSION, installed: true });
+    expect(execCalls).toHaveLength(2);
+  });
+
+  test("a tokenFile is threaded into the installer's env as K3S_TOKEN_FILE", async () => {
+    execCalls.length = 0;
+    versionReply = new Error("k3s: command not found");
+    await k3sInstall({
+      role: "agent",
+      configFile: "/etc/rancher/k3s/config.yaml",
+      tokenFile: "/etc/rancher/k3s/agent-token",
+    });
+    const opts = execCalls[1].opts as { env?: Record<string, string> };
+    expect(opts.env?.K3S_TOKEN_FILE).toBe("/etc/rancher/k3s/agent-token");
+  });
+});
+
+describe("k3sUninstall (#1601)", () => {
+  test("runs the uninstall command for the given role", async () => {
+    execCalls.length = 0;
+    uninstallReply = { stdout: "k3s uninstalled\n", stderr: "" };
+    await k3sUninstall({ role: "server" });
+    expect(execCalls).toHaveLength(1);
+    expect(execCalls[0].cmd).toContain("k3s-uninstall.sh");
+  });
+
+  test("never-installed host: the guarded command still resolves (no-op success)", async () => {
+    execCalls.length = 0;
+    uninstallReply = { stdout: "k3s server already uninstalled\n", stderr: "" };
+    await expect(k3sUninstall({ role: "server" })).resolves.toBeUndefined();
+  });
+});

package/src/op/activities/k3s.ts

@@ -0,0 +1,170 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { safeHeartbeat } from "@intentius/chant/op";
+import { K3S_VERSION } from "../../spec/fetch";
+
+const execAsync = promisify(exec);
+
+/** `k3s server` runs the control plane; `k3s agent` joins one as a worker. */
+export type K3sRole = "server" | "agent";
+
+export interface K3sInstallArgs {
+  /** Which k3s subcommand the installer configures (`k3s server` / `k3s agent`). */
+  role: K3sRole;
+  /**
+   * Path to the chant-emitted `config.yaml` on the reachable host, passed as
+   * `--config` to the installed binary. chant does not write this file itself
+   * — a build/apply step upstream of this activity is responsible for getting
+   * it onto the host (host provisioning is out of scope, chant#1598).
+   */
+  configFile: string;
+  /**
+   * Installer version pin (`INSTALL_K3S_VERSION`). Default: the lexicon's
+   * {@link K3S_VERSION} pin — bump that constant, not this arg, to track a
+   * new upstream release across the whole lexicon.
+   */
+  version?: string;
+  /**
+   * Path to a file on the host holding the cluster join token, passed to the
+   * installer as `K3S_TOKEN_FILE`. This is the only token-shaped input this
+   * activity accepts — see the "token boundary" note below.
+   */
+  tokenFile?: string;
+}
+
+export interface K3sUninstallArgs {
+  /** Which uninstall script to run — k3s ships a separate one per role. */
+  role: K3sRole;
+}
+
+/** What {@link k3sInstall} resolved. */
+export interface K3sInstallResult {
+  /** The k3s version now installed (the target version, whether freshly installed or already present). */
+  version: string;
+  /** `false` when an already-installed matching version made the install a no-op. */
+  installed: boolean;
+}
+
+/**
+ * `k3s --version` output, first line: `k3s version v1.36.3+k3s1 (hash)`.
+ * Returns `undefined` when k3s is not installed or the output doesn't match.
+ */
+export function parseK3sVersion(stdout: string): string | undefined {
+  return stdout.match(/k3s version (\S+)/)?.[1];
+}
+
+/** Check-install-version command — errors (non-zero exit) when k3s is absent. */
+export function k3sVersionCommand(): string {
+  return "k3s --version";
+}
+
+/**
+ * Build the get.k3s.io installer command. The version pin and the join-token
+ * reference (if any) travel as environment variables via {@link k3sInstallEnv},
+ * not interpolated into this string — see the token-boundary note on
+ * {@link k3sInstall}.
+ */
+export function k3sInstallCommand(args: K3sInstallArgs): string {
+  return `curl -sfL https://get.k3s.io | sh -s - ${args.role} --config ${args.configFile}`;
+}
+
+/**
+ * Environment for {@link k3sInstallCommand}: `INSTALL_K3S_VERSION` (the pin)
+ * and, only when a `tokenFile` path is given, `K3S_TOKEN_FILE`.
+ *
+ * ## The token boundary (#1601)
+ *
+ * This is the only token-shaped input the install activity accepts, and it
+ * is a path, not a secret — the join token itself never passes through
+ * activity args, never gets logged, and never lands in an emitted
+ * config.yaml (K3S001 rejects a literal `token`/`agent-token` at lint). A
+ * `K3S_TOKEN` (the literal, env-var form k3s itself supports for agents) is
+ * deliberately not modeled here: the reference form the lexicon carries
+ * end-to-end is a file path, matching `token-file`/`agent-token-file` on the
+ * declared config surface (chant#1365's provenance stance applied at this
+ * surface, not a new mechanism).
+ */
+export function k3sInstallEnv(args: K3sInstallArgs): Record<string, string> {
+  const env: Record<string, string> = { INSTALL_K3S_VERSION: args.version ?? K3S_VERSION };
+  if (args.tokenFile) env.K3S_TOKEN_FILE = args.tokenFile;
+  return env;
+}
+
+/** Path k3s installs its uninstall script at — one per role. */
+export function k3sUninstallScript(role: K3sRole): string {
+  return role === "agent" ? "/usr/local/bin/k3s-agent-uninstall.sh" : "/usr/local/bin/k3s-uninstall.sh";
+}
+
+/**
+ * Build the uninstall command. Gated the way `k3dDown` is (chant#1410): no
+ * pre-check activity, no SSH orchestration — just the native idempotent
+ * behavior. Unlike `k3d cluster delete` (idempotent on its own), the k3s
+ * uninstall script does not exist at all on a host where k3s was never
+ * installed, so the command guards on the script's presence itself rather
+ * than assume it errors safely.
+ */
+export function k3sUninstallCommand(args: K3sUninstallArgs): string {
+  const script = k3sUninstallScript(args.role);
+  return `test -x ${script} && ${script} || echo "k3s ${args.role} already uninstalled"`;
+}
+
+/**
+ * Run the pinned k3s installer against a reachable host. Idempotent on an
+ * already-installed matching version: if `k3s --version` already reports the
+ * target version, the install is skipped. Uses longInfra profile — 20m
+ * timeout, heartbeat every 15s (the installer downloads and starts the
+ * k3s binary).
+ *
+ * Bounded exactly as `k3dUp`/`k3dDown` were (chant#1410, epic #1598): this
+ * drives the case where the host is reachable from where the Op runs. It
+ * does not provision the host, and it is not an SSH orchestrator.
+ */
+export async function k3sInstall(
+  args: K3sInstallArgs,
+  signal?: AbortSignal,
+): Promise<K3sInstallResult> {
+  const target = args.version ?? K3S_VERSION;
+
+  try {
+    const { stdout } = await execAsync(k3sVersionCommand(), { signal });
+    const installed = parseK3sVersion(stdout);
+    if (installed === target) {
+      console.log(`k3s ${target} already installed (${args.role}) — skipping install`);
+      return { version: target, installed: false };
+    }
+    if (installed) {
+      console.log(`k3s ${installed} installed, target is ${target} — reinstalling`);
+    }
+  } catch {
+    // `k3s --version` errors when k3s is absent — fall through to install.
+  }
+
+  const heartbeatInterval = setInterval(() => {
+    safeHeartbeat({ step: "k3s install", role: args.role, version: target });
+  }, 15_000);
+
+  try {
+    const { stdout, stderr } = await execAsync(k3sInstallCommand(args), {
+      signal,
+      env: { ...process.env, ...k3sInstallEnv(args) },
+    });
+    if (stdout) console.log(stdout);
+    if (stderr) console.error(stderr);
+  } finally {
+    clearInterval(heartbeatInterval);
+  }
+
+  return { version: target, installed: true };
+}
+
+/**
+ * Uninstall k3s from a reachable host. Uses fastIdempotent profile — 5m
+ * timeout. A host where k3s was never installed (no uninstall script present)
+ * is a no-op success, the same idempotent shape as `k3dDown` against an
+ * already-gone cluster.
+ */
+export async function k3sUninstall(args: K3sUninstallArgs, signal?: AbortSignal): Promise<void> {
+  const { stdout, stderr } = await execAsync(k3sUninstallCommand(args), { signal });
+  if (stdout) console.log(stdout);
+  if (stderr) console.error(stderr);
+}

package/src/plugin.ts

@@ -6,6 +6,7 @@ import type { McpToolContribution, McpResourceContribution } from "@intentius/ch
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
+import { LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
 import { k3sSerializer } from "./serializer";
 import { rules } from "./lint/rules";
 import { postSynthChecks } from "./lint/post-synth";
@@ -34,6 +35,22 @@ export const k3sPlugin: LexiconPlugin = {
     upstream: { owner: "k3s-io", repo: "k3s", kind: "releases" },
   },
 
+  /**
+   * The marker rides `node-label` (the serializer stamps it there when a
+   * build carries ownership) and lands on the registered Node as ordinary
+   * Kubernetes labels — read back the same way every label-based lexicon
+   * does. See `./describe-resources.ts` (#1603).
+   */
+  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> {

package/src/skills/chant-k3s.md

@@ -70,6 +70,49 @@ export const registries = new Registries({
 Literal `auth.password` / `auth.token` fail K3S102; `insecure_skip_verify`
 warns via K3S105 — pin the CA instead.
 
+## Op lifecycle (reachable-host case)
+
+`k3sInstall` / `k3sUninstall` (chant#1601) drive a k3s installer against a
+host the Op runs on or can reach directly — the same boundary `k3dUp`/
+`k3dDown` draw (chant#1410): no host provisioning, no SSH orchestration.
+Requires `"k3s"` in the project's `chant.config.ts` `lexicons`.
+
+```typescript
+import { Op, phase, k3sInstall, k3sUninstall } from "@intentius/chant-lexicon-temporal";
+
+export default Op({
+  name: "k3s-controlplane",
+  phases: [
+    phase("Install", [
+      k3sInstall("server", { configFile: "/etc/rancher/k3s/config.yaml" }),
+    ]),
+  ],
+});
+```
+
+`k3sInstall` runs the pinned `get.k3s.io` installer (`INSTALL_K3S_VERSION`
+from the lexicon's pin, or an explicit `version` override) with `--config`
+pointing at a config.yaml already on the host — a build/apply step upstream
+puts it there. It is idempotent on an already-installed matching version:
+`k3s --version` is checked first, and a match skips the install entirely.
+`k3sUninstall` runs the matching uninstall script; a host where k3s was
+never installed is a no-op success.
+
+**The token boundary carries through to the Op surface.** There is no
+`token` option on `k3sInstall` — only `tokenFile`, a path passed to the
+installer as `K3S_TOKEN_FILE`. The join secret's value never appears in
+Op-authored TypeScript (which is committed source, same as a config.yaml
+declaration), is never logged, and is never interpolated into the installer
+command string — it travels only as an environment variable set on the
+child process at install time.
+
+```typescript
+k3sInstall("agent", {
+  configFile: "/etc/rancher/k3s/config.yaml",
+  tokenFile: "/etc/rancher/k3s/agent-token", // a path, not the secret
+});
+```
+
 ## Output shape
 
 One file per declared entity. The first Server/Agent config is the primary
@@ -88,3 +131,5 @@ with any kubectl.
 | K3S103 | error | an Agent with no `server` to join |
 | K3S104 | warning | kubeconfig written wider than 0644 |
 | K3S105 | warning | registry TLS verification disabled |
+| K3S106 | warning | tls-san missing for a declared bind/advertise address |
+| K3S107 | warning | disable names a component the config also configures |