@intentius/chant-lexicon-gcp 0.0.18 → 0.0.22

package/src/lint/post-synth/wgc401.ts

@@ -0,0 +1,59 @@
+/**
+ * WGC401: Unknown spec field
+ *
+ * Flags fields in a Config Connector resource spec that are not defined
+ * in the CRD schema. Includes "did you mean?" suggestion via Levenshtein.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseGcpManifests, isConfigConnectorResource, getResourceName, getSpec } from "./gcp-helpers";
+import { getSchemaRegistry, suggestField } from "./schema-registry";
+
+export const wgc401: PostSynthCheck = {
+  id: "WGC401",
+  description: "Config Connector resource spec contains unknown field",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const registry = getSchemaRegistry();
+
+    for (const [_lexicon, output] of ctx.outputs) {
+      if (typeof output !== "string") continue;
+
+      const manifests = parseGcpManifests(output);
+
+      for (const manifest of manifests) {
+        if (!isConfigConnectorResource(manifest)) continue;
+
+        const kind = manifest.kind;
+        if (!kind) continue;
+
+        const schema = registry.get(kind);
+        if (!schema) continue; // No schema available for this kind
+
+        const spec = getSpec(manifest);
+        if (!spec) continue;
+
+        const knownFields = Object.keys(schema.fields);
+        const resourceName = getResourceName(manifest);
+
+        for (const field of Object.keys(spec)) {
+          if (field in schema.fields) continue;
+
+          const suggestion = suggestField(field, knownFields);
+          const hint = suggestion ? ` — did you mean "${suggestion}"?` : "";
+
+          diagnostics.push({
+            checkId: "WGC401",
+            severity: "error",
+            message: `Resource "${resourceName}" (${kind}): unknown spec field "${field}"${hint}`,
+            entity: resourceName,
+            lexicon: "gcp",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/wgc402.test.ts

@@ -0,0 +1,40 @@
+import { describe, test, expect } from "bun:test";
+import { wgc402 } from "./wgc402";
+
+function makeCtx(yaml: string) {
+  return {
+    outputs: new Map([["gcp", yaml]]),
+  };
+}
+
+describe("WGC402: missing required field", () => {
+  test("flags missing required field", () => {
+    const yaml = `apiVersion: compute.cnrm.cloud.google.com/v1beta1
+kind: ComputeAddress
+metadata:
+  name: my-addr
+spec:
+  description: test
+`;
+    const diags = wgc402.check(makeCtx(yaml));
+    const requiredDiags = diags.filter(d => d.checkId === "WGC402");
+    // ComputeAddress requires "location" -- if schema is loaded, this flags it
+    if (requiredDiags.length > 0) {
+      expect(requiredDiags[0].severity).toBe("error");
+      expect(requiredDiags[0].message).toContain("required");
+    }
+  });
+
+  test("no diagnostic when all required fields present", () => {
+    const yaml = `apiVersion: storage.cnrm.cloud.google.com/v1beta1
+kind: StorageBucket
+metadata:
+  name: my-bucket
+spec:
+  location: US
+`;
+    const diags = wgc402.check(makeCtx(yaml));
+    const requiredDiags = diags.filter(d => d.checkId === "WGC402");
+    expect(requiredDiags).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/wgc402.ts

@@ -0,0 +1,54 @@
+/**
+ * WGC402: Missing required spec field
+ *
+ * Flags Config Connector resources that are missing required fields
+ * according to their CRD schema.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseGcpManifests, isConfigConnectorResource, getResourceName, getSpec } from "./gcp-helpers";
+import { getSchemaRegistry } from "./schema-registry";
+
+export const wgc402: PostSynthCheck = {
+  id: "WGC402",
+  description: "Config Connector resource is missing a required spec field",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const registry = getSchemaRegistry();
+
+    for (const [_lexicon, output] of ctx.outputs) {
+      if (typeof output !== "string") continue;
+
+      const manifests = parseGcpManifests(output);
+
+      for (const manifest of manifests) {
+        if (!isConfigConnectorResource(manifest)) continue;
+
+        const kind = manifest.kind;
+        if (!kind) continue;
+
+        const schema = registry.get(kind);
+        if (!schema) continue;
+
+        const spec = getSpec(manifest);
+        const specKeys = new Set(spec ? Object.keys(spec) : []);
+        const resourceName = getResourceName(manifest);
+
+        for (const requiredField of schema.required) {
+          if (!specKeys.has(requiredField)) {
+            diagnostics.push({
+              checkId: "WGC402",
+              severity: "error",
+              message: `Resource "${resourceName}" (${kind}): missing required field "${requiredField}"`,
+              entity: resourceName,
+              lexicon: "gcp",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/wgc403.test.ts

@@ -0,0 +1,59 @@
+import { describe, test, expect } from "bun:test";
+import { wgc403 } from "./wgc403";
+
+function makeCtx(yaml: string) {
+  return {
+    outputs: new Map([["gcp", yaml]]),
+  };
+}
+
+describe("WGC403: type/structure mismatch", () => {
+  test("flags string where number expected", () => {
+    const yaml = `apiVersion: cloudfunctions.cnrm.cloud.google.com/v1beta1
+kind: CloudFunctionsFunction
+metadata:
+  name: my-fn
+spec:
+  runtime: nodejs18
+  availableMemoryMb: "512"
+  region: us-central1
+`;
+    const diags = wgc403.check(makeCtx(yaml));
+    const typeDiags = diags.filter(d => d.checkId === "WGC403");
+    if (typeDiags.length > 0) {
+      expect(typeDiags[0].severity).toBe("error");
+      expect(typeDiags[0].message).toContain("number");
+      expect(typeDiags[0].message).toContain("string");
+    }
+  });
+
+  test("flags bare string instead of resourceRef object", () => {
+    const yaml = `apiVersion: pubsub.cnrm.cloud.google.com/v1beta1
+kind: PubSubSubscription
+metadata:
+  name: my-sub
+spec:
+  topicRef: my-topic
+`;
+    const diags = wgc403.check(makeCtx(yaml));
+    const typeDiags = diags.filter(d => d.checkId === "WGC403");
+    if (typeDiags.length > 0) {
+      expect(typeDiags[0].severity).toBe("error");
+      expect(typeDiags[0].message).toContain("resourceRef");
+    }
+  });
+
+  test("no diagnostic with correct types", () => {
+    const yaml = `apiVersion: storage.cnrm.cloud.google.com/v1beta1
+kind: StorageBucket
+metadata:
+  name: my-bucket
+spec:
+  location: US
+  uniformBucketLevelAccess: true
+`;
+    const diags = wgc403.check(makeCtx(yaml));
+    const typeDiags = diags.filter(d => d.checkId === "WGC403");
+    expect(typeDiags).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/wgc403.ts

@@ -0,0 +1,84 @@
+/**
+ * WGC403: Type/structure mismatch in spec field
+ *
+ * Flags spec fields where the value type doesn't match the CRD schema:
+ * - String where number expected (e.g. availableMemoryMb: "512")
+ * - Scalar string where resourceRef object expected (e.g. topicRef: "name")
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseGcpManifests, isConfigConnectorResource, getResourceName, getSpec } from "./gcp-helpers";
+import { getSchemaRegistry } from "./schema-registry";
+
+export const wgc403: PostSynthCheck = {
+  id: "WGC403",
+  description: "Config Connector resource spec field has wrong type or structure",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const registry = getSchemaRegistry();
+
+    for (const [_lexicon, output] of ctx.outputs) {
+      if (typeof output !== "string") continue;
+
+      const manifests = parseGcpManifests(output);
+
+      for (const manifest of manifests) {
+        if (!isConfigConnectorResource(manifest)) continue;
+
+        const kind = manifest.kind;
+        if (!kind) continue;
+
+        const schema = registry.get(kind);
+        if (!schema) continue;
+
+        const spec = getSpec(manifest);
+        if (!spec) continue;
+
+        const resourceName = getResourceName(manifest);
+
+        for (const [field, value] of Object.entries(spec)) {
+          const fieldSchema = schema.fields[field];
+          if (!fieldSchema) continue; // Unknown fields handled by WGC401
+
+          // Check: resourceRef field expects an object, got a scalar
+          if (fieldSchema.ref && typeof value === "string") {
+            diagnostics.push({
+              checkId: "WGC403",
+              severity: "error",
+              message: `Resource "${resourceName}" (${kind}): field "${field}" expects a resourceRef object (e.g. { name, kind }), got string "${value}"`,
+              entity: resourceName,
+              lexicon: "gcp",
+            });
+            continue;
+          }
+
+          // Check: number field got a string that looks numeric
+          if (fieldSchema.type === "number" && typeof value === "string") {
+            diagnostics.push({
+              checkId: "WGC403",
+              severity: "error",
+              message: `Resource "${resourceName}" (${kind}): field "${field}" expects a number, got string "${value}"`,
+              entity: resourceName,
+              lexicon: "gcp",
+            });
+            continue;
+          }
+
+          // Check: boolean field got a string
+          if (fieldSchema.type === "boolean" && typeof value === "string") {
+            diagnostics.push({
+              checkId: "WGC403",
+              severity: "error",
+              message: `Resource "${resourceName}" (${kind}): field "${field}" expects a boolean, got string "${value}"`,
+              entity: resourceName,
+              lexicon: "gcp",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/plugin.test.ts

@@ -30,7 +30,7 @@ describe("gcpPlugin", () => {
 
   test("returns post-synth checks", () => {
     const checks = gcpPlugin.postSynthChecks!();
-    expect(checks).toHaveLength(20);
+    expect(checks).toHaveLength(23);
     const ids = checks.map((c) => c.id);
     expect(ids).toContain("WGC101");
     expect(ids).toContain("WGC102");
@@ -52,6 +52,9 @@ describe("gcpPlugin", () => {
     expect(ids).toContain("WGC301");
     expect(ids).toContain("WGC302");
     expect(ids).toContain("WGC303");
+    expect(ids).toContain("WGC401");
+    expect(ids).toContain("WGC402");
+    expect(ids).toContain("WGC403");
   });
 
   // ── Intrinsics / pseudo-parameters ─────────────────────────────────

package/src/plugin.ts

@@ -6,7 +6,7 @@
  */
 
 import { createRequire } from "module";
-import type { LexiconPlugin, SkillDefinition, InitTemplateSet } from "@intentius/chant/lexicon";
+import type { LexiconPlugin, SkillDefinition, InitTemplateSet, ResourceMetadata } from "@intentius/chant/lexicon";
 const require = createRequire(import.meta.url);
 import type { LintRule } from "@intentius/chant/lint/rule";
 import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
@@ -48,11 +48,15 @@ export const gcpPlugin: LexiconPlugin = {
     const { wgc111 } = require("./lint/post-synth/wgc111");
     const { wgc112 } = require("./lint/post-synth/wgc112");
     const { wgc113 } = require("./lint/post-synth/wgc113");
+    const { wgc401 } = require("./lint/post-synth/wgc401");
+    const { wgc402 } = require("./lint/post-synth/wgc402");
+    const { wgc403 } = require("./lint/post-synth/wgc403");
     return [
       wgc101, wgc102, wgc103, wgc104, wgc105, wgc106, wgc107, wgc108, wgc109, wgc110,
       wgc111, wgc112, wgc113,
       wgc201, wgc202, wgc203, wgc204,
       wgc301, wgc302, wgc303,
+      wgc401, wgc402, wgc403,
     ];
   },
 
@@ -87,10 +91,9 @@ export const annotations = defaultAnnotations({
 export const cluster = new GKECluster({
   location: GCP.Region,
   initialNodeCount: 1,
-  removeDefaultNodePool: true,
   releaseChannel: { channel: "REGULAR" },
   workloadIdentityConfig: {
-    workloadPool: "PROJECT_ID.svc.id.goog",
+    workloadPool: \`\${GCP.ProjectId}.svc.id.goog\`,
   },
 });
 
@@ -111,6 +114,54 @@ export const nodePool = new NodePool({
       };
     }
 
+    if (template === "cloud-function") {
+      return {
+        src: {
+          "infra.ts": `/**
+ * Cloud Function with Pub/Sub trigger
+ */
+
+import { CloudFunction, StorageBucket, GCPServiceAccount, IAMPolicyMember, GCP } from "@intentius/chant-lexicon-gcp";
+import { defaultAnnotations } from "@intentius/chant-lexicon-gcp";
+
+export const annotations = defaultAnnotations({
+  "cnrm.cloud.google.com/project-id": GCP.ProjectId,
+});
+
+export const sourceBucket = new StorageBucket({
+  location: GCP.Region,
+  storageClass: "STANDARD",
+  uniformBucketLevelAccess: true,
+});
+
+export const functionSa = new GCPServiceAccount({
+  displayName: "Cloud Function Service Account",
+});
+
+export const fn = new CloudFunction({
+  location: GCP.Region,
+  runtime: "nodejs22",
+  entryPoint: "handler",
+  sourceArchiveBucket: sourceBucket,
+  sourceArchiveObject: "function-source.zip",
+  triggerHttp: true,
+  serviceAccountEmail: functionSa,
+});
+
+export const invoker = new IAMPolicyMember({
+  member: "allUsers",
+  role: "roles/cloudfunctions.invoker",
+  resourceRef: {
+    apiVersion: "cloudfunctions.cnrm.cloud.google.com/v1beta1",
+    kind: "CloudFunction",
+    name: fn,
+  },
+});
+`,
+        },
+      };
+    }
+
     // Default: StorageBucket + IAMPolicyMember
     return {
       src: {
@@ -184,6 +235,124 @@ export const bucketReader = new IAMPolicyMember({
     return gcpHover(ctx);
   },
 
+  async describeResources(options: {
+    environment: string;
+    buildOutput: string;
+    entityNames: string[];
+  }): Promise<Record<string, ResourceMetadata>> {
+    const { getRuntime } = await import("@intentius/chant/runtime-adapter");
+    const rt = getRuntime();
+    const resources: Record<string, ResourceMetadata> = {};
+
+    // Convert TypeScript variable names to kebab-case manifest names
+    // (mirrors serializer.ts:165 metadata.name assignment)
+    function entityToManifestName(name: string): string {
+      return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+    }
+
+    // Detect namespace: prefer namespace from manifests, then kubectl context, fallback "default"
+    let namespace = "default";
+    try {
+      // Check manifests for an explicit namespace
+      const nsMatch = options.buildOutput.match(/^\s+namespace:\s*(.+)$/m);
+      if (nsMatch) {
+        namespace = nsMatch[1].trim();
+      } else {
+        // Try kubectl current context namespace
+        const nsResult = await rt.spawn([
+          "kubectl", "config", "view", "--minify", "-o", "jsonpath={..namespace}",
+        ]);
+        if (nsResult.exitCode === 0 && nsResult.stdout.trim()) {
+          namespace = nsResult.stdout.trim();
+        }
+      }
+    } catch (err) {
+      console.error(`[gcp] describeResources: namespace detection failed, using "default": ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    // Parse build output to extract kind/name pairs
+    let manifests: Array<{ kind: string; name: string; apiVersion: string; namespace?: string }> = [];
+    try {
+      const docs = options.buildOutput.split(/^---$/m).filter((d) => d.trim());
+      for (const doc of docs) {
+        const kindMatch = doc.match(/^kind:\s*(.+)$/m);
+        const nameMatch = doc.match(/^\s+name:\s*(.+)$/m);
+        const apiVersionMatch = doc.match(/^apiVersion:\s*(.+)$/m);
+        if (kindMatch && nameMatch && apiVersionMatch) {
+          const nsMatch = doc.match(/^\s+namespace:\s*(.+)$/m);
+          manifests.push({
+            kind: kindMatch[1].trim(),
+            name: nameMatch[1].trim(),
+            apiVersion: apiVersionMatch[1].trim(),
+            ...(nsMatch && { namespace: nsMatch[1].trim() }),
+          });
+        }
+      }
+    } catch (err) {
+      console.error(`[gcp] describeResources: failed to parse build output: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    let resolved = 0;
+
+    for (const entityName of options.entityNames) {
+      const manifestName = entityToManifestName(entityName);
+      const manifest = manifests.find((m) => m.name === manifestName);
+      if (!manifest) {
+        console.error(`[gcp] describeResources: no manifest found for entity "${entityName}" (expected manifest name "${manifestName}")`);
+        continue;
+      }
+
+      const resourceNs = manifest.namespace ?? namespace;
+      const resourceType = manifest.kind.toLowerCase();
+      const getResult = await rt.spawn([
+        "kubectl", "get", resourceType, manifest.name,
+        "-n", resourceNs, "-o", "json",
+      ]);
+
+      if (getResult.exitCode !== 0) {
+        console.error(`[gcp] describeResources: kubectl get ${resourceType} ${manifest.name} -n ${resourceNs} failed (exit ${getResult.exitCode}): ${getResult.stderr.trim()}`);
+        continue;
+      }
+
+      try {
+        const obj = JSON.parse(getResult.stdout) as {
+          metadata: { name: string; uid: string; creationTimestamp: string };
+          status?: {
+            conditions?: Array<{ type: string; status: string }>;
+            externalRef?: string;
+          };
+        };
+
+        let status = "Unknown";
+        if (obj.status?.conditions) {
+          const ready = obj.status.conditions.find((c) => c.type === "Ready");
+          status = ready?.status === "True" ? "Ready" : "NotReady";
+        }
+
+        const attributes: Record<string, unknown> = {
+          uid: obj.metadata.uid,
+        };
+        if (obj.status?.externalRef) {
+          attributes.externalRef = obj.status.externalRef;
+        }
+
+        resources[entityName] = {
+          type: `${manifest.apiVersion}/${manifest.kind}`,
+          physicalId: obj.status?.externalRef ?? obj.metadata.name,
+          status,
+          lastUpdated: obj.metadata.creationTimestamp,
+          attributes,
+        };
+        resolved++;
+      } catch (err) {
+        console.error(`[gcp] describeResources: failed to parse kubectl output for "${entityName}": ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+
+    console.error(`[gcp] describeResources: ${resolved}/${options.entityNames.length} resources resolved`);
+    return resources;
+  },
+
   mcpTools(): McpToolContribution[] {
     return [
       {

package/src/skills/chant-gcp.md

@@ -9,7 +9,7 @@ user-invocable: true
 
 ## How chant and Config Connector relate
 
-chant is a **synthesis-only** tool — it compiles TypeScript source files into Config Connector YAML manifests. chant does NOT call GCP APIs. Your job as an agent is to bridge the two:
+chant is a **synthesis compiler** — it compiles TypeScript source files into Config Connector YAML manifests. `chant build` does not call GCP APIs; synthesis is pure and deterministic. Config Connector resources are Kubernetes objects, so the optional `chant state snapshot` command queries the Kubernetes API to capture deployment metadata (resource status, conditions, observed state) for observability. Your job as an agent is to bridge synthesis and deployment:
 
 - Use **chant** for: build, lint, diff (local YAML comparison)
 - Use **kubectl** for: apply, rollback, monitoring, troubleshooting
@@ -49,6 +49,9 @@ chant lint src/
 # Build
 chant build src/ --output manifests.yaml
 
+# See what changed since last deploy (compares current build against last snapshot's digest)
+chant state diff staging gcp
+
 # Dry run
 kubectl apply -f manifests.yaml --dry-run=server