@intentius/chant-lexicon-gcp 0.124.30 → 0.124.32

package/dist/op/builders.js

@@ -0,0 +1,50 @@
+/**
+ * Typed step-builder wrappers for this lexicon's activities (chant #1288
+ * Stage 2). See `lexicons/k8s/src/op/builders.ts`'s module doc for why these
+ * live beside their `*Args` interfaces rather than in core: core cannot
+ * import a lexicon's types, so a wrapper whose `opts` IS the activity's own
+ * `*Args` interface can only sit in the lexicon that declares that
+ * interface. `opts`'s type in each wrapper below IS the activity's own
+ * `*Args` interface (via `Omit`/`WithStepRefs`) — never restated. `core`'s own
+ * `gcpApply`/`gcpDelete`/`flociGcpUp`/`flociGcpDown` are unchanged and
+ * produce byte-identical `ActivityStep` output; these are purely additive.
+ */
+import { activity, takeProfileAndId, } from "@intentius/chant/op";
+/**
+ * Apply built GCP (CNRM) resources directly to their GCP REST APIs — the
+ * fully typed twin of core's `gcpApply`. `opts` is {@link GcpApplyArgs}
+ * itself, minus the positional `manifestPath`. Defaults to the `longInfra`
+ * profile.
+ */
+export const gcpApply = (manifestPath, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("gcpApply", { manifestPath, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+/**
+ * Delete the GCP (CNRM) resources in a built manifest — the inverse of
+ * {@link gcpApply}, fully typed twin of core's `gcpDelete`. `opts` is
+ * {@link GcpApplyArgs} itself (the activity reuses it), minus the positional
+ * `manifestPath`. Defaults to the `longInfra` profile.
+ */
+export const gcpDelete = (manifestPath, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("gcpDelete", { manifestPath, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+/**
+ * Boot a local floci-gcp (GCP emulator) — the fully typed twin of core's
+ * `flociGcpUp`. `opts` is {@link FlociGcpUpArgs} itself. Defaults to the
+ * `longInfra` profile.
+ */
+export const flociGcpUp = (opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("flociGcpUp", args, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+/**
+ * Stop and remove the local floci-gcp container — the fully typed twin of
+ * core's `flociGcpDown`. `opts` is {@link FlociGcpDownArgs} itself. Defaults
+ * to the `fastIdempotent` profile.
+ */
+export const flociGcpDown = (opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("flociGcpDown", args, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};

package/dist/ownership.js

@@ -0,0 +1,38 @@
+/**
+ * GCP's ownership marker channels (#1446).
+ *
+ * The gcp lexicon marks ownership on **two different surfaces**, and they
+ * legitimately use different key vocabularies:
+ *
+ * 1. **The Config Connector object** — what the serializer emits. Its
+ *    `metadata.labels` are Kubernetes labels, so it uses core's shared
+ *    `LABEL_OWNERSHIP_KEYS` (`app.kubernetes.io/managed-by`). That is the key
+ *    `plugin.ts` registers as the lexicon's `ownershipChannel` and the one the
+ *    read paths resolve through.
+ *
+ * 2. **The GCP resource itself** — what `gcpApply` PUTs to the REST API. GCP
+ *    label keys may not contain `/` or `.`, so `app.kubernetes.io/managed-by`
+ *    is not a legal key there. Hence {@link GCP_RESOURCE_OWNERSHIP_KEYS}.
+ *
+ * This is worth stating because the split looks like the bug #1446 found in the
+ * azure applier, and is not. Azure's serializer and applier both write ARM tags
+ * — one surface, and they had drifted onto two keys for no reason. Here the two
+ * surfaces are real and each key is the only legal one for its target.
+ *
+ * What #1446 changes is that the applier's predicate resolves through core's
+ * `hasOwnershipMarker` against a declared channel, rather than comparing a
+ * string literal inline. The key does not move; the drift risk does.
+ */
+/**
+ * Ownership keys for labels on a live GCP resource — the surface `gcpApply`
+ * writes and `pruneOrphans` reads.
+ *
+ * GCP label keys are lowercase alphanumerics, `-` and `_` only, so this is the
+ * GCP-valid equivalent of core's label convention rather than that convention
+ * itself.
+ */
+export const GCP_RESOURCE_OWNERSHIP_KEYS = {
+    managedBy: "managed-by",
+    stack: "chant-stack",
+    env: "chant-env",
+};

package/dist/package-cli.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env tsx
+/**
+ * Thin entry point for `npm run bundle` in lexicon-gcp.
+ * Generates src/generated/ files and writes dist/ bundle.
+ *
+ * NOTE: Uses top-level await (matching AWS/Azure pattern) to avoid
+ * event loop references from async wrappers keeping the process alive.
+ */
+import { packageLexicon } from "./codegen/package.js";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+const pkgDir = dirname(fileURLToPath(import.meta.url));
+const distDir = join(pkgDir, "..", "dist");
+const verbose = process.argv.includes("--verbose") || !process.argv.includes("--quiet");
+const force = process.argv.includes("--force");
+const { spec, stats } = await packageLexicon({ verbose, force });
+writeBundleSpec(spec, distDir);
+console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+console.error(`dist/ written to ${distDir}`);

package/dist/plugin.js

@@ -0,0 +1,371 @@
+/**
+ * GCP Config Connector lexicon plugin.
+ *
+ * Provides serializer, lint rules, template detection,
+ * import parsing, and code generation for GCP Config Connector resources.
+ */
+import { compositeCatalog } from "./composites/catalog.js";
+import { detectTemplate } from "./detect.js";
+import { LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+import { postSynthChecks as postSynthCheckList } from "./lint/post-synth/index.js";
+import { gcpAuditCatalog } from "./lint/audit-catalog.js";
+import { FLOCI_GCP_EMULATOR } from "./op/activities/floci-gcp.js";
+import { createSkillsLoader, createDiffTool, createCatalogResource } from "@intentius/chant/lexicon-plugin-helpers";
+import { gcpSerializer } from "./serializer.js";
+import { hardcodedProjectRule } from "./lint/rules/hardcoded-project.js";
+import { hardcodedRegionRule } from "./lint/rules/hardcoded-region.js";
+import { publicIamRule } from "./lint/rules/public-iam.js";
+import { GcpParser } from "./import/parser.js";
+import { GcpGenerator } from "./import/generator.js";
+import { gcpCompletions } from "./lsp/completions.js";
+import { gcpHover } from "./lsp/hover.js";
+import { gcpDeepNormalizationHooks } from "./deep-observe-hooks.js";
+export const gcpPlugin = {
+    name: "gcp",
+    ownershipChannel: { keys: LABEL_OWNERSHIP_KEYS, reads: ["describeResources", "observeResourcesDeep", "exportResources"] },
+    emulator: FLOCI_GCP_EMULATOR,
+    auditCatalog: () => gcpAuditCatalog,
+    // Self-upgrade: where the pinned Config Connector (KCC) version lives + its upstream (#685).
+    upstreamPin: {
+        file: "src/spec/fetch.ts",
+        pattern: /export const KCC_VERSION\s*=\s*"([^"]+)"/,
+        replace: (v, line) => line.replace(/export const KCC_VERSION\s*=\s*"[^"]+"/, `export const KCC_VERSION = "${v}"`),
+        upstream: { owner: "GoogleCloudPlatform", repo: "k8s-config-connector", kind: "releases" },
+    },
+    serializer: gcpSerializer,
+    lintRules() {
+        return [hardcodedProjectRule, hardcodedRegionRule, publicIamRule];
+    },
+    postSynthChecks() {
+        return postSynthCheckList;
+    },
+    intrinsics() {
+        // Config Connector YAML has no intrinsic template functions
+        return [];
+    },
+    pseudoParameters() {
+        return [
+            "GCP::ProjectId",
+            "GCP::Region",
+            "GCP::Zone",
+        ];
+    },
+    initTemplates(template) {
+        if (template === "gke") {
+            return {
+                src: {
+                    "infra.ts": `/**
+ * GKE Cluster + Node Pool + Workload Identity
+ */
+
+import { GKECluster, NodePool, 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 cluster = new GKECluster({
+  location: GCP.Region,
+  initialNodeCount: 1,
+  releaseChannel: { channel: "REGULAR" },
+  workloadIdentityConfig: {
+    workloadPool: \`\${GCP.ProjectId}.svc.id.goog\`,
+  },
+});
+
+export const nodePool = new NodePool({
+  clusterRef: { name: cluster },
+  initialNodeCount: 2,
+  autoscaling: { minNodeCount: 1, maxNodeCount: 10 },
+  nodeConfig: {
+    machineType: "e2-medium",
+    diskSizeGb: 100,
+    oauthScopes: ["https://www.googleapis.com/auth/cloud-platform"],
+    workloadMetadataConfig: { mode: "GKE_METADATA" },
+  },
+  management: { autoRepair: true, autoUpgrade: true },
+});
+`,
+                },
+            };
+        }
+        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: {
+                "infra.ts": `/**
+ * GCS Bucket with encryption and IAM binding
+ */
+
+import { StorageBucket, 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 dataBucket = new StorageBucket({
+  location: "US",
+  storageClass: "STANDARD",
+  uniformBucketLevelAccess: true,
+  versioning: { enabled: true },
+});
+
+export const bucketReader = new IAMPolicyMember({
+  member: "serviceAccount:my-app@PROJECT_ID.iam.gserviceaccount.com",
+  role: "roles/storage.objectViewer",
+  resourceRef: {
+    apiVersion: "storage.cnrm.cloud.google.com/v1beta1",
+    kind: "StorageBucket",
+    name: dataBucket,
+  },
+});
+`,
+            },
+        };
+    },
+    detectTemplate,
+    templateParser() {
+        return new GcpParser();
+    },
+    templateGenerator() {
+        return new GcpGenerator();
+    },
+    completionProvider(ctx) {
+        return gcpCompletions(ctx);
+    },
+    hoverProvider(ctx) {
+        return gcpHover(ctx);
+    },
+    composites() {
+        return compositeCatalog;
+    },
+    mcpTools() {
+        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", "gcp"),
+            {
+                uri: "examples/basic-bucket",
+                name: "Basic GCS Bucket Example",
+                description: "A GCS bucket with encryption and IAM binding",
+                mimeType: "text/typescript",
+                async handler() {
+                    return `import { StorageBucket, 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 bucket = new StorageBucket({
+  location: "US",
+  storageClass: "STANDARD",
+  uniformBucketLevelAccess: true,
+  versioning: { enabled: true },
+});
+`;
+                },
+            },
+        ];
+    },
+    skills: createSkillsLoader(import.meta.url, [
+        {
+            file: "chant-gcp.md",
+            name: "chant-gcp",
+            description: "Build, validate, and deploy GCP Config Connector manifests from a chant project",
+            triggers: [
+                { type: "file-pattern", value: "*.gcp.ts" },
+                { type: "context", value: "gcp" },
+            ],
+            parameters: [
+                {
+                    name: "resourceType",
+                    type: "string",
+                    description: "GCP Config Connector resource type to work with",
+                },
+            ],
+            examples: [
+                {
+                    title: "Create a Storage Bucket",
+                    output: "new StorageBucket({ location: \"US\", storageClass: \"STANDARD\" })",
+                },
+                {
+                    title: "Create a GKE Cluster",
+                    output: "new GKECluster({ location: GCP.Region, releaseChannel: { channel: \"REGULAR\" } })",
+                },
+            ],
+        },
+        {
+            file: "chant-gcp-security.md",
+            name: "chant-gcp-security",
+            description: "GCP security best practices for infrastructure",
+            triggers: [
+                { type: "context", value: "gcp security" },
+                { type: "context", value: "gcp iam" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Secure Storage Bucket",
+                    input: "Create a storage bucket with encryption and uniform access",
+                    output: "import { GcsBucket } from \"@intentius/chant-lexicon-gcp\";\n\nconst { bucket } = GcsBucket({ name: \"my-bucket\", kmsKeyName: \"...\" });",
+                },
+            ],
+        },
+        {
+            file: "chant-gcp-patterns.md",
+            name: "chant-gcp-patterns",
+            description: "Advanced GCP Config Connector patterns",
+            triggers: [
+                { type: "context", value: "gcp patterns" },
+                { type: "context", value: "gcp composites" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "VPC with Subnets",
+                    input: "Create a VPC network with private subnets",
+                    output: "import { VpcNetwork } from \"@intentius/chant-lexicon-gcp\";\n\nconst { network, subnets } = VpcNetwork({ name: \"my-vpc\", subnets: [...] });",
+                },
+            ],
+        },
+        {
+            file: "chant-gcp-gke.md",
+            name: "chant-gcp-gke",
+            description: "End-to-end GKE workflow bridging GCP infrastructure and Kubernetes workloads",
+            triggers: [
+                { type: "context", value: "gke" },
+                { type: "context", value: "gcp kubernetes" },
+                { type: "context", value: "config connector" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Deploy GKE microservice",
+                    input: "Deploy a GKE project end-to-end",
+                    output: "npm run bootstrap && npm run deploy",
+                },
+            ],
+        },
+    ]),
+    async generate(options) {
+        const { generate, writeGeneratedFiles } = await import("./codegen/generate.js");
+        const { dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const result = await generate({ verbose: options?.verbose ?? true });
+        const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+        writeGeneratedFiles(result, pkgDir);
+        console.error(`Generated ${result.resources} resources, ${result.properties} property types, ${result.enums} enums`);
+        if (result.warnings.length > 0) {
+            console.error(`${result.warnings.length} warnings`);
+        }
+    },
+    async validate(options) {
+        const { validate } = await import("./validate.js");
+        const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+        const result = await validate();
+        printValidationResult(result);
+    },
+    async coverage(options) {
+        const { analyzeGcpCoverage } = await import("./coverage.js");
+        await analyzeGcpCoverage({
+            verbose: options?.verbose,
+            minOverall: options?.minOverall,
+        });
+    },
+    async package(options) {
+        const { packageLexicon } = await import("./codegen/package.js");
+        const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+        const { join, dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const { spec, stats } = await packageLexicon({ verbose: options?.verbose, force: options?.force });
+        const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+        const distDir = join(pkgDir, "dist");
+        writeBundleSpec(spec, distDir);
+        console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+        const { getRuntime } = await import("@intentius/chant/runtime-adapter");
+        const rt = getRuntime();
+        const { stdout: packOut, stderr: packErr, exitCode: packExit } = await rt.spawn(rt.commands.packCmd, { cwd: pkgDir });
+        if (packExit === 0) {
+            console.error(`Tarball: ${packOut.trim()}`);
+        }
+        else {
+            console.error(`${rt.commands.packCmd.join(" ")} failed: ${packErr}`);
+        }
+    },
+    async docs(options) {
+        const { generateDocs } = await import("./codegen/docs.js");
+        await generateDocs(options);
+    },
+    async describeResources(options) {
+        const { describeResources } = await import("./describe-resources.js");
+        return describeResources(options);
+    },
+    async exportResources(options) {
+        const { exportResources } = await import("./export-resources.js");
+        return exportResources(options);
+    },
+    // Property-level live drift via SSA managed-fields (#1087, epic #1073),
+    // reusing the k8s row (#1076) rather than writing a second implementation —
+    // a Config Connector custom resource is a Kubernetes object too. The
+    // reader lives in ./deep-observe.ts, loaded only through this dynamic
+    // import — same reason describeResources/exportResources are — so nothing
+    // on the build path resolves the live kubectl transport it shares with
+    // ./describe-resources.ts. deepNormalizationHooks is plain data with no
+    // transport dependency and is imported statically above, because core
+    // applies it to the *declared* tree whether or not a live read ever happens.
+    async observeResourcesDeep(options) {
+        const { observeResourcesDeepGcp } = await import("./deep-observe.js");
+        return observeResourcesDeepGcp(options);
+    },
+    deepNormalizationHooks: gcpDeepNormalizationHooks,
+};

package/dist/pseudo.js

@@ -0,0 +1,15 @@
+import { PseudoParameter, createPseudoParameters } from "@intentius/chant/pseudo-parameter";
+export { PseudoParameter };
+export const { ProjectId, Region, Zone } = createPseudoParameters({
+    ProjectId: "GCP::ProjectId",
+    Region: "GCP::Region",
+    Zone: "GCP::Zone",
+});
+/**
+ * GCP namespace containing all pseudo-parameters.
+ */
+export const GCP = {
+    ProjectId,
+    Region,
+    Zone,
+};

package/dist/rules/schema-registry.ts

@@ -6,6 +6,7 @@
  */
 
 import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 
 export interface FieldSchema {
   type: string;
@@ -38,7 +39,7 @@ export function getSchemaRegistry(): Map<string, ResourceSchema> {
     // Built lazily (not at module load) so importing this module stays edge-safe:
     // `createRequire(import.meta.url)` throws where import.meta.url is undefined
     // (bundled Workers); there it's caught here and the registry is just empty.
-    const require = createRequire(import.meta.url);
+    const require = createRequire(moduleSourceUrl(import.meta.url));
     const lexicon = require("../../generated/lexicon-gcp.json") as Record<string, LexiconEntry>;
     for (const entry of Object.values(lexicon)) {
       if (entry.kind === "resource" && entry.gvkKind && entry.schema) {

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AAiClG;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAW1F;AAuDD;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UA2F3B,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AAiClG;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAW1F;AAuDD;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UA2F3B,CAAC"}