@intentius/chant-lexicon-k8s 0.30.0 → 0.32.0

package/src/plugin.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "vitest";
+import { describe, test, expect, vi } from "vitest";
 import { existsSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
@@ -211,4 +211,61 @@ describe("k8sPlugin", () => {
   test("package() method exists", () => {
     expect(typeof k8sPlugin.package).toBe("function");
   });
+
+  // chant #1078 — the command-group seam's first real tenant: `commands()`
+  // mounts a "kube" verb group, reserving the namespace #1079's `chant kube`
+  // terminal surface will add its own verbs to.
+  describe("commands() — the `kube` command group (#1078)", () => {
+    test("contributes a group named kube with a version verb", () => {
+      const group = k8sPlugin.commands!();
+      expect(group.name).toBe("kube");
+      expect(group.commands.map((c) => c.name)).toContain("version");
+    });
+
+    test("kube version prints the pinned K8S_SCHEMA_VERSION", async () => {
+      const { K8S_SCHEMA_VERSION } = await import("./spec/fetch");
+      const group = k8sPlugin.commands!();
+      const version = group.commands.find((c) => c.name === "version")!;
+      const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      try {
+        const exitCode = await version.handler({ verb: "version", rawArgs: [] });
+        expect(exitCode).toBe(0);
+        expect(logSpy).toHaveBeenCalledWith(K8S_SCHEMA_VERSION);
+      } finally {
+        logSpy.mockRestore();
+      }
+    });
+
+    test("kube version --format json emits a JSON envelope", async () => {
+      const { K8S_SCHEMA_VERSION } = await import("./spec/fetch");
+      const group = k8sPlugin.commands!();
+      const version = group.commands.find((c) => c.name === "version")!;
+      const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      try {
+        const exitCode = await version.handler({ verb: "version", rawArgs: ["--format", "json"] });
+        expect(exitCode).toBe(0);
+        expect(logSpy).toHaveBeenCalledWith(JSON.stringify({ schemaVersion: K8S_SCHEMA_VERSION }));
+      } finally {
+        logSpy.mockRestore();
+      }
+    });
+
+    test("kube version --format=json (joined form, #1127 discipline) works identically", async () => {
+      const group = k8sPlugin.commands!();
+      const version = group.commands.find((c) => c.name === "version")!;
+      const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      try {
+        await version.handler({ verb: "version", rawArgs: ["--format=json"] });
+        expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("schemaVersion"));
+      } finally {
+        logSpy.mockRestore();
+      }
+    });
+
+    test("kube version rejects an unknown flag (#1127 discipline applies to mounted commands)", async () => {
+      const group = k8sPlugin.commands!();
+      const version = group.commands.find((c) => c.name === "version")!;
+      await expect(version.handler({ verb: "version", rawArgs: ["--bogus"] })).rejects.toThrow(/Unknown flag: --bogus/);
+    });
+  });
 });

package/src/plugin.ts

@@ -6,6 +6,8 @@
  */
 
 import type { LexiconPlugin, InitTemplateSet, ResourceMetadata } from "@intentius/chant/lexicon";
+import type { CommandGroup } from "@intentius/chant/cli/command-group";
+import { kubeCommandGroup } from "./kube/group";
 import { detectTemplate } from "./detect";
 import type { LintRule } from "@intentius/chant/lint/rule";
 import { postSynthChecks as postSynthCheckList } from "./lint/post-synth";
@@ -23,6 +25,7 @@ import { k8sCompletions } from "./lsp/completions";
 import { k8sHover } from "./lsp/hover";
 import { K8sParser } from "./import/parser";
 import { K8sGenerator } from "./import/generator";
+import { k8sDeepNormalizationHooks } from "./deep-observe-hooks";
 
 export const k8sPlugin: LexiconPlugin = {
   name: "k8s",
@@ -37,6 +40,17 @@ export const k8sPlugin: LexiconPlugin = {
     upstream: { owner: "kubernetes", repo: "kubernetes", kind: "releases" },
   },
 
+  // chant #1078/#1079 — the command-group seam's tenant. `kube` mounts the
+  // terminal surface over the typed client: kubectl-compatible reads (get,
+  // describe, logs, events, top, wait), chant's own additions (source, the
+  // `get` verdict column, -o chant), and gated writes (apply, delete) that
+  // route through the exact same machinery the Op activities use — never a
+  // parallel implementation. See ./kube/group.ts for the full verb list;
+  // this plugin only mounts it.
+  commands(): CommandGroup {
+    return kubeCommandGroup();
+  },
+
   lintRules(): LintRule[] {
     return [
       hardcodedNamespaceRule,
@@ -617,4 +631,19 @@ const { deployment, service, serviceMonitor, prometheusRule } = MonitoredService
     const { exportResources } = await import("./export-resources");
     return exportResources(options);
   },
+
+  // Property-level live drift via SSA managed-fields (#1076, epic #1073).
+  // The reader lives in ./deep-observe.ts, loaded only through this dynamic
+  // import — same reason describeResources/exportResources are — so the API
+  // client never becomes reachable from the build path (chant #1074,
+  // examples/k8s-client-boundary.test.ts). deepNormalizationHooks is plain
+  // data with no client dependency (./deep-observe-hooks.ts) and is imported
+  // statically above, because core applies it to the *declared* tree whether
+  // or not a live read ever happens.
+  async observeResourcesDeep(options) {
+    const { observeResourcesDeepK8s } = await import("./deep-observe");
+    return observeResourcesDeepK8s(options);
+  },
+
+  deepNormalizationHooks: k8sDeepNormalizationHooks,
 };

package/src/spec/parse.ts

@@ -53,6 +53,26 @@ export interface GroupVersionKind {
   kind: string;
 }
 
+/**
+ * How this resource is addressed over the API — chant #1074.
+ *
+ * Read out of the same document the resource's types come from (the OpenAPI
+ * `paths` for core kinds, the CRD's `spec.names` / `spec.scope` for custom
+ * ones), so the operation surface and the declarable surface cannot drift
+ * apart the way a hand-maintained `kind → kubectl resource` table did.
+ *
+ * It is a starting point, not the authority: the live client confirms plural
+ * and scope against the cluster's own discovery, which is the only thing that
+ * knows what a given cluster actually serves.
+ */
+export interface ParsedOperation {
+  /** Plural path segment, e.g. `deployments`. */
+  plural: string;
+  scope: "Namespaced" | "Cluster";
+  /** Verbs the schema documents for the named resource, e.g. `get`, `patch`. */
+  verbs: string[];
+}
+
 export interface K8sParseResult {
   resource: ParsedResource;
   propertyTypes: ParsedPropertyType[];
@@ -60,6 +80,8 @@ export interface K8sParseResult {
   gvk: GroupVersionKind;
   /** Whether this entity is a property type (nested inside resources) */
   isProperty?: boolean;
+  /** How the API addresses this resource. Absent for property types. */
+  operation?: ParsedOperation;
 }
 
 // ── Swagger types ──────────────────────────────────────────────────
@@ -90,9 +112,17 @@ interface SwaggerProperty extends SwaggerDefinition {
 
 interface SwaggerSpec {
   definitions?: Record<string, SwaggerDefinition>;
+  paths?: Record<string, SwaggerPathItem>;
   [key: string]: unknown;
 }
 
+interface SwaggerOperation {
+  "x-kubernetes-group-version-kind"?: GroupVersionKind;
+  "x-kubernetes-action"?: string;
+}
+
+type SwaggerPathItem = Record<string, SwaggerOperation | unknown>;
+
 // ── Well-known property type definitions ───────────────────────────
 
 /**
@@ -162,6 +192,7 @@ export function parseK8sSwagger(data: string | Buffer): K8sParseResult[] {
   const spec: SwaggerSpec = JSON.parse(typeof data === "string" ? data : data.toString("utf-8"));
   const definitions = spec.definitions ?? {};
   const results: K8sParseResult[] = [];
+  const operations = parseOperations(spec.paths);
 
   // Phase 1: Extract top-level resources (definitions with GVK)
   for (const [defKey, def] of Object.entries(definitions)) {
@@ -176,7 +207,11 @@ export function parseK8sSwagger(data: string | Buffer): K8sParseResult[] {
 
     const typeName = gvkToTypeName(gvk);
     const result = extractResource(defKey, def, typeName, gvk, definitions);
-    if (result) results.push(result);
+    if (result) {
+      const operation = operations.get(gvkKey(gvk));
+      if (operation) result.operation = operation;
+      results.push(result);
+    }
   }
 
   // Phase 2: Extract well-known property types
@@ -191,6 +226,63 @@ export function parseK8sSwagger(data: string | Buffer): K8sParseResult[] {
   return results;
 }
 
+/** Stable key for a GVK, used to join the `paths` pass onto the `definitions` pass. */
+export function gvkKey(gvk: GroupVersionKind): string {
+  return `${gvk.group}|${gvk.version}|${gvk.kind}`;
+}
+
+/**
+ * Derive the operation surface from the OpenAPI `paths` — chant #1074.
+ *
+ * Every Kubernetes operation carries `x-kubernetes-group-version-kind` and
+ * `x-kubernetes-action`, and the path itself carries the two facts a REST call
+ * needs and a definition does not have: the plural segment, and whether the
+ * resource is namespaced (`/namespaces/{namespace}/` appears in its path).
+ *
+ * Only paths addressing a single named object (`.../{plural}/{name}`) are read,
+ * so subresource paths (`.../{name}/status`, `.../{name}/scale`) and collection
+ * paths do not supply the plural — but their verbs are collected, because
+ * "this kind can be listed" is worth knowing.
+ */
+export function parseOperations(paths: Record<string, SwaggerPathItem> | undefined): Map<string, ParsedOperation> {
+  const out = new Map<string, ParsedOperation>();
+  if (!paths) return out;
+
+  for (const [path, item] of Object.entries(paths)) {
+    for (const operation of Object.values(item ?? {})) {
+      if (!operation || typeof operation !== "object") continue;
+      const op = operation as SwaggerOperation;
+      const gvk = op["x-kubernetes-group-version-kind"];
+      const action = op["x-kubernetes-action"];
+      if (!gvk || !action) continue;
+
+      const segments = path.split("/").filter(Boolean);
+      const last = segments[segments.length - 1];
+      // `.../{plural}/{name}` — the only shape that names the plural
+      // unambiguously. `/api/v1/namespaces/{name}` is such a shape too, and
+      // correctly yields plural `namespaces`, cluster-scoped.
+      if (last !== "{name}") continue;
+      const plural = segments[segments.length - 2];
+      if (!plural || plural.startsWith("{")) continue;
+
+      const key = gvkKey(gvk);
+      const existing = out.get(key);
+      if (existing) {
+        if (!existing.verbs.includes(action)) existing.verbs.push(action);
+        continue;
+      }
+      out.set(key, {
+        plural,
+        scope: path.includes("/namespaces/{namespace}/") ? "Namespaced" : "Cluster",
+        verbs: [action],
+      });
+    }
+  }
+
+  for (const operation of out.values()) operation.verbs.sort();
+  return out;
+}
+
 /**
  * Convert GVK to our type name convention: K8s::{Group}::{Kind}
  */