@intentius/chant 0.28.0 → 0.29.0

package/src/lifecycle/snapshot.ts

@@ -9,6 +9,7 @@ import type { LifecycleSnapshot } from "./types";
 import { computeBuildDigest } from "./digest";
 import { writeSnapshot, snapshotStorageKey, getHeadCommit, pushLifecycle } from "./git";
 import { sortedJsonReplacer } from "../utils";
+import { formatUnobserved, normalizeObservation, unobservedAll, type UnobservedEntity } from "../observation";
 
 /** Patterns in attribute names that suggest sensitive data. */
 const SENSITIVE_PATTERNS = [
@@ -124,22 +125,32 @@ export async function takeSnapshot(
 
     let resources: Record<string, ResourceMetadata> = {};
     let artifacts: Record<string, ArtifactMetadata> = {};
+    let unobserved: Record<string, UnobservedEntity> = {};
 
     try {
       if (plugin.describeResources) {
-        const raw = await plugin.describeResources({
-          environment,
-          buildOutput,
-          entityNames,
-          entities,
-          stack,
-        });
-        const { valid, dropped, warnings: validationWarnings } = validateResources(raw);
+        const observed = normalizeObservation(
+          await plugin.describeResources({
+            environment,
+            buildOutput,
+            entityNames,
+            entities,
+            stack,
+          }),
+        );
+        const { valid, dropped, warnings: validationWarnings } = validateResources(observed.resources);
         warnings.push(...validationWarnings);
         if (dropped.length > 0) {
           warnings.push(`${plugin.name}: dropped ${dropped.length} invalid resource(s)`);
         }
         resources = valid;
+        // Record the holes (#1089). A snapshot is evidence of what was seen; an
+        // entity nobody could read must not be recorded as "was not there",
+        // because the next diff would then read it back as absent.
+        unobserved = observed.unobserved;
+        for (const [name, entry] of Object.entries(unobserved)) {
+          warnings.push(`${plugin.name}: not observed — ${formatUnobserved(name, entry)}`);
+        }
       }
 
       if (plugin.listArtifacts) {
@@ -153,7 +164,12 @@ export async function takeSnapshot(
       }
 
       if (Object.keys(resources).length === 0 && Object.keys(artifacts).length === 0) {
-        errors.push(`${plugin.name}: no valid resources or artifacts returned`);
+        const unreadable = Object.keys(unobserved).length;
+        errors.push(
+          unreadable > 0
+            ? `${plugin.name}: nothing observed — ${unreadable} declared entity(ies) could not be read (see warnings); not snapshotting an unread environment as empty`
+            : `${plugin.name}: no valid resources or artifacts returned`,
+        );
         continue;
       }
 
@@ -164,15 +180,24 @@ export async function takeSnapshot(
         commit: headCommit,
         timestamp,
         resources,
+        ...(Object.keys(unobserved).length > 0 && { unobserved }),
         ...(Object.keys(artifacts).length > 0 && { artifacts }),
         digest,
       };
 
       snapshots.push(snapshot);
     } catch (err) {
+      // A thrown read is not an empty environment — record nothing and say so
+      // (#1089). Writing a snapshot here would persist "none of this exists".
       errors.push(
         `${plugin.name}: ${err instanceof Error ? err.message : String(err)}`,
       );
+      const message = err instanceof Error ? err.message : String(err);
+      for (const [name, entry] of Object.entries(
+        unobservedAll(entityNames, "read-failed", message, entities),
+      )) {
+        warnings.push(`${plugin.name}: not observed — ${formatUnobserved(name, entry)}`);
+      }
     }
   }
 

package/src/lifecycle/status.test.ts

@@ -32,8 +32,8 @@ describe("status", () => {
       const cs: ChangeSet = {
         env: "prod",
         entries: [
-          { name: "search-service", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true }, ownership: "owned" },
-          { name: "orphan-thing", type: "T", action: "adopt", evidence: { declared: false, inSnapshot: false, live: true }, ownership: "foreign" },
+          { name: "search-service", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true, observed: true }, ownership: "owned" },
+          { name: "orphan-thing", type: "T", action: "adopt", evidence: { declared: false, inSnapshot: false, live: true, observed: true }, ownership: "foreign" },
         ],
       };
       const evidence = liveEvidenceFromChangeSet(cs);
@@ -49,7 +49,7 @@ describe("status", () => {
         const cs: ChangeSet = {
           env: "prod",
           entries: [
-            { name: "search-service-v2", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true }, ownership: "owned" },
+            { name: "search-service-v2", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true, observed: true }, ownership: "owned" },
           ],
         };
         const mapping: LiveNameMapping = new Map([["search-svc", ["search-service-v2"]]]);
@@ -63,7 +63,7 @@ describe("status", () => {
         const cs: ChangeSet = {
           env: "prod",
           entries: [
-            { name: "search-service", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true }, ownership: "owned" },
+            { name: "search-service", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true, observed: true }, ownership: "owned" },
           ],
         };
         const mapping: LiveNameMapping = new Map([["some-other-component", ["renamed-thing"]]]);
@@ -75,8 +75,8 @@ describe("status", () => {
         const cs: ChangeSet = {
           env: "prod",
           entries: [
-            { name: "cluster-node-1", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true }, ownership: "owned" },
-            { name: "cluster-node-2", type: "T", action: "update", evidence: { declared: true, inSnapshot: true, live: true }, ownership: "owned" },
+            { name: "cluster-node-1", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true, observed: true }, ownership: "owned" },
+            { name: "cluster-node-2", type: "T", action: "update", evidence: { declared: true, inSnapshot: true, live: true, observed: true }, ownership: "owned" },
           ],
         };
         const mapping: LiveNameMapping = new Map([["neo4j-cluster", ["cluster-node-1", "cluster-node-2"]]]);
@@ -297,7 +297,7 @@ describe("status", () => {
       const cs: ChangeSet = {
         env: "prod",
         entries: [
-          { name: "search-service-v2", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true }, ownership: "owned" },
+          { name: "search-service-v2", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true, observed: true }, ownership: "owned" },
         ],
       };
       const mapping: LiveNameMapping = new Map([["search-svc", ["search-service-v2"]]]);
@@ -311,7 +311,7 @@ describe("status", () => {
       const cs: ChangeSet = {
         env: "prod",
         entries: [
-          { name: "search-service", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true }, ownership: "owned" },
+          { name: "search-service", type: "T", action: "noop", evidence: { declared: true, inSnapshot: true, live: true, observed: true }, ownership: "owned" },
         ],
       };
       const liveEvidence = liveEvidenceFromChangeSet(cs);
@@ -381,5 +381,86 @@ describe("status", () => {
       const merged = mergeLiveEvidence(undefined, supplement);
       expect(merged.get("c")).toEqual({ live: true, ownership: "owned", action: undefined });
     });
+
+    test("a direct stack observation clears an inherited hole; a failing one keeps it (#1089)", () => {
+      const base = new Map<string, LiveComponentEvidence>([
+        ["a", { live: false, unobserved: { reason: "read-failed" } }],
+        ["b", { live: false, unobserved: { reason: "read-failed" } }],
+      ]);
+      const supplement = new Map<string, LiveComponentEvidence>([
+        ["a", { live: true, ownership: "owned" }],
+        ["b", { live: false, unobserved: { reason: "read-failed", detail: "no determinate status" } }],
+      ]);
+      const merged = mergeLiveEvidence(base, supplement);
+      expect(merged.get("a")!.unobserved).toBeUndefined();
+      expect(merged.get("b")!.unobserved?.reason).toBe("read-failed");
+    });
+  });
+
+  // ── The observation tri-state reaches the status join (#1089) ─────────────
+
+  describe("not-observed never becomes 'stale' (#1089)", () => {
+    const record = {
+      version: 1,
+      component: "search-svc",
+      env: "prod",
+      digest: "sha256:abc",
+      gitSha: "g",
+      runId: "r",
+      timestamp: "2026-01-01T00:00:00Z",
+      actor: "ci",
+    } as const;
+
+    test("a recorded component whose live state could not be read reports unknown", () => {
+      const rows = reconcileStatus("prod", [record], {
+        liveEvidence: new Map<string, LiveComponentEvidence>([
+          ["search-svc", { live: false, unobserved: { reason: "no-binding", detail: "no kubectl context" } }],
+        ]),
+      });
+      expect(rows[0].reconciliation).toBe("unknown");
+      expect(rows[0].detail).toContain("could not be observed");
+      expect(rows[0].detail).toContain("no kubectl context");
+      // `live` is omitted entirely — `false` would read as "not deployed".
+      expect(rows[0].live).toBeUndefined();
+      expect(rows[0].unobserved).toEqual({ reason: "no-binding", detail: "no kubectl context" });
+    });
+
+    test("the same component, actually observed absent, still reports stale", () => {
+      const rows = reconcileStatus("prod", [record], {
+        liveEvidence: new Map<string, LiveComponentEvidence>([["search-svc", { live: false }]]),
+      });
+      expect(rows[0].reconciliation).toBe("stale");
+      expect(rows[0].live).toBe(false);
+    });
+
+    test("an unrecorded component that could not be read is unknown, not unrecorded", () => {
+      const rows = reconcileStatus("prod", [], {
+        allComponents: ["search-svc"],
+        liveEvidence: new Map<string, LiveComponentEvidence>([
+          ["search-svc", { live: false, unobserved: { reason: "read-failed" } }],
+        ]),
+      });
+      expect(rows[0].reconciliation).toBe("unknown");
+    });
+
+    test("liveEvidenceFromChangeSet carries the plan's unobserved verdict", () => {
+      const evidence = liveEvidenceFromChangeSet({
+        env: "prod",
+        entries: [
+          {
+            name: "search-svc",
+            action: "unobserved",
+            evidence: { declared: true, inSnapshot: false, live: false, observed: false },
+            ownership: "unknown",
+            unobservedReason: "unsupported-kind",
+            unobservedDetail: "no reader",
+          },
+        ],
+      });
+      expect(evidence.get("search-svc")!.unobserved).toEqual({
+        reason: "unsupported-kind",
+        detail: "no reader",
+      });
+    });
   });
 });

package/src/lifecycle/status.ts

@@ -21,6 +21,9 @@
  *    lower-confidence signal rather than silently treated as "reconciled".
  *  - **reconciled** — a release record exists and live evidence (via
  *    ownership) confirms the component is present and owned by chant.
+ *  - **unknown** — live evidence was requested and could not be read (#1089),
+ *    or was not requested at all. A component chant could not observe is never
+ *    reported `stale`: "the read failed" and "it is gone" are different facts.
  *
  * This is deliberately a light-touch reconciliation: chant's lexicons report
  * resource-level status (`ResourceMetadata`), not "the digest currently
@@ -36,6 +39,7 @@
 import type { ChangeSet, ChangeAction } from "./change-set";
 import { latestPerComponent, type ReleaseRecord } from "./release-ledger";
 import type { BuildLedgerEntry, ComponentBomSummary } from "./build-ledger";
+import { unobservedReasonText, type UnobservedReason } from "../observation";
 
 /** One row of `chant components status [env]` — the per-component join of recorded vs live. */
 export interface ComponentStatusRow {
@@ -63,9 +67,18 @@ export interface ComponentStatusRow {
   /**
    * Machine-readable "observed live", when live evidence was gathered (`--live`).
    * A consumer joining this row onto a graph node should read this rather than
-   * string-matching `detail`. Absent when `--live` was not requested.
+   * string-matching `detail`. Absent when `--live` was not requested — and, since
+   * #1089, also absent when live state could not be read at all: `false` means
+   * "looked, not there", never "did not look". Read {@link unobserved} for that
+   * case; a consumer that treats absent as "unknown" already handles it.
    */
   live?: boolean;
+  /**
+   * Set when `--live` was requested and the observation could not read this
+   * component (#1089). `live` is absent alongside it and `reconciliation` is
+   * `unknown` — the row reports a hole rather than a verdict.
+   */
+  unobserved?: { reason: UnobservedReason; detail?: string };
   /**
    * The owning deploy unit's raw status, when a lexicon reported it (AWS: the
    * component's own CFN stack via `describeStackStatus`). Lets a renderer paint a
@@ -103,6 +116,12 @@ export interface ComponentStatusResult {
 export interface LiveComponentEvidence {
   /** True if this component name was observed live at all (declared+live, or orphan+live). */
   live: boolean;
+  /**
+   * Set when the observation could not read this component (#1089). `live` is
+   * `false` alongside it, but only because the boolean has nowhere else to go —
+   * every consumer must branch on this field before believing `live: false`.
+   */
+  unobserved?: { reason: UnobservedReason; detail?: string };
   /** The `ChangeSet` action chant's existing plan logic assigned, when the component maps to a tracked entity/resource name. */
   action?: ChangeAction;
   /** Ownership verdict, when known. */
@@ -132,6 +151,10 @@ export function mergeLiveEvidence(
     const b = merged.get(component);
     merged.set(component, {
       live: sup.live,
+      // A direct stack observation that succeeded answers the question the
+      // change-set axis could not — so it clears an inherited "not observed".
+      // A supplement that itself could not read keeps the hole.
+      ...(sup.unobserved ? { unobserved: sup.unobserved } : {}),
       ownership: sup.ownership ?? b?.ownership,
       action: b?.action,
       stack: sup.stack ?? b?.stack,
@@ -178,8 +201,12 @@ function mergeEvidence(entries: LiveComponentEvidence[]): LiveComponentEvidence
   const action = entries.some((e) => e.action === "update")
     ? "update"
     : entries.find((e) => e.action !== undefined)?.action;
+  // A component whose entities were partly readable is still partly unknown, so
+  // any unobserved entity keeps the hole — unless something under it was
+  // actually seen live, which already answers "is this deployed".
+  const unobserved = live ? undefined : entries.find((e) => e.unobserved)?.unobserved;
 
-  return { live, ownership, action };
+  return { live, ownership, action, ...(unobserved ? { unobserved } : {}) };
 }
 
 /**
@@ -204,6 +231,16 @@ export function liveEvidenceFromChangeSet(
       live: entry.evidence.live,
       action: entry.action,
       ownership: entry.ownership,
+      // Carry the plan's "could not look" verdict through so the status join
+      // reports a hole instead of reading `live: false` as "gone" (#1089).
+      ...(entry.action === "unobserved" && entry.unobservedReason
+        ? {
+            unobserved: {
+              reason: entry.unobservedReason,
+              ...(entry.unobservedDetail ? { detail: entry.unobservedDetail } : {}),
+            },
+          }
+        : {}),
     });
   }
 
@@ -275,6 +312,15 @@ export function reconcileStatus(
       detail = recorded
         ? "recorded; live status not queried (pass --live to reconcile)"
         : "no release record found";
+    } else if (evidence?.unobserved) {
+      // Live evidence was requested and could not be read (#1089). Neither
+      // `stale` (which claims the component is gone) nor `reconciled` is
+      // supportable — the honest verdict is that nothing is known.
+      reconciliation = "unknown";
+      const why = `${unobservedReasonText(evidence.unobserved.reason)}${evidence.unobserved.detail ? `: ${evidence.unobserved.detail}` : ""}`;
+      detail = recorded
+        ? `recorded ${recorded.timestamp} (digest ${recorded.digest}), but live state could not be observed — ${why}`
+        : `no release record, and live state could not be observed — ${why}`;
     } else if (!recorded && evidence?.live) {
       reconciliation = "unrecorded";
       detail = `live${evidence.ownership === "owned" ? " and chant-owned" : ""}, but no release record exists — deployed outside the recorded path`;
@@ -300,7 +346,11 @@ export function reconcileStatus(
       componentBom,
       reconciliation,
       detail,
-      ...(liveEvidence ? { live: !!evidence?.live } : {}),
+      // `live` is only emitted when it is a real answer: requested AND read.
+      // An unread component leaves it absent (= unknown to every consumer)
+      // rather than reporting `false`, which would read as "not deployed".
+      ...(liveEvidence && !evidence?.unobserved ? { live: !!evidence?.live } : {}),
+      ...(evidence?.unobserved ? { unobserved: evidence.unobserved } : {}),
       ...(evidence?.stack ? { stack: evidence.stack } : {}),
     });
   }

package/src/lifecycle/types.ts

@@ -1,4 +1,5 @@
 import type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
+import type { UnobservedEntity } from "../observation";
 
 export type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
 
@@ -18,6 +19,13 @@ export interface LifecycleSnapshot {
   timestamp: string;
   /** Resource metadata keyed by logical name */
   resources: Record<string, ResourceMetadata>;
+  /**
+   * Declared entities this observation could not read (#1089), keyed by logical
+   * name. Additive and optional: a snapshot without it observed everything it
+   * was asked about. Present so a later diff can tell "was not there when the
+   * snapshot was taken" from "was never looked at".
+   */
+  unobserved?: Record<string, UnobservedEntity>;
   /** Artifact metadata keyed by server-side identifier (lexicon-specific). */
   artifacts?: Record<string, ArtifactMetadata>;
   /** Build digest at snapshot time — what was declared when this snapshot was taken */

package/src/live-endpoint.test.ts

@@ -0,0 +1,115 @@
+import { describe, test, expect } from "vitest";
+import { applyLiveEndpoint, zeroResourcesWarning, LEXICON_ENDPOINT_ENV_VAR } from "./live-endpoint";
+import type { EnvironmentDeclaration } from "./config";
+
+describe("applyLiveEndpoint (#1166)", () => {
+  test("no-op — and no notice — when the environment declares no endpoint at all", () => {
+    const env: NodeJS.ProcessEnv = {};
+    const result = applyLiveEndpoint(["floci", "prod"], "floci", ["aws"], env);
+    expect(result.notice).toBeUndefined();
+    expect(env.AWS_ENDPOINT_URL).toBeUndefined();
+    result.restore(); // always safe, even as a no-op
+    expect(env.AWS_ENDPOINT_URL).toBeUndefined();
+  });
+
+  test("applies the declared endpoint to the ambient var of every observing lexicon that has one", () => {
+    const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
+    const env: NodeJS.ProcessEnv = {};
+    const result = applyLiveEndpoint(environments, "floci", ["aws"], env);
+    expect(env.AWS_ENDPOINT_URL).toBe("http://localhost:4566");
+    expect(result.notice).toMatch(/environment "floci" declares endpoint http:\/\/localhost:4566/);
+    expect(result.notice).toMatch(/AWS_ENDPOINT_URL/);
+  });
+
+  test("restore() removes exactly what it set, not a pre-existing value it didn't touch", () => {
+    const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
+    const env: NodeJS.ProcessEnv = {};
+    const result = applyLiveEndpoint(environments, "floci", ["aws"], env);
+    expect(env.AWS_ENDPOINT_URL).toBe("http://localhost:4566");
+    result.restore();
+    expect(env.AWS_ENDPOINT_URL).toBeUndefined();
+  });
+
+  test("ambient wins: an already-set var is left untouched, and the notice says so", () => {
+    const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
+    const env: NodeJS.ProcessEnv = { AWS_ENDPOINT_URL: "http://real-endpoint.example" };
+    const result = applyLiveEndpoint(environments, "floci", ["aws"], env);
+    expect(env.AWS_ENDPOINT_URL).toBe("http://real-endpoint.example"); // unchanged
+    expect(result.notice).toMatch(/ambient AWS_ENDPOINT_URL already set/);
+    result.restore();
+    expect(env.AWS_ENDPOINT_URL).toBe("http://real-endpoint.example"); // restore never touches what it didn't set
+  });
+
+  test("a bare-string environment entry has no endpoint to apply", () => {
+    const env: NodeJS.ProcessEnv = {};
+    const result = applyLiveEndpoint(["floci"], "floci", ["aws"], env);
+    expect(result.notice).toBeUndefined();
+    expect(env.AWS_ENDPOINT_URL).toBeUndefined();
+  });
+
+  test("only applies to lexicons actually observing, and only those with a known endpoint var", () => {
+    const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
+    const env: NodeJS.ProcessEnv = {};
+    // k8s has no ambient-var knob (config-resolved instead) — nothing to set.
+    const result = applyLiveEndpoint(environments, "floci", ["k8s"], env);
+    expect(env.AWS_ENDPOINT_URL).toBeUndefined();
+    expect(result.notice).toBeUndefined();
+  });
+
+  test("applies to fly's FLY_FLAPS_BASE_URL too, when fly is among the observing lexicons", () => {
+    const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
+    const env: NodeJS.ProcessEnv = {};
+    const result = applyLiveEndpoint(environments, "floci", ["aws", "fly"], env);
+    expect(env.AWS_ENDPOINT_URL).toBe("http://localhost:4566");
+    expect(env.FLY_FLAPS_BASE_URL).toBe("http://localhost:4566");
+    result.restore();
+    expect(env.AWS_ENDPOINT_URL).toBeUndefined();
+    expect(env.FLY_FLAPS_BASE_URL).toBeUndefined();
+  });
+
+  test("mixed: one lexicon's var is applied, another's ambient value wins — both show up in the notice", () => {
+    const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
+    const env: NodeJS.ProcessEnv = { FLY_FLAPS_BASE_URL: "http://real-fly.example" };
+    const result = applyLiveEndpoint(environments, "floci", ["aws", "fly"], env);
+    expect(env.AWS_ENDPOINT_URL).toBe("http://localhost:4566"); // applied
+    expect(env.FLY_FLAPS_BASE_URL).toBe("http://real-fly.example"); // ambient wins
+    expect(result.notice).toMatch(/applied to AWS_ENDPOINT_URL/);
+    expect(result.notice).toMatch(/ambient FLY_FLAPS_BASE_URL already set/);
+  });
+
+  test("audited endpoint-knob registry: only aws and fly (gcp/k8s/azure/temporal resolve via config, not an ambient var)", () => {
+    expect(LEXICON_ENDPOINT_ENV_VAR).toEqual({ aws: "AWS_ENDPOINT_URL", fly: "FLY_FLAPS_BASE_URL" });
+  });
+
+  test("a name that isn't declared at all has no endpoint to apply", () => {
+    const environments: EnvironmentDeclaration[] = [{ name: "floci", endpoint: "http://localhost:4566" }];
+    const env: NodeJS.ProcessEnv = {};
+    const result = applyLiveEndpoint(environments, "prod", ["aws"], env);
+    expect(result.notice).toBeUndefined();
+    expect(env.AWS_ENDPOINT_URL).toBeUndefined();
+  });
+});
+
+describe("zeroResourcesWarning (#1166)", () => {
+  test("undefined when nothing was declared to look for", () => {
+    expect(zeroResourcesWarning("aws", "floci", 0, { resources: {}, unobserved: {} })).toBeUndefined();
+  });
+
+  test("undefined when resources were actually observed", () => {
+    expect(
+      zeroResourcesWarning("aws", "floci", 2, { resources: { a: {} }, unobserved: {} }),
+    ).toBeUndefined();
+  });
+
+  test("undefined when the emptiness is already explained by #1089 unobserved", () => {
+    expect(
+      zeroResourcesWarning("aws", "floci", 2, { resources: {}, unobserved: { a: { reason: "no-binding" } } }),
+    ).toBeUndefined();
+  });
+
+  test("warns with declared count and the check-endpoint hint when truly empty and unexplained", () => {
+    expect(zeroResourcesWarning("aws", "floci", 3, { resources: {}, unobserved: {} })).toBe(
+      'aws: 0 live resources for env "floci" (3 declared) — check the endpoint/credentials',
+    );
+  });
+});

package/src/live-endpoint.ts

@@ -0,0 +1,148 @@
+/**
+ * chant #1166 — let a declared `environment` carry its own endpoint so
+ * `--live --env <name>` is self-sufficient.
+ *
+ * The bug this closes: `chant graph --live --env floci` (and `lifecycle
+ * diff`/`plan`) observe a stack by shelling out through each lexicon's
+ * `describeResources()`. For AWS that shell-out honors the ambient
+ * `AWS_ENDPOINT_URL` env var — when a project's `floci` environment is a local
+ * emulator (`http://localhost:4566`) but the invoking shell never exported
+ * that var, the AWS CLI silently targets real AWS instead. The stack named
+ * after the environment doesn't exist there, so `describeResources` hits its
+ * `stackDoesNotExist` branch and returns an empty, unremarkable "nothing is
+ * deployed" — indistinguishable from the truthful answer. This cost real
+ * debugging time validating #1162's live overlay: the observation code was
+ * right, the manual repro just never set the var.
+ *
+ * The fix: `environments` in `chant.config.ts` can name an endpoint per
+ * environment (`config.ts`'s `EnvironmentDeclaration`), and {@link
+ * applyLiveEndpoint} injects it into the ambient env var each observing
+ * lexicon's CLI shell-out actually reads — but only for a var that isn't
+ * already set. Ambient always wins: a shell that already exports
+ * `AWS_ENDPOINT_URL` sees no change in behavior.
+ *
+ * Audited (#1166) which lexicons have an ambient-env-var endpoint knob at
+ * all, since that's the specific footgun — a lexicon whose environment
+ * binding is resolved from `chant.config` itself (not an ambient var) has
+ * nothing to inject here:
+ *
+ *   - **aws**  — `AWS_ENDPOINT_URL`, read directly by
+ *     `lexicons/aws/src/components/cloud-executor.ts` / `plugin.ts` before
+ *     every `aws …` shell-out (`applyAwsEndpoint`/`applyAwsEndpointArgv`).
+ *   - **fly**  — `FLY_FLAPS_BASE_URL`, read by `resolveEndpoint()` in
+ *     `lexicons/fly/src/op/activities/fly-apply.ts`, the same seam
+ *     `describeResources` (`../describe-resources.ts`) calls through.
+ *   - **gcp**, **k8s** — resolve their live target from `chant.config` itself
+ *     (`k8s.profiles.<env>.context` via `resolveClusterTarget`,
+ *     `packages/core/src/kubectl-context.ts`), not an ambient var. Nothing to
+ *     inject: the config *is* the binding already.
+ *   - **azure** — resolves via the `az` CLI's own logged-in
+ *     subscription/session context; no ambient endpoint var exists to miss.
+ *   - **temporal** — resolves its connection from `temporal.profiles.<env>`
+ *     (`resolveProfile`, `lexicons/temporal/src/describe-resources.ts`), the
+ *     same "config is the binding" shape as k8s/gcp.
+ */
+
+import { environmentEndpoint, type EnvironmentDeclaration } from "./config";
+
+/**
+ * Per-lexicon ambient env var a `--live` read honors for its endpoint. Only
+ * lexicons with a genuine ambient-var footgun are listed — see the module doc
+ * for the full audit (gcp/k8s/azure/temporal resolve their target from
+ * `chant.config` instead, so they have nothing to inject).
+ */
+export const LEXICON_ENDPOINT_ENV_VAR: Record<string, string> = {
+  aws: "AWS_ENDPOINT_URL",
+  fly: "FLY_FLAPS_BASE_URL",
+};
+
+/** Result of {@link applyLiveEndpoint} — always call `restore()`, even when nothing was applied (it is then a no-op). */
+export interface AppliedEndpoint {
+  /**
+   * One line describing what happened, or `undefined` when the environment
+   * declares no endpoint at all (nothing to say). Present whether the
+   * declared endpoint was applied OR an ambient var already won — #1166's
+   * "no silent anything" stance: an operator should never have to guess which
+   * target a `--live` read actually used.
+   */
+  notice?: string;
+  /** Undo whatever ambient env vars this call set. Always safe to call. */
+  restore: () => void;
+}
+
+/**
+ * Resolve `environment`'s declared endpoint (if any) from `config.environments`
+ * and apply it to the ambient env var of every lexicon in `lexicons` that has
+ * one ({@link LEXICON_ENDPOINT_ENV_VAR}) — but only when that var isn't
+ * already set. Ambient always wins (#1166): behavior for a shell that already
+ * exports `AWS_ENDPOINT_URL` is unchanged.
+ *
+ * Call before a `--live` describe/enrich pass; `restore()` in a `finally` so
+ * the injected value never leaks into a later invocation in the same process
+ * (tests, or a long-lived host like the MCP server).
+ */
+export function applyLiveEndpoint(
+  environments: EnvironmentDeclaration[] | undefined,
+  environment: string,
+  lexicons: readonly string[],
+  env: NodeJS.ProcessEnv = process.env,
+): AppliedEndpoint {
+  const endpoint = environmentEndpoint(environments, environment);
+  if (!endpoint) return { restore: () => {} };
+
+  const applied: string[] = [];
+  const overridden: string[] = [];
+  const seen = new Set<string>(); // a var shared by two lexicons is only reported once
+  for (const lexicon of lexicons) {
+    const varName = LEXICON_ENDPOINT_ENV_VAR[lexicon];
+    if (!varName || seen.has(varName)) continue;
+    seen.add(varName);
+    if (env[varName]) {
+      overridden.push(varName);
+      continue;
+    }
+    env[varName] = endpoint;
+    applied.push(varName);
+  }
+
+  const notices: string[] = [];
+  if (applied.length > 0) {
+    notices.push(
+      `environment "${environment}" declares endpoint ${endpoint} — applied to ${applied.join(", ")} for this read`,
+    );
+  }
+  if (overridden.length > 0) {
+    notices.push(
+      `ambient ${overridden.join(", ")} already set — keeping it over environment "${environment}"'s declared endpoint (${endpoint})`,
+    );
+  }
+
+  return {
+    notice: notices.length > 0 ? notices.join("; ") : undefined,
+    restore: () => {
+      for (const varName of applied) delete env[varName];
+    },
+  };
+}
+
+/**
+ * #1166 acceptance: when a `--live` describe comes back with zero resources
+ * for a lexicon that had declared entities to look for, and nothing was
+ * already reported NOT-OBSERVED (#1089) either, that is either "genuinely
+ * nothing is deployed yet" or a misconfigured endpoint/credentials — the two
+ * are visually identical, so a caller must say so rather than stay quiet.
+ * Returns `undefined` when there is nothing to declare (no declared entities
+ * to have asked about, or the emptiness is already explained by #1089's
+ * `unobserved`).
+ */
+export function zeroResourcesWarning(
+  lexicon: string,
+  environment: string,
+  declaredCount: number,
+  observed: { resources: Record<string, unknown>; unobserved: Record<string, unknown> },
+): string | undefined {
+  if (declaredCount === 0) return undefined;
+  if (Object.keys(observed.resources).length > 0) return undefined;
+  if (Object.keys(observed.unobserved).length > 0) return undefined;
+  return `${lexicon}: 0 live resources for env "${environment}" (${declaredCount} declared) — check the endpoint/credentials`;
+}