@intentius/chant-lexicon-fly 0.28.0 → 0.30.0

package/dist/describe-resources.d.ts

@@ -26,7 +26,7 @@
  * real-Fly target flyApply writes. Secrets are apply-only (D7): flaps returns
  * only a digest, so they never enter a diff and are excluded here.
  */
-import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import type { ObservationResult, ResourceMetadata } from "@intentius/chant/lexicon";
 import { type ChangeSet } from "@intentius/chant/lifecycle/change-set";
 import { type FlyHttp } from "./op/activities/fly-apply.js";
 export interface DescribeResourcesOptions {
@@ -51,7 +51,7 @@ export interface DescribeResourcesOptions {
  * `http` is injectable for tests; the default reuses the applier's fetch client
  * (bearer token from FLY_API_TOKEN).
  */
-export declare function describeResources(options: DescribeResourcesOptions, http?: FlyHttp, signal?: AbortSignal): Promise<Record<string, ResourceMetadata>>;
+export declare function describeResources(options: DescribeResourcesOptions, http?: FlyHttp, signal?: AbortSignal): Promise<ObservationResult>;
 /**
  * Read-only plan (#767 §4): a `flyApply` dry-run. Reads live state via
  * {@link describeResources}, promotes it to core's typed change set, then

package/dist/describe-resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAqBL,KAAK,OAAO,EAIb,MAAM,2BAA2B,CAAC;AAcnC,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,gDAAgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAeD;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,EACjC,IAAI,GAAE,OAA0B,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CA0M3C;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,wBAAwB,GAAG;IAClC,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACjD,EACD,IAAI,GAAE,OAA0B,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA8BrD"}
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAoB,MAAM,0BAA0B,CAAC;AAEtG,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAqBL,KAAK,OAAO,EAIb,MAAM,2BAA2B,CAAC;AAcnC,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,gDAAgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAeD;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,EACjC,IAAI,GAAE,OAA0B,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,iBAAiB,CAAC,CA4R5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,wBAAwB,GAAG;IAClC,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACjD,EACD,IAAI,GAAE,OAA0B,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAkCrD"}

package/dist/integrity.json

@@ -1,9 +1,9 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "8097252bf7eb52757c71e36712881bf6875fb6ee8402720d09e76fc610673b2f",
+    "manifest.json": "90960c725f3d0ece08fdfa0ef23e5d796094f41c4ee9ead658e6657d53ab7e1e",
     "meta.json": "e46e65ba7544fafc6dbb3fd48b841904b5ae6f7cb4d517a940ed68b01626c097",
     "types/index.d.ts": "07f5d04d0d3831cae053b1f0f5dd661c58e9708f45067a0fc85dd94079ac144b"
   },
-  "composite": "3a126dd75324cc55919dbdd7ab7ef3eec0c1db50115daa0d8a702d5e6570cb1c"
+  "composite": "f1bba49b606cb7bb617816ebfb6a0cfe0c9a8e04478bb27a93cd2f426d69abf4"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "fly",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "chantVersion": ">=0.1.0",
   "namespace": "Fly"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-fly",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "type": "module",
   "files": [
     "src/",
@@ -57,7 +57,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.28.0",
+    "@intentius/chant": "^0.30.0",
     "typescript": "^5.9.3"
   },
   "description": "Google Cloud lexicon for chant — declarative IaC in TypeScript",

package/src/describe-resources.test.ts

@@ -1,4 +1,5 @@
 import { describe, test, expect } from "vitest";
+import { describeObservationConformance } from "@intentius/chant-test-utils";
 import { describeResources, flyPlan } from "./describe-resources";
 import type { FlyHttp } from "./op/activities/fly-apply";
 
@@ -72,21 +73,21 @@ describe("describeResources: live machines → ResourceMetadata verdicts", () =>
     );
 
     // Declared machine keyed by its entity name; orphan keyed by its live name.
-    expect(res.web.type).toBe("Fly::Machines::Machine");
-    expect(res.web.ownership).toBe("owned");
-    expect(res.web.physicalId).toBe("m-web");
-    expect(res.web.status).toBe("started");
-    expect((res.web.attributes as { config?: unknown }).config).toEqual({
+    expect(res.resources.web.type).toBe("Fly::Machines::Machine");
+    expect(res.resources.web.ownership).toBe("owned");
+    expect(res.resources.web.physicalId).toBe("m-web");
+    expect(res.resources.web.status).toBe("started");
+    expect((res.resources.web.attributes as { config?: unknown }).config).toEqual({
       image: "nginx:1",
       metadata: { "managed-by": "chant" },
     });
 
-    expect(res.legacy.ownership).toBe("foreign");
-    expect(res.legacy.type).toBe("Fly::Machines::Machine");
+    expect(res.resources.legacy.ownership).toBe("foreign");
+    expect(res.resources.legacy.type).toBe("Fly::Machines::Machine");
 
     // App surfaced as owned (app-boundary: it carries an owned machine).
-    expect(res.app.type).toBe("Fly::Machines::App");
-    expect(res.app.ownership).toBe("owned");
+    expect(res.resources.app.type).toBe("Fly::Machines::App");
+    expect(res.resources.app.ownership).toBe("owned");
   });
 
   test("the owned filter drops foreign entries", async () => {
@@ -98,8 +99,8 @@ describe("describeResources: live machines → ResourceMetadata verdicts", () =>
       { environment: "prod", buildOutput: PLAN, entityNames: ["app", "web"], entities: ENTS, owned: true, endpoint: ENDPOINT },
       http,
     );
-    expect(res.web?.ownership).toBe("owned");
-    expect(res.legacy).toBeUndefined(); // foreign machine filtered out
+    expect(res.resources.web?.ownership).toBe("owned");
+    expect(res.resources.legacy).toBeUndefined(); // foreign machine filtered out
   });
 
   test("terminal machines (destroyed/destroying) are not reported live", async () => {
@@ -111,8 +112,8 @@ describe("describeResources: live machines → ResourceMetadata verdicts", () =>
       { environment: "prod", buildOutput: PLAN, entityNames: ["app", "web"], entities: ENTS, endpoint: ENDPOINT },
       http,
     );
-    expect(res.web).toBeDefined();
-    expect(res.gone).toBeUndefined();
+    expect(res.resources.web).toBeDefined();
+    expect(res.resources.gone).toBeUndefined();
   });
 
   test("empty build output returns nothing", async () => {
@@ -120,7 +121,27 @@ describe("describeResources: live machines → ResourceMetadata verdicts", () =>
       { environment: "prod", buildOutput: "", entityNames: [], entities: new Map(), endpoint: ENDPOINT },
       fakeHttp([]),
     );
-    expect(res).toEqual({});
+    expect(res.resources).toEqual({});
+  });
+
+  test("with no readable plan, declared entities are unobserved rather than absent (#1089)", async () => {
+    const res = await describeResources(
+      { environment: "prod", buildOutput: "", entityNames: ["web"], entities: ENTS, endpoint: ENDPOINT },
+      fakeHttp([]),
+    );
+    expect(res.resources).toEqual({});
+    expect(res.unobserved?.web?.reason).toBe("read-failed");
+    expect(res.unobserved?.app?.reason).toBe("read-failed");
+  });
+
+  test("the owned filter records a withheld declared machine as `filtered`, not absent (#1089)", async () => {
+    const http = fakeHttp([liveMachine("web", "nginx:1", { id: "m-web", owned: false })]);
+    const res = await describeResources(
+      { environment: "prod", buildOutput: PLAN, entityNames: ["app", "web"], entities: ENTS, owned: true, endpoint: ENDPOINT },
+      http,
+    );
+    expect(res.resources.web).toBeUndefined();
+    expect(res.unobserved?.web?.reason).toBe("filtered");
   });
 });
 
@@ -185,4 +206,56 @@ describe("flyPlan: declared-vs-live change set (create/noop/delete/adopt)", () =
     );
     expect(changeSet.entries.find((e) => e.name === "web")?.action).toBe("update");
   });
+
+  test("an unreadable plan makes every declared entity unobserved, not a create (#1089)", async () => {
+    const { changeSet } = await flyPlan(
+      { environment: "prod", buildOutput: "not json", entityNames: [...ENTS.keys()], entities: ENTS, endpoint: ENDPOINT },
+      fakeHttp([]),
+    );
+    expect(changeSet.entries.map((e) => e.action)).toEqual(["unobserved", "unobserved"]);
+  });
+});
+
+// The shared conformance suite (#1089).
+describeObservationConformance({
+  lexicon: "fly",
+  scenarios: [
+    {
+      name: "a build output that is not a readable fly plan",
+      declared: ["app", "web"],
+      expectUnobserved: ["app", "web"],
+      run: () =>
+        describeResources(
+          { environment: "prod", buildOutput: "{{ not json", entityNames: ["app", "web"], entities: ENTS, endpoint: ENDPOINT },
+          fakeHttp([]),
+        ),
+    },
+    {
+      name: "the owned filter withholding a declared machine",
+      declared: ["app", "web"],
+      expectUnobserved: ["web"],
+      run: () =>
+        describeResources(
+          {
+            environment: "prod",
+            buildOutput: PLAN,
+            entityNames: ["app", "web"],
+            entities: ENTS,
+            owned: true,
+            endpoint: ENDPOINT,
+          },
+          fakeHttp([liveMachine("web", "nginx:1", { owned: false })]),
+        ),
+    },
+    {
+      name: "a healthy read",
+      declared: ["app", "web"],
+      expectPresent: ["app", "web"],
+      run: () =>
+        describeResources(
+          { environment: "prod", buildOutput: PLAN, entityNames: ["app", "web"], entities: ENTS, endpoint: ENDPOINT },
+          fakeHttp([liveMachine("web", "nginx:1")]),
+        ),
+    },
+  ],
 });

package/src/op/activities/describe-resources.integration.test.ts

@@ -77,15 +77,15 @@ describe("describeResources against live mudflaps (#767)", () => {
 
     // 3. describeResources sees web owned, legacy foreign.
     const live = await describeResources({ environment: "it", buildOutput, entityNames: [...ents.keys()], entities: ents, endpoint });
-    expect(live.web?.ownership).toBe("owned");
-    expect(live.web?.status).toBe("started");
-    expect(live.legacy?.ownership).toBe("foreign");
-    expect(live.app?.ownership).toBe("owned"); // app-boundary: carries an owned machine
+    expect(live.resources.web?.ownership).toBe("owned");
+    expect(live.resources.web?.status).toBe("started");
+    expect(live.resources.legacy?.ownership).toBe("foreign");
+    expect(live.resources.app?.ownership).toBe("owned"); // app-boundary: carries an owned machine
 
     // 4. The owned filter drops the unmarked machine.
     const ownedOnly = await describeResources({ environment: "it", buildOutput, entityNames: [...ents.keys()], entities: ents, owned: true, endpoint });
-    expect(ownedOnly.web?.ownership).toBe("owned");
-    expect(ownedOnly.legacy).toBeUndefined();
+    expect(ownedOnly.resources.web?.ownership).toBe("owned");
+    expect(ownedOnly.resources.legacy).toBeUndefined();
 
     // 5. Drop "web" from the declared plan. The plan now classifies the live
     //    owned "web" as a delete; the unmarked "legacy" stays adopt (never delete).