@intentius/chant-lexicon-gcp 0.0.15

package/src/skills/chant-gcp.md

@@ -0,0 +1,108 @@
+---
+skill: chant-gcp
+description: Build, validate, and deploy GCP Config Connector manifests from a chant project
+source: chant-lexicon
+user-invocable: true
+---
+
+# GCP Config Connector Operational Playbook
+
+## 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:
+
+- Use **chant** for: build, lint, diff (local YAML comparison)
+- Use **kubectl** for: apply, rollback, monitoring, troubleshooting
+
+The source of truth for infrastructure is the TypeScript in `src/`. The generated YAML manifests are intermediate artifacts.
+
+## Prerequisites
+
+1. A GKE cluster with Config Connector installed
+2. A ConfigConnectorContext resource per namespace
+3. A GCP Service Account with appropriate IAM roles
+
+## Build and validate
+
+### Build manifests
+
+```bash
+chant build src/ --output manifests.yaml
+```
+
+### Lint the source
+
+```bash
+chant lint src/
+```
+
+### What each step catches
+
+| Step | Catches | When to run |
+|------|---------|-------------|
+| `chant lint` | Hardcoded project IDs (WGC001), regions (WGC002), public IAM (WGC003) | Every edit |
+| `chant build` | Post-synth: missing encryption (WGC101), public IAM in output (WGC102), missing project annotation (WGC103) | Before apply |
+
+## Applying to Kubernetes
+
+```bash
+# Build
+chant build src/ --output manifests.yaml
+
+# Dry run
+kubectl apply -f manifests.yaml --dry-run=server
+
+# Apply
+kubectl apply -f manifests.yaml
+```
+
+## Resource reference patterns
+
+Config Connector resources reference each other using `resourceRef`:
+
+```yaml
+# By name (same namespace)
+resourceRef:
+  name: my-network
+
+# By external reference (cross-project)
+resourceRef:
+  external: projects/my-project/global/networks/my-network
+```
+
+## Project binding
+
+Bind resources to a GCP project via annotations:
+
+```yaml
+metadata:
+  annotations:
+    cnrm.cloud.google.com/project-id: my-project
+```
+
+Or use defaultAnnotations in chant:
+
+```typescript
+export const annotations = defaultAnnotations({
+  "cnrm.cloud.google.com/project-id": GCP.ProjectId,
+});
+```
+
+## Troubleshooting
+
+| Status | Meaning | Fix |
+|--------|---------|-----|
+| UpToDate | Resource is in sync | None needed |
+| UpdateFailed | GCP API error | Check `kubectl describe` events |
+| DependencyNotReady | Waiting for referenced resource | Ensure dependency exists |
+| DeletionFailed | Cannot delete GCP resource | Check IAM permissions |
+
+## Quick reference
+
+| Command | Description |
+|---------|-------------|
+| `chant build src/` | Synthesize manifests |
+| `chant lint src/` | Check for anti-patterns |
+| `kubectl apply -f manifests.yaml` | Apply to cluster |
+| `kubectl get gcp` | List all Config Connector resources |
+| `kubectl describe <resource>` | Check reconciliation status |

package/src/spec/fetch.test.ts

@@ -0,0 +1,16 @@
+import { describe, test, expect } from "bun:test";
+import { getCachePath, KCC_VERSION } from "./fetch";
+
+describe("fetch", () => {
+  test("cache path includes version", () => {
+    const path = getCachePath();
+    expect(path).toContain(KCC_VERSION);
+    expect(path).toContain(".chant");
+    expect(path).toEndWith(".tar.gz");
+  });
+
+  test("custom version in cache path", () => {
+    const path = getCachePath("v1.120.0");
+    expect(path).toContain("v1.120.0");
+  });
+});

package/src/spec/fetch.ts

@@ -0,0 +1,121 @@
+/**
+ * Schema fetching — downloads Config Connector CRD bundle from GitHub releases.
+ *
+ * Uses the release bundle tar.gz, filtering for CRD YAML files.
+ */
+
+import { homedir } from "os";
+import { join } from "path";
+import { fetchWithCache, clearCacheFile } from "@intentius/chant/codegen/fetch";
+
+/**
+ * Pinned Config Connector version for reproducible codegen.
+ */
+export const KCC_VERSION = "v1.145.0";
+
+const CACHE_DIR = join(homedir(), ".chant");
+
+function bundleUrl(version: string): string {
+  // The release-bundle.tar.gz asset is no longer published.
+  // Use GitHub's auto-generated source tarball instead — CRDs are at config/crds/resources/.
+  return `https://github.com/GoogleCloudPlatform/k8s-config-connector/archive/refs/tags/${version}.tar.gz`;
+}
+
+function cacheFile(version: string): string {
+  return join(CACHE_DIR, `kcc-crds-${version}.tar.gz`);
+}
+
+/**
+ * Fetch the Config Connector CRD bundle and extract CRD YAML files.
+ *
+ * Returns a Map keyed by CRD filename (e.g., "computeinstance.yaml") with
+ * the raw YAML content as a Buffer.
+ */
+export async function fetchCRDBundle(
+  force = false,
+  version: string = KCC_VERSION,
+): Promise<Map<string, Buffer>> {
+  const url = bundleUrl(version);
+  const cache = cacheFile(version);
+
+  const tarData = await fetchWithCache({ url, cacheFile: cache }, force);
+  return extractCRDs(tarData);
+}
+
+/**
+ * Extract CRD YAML files from a tar.gz bundle.
+ *
+ * Filters for entries under a crds/ directory or standalone CRD YAML files.
+ */
+async function extractCRDs(tarData: Buffer): Promise<Map<string, Buffer>> {
+  const { gunzipSync } = await import("fflate");
+  const crds = new Map<string, Buffer>();
+
+  // Decompress gzip synchronously (avoids lingering event loop references)
+  const gunzipped = gunzipSync(new Uint8Array(tarData));
+
+  // Parse tar (512-byte header blocks) with PAX extended header support.
+  // GitHub source tarballs use PAX headers (type 'x') for long filenames.
+  let offset = 0;
+  const data = gunzipped;
+  let paxPath: string | null = null;
+
+  while (offset < data.length - 512) {
+    const header = data.slice(offset, offset + 512);
+    offset += 512;
+
+    if (header.every((b) => b === 0)) break;
+
+    // Extract filename: ustar prefix (bytes 345-499) + name (bytes 0-99)
+    const nameBytes = header.slice(0, 100);
+    const nameEnd = nameBytes.indexOf(0);
+    let name = new TextDecoder().decode(nameBytes.slice(0, nameEnd > 0 ? nameEnd : 100)).trim();
+    const prefixBytes = header.slice(345, 500);
+    const prefixEnd = prefixBytes.indexOf(0);
+    const ustarPrefix = new TextDecoder().decode(prefixBytes.slice(0, prefixEnd > 0 ? prefixEnd : 155)).trim();
+    if (ustarPrefix) name = `${ustarPrefix}/${name}`;
+
+    const sizeStr = new TextDecoder().decode(header.slice(124, 136)).trim().replace(/\0/g, "");
+    const size = parseInt(sizeStr, 8) || 0;
+    const typeFlag = header[156];
+    const typeFlagChar = String.fromCharCode(typeFlag);
+
+    const blocks = Math.ceil(size / 512);
+    const fileData = data.slice(offset, offset + size);
+    offset += blocks * 512;
+
+    // PAX extended header — extract path= for the next entry
+    if (typeFlagChar === "x") {
+      const paxStr = new TextDecoder().decode(fileData);
+      const match = paxStr.match(/\bpath=([^\n]+)/);
+      if (match) paxPath = match[1];
+      continue;
+    }
+
+    // Use PAX path if available, then reset
+    if (paxPath) {
+      name = paxPath;
+      paxPath = null;
+    }
+
+    // Only process regular files
+    if (typeFlag !== 48 && typeFlag !== 0) continue;
+    if (size === 0) continue;
+
+    // Match CRD YAML files — source tarball has them at config/crds/resources/
+    if (name.includes("config/crds/resources/") && name.endsWith(".yaml")) {
+      const basename = name.split("/").pop() || name;
+      crds.set(basename, Buffer.from(fileData));
+    }
+  }
+
+  return crds;
+}
+
+export function getCachePath(version: string = KCC_VERSION): string {
+  return cacheFile(version);
+}
+
+export function clearCache(version: string = KCC_VERSION): void {
+  clearCacheFile(cacheFile(version));
+}

package/src/spec/parse.test.ts

@@ -0,0 +1,163 @@
+import { describe, test, expect } from "bun:test";
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import {
+  parseGcpCRD,
+  gcpServiceName,
+  stripServicePrefix,
+  gcpTypeName,
+  gcpShortName,
+} from "./parse";
+
+const __dirname_ = dirname(fileURLToPath(import.meta.url));
+const testdata = join(__dirname_, "..", "testdata");
+
+describe("gcpServiceName", () => {
+  test("extracts service from CNRM group", () => {
+    expect(gcpServiceName("compute.cnrm.cloud.google.com")).toBe("Compute");
+    expect(gcpServiceName("storage.cnrm.cloud.google.com")).toBe("Storage");
+    expect(gcpServiceName("iam.cnrm.cloud.google.com")).toBe("Iam");
+    expect(gcpServiceName("container.cnrm.cloud.google.com")).toBe("Container");
+    expect(gcpServiceName("sql.cnrm.cloud.google.com")).toBe("Sql");
+  });
+});
+
+describe("stripServicePrefix", () => {
+  test("strips known prefix", () => {
+    expect(stripServicePrefix("ComputeInstance", "Compute")).toBe("Instance");
+    expect(stripServicePrefix("StorageBucket", "Storage")).toBe("Bucket");
+    expect(stripServicePrefix("IAMPolicyMember", "IAM")).toBe("PolicyMember");
+  });
+
+  test("returns kind if no prefix match", () => {
+    expect(stripServicePrefix("VPCNetwork", "Compute")).toBe("VPCNetwork");
+  });
+});
+
+describe("gcpTypeName", () => {
+  test("builds full type name", () => {
+    expect(gcpTypeName("compute.cnrm.cloud.google.com", "ComputeInstance")).toBe("GCP::Compute::Instance");
+    expect(gcpTypeName("storage.cnrm.cloud.google.com", "StorageBucket")).toBe("GCP::Storage::Bucket");
+  });
+});
+
+describe("gcpShortName", () => {
+  test("extracts short name", () => {
+    expect(gcpShortName("GCP::Compute::Instance")).toBe("Instance");
+    expect(gcpShortName("GCP::Storage::Bucket")).toBe("Bucket");
+  });
+});
+
+describe("parseGcpCRD", () => {
+  test("parses ComputeInstance CRD", () => {
+    const content = readFileSync(join(testdata, "compute-instance.yaml"), "utf-8");
+    const results = parseGcpCRD(content);
+
+    expect(results).toHaveLength(1);
+    const result = results[0];
+
+    expect(result.resource.typeName).toBe("GCP::Compute::Instance");
+    expect(result.gvk.group).toBe("compute.cnrm.cloud.google.com");
+    expect(result.gvk.version).toBe("v1beta1");
+    expect(result.gvk.kind).toBe("ComputeInstance");
+
+    // Check properties
+    const propNames = result.resource.properties.map((p) => p.name);
+    expect(propNames).toContain("machineType");
+    expect(propNames).toContain("zone");
+    expect(propNames).toContain("canIpForward");
+    expect(propNames).toContain("tags");
+
+    // Check required
+    const machineType = result.resource.properties.find((p) => p.name === "machineType")!;
+    expect(machineType.required).toBe(true);
+    expect(machineType.tsType).toBe("string");
+
+    // Check resourceRef detection
+    const netRef = result.resource.properties.find((p) => p.name === "networkInterfaceRef");
+    expect(netRef).toBeDefined();
+    expect(netRef!.isResourceRef).toBe(true);
+
+    // Check attributes
+    expect(result.resource.attributes).toHaveLength(3);
+    expect(result.resource.attributes[0].name).toBe("name");
+  });
+
+  test("parses StorageBucket CRD", () => {
+    const content = readFileSync(join(testdata, "storage-bucket.yaml"), "utf-8");
+    const results = parseGcpCRD(content);
+
+    expect(results).toHaveLength(1);
+    const result = results[0];
+
+    expect(result.resource.typeName).toBe("GCP::Storage::Bucket");
+
+    // Check enum
+    const storageClass = result.resource.properties.find((p) => p.name === "storageClass");
+    expect(storageClass).toBeDefined();
+    expect(storageClass!.enum).toContain("STANDARD");
+    expect(storageClass!.enum).toContain("NEARLINE");
+
+    // Check property types (nested objects)
+    expect(result.propertyTypes.length).toBeGreaterThan(0);
+    const versioning = result.propertyTypes.find((pt) => pt.specType === "versioning");
+    expect(versioning).toBeDefined();
+  });
+
+  test("parses IAMPolicyMember CRD", () => {
+    const content = readFileSync(join(testdata, "iam-policy-member.yaml"), "utf-8");
+    const results = parseGcpCRD(content);
+
+    expect(results).toHaveLength(1);
+    const result = results[0];
+
+    expect(result.resource.typeName).toBe("GCP::Iam::PolicyMember");
+
+    // Check required properties
+    const member = result.resource.properties.find((p) => p.name === "member")!;
+    expect(member.required).toBe(true);
+
+    const role = result.resource.properties.find((p) => p.name === "role")!;
+    expect(role.required).toBe(true);
+
+    // resourceRef should be detected
+    const resRef = result.resource.properties.find((p) => p.name === "resourceRef");
+    expect(resRef).toBeDefined();
+    expect(resRef!.isResourceRef).toBe(true);
+  });
+
+  test("handles multi-document CRD bundle", () => {
+    const content = [
+      readFileSync(join(testdata, "compute-instance.yaml"), "utf-8"),
+      readFileSync(join(testdata, "storage-bucket.yaml"), "utf-8"),
+    ].join("\n---\n");
+
+    const results = parseGcpCRD(content);
+    expect(results).toHaveLength(2);
+    expect(results.map((r) => r.resource.typeName)).toContain("GCP::Compute::Instance");
+    expect(results.map((r) => r.resource.typeName)).toContain("GCP::Storage::Bucket");
+  });
+
+  test("skips non-CNRM CRDs", () => {
+    const content = `
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: foo.example.com
+spec:
+  group: example.com
+  names:
+    kind: Foo
+  versions:
+    - name: v1
+      served: true
+      storage: true
+      schema:
+        openAPIV3Schema:
+          type: object
+`;
+    const results = parseGcpCRD(content);
+    expect(results).toHaveLength(0);
+  });
+});