@intentius/chant-lexicon-k3d 0.124.31 → 0.124.33

package/dist/plugin.js

@@ -0,0 +1,88 @@
+import { LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+import { k3dSerializer } from "./serializer.js";
+import { rules } from "./lint/rules/index.js";
+import { postSynthChecks } from "./lint/post-synth/index.js";
+import { k3dAuditCatalog } from "./lint/audit-catalog.js";
+import { completions } from "./lsp/completions.js";
+import { hover } from "./lsp/hover.js";
+/**
+ * k3d lexicon plugin.
+ *
+ * Implements all required LexiconPlugin lifecycle methods.
+ */
+export const k3dPlugin = {
+    name: "k3d",
+    serializer: k3dSerializer,
+    /**
+     * The marker is stamped as Docker labels on every node via
+     * `options.runtime.labels` (the serializer does this when a build carries
+     * ownership) and read back through `docker inspect` — k3d's own list
+     * output does not expose custom labels (#1412, verified live). Labels
+     * survive `k3d cluster stop`/`start`.
+     */
+    ownershipChannel: {
+        keys: LABEL_OWNERSHIP_KEYS,
+        reads: ["describeResources"],
+    },
+    async describeResources(options) {
+        const { describeResources } = await import("./describe-resources.js");
+        return describeResources(options);
+    },
+    // ── Required lifecycle methods ────────────────────────────────
+    async generate(options) {
+        const { generate } = await import("./codegen/generate.js");
+        await generate(options);
+    },
+    async validate(options) {
+        const { validate } = await import("./validate.js");
+        const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+        const result = await validate();
+        printValidationResult(result);
+    },
+    async coverage(options) {
+        // TODO: Implement coverage analysis
+        console.error("Coverage analysis not yet implemented");
+    },
+    async package(options) {
+        const { packageLexicon } = await import("./codegen/package.js");
+        const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+        const { join, dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const { spec, stats } = await packageLexicon(options);
+        const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+        writeBundleSpec(spec, join(pkgDir, "dist"));
+        console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+    },
+    // ── Optional extensions ────────────────────────────────────
+    lintRules() {
+        return rules;
+    },
+    postSynthChecks() {
+        return postSynthChecks;
+    },
+    auditCatalog() {
+        return k3dAuditCatalog;
+    },
+    skills() {
+        return []; // TODO: Add skills
+    },
+    mcpTools() {
+        return []; // TODO: Implement MCP tools
+    },
+    mcpResources() {
+        return []; // TODO: Implement MCP resources
+    },
+    detectTemplate(data) {
+        return false; // TODO: Detect if a template belongs to this lexicon
+    },
+    completionProvider(ctx) {
+        return completions(ctx);
+    },
+    hoverProvider(ctx) {
+        return hover(ctx);
+    },
+    async docs(options) {
+        const { generateDocs } = await import("./codegen/docs.js");
+        return generateDocs(options);
+    },
+};

package/dist/serializer.js

@@ -0,0 +1,179 @@
+/**
+ * k3d SimpleConfig YAML serializer.
+ *
+ * Emits the config file `k3d cluster create --config` consumes verbatim —
+ * the walk-away artifact that justifies a lexicon here at all. One YAML
+ * document per declared Cluster: the first is the primary output, any
+ * further clusters land in files[] keyed `<name>.k3d.yaml`.
+ *
+ * Three things are non-negotiable in the output (#1408):
+ *
+ *   - `apiVersion` and `kind` are literal schema properties, not derived
+ *     from a type name. They default when undeclared and are never dropped.
+ *   - Booleans stay booleans and zero stays zero. `agents: 0` is the normal
+ *     local shape and `updateDefaultKubeconfig: "false"` is truthy.
+ *   - `nodeFilters` pass through untouched — they are k3d's own syntax
+ *     (`server:0`, `agent:*`, `loadbalancer`) and rewriting them here would
+ *     be inventing a dialect.
+ *
+ * ## The kubeconfig default is chant's, not upstream's
+ *
+ * When a declaration says nothing about `options.kubeconfig`, the emitted
+ * config pins `updateDefaultKubeconfig: false` and `switchCurrentContext:
+ * false` — the opposite of k3d's own defaults, chosen deliberately (#1411):
+ * a tool that reconciles infrastructure must not rewrite ~/.kube/config or
+ * repoint the caller's shell as a side effect. Injecting the values into the
+ * artifact rather than relying on activity flags means the emitted YAML says
+ * on its face what creating the cluster will do, and `k3d --config` applied
+ * by hand behaves identically. A declaration that sets `options.kubeconfig`
+ * itself — either key — is passed through exactly as written; upstream
+ * defaults then apply to whatever it left unset, because a partially
+ * explicit block is the author taking the wheel.
+ */
+import { isResourceDeclarable } from "@intentius/chant/declarable";
+import { walkValue } from "@intentius/chant/serializer-walker";
+import { emitYAMLEntry } from "@intentius/chant/yaml";
+import { ownershipEntries, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+const CLUSTER_TYPE = "K3d::Cluster";
+const API_VERSION = "k3d.io/v1alpha5";
+const KIND = "Simple";
+/**
+ * Top-level key order, matching the schema's own property order so a chant
+ * emission diffs cleanly against upstream's documented examples.
+ */
+const KEY_ORDER = [
+    "apiVersion",
+    "kind",
+    "metadata",
+    "servers",
+    "agents",
+    "kubeAPI",
+    "image",
+    "network",
+    "subnet",
+    "token",
+    "volumes",
+    "ports",
+    "files",
+    "env",
+    "registries",
+    "hostAliases",
+    "options",
+];
+const visitor = {
+    attrRef: (name) => name,
+    resourceRef: (name) => name,
+    propertyDeclarable: (entity, walk) => {
+        if (!isResourceDeclarable(entity) || typeof entity.props !== "object" || entity.props === null) {
+            return undefined;
+        }
+        const props = entity.props;
+        const result = {};
+        for (const [key, value] of Object.entries(props)) {
+            if (value !== undefined)
+                result[key] = walk(value);
+        }
+        return result;
+    },
+};
+/**
+ * Stamp the ownership marker as Docker labels on every node, via
+ * `options.runtime.labels` (#1412). The labels survive `k3d cluster stop`/
+ * `start` and are readable back through `docker inspect` — verified live;
+ * `k3d cluster list -o json` does not expose custom labels, so the read
+ * side goes to Docker. An author's own label with the same key wins.
+ */
+function stampOwnership(options, ownership) {
+    const runtime = { ...(options.runtime ?? {}) };
+    const labels = Array.isArray(runtime.labels) ? [...runtime.labels] : [];
+    const present = new Set(labels
+        .map((l) => (typeof l === "object" && l !== null ? l.label : undefined))
+        .filter((l) => typeof l === "string")
+        .map((l) => l.split("=")[0]));
+    for (const [key, value] of Object.entries(ownershipEntries(LABEL_OWNERSHIP_KEYS, ownership))) {
+        if (present.has(key))
+            continue;
+        labels.push({ label: `${key}=${value}`, nodeFilters: ["all"] });
+    }
+    runtime.labels = labels;
+    options.runtime = runtime;
+}
+function clusterDocument(name, cluster, entityNames, context) {
+    const raw = (isResourceDeclarable(cluster) ? cluster.props : {});
+    const props = (walkValue(raw, entityNames, visitor) ?? {});
+    const doc = {};
+    doc.apiVersion = props.apiVersion ?? API_VERSION;
+    doc.kind = props.kind ?? KIND;
+    // metadata.name defaults from the entity's declared name — the schema wants
+    // a hostname there and the export name is the one identity the author has
+    // already chosen. An explicit metadata wins untouched.
+    const metadata = props.metadata;
+    doc.metadata = metadata?.name !== undefined ? metadata : { ...(metadata ?? {}), name: name };
+    for (const key of KEY_ORDER) {
+        if (key === "apiVersion" || key === "kind" || key === "metadata" || key === "options")
+            continue;
+        if (props[key] !== undefined)
+            doc[key] = props[key];
+    }
+    const options = { ...(props.options ?? {}) };
+    if (options.kubeconfig === undefined) {
+        // chant's deliberate inversion of upstream's true/true — see module doc.
+        options.kubeconfig = { updateDefaultKubeconfig: false, switchCurrentContext: false };
+    }
+    if (context?.ownership)
+        stampOwnership(options, context.ownership);
+    doc.options = options;
+    // Anything declared outside the known order still emits — the schema is
+    // additionalProperties: false, so this only ever carries what a future
+    // schema version adds before KEY_ORDER learns about it.
+    for (const [key, value] of Object.entries(props)) {
+        if (KEY_ORDER.includes(key) || value === undefined)
+            continue;
+        doc[key] = value;
+    }
+    return doc;
+}
+function emitDocument(doc) {
+    const sections = [];
+    for (const [key, value] of Object.entries(doc)) {
+        if (value === undefined)
+            continue;
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            sections.push(`${key}: ${scalar(value)}`);
+        }
+        else {
+            sections.push(emitYAMLEntry(key, value));
+        }
+    }
+    return sections.join("\n") + "\n";
+}
+function scalar(value) {
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number")
+        return String(value);
+    if (/[:#\[\]{}|>&*!%@`'"]|^[\s\d]|\s$|^$|^(true|false|null|yes|no|on|off)$/i.test(value)) {
+        return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    }
+    return value;
+}
+export const k3dSerializer = {
+    name: "k3d",
+    rulePrefix: "K3D",
+    serialize(entities, _outputs, context) {
+        const entityNames = new Map();
+        for (const [name, entity] of entities)
+            entityNames.set(entity, name);
+        const clusters = [...entities].filter(([, e]) => e.entityType === CLUSTER_TYPE);
+        let primary = "";
+        const files = {};
+        clusters.forEach(([name, cluster], i) => {
+            const content = emitDocument(clusterDocument(name, cluster, entityNames, context));
+            if (i === 0)
+                primary = content;
+            else
+                files[`${name}.k3d.yaml`] = content;
+        });
+        return Object.keys(files).length > 0 ? { primary, files } : primary;
+    },
+};

package/dist/spec/fetch.js

@@ -0,0 +1,56 @@
+/**
+ * k3d SimpleConfig schema fetching — downloads the JSON Schema and
+ * caches it locally.
+ */
+import { join } from "path";
+import { homedir } from "os";
+import { fetchWithCache, clearCacheFile } from "@intentius/chant/codegen/fetch";
+/**
+ * Pinned upstream k3d release.
+ *
+ * The schema is fetched from the tagged source tree, not a moving branch:
+ * https://raw.githubusercontent.com/k3d-io/k3d/v5.9.0/pkg/config/v1alpha5/schema.json
+ *
+ * v1alpha5 is the config apiVersion this lexicon models. Older config
+ * versions (v1alpha2..v1alpha4) each ship their own migrate.go upstream —
+ * k3d migrates old configs itself, so modelling superseded versions here
+ * would duplicate upstream's job. Bump this constant (and re-generate)
+ * when adopting a newer k3d release.
+ */
+export const K3D_VERSION = "v5.9.0";
+const SCHEMA_URL = `https://raw.githubusercontent.com/k3d-io/k3d/${K3D_VERSION}/pkg/config/v1alpha5/schema.json`;
+/**
+ * Get the cache file path for the k3d schema.
+ */
+export function getCachePath() {
+    return join(homedir(), ".chant", `k3d-schema-${K3D_VERSION}.json`);
+}
+/**
+ * Fetch the k3d SimpleConfig JSON Schema.
+ * Uses local file caching with 24-hour TTL.
+ */
+export async function fetchConfigSchema(force) {
+    return fetchWithCache({
+        url: SCHEMA_URL,
+        cacheFile: getCachePath(),
+    }, force);
+}
+/**
+ * Fetch the config schema as a Map<typeName, Buffer> compatible with the
+ * generatePipeline fetchSchemas callback.
+ *
+ * Single document keyed by "K3d::Cluster" — the parse step splits it into
+ * multiple entities.
+ */
+export async function fetchSchemas(force) {
+    const data = await fetchConfigSchema(force);
+    const schemas = new Map();
+    schemas.set("K3d::Cluster", data);
+    return schemas;
+}
+/**
+ * Clear the cached schema file.
+ */
+export function clearCache() {
+    clearCacheFile(getCachePath());
+}

package/dist/testdata/load-fixtures.js

@@ -0,0 +1,24 @@
+/**
+ * Test fixture loader for the k3d lexicon.
+ *
+ * The fixture is a verbatim copy of the pinned upstream schema
+ * (see src/spec/fetch.ts for the pin), committed so codegen tests
+ * run offline.
+ */
+import { readFileSync } from "fs";
+import { join } from "path";
+/**
+ * Load the pinned SimpleConfig schema fixture for offline testing.
+ */
+export function loadSchemaFixture() {
+    const fixturePath = join(import.meta.dirname, "k3d-schema-fixture.json");
+    return Buffer.from(readFileSync(fixturePath));
+}
+/**
+ * Load the schema fixture as a Map compatible with generatePipeline.
+ */
+export function loadSchemaFixtureMap() {
+    const schemas = new Map();
+    schemas.set("K3d::Cluster", loadSchemaFixture());
+    return schemas;
+}

package/dist/validate-cli.js

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

package/dist/validate.js

@@ -0,0 +1,22 @@
+/**
+ * Validate generated lexicon-k3d artifacts.
+ *
+ * Thin wrapper around the core validation framework
+ * with k3d-specific configuration.
+ */
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts } from "@intentius/chant/codegen/validate";
+// TODO: Add names of required entities for your lexicon
+const REQUIRED_NAMES = [];
+/**
+ * Validate the generated lexicon-k3d artifacts.
+ */
+export async function validate(opts) {
+    const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+    return validateLexiconArtifacts({
+        lexiconJsonFilename: "lexicon-k3d.json",
+        requiredNames: REQUIRED_NAMES,
+        basePath,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k3d",
-  "version": "0.124.31",
+  "version": "0.124.33",
   "type": "module",
   "files": [
     "src/",
@@ -10,22 +10,22 @@
     ".": {
       "development": "./src/index.ts",
       "types": "./dist/index.d.ts",
-      "default": "./src/index.ts"
+      "default": "./dist/index.js"
     },
     "./*": {
       "development": "./src/*.ts",
       "types": "./dist/*.d.ts",
-      "default": "./src/*.ts"
+      "default": "./dist/*.js"
     },
     "./op/activities": {
       "development": "./src/op/activities/index.ts",
       "types": "./dist/op/activities/index.d.ts",
-      "default": "./src/op/activities/index.ts"
+      "default": "./dist/op/activities/index.js"
     },
     "./lint/post-synth": {
       "development": "./src/lint/post-synth/index.ts",
       "types": "./dist/lint/post-synth/index.d.ts",
-      "default": "./src/lint/post-synth/index.ts"
+      "default": "./dist/lint/post-synth/index.js"
     },
     "./manifest": "./dist/manifest.json",
     "./meta": "./dist/meta.json",
@@ -35,7 +35,7 @@
     "generate": "npx tsx src/codegen/generate-cli.ts",
     "validate": "npx tsx src/validate-cli.ts",
     "docs": "npx tsx src/codegen/docs-cli.ts",
-    "build": "../../scripts/tsc7.sh -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete",
+    "build": "../../scripts/tsc7.sh -p tsconfig.build.json --sourceMap false && tsc-alias -p tsconfig.build.json",
     "prepack": "npm run generate && npm run bundle && npm run validate && npm run build",
     "bundle": "tsx src/package-cli.ts"
   },
@@ -52,7 +52,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.31"
+    "@intentius/chant": "^0.124.33"
   },
   "description": "k3d lexicon for chant — a local Kubernetes cluster as declarable data",
   "license": "Apache-2.0",

package/src/codegen/package.ts

@@ -2,13 +2,13 @@ import { packagePipeline } from "@intentius/chant/codegen/package";
 import type { PackagePipelineConfig } from "@intentius/chant/codegen/package";
 import { generate } from "./generate";
 import { dirname } from "path";
-import { fileURLToPath } from "url";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 
 /**
  * Package the k3d lexicon for distribution.
  */
 export async function packageLexicon(options?: { verbose?: boolean; force?: boolean }) {
-  const srcDir = dirname(fileURLToPath(import.meta.url));
+  const srcDir = moduleSourceDir(import.meta.url);
 
   const { spec, stats } = await packagePipeline({
     generate: (opts) => generate({ verbose: opts?.verbose, force: opts?.force }),

package/src/lsp/completions.ts

@@ -1,7 +1,8 @@
 import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 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);
+const require = createRequire(moduleSourceUrl(import.meta.url));
 
 let cachedIndex: LexiconIndex | null = null;
 

package/src/lsp/hover.ts

@@ -1,7 +1,8 @@
 import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 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);
+const require = createRequire(moduleSourceUrl(import.meta.url));
 
 let cachedIndex: LexiconIndex | null = null;