@pithy-sh/cloudflare 0.1.1 → 0.1.3

package/dist/test-utils/fixtureReportSetup.js

@@ -0,0 +1,30 @@
+import { reportFixtureEstate } from "./fixtures.js";
+//#region src/test-utils/fixtureReportSetup.ts
+/**
+* The `globalSetup` for an integration config whose suites **create nothing** — the fixture report, and
+* no debris sweep.
+*
+* `integrationSetup.ts` beside this does both, and it is the right entry point for a package that mints
+* a Worker, a database or a bucket. A package whose live suites only *read* a third party — a token
+* endpoint, a siteverify — has nothing to reclaim, and pointing it at the sweeping setup would mean
+* every run of it deleted stale resources across the whole account on behalf of suites it does not run.
+* That is somebody else's housekeeping, done at a surprising moment, and it costs a run half a minute
+* of REST calls that answer nothing about the code under test.
+*
+* The report half is not optional either way, which is the whole reason this file exists rather than
+* the config simply declaring no `globalSetup`. Vitest runs no hooks inside a `describe.skipIf(true)`,
+* so a suite that skips for want of a fixture is exactly the suite that cannot say which fixture — see
+* the long note in `fixtures.ts`. A config with no `globalSetup` gets a silent skip, and a silent skip
+* is the failure mode #106 exists to remove.
+*
+* **Switch a config to `integrationSetup` the moment one of its suites creates a Cloudflare resource.**
+* A suite that mints and a run that never sweeps is how debris becomes permanent.
+*
+* Never throws, for the same reason its neighbor does not: a report that fails the run it was meant to
+* explain is worse than no report.
+*/
+function setup() {
+	reportFixtureEstate();
+}
+//#endregion
+export { setup as default };

package/dist/test-utils/fixtures.d.ts

@@ -0,0 +1,224 @@
+/**
+ * The live test fixture estate: which real-world things a live suite needs, whether this run has them,
+ * and what a run says when it does not.
+ *
+ * ## Absent means skip, never fail
+ *
+ * A contributor with no Cloudflare account, no Turnstile widget and no zone must be able to run the
+ * whole suite and get green. That is the rule, and both ways of getting it subtly wrong are worse than
+ * having no helper at all. A gate that **throws** on a missing fixture turns "you have no credentials"
+ * into "the kit is broken", and every one of those costs somebody an afternoon proving it is not. A gate
+ * that **silently passes** turns "nothing ran" into "everything is fine", which is how a release gate
+ * comes to certify a suite that has never executed.
+ *
+ * So the skip is loud. {@link reportFixtureEstate} runs from `globalSetup` — once per run, before a
+ * single suite is collected — and prints a line per fixture naming what is missing, what will therefore
+ * skip, and the document that creates it. The `describe.skipIf` in a suite is only the mechanism; this
+ * report is the sentence a human reads.
+ *
+ * **From `globalSetup` for the same reason the debris sweep is** (see `integrationSetup.ts`): Vitest runs
+ * no hooks inside a `describe.skipIf(true)`, so anything living in a suite hook is gated on exactly the
+ * condition it exists to report. A report that goes quiet precisely when there is something to say is
+ * not a report.
+ *
+ * ## A value never appears
+ *
+ * These names resolve API tokens, OAuth client secrets and Turnstile secret keys. A line here names the
+ * **variable** and never its contents, in every outcome — including the malformed ones, where the
+ * temptation to print what was found is strongest. `fixtures.test.ts` plants a distinctive value and
+ * asserts no report line contains it.
+ */
+/**
+ * How a fixture's value is judged.
+ *
+ * `credential` — any usable text is the fixture. An account id, a token, a zone id, a sitekey.
+ *
+ * `switch` — a deliberate opt-in, where the *word* is the whole meaning. `PITHY_LIVE_DEPLOY` is the one
+ * that matters: it arms a suite that deploys real Workers and deletes them again, so `0` has to mean no
+ * rather than "a non-empty string, therefore yes". Judging it as a credential is not a style choice —
+ * it is the difference between an opt-out and a deploy.
+ */
+export type FixtureShape = "credential" | "switch";
+/** One live fixture: what it is, where its value comes from, what skips without it, and how to make it. */
+export interface LiveFixture {
+    /** The fixture's name — what a skip line says, and the anchor its documentation lives under. */
+    name: string;
+    /** Every environment variable that must resolve before the fixture is usable. All of them, not any. */
+    keys: readonly string[];
+    /** How the value is judged. See {@link FixtureShape}. */
+    shape: FixtureShape;
+    /**
+     * What a run loses without it, as a whole sentence — "Turnstile sign-in gating (#84) skips."
+     *
+     * A sentence rather than a noun phrase, because the report is read by somebody deciding whether the
+     * green they just got means anything, and "the Custom Hostnames lifecycle" does not answer that.
+     */
+    consequence: string;
+    /** The document section that creates it. Must exist; `fixtures.test.ts` proves every one of them does. */
+    doc: string;
+}
+/**
+ * What this run has, per fixture.
+ *
+ * Four outcomes rather than a boolean, because three different things skip a suite and only one of them
+ * is fine. **`absent`** is the contributor with no credentials, and is the normal case. **`declined`** is
+ * a switch deliberately turned off. **`malformed`** is somebody who tried to set the fixture and failed —
+ * a CI export of an unset secret, a shell interpolation that produced the literal text `undefined`.
+ *
+ * All three skip. Only the reporting differs, and that is the whole point: #323 landed the same
+ * distinction one layer down — *"'not recorded' is a claim about the file, and it is now made only when
+ * the file makes no claim"* — after two investigations died inside a "missing" that meant "malformed".
+ * A fixture blanked by a broken export must not read as a fixture nobody configured.
+ */
+export type FixtureOutcome = "present" | "absent" | "malformed" | "declined";
+/** A fixture, resolved against one environment. */
+export interface FixtureResolution {
+    /** The fixture that was resolved. */
+    fixture: LiveFixture;
+    /** The fixture's outcome — the worst of its keys'. */
+    outcome: FixtureOutcome;
+    /** True only for `present`. The boolean a `describe.skipIf` negates. */
+    ready: boolean;
+    /** One sentence naming the offending variables and their state. Never a value. */
+    reason: string;
+}
+/**
+ * The estate, declared once.
+ *
+ * Every live fixture the repository knows about, whether or not a suite reads it yet — a fixture that
+ * exists only in the head of whoever wrote the suite is a fixture nobody can be told to create. The
+ * `consequence` line names the issue, so the report is a to-do list for anyone who wants a red X to become
+ * a run.
+ *
+ * Alphabetical, as the reap plan is, so the set reads as a list rather than as an accident of the order
+ * somebody happened to add things in.
+ */
+export declare const LIVE_FIXTURES: {
+    readonly "cloudflare-account": {
+        readonly name: "cloudflare-account";
+        readonly keys: readonly ["CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_API_TOKEN"];
+        readonly shape: "credential";
+        readonly consequence: "Every live suite skips, and the run sweeps no debris.";
+        readonly doc: "docs/FIXTURES.md#cloudflare-account";
+    };
+    readonly "custom-hostname-zones": {
+        readonly name: "custom-hostname-zones";
+        readonly keys: readonly ["CUSTOM_HOSTNAME_ZONE_ID", "CUSTOM_HOSTNAME_CUSTOMER_ZONE_ID"];
+        readonly shape: "credential";
+        readonly consequence: "The Custom Hostnames lifecycle (#41) skips.";
+        readonly doc: "docs/FIXTURES.md#custom-hostname-zones";
+    };
+    readonly "email-routing": {
+        readonly name: "email-routing";
+        readonly keys: readonly ["EMAIL_ROUTING_ZONE_ID", "EMAIL_ROUTING_ADDRESS"];
+        readonly shape: "credential";
+        readonly consequence: "The inbound Email Routing rule (#47) skips.";
+        readonly doc: "docs/FIXTURES.md#email-routing";
+    };
+    readonly "email-sending": {
+        readonly name: "email-sending";
+        readonly keys: readonly ["EMAIL_SENDING_FROM"];
+        readonly shape: "credential";
+        readonly consequence: "The inbound delivery round trip (#47) skips: nothing can post a message to the routed address.";
+        readonly doc: "docs/FIXTURES.md#email-sending";
+    };
+    readonly "google-oauth": {
+        readonly name: "google-oauth";
+        readonly keys: readonly ["GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET"];
+        readonly shape: "credential";
+        readonly consequence: "The Google provider suite, on localhost (#84), skips.";
+        readonly doc: "docs/FIXTURES.md#google-oauth";
+    };
+    readonly "live-deploy": {
+        readonly name: "live-deploy";
+        readonly keys: readonly ["PITHY_LIVE_DEPLOY"];
+        readonly shape: "switch";
+        readonly consequence: "The secrets provision, write, rotate and teardown round trip skips.";
+        readonly doc: "docs/FIXTURES.md#live-deploy";
+    };
+    readonly "r2-s3-keys": {
+        readonly name: "r2-s3-keys";
+        readonly keys: readonly ["R2_CREDENTIALS"];
+        readonly shape: "credential";
+        readonly consequence: "The R2 presigned-URL suite skips, and stale buckets are not reclaimed.";
+        readonly doc: "docs/FIXTURES.md#r2-s3-keys";
+    };
+    readonly "secrets-store": {
+        readonly name: "secrets-store";
+        readonly keys: readonly ["SECRETS_STORE_ID"];
+        readonly shape: "credential";
+        readonly consequence: "The Secrets Store suites skip, and stale entries are not reclaimed.";
+        readonly doc: "docs/FIXTURES.md#secrets-store";
+    };
+    readonly "turnstile-widget": {
+        readonly name: "turnstile-widget";
+        readonly keys: readonly ["TURNSTILE_SITE_KEY", "TURNSTILE_SECRET_KEY"];
+        readonly shape: "credential";
+        readonly consequence: "Turnstile sign-in gating on a workers.dev hostname (#84) skips.";
+        readonly doc: "docs/FIXTURES.md#turnstile-widget";
+    };
+};
+/** Every declared fixture name. A typo is a type error rather than a silently skipped suite. */
+export type FixtureName = keyof typeof LIVE_FIXTURES;
+/** How a fixture is resolved: from an injected environment, or from the run's own. */
+export interface FixtureOptions {
+    /**
+     * The environment to read. Defaults to {@link fixtureEnv}.
+     *
+     * A test passes its own, so a maintainer's real `.dev.vars` can never decide whether a unit test
+     * passes — the failure mode `vitest.setup.ts` exists to prevent, one level up.
+     */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * The environment a fixture resolves against: `packages/cloudflare/.dev.vars` first, then `process.env`.
+ *
+ * The same pair {@link loadIntegrationEnv} already reads for credentials, so a fixture and a credential
+ * cannot disagree about which file they came from. `.dev.vars` wins where both state a key, because a
+ * file somebody wrote on purpose beats a variable their shell exported hours ago.
+ */
+export declare function fixtureEnv(): Record<string, string | undefined>;
+/**
+ * Resolve one fixture against an environment.
+ *
+ * Never throws and never reaches the network. It answers what this run has; deciding what to do about it
+ * is {@link fixtureReady}'s job, and saying so out loud is {@link reportFixtureEstate}'s.
+ */
+export declare function resolveFixture(name: FixtureName, options?: FixtureOptions): FixtureResolution;
+/**
+ * Whether a suite gated on this fixture can run — the boolean a `describe.skipIf` negates:
+ *
+ * ```ts
+ * describe.skipIf(!fixtureReady("turnstile-widget"))("turnstile — LIVE", () => { … });
+ * ```
+ *
+ * False for every outcome that is not `present`, malformed included. The distinction between a fixture
+ * nobody configured and one somebody configured wrongly belongs in the report, not in whether the suite
+ * runs: neither can be tested against, and a run that failed on the second would fail a contributor
+ * whose CI template exports blanks — the same "the kit is broken" this file exists to prevent.
+ */
+export declare function fixtureReady(name: FixtureName, options?: FixtureOptions): boolean;
+/**
+ * One of a ready fixture's values.
+ *
+ * Throws when the fixture is not ready, and that is not a contradiction of the rule above: reaching here
+ * means a suite read a value it never gated on, which is a defect in the suite rather than a missing
+ * credential. The error names the key and never carries a value — `detail` reaches a log.
+ */
+export declare function fixtureValue(name: FixtureName, key: string, options?: FixtureOptions): string;
+/**
+ * The lines a run prints about its fixtures — pure, so a test reads exactly what a human would.
+ *
+ * One line per fixture, then a count. A present fixture still gets a line: a report that only speaks when
+ * something is wrong cannot tell "the estate is complete" from "the report never ran", and that is the
+ * same indistinguishability this whole file is about.
+ */
+export declare function fixtureReportLines(resolutions: readonly FixtureResolution[]): string[];
+/**
+ * Resolve every fixture, say what the run has, and hand back the resolutions.
+ *
+ * The `globalSetup` entry point. Never throws — a report that fails the run it was meant to explain is
+ * worse than no report, exactly as the debris sweep beside it is.
+ */
+export declare function reportFixtureEstate(options?: FixtureOptions): FixtureResolution[];
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/test-utils/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../src/test-utils/fixtures.ts"],"names":[],"mappings":"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"}

package/dist/test-utils/fixtures.js

@@ -0,0 +1,277 @@
+import { loadIntegrationEnv } from "./harness.js";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+//#region src/test-utils/fixtures.ts
+/** Words a switch reads as on. Case-insensitive. */
+const SWITCH_ON = /* @__PURE__ */ new Set([
+	"1",
+	"true",
+	"yes",
+	"on"
+]);
+/** Words a switch reads as off — a deliberate decline, not a misconfiguration. */
+const SWITCH_OFF = /* @__PURE__ */ new Set([
+	"0",
+	"false",
+	"no",
+	"off"
+]);
+/**
+* Text a value must never be, whatever its shape.
+*
+* These are not values. They are what a templating layer writes when it had nothing: `export
+* KEY=$MISSING` under some shells, a JSON `null` stringified, a GitHub Actions expression that resolved
+* to nothing and got quoted anyway. Each is a non-empty string, so every `Boolean(value)` check in the
+* world reads it as present and hands it to Cloudflare, which answers 401 three frames later.
+*/
+const PLACEHOLDER_TEXT = /* @__PURE__ */ new Set(["undefined", "null"]);
+/** Worst-first, so folding a fixture's keys is a `Math.min` over this order. */
+const OUTCOME_RANK = {
+	malformed: 0,
+	absent: 1,
+	declined: 2,
+	present: 3
+};
+/**
+* The estate, declared once.
+*
+* Every live fixture the repository knows about, whether or not a suite reads it yet — a fixture that
+* exists only in the head of whoever wrote the suite is a fixture nobody can be told to create. The
+* `consequence` line names the issue, so the report is a to-do list for anyone who wants a red X to become
+* a run.
+*
+* Alphabetical, as the reap plan is, so the set reads as a list rather than as an accident of the order
+* somebody happened to add things in.
+*/
+const LIVE_FIXTURES = {
+	"cloudflare-account": {
+		name: "cloudflare-account",
+		keys: ["CLOUDFLARE_ACCOUNT_ID", "CLOUDFLARE_API_TOKEN"],
+		shape: "credential",
+		consequence: "Every live suite skips, and the run sweeps no debris.",
+		doc: "docs/FIXTURES.md#cloudflare-account"
+	},
+	"custom-hostname-zones": {
+		name: "custom-hostname-zones",
+		keys: ["CUSTOM_HOSTNAME_ZONE_ID", "CUSTOM_HOSTNAME_CUSTOMER_ZONE_ID"],
+		shape: "credential",
+		consequence: "The Custom Hostnames lifecycle (#41) skips.",
+		doc: "docs/FIXTURES.md#custom-hostname-zones"
+	},
+	"email-routing": {
+		name: "email-routing",
+		keys: ["EMAIL_ROUTING_ZONE_ID", "EMAIL_ROUTING_ADDRESS"],
+		shape: "credential",
+		consequence: "The inbound Email Routing rule (#47) skips.",
+		doc: "docs/FIXTURES.md#email-routing"
+	},
+	"email-sending": {
+		name: "email-sending",
+		keys: ["EMAIL_SENDING_FROM"],
+		shape: "credential",
+		consequence: "The inbound delivery round trip (#47) skips: nothing can post a message to the routed address.",
+		doc: "docs/FIXTURES.md#email-sending"
+	},
+	"google-oauth": {
+		name: "google-oauth",
+		keys: ["GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET"],
+		shape: "credential",
+		consequence: "The Google provider suite, on localhost (#84), skips.",
+		doc: "docs/FIXTURES.md#google-oauth"
+	},
+	"live-deploy": {
+		name: "live-deploy",
+		keys: ["PITHY_LIVE_DEPLOY"],
+		shape: "switch",
+		consequence: "The secrets provision, write, rotate and teardown round trip skips.",
+		doc: "docs/FIXTURES.md#live-deploy"
+	},
+	"r2-s3-keys": {
+		name: "r2-s3-keys",
+		keys: ["R2_CREDENTIALS"],
+		shape: "credential",
+		consequence: "The R2 presigned-URL suite skips, and stale buckets are not reclaimed.",
+		doc: "docs/FIXTURES.md#r2-s3-keys"
+	},
+	"secrets-store": {
+		name: "secrets-store",
+		keys: ["SECRETS_STORE_ID"],
+		shape: "credential",
+		consequence: "The Secrets Store suites skip, and stale entries are not reclaimed.",
+		doc: "docs/FIXTURES.md#secrets-store"
+	},
+	"turnstile-widget": {
+		name: "turnstile-widget",
+		keys: ["TURNSTILE_SITE_KEY", "TURNSTILE_SECRET_KEY"],
+		shape: "credential",
+		consequence: "Turnstile sign-in gating on a workers.dev hostname (#84) skips.",
+		doc: "docs/FIXTURES.md#turnstile-widget"
+	}
+};
+/**
+* The environment a fixture resolves against: `packages/cloudflare/.dev.vars` first, then `process.env`.
+*
+* The same pair {@link loadIntegrationEnv} already reads for credentials, so a fixture and a credential
+* cannot disagree about which file they came from. `.dev.vars` wins where both state a key, because a
+* file somebody wrote on purpose beats a variable their shell exported hours ago.
+*/
+function fixtureEnv() {
+	return {
+		...process.env,
+		...loadIntegrationEnv()
+	};
+}
+/** Judge one variable, with no knowledge of the fixture it belongs to. */
+function verdictFor(key, shape, raw) {
+	if (raw === void 0) return {
+		key,
+		outcome: "absent",
+		note: "is not set"
+	};
+	if (raw === "") return {
+		key,
+		outcome: "malformed",
+		note: "is set to an empty value"
+	};
+	const value = raw.trim();
+	if (value === "") return {
+		key,
+		outcome: "malformed",
+		note: "is set to whitespace"
+	};
+	if (PLACEHOLDER_TEXT.has(value.toLowerCase())) return {
+		key,
+		outcome: "malformed",
+		note: "is set to placeholder text, not a value"
+	};
+	if (shape === "switch") {
+		const word = value.toLowerCase();
+		if (SWITCH_ON.has(word)) return {
+			key,
+			outcome: "present",
+			note: "is on"
+		};
+		if (SWITCH_OFF.has(word)) return {
+			key,
+			outcome: "declined",
+			note: "is off"
+		};
+		return {
+			key,
+			outcome: "malformed",
+			note: "is set to a word that is neither on nor off"
+		};
+	}
+	return {
+		key,
+		outcome: "present",
+		note: "is set"
+	};
+}
+/** Fold a fixture's keys into one outcome: the worst wins, so one broken key is never averaged away. */
+function foldOutcome(verdicts) {
+	let worst = "present";
+	for (const verdict of verdicts) if (OUTCOME_RANK[verdict.outcome] < OUTCOME_RANK[worst]) worst = verdict.outcome;
+	return worst;
+}
+/** The sentence for a fixture's outcome: every key in the offending state, and what state that is. */
+function reasonFor(outcome, verdicts) {
+	if (outcome === "present") return "Ready.";
+	const offenders = verdicts.filter((verdict) => verdict.outcome === outcome);
+	const note = offenders[0]?.note ?? "is not set";
+	return `${offenders.map((verdict) => verdict.key).join(", ")} ${offenders.length === 1 ? note : note.replace(/^is /, "are ")}.`;
+}
+/**
+* Resolve one fixture against an environment.
+*
+* Never throws and never reaches the network. It answers what this run has; deciding what to do about it
+* is {@link fixtureReady}'s job, and saying so out loud is {@link reportFixtureEstate}'s.
+*/
+function resolveFixture(name, options = {}) {
+	const fixture = LIVE_FIXTURES[name];
+	const env = options.env ?? fixtureEnv();
+	const verdicts = fixture.keys.map((key) => verdictFor(key, fixture.shape, env[key]));
+	const outcome = foldOutcome(verdicts);
+	return {
+		fixture,
+		outcome,
+		ready: outcome === "present",
+		reason: reasonFor(outcome, verdicts)
+	};
+}
+/**
+* Whether a suite gated on this fixture can run — the boolean a `describe.skipIf` negates:
+*
+* ```ts
+* describe.skipIf(!fixtureReady("turnstile-widget"))("turnstile — LIVE", () => { … });
+* ```
+*
+* False for every outcome that is not `present`, malformed included. The distinction between a fixture
+* nobody configured and one somebody configured wrongly belongs in the report, not in whether the suite
+* runs: neither can be tested against, and a run that failed on the second would fail a contributor
+* whose CI template exports blanks — the same "the kit is broken" this file exists to prevent.
+*/
+function fixtureReady(name, options = {}) {
+	return resolveFixture(name, options).ready;
+}
+/**
+* One of a ready fixture's values.
+*
+* Throws when the fixture is not ready, and that is not a contradiction of the rule above: reaching here
+* means a suite read a value it never gated on, which is a defect in the suite rather than a missing
+* credential. The error names the key and never carries a value — `detail` reaches a log.
+*/
+function fixtureValue(name, key, options = {}) {
+	const fixture = LIVE_FIXTURES[name];
+	if (!fixture.keys.includes(key)) throw new ValidationError({
+		message: `Fixture ${name} declares no ${key}.`,
+		action: `Read one of: ${fixture.keys.join(", ")}.`,
+		detail: `fixtureValue was asked for ${key}, which is not in the ${name} fixture's keys.`
+	});
+	const resolution = resolveFixture(name, options);
+	if (!resolution.ready) throw new ValidationError({
+		message: `Fixture ${name} is ${resolution.outcome}.`,
+		action: `Gate the suite with fixtureReady("${name}"), or create the fixture: ${fixture.doc}.`,
+		detail: `${resolution.reason} A suite read a fixture value it had not gated on.`
+	});
+	return ((options.env ?? fixtureEnv())[key] ?? "").trim();
+}
+/**
+* The lines a run prints about its fixtures — pure, so a test reads exactly what a human would.
+*
+* One line per fixture, then a count. A present fixture still gets a line: a report that only speaks when
+* something is wrong cannot tell "the estate is complete" from "the report never ran", and that is the
+* same indistinguishability this whole file is about.
+*/
+function fixtureReportLines(resolutions) {
+	const lines = resolutions.map((resolution) => {
+		if (resolution.ready) return `fixture present: ${resolution.fixture.name}.`;
+		return [
+			`fixture ${resolution.outcome}: ${resolution.fixture.name}.`,
+			resolution.reason,
+			resolution.fixture.consequence,
+			`See ${resolution.fixture.doc}.`
+		].join(" ");
+	});
+	const counted = (outcome) => resolutions.filter((entry) => entry.outcome === outcome).length;
+	lines.push(`fixtures: ${counted("present")} present, ${counted("absent")} absent, ${counted("malformed")} malformed, ${counted("declined")} declined. A skipped suite is not a passing one.`);
+	return lines;
+}
+/**
+* Resolve every fixture, say what the run has, and hand back the resolutions.
+*
+* The `globalSetup` entry point. Never throws — a report that fails the run it was meant to explain is
+* worse than no report, exactly as the debris sweep beside it is.
+*/
+function reportFixtureEstate(options = {}) {
+	let resolutions = [];
+	try {
+		const env = options.env ?? fixtureEnv();
+		resolutions = Object.keys(LIVE_FIXTURES).map((name) => resolveFixture(name, { env }));
+		for (const line of fixtureReportLines(resolutions)) console.warn(line);
+	} catch (error) {
+		console.warn(`the fixture estate could not be reported: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	return resolutions;
+}
+//#endregion
+export { LIVE_FIXTURES, fixtureEnv, fixtureReady, fixtureReportLines, fixtureValue, reportFixtureEstate, resolveFixture };