@intentius/chant-lexicon-k3d 0.0.1

package/src/codegen/parse.ts

@@ -0,0 +1,359 @@
+/**
+ * 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 type { PropertyConstraints } from "@intentius/chant/codegen/json-schema";
+import {
+  extractConstraints as coreExtractConstraints,
+  constraintsIsEmpty as coreConstraintsIsEmpty,
+  primaryType,
+  type JsonSchemaProperty,
+} from "@intentius/chant/codegen/json-schema";
+
+// ── Types ──────────────────────────────────────────────────────────
+
+export type { PropertyConstraints };
+export { coreConstraintsIsEmpty as constraintsIsEmpty };
+
+export interface ParsedProperty {
+  name: string;
+  tsType: string;
+  required: boolean;
+  description?: string;
+  enum?: string[];
+  constraints: PropertyConstraints;
+}
+
+export interface ParsedPropertyType {
+  name: string;
+  defType: string;
+  properties: ParsedProperty[];
+}
+
+export interface ParsedEnum {
+  name: string;
+  values: string[];
+}
+
+export interface ParsedResource {
+  typeName: string;
+  description?: string;
+  properties: ParsedProperty[];
+  attributes: Array<{ name: string; tsType: string }>;
+  deprecatedProperties: string[];
+}
+
+export interface K3dParseResult {
+  resource: ParsedResource;
+  propertyTypes: ParsedPropertyType[];
+  enums: ParsedEnum[];
+  isProperty?: boolean;
+}
+
+// ── Schema types ──────────────────────────────────────────────────
+
+interface SchemaDefinition {
+  type?: string | string[];
+  description?: string;
+  // A property value can be a bare boolean ("additionalProperties": false
+  // misplaced inside a properties block — see parseProperties).
+  properties?: Record<string, SchemaProperty | boolean>;
+  required?: string[];
+  enum?: string[];
+  $ref?: string;
+  items?: SchemaProperty;
+  examples?: unknown[];
+  const?: unknown;
+  default?: unknown;
+  additionalProperties?: boolean | SchemaProperty;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  format?: string;
+}
+
+interface SchemaProperty extends SchemaDefinition {}
+
+interface ConfigSchema {
+  title?: string;
+  definitions?: Record<string, SchemaDefinition>;
+  properties?: Record<string, SchemaProperty | boolean>;
+  required?: string[];
+  [key: string]: unknown;
+}
+
+// ── Entity extraction mapping ──────────────────────────────────────
+
+const RESOURCE_ENTITIES: Array<{
+  typeName: string;
+  source: string;
+  description?: string;
+}> = [
+  {
+    typeName: "K3d::Cluster",
+    source: "root",
+    description: "A k3d cluster (SimpleConfig, apiVersion k3d.io/v1alpha5)",
+  },
+];
+
+const PROPERTY_ENTITIES: Array<{
+  typeName: string;
+  source: string;
+  description?: string;
+}> = [
+  { 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: string | Buffer): K3dParseResult[] {
+  const schema: ConfigSchema = JSON.parse(typeof data === "string" ? data : data.toString("utf-8"));
+  const results: K3dParseResult[] = [];
+
+  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: ConfigSchema,
+  entity: { typeName: string; source: string; description?: string },
+): K3dParseResult | null {
+  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: ConfigSchema, source: string): SchemaDefinition | null {
+  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: SchemaDefinition | null = { properties: schema.properties };
+  for (const seg of path.split(".")) {
+    const next: SchemaProperty | boolean | undefined = 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: string, schema: ConfigSchema): SchemaDefinition | null {
+  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: Record<string, SchemaProperty | boolean>,
+  requiredSet: Set<string>,
+  schema: ConfigSchema,
+): ParsedProperty[] {
+  const result: ParsedProperty[] = [];
+  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 as JsonSchemaProperty),
+    });
+  }
+  return result;
+}
+
+function resolvePropertyType(prop: SchemaProperty, schema: ConfigSchema): string {
+  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: Record<string, Record<string, string>> = {
+  "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: string): string {
+  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: string): string {
+  return "K3d";
+}

package/src/describe-resources.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from "vitest";
+import { describeObservationConformance } from "@intentius/chant-test-utils";
+import { normalizeObservation } from "@intentius/chant/observation";
+import { describeResources, declaredClusterName, type ExecFn } from "./describe-resources";
+import { k3dPlugin } from "./plugin";
+
+const LIST_CMD = "k3d cluster list -o json";
+
+function fakeExec(handlers: Record<string, string | Error>): ExecFn {
+  return async (command: string) => {
+    for (const [prefix, result] of Object.entries(handlers)) {
+      if (command.startsWith(prefix)) {
+        if (result instanceof Error) throw result;
+        return { stdout: result };
+      }
+    }
+    throw new Error(`unexpected command: ${command}`);
+  };
+}
+
+const RUNNING_CLUSTER = JSON.stringify([
+  {
+    name: "probe",
+    serversCount: 1,
+    serversRunning: 1,
+    agentsCount: 0,
+    agentsRunning: 0,
+    nodes: [{ name: "k3d-probe-server-0", role: "server", State: { Running: true } }],
+  },
+]);
+
+const OWNED_LABELS = JSON.stringify({
+  "app.kubernetes.io/managed-by": "chant",
+  "chant.intentius.io/stack": "probe",
+  "chant.intentius.io/env": "local",
+});
+
+function options(names: string[] = ["probe"]) {
+  return {
+    environment: "local",
+    buildOutput: "",
+    entityNames: names,
+    entities: new Map(names.map((n) => [n, { entityType: "K3d::Cluster", props: {} }])),
+  };
+}
+
+describe("k3d describeResources", () => {
+  it("reports a running, chant-labelled cluster as present and owned", async () => {
+    const result = await describeResources(
+      options(),
+      fakeExec({ [LIST_CMD]: RUNNING_CLUSTER, "docker inspect": OWNED_LABELS }),
+    );
+    const { resources } = normalizeObservation(result);
+    expect(resources.probe.status).toBe("running");
+    expect(resources.probe.ownership).toBe("owned");
+    expect(resources.probe.physicalId).toBe("probe");
+  });
+
+  it("reports a cluster without the marker as foreign", async () => {
+    const result = await describeResources(
+      options(),
+      fakeExec({ [LIST_CMD]: RUNNING_CLUSTER, "docker inspect": JSON.stringify({ "k3d.cluster": "probe" }) }),
+    );
+    const { resources } = normalizeObservation(result);
+    expect(resources.probe.ownership).toBe("foreign");
+  });
+
+  it("reports a missing cluster as absent — in neither map", async () => {
+    const result = await describeResources(options(), fakeExec({ [LIST_CMD]: "[]", "docker inspect": "{}" }));
+    const { resources, unobserved } = normalizeObservation(result);
+    expect(resources.probe).toBeUndefined();
+    expect(unobserved.probe).toBeUndefined();
+  });
+
+  it("reports read-failed for everything when the list command fails — never absence", async () => {
+    const result = await describeResources(
+      options(["probe", "second"]),
+      fakeExec({ [LIST_CMD]: new Error("Cannot connect to the Docker daemon") }),
+    );
+    const { resources, unobserved } = normalizeObservation(result);
+    expect(Object.keys(resources)).toHaveLength(0);
+    expect(unobserved.probe.reason).toBe("read-failed");
+    expect(unobserved.second.reason).toBe("read-failed");
+    expect(unobserved.probe.detail).toContain("Docker");
+  });
+
+  it("stays present with ownership unknown when only docker inspect fails", async () => {
+    const result = await describeResources(
+      options(),
+      fakeExec({ [LIST_CMD]: RUNNING_CLUSTER, "docker inspect": new Error("no such container") }),
+    );
+    const { resources } = normalizeObservation(result);
+    expect(resources.probe.status).toBe("running");
+    expect(resources.probe.ownership).toBe("unknown");
+  });
+
+  it("reports a stopped cluster's status", async () => {
+    const stopped = JSON.stringify([
+      { name: "probe", serversCount: 1, serversRunning: 0, agentsCount: 0, agentsRunning: 0 },
+    ]);
+    const result = await describeResources(
+      options(),
+      fakeExec({ [LIST_CMD]: stopped, "docker inspect": OWNED_LABELS }),
+    );
+    const { resources } = normalizeObservation(result);
+    expect(resources.probe.status).toBe("stopped");
+  });
+
+  it("resolves the cluster name from metadata.name over the entity name", () => {
+    expect(
+      declaredClusterName({ name: "entity", type: "K3d::Cluster", props: { metadata: { name: "real" } } }),
+    ).toBe("real");
+    expect(declaredClusterName({ name: "entity", type: "K3d::Cluster", props: {} })).toBe("entity");
+  });
+});
+
+describeObservationConformance({
+  lexicon: "k3d",
+  ownershipChannel: k3dPlugin.ownershipChannel,
+  scenarios: [
+    {
+      name: "running owned cluster",
+      declared: ["probe"],
+      owned: true,
+      expectPresent: ["probe"],
+      run: () =>
+        describeResources(options(), fakeExec({ [LIST_CMD]: RUNNING_CLUSTER, "docker inspect": OWNED_LABELS })),
+    },
+    {
+      name: "docker down",
+      declared: ["probe"],
+      expectUnobserved: ["probe"],
+      run: () => describeResources(options(), fakeExec({ [LIST_CMD]: new Error("docker: not running") })),
+    },
+    {
+      name: "cluster absent",
+      declared: ["probe"],
+      expectAbsent: ["probe"],
+      run: () => describeResources(options(), fakeExec({ [LIST_CMD]: "[]" })),
+    },
+  ],
+});

package/src/describe-resources.ts

@@ -0,0 +1,144 @@
+/**
+ * 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 type { DescribeResourcesResult } from "@intentius/chant/lexicon";
+import {
+  observeEntities,
+  type DeclaredEntity,
+  type EntityObservation,
+  type ObserverAdapter,
+} from "@intentius/chant/observation";
+import { classifyOwnership, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+
+const execAsync = promisify(exec);
+
+const CLUSTER_TYPE = "K3d::Cluster";
+
+/** The two commands the observer runs, injectable for tests. */
+export type ExecFn = (command: string) => Promise<{ stdout: string }>;
+
+interface K3dNode {
+  name?: string;
+  role?: string;
+  State?: { Running?: boolean; Status?: string };
+}
+
+interface K3dClusterListEntry {
+  name?: string;
+  nodes?: K3dNode[];
+  serversCount?: number;
+  serversRunning?: number;
+  agentsCount?: number;
+  agentsRunning?: number;
+}
+
+/** The cluster name a declaration resolves to: metadata.name, else the entity name. */
+export function declaredClusterName(entity: DeclaredEntity): string {
+  const metadata = entity.props.metadata as Record<string, unknown> | undefined;
+  const name = metadata?.name;
+  return typeof name === "string" && name.length > 0 ? name : entity.name;
+}
+
+function clusterStatus(cluster: K3dClusterListEntry): string {
+  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: ExecFn): ObserverAdapter<K3dClusterListEntry[]> {
+  return {
+    async bind() {
+      const { stdout } = await execFn("k3d cluster list -o json");
+      const parsed = JSON.parse(stdout || "[]");
+      return Array.isArray(parsed) ? (parsed as K3dClusterListEntry[]) : [];
+    },
+
+    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): Promise<EntityObservation> {
+      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: "owned" | "foreign" | "unknown" = "unknown";
+      try {
+        const { stdout } = await execFn(
+          `docker inspect k3d-${name}-server-0 --format '{{json .Config.Labels}}'`,
+        );
+        const labels = JSON.parse(stdout.trim().replace(/^'|'$/g, "") || "{}") as Record<string, unknown>;
+        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: {
+    entityNames: string[];
+    entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  },
+  execFn: ExecFn = execAsync,
+): Promise<DescribeResourcesResult> {
+  const declared: DeclaredEntity[] = options.entityNames.map((name) => {
+    const entity = options.entities.get(name);
+    return {
+      name,
+      type: entity?.entityType ?? "",
+      props: entity?.props ?? {},
+    };
+  });
+
+  return observeEntities(declared, adapter(execFn));
+}