@intentius/chant-lexicon-gcp 0.27.0 → 0.29.0

package/dist/describe-resources.d.ts

@@ -9,9 +9,19 @@
  *   GCP::Storage::Bucket    → kubectl get storagebucket.storage.cnrm.cloud.google.com
  *   GCP::Compute::Subnetwork → kubectl get computesubnetwork.compute.cnrm.cloud.google.com
  *
- * Resource-not-found is silent — `state diff --live` reports it as missing.
+ * Resource-not-found is an absence — `state diff --live` reports it as missing.
+ * Everything else the kubectl call can fail with (auth, an unreachable API
+ * server, an entity type with no derivable GVK) is NOT-OBSERVED (#1089), so a
+ * read that never happened cannot become a proposed `create`.
+ *
+ * Since this reads Config Connector CRDs through the same kubectl path as
+ * the K8s lexicon, it resolves the same environment→cluster binding (chant
+ * #1100) via `resolveClusterTarget` — `k8s.profiles.<env>.context` in
+ * `chant.config.ts` (see `lexicons/k8s/src/config.ts`), not a separate
+ * `gcp.profiles` key, because it is fundamentally the same kubectl context a
+ * project's K8s entities would use against the same cluster.
  */
-import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import type { ObservationResult } from "@intentius/chant/lexicon";
 /**
  * Mirror of `lexicons/gcp/src/serializer.ts:deriveGVKFromType` — keeping the
  * derivation logic local so describeResources can compute the kubectl resource
@@ -30,5 +40,5 @@ export declare function describeResources(options: {
         props: Record<string, unknown>;
     }>;
     owned?: boolean;
-}): Promise<Record<string, ResourceMetadata>>;
+}): Promise<ObservationResult>;
 //# sourceMappingURL=describe-resources.d.ts.map

package/dist/describe-resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAoBjE;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CASpF;AA4BD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAwC5C"}
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAsC,MAAM,0BAA0B,CAAC;AAuBtG;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CASpF;AA4BD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA8E7B"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "0fcdcb7ff056aa43420690a59a0927d5cfb50ab6de1b3399a399dbb529ea8782",
+    "manifest.json": "fa47fcfe6d8f3de4d1844dce0ccf6c7d35bfb0596dd700a11ea870986b29e8e6",
     "meta.json": "475f10909854d059a2e2d4fb541c058803422e38b9c64bd4d6858c0623eedb8c",
     "types/index.d.ts": "5433b54c04b57d6fda8f3d81ef92ed0aca87f7e8e5dd3ea92d8de6e62a3ccfab",
     "rules/hardcoded-project.ts": "228631d3159e1ffcce2359c66073d4ae59bb0285f378e46e446f416aec50481c",
@@ -37,5 +37,5 @@
     "skills/chant-gcp-patterns.md": "a7ef31c1eb2f7244d3f73952c300472ef94c1eb09bd7a1003281b89299b6b704",
     "skills/chant-gcp-gke.md": "be277019da9a722c851e47cd2dfb9c9536668948c3535fb20db7697e934c4e2b"
   },
-  "composite": "3ae099bad7752191fc7ffaec95374370d69de052349b8888efeafc758aeca632"
+  "composite": "83f8a5fc48ff3282c804d14768e9c904873d2fdc1b168276400780da729a4ba8"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "gcp",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "chantVersion": ">=0.1.0",
   "namespace": "GCP",
   "intrinsics": [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gcp",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Google Cloud lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -76,7 +76,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.27.0",
+    "@intentius/chant": "^0.29.0",
     "typescript": "^5.9.3"
   }
 }

package/src/describe-resources.test.ts

@@ -11,6 +11,11 @@ vi.mock("node:child_process", async () => {
   } };
 });
 
+const loadChantConfigMock = vi.fn();
+vi.mock("@intentius/chant/config", () => ({
+  loadChantConfig: (...args: unknown[]) => loadChantConfigMock(...args),
+}));
+
 const { describeResources } = await import("./describe-resources");
 
 function makeEntities(records: Array<{ name: string; entityType: string; props: Record<string, unknown> }>) {
@@ -20,6 +25,10 @@ function makeEntities(records: Array<{ name: string; entityType: string; props:
 describe("gcp describeResources (Config Connector)", () => {
   beforeEach(() => {
     execMock.mockReset();
+    loadChantConfigMock.mockReset();
+    // No binding declared by default — matches every test below except the
+    // dedicated cluster-binding tests, which override this per case.
+    loadChantConfigMock.mockResolvedValue({ config: {} });
   });
 
   test("queries kubectl with the derived CC GVK and maps the response", async () => {
@@ -46,7 +55,7 @@ describe("gcp describeResources (Config Connector)", () => {
     expect(receivedCmd).toContain("data-bucket");
     expect(receivedCmd).toContain("-n config-control");
 
-    expect(result["dataBucket"]).toMatchObject({
+    expect(result.resources["dataBucket"]).toMatchObject({
       type: "GCP::Storage::Bucket",
       physicalId: "uid-1",
       status: "READY",
@@ -90,7 +99,7 @@ describe("gcp describeResources (Config Connector)", () => {
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["x"], entities });
 
-    expect(result["x"].status).toBe("DependencyNotFound");
+    expect(result.resources["x"].status).toBe("DependencyNotFound");
   });
 
   test("missing Ready condition falls back to PRESENT", async () => {
@@ -108,10 +117,10 @@ describe("gcp describeResources (Config Connector)", () => {
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["x"], entities });
 
-    expect(result["x"].status).toBe("PRESENT");
+    expect(result.resources["x"].status).toBe("PRESENT");
   });
 
-  test("kubectl-not-found leaves entity out of result", async () => {
+  test("kubectl-not-found leaves entity out of result (a confirmed absence)", async () => {
     execMock.mockImplementation(() => { throw new Error('Error from server (NotFound): storagebucket "x" not found'); });
 
     const entities = makeEntities([
@@ -120,28 +129,115 @@ describe("gcp describeResources (Config Connector)", () => {
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["x"], entities });
 
-    expect(result).toEqual({});
+    expect(result.resources).toEqual({});
+    expect(result.unobserved ?? {}).toEqual({});
+  });
+
+  test("an unreachable cluster is unobserved, not absent (#1089)", async () => {
+    execMock.mockImplementation(() => {
+      throw Object.assign(new Error("kubectl failed"), {
+        stderr: "Unable to connect to the server: dial tcp: i/o timeout",
+      });
+    });
+
+    const entities = makeEntities([
+      { name: "x", entityType: "GCP::Storage::Bucket", props: { metadata: { name: "x" } } },
+    ]);
+
+    const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["x"], entities });
+
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.x?.reason).toBe("no-binding");
   });
 
-  test("non-GCP entity types are skipped", async () => {
+  test("non-GCP entity types are unobserved — no GVK to query (#1089)", async () => {
     const entities = makeEntities([
       { name: "x", entityType: "AWS::S3::Bucket", props: { metadata: { name: "x" } } },
     ]);
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["x"], entities });
 
-    expect(result).toEqual({});
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.x?.reason).toBe("unsupported-kind");
     expect(execMock).not.toHaveBeenCalled();
   });
 
-  test("entity without metadata.name is silently skipped", async () => {
+  test("entity without metadata.name is unobserved — nothing was queried", async () => {
     const entities = makeEntities([
       { name: "broken", entityType: "GCP::Storage::Bucket", props: {} },
     ]);
 
     const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["broken"], entities });
 
-    expect(result).toEqual({});
+    expect(result.resources).toEqual({});
+    expect(result.unobserved?.broken?.reason).toBe("read-failed");
     expect(execMock).not.toHaveBeenCalled();
   });
+
+  // chant #1100 — GCP-via-CNRM resolves the same environment→cluster binding
+  // as the K8s lexicon (bound-and-matching, bound-and-mismatched loud
+  // refusal, unbound unchanged), since it observes through the same kubectl
+  // path against the same cluster.
+  describe("cluster binding (chant #1100)", () => {
+    function bucketEntities() {
+      return makeEntities([
+        { name: "dataBucket", entityType: "GCP::Storage::Bucket", props: { metadata: { name: "data-bucket" } } },
+      ]);
+    }
+
+    const bucketStdout = JSON.stringify({
+      metadata: { name: "data-bucket", uid: "uid-1", creationTimestamp: "2026-05-01T00:00:00Z" },
+      status: { conditions: [{ type: "Ready", status: "True" }] },
+    });
+
+    test("bound and ambient context matches: observes explicitly via --context", async () => {
+      loadChantConfigMock.mockResolvedValue({ config: { k8s: { profiles: { prod: { context: "prod-cnrm" } } } } });
+      let receivedCmd = "";
+      execMock.mockImplementation((cmd: string) => {
+        if (cmd.includes("current-context")) return { stdout: "prod-cnrm\n", stderr: "" };
+        receivedCmd = cmd;
+        return { stdout: bucketStdout, stderr: "" };
+      });
+
+      const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["dataBucket"], entities: bucketEntities() });
+
+      expect(receivedCmd).toContain("--context prod-cnrm");
+      expect(result.resources["dataBucket"]).toMatchObject({ type: "GCP::Storage::Bucket", physicalId: "uid-1", status: "READY" });
+    });
+
+    test("bound and ambient context mismatches: refuses loudly instead of observing the wrong cluster", async () => {
+      loadChantConfigMock.mockResolvedValue({ config: { k8s: { profiles: { prod: { context: "prod-cnrm" } } } } });
+      execMock.mockImplementation((cmd: string) => {
+        if (cmd.includes("current-context")) return { stdout: "staging-cnrm\n", stderr: "" };
+        throw new Error(`unexpected cmd (should have refused before any kubectl get): ${cmd}`);
+      });
+
+      await expect(
+        describeResources({ environment: "prod", buildOutput: "", entityNames: ["dataBucket"], entities: bucketEntities() }),
+      ).rejects.toThrow(/environment "prod".*"prod-cnrm".*"staging-cnrm"/s);
+
+      expect(execMock).toHaveBeenCalledTimes(1);
+    });
+
+    test("unbound: ambient context is used unchanged, but the fallback is visible (not silent)", async () => {
+      loadChantConfigMock.mockResolvedValue({ config: {} });
+      const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+      let receivedCmd = "";
+      execMock.mockImplementation((cmd: string) => {
+        receivedCmd = cmd;
+        return { stdout: bucketStdout, stderr: "" };
+      });
+
+      const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["dataBucket"], entities: bucketEntities() });
+
+      expect(receivedCmd).not.toContain("--context");
+      expect(receivedCmd).not.toContain("current-context");
+      expect(result.resources["dataBucket"]).toMatchObject({ type: "GCP::Storage::Bucket", physicalId: "uid-1", status: "READY" });
+
+      const bindingWarning = warnSpy.mock.calls.find((c) => String(c[0]).includes("no cluster binding"));
+      expect(bindingWarning?.[0]).toContain('environment "prod"');
+      expect(bindingWarning?.[0]).toContain("k8s.profiles.prod.context");
+      warnSpy.mockRestore();
+    });
+  });
 });

package/src/describe-resources.ts

@@ -9,13 +9,26 @@
  *   GCP::Storage::Bucket    → kubectl get storagebucket.storage.cnrm.cloud.google.com
  *   GCP::Compute::Subnetwork → kubectl get computesubnetwork.compute.cnrm.cloud.google.com
  *
- * Resource-not-found is silent — `state diff --live` reports it as missing.
+ * Resource-not-found is an absence — `state diff --live` reports it as missing.
+ * Everything else the kubectl call can fail with (auth, an unreachable API
+ * server, an entity type with no derivable GVK) is NOT-OBSERVED (#1089), so a
+ * read that never happened cannot become a proposed `create`.
+ *
+ * Since this reads Config Connector CRDs through the same kubectl path as
+ * the K8s lexicon, it resolves the same environment→cluster binding (chant
+ * #1100) via `resolveClusterTarget` — `k8s.profiles.<env>.context` in
+ * `chant.config.ts` (see `lexicons/k8s/src/config.ts`), not a separate
+ * `gcp.profiles` key, because it is fundamentally the same kubectl context a
+ * project's K8s entities would use against the same cluster.
  */
 
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
-import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import type { ObservationResult, ResourceMetadata, UnobservedEntity } from "@intentius/chant/lexicon";
+import { observation } from "@intentius/chant/observation";
 import { hasOwnershipMarker, classifyOwnership, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+import { loadChantConfig } from "@intentius/chant/config";
+import { resolveClusterTarget, classifyKubectlFailure } from "@intentius/chant/kubectl-context";
 
 const execAsync = promisify(exec);
 
@@ -82,26 +95,57 @@ export async function describeResources(options: {
   entityNames: string[];
   entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
   owned?: boolean;
-}): Promise<Record<string, ResourceMetadata>> {
+}): Promise<ObservationResult> {
   const result: Record<string, ResourceMetadata> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
+
+  // Resolve the cluster identity for this environment before touching any
+  // resource — a declared-but-mismatched binding throws here, aborting the
+  // whole describe rather than letting the per-entity try/catch below
+  // absorb it as an ordinary "not found".
+  const { config } = await loadChantConfig(process.cwd());
+  const target = await resolveClusterTarget(config as Record<string, unknown>, options.environment, "gcp");
+  const ctxArg = target.context ? ["--context", target.context] : [];
 
   for (const [entityName, { entityType, props }] of options.entities) {
     const gvk = deriveGVK(entityType);
-    if (!gvk) continue;
+    if (!gvk) {
+      // Not a `GCP::Service::Kind` this lexicon can turn into a Config
+      // Connector GVK — nothing was queried, so nothing is known (#1089).
+      unobserved[entityName] = {
+        type: entityType,
+        reason: "unsupported-kind",
+        detail: `cannot derive a Config Connector GVK from ${entityType}`,
+      };
+      continue;
+    }
 
     const metadata = props.metadata as { name?: string; namespace?: string } | undefined;
     const name = metadata?.name;
-    if (!name) continue;
+    if (!name) {
+      unobserved[entityName] = {
+        type: entityType,
+        reason: "read-failed",
+        detail: "declared entity has no metadata.name to query by",
+      };
+      continue;
+    }
 
     const kubectlResource = `${gvk.kind.toLowerCase()}.${gvk.group}`;
     const nsArg = metadata.namespace ? ["-n", metadata.namespace] : [];
-    const cmd = ["kubectl", "get", kubectlResource, name, ...nsArg, "-o", "json"].join(" ");
+    const cmd = ["kubectl", "get", kubectlResource, name, ...nsArg, ...ctxArg, "-o", "json"].join(" ");
 
     try {
       const { stdout } = await execAsync(cmd);
       const obj: KubectlResponse = JSON.parse(stdout);
-      // owned filter: skip resources not carrying chant's marker label.
+      // owned filter: withhold resources not carrying chant's marker label.
+      // Withheld is not absent (#1089) — the CR exists, it just isn't chant's.
       if (options.owned && !hasOwnershipMarker(obj.metadata?.labels, LABEL_OWNERSHIP_KEYS)) {
+        unobserved[entityName] = {
+          type: entityType,
+          reason: "filtered",
+          detail: "live resource carries no chant ownership marker and --owned was requested",
+        };
         continue;
       }
       result[entityName] = {
@@ -116,10 +160,17 @@ export async function describeResources(options: {
           annotations: obj.metadata?.annotations,
         }),
       };
-    } catch {
-      // CRD or instance not found — skip silently
+    } catch (err) {
+      // A NotFound is a real absence (the CR isn't there, or Config Connector
+      // doesn't serve that CRD, so no instance can be). Anything else — auth,
+      // an unreachable API server, a context that doesn't resolve — proves
+      // nothing and is reported as a hole rather than an absence (#1089).
+      const outcome = classifyKubectlFailure(err);
+      if (outcome.kind === "unobserved") {
+        unobserved[entityName] = { type: entityType, reason: outcome.reason, detail: outcome.detail };
+      }
     }
   }
 
-  return result;
+  return observation(result, unobserved);
 }

package/src/lifecycle-integration.test.ts

@@ -31,6 +31,8 @@ vi.mock("node:child_process", async () => {
 const { gcpPlugin } = await import("./plugin");
 const { liveImportFromPlugins } = await import("@intentius/chant/cli/commands/import");
 const { buildChangeSet } = await import("@intentius/chant/lifecycle/change-set");
+const { normalizeObservation } = await import("@intentius/chant/observation");
+const { describeObservationConformance } = await import("@intentius/chant-test-utils");
 
 const liveBucket = {
   apiVersion: "storage.cnrm.cloud.google.com/v1beta1",
@@ -84,20 +86,22 @@ describe("gcp lifecycle integration (#163)", () => {
         : new Error("not found"),
     );
 
-    const observedNow = await gcpPlugin.describeResources!({
-      environment: "prod",
-      buildOutput: "",
-      entityNames: ["dataBucket"],
-      entities: new Map([
-        [
-          "dataBucket",
-          {
-            entityType: "GCP::Storage::Bucket",
-            props: { metadata: { name: "data-bucket", namespace: "config-control" } },
-          },
-        ],
-      ]),
-    });
+    const { resources: observedNow } = normalizeObservation(
+      await gcpPlugin.describeResources!({
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["dataBucket"],
+        entities: new Map([
+          [
+            "dataBucket",
+            {
+              entityType: "GCP::Storage::Bucket",
+              props: { metadata: { name: "data-bucket", namespace: "config-control" } },
+            },
+          ],
+        ]),
+      }),
+    );
     expect(observedNow.dataBucket?.type).toBe("GCP::Storage::Bucket");
 
     const cs = buildChangeSet("prod", {
@@ -117,3 +121,46 @@ describe("gcp lifecycle integration (#163)", () => {
     expect(cs2.entries.find((e) => e.name === "dataBucket")!.action).toBe("noop");
   });
 });
+
+// The shared conformance suite (#1089).
+describeObservationConformance({
+  lexicon: "gcp",
+  scenarios: [
+    {
+      name: "an entity type with no derivable Config Connector GVK",
+      declared: ["notGcp", "gone"],
+      expectUnobserved: ["notGcp"],
+      expectAbsent: ["gone"],
+      run: () => {
+        execMock.mockImplementation(() => new Error('Error from server (NotFound): storagebucket "gone" not found'));
+        return gcpPlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["notGcp", "gone"],
+          entities: new Map([
+            ["notGcp", { entityType: "AWS::S3::Bucket", props: { metadata: { name: "not-gcp" } } }],
+            ["gone", { entityType: "GCP::Storage::Bucket", props: { metadata: { name: "gone" } } }],
+          ]),
+        });
+      },
+    },
+    {
+      name: "an unreachable Config Connector cluster",
+      declared: ["dataBucket"],
+      expectUnobserved: ["dataBucket"],
+      run: () => {
+        execMock.mockImplementation(() =>
+          Object.assign(new Error("kubectl failed"), { stderr: "Unable to connect to the server: dial tcp: i/o timeout" }),
+        );
+        return gcpPlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["dataBucket"],
+          entities: new Map([
+            ["dataBucket", { entityType: "GCP::Storage::Bucket", props: { metadata: { name: "data-bucket" } } }],
+          ]),
+        });
+      },
+    },
+  ],
+});