@intentius/chant-lexicon-k3d 0.0.1

package/src/lint/rules/registry-proxy-password.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "vitest";
+import * as ts from "typescript";
+import type { LintContext } from "@intentius/chant/lint/rule";
+import { registryProxyPasswordRule } from "./registry-proxy-password";
+
+function createContext(code: string, fileName = "cluster.ts"): LintContext {
+  const sourceFile = ts.createSourceFile(fileName, code, ts.ScriptTarget.Latest, true);
+  return { sourceFile, entities: [], filePath: fileName };
+}
+
+describe("K3D001: registry proxy password literal", () => {
+  test("flags a literal password inside RegistryProxy(...)", () => {
+    const diags = registryProxyPasswordRule.check(
+      createContext(`const p = RegistryProxy({ remoteURL: "https://registry-1.docker.io", password: "hunter2" });`),
+    );
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("K3D001");
+    expect(diags[0].severity).toBe("error");
+  });
+
+  test("flags a literal password inside new RegistryProxy(...)", () => {
+    const diags = registryProxyPasswordRule.check(
+      createContext(`const p = new RegistryProxy({ password: "hunter2" });`),
+    );
+    expect(diags).toHaveLength(1);
+  });
+
+  test("flags a literal password in a plain proxy object", () => {
+    const diags = registryProxyPasswordRule.check(
+      createContext(`const r = RegistryCreate({ proxy: { remoteURL: "https://x", password: \`hunter2\` } });`),
+    );
+    expect(diags).toHaveLength(1);
+  });
+
+  test("does not flag a password that is not a literal", () => {
+    const diags = registryProxyPasswordRule.check(
+      createContext(`const p = RegistryProxy({ password: process.env.REGISTRY_PASSWORD });`),
+    );
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag unrelated password properties", () => {
+    const diags = registryProxyPasswordRule.check(
+      createContext(`const config = { database: { password: "not-k3d's-business" } };`),
+    );
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag an empty literal", () => {
+    const diags = registryProxyPasswordRule.check(createContext(`const p = RegistryProxy({ password: "" });`));
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lint/rules/registry-proxy-password.ts

@@ -0,0 +1,93 @@
+import * as ts from "typescript";
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+
+/**
+ * K3D001: literal registry proxy password in source.
+ *
+ * The v1alpha5 schema types `registries.create.proxy.password` as a plain
+ * string, so nothing upstream stops a declaration from carrying the registry
+ * credential verbatim — and a cluster config is exactly the kind of file
+ * that gets committed. A literal here is a credential in source, which is
+ * the line chant does not cross anywhere else (FTN001, WK8005).
+ *
+ * Flags a string-literal `password` when it is unambiguously the k3d proxy
+ * one: inside a `RegistryProxy(...)` construction, or inside an object
+ * assigned to a `proxy` property. A bare `password:` elsewhere in the file
+ * is someone else's business.
+ */
+export const registryProxyPasswordRule: LintRule = {
+  id: "K3D001",
+  severity: "error",
+  category: "security",
+  description: "Registry proxy password declared as a string literal in source",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const source = context.sourceFile;
+
+    const flag = (node: ts.Node) => {
+      const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+      diagnostics.push({
+        ruleId: "K3D001",
+        severity: "error",
+        message:
+          "registries.create.proxy.password is a literal in source — a committed cluster config " +
+          "is a leaked registry credential. Keep the value out of the declaration: connect a " +
+          "pre-existing registry via registries.use, or supply the proxy credential outside chant.",
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+      });
+    };
+
+    const passwordLiteral = (obj: ts.ObjectLiteralExpression): ts.Node | undefined => {
+      for (const prop of obj.properties) {
+        if (
+          ts.isPropertyAssignment(prop) &&
+          ts.isIdentifier(prop.name) &&
+          prop.name.text === "password" &&
+          (ts.isStringLiteral(prop.initializer) || ts.isNoSubstitutionTemplateLiteral(prop.initializer)) &&
+          prop.initializer.text.length > 0
+        ) {
+          return prop.initializer;
+        }
+      }
+      return undefined;
+    };
+
+    const visit = (node: ts.Node) => {
+      // RegistryProxy({ ..., password: "..." }) — with or without `new`.
+      if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+        const callee = node.expression;
+        const name = ts.isIdentifier(callee)
+          ? callee.text
+          : ts.isPropertyAccessExpression(callee)
+            ? callee.name.text
+            : undefined;
+        if (name === "RegistryProxy") {
+          const arg = node.arguments?.[0];
+          if (arg && ts.isObjectLiteralExpression(arg)) {
+            const literal = passwordLiteral(arg);
+            if (literal) flag(literal);
+          }
+        }
+      }
+
+      // proxy: { ..., password: "..." } — the plain-object form.
+      if (
+        ts.isPropertyAssignment(node) &&
+        ts.isIdentifier(node.name) &&
+        node.name.text === "proxy" &&
+        ts.isObjectLiteralExpression(node.initializer)
+      ) {
+        const literal = passwordLiteral(node.initializer);
+        if (literal) flag(literal);
+      }
+
+      ts.forEachChild(node, visit);
+    };
+
+    visit(source);
+    return diagnostics;
+  },
+};

package/src/lsp/completions.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+import { completions } from "./completions";
+
+describe("LSP completions", () => {
+  it("returns an array", () => {
+    // TODO: Replace with a real CompletionContext
+    const result = completions({} as any);
+    expect(Array.isArray(result)).toBe(true);
+  });
+});

package/src/lsp/completions.ts

@@ -0,0 +1,21 @@
+import { createRequire } from "module";
+import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconCompletions, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(import.meta.url);
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-k3d.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Provide k3d completions based on context — Cluster and its property
+ * entities, from the generated registry.
+ */
+export function completions(ctx: CompletionContext): CompletionItem[] {
+  return lexiconCompletions(ctx, getIndex(), "k3d entity");
+}

package/src/lsp/hover.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+import { hover } from "./hover";
+
+describe("LSP hover", () => {
+  it("returns undefined for unknown context", () => {
+    // TODO: Replace with a real HoverContext
+    const result = hover({} as any);
+    expect(result).toBeUndefined();
+  });
+});

package/src/lsp/hover.ts

@@ -0,0 +1,39 @@
+import { createRequire } from "module";
+import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconHover, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(import.meta.url);
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-k3d.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Provide hover information for k3d entity types.
+ */
+export function hover(ctx: HoverContext): HoverInfo | undefined {
+  return lexiconHover(ctx, getIndex(), resourceHover);
+}
+
+function resourceHover(className: string, entry: LexiconEntry): HoverInfo | undefined {
+  const lines: string[] = [];
+
+  lines.push(`**${className}**`);
+  lines.push("");
+  lines.push(`k3d type: \`${entry.resourceType}\``);
+  lines.push("");
+  if (entry.kind === "resource") {
+    lines.push(
+      "*Resource entity — serialized as a `k3d.io/v1alpha5` SimpleConfig " +
+        "document that `k3d cluster create --config` consumes verbatim*",
+    );
+  } else {
+    lines.push("*Property entity — a nested value in a Cluster declaration*");
+  }
+
+  return { contents: lines.join("\n") };
+}

package/src/op/activities/index.ts

@@ -0,0 +1,24 @@
+/**
+ * k3d Op activities — resolved by the core activity registry when a project's
+ * `chant.config.ts` lists the `k3d` lexicon. Relocated from the k8s lexicon
+ * (chant #1410) so the local-cluster tooling lives with its product:
+ *   - k3dUp / k3dDown — boot/tear down a local k3d cluster. Since #1411 the
+ *     kubeconfig default is safe: the caller's default kubeconfig and current
+ *     context are left alone unless explicitly requested, and `k3dUp` returns
+ *     `{ context, kubeconfigPath? }` so later steps know what to talk to.
+ *
+ * The step builders (k3dUp, k3dDown) stay in core, re-exported from the
+ * temporal Op-authoring barrel like the other core builders. The activities are
+ * dependency-light — they shell out to the k3d CLI and do not import the k3d
+ * declarable surface — so a Temporal worker loads them cheaply.
+ */
+export {
+  k3dUp,
+  k3dDown,
+  k3dUpCommand,
+  k3dDownCommand,
+  k3dExistsCommand,
+  k3dKubeconfigWriteCommand,
+  k3dContextName,
+} from "./k3d";
+export type { K3dUpArgs, K3dDownArgs, K3dUpResult } from "./k3d";

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

@@ -0,0 +1,168 @@
+import { describe, test, expect, vi } from "vitest";
+import {
+  k3dUp,
+  k3dUpCommand,
+  k3dDownCommand,
+  k3dExistsCommand,
+  k3dKubeconfigWriteCommand,
+  k3dContextName,
+} from "./k3d";
+
+// The return-shape tests below exercise k3dUp's already-exists skip path, so
+// every command goes through this mock — no real cluster, no k3d binary.
+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) => {
+    if (cmd.startsWith("k3d cluster list")) return { stdout: "dev up\n", stderr: "" };
+    if (cmd.startsWith("k3d kubeconfig write")) {
+      return { stdout: "/home/user/.config/k3d/kubeconfig-dev.yaml\n", stderr: "" };
+    }
+    return { stdout: "", stderr: "" };
+  };
+  return { exec };
+});
+
+describe("k3dUpCommand (#704, kubeconfig defaults #1411)", () => {
+  test("minimal — name only: safe kubeconfig defaults, --wait with a 120s timeout", () => {
+    const cmd = k3dUpCommand({ name: "chant-local" });
+    expect(cmd).toBe(
+      "k3d cluster create chant-local --kubeconfig-update-default=false --kubeconfig-switch-context=false --wait --timeout 120s",
+    );
+  });
+
+  test("servers/agents/image flags", () => {
+    const cmd = k3dUpCommand({
+      name: "dev",
+      servers: 1,
+      agents: 2,
+      image: "rancher/k3s:v1.31.4-k3s1",
+    });
+    expect(cmd).toContain("--servers 1");
+    expect(cmd).toContain("--agents 2");
+    expect(cmd).toContain("--image rancher/k3s:v1.31.4-k3s1");
+  });
+
+  test("each port becomes a quoted -p flag", () => {
+    const cmd = k3dUpCommand({
+      name: "dev",
+      ports: ["8080:80@loadbalancer", "8443:443@loadbalancer"],
+    });
+    expect(cmd).toContain('-p "8080:80@loadbalancer"');
+    expect(cmd).toContain('-p "8443:443@loadbalancer"');
+  });
+
+  test("registry and config file", () => {
+    const cmd = k3dUpCommand({
+      name: "dev",
+      registryCreate: "chant-registry",
+      configFile: "k3d.yaml",
+    });
+    expect(cmd).toContain("--registry-create chant-registry");
+    expect(cmd).toContain("--config k3d.yaml");
+  });
+
+  test("custom timeout overrides the default", () => {
+    const cmd = k3dUpCommand({ name: "dev", timeout: "300s" });
+    expect(cmd).toContain("--timeout 300s");
+    expect(cmd).not.toContain("120s");
+  });
+
+  test("zero servers is emitted (not dropped as falsy)", () => {
+    // servers: 0 is unusual but must round-trip — guarded by `!== undefined`.
+    const cmd = k3dUpCommand({ name: "dev", servers: 0 });
+    expect(cmd).toContain("--servers 0");
+  });
+});
+
+describe("k3dUpCommand — kubeconfig flag mapping (#1411)", () => {
+  test("no configFile, args unset: both flags forced to chant's safe false", () => {
+    const cmd = k3dUpCommand({ name: "dev" });
+    expect(cmd).toContain("--kubeconfig-update-default=false");
+    expect(cmd).toContain("--kubeconfig-switch-context=false");
+  });
+
+  test("configFile present, args unset: no kubeconfig flags — the declared config governs", () => {
+    // k3d gives CLI flags precedence over config, so emitting our defaults
+    // here would silently override a config's declared `options.kubeconfig`.
+    const cmd = k3dUpCommand({ name: "dev", configFile: "k3d.yaml" });
+    expect(cmd).not.toContain("--kubeconfig-update-default");
+    expect(cmd).not.toContain("--kubeconfig-switch-context");
+  });
+
+  test("explicit true is passed through, even alongside a configFile", () => {
+    const cmd = k3dUpCommand({
+      name: "dev",
+      configFile: "k3d.yaml",
+      updateDefaultKubeconfig: true,
+      switchCurrentContext: true,
+    });
+    expect(cmd).toContain("--kubeconfig-update-default=true");
+    expect(cmd).toContain("--kubeconfig-switch-context=true");
+  });
+
+  test("explicit false alongside a configFile is also passed (caller overrides config)", () => {
+    const cmd = k3dUpCommand({
+      name: "dev",
+      configFile: "k3d.yaml",
+      updateDefaultKubeconfig: false,
+    });
+    expect(cmd).toContain("--kubeconfig-update-default=false");
+    // switchCurrentContext stays unset — the config governs it.
+    expect(cmd).not.toContain("--kubeconfig-switch-context");
+  });
+
+  test("flags can be set independently without a configFile", () => {
+    const cmd = k3dUpCommand({ name: "dev", switchCurrentContext: true });
+    expect(cmd).toContain("--kubeconfig-update-default=false");
+    expect(cmd).toContain("--kubeconfig-switch-context=true");
+  });
+});
+
+describe("k3dUp result shape (#1411)", () => {
+  test("default (kubeconfig untouched): returns context + dedicated kubeconfig path", async () => {
+    // The mocked `cluster list` reports the cluster as existing, so this runs
+    // the skip path; the mocked `kubeconfig write` prints a path.
+    const result = await k3dUp({ name: "dev" });
+    expect(result).toEqual({
+      context: "k3d-dev",
+      kubeconfigPath: "/home/user/.config/k3d/kubeconfig-dev.yaml",
+    });
+  });
+
+  test("explicit updateDefaultKubeconfig: true — context only, no dedicated kubeconfig", async () => {
+    const result = await k3dUp({ name: "dev", updateDefaultKubeconfig: true });
+    expect(result).toEqual({ context: "k3d-dev" });
+    expect(result.kubeconfigPath).toBeUndefined();
+  });
+});
+
+describe("k3dDownCommand (#704)", () => {
+  test("deletes the named cluster", () => {
+    expect(k3dDownCommand({ name: "chant-local" })).toBe(
+      "k3d cluster delete chant-local",
+    );
+  });
+});
+
+describe("k3dExistsCommand (#704)", () => {
+  test("lists a single cluster with no headers for an emptiness check", () => {
+    expect(k3dExistsCommand("chant-local")).toBe(
+      "k3d cluster list chant-local --no-headers",
+    );
+  });
+});
+
+describe("k3dKubeconfigWriteCommand / k3dContextName (#1411)", () => {
+  test("writes the named cluster's kubeconfig", () => {
+    expect(k3dKubeconfigWriteCommand("chant-local")).toBe(
+      "k3d kubeconfig write chant-local",
+    );
+  });
+
+  test("context name is k3d-<name>", () => {
+    expect(k3dContextName("chant-local")).toBe("k3d-chant-local");
+  });
+});

package/src/op/activities/k3d.ts

@@ -0,0 +1,183 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { safeHeartbeat } from "@intentius/chant/op";
+
+const execAsync = promisify(exec);
+
+export interface K3dUpArgs {
+  /** Cluster name (`k3d cluster create <name>`). */
+  name: string;
+  /** Number of server (control-plane) nodes. */
+  servers?: number;
+  /** Number of agent (worker) nodes. */
+  agents?: number;
+  /** k3s image, e.g. `rancher/k3s:v1.31.4-k3s1`. */
+  image?: string;
+  /** Port mappings, e.g. `["8080:80@loadbalancer"]`. */
+  ports?: string[];
+  /** Create a managed local registry with this name (`--registry-create`). */
+  registryCreate?: string;
+  /** Path to a k3d config file (`--config`). */
+  configFile?: string;
+  /** Readiness timeout for `--wait`. Default: `120s`. */
+  timeout?: string;
+  /**
+   * Merge the new cluster into the caller's default kubeconfig
+   * (`--kubeconfig-update-default=<bool>`). Chant's default is `false` —
+   * deliberately the opposite of upstream k3d's `true`: a tool that reconciles
+   * infrastructure must not repoint the caller's shell. The context-hijack
+   * false-failure during #1394's scoping is the receipt. When the default
+   * kubeconfig is left alone, {@link k3dUp} writes a dedicated kubeconfig and
+   * returns its path so later steps can still reach the cluster.
+   *
+   * With a `configFile` and this arg unset, no flag is passed at all — the
+   * declared config's own `options.kubeconfig` governs (k3d gives CLI flags
+   * precedence over config, so a declared `true` keeps working).
+   */
+  updateDefaultKubeconfig?: boolean;
+  /**
+   * Switch the caller's current kubectl context to the new cluster
+   * (`--kubeconfig-switch-context=<bool>`). Chant's default is `false` — see
+   * {@link K3dUpArgs.updateDefaultKubeconfig} for why chant inverts upstream's
+   * default. Same `configFile` rule: unset alongside a `configFile`, no flag
+   * is passed and the config governs.
+   */
+  switchCurrentContext?: boolean;
+}
+
+export interface K3dDownArgs {
+  /** Cluster name to delete. */
+  name: string;
+}
+
+/** What {@link k3dUp} resolved for talking to the cluster. */
+export interface K3dUpResult {
+  /** kubectl context name for the cluster — always `k3d-<name>`. */
+  context: string;
+  /**
+   * Path of the dedicated kubeconfig (`k3d kubeconfig write <name>`), present
+   * whenever the caller did not explicitly merge into the default kubeconfig —
+   * without it the context exists nowhere a later `kubectl` step could find it.
+   */
+  kubeconfigPath?: string;
+}
+
+/** `k3d cluster list <name> --no-headers` — non-empty stdout means the cluster exists. */
+export function k3dExistsCommand(name: string): string {
+  return `k3d cluster list ${name} --no-headers`;
+}
+
+/** kubectl context name k3d assigns a cluster: `k3d-<name>`. */
+export function k3dContextName(name: string): string {
+  return `k3d-${name}`;
+}
+
+/** `k3d kubeconfig write <name>` — prints the path of the written kubeconfig. */
+export function k3dKubeconfigWriteCommand(name: string): string {
+  return `k3d kubeconfig write ${name}`;
+}
+
+/**
+ * Build the `k3d cluster create` command.
+ *
+ * Kubeconfig behavior: upstream k3d merges the new cluster into the default
+ * kubeconfig and switches the current context. Chant defaults both to `false`
+ * (see {@link K3dUpArgs.updateDefaultKubeconfig}) — but only forces its
+ * defaults when no `configFile` is given. Each kubeconfig flag is emitted when
+ * the caller set it explicitly, or when there is no `configFile`; with a
+ * `configFile` and the arg unset, the flag is omitted so the declared config's
+ * `options.kubeconfig` governs.
+ */
+export function k3dUpCommand(args: K3dUpArgs): string {
+  const parts = ["k3d", "cluster", "create", args.name];
+  if (args.servers !== undefined) parts.push(`--servers ${args.servers}`);
+  if (args.agents !== undefined) parts.push(`--agents ${args.agents}`);
+  if (args.image) parts.push(`--image ${args.image}`);
+  for (const p of args.ports ?? []) parts.push(`-p "${p}"`);
+  if (args.registryCreate) parts.push(`--registry-create ${args.registryCreate}`);
+  if (args.configFile) parts.push(`--config ${args.configFile}`);
+  if (!args.configFile || args.updateDefaultKubeconfig !== undefined) {
+    parts.push(`--kubeconfig-update-default=${args.updateDefaultKubeconfig ?? false}`);
+  }
+  if (!args.configFile || args.switchCurrentContext !== undefined) {
+    parts.push(`--kubeconfig-switch-context=${args.switchCurrentContext ?? false}`);
+  }
+  parts.push("--wait");
+  parts.push(`--timeout ${args.timeout ?? "120s"}`);
+  return parts.join(" ");
+}
+
+/** Build the `k3d cluster delete` command. */
+export function k3dDownCommand(args: K3dDownArgs): string {
+  return `k3d cluster delete ${args.name}`;
+}
+
+/**
+ * Resolve and report how to reach the cluster. Only an explicit
+ * `updateDefaultKubeconfig: true` proves the context landed in the default
+ * kubeconfig; in every other case (chant's `false` default, or an opaque
+ * `configFile` whose `options.kubeconfig` we cannot see) a dedicated
+ * kubeconfig is written so the returned path always works.
+ */
+async function resolveConnection(args: K3dUpArgs, signal?: AbortSignal): Promise<K3dUpResult> {
+  const context = k3dContextName(args.name);
+  if (args.updateDefaultKubeconfig === true) {
+    console.log(
+      `k3d cluster "${args.name}" ready — context "${context}" (merged into the default kubeconfig)`,
+    );
+    return { context };
+  }
+  const { stdout } = await execAsync(k3dKubeconfigWriteCommand(args.name), { signal });
+  const kubeconfigPath = stdout.trim();
+  console.log(
+    `k3d cluster "${args.name}" ready — context "${context}", kubeconfig: ${kubeconfigPath}`,
+  );
+  return { context, kubeconfigPath };
+}
+
+/**
+ * Create a local k3d cluster (vanilla Kubernetes in Docker). Idempotent: if a
+ * cluster of the same name already exists it is left as-is. Uses longInfra
+ * profile — 20m timeout, heartbeat every 15s (creation may pull the k3s image).
+ *
+ * Unlike the upstream CLI, this does NOT touch the caller's default kubeconfig
+ * or current context unless asked (see {@link K3dUpArgs.updateDefaultKubeconfig}).
+ * It returns the context name and, when the default kubeconfig was left alone,
+ * the path of a dedicated kubeconfig — pass those to the steps that apply
+ * manifests afterwards.
+ */
+export async function k3dUp(args: K3dUpArgs, signal?: AbortSignal): Promise<K3dUpResult> {
+  try {
+    const { stdout } = await execAsync(k3dExistsCommand(args.name), { signal });
+    if (stdout.trim()) {
+      console.log(`k3d cluster "${args.name}" already exists — skipping create`);
+      return await resolveConnection(args, signal);
+    }
+  } catch {
+    // `cluster list` errors when the cluster is absent — fall through to create.
+  }
+
+  const heartbeatInterval = setInterval(() => {
+    safeHeartbeat({ step: "k3d cluster create", cluster: args.name });
+  }, 15_000);
+
+  try {
+    const { stdout, stderr } = await execAsync(k3dUpCommand(args), { signal });
+    if (stdout) console.log(stdout);
+    if (stderr) console.error(stderr);
+  } finally {
+    clearInterval(heartbeatInterval);
+  }
+
+  return resolveConnection(args, signal);
+}
+
+/**
+ * Delete a local k3d cluster. Uses fastIdempotent profile — 5m timeout.
+ * `k3d cluster delete` is a no-op success when the cluster is already gone.
+ */
+export async function k3dDown(args: K3dDownArgs, signal?: AbortSignal): Promise<void> {
+  const { stdout, stderr } = await execAsync(k3dDownCommand(args), { signal });
+  if (stdout) console.log(stdout);
+  if (stderr) console.error(stderr);
+}

package/src/package-cli.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env tsx
+/**
+ * Thin entry point for `npm run bundle` in lexicon-k3d.
+ */
+import { generate, writeGeneratedFiles } from "./codegen/generate";
+import { packageLexicon } from "./codegen/package";
+import { writeFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(fileURLToPath(import.meta.url));
+
+// 1. Generate src/generated/ files (writeGeneratedFiles resolves its own target)
+const genResult = await generate({ verbose: true });
+writeGeneratedFiles(genResult);
+
+// 2. Run package pipeline and write dist/
+const { spec, stats } = await packageLexicon({ verbose: true });
+
+const distDir = join(dirname(pkgDir), "dist");
+mkdirSync(join(distDir, "types"), { recursive: true });
+mkdirSync(join(distDir, "rules"), { recursive: true });
+mkdirSync(join(distDir, "skills"), { recursive: true });
+
+writeFileSync(join(distDir, "manifest.json"), JSON.stringify(spec.manifest, null, 2));
+writeFileSync(join(distDir, "meta.json"), spec.registry);
+writeFileSync(join(distDir, "types", "index.d.ts"), spec.typesDTS);
+
+for (const [name, content] of spec.rules) {
+  writeFileSync(join(distDir, "rules", name), content);
+}
+for (const [name, content] of spec.skills) {
+  writeFileSync(join(distDir, "skills", name), content);
+}
+
+if (spec.integrity) {
+  writeFileSync(join(distDir, "integrity.json"), JSON.stringify(spec.integrity, null, 2));
+}
+
+console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+console.error(`dist/ written to ${distDir}`);

package/src/plugin.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { k3dPlugin } from "./plugin";
+import { isLexiconPlugin } from "@intentius/chant/lexicon";
+
+describe("k3d plugin", () => {
+  it("is a valid LexiconPlugin", () => {
+    expect(isLexiconPlugin(k3dPlugin)).toBe(true);
+  });
+
+  it("has the correct name", () => {
+    expect(k3dPlugin.name).toBe("k3d");
+  });
+
+  it("has a serializer", () => {
+    expect(k3dPlugin.serializer).toBeDefined();
+  });
+});