@intentius/chant-lexicon-k8s 0.30.0 → 0.31.0

package/src/api/fake-cluster.ts

@@ -0,0 +1,218 @@
+/**
+ * A fake cluster to point the k8s lexicon at, for tests (chant #1074).
+ *
+ * It builds a **real** `@intentius/chant-k8s-client` over a literal kubeconfig
+ * with `@kubernetes/client-node`'s HTTP send replaced. So kubeconfig parsing,
+ * context selection, the credential policy, API discovery, path construction
+ * and the auth path all run for real; the only thing that does not happen is
+ * the socket. Nothing reads `~/.kube/config` or `$KUBECONFIG`, and nothing can
+ * reach a cluster the developer happens to have a context for.
+ *
+ * Shipped rather than kept in a test file because the lexicon's own tests, the
+ * cross-lexicon lifecycle suite and a consumer wiring chant into their harness
+ * all need the same thing.
+ */
+
+import type { K8sObject } from "@intentius/chant-k8s-client";
+import { apiResourceList, fakeKubeconfig, fakeRequestLayer, statusBody } from "@intentius/chant-k8s-client/testing";
+import type { FakeRequestLayer, RecordedRequest } from "@intentius/chant-k8s-client/testing";
+import { createK8sClient } from "@intentius/chant-k8s-client";
+import type { ConnectedClient, ConnectOptions, K8sConnector } from "./connect";
+import { operationTable } from "./operation-surface";
+
+export interface FakeClusterOptions {
+  /**
+   * Objects the cluster holds, keyed by
+   * `<apiVersion>/<Kind>/<namespace|_>/<name>`, e.g.
+   * `apps/v1/Deployment/prod/web`. Build keys with {@link objectKey}.
+   */
+  objects?: Record<string, K8sObject>;
+  /**
+   * Entity types (or `<apiVersion> <Kind>` pairs) this cluster serves. Defaults
+   * to every type in the generated operation surface, which is what makes a
+   * CRD resolvable in a test without registering anything.
+   */
+  serves?: readonly string[];
+  /** Full control: return a response for a request, or undefined to fall through. */
+  respond?: (request: RecordedRequest) => { status?: number; body?: unknown } | undefined;
+  /** Kubeconfig to hand the client. Defaults to a single-context one. */
+  kubeconfig?: string;
+}
+
+export interface FakeCluster {
+  connector: K8sConnector;
+  layer: FakeRequestLayer;
+  /** Connect options every call received, for asserting the binding path. */
+  connects: ConnectOptions[];
+}
+
+/** Key an object the way {@link fakeCluster} indexes them. */
+export function objectKey(apiVersion: string, kind: string, name: string, namespace?: string): string {
+  return `${apiVersion}/${kind}/${namespace ?? "_"}/${name}`;
+}
+
+/** Build a live object with chant's ownership marker already on it. */
+export function ownedObject(
+  apiVersion: string,
+  kind: string,
+  name: string,
+  namespace: string | undefined,
+  extra: Partial<K8sObject> = {},
+): K8sObject {
+  return {
+    apiVersion,
+    kind,
+    metadata: {
+      name,
+      ...(namespace ? { namespace } : {}),
+      uid: `uid-${name}`,
+      resourceVersion: "1",
+      labels: { "app.kubernetes.io/managed-by": "chant" },
+      ...(extra.metadata ?? {}),
+    },
+    ...(extra.status ? { status: extra.status } : {}),
+  };
+}
+
+interface ServedResource {
+  apiVersion: string;
+  kind: string;
+  plural: string;
+  namespaced: boolean;
+}
+
+function servedResources(serves: readonly string[] | undefined): ServedResource[] {
+  const table = operationTable();
+  const entries = serves
+    ? serves.map((s) => table[s]).filter((d) => d !== undefined)
+    : Object.values(table);
+  return entries
+    .filter((d) => d.verbs.length > 0)
+    .map((d) => ({
+      apiVersion: d.apiVersion,
+      kind: d.kind,
+      plural: d.plural,
+      namespaced: d.scope === "Namespaced",
+    }));
+}
+
+/**
+ * A cluster that answers discovery for the kinds it serves and holds the
+ * objects it was given. Anything else 404s with a real `Status` body, which is
+ * how a test drives the absent branch of the observation tri-state.
+ */
+export function fakeCluster(options: FakeClusterOptions = {}): FakeCluster {
+  const resources = servedResources(options.serves);
+  const byApiVersion = new Map<string, ServedResource[]>();
+  for (const r of resources) {
+    const list = byApiVersion.get(r.apiVersion) ?? [];
+    list.push(r);
+    byApiVersion.set(r.apiVersion, list);
+  }
+
+  // Path → the object it addresses, and list path → its members, precomputed
+  // so the responder below is a pair of lookups.
+  const byPath = new Map<string, K8sObject>();
+  const listPaths = new Map<string, K8sObject[]>();
+  const addToList = (path: string, object: K8sObject): void => {
+    const list = listPaths.get(path) ?? [];
+    list.push(object);
+    listPaths.set(path, list);
+  };
+  for (const [key, object] of Object.entries(options.objects ?? {})) {
+    const [group, version, kind, namespace, name] = splitKey(key);
+    const apiVersion = group ? `${group}/${version}` : version;
+    const resource = resources.find((r) => r.apiVersion === apiVersion && r.kind === kind);
+    if (!resource) continue;
+    const base = apiVersion.includes("/") ? `/apis/${apiVersion}` : `/api/${apiVersion}`;
+    if (resource.namespaced) {
+      const ns = namespace === "_" ? "default" : namespace;
+      byPath.set(`${base}/namespaces/${ns}/${resource.plural}/${name}`, object);
+      addToList(`${base}/namespaces/${ns}/${resource.plural}`, object);
+    } else {
+      byPath.set(`${base}/${resource.plural}/${name}`, object);
+    }
+    // Cluster-wide list, which is what `chant import` sweeps.
+    addToList(`${base}/${resource.plural}`, object);
+  }
+
+  const groups = new Map<string, string>();
+  for (const apiVersion of byApiVersion.keys()) {
+    if (!apiVersion.includes("/")) continue;
+    const group = apiVersion.slice(0, apiVersion.indexOf("/"));
+    if (!groups.has(group)) groups.set(group, apiVersion);
+  }
+
+  const layer = fakeRequestLayer((request) => {
+    const custom = options.respond?.(request);
+    if (custom !== undefined) return custom;
+
+    if (request.path === "/api") return { body: { kind: "APIVersions", versions: ["v1"] } };
+    if (request.path === "/apis") {
+      return {
+        body: {
+          kind: "APIGroupList",
+          groups: [...groups].map(([name, apiVersion]) => ({
+            name,
+            preferredVersion: { groupVersion: apiVersion, version: apiVersion.split("/")[1] },
+            versions: [{ groupVersion: apiVersion }],
+          })),
+        },
+      };
+    }
+
+    const apiVersion = apiVersionFromDiscoveryPath(request.path);
+    if (apiVersion) {
+      const served = byApiVersion.get(apiVersion);
+      if (!served) return { status: 404, body: statusBody(404, "NotFound", "the server could not find the requested resource") };
+      return {
+        body: apiResourceList(
+          apiVersion,
+          served.map((r) => ({ name: r.plural, kind: r.kind, namespaced: r.namespaced })),
+        ),
+      };
+    }
+
+    const object = byPath.get(request.path);
+    if (object) return { body: object };
+
+    if (isListPath(request.path, resources)) {
+      return { body: { kind: "List", items: listPaths.get(request.path) ?? [], metadata: {} } };
+    }
+
+    return { status: 404, body: statusBody(404, "NotFound", `${request.path} not found`) };
+  });
+
+  const connects: ConnectOptions[] = [];
+  const connector: K8sConnector = async (connectOptions): Promise<ConnectedClient> => {
+    connects.push(connectOptions);
+    const client = await createK8sClient({
+      kubeconfig: options.kubeconfig ?? fakeKubeconfig(),
+      requestLayer: layer,
+      ...(connectOptions.context ? { context: connectOptions.context } : {}),
+      ...connectOptions.client,
+    });
+    return { client, target: { source: "ambient" } };
+  };
+
+  return { connector, layer, connects };
+}
+
+function splitKey(key: string): [group: string, version: string, kind: string, namespace: string, name: string] {
+  const parts = key.split("/");
+  // `apps/v1/Deployment/prod/web` (5) or `v1/Service/prod/web` (4)
+  if (parts.length === 5) return [parts[0], parts[1], parts[2], parts[3], parts[4]];
+  return ["", parts[0], parts[1], parts[2], parts[3]];
+}
+
+function apiVersionFromDiscoveryPath(path: string): string | undefined {
+  if (/^\/api\/[^/]+$/.test(path)) return path.slice("/api/".length);
+  if (/^\/apis\/[^/]+\/[^/]+$/.test(path)) return path.slice("/apis/".length);
+  return undefined;
+}
+
+/** True when the path addresses a collection of a kind this cluster serves. */
+function isListPath(path: string, resources: ServedResource[]): boolean {
+  const plural = path.split("/").pop();
+  return resources.some((r) => r.plural === plural);
+}

package/src/api/operation-surface.test.ts

@@ -0,0 +1,116 @@
+/**
+ * The generated operation surface (chant #1074) — and the anti-skew gate that
+ * is the whole reason it is generated rather than written.
+ *
+ * The issue's requirement is that the client's addressing and the declarable
+ * types come out of the same codegen pass "so types and client cannot skew".
+ * Generating them together is the mechanism; this file is the proof, and it is
+ * what would fail if someone later added a resource to one artifact and not the
+ * other.
+ */
+
+import { describe, test, expect } from "vitest";
+import { createRequire } from "module";
+import { addressableEntityTypes, deriveOperation, operationFor, operationTable, pluralizeKind } from "./operation-surface";
+
+const require = createRequire(import.meta.url);
+
+interface RegistryEntry {
+  resourceType: string;
+  kind: "resource" | "property";
+  apiVersion?: string;
+  gvkKind?: string;
+}
+
+const registry = require("../generated/lexicon-k8s.json") as Record<string, RegistryEntry>;
+
+describe("operation surface ↔ declarable registry (the anti-skew gate)", () => {
+  test("every registry resource with a GVK has an operation entry saying the same thing", () => {
+    const table = operationTable();
+    const missing: string[] = [];
+    const disagreeing: string[] = [];
+
+    for (const entry of Object.values(registry)) {
+      if (entry.kind !== "resource" || !entry.apiVersion || !entry.gvkKind) continue;
+      const operation = table[entry.resourceType];
+      if (!operation) {
+        missing.push(entry.resourceType);
+        continue;
+      }
+      if (operation.apiVersion !== entry.apiVersion || operation.kind !== entry.gvkKind) {
+        disagreeing.push(
+          `${entry.resourceType}: registry ${entry.apiVersion}/${entry.gvkKind} vs operations ${operation.apiVersion}/${operation.kind}`,
+        );
+      }
+    }
+
+    expect(missing, "resources the serializer can emit but the client cannot address").toEqual([]);
+    expect(disagreeing, "resources the serializer and the client disagree about").toEqual([]);
+  });
+
+  test("no operation entry names a type the registry does not carry", () => {
+    const known = new Set(Object.values(registry).map((e) => e.resourceType));
+    const orphans = addressableEntityTypes().filter((t) => !known.has(t));
+    expect(orphans, "operation entries with no declarable type behind them").toEqual([]);
+  });
+
+  test("coverage is an order of magnitude past the twenty-entry map it replaces", () => {
+    // The retired KUBECTL_RESOURCE had 20 entries and every CRD fell off it.
+    expect(addressableEntityTypes().length).toBeGreaterThan(150);
+  });
+});
+
+describe("addressing", () => {
+  test.each([
+    ["K8s::Apps::Deployment", "apps/v1", "Deployment", "deployments", "Namespaced"],
+    ["K8s::Core::Pod", "v1", "Pod", "pods", "Namespaced"],
+    ["K8s::Core::Namespace", "v1", "Namespace", "namespaces", "Cluster"],
+    ["K8s::Rbac::ClusterRole", "rbac.authorization.k8s.io/v1", "ClusterRole", "clusterroles", "Cluster"],
+    ["K8s::Networking::Ingress", "networking.k8s.io/v1", "Ingress", "ingresses", "Namespaced"],
+    ["K8s::Batch::CronJob", "batch/v1", "CronJob", "cronjobs", "Namespaced"],
+  ])("%s → %s %s /%s (%s)", (entityType, apiVersion, kind, plural, scope) => {
+    expect(operationFor(entityType)).toMatchObject({ apiVersion, kind, plural, scope });
+  });
+
+  // Every one of these was `unsupported-kind` before #1074.
+  test.each([
+    ["K8s::Ray::RayCluster", "ray.io/v1", "RayCluster", "rayclusters"],
+    ["K8s::Argo::Application", "argoproj.io/v1alpha1", "Application", "applications"],
+    ["K8s::CertManager::Certificate", "cert-manager.io/v1", "Certificate", "certificates"],
+    ["K8s::Monitoring::ServiceMonitor", "monitoring.coreos.com/v1", "ServiceMonitor", "servicemonitors"],
+  ])("CRD %s → %s %s /%s", (entityType, apiVersion, kind, plural) => {
+    expect(operationFor(entityType)).toMatchObject({ apiVersion, kind, plural });
+  });
+
+  test("the plural and scope come from the schema, not from a guess", () => {
+    // `ingresses`, not `ingresss`; `namespaces` cluster-scoped, not namespaced.
+    const ingress = operationFor("K8s::Networking::Ingress")!;
+    expect(ingress.plural).toBe("ingresses");
+    expect(operationFor("K8s::Core::Namespace")!.scope).toBe("Cluster");
+    // And verbs are documented rather than assumed.
+    expect(ingress.verbs).toContain("get");
+  });
+
+  test("an entity type in no known API group is not guessed at", () => {
+    expect(operationFor("K8s::NotAGroupChantKnows::Thing")).toBeUndefined();
+    expect(operationFor("AWS::S3::Bucket")).toBeUndefined();
+    expect(operationFor("nonsense")).toBeUndefined();
+  });
+
+  test("derivation covers a checkout with no generated artifacts", () => {
+    expect(deriveOperation("K8s::Apps::Deployment")).toMatchObject({ apiVersion: "apps/v1", kind: "Deployment" });
+    expect(deriveOperation("K8s::Ray::RayCluster")).toBeUndefined();
+  });
+});
+
+describe("pluralizeKind", () => {
+  test.each([
+    ["Deployment", "deployments"],
+    ["Ingress", "ingresses"],
+    ["NetworkPolicy", "networkpolicies"],
+    ["Endpoints", "endpointses"],
+    ["Gateway", "gateways"],
+  ])("%s → %s", (kind, plural) => {
+    expect(pluralizeKind(kind)).toBe(plural);
+  });
+});

package/src/api/operation-surface.ts

@@ -0,0 +1,129 @@
+/**
+ * Reading the generated operation surface — chant #1074.
+ *
+ * The table itself is written by `chant generate` (see
+ * `../codegen/generate-operations.ts`); this is the runtime side, and it is
+ * deliberately the only place in the lexicon that knows how an entity type
+ * becomes an API address.
+ *
+ * Loading mirrors the serializer's handling of `lexicon-k8s.json`: a `require`
+ * behind a try/catch, so a checkout that has not run `chant generate` yet
+ * degrades to derivation rather than failing to import. Nothing here touches
+ * the filesystem at module load (chant #1081) — the first call does, and caches.
+ */
+
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+
+/** One resource's addressing information, as `chant generate` emits it. */
+export interface K8sOperationDescriptor {
+  /** chant entity type, e.g. `K8s::Apps::Deployment`. */
+  entityType: string;
+  /** `v1`, `apps/v1`, `ray.io/v1` — what goes in a manifest. */
+  apiVersion: string;
+  /** `Deployment`, `RayCluster`. */
+  kind: string;
+  /** Plural path segment the schema documents, e.g. `deployments`. */
+  plural: string;
+  scope: "Namespaced" | "Cluster";
+  /** Verbs the schema documents for the named-object path. */
+  verbs: string[];
+}
+
+/** The generated file's shape: entity type → descriptor. */
+export type K8sOperationTable = Record<string, K8sOperationDescriptor>;
+
+/**
+ * Fallback plural for a kind whose schema documented no named-object path.
+ *
+ * Kubernetes' own pluralization for resource names is the lowercased kind with
+ * English plural rules applied — the three cases `kubectl` implements. It only
+ * fires for kinds the OpenAPI paths do not cover, and the live client overrides
+ * it from the cluster's discovery regardless, so it is a placeholder rather
+ * than a second table to maintain.
+ */
+export function pluralizeKind(kind: string): string {
+  const lower = kind.toLowerCase();
+  if (/(s|x|z|ch|sh)$/.test(lower)) return `${lower}es`;
+  if (/[^aeiou]y$/.test(lower)) return `${lower.slice(0, -1)}ies`;
+  return `${lower}s`;
+}
+
+/**
+ * Well-known API group → apiVersion, for a checkout with no generated table.
+ * Deliberately the same list the serializer falls back to, so a lexicon
+ * running without generated artifacts addresses what it serializes.
+ */
+const FALLBACK_GROUP_VERSIONS: Record<string, string> = {
+  Core: "v1",
+  Apps: "apps/v1",
+  Batch: "batch/v1",
+  Networking: "networking.k8s.io/v1",
+  Policy: "policy/v1",
+  Rbac: "rbac.authorization.k8s.io/v1",
+  Storage: "storage.k8s.io/v1",
+  Autoscaling: "autoscaling/v2",
+  Admissionregistration: "admissionregistration.k8s.io/v1",
+};
+
+let cached: K8sOperationTable | null = null;
+
+/** The generated table, loaded once. Empty when nothing has been generated. */
+export function operationTable(): K8sOperationTable {
+  if (cached) return cached;
+  try {
+    cached = require("../generated/operations.json") as K8sOperationTable;
+  } catch {
+    cached = {};
+  }
+  return cached;
+}
+
+/** Reset the memoized table. Tests only. */
+export function resetOperationTableForTests(): void {
+  cached = null;
+}
+
+/**
+ * How to address a declared entity type over the API.
+ *
+ * Returns undefined only for a type the generated surface does not carry and
+ * whose `K8s::<Group>::<Kind>` shape yields no known group — which is the one
+ * case where chant genuinely does not know what to ask for. Every generated
+ * resource type, including every CRD baked in at generation time, is in the
+ * table; that is the difference between this and the twenty-entry map it
+ * replaces.
+ */
+export function operationFor(entityType: string): K8sOperationDescriptor | undefined {
+  const table = operationTable();
+  const found = table[entityType];
+  if (found) return found;
+  return deriveOperation(entityType);
+}
+
+/**
+ * Last-resort derivation from the entity type's own shape, for a lexicon
+ * running without generated artifacts. It cannot invent an API group it has
+ * never seen, so an unknown group returns undefined rather than a guess that
+ * would address the wrong thing.
+ */
+export function deriveOperation(entityType: string): K8sOperationDescriptor | undefined {
+  const parts = entityType.split("::");
+  if (parts.length !== 3 || parts[0] !== "K8s") return undefined;
+  const apiVersion = FALLBACK_GROUP_VERSIONS[parts[1]];
+  if (!apiVersion) return undefined;
+  return {
+    entityType,
+    apiVersion,
+    kind: parts[2],
+    plural: pluralizeKind(parts[2]),
+    scope: "Namespaced",
+    verbs: [],
+  };
+}
+
+/** Every entity type the generated surface can address. */
+export function addressableEntityTypes(): string[] {
+  return Object.keys(operationTable()).sort();
+}

package/src/codegen/generate-operations.ts

@@ -0,0 +1,56 @@
+/**
+ * The generated operation surface — chant #1074.
+ *
+ * `describeResources` used to reach the cluster through a hand-written
+ * `entityType → kubectl resource` map with twenty entries in it. Every one of
+ * the other ~180 generated resource types, and every CRD, fell off the end of
+ * it. The map was hand-maintained precisely because nothing derived it, and
+ * nothing derived it because the codegen pass that produces the types never
+ * emitted the addressing half.
+ *
+ * It does now. This artifact is written by the same `generate()` run that
+ * writes `lexicon-k8s.json` and `index.d.ts`, out of the same parsed results,
+ * so a resource that has a declarable class necessarily has an operation entry
+ * with the same apiVersion and kind. `operation-surface.test.ts` asserts that
+ * correspondence rather than trusting it.
+ *
+ * What it is not: an authority on what a given cluster serves. `plural` and
+ * `scope` are what the schema says; the live client confirms both against the
+ * cluster's own discovery before addressing anything, because a cluster can
+ * serve a different version of a CRD than the one chant generated from.
+ */
+
+import type { K8sParseResult } from "../spec/parse";
+import { gvkToApiVersion } from "../spec/parse";
+import { pluralizeKind, type K8sOperationDescriptor, type K8sOperationTable } from "../api/operation-surface";
+
+export type { K8sOperationDescriptor, K8sOperationTable };
+
+/** Build the operation table from the same parsed results the types come from. */
+export function buildOperationTable(results: K8sParseResult[]): K8sOperationTable {
+  const table: K8sOperationTable = {};
+  for (const result of results) {
+    if (result.isProperty) continue;
+    const entityType = result.resource.typeName;
+    // A later result for the same type wins nothing — the first parse of a
+    // preferred version is canonical, matching the registry's own precedence.
+    if (table[entityType]) continue;
+    table[entityType] = {
+      entityType,
+      apiVersion: gvkToApiVersion(result.gvk),
+      kind: result.gvk.kind,
+      plural: result.operation?.plural ?? pluralizeKind(result.gvk.kind),
+      scope: result.operation?.scope ?? "Namespaced",
+      verbs: result.operation?.verbs ?? [],
+    };
+  }
+  return table;
+}
+
+/** Serialize the table, key-sorted so regeneration produces a stable diff. */
+export function generateOperationsJSON(results: K8sParseResult[]): string {
+  const table = buildOperationTable(results);
+  const sorted: K8sOperationTable = {};
+  for (const key of Object.keys(table).sort()) sorted[key] = table[key];
+  return `${JSON.stringify(sorted, null, 2)}\n`;
+}

package/src/codegen/generate.ts

@@ -17,6 +17,7 @@ import { loadMultipleCRDs } from "../crd/loader";
 import { CRD_SOURCES } from "../crd/crd-sources";
 import { NamingStrategy, propertyTypeName, extractDefName } from "./naming";
 import { generateLexiconJSON } from "./generate-lexicon";
+import { generateOperationsJSON } from "./generate-operations";
 import { generateTypeScriptDeclarations } from "./generate-typescript";
 import {
   generateRuntimeIndex as coreGenerateRuntimeIndex,
@@ -98,6 +99,13 @@ export async function generate(opts: K8sGenerateOptions = {}): Promise<GenerateR
     generateRuntimeIndex: (results, naming) => {
       return generateRuntimeIndex(results, naming as NamingStrategy);
     },
+
+    // chant #1074 — the operation surface, out of the same results the types
+    // and the registry come out of, so the live client cannot address a kind
+    // differently from how the declarable surface names it.
+    generateExtraArtifacts: (results) => ({
+      "operations.json": generateOperationsJSON(results),
+    }),
   };
 
   return generatePipeline(config, opts);
@@ -114,6 +122,7 @@ export function writeGeneratedFiles(result: GenerateResult, baseDir: string): vo
       "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`,
+      ...(result.extraArtifacts ?? {}),
     },
   });
 }

package/src/config.ts

@@ -60,4 +60,21 @@ export interface K8sClusterProfile {
 export interface K8sChantConfig {
   /** Named environment → cluster bindings, keyed by environment name. */
   profiles?: Record<string, K8sClusterProfile>;
+  /**
+   * Exec credential-plugin commands chant may execute (chant #1074).
+   *
+   * On EKS, AKS and GKE, kubeconfig authentication is a subprocess:
+   * `aws eks get-token`, `kubelogin`, `gke-gcloud-auth-plugin`. Those three
+   * plus `kubectl` are allowed by default. Anything else the kubeconfig names
+   * is refused, because an exec plugin is an arbitrary binary named in a file
+   * chant did not write. Setting this **replaces** the default list.
+   *
+   * ```ts
+   * k8s: {
+   *   profiles: { prod: { context: "prod-eks" } },
+   *   execCredentialPlugins: ["aws", "my-org-oidc-helper"],
+   * } satisfies K8sChantConfig
+   * ```
+   */
+  execCredentialPlugins?: string[];
 }

package/src/crd/parser.ts

@@ -124,6 +124,14 @@ export function parseCRDSpec(spec: CRDSpec): K8sParseResult[] {
     propertyTypes: status.propertyType ? [...propertyTypes, status.propertyType] : propertyTypes,
     enums: [],
     gvk,
+    // chant #1074 — the CRD declares its own plural and scope, so the
+    // operation surface for a custom resource comes from the same document its
+    // types do, exactly as the OpenAPI `paths` supply them for built-in kinds.
+    operation: {
+      plural: spec.names.plural,
+      scope: spec.scope ?? "Namespaced",
+      verbs: ["delete", "get", "list", "patch", "post", "put", "watch"],
+    },
   });
 
   return results;

package/src/crd/types.ts

@@ -34,6 +34,13 @@ export interface CRDSource {
 export interface CRDSpec {
   /** API group (e.g. "cert-manager.io") */
   group: string;
+  /**
+   * Whether instances are namespaced. Declared by the CRD itself, so it is the
+   * authoritative source for a custom resource's scope — the equivalent of what
+   * the OpenAPI `paths` say for built-in kinds (chant #1074). Defaults to
+   * `Namespaced`, matching the API server's own default.
+   */
+  scope?: "Namespaced" | "Cluster";
   /** Name variants for the CRD */
   names: {
     kind: string;