@intentius/chant-lexicon-gcp 0.124.31 → 0.124.33

package/src/health.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { cloudRunEntry, observeHealthGcp } from "./health";
+import type { GcpReadHttp } from "./api/read-client";
+
+const AT = "2026-10-20T21:00:00.000Z";
+const now = () => new Date(AT);
+const entities = new Map([
+  [
+    "api",
+    {
+      entityType: "GCP::Run::Service",
+      props: { metadata: { name: "api", annotations: { "cnrm.cloud.google.com/project-id": "demo" } }, spec: { location: "us-central1" } },
+    },
+  ],
+]);
+
+describe("gcp health (#4177)", () => {
+  let saved: string | undefined;
+  beforeEach(() => {
+    saved = process.env.GCP_ENDPOINT_URL;
+    process.env.GCP_ENDPOINT_URL = "http://localhost:4588";
+  });
+  afterEach(() => {
+    if (saved === undefined) delete process.env.GCP_ENDPOINT_URL;
+    else process.env.GCP_ENDPOINT_URL = saved;
+  });
+
+  test("reads the v2 terminalCondition and the v1 status conditions", () => {
+    expect(
+      cloudRunEntry({ terminalCondition: { type: "Ready", state: "CONDITION_SUCCEEDED", lastTransitionTime: "2026-10-20T20:00:00Z" }, latestReadyRevision: "projects/demo/locations/us-central1/services/api/revisions/api-00002" }, AT),
+    ).toMatchObject({ state: "healthy", detail: "Ready CONDITION_SUCCEEDED, latest ready api-00002", checkedAt: "2026-10-20T20:00:00Z" });
+    expect(cloudRunEntry({ terminalCondition: { type: "Ready", state: "CONDITION_FAILED", message: "image not found" } }, AT)).toMatchObject({
+      state: "unhealthy",
+      detail: "Ready CONDITION_FAILED: image not found",
+    });
+    expect(cloudRunEntry({ terminalCondition: { type: "Ready", state: "CONDITION_RECONCILING" } }, AT).state).toBe("unknown");
+    expect(cloudRunEntry({ status: { conditions: [{ type: "Ready", status: "False", reason: "RevisionFailed" }] } }, AT).state).toBe("unhealthy");
+    expect(cloudRunEntry({}, AT).state).toBe("unknown");
+  });
+
+  test("reads at the endpoint override in the declared project and location", async () => {
+    const urls: string[] = [];
+    const http: GcpReadHttp = async (_m, url) => {
+      urls.push(url);
+      return { status: 200, text: JSON.stringify({ terminalCondition: { type: "Ready", state: "CONDITION_SUCCEEDED" } }) };
+    };
+    const r = await observeHealthGcp({ environment: "dev", buildOutput: "", entities, http, now });
+    expect(r.entities.api).toMatchObject({ state: "healthy", observedAt: AT });
+    expect(urls).toEqual(["http://localhost:4588/v2/projects/demo/locations/us-central1/services/api"]);
+  });
+
+  test("a 404 is absent; a 403 is a no-credentials hole", async () => {
+    const notFound: GcpReadHttp = async () => ({ status: 404, text: "" });
+    expect((await observeHealthGcp({ environment: "dev", buildOutput: "", entities, http: notFound })).absent).toEqual(["api"]);
+    const denied: GcpReadHttp = async () => ({ status: 403, text: "denied" });
+    const r = await observeHealthGcp({ environment: "dev", buildOutput: "", entities, http: denied });
+    expect(r.unobserved.api?.reason).toBe("no-credentials");
+  });
+});

package/src/health.ts

@@ -0,0 +1,123 @@
+/**
+ * Runtime health for GCP (#4177): Cloud Run services.
+ *
+ * A Cloud Run v2 service carries its `Ready` condition as `terminalCondition`
+ * (`CONDITION_SUCCEEDED`, `CONDITION_FAILED`, pending or reconciling). The v1
+ * and Config Connector shape carries it in `status.conditions` with
+ * `status: "True" | "False" | "Unknown"`; both are read. Same transport,
+ * project resolution and endpoint rule as `describe-resources.ts`, so
+ * `GCP_ENDPOINT_URL` (floci-gcp) answers.
+ */
+
+import type { HealthEntry, HealthReadOptions, HealthReadResult, UnobservedEntity } from "@intentius/chant/lexicon";
+import { getResource, GcpReadError, isNotFound, type GcpReadHttp } from "./api/read-client";
+import { deriveGVK, manifestProjectAnnotations, resolveReadProject } from "./describe-resources";
+
+export const GCP_HEALTH_TYPES = ["GCP::Run::Service"] as const;
+
+export interface GcpHealthOptions extends HealthReadOptions {
+  http?: GcpReadHttp;
+  now?: () => Date;
+}
+
+interface Condition {
+  type?: string;
+  state?: string;
+  status?: string;
+  reason?: string;
+  message?: string;
+  lastTransitionTime?: string;
+}
+
+/** The parts of a Cloud Run service body that decide health. */
+export interface CloudRunServiceState {
+  terminalCondition?: Condition;
+  conditions?: Condition[];
+  reconciling?: boolean;
+  latestReadyRevision?: string;
+  uri?: string;
+  status?: { conditions?: Condition[]; url?: string };
+}
+
+function readyCondition(body: CloudRunServiceState): Condition | undefined {
+  if (body.terminalCondition && (body.terminalCondition.type ?? "Ready") === "Ready") return body.terminalCondition;
+  return body.conditions?.find((c) => c.type === "Ready") ?? body.status?.conditions?.find((c) => c.type === "Ready");
+}
+
+/** The `Ready` condition's verdict. No condition at all is `unknown`. */
+export function cloudRunEntry(body: CloudRunServiceState, observedAt: string): HealthEntry {
+  const type = "GCP::Run::Service";
+  const ready = readyCondition(body);
+  if (!ready) return { type, state: "unknown", detail: "no Ready condition", observedAt };
+  const value = (ready.state ?? ready.status ?? "").toUpperCase();
+  const state =
+    value === "CONDITION_SUCCEEDED" || value === "TRUE"
+      ? "healthy"
+      : value === "CONDITION_FAILED" || value === "FALSE"
+        ? "unhealthy"
+        : "unknown";
+  const why = ready.message || ready.reason;
+  const revision = body.latestReadyRevision ? `, latest ready ${body.latestReadyRevision.split("/").pop()}` : "";
+  const reconciling = body.reconciling ? ", reconciling" : "";
+  return {
+    type,
+    state,
+    detail: `Ready ${ready.state ?? ready.status ?? "unset"}${why ? `: ${why}` : ""}${revision}${reconciling}`,
+    observedAt,
+    ...(ready.lastTransitionTime ? { checkedAt: ready.lastTransitionTime } : {}),
+  };
+}
+
+export async function observeHealthGcp(options: GcpHealthOptions): Promise<HealthReadResult> {
+  const observedAt = (options.now?.() ?? new Date()).toISOString();
+  const endpoint = process.env.GCP_ENDPOINT_URL;
+  const manifestProjects = manifestProjectAnnotations(options.buildOutput);
+  const entities: Record<string, HealthEntry> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
+  const absent: string[] = [];
+
+  await Promise.all(
+    [...options.entities].map(async ([entityName, { entityType, props }]) => {
+      const gvk = deriveGVK(entityType);
+      const metadata = props.metadata as { name?: string; annotations?: Record<string, string> } | undefined;
+      const name = metadata?.name;
+      if (!gvk || !name) {
+        unobserved[entityName] = {
+          type: entityType,
+          reason: "read-failed",
+          detail: gvk ? "declared entity has no metadata.name to query by" : `cannot derive a GCP kind from ${entityType}`,
+        };
+        return;
+      }
+      let project: string;
+      try {
+        project = resolveReadProject(gvk.kind, name, metadata, manifestProjects);
+      } catch (err) {
+        unobserved[entityName] = { type: entityType, reason: "no-binding", detail: err instanceof Error ? err.message : String(err) };
+        return;
+      }
+      try {
+        const body = await getResource(
+          { project, ...(endpoint ? { endpoint } : {}), ...(options.http ? { http: options.http } : {}) },
+          gvk.kind,
+          name,
+          props,
+        );
+        entities[entityName] = cloudRunEntry(body as CloudRunServiceState, observedAt);
+      } catch (err) {
+        if (isNotFound(err)) {
+          absent.push(entityName);
+          return;
+        }
+        const status = err instanceof GcpReadError ? err.status : undefined;
+        unobserved[entityName] = {
+          type: entityType,
+          reason: status === 401 || status === 403 ? "no-credentials" : "read-failed",
+          detail: (err instanceof Error ? err.message : String(err)).slice(0, 200),
+        };
+      }
+    }),
+  );
+
+  return { entities, unobserved, absent };
+}

package/src/index.ts

@@ -21,6 +21,9 @@ export { GCP, ProjectId, Region, Zone } from "./pseudo";
 // Variables / annotation constants
 export { GcpAnnotations } from "./variables";
 
+// Outputs (#4181): the build warns that Config Connector YAML can't carry them.
+export { LexiconOutput, output, isLexiconOutput } from "@intentius/chant/lexicon-output";
+
 // Generated entities — export everything from generated index
 // After running `npm run generate`, this re-exports all Config Connector resource classes
 export * from "./generated/index";

package/src/lint/post-synth/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/src/lsp/completions.ts

@@ -1,7 +1,8 @@
 import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
 import { LexiconIndex, lexiconCompletions, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
-const require = createRequire(import.meta.url);
+const require = createRequire(moduleSourceUrl(import.meta.url));
 
 let cachedIndex: LexiconIndex | null = null;
 

package/src/lsp/hover.ts

@@ -1,7 +1,8 @@
 import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
 import { LexiconIndex, lexiconHover, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
-const require = createRequire(import.meta.url);
+const require = createRequire(moduleSourceUrl(import.meta.url));
 
 // GCP's generated lexicon JSON includes extra CRD-derived metadata (apiVersion,
 // gvkKind) that the core LexiconEntry interface doesn't carry. Type the data

package/src/plugin.ts

@@ -410,4 +410,12 @@ export const bucket = new StorageBucket({
   },
 
   deepNormalizationHooks: gcpDeepNormalizationHooks,
+
+  /** Runtime health (#4177): Cloud Run services. Implementation in ./health.ts. */
+  healthTypes: ["GCP::Run::Service"],
+
+  async observeHealth(options) {
+    const { observeHealthGcp } = await import("./health");
+    return observeHealthGcp(options);
+  },
 };

package/src/serializer-outputs.test.ts

@@ -0,0 +1,26 @@
+/**
+ * Config Connector YAML has no outputs, so an output of a gcp resource is
+ * named in a warning instead of vanishing (#4181).
+ */
+
+import { describe, expect, it } from "vitest";
+import { output, CloudRunService } from "./index";
+import { gcpSerializer } from "./serializer";
+
+describe("gcp outputs", () => {
+  it("warns that an output of a gcp resource can't be written", () => {
+    const svc = new CloudRunService({ location: "us-central1", projectRef: { external: "p" }, template: {} }) as any;
+    const out = output(svc.status_uri, "WebUri");
+    out._setSourceEntity("web");
+    const result = gcpSerializer.serialize(new Map([["web", svc]]), [out]);
+    expect(typeof result).toBe("object");
+    const warnings = (result as { warnings?: string[] }).warnings ?? [];
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('output "WebUri" (web.status.uri)');
+  });
+
+  it("says nothing about an output with no source lexicon", () => {
+    const result = gcpSerializer.serialize(new Map(), [output("eastus", "Region")]);
+    expect(typeof result).toBe("string");
+  });
+});

package/src/serializer.ts

@@ -6,6 +6,7 @@
  */
 
 import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 import type { Declarable } from "@intentius/chant/declarable";
 import { isPropertyDeclarable, isResourceDeclarable } from "@intentius/chant/declarable";
 import type { Serializer, SerializerResult, SerializeContext } from "@intentius/chant/serializer";
@@ -16,7 +17,7 @@ import { emitYAML } from "@intentius/chant/yaml";
 import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
 import { isDefaultLabels, isDefaultAnnotations, type DefaultLabels, type DefaultAnnotations } from "./default-labels";
 
-const require = createRequire(import.meta.url);
+const require = createRequire(moduleSourceUrl(import.meta.url));
 
 /**
  * GVK mapping entry — loaded from generated lexicon-gcp.json.
@@ -115,6 +116,21 @@ function toYAMLValue(value: unknown, entityNames: Map<Declarable, string>): unkn
   return walkValue(value, entityNames, gcpVisitor(entityNames));
 }
 
+/**
+ * A warning for each output of a gcp resource (#4181). Config Connector YAML
+ * has no outputs section, and a field such as `status.uri` exists only once
+ * the resource is applied, so the build cannot write the value anywhere. An
+ * output with no source lexicon (a literal or an intrinsic) is passed to
+ * every lexicon and is left to one that writes outputs.
+ */
+function unwritableOutputWarnings(outputs: LexiconOutput[] | undefined): string[] {
+  return (outputs ?? [])
+    .filter((o) => o.sourceLexicon === "gcp")
+    .map((o) =>
+      `gcp: output "${o.outputName}" (${o.sourceEntity || "?"}.${o.sourceAttribute}) is not written: Config Connector YAML has no outputs, so the value exists only after apply. Read it from the live resource instead.`,
+    );
+}
+
 /**
  * GCP Config Connector YAML serializer implementation.
  */
@@ -122,7 +138,7 @@ export const gcpSerializer: Serializer = {
   name: "gcp",
   rulePrefix: "WGC",
 
-  serialize(entities: Map<string, Declarable>, _outputs?: LexiconOutput[], context?: SerializeContext): string {
+  serialize(entities: Map<string, Declarable>, outputs?: LexiconOutput[], context?: SerializeContext): string | SerializerResult {
     // Build reverse map: entity → name
     const entityNames = new Map<Declarable, string>();
     for (const [name, entity] of entities) {
@@ -207,7 +223,9 @@ export const gcpSerializer: Serializer = {
       documents.push(yamlDoc);
     }
 
-    return documents.join("\n---\n");
+    const primary = documents.join("\n---\n");
+    const warnings = unwritableOutputWarnings(outputs);
+    return warnings.length > 0 ? { primary, warnings } : primary;
   },
 };
 

package/src/spec/parse.test.ts

@@ -50,6 +50,47 @@ describe("gcpShortName", () => {
 });
 
 describe("parseGcpCRD", () => {
+  test("turns the scalar fields of status into attributes (#4179)", () => {
+    const crd = `apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: runservices.run.cnrm.cloud.google.com
+spec:
+  group: run.cnrm.cloud.google.com
+  names:
+    kind: RunService
+  versions:
+    - name: v1beta1
+      served: true
+      storage: true
+      schema:
+        openAPIV3Schema:
+          properties:
+            spec:
+              type: object
+              properties:
+                location:
+                  type: string
+            status:
+              type: object
+              properties:
+                uri:
+                  type: string
+                observedGeneration:
+                  type: integer
+                conditions:
+                  type: array
+                  items:
+                    type: object
+`;
+    const [result] = parseGcpCRD(crd);
+    const attrs = Object.fromEntries(result.resource.attributes.map((a) => [a.name, a.tsType]));
+    expect(attrs["status.uri"]).toBe("string");
+    expect(attrs["status.observedGeneration"]).toBe("number");
+    expect(attrs["status.conditions"]).toBeUndefined();
+    expect(attrs.name).toBe("string");
+  });
+
   test("parses ComputeInstance CRD", () => {
     const content = readFileSync(join(testdata, "compute-instance.yaml"), "utf-8");
     const results = parseGcpCRD(content);
@@ -80,8 +121,7 @@ describe("parseGcpCRD", () => {
     expect(netRef!.isResourceRef).toBe(true);
 
     // Check attributes
-    expect(result.resource.attributes).toHaveLength(3);
-    expect(result.resource.attributes[0].name).toBe("name");
+    expect(result.resource.attributes.map((a) => a.name)).toEqual(["name", "namespace", "uid", "status.instanceId", "status.selfLink"]);
   });
 
   test("parses StorageBucket CRD", () => {

package/src/spec/parse.ts

@@ -4,7 +4,7 @@
  * Adapts the K8s CRD parser pattern for GCP-specific concerns:
  * - Type naming: GCP::{Service}::{Kind}
  * - resourceRef detection
- * - Status field skipping
+ * - Status fields skipped as props; scalar ones become attributes
  */
 
 import yaml from "js-yaml";
@@ -212,6 +212,7 @@ function parseCRDSpec(spec: CRDSpec): GcpParseResult[] {
         { name: "name", tsType: "string" },
         { name: "namespace", tsType: "string" },
         { name: "uid", tsType: "string" },
+        ...statusAttributes(schema?.properties?.status),
       ],
       deprecatedProperties: [],
     },
@@ -223,6 +224,21 @@ function parseCRDSpec(spec: CRDSpec): GcpParseResult[] {
   return results;
 }
 
+/**
+ * The scalar top-level fields of a CRD's `status`, such as RunService's
+ * `status.uri` (#4179), as dotted attribute names. Config Connector fills them
+ * once the resource is ready, so they can't appear in the resource's own
+ * YAML, but another lexicon or an output can reference them.
+ */
+function statusAttributes(statusSchema: OpenAPISchema | undefined): ParsedAttribute[] {
+  const out: ParsedAttribute[] = [];
+  for (const [name, prop] of Object.entries(statusSchema?.properties ?? {})) {
+    if (prop.type !== "string" && prop.type !== "integer" && prop.type !== "number" && prop.type !== "boolean") continue;
+    out.push({ name: `status.${name}`, tsType: resolveSchemaType(prop) });
+  }
+  return out;
+}
+
 // ── Property extraction ─────────────────────────────────────────────
 
 /**