@intentius/chant-lexicon-k3d 0.44.13 → 0.45.0

package/dist/codegen/docs-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+export {};
+//# sourceMappingURL=docs-cli.d.ts.map

package/dist/codegen/docs-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-cli.d.ts","sourceRoot":"","sources":["../../src/codegen/docs-cli.ts"],"names":[],"mappings":""}

package/dist/codegen/docs.d.ts

@@ -1,7 +1,10 @@
 /**
- * Generate documentation site for the k3d lexicon.
+ * 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/.
  */
-export declare function generateDocs(options?: {
+export declare function generateDocs(opts?: {
     verbose?: boolean;
 }): Promise<void>;
 //# sourceMappingURL=docs.d.ts.map

package/dist/codegen/docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAsB,YAAY,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBjF"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgFH,wBAAsB,YAAY,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB9E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k3d",
-  "version": "0.44.13",
+  "version": "0.45.0",
   "type": "module",
   "files": [
     "src/",
@@ -52,7 +52,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.44.13",
+    "@intentius/chant": "^0.45.0",
     "typescript": "^5.9.3"
   },
   "description": "k3d lexicon for chant — a local Kubernetes cluster as declarable data",

package/src/codegen/docs-cli.ts

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

package/src/codegen/docs.ts

@@ -1,25 +1,106 @@
-import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
-
 /**
- * Generate documentation site for the k3d lexicon.
+ * 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/.
  */
-export async function generateDocs(options?: { verbose?: boolean }): Promise<void> {
-  const config = {
+
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite, type DocsConfig } from "@intentius/chant/codegen/docs";
+
+function serviceFromType(resourceType: string): string {
+  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?: { verbose?: boolean }): Promise<void> {
+  const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+
+  const config: DocsConfig = {
     name: "k3d",
     displayName: "K3d",
-    description: "k3d lexicon documentation",
-    distDir: "./dist",
-    outDir: "./docs",
-    // TODO: Implement service grouping for your provider
-    serviceFromType: (type: string) => type.split("::")[1] ?? type,
-    // TODO: Implement resource documentation URLs
-    resourceTypeUrl: (type: string) => `#${type}`,
+    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 (options?.verbose) {
-    console.error("Documentation generated");
+  if (opts?.verbose) {
+    console.error(`Generated ${result.pages.size} documentation pages`);
   }
 }