@intentius/chant-lexicon-k3d 0.124.31 → 0.124.33

package/dist/codegen/docs-cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs.js";
+await generateDocs({ verbose: true });

package/dist/codegen/docs.js

@@ -0,0 +1,99 @@
+/**
+ * Documentation generation for the k3d lexicon.
+ *
+ * Generates Starlight MDX pages for k3d entities using the core docs pipeline.
+ * The overview prose lives here; authored pages live under docs/pages/.
+ */
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+function serviceFromType(resourceType) {
+    const parts = resourceType.split("::");
+    return parts.length >= 2 ? parts[1] : "K3d";
+}
+const overview = `The k3d lexicon types [k3d](https://k3d.io)'s own declarative config —
+\`k3d.io/v1alpha5\` SimpleConfig, generated from upstream's published JSON
+Schema, pinned at **k3d v5.9.0**. \`chant build\` emits a YAML file that
+\`k3d cluster create --config\` consumes verbatim, so the walk-away cost is
+zero: the artifact is a file the native tool accepts with chant nowhere in
+sight.
+
+\`\`\`ts
+import { Cluster, K3dOptions, Options } from "@intentius/chant-lexicon-k3d";
+
+export const devCluster = new Cluster({
+  metadata: { name: "chant-dev" },
+  servers: 1,
+  agents: 0,
+  options: new Options({
+    k3d: new K3dOptions({ disableLoadbalancer: true }),
+  }),
+});
+\`\`\`
+
+## The kubeconfig default is chant's, not upstream's
+
+k3d's own defaults rewrite \`~/.kube/config\` and switch your active context
+on every cluster create. When a declaration says nothing about
+\`options.kubeconfig\`, the emitted config pins both off:
+
+\`\`\`yaml
+options:
+  kubeconfig:
+    updateDefaultKubeconfig: false
+    switchCurrentContext: false
+\`\`\`
+
+This is deliberate: a tool that reconciles infrastructure must not repoint
+your shell as a side effect — an unrelated \`k3d cluster create\` switching
+the ambient context mid-run produces convincingly false failures. Declare
+\`options.kubeconfig\` yourself to opt back into upstream behaviour; what you
+write is emitted exactly as written. The \`k3dUp\` activity reports the
+context name and kubeconfig path it produced either way, so whatever
+applies manifests afterwards knows what to talk to.
+
+## Lifecycle is an Op activity pair
+
+Cluster creation is procedural, not desired-state — nobody expects
+\`chant lifecycle diff\` to reconcile a laptop. \`k3dUp\` / \`k3dDown\` shell out
+to k3d with the emitted config and are idempotent; add \`"k3d"\` to your
+project's \`lexicons\` so \`loadActivities\` finds them.
+
+## Ownership and observation
+
+With ownership configured, the serializer stamps chant's marker as Docker
+labels on every node via \`options.runtime.labels\`; the labels survive
+\`k3d cluster stop\`/\`start\`. \`chant lifecycle diff --live\` reports each
+declared cluster as present, absent, or not-observed-with-a-reason — Docker
+being down reads as *not observed*, never as *absent*, so a stopped daemon
+cannot masquerade as a missing cluster. There is no property-level drift on
+purpose: the config is an input to creation, not a spec k3d reconciles
+against.
+
+## Checks
+
+- **K3D001** (lint, error) — a literal \`registries.create.proxy.password\`
+  in source. A committed cluster config is a leaked registry credential.
+- **K3D101** (post-synth, error) — a \`nodeFilter\` that matches no node.
+  k3d applies an unmatched filter to nothing and says nothing.
+- **K3D102** (post-synth, error) — a registry proxy password that reached
+  the emitted config, whatever route it took through the source.
+`;
+export async function generateDocs(opts) {
+    const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const config = {
+        name: "k3d",
+        displayName: "K3d",
+        description: "Declare a local k3d cluster as data; the config is the artifact",
+        distDir: join(pkgDir, "dist"),
+        outDir: join(pkgDir, "docs"),
+        basePath: process.env.DOCS_BASE_PATH ?? "/chant/lexicons/k3d/",
+        overview,
+        serviceFromType,
+    };
+    const result = docsPipeline(config);
+    writeDocsSite(config, result);
+    if (opts?.verbose) {
+        console.error(`Generated ${result.pages.size} documentation pages`);
+    }
+}

package/dist/codegen/generate-cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for k3d lexicon generation.
+ */
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { generate, writeGeneratedFiles } from "./generate.js";
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+async function main() {
+    const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+    const force = process.argv.includes("--force") || process.argv.includes("-f");
+    console.error("Generating k3d lexicon...");
+    const result = await generate({ verbose, force });
+    writeGeneratedFiles(result, pkgDir);
+    console.error(`Generated ${result.resources} entities, ${result.properties} property types, ${result.enums} enums`);
+    if (result.warnings.length > 0) {
+        console.error(`${result.warnings.length} warnings:`);
+        for (const w of result.warnings) {
+            console.error(`  ${w.file}: ${w.error}`);
+        }
+    }
+}
+main().catch((err) => {
+    console.error("Generation failed:", err);
+    process.exit(1);
+});

package/dist/codegen/generate-lexicon.js

@@ -0,0 +1,36 @@
+/**
+ * Lexicon JSON generator — produces lexicon-k3d.json with metadata
+ * for all k3d entities.
+ */
+import { k3dShortName } from "./parse.js";
+import { buildRegistry, serializeRegistry, } from "@intentius/chant/codegen/generate-registry";
+/**
+ * Generate the lexicon-k3d.json content.
+ */
+export function generateLexiconJSON(results, naming) {
+    const registryResources = results.map((r) => ({
+        typeName: r.resource.typeName,
+        attributes: r.resource.attributes,
+        properties: r.resource.properties,
+        propertyTypes: r.propertyTypes.map((pt) => ({ name: pt.name, specType: pt.defType })),
+    }));
+    const entries = buildRegistry(registryResources, naming, {
+        shortName: k3dShortName,
+        buildEntry: (resource, _tsName, _attrs, propConstraints) => {
+            const r = results.find((res) => res.resource.typeName === resource.typeName);
+            return {
+                resourceType: resource.typeName,
+                kind: (r?.isProperty ? "property" : "resource"),
+                lexicon: "k3d",
+                ...(r?.resource.deprecatedProperties?.length && { deprecatedProperties: r.resource.deprecatedProperties }),
+                ...(propConstraints && Object.keys(propConstraints).length > 0 && { constraints: propConstraints }),
+            };
+        },
+        buildPropertyEntry: (resourceType, propertyType) => ({
+            resourceType: `${resourceType}.${propertyType}`,
+            kind: "property",
+            lexicon: "k3d",
+        }),
+    });
+    return serializeRegistry(entries);
+}

package/dist/codegen/generate-typescript.js

@@ -0,0 +1,67 @@
+/**
+ * TypeScript declaration file generator — produces index.d.ts with all
+ * k3d entity classes.
+ */
+import { k3dShortName } from "./parse.js";
+import { propertyTypeName, extractDefName } from "./naming.js";
+import { writeResourceClass, writeEnumType, } from "@intentius/chant/codegen/generate-typescript";
+/**
+ * Generate the complete .d.ts file content.
+ */
+export function generateTypeScriptDeclarations(results, naming) {
+    const lines = [];
+    lines.push("// Code generated by chant k3d generate. DO NOT EDIT.");
+    const resources = [];
+    const enums = [];
+    for (const r of results) {
+        const typeName = r.resource.typeName;
+        const tsName = naming.resolve(typeName);
+        if (!tsName)
+            continue;
+        const shortName = k3dShortName(typeName);
+        const remap = new Map();
+        for (const pt of r.propertyTypes) {
+            const defName = extractDefName(pt.name, shortName);
+            remap.set(pt.name, propertyTypeName(tsName, defName));
+        }
+        for (const e of r.enums) {
+            const defName = extractDefName(e.name, shortName);
+            remap.set(e.name, propertyTypeName(tsName, defName));
+        }
+        const dtsProps = r.resource.properties.map((p) => ({
+            name: p.name,
+            type: p.tsType,
+            required: p.required,
+            description: p.description,
+        }));
+        const dtsAttrs = r.resource.attributes.map((a) => ({
+            name: a.name,
+            type: a.tsType,
+        }));
+        resources.push({ tsName, properties: dtsProps, attributes: dtsAttrs, remap });
+        for (const alias of naming.aliases(typeName)) {
+            resources.push({ tsName: alias, properties: dtsProps, attributes: dtsAttrs, remap });
+        }
+        for (const e of r.enums) {
+            const defName = extractDefName(e.name, shortName);
+            const eName = propertyTypeName(tsName, defName);
+            enums.push({ tsName: eName, values: e.values });
+        }
+    }
+    resources.sort((a, b) => a.tsName.localeCompare(b.tsName));
+    enums.sort((a, b) => a.tsName.localeCompare(b.tsName));
+    lines.push("");
+    lines.push("// --- k3d Entity classes ---");
+    for (const re of resources) {
+        writeResourceClass(lines, re.tsName, re.properties, re.attributes, re.remap);
+    }
+    if (enums.length > 0) {
+        lines.push("");
+        lines.push("// --- Enum types ---");
+        for (const ee of enums) {
+            writeEnumType(lines, ee.tsName, ee.values);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/codegen/generate.js

@@ -0,0 +1,109 @@
+/**
+ * k3d generation pipeline — uses core generatePipeline with k3d-specific
+ * fetch, parse, naming, and generation callbacks.
+ */
+import { generatePipeline, writeGeneratedArtifacts, } from "@intentius/chant/codegen/generate";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { fetchSchemas } from "../spec/fetch.js";
+import { parseConfigSchema, k3dShortName } from "./parse.js";
+import { NamingStrategy, propertyTypeName, extractDefName } from "./naming.js";
+import { generateLexiconJSON } from "./generate-lexicon.js";
+import { generateTypeScriptDeclarations } from "./generate-typescript.js";
+import { generateRuntimeIndex as coreGenerateRuntimeIndex, } from "@intentius/chant/codegen/generate-runtime-index";
+/**
+ * Run the full k3d generation pipeline.
+ */
+export async function generate(opts = {}) {
+    let pendingResults = [];
+    const config = {
+        fetchSchemas: async (fetchOpts) => {
+            return fetchSchemas(fetchOpts.force);
+        },
+        parseSchema: (_typeName, data) => {
+            const results = parseConfigSchema(data);
+            if (results.length === 0)
+                return null;
+            pendingResults = results.slice(1);
+            return results[0];
+        },
+        createNaming: (results) => new NamingStrategy(results),
+        augmentResults: (results, _opts, log) => {
+            if (pendingResults.length > 0) {
+                results.push(...pendingResults);
+                log(`Added ${pendingResults.length} additional entities from single schema`);
+                pendingResults = [];
+            }
+            log(`Total: ${results.length} k3d entity schemas`);
+            return { results };
+        },
+        generateRegistry: (results, naming) => {
+            return generateLexiconJSON(results, naming);
+        },
+        generateTypes: (results, naming) => {
+            return generateTypeScriptDeclarations(results, naming);
+        },
+        generateRuntimeIndex: (results, naming) => {
+            return generateRuntimeIndex(results, naming);
+        },
+    };
+    return generatePipeline(config, opts);
+}
+/**
+ * Write generated artifacts to disk.
+ */
+export function writeGeneratedFiles(result, pkgDir) {
+    const baseDir = pkgDir ?? dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    writeGeneratedArtifacts({
+        baseDir,
+        files: {
+            "lexicon-k3d.json": result.lexiconJSON,
+            "index.d.ts": result.typesDTS,
+            "index.ts": result.indexTS,
+            "runtime.ts": `/**\n * Runtime factory constructors — re-exported from core.\n */\nexport { createResource, createProperty } from "@intentius/chant/runtime";\n`,
+        },
+    });
+}
+/**
+ * Generate the runtime index.ts with factory constructor exports.
+ */
+function generateRuntimeIndex(results, naming) {
+    const resourceEntries = [];
+    const propertyEntries = [];
+    for (const r of results) {
+        const typeName = r.resource.typeName;
+        const tsName = naming.resolve(typeName);
+        if (!tsName)
+            continue;
+        const attrs = {};
+        if (r.isProperty) {
+            propertyEntries.push({ tsName, resourceType: typeName });
+            for (const alias of naming.aliases(typeName)) {
+                propertyEntries.push({ tsName: alias, resourceType: typeName });
+            }
+        }
+        else {
+            resourceEntries.push({ tsName, resourceType: typeName, attrs });
+            for (const alias of naming.aliases(typeName)) {
+                resourceEntries.push({ tsName: alias, resourceType: typeName, attrs });
+            }
+        }
+        const shortName = k3dShortName(typeName);
+        const ptAliases = naming.propertyTypeAliases(typeName);
+        for (const pt of r.propertyTypes) {
+            const defName = extractDefName(pt.name, shortName);
+            const ptName = propertyTypeName(tsName, defName);
+            const ptType = `${typeName}.${pt.defType}`;
+            propertyEntries.push({ tsName: ptName, resourceType: ptType });
+            if (ptAliases) {
+                const aliasName = ptAliases.get(defName);
+                if (aliasName) {
+                    propertyEntries.push({ tsName: aliasName, resourceType: ptType });
+                }
+            }
+        }
+    }
+    return coreGenerateRuntimeIndex(resourceEntries, propertyEntries, {
+        lexiconName: "k3d",
+    });
+}

package/dist/codegen/naming.js

@@ -0,0 +1,48 @@
+/**
+ * k3d naming strategy — flat namespace, one short name per entity.
+ */
+import { NamingStrategy as CoreNamingStrategy, } from "@intentius/chant/codegen/naming";
+import { k3dShortName, k3dServiceName } from "./parse.js";
+export { propertyTypeName, extractDefName } from "@intentius/chant/codegen/naming";
+const k3dNamingConfig = {
+    priorityNames: {
+        "K3d::Cluster": "Cluster",
+        "K3d::Metadata": "Metadata",
+        "K3d::KubeAPI": "KubeAPI",
+        "K3d::Volume": "Volume",
+        "K3d::Port": "Port",
+        "K3d::File": "File",
+        "K3d::EnvVar": "EnvVar",
+        "K3d::HostAlias": "HostAlias",
+        "K3d::Registries": "Registries",
+        "K3d::RegistryCreate": "RegistryCreate",
+        "K3d::RegistryProxy": "RegistryProxy",
+        "K3d::Options": "Options",
+        "K3d::K3dOptions": "K3dOptions",
+        "K3d::LoadbalancerOptions": "LoadbalancerOptions",
+        "K3d::K3sOptions": "K3sOptions",
+        "K3d::K3sExtraArg": "K3sExtraArg",
+        "K3d::NodeLabel": "NodeLabel",
+        "K3d::KubeconfigOptions": "KubeconfigOptions",
+        "K3d::RuntimeOptions": "RuntimeOptions",
+        "K3d::RuntimeLabel": "RuntimeLabel",
+        "K3d::Ulimit": "Ulimit",
+    },
+    priorityAliases: {},
+    priorityPropertyAliases: {},
+    serviceAbbreviations: {},
+    shortName: k3dShortName,
+    serviceName: k3dServiceName,
+};
+/**
+ * k3d naming strategy.
+ */
+export class NamingStrategy extends CoreNamingStrategy {
+    constructor(results) {
+        const inputs = results.map((r) => ({
+            typeName: r.resource.typeName,
+            propertyTypes: r.propertyTypes,
+        }));
+        super(inputs, k3dNamingConfig);
+    }
+}

package/dist/codegen/package.js

@@ -0,0 +1,22 @@
+import { packagePipeline } from "@intentius/chant/codegen/package";
+import { generate } from "./generate.js";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+/**
+ * Package the k3d lexicon for distribution.
+ */
+export async function packageLexicon(options) {
+    const srcDir = moduleSourceDir(import.meta.url);
+    const { spec, stats } = await packagePipeline({
+        generate: (opts) => generate({ verbose: opts?.verbose, force: opts?.force }),
+        buildManifest: () => ({
+            name: "k3d",
+            version: "0.0.1",
+            chantVersion: ">=0.1.0",
+            namespace: "K3d",
+        }),
+        srcDir,
+        collectSkills: () => new Map(),
+    });
+    console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules`);
+    return { spec, stats };
+}

package/dist/codegen/parse.js

@@ -0,0 +1,244 @@
+/**
+ * k3d SimpleConfig JSON Schema parser.
+ *
+ * Parses the single v1alpha5 schema into multiple entity results — the
+ * Cluster resource plus one property entity per nested config object
+ * (Metadata, Volume, Registries, Options, etc.).
+ */
+import { extractConstraints as coreExtractConstraints, constraintsIsEmpty as coreConstraintsIsEmpty, primaryType, } from "@intentius/chant/codegen/json-schema";
+export { coreConstraintsIsEmpty as constraintsIsEmpty };
+// ── Entity extraction mapping ──────────────────────────────────────
+const RESOURCE_ENTITIES = [
+    {
+        typeName: "K3d::Cluster",
+        source: "root",
+        description: "A k3d cluster (SimpleConfig, apiVersion k3d.io/v1alpha5)",
+    },
+];
+const PROPERTY_ENTITIES = [
+    { typeName: "K3d::Metadata", source: "metadata", description: "Cluster metadata (name)" },
+    { typeName: "K3d::KubeAPI", source: "kubeAPI", description: "Kubernetes API server exposure settings" },
+    { typeName: "K3d::Volume", source: "volumes:item", description: "A volume mount with node filters" },
+    { typeName: "K3d::Port", source: "ports:item", description: "A port mapping with node filters" },
+    { typeName: "K3d::File", source: "files:item", description: "A file to copy into nodes" },
+    { typeName: "K3d::EnvVar", source: "env:item", description: "An environment variable with node filters" },
+    { typeName: "K3d::HostAlias", source: "hostAliases:item", description: "An IP to hostnames mapping" },
+    { typeName: "K3d::Registries", source: "registries", description: "Registry configuration" },
+    { typeName: "K3d::RegistryCreate", source: "registries.create", description: "Create a new container image registry alongside the cluster" },
+    { typeName: "K3d::RegistryProxy", source: "registries.create.proxy", description: "Pull-through proxy settings for a created registry" },
+    { typeName: "K3d::Options", source: "options", description: "Cluster options (k3d, k3s, kubeconfig, runtime)" },
+    { typeName: "K3d::K3dOptions", source: "options.k3d", description: "k3d-specific options" },
+    { typeName: "K3d::LoadbalancerOptions", source: "options.k3d.loadbalancer", description: "Loadbalancer options" },
+    { typeName: "K3d::K3sOptions", source: "options.k3s", description: "k3s-specific options" },
+    { typeName: "K3d::K3sExtraArg", source: "options.k3s.extraArgs:item", description: "An extra k3s server/agent argument with node filters" },
+    { typeName: "K3d::NodeLabel", source: "options.k3s.nodeLabels:item", description: "A Kubernetes node label with node filters" },
+    { typeName: "K3d::KubeconfigOptions", source: "options.kubeconfig", description: "Kubeconfig update behaviour" },
+    { typeName: "K3d::RuntimeOptions", source: "options.runtime", description: "Container runtime options" },
+    { typeName: "K3d::RuntimeLabel", source: "options.runtime.labels:item", description: "A container runtime label with node filters" },
+    { typeName: "K3d::Ulimit", source: "options.runtime.ulimits:item", description: "A ulimit setting for nodes" },
+];
+// ── Parser ─────────────────────────────────────────────────────────
+/**
+ * Parse the k3d SimpleConfig JSON Schema into multiple entity results.
+ */
+export function parseConfigSchema(data) {
+    const schema = JSON.parse(typeof data === "string" ? data : data.toString("utf-8"));
+    const results = [];
+    for (const entity of RESOURCE_ENTITIES) {
+        const result = extractEntity(schema, entity);
+        if (result)
+            results.push(result);
+    }
+    for (const entity of PROPERTY_ENTITIES) {
+        const result = extractEntity(schema, entity);
+        if (result) {
+            result.isProperty = true;
+            results.push(result);
+        }
+    }
+    return results;
+}
+function extractEntity(schema, entity) {
+    const def = resolveSource(schema, entity.source);
+    if (!def?.properties)
+        return null;
+    const properties = parseProperties(def.properties, new Set(def.required ?? []), schema);
+    const overrides = PROPERTY_OVERRIDES[entity.typeName];
+    if (overrides) {
+        for (const prop of properties) {
+            if (overrides[prop.name]) {
+                prop.tsType = overrides[prop.name];
+            }
+        }
+    }
+    return {
+        resource: {
+            typeName: entity.typeName,
+            description: entity.description ?? def.description,
+            properties,
+            attributes: [],
+            deprecatedProperties: [],
+        },
+        propertyTypes: [],
+        enums: [],
+    };
+}
+// ── Source resolution ──────────────────────────────────────────────
+/**
+ * Resolve an extraction source to a schema definition.
+ *
+ * Sources are:
+ * - "root" — the schema document itself (K3d::Cluster)
+ * - a dotted path of property names from the root, e.g. "options.k3d"
+ * - a dotted path ending in ":item" for array item schemas,
+ *   e.g. "volumes:item", "options.k3s.extraArgs:item"
+ */
+function resolveSource(schema, source) {
+    if (source === "root") {
+        return { properties: schema.properties, required: schema.required };
+    }
+    const wantsItem = source.endsWith(":item");
+    const path = wantsItem ? source.slice(0, -":item".length) : source;
+    let current = { properties: schema.properties };
+    for (const seg of path.split(".")) {
+        const next = current?.properties?.[seg];
+        if (!next || typeof next === "boolean")
+            return null;
+        current = next;
+    }
+    if (!current)
+        return null;
+    if (wantsItem) {
+        return current.items ?? null;
+    }
+    return current;
+}
+function resolveRef(ref, schema) {
+    const prefix = "#/definitions/";
+    if (!ref.startsWith(prefix))
+        return null;
+    const defName = ref.slice(prefix.length);
+    return schema.definitions?.[defName] ?? null;
+}
+// ── Property parsing ──────────────────────────────────────────────
+function parseProperties(properties, requiredSet, schema) {
+    const result = [];
+    for (const [name, prop] of Object.entries(properties)) {
+        // Upstream schema bug (present in v5.9.0): inside `registries.properties`
+        // the key `"additionalProperties": false` is nested INSIDE the properties
+        // block instead of sitting beside it, so a naive walk would emit a config
+        // property literally named "additionalProperties" whose schema is the
+        // bare boolean `false`. Drop it — it is a misplaced schema keyword, not a
+        // property. Keep this guard on regeneration until upstream fixes the
+        // schema, or the bogus property comes back.
+        if (name === "additionalProperties" && typeof prop === "boolean")
+            continue;
+        if (typeof prop === "boolean")
+            continue;
+        const tsType = resolvePropertyType(prop, schema);
+        result.push({
+            name,
+            tsType,
+            required: requiredSet.has(name),
+            description: prop.description,
+            enum: prop.enum,
+            constraints: coreExtractConstraints(prop),
+        });
+    }
+    return result;
+}
+function resolvePropertyType(prop, schema) {
+    if (!prop)
+        return "any";
+    if (prop.$ref) {
+        const def = resolveRef(prop.$ref, schema);
+        // The only definition in the v1alpha5 schema is nodeFilters
+        // (array of strings); resolve through it structurally.
+        if (def)
+            return resolvePropertyType(def, schema);
+        return "any";
+    }
+    if (prop.enum && prop.enum.length > 0) {
+        return prop.enum.map((v) => JSON.stringify(v)).join(" | ");
+    }
+    const pt = primaryType(prop.type);
+    switch (pt) {
+        case "string": return "string";
+        case "integer":
+        case "number": return "number";
+        case "boolean": return "boolean";
+        case "array":
+            if (prop.items) {
+                const itemType = resolvePropertyType(prop.items, schema);
+                if (itemType.includes(" | "))
+                    return `(${itemType})[]`;
+                return `${itemType}[]`;
+            }
+            return "any[]";
+        case "object": return "Record<string, any>";
+        default:
+            // Upstream schema quirk (v5.9.0): `options.k3d.timeout` declares
+            // `examples` ("60s", "1m", "1m30s") but no `type` at all. It is a Go
+            // time.Duration string upstream, so when a type-less schema carries
+            // string examples we treat it as a string (duration) rather than `any`.
+            if (Array.isArray(prop.examples) && prop.examples.length > 0 && prop.examples.every((e) => typeof e === "string")) {
+                return "string";
+            }
+            return "any";
+    }
+}
+// ── Property overrides ────────────────────────────────────────────
+/**
+ * Cross-reference nested objects to their extracted property entity
+ * classes so authors get typed constructors instead of Record<string, any>.
+ */
+const PROPERTY_OVERRIDES = {
+    "K3d::Cluster": {
+        metadata: "Metadata",
+        kubeAPI: "KubeAPI",
+        volumes: "Volume[]",
+        ports: "Port[]",
+        files: "File[]",
+        env: "EnvVar[]",
+        hostAliases: "HostAlias[]",
+        registries: "Registries",
+        options: "Options",
+    },
+    "K3d::Registries": {
+        create: "RegistryCreate",
+    },
+    "K3d::RegistryCreate": {
+        proxy: "RegistryProxy",
+    },
+    "K3d::Options": {
+        k3d: "K3dOptions",
+        k3s: "K3sOptions",
+        kubeconfig: "KubeconfigOptions",
+        runtime: "RuntimeOptions",
+    },
+    "K3d::K3dOptions": {
+        loadbalancer: "LoadbalancerOptions",
+    },
+    "K3d::K3sOptions": {
+        extraArgs: "K3sExtraArg[]",
+        nodeLabels: "NodeLabel[]",
+    },
+    "K3d::RuntimeOptions": {
+        labels: "RuntimeLabel[]",
+        ulimits: "Ulimit[]",
+    },
+};
+// ── Helpers ───────────────────────────────────────────────────────
+/**
+ * Extract short name: "K3d::Cluster" → "Cluster"
+ */
+export function k3dShortName(typeName) {
+    const parts = typeName.split("::");
+    return parts[parts.length - 1];
+}
+/**
+ * Extract service name: always "K3d" — the lexicon is a single flat service.
+ */
+export function k3dServiceName(_typeName) {
+    return "K3d";
+}