@intentius/chant-lexicon-k3d 0.124.30 → 0.124.32

package/dist/describe-resources.js

@@ -0,0 +1,102 @@
+/**
+ * Live observation for declared k3d clusters (#1412).
+ *
+ * The read is two commands: `k3d cluster list -o json` for presence and
+ * running state, and `docker inspect` on the cluster's first server node for
+ * the ownership marker — k3d's list output carries a `runtimeLabels` field
+ * but only k3d's own `k3d.*` labels appear in it, so the custom labels the
+ * serializer stamps via `options.runtime.labels` are only visible to Docker.
+ * Verified live before this was written; see #1412.
+ *
+ * The tri-state is the whole report (#1089): a declared cluster is present,
+ * absent, or not-observed-with-a-reason. k3d or Docker being unavailable is
+ * `read-failed` for everything — never absence, because proposing to create
+ * a cluster while Docker is stopped is the false finding the contract
+ * exists to prevent. There is no property-level drift here on purpose: the
+ * declared config is an input to creation, not a spec k3d reconciles
+ * against, so node counts diverging is not "drift" anyone can act on.
+ */
+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";
+const execAsync = promisify(exec);
+const CLUSTER_TYPE = "K3d::Cluster";
+/** The cluster name a declaration resolves to: metadata.name, else the entity name. */
+export function declaredClusterName(entity) {
+    const metadata = entity.props.metadata;
+    const name = metadata?.name;
+    return typeof name === "string" && name.length > 0 ? name : entity.name;
+}
+function clusterStatus(cluster) {
+    const total = cluster.serversCount ?? cluster.nodes?.filter((n) => n.role === "server").length ?? 0;
+    const running = cluster.serversRunning ??
+        cluster.nodes?.filter((n) => n.role === "server" && n.State?.Running).length ??
+        0;
+    if (total === 0)
+        return "unknown";
+    if (running === 0)
+        return "stopped";
+    return running < total ? "degraded" : "running";
+}
+function adapter(execFn) {
+    return {
+        async bind() {
+            const { stdout } = await execFn("k3d cluster list -o json");
+            const parsed = JSON.parse(stdout || "[]");
+            return Array.isArray(parsed) ? parsed : [];
+        },
+        classifyBindFailure(err) {
+            // k3d missing, Docker stopped, or unparsable output — all mean "could
+            // not look", never "not there".
+            const detail = err instanceof Error ? err.message.split("\n")[0] : String(err);
+            return { reason: "read-failed", detail };
+        },
+        async read(clusters, entity) {
+            if (entity.type !== CLUSTER_TYPE) {
+                return { unobserved: { reason: "unsupported-kind", detail: entity.type } };
+            }
+            const name = declaredClusterName(entity);
+            const cluster = clusters.find((c) => c.name === name);
+            if (!cluster)
+                return { absent: true };
+            // The marker lives on the server node's Docker labels; k3d's list JSON
+            // does not surface custom labels, so ask Docker. A cluster that is
+            // present but uninspectable still reports present — with the honest
+            // `unknown` verdict rather than a guessed one.
+            let ownership = "unknown";
+            try {
+                const { stdout } = await execFn(`docker inspect k3d-${name}-server-0 --format '{{json .Config.Labels}}'`);
+                const labels = JSON.parse(stdout.trim().replace(/^'|'$/g, "") || "{}");
+                ownership = classifyOwnership(labels, LABEL_OWNERSHIP_KEYS);
+            }
+            catch {
+                ownership = "unknown";
+            }
+            return {
+                present: {
+                    type: CLUSTER_TYPE,
+                    physicalId: name,
+                    status: clusterStatus(cluster),
+                    ownership,
+                    attributes: {
+                        servers: cluster.serversCount ?? undefined,
+                        agents: cluster.agentsCount ?? undefined,
+                        serversRunning: cluster.serversRunning ?? undefined,
+                    },
+                },
+            };
+        },
+    };
+}
+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 ?? {},
+        };
+    });
+    return observeEntities(declared, adapter(execFn));
+}

package/dist/generated/index.js

@@ -0,0 +1,24 @@
+// Code generated by chant generate. DO NOT EDIT.
+import { createResource, createProperty } from "./runtime.js";
+export const Cluster = /* @__PURE__ */ createResource("K3d::Cluster", "k3d", {});
+export const EnvVar = /* @__PURE__ */ createProperty("K3d::EnvVar", "k3d");
+export const File = /* @__PURE__ */ createProperty("K3d::File", "k3d");
+export const HostAlias = /* @__PURE__ */ createProperty("K3d::HostAlias", "k3d");
+export const K3dOptions = /* @__PURE__ */ createProperty("K3d::K3dOptions", "k3d");
+export const K3sExtraArg = /* @__PURE__ */ createProperty("K3d::K3sExtraArg", "k3d");
+export const K3sOptions = /* @__PURE__ */ createProperty("K3d::K3sOptions", "k3d");
+export const KubeAPI = /* @__PURE__ */ createProperty("K3d::KubeAPI", "k3d");
+export const KubeconfigOptions = /* @__PURE__ */ createProperty("K3d::KubeconfigOptions", "k3d");
+export const LoadbalancerOptions = /* @__PURE__ */ createProperty("K3d::LoadbalancerOptions", "k3d");
+export const Metadata = /* @__PURE__ */ createProperty("K3d::Metadata", "k3d");
+export const NodeLabel = /* @__PURE__ */ createProperty("K3d::NodeLabel", "k3d");
+export const Options = /* @__PURE__ */ createProperty("K3d::Options", "k3d");
+export const Port = /* @__PURE__ */ createProperty("K3d::Port", "k3d");
+export const Registries = /* @__PURE__ */ createProperty("K3d::Registries", "k3d");
+export const RegistryCreate = /* @__PURE__ */ createProperty("K3d::RegistryCreate", "k3d");
+export const RegistryProxy = /* @__PURE__ */ createProperty("K3d::RegistryProxy", "k3d");
+export const RuntimeLabel = /* @__PURE__ */ createProperty("K3d::RuntimeLabel", "k3d");
+export const RuntimeOptions = /* @__PURE__ */ createProperty("K3d::RuntimeOptions", "k3d");
+export const Ulimit = /* @__PURE__ */ createProperty("K3d::Ulimit", "k3d");
+export const Volume = /* @__PURE__ */ createProperty("K3d::Volume", "k3d");
+// 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,11 @@
+// Typed Op step-builder wrappers (chant #1288 Stage 2) — k3dUp/k3dDown 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 { k3dUp, k3dDown } from "./op/builders.js";
+// Plugin
+export { k3dPlugin } from "./plugin.js";
+// Serializer
+export { k3dSerializer } from "./serializer.js";
+// Generated resources — export everything from generated index
+export * from "./generated/index.js";

package/dist/lint/audit-catalog.js

@@ -0,0 +1,11 @@
+/**
+ * The k3d lexicon's chant audit catalog — metadata for its post-synth
+ * checks, contributed via k3dPlugin.auditCatalog() (#687, #1346). Every
+ * post-synth check has an entry, or the check contributes nothing to
+ * `chant audit`, silently.
+ */
+import { auditRule } from "@intentius/chant/audit/catalog";
+export const k3dAuditCatalog = {
+    K3D101: auditRule("K3D101", "merge-worthy", "guidance", "nodeFilter matches no node", 'Use a real k3d selector: "all", "loadbalancer", or "server"/"agent" with ":<index>" or ":*".', { category: "correctness" }),
+    K3D102: auditRule("K3D102", "merge-worthy", "guidance", "Registry proxy password in the emitted cluster config", "Remove the credential from the declaration; connect the registry via registries.use or configure the proxy outside chant.", { category: "security" }),
+};

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

@@ -0,0 +1,6 @@
+import { k3d101 } from "./k3d101.js";
+import { k3d102 } from "./k3d102.js";
+export const postSynthChecks = [
+    k3d101,
+    k3d102,
+];

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

@@ -0,0 +1,84 @@
+/**
+ * K3D101: malformed nodeFilters.
+ *
+ * `nodeFilters` are k3d's own selector syntax and the schema types them as
+ * bare strings, so a typo validates, applies to nothing, and reports
+ * nothing — the port mapping or volume silently lands nowhere. This is the
+ * silent-at-create failure worth an error.
+ *
+ * Valid forms (k3d v5): `all`, `loadbalancer`, or `server`/`agent` with an
+ * optional `:<index>` / `:*`, and for port mappings an optional trailing
+ * `:direct` / `:proxy`.
+ */
+import { load, loadAll } from "js-yaml";
+const VALID_FILTER = /^(all|loadbalancer|server|agent)(:(\d+|\*))?(:(direct|proxy))?$/;
+export function k3dDocuments(ctx) {
+    const docs = [];
+    for (const [outputName, output] of ctx.outputs) {
+        const texts = typeof output === "string"
+            ? [[outputName, output]]
+            : [
+                [outputName, output.primary],
+                ...Object.entries(output.files ?? {}),
+            ];
+        for (const [source, text] of texts) {
+            if (!text || !text.includes("k3d.io/"))
+                continue;
+            try {
+                for (const doc of loadAll(text))
+                    docs.push({ source, doc });
+            }
+            catch {
+                try {
+                    docs.push({ source, doc: load(text) });
+                }
+                catch {
+                    // not YAML — someone else's output
+                }
+            }
+        }
+    }
+    return docs;
+}
+function collectFilters(value, path, out) {
+    if (Array.isArray(value)) {
+        value.forEach((v, i) => collectFilters(v, `${path}[${i}]`, out));
+        return;
+    }
+    if (typeof value !== "object" || value === null)
+        return;
+    for (const [key, v] of Object.entries(value)) {
+        if (key === "nodeFilters" && Array.isArray(v)) {
+            v.forEach((f, i) => {
+                if (typeof f === "string")
+                    out.push({ path: `${path}.nodeFilters[${i}]`, filter: f });
+            });
+            continue;
+        }
+        collectFilters(v, path ? `${path}.${key}` : key, out);
+    }
+}
+export const k3d101 = {
+    id: "K3D101",
+    description: "A nodeFilter that matches no node applies to nothing, silently",
+    check(ctx) {
+        const diagnostics = [];
+        for (const { source, doc } of k3dDocuments(ctx)) {
+            const filters = [];
+            collectFilters(doc, "", filters);
+            for (const { path, filter } of filters) {
+                if (VALID_FILTER.test(filter))
+                    continue;
+                diagnostics.push({
+                    checkId: "K3D101",
+                    severity: "error",
+                    message: `${source}: nodeFilter "${filter}" at ${path} is not a k3d selector — valid forms are ` +
+                        `"all", "loadbalancer", "server"/"agent" with optional ":<index>" or ":*", plus ` +
+                        `":direct"/":proxy" on port mappings. k3d applies an unmatched filter to nothing and says nothing.`,
+                    lexicon: "k3d",
+                });
+            }
+        }
+        return diagnostics;
+    },
+};

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

@@ -0,0 +1,36 @@
+/**
+ * K3D102: registry proxy credential in the emitted config.
+ *
+ * The other half of K3D001: the lint rule sees literals in source, this
+ * sees what actually landed in the artifact — a value that arrived through
+ * a variable, a helper, or anything else the AST rule cannot follow. The
+ * emitted config is the file people commit, attach to issues and copy to
+ * other machines, which is exactly where a registry credential must not be.
+ */
+import { k3dDocuments } from "./k3d101.js";
+export const k3d102 = {
+    id: "K3D102",
+    description: "The emitted cluster config carries a registry proxy password",
+    check(ctx) {
+        const diagnostics = [];
+        for (const { source, doc } of k3dDocuments(ctx)) {
+            if (typeof doc !== "object" || doc === null)
+                continue;
+            const registries = doc.registries;
+            const create = registries?.create;
+            const proxy = create?.proxy;
+            const password = proxy?.password;
+            if (typeof password === "string" && password.length > 0) {
+                diagnostics.push({
+                    checkId: "K3D102",
+                    severity: "error",
+                    message: `${source}: registries.create.proxy.password is present in the emitted config — ` +
+                        `this file is the walk-away artifact and a credential inside it is a credential in source. ` +
+                        `Connect a pre-existing registry via registries.use, or supply the proxy credential outside chant.`,
+                    lexicon: "k3d",
+                });
+            }
+        }
+        return diagnostics;
+    },
+};

package/dist/lint/rules/index.js

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

package/dist/lint/rules/registry-proxy-password.js

@@ -0,0 +1,81 @@
+import { ts } from "@intentius/chant/lint/typescript";
+/**
+ * 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 = {
+    id: "K3D001",
+    severity: "error",
+    category: "security",
+    description: "Registry proxy password declared as a string literal in source",
+    check(context) {
+        const diagnostics = [];
+        const source = context.sourceFile;
+        const flag = (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) => {
+            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) => {
+            // 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/dist/lsp/completions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"completions.d.ts","sourceRoot":"","sources":["../../src/lsp/completions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAapF;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,iBAAiB,GAAG,cAAc,EAAE,CAEpE"}
+{"version":3,"file":"completions.d.ts","sourceRoot":"","sources":["../../src/lsp/completions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAapF;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,iBAAiB,GAAG,cAAc,EAAE,CAEpE"}

package/dist/lsp/completions.js

@@ -0,0 +1,19 @@
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+import { LexiconIndex, lexiconCompletions } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(moduleSourceUrl(import.meta.url));
+let cachedIndex = null;
+function getIndex() {
+    if (cachedIndex)
+        return cachedIndex;
+    const data = require("../generated/lexicon-k3d.json");
+    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) {
+    return lexiconCompletions(ctx, getIndex(), "k3d entity");
+}

package/dist/lsp/hover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hover.d.ts","sourceRoot":"","sources":["../../src/lsp/hover.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAa1E;;GAEG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAE9D"}
+{"version":3,"file":"hover.d.ts","sourceRoot":"","sources":["../../src/lsp/hover.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAa1E;;GAEG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAE9D"}

package/dist/lsp/hover.js

@@ -0,0 +1,33 @@
+import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
+import { LexiconIndex, lexiconHover } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(moduleSourceUrl(import.meta.url));
+let cachedIndex = null;
+function getIndex() {
+    if (cachedIndex)
+        return cachedIndex;
+    const data = require("../generated/lexicon-k3d.json");
+    cachedIndex = new LexiconIndex(data);
+    return cachedIndex;
+}
+/**
+ * Provide hover information for k3d entity types.
+ */
+export function hover(ctx) {
+    return lexiconHover(ctx, getIndex(), resourceHover);
+}
+function resourceHover(className, entry) {
+    const lines = [];
+    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/dist/op/activities/index.js

@@ -0,0 +1,17 @@
+/**
+ * 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 and reach authors through
+ * `@intentius/chant/op` 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 `loadActivities`
+ * (`packages/core/src/op/activity-registry.ts`), which imports this module at
+ * run time, pulls in nothing expensive.
+ */
+export { k3dUp, k3dDown, k3dUpCommand, k3dDownCommand, k3dExistsCommand, k3dKubeconfigWriteCommand, k3dContextName, } from "./k3d.js";

package/dist/op/activities/k3d.js

@@ -0,0 +1,113 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+/** `k3d cluster list <name> --no-headers` — non-empty stdout means the cluster exists. */
+export function k3dExistsCommand(name) {
+    return `k3d cluster list ${name} --no-headers`;
+}
+/** kubectl context name k3d assigns a cluster: `k3d-<name>`. */
+export function k3dContextName(name) {
+    return `k3d-${name}`;
+}
+/** `k3d kubeconfig write <name>` — prints the path of the written kubeconfig. */
+export function k3dKubeconfigWriteCommand(name) {
+    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) {
+    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) {
+    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, signal) {
+    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 the longInfra
+ * profile: a 20m timeout, wide enough that creation can pull the k3s image, and
+ * three attempts backing off from 30s.
+ *
+ * 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, signal) {
+    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 { stdout, stderr } = await execAsync(k3dUpCommand(args), { signal });
+    if (stdout)
+        console.log(stdout);
+    if (stderr)
+        console.error(stderr);
+    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, signal) {
+    const { stdout, stderr } = await execAsync(k3dDownCommand(args), { signal });
+    if (stdout)
+        console.log(stdout);
+    if (stderr)
+        console.error(stderr);
+}

package/dist/op/builders.js

@@ -0,0 +1,30 @@
+/**
+ * Typed step-builder wrappers for this lexicon's activities (chant #1288
+ * Stage 2). See `lexicons/k8s/src/op/builders.ts`'s module doc for why these
+ * live beside their `*Args` interfaces rather than in core: core cannot
+ * import a lexicon's types, so a wrapper whose `opts` IS the activity's own
+ * `*Args` interface can only sit in the lexicon that declares that
+ * interface. `opts`'s type in each wrapper below IS the activity's own
+ * `*Args` interface (via `Omit`/`WithStepRefs`) — never restated. `core`'s own
+ * `k3dUp`/`k3dDown` are unchanged and produce byte-identical `ActivityStep`
+ * output; these are purely additive.
+ */
+import { activity, takeProfileAndId, } from "@intentius/chant/op";
+/**
+ * Create a local k3d cluster — the fully typed twin of core's `k3dUp`.
+ * `opts` is {@link K3dUpArgs} itself, minus the positional `name`. Defaults
+ * to the `longInfra` profile.
+ */
+export const k3dUp = (name, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("k3dUp", { name, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+/**
+ * Delete a local k3d cluster — the fully typed twin of core's `k3dDown`.
+ * `opts` is {@link K3dDownArgs} itself, minus the positional `name`.
+ * Defaults to the `fastIdempotent` profile.
+ */
+export const k3dDown = (name, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("k3dDown", { name, ...args }, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};

package/dist/package-cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env tsx
+/**
+ * Thin entry point for `npm run bundle` in lexicon-k3d.
+ */
+import { generate, writeGeneratedFiles } from "./codegen/generate.js";
+import { packageLexicon } from "./codegen/package.js";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+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");
+writeBundleSpec(spec, distDir);
+console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+console.error(`dist/ written to ${distDir}`);