@intentius/chant-lexicon-gcp 0.1.6 → 0.1.8

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "8939a54211882426c712c23fd6cdf36237dd92741ce3b3d18227f84225e2c50c",
+    "manifest.json": "31ad54417045b2707c880b9b6176dd0aa8a5feeb1dfbc645f9d1a20707c525f5",
     "meta.json": "2bc3713e9e01e90832d18dedaf4bf544dd4d8fe32f1363f7e95dc711d3d76e9d",
     "types/index.d.ts": "0554f7e883c6216ba735cbe79a8534ccad762bea28cc4d4c4884f8760a2f1dd3",
     "rules/hardcoded-project.ts": "228631d3159e1ffcce2359c66073d4ae59bb0285f378e46e446f416aec50481c",
@@ -37,5 +37,5 @@
     "skills/chant-gcp-patterns.md": "a7ef31c1eb2f7244d3f73952c300472ef94c1eb09bd7a1003281b89299b6b704",
     "skills/chant-gcp-gke.md": "be277019da9a722c851e47cd2dfb9c9536668948c3535fb20db7697e934c4e2b"
   },
-  "composite": "a66d209a7b1a390307e1603ac89a5552e0bd6b095fe7c49ee968a4cb7640d8d6"
+  "composite": "a1ac4dc45f5c0421e27da3284a16555e53820e14a09161ce3318d10cb75b5024"
 }

package/dist/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gcp",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Google Cloud lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/describe-resources.test.ts

@@ -0,0 +1,147 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+
+const execMock = vi.fn();
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return { ...actual, exec: (cmd: string, cb: (err: Error | null, out: { stdout: string; stderr: string }) => void) => {
+    Promise.resolve(execMock(cmd)).then(
+      (out) => cb(null, out),
+      (err) => cb(err as Error, { stdout: "", stderr: "" }),
+    );
+  } };
+});
+
+const { describeResources } = await import("./describe-resources");
+
+function makeEntities(records: Array<{ name: string; entityType: string; props: Record<string, unknown> }>) {
+  return new Map(records.map((r) => [r.name, { entityType: r.entityType, props: r.props }]));
+}
+
+describe("gcp describeResources (Config Connector)", () => {
+  beforeEach(() => {
+    execMock.mockReset();
+  });
+
+  test("queries kubectl with the derived CC GVK and maps the response", async () => {
+    let receivedCmd = "";
+    execMock.mockImplementation((cmd: string) => {
+      receivedCmd = cmd;
+      return {
+        stdout: JSON.stringify({
+          metadata: { name: "data-bucket", namespace: "config-control", uid: "uid-1", creationTimestamp: "2026-05-01T00:00:00Z" },
+          status: { conditions: [{ type: "Ready", status: "True" }] },
+        }),
+        stderr: "",
+      };
+    });
+
+    const entities = makeEntities([
+      { name: "dataBucket", entityType: "GCP::Storage::Bucket", props: { metadata: { name: "data-bucket", namespace: "config-control" } } },
+    ]);
+
+    const result = await describeResources({ environment: "prod", buildOutput: "", entityNames: ["dataBucket"], entities });
+
+    // Resource name follows: <lowerKind>.<service>.cnrm.cloud.google.com
+    expect(receivedCmd).toContain("storagebucket.storage.cnrm.cloud.google.com");
+    expect(receivedCmd).toContain("data-bucket");
+    expect(receivedCmd).toContain("-n config-control");
+
+    expect(result["dataBucket"]).toMatchObject({
+      type: "GCP::Storage::Bucket",
+      physicalId: "uid-1",
+      status: "READY",
+    });
+  });
+
+  test("Compute resource derives correct GVK with service prefix", async () => {
+    let receivedCmd = "";
+    execMock.mockImplementation((cmd: string) => {
+      receivedCmd = cmd;
+      return {
+        stdout: JSON.stringify({
+          metadata: { name: "subnet-1", uid: "uid", creationTimestamp: "t" },
+          status: { conditions: [{ type: "Ready", status: "True" }] },
+        }),
+        stderr: "",
+      };
+    });
+
+    const entities = makeEntities([
+      { name: "sub", entityType: "GCP::Compute::Subnetwork", props: { metadata: { name: "subnet-1" } } },
+    ]);
+
+    await describeResources({ environment: "prod", buildOutput: "", entityNames: ["sub"], entities });
+
+    expect(receivedCmd).toContain("computesubnetwork.compute.cnrm.cloud.google.com");
+  });
+
+  test("Ready=False maps to the condition's reason", async () => {
+    execMock.mockResolvedValue({
+      stdout: JSON.stringify({
+        metadata: { name: "x", uid: "uid", creationTimestamp: "t" },
+        status: { conditions: [{ type: "Ready", status: "False", reason: "DependencyNotFound", message: "..." }] },
+      }),
+      stderr: "",
+    });
+
+    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["x"].status).toBe("DependencyNotFound");
+  });
+
+  test("missing Ready condition falls back to PRESENT", async () => {
+    execMock.mockResolvedValue({
+      stdout: JSON.stringify({
+        metadata: { name: "x", uid: "uid", creationTimestamp: "t" },
+        status: {},
+      }),
+      stderr: "",
+    });
+
+    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["x"].status).toBe("PRESENT");
+  });
+
+  test("kubectl-not-found leaves entity out of result", async () => {
+    execMock.mockImplementation(() => { throw new Error('Error from server (NotFound): storagebucket "x" not found'); });
+
+    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).toEqual({});
+  });
+
+  test("non-GCP entity types are skipped", 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(execMock).not.toHaveBeenCalled();
+  });
+
+  test("entity without metadata.name is silently skipped", 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(execMock).not.toHaveBeenCalled();
+  });
+});

package/src/describe-resources.ts

@@ -0,0 +1,118 @@
+/**
+ * Live introspection of a GCP project via Config Connector CRDs.
+ *
+ * GCP entities in chant are emitted as Config Connector custom resources
+ * (apiVersion <service>.cnrm.cloud.google.com/v1beta1, kind <Service><Kind>).
+ * To observe them at runtime we shell out to kubectl against a Config
+ * Connector-enabled cluster — the same pattern as the K8s lexicon.
+ *
+ *   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.
+ */
+
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+
+const execAsync = promisify(exec);
+
+interface KubectlResponse {
+  metadata?: {
+    name?: string;
+    namespace?: string;
+    uid?: string;
+    creationTimestamp?: string;
+    labels?: Record<string, string>;
+    annotations?: Record<string, string>;
+  };
+  status?: {
+    conditions?: Array<{ type?: string; status?: string; reason?: string; message?: string }>;
+    [k: string]: unknown;
+  };
+}
+
+/**
+ * Mirror of `lexicons/gcp/src/serializer.ts:deriveGVKFromType` — keeping the
+ * derivation logic local so describeResources can compute the kubectl resource
+ * name without importing serializer internals.
+ */
+function deriveGVK(entityType: string): { group: string; kind: string } | null {
+  const parts = entityType.split("::");
+  if (parts.length !== 3 || parts[0] !== "GCP") return null;
+  const service = parts[1].toLowerCase();
+  const shortKind = parts[2];
+  return {
+    group: `${service}.cnrm.cloud.google.com`,
+    kind: `${parts[1]}${shortKind}`,
+  };
+}
+
+function pruneUndefined<T extends Record<string, unknown>>(obj: T): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Config Connector encodes deployment state as a `Ready` condition on the
+ * resource's status. Fall back to listing all condition types if `Ready`
+ * isn't present.
+ */
+function statusFromCC(obj: KubectlResponse): string {
+  const conditions = obj.status?.conditions ?? [];
+  const ready = conditions.find((c) => c.type === "Ready");
+  if (ready) {
+    if (ready.status === "True") return "READY";
+    return ready.reason ?? "NOT_READY";
+  }
+  if (conditions.length > 0) {
+    return conditions.map((c) => `${c.type}=${c.status}`).join(",");
+  }
+  return "PRESENT";
+}
+
+export async function describeResources(options: {
+  environment: string;
+  buildOutput: string;
+  entityNames: string[];
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+}): Promise<Record<string, ResourceMetadata>> {
+  const result: Record<string, ResourceMetadata> = {};
+
+  for (const [entityName, { entityType, props }] of options.entities) {
+    const gvk = deriveGVK(entityType);
+    if (!gvk) continue;
+
+    const metadata = props.metadata as { name?: string; namespace?: string } | undefined;
+    const name = metadata?.name;
+    if (!name) 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(" ");
+
+    try {
+      const { stdout } = await execAsync(cmd);
+      const obj: KubectlResponse = JSON.parse(stdout);
+      result[entityName] = {
+        type: entityType,
+        physicalId: obj.metadata?.uid,
+        status: statusFromCC(obj),
+        lastUpdated: obj.metadata?.creationTimestamp,
+        attributes: pruneUndefined({
+          namespace: obj.metadata?.namespace,
+          labels: obj.metadata?.labels,
+          annotations: obj.metadata?.annotations,
+        }),
+      };
+    } catch {
+      // CRD or instance not found — skip silently
+    }
+  }
+
+  return result;
+}

package/src/plugin.test.ts

@@ -214,7 +214,7 @@ describe("gcpPlugin", () => {
 
     test("diff tool has correct structure", () => {
       const tools = gcpPlugin.mcpTools!();
-      const diffTool = tools.find((t) => t.name === "diff");
+      const diffTool = tools.find((t) => t.name === "gcp:diff");
       expect(diffTool).toBeDefined();
       expect(diffTool!.description.length).toBeGreaterThan(0);
       expect(diffTool!.inputSchema.type).toBe("object");
@@ -230,7 +230,7 @@ describe("gcpPlugin", () => {
 
     test("resource-catalog has correct structure", () => {
       const resources = gcpPlugin.mcpResources!();
-      const catalog = resources.find((r) => r.uri === "resource-catalog");
+      const catalog = resources.find((r) => r.uri === "gcp:resource-catalog");
       expect(catalog).toBeDefined();
       expect(catalog!.mimeType).toBe("application/json");
       expect(typeof catalog!.handler).toBe("function");

package/src/plugin.ts

@@ -326,12 +326,12 @@ export const bucketReader = new IAMPolicyMember({
   },
 
   mcpTools() {
-    return [createDiffTool(gcpSerializer, "Compare current build output against previous output for GCP Config Connector manifests")];
+    return [createDiffTool(gcpSerializer, "Compare current build output against previous output for GCP Config Connector manifests", "gcp")];
   },
 
   mcpResources() {
     return [
-      createCatalogResource(import.meta.url, "GCP Config Connector Resource Catalog", "JSON list of all supported GCP Config Connector resource types", "lexicon-gcp.json"),
+      createCatalogResource(import.meta.url, "GCP Config Connector Resource Catalog", "JSON list of all supported GCP Config Connector resource types", "lexicon-gcp.json", "gcp"),
       {
         uri: "examples/basic-bucket",
         name: "Basic GCS Bucket Example",
@@ -499,4 +499,9 @@ export const bucket = new StorageBucket({
     const { generateDocs } = await import("./codegen/docs");
     await generateDocs(options);
   },
+
+  async describeResources(options) {
+    const { describeResources } = await import("./describe-resources");
+    return describeResources(options);
+  },
 };