@tokenoftrust/storefront-runner 3.10.4 → 3.11.0

package/apps/storefront/src/components/compliance/storefront/islands/CheckoutComplianceGate.tsx

@@ -25,6 +25,7 @@
 import { useCallback, useEffect, useRef, useState } from "preact/hooks";
 import type { CartComplianceDecision } from "@tot/public-runtime";
 import {
+  bypassesComplianceGate,
   clearStoredRef,
   isStoreNotPublicRefusal,
   parsePreflightResponse,
@@ -118,6 +119,8 @@ export default function CheckoutComplianceGate({ preflightUrl, minAge }: Props)
   const pollToken = useRef<{ cancelled: boolean } | null>(null);
   /** Set by the last preflight POST when the store-not-public gate answered it. */
   const gateRefused = useRef(false);
+  /** `proceed`, reachable from the submit listener registered before it is defined. */
+  const proceedRef = useRef<((line: PendingLine, ref: string | null) => void) | null>(null);
 
   const stopPolling = useCallback(() => {
     if (pollToken.current) pollToken.current.cancelled = true;
@@ -144,6 +147,32 @@ export default function CheckoutComplianceGate({ preflightUrl, minAge }: Props)
         quantity,
         title: form.dataset.productTitle ?? "this item",
       };
+      // Whether the store asks for this step is the server's call at click time, read from the
+      // store's current settings: a static page carries no decision frozen at build time. Only a
+      // readable "not-required" + clear answer skips the dialog; anything else opens it.
+      void probe(line).then((res) => {
+        if (bypassesComplianceGate(res)) proceedRef.current?.(line, null);
+        else open(line);
+      });
+    }
+    async function probe(line: PendingLine): Promise<PreflightResponse | null> {
+      try {
+        const res = await fetch(preflightUrl, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            lines: [{ handle: line.handle, sku: line.sku, variantId: line.variantId, quantity: line.quantity }],
+            destination: null,
+            ageAffirmed: false,
+          }),
+        });
+        if (!res.ok) return null;
+        return parsePreflightResponse(await res.json());
+      } catch {
+        return null;
+      }
+    }
+    function open(line: PendingLine) {
       setPending(line);
       setDecision(null);
       setError(null);
@@ -200,6 +229,7 @@ export default function CheckoutComplianceGate({ preflightUrl, minAge }: Props)
     if (typeof line.form.requestSubmit === "function") line.form.requestSubmit();
     else line.form.submit();
   }, [preflightUrl, stopPolling]);
+  proceedRef.current = proceed;
 
   /**
    * One preflight POST. `null` for a transport error or any body we cannot fully

package/apps/storefront/src/lib/checkout/browser/checkoutRequirementsForm.ts

@@ -3,16 +3,31 @@
 type StatusState = "ok" | "err";
 
 interface SaveResponse {
+  readBack?: string;
   notice?: string;
   error?: string;
   errors?: unknown;
 }
 
+export const SAVED_IN_EFFECT = "Saved. In effect on your preview and live store.";
+
 export function saveFailureMessage(status: number, data: SaveResponse): string {
   if (Array.isArray(data.errors) && data.errors.length) return data.errors.join(" ");
   return data.error || `Save failed (${status})`;
 }
 
+/**
+ * What the form reports for a save response. "Saved" only when the server read the save back
+ * through the readers' own resolver (`readBack: "in-effect"`); an accepted save the edge has not
+ * picked up yet reports its notice without the ok state.
+ */
+export function saveResultStatus(httpOk: boolean, status: number, data: SaveResponse): { message: string; state?: StatusState } {
+  if (!httpOk) return { message: saveFailureMessage(status, data), state: "err" };
+  if (data.readBack === "in-effect") return { message: SAVED_IN_EFFECT, state: "ok" };
+  if (data.readBack === "pending") return { message: data.notice || "Accepted. Reload to confirm it is in effect." };
+  return { message: "The save could not be confirmed in effect. Reload to check.", state: "err" };
+}
+
 export function mountCheckoutRequirementsForm(form: HTMLElement): void {
   const endpoint = form.dataset.endpoint || "/api/preview/checkout-requirements";
   const targetTenant = form.dataset.targetTenant || "";
@@ -43,8 +58,8 @@ export function mountCheckoutRequirementsForm(form: HTMLElement): void {
       } catch {
         // non-JSON error body
       }
-      if (res.ok) setStatus(data.notice || "Saved to test", "ok");
-      else setStatus(saveFailureMessage(res.status, data), "err");
+      const result = saveResultStatus(res.ok, res.status, data);
+      setStatus(result.message, result.state);
     } catch {
       setStatus("Save failed — network error", "err");
     } finally {

package/apps/storefront/src/lib/checkout/commerce/checkoutRequirements.ts

@@ -3,13 +3,14 @@
  * /admin → Settings → Checkout requirements.
  *
  * They are merchant-operated commerce settings (ADR 0035 "operational"), saved as the
- * tenant-owned artifact `tenants/<id>/checkout-requirements.json` on the publish spine — saved
- * to `test`, promoted to `live` with the rest of the store. Every switch defaults off and can
- * only make checkout stricter, so no write can weaken what the platform enforces. They apply
- * only while the store checks out on the shared test store; a store with its own checkout store,
- * and production, keep the full fail-closed contract regardless of what is saved here.
+ * tenant-owned artifact `tenants/<id>/checkout-requirements.json` to the store's operational
+ * selection. A save is in effect at once on the store's preview AND its live store — every
+ * reader resolves it through `resolveArtifactSelection`, with no promote. Every switch defaults
+ * off and can only make checkout stricter, so no write can weaken what the platform enforces.
+ * They apply only while the store checks out on the shared test store; a store with its own
+ * checkout store, and production, keep the full fail-closed contract regardless of what is saved here.
  */
-import { readPublishedArtifact, type CustomizationEnv } from "@tot/public-runtime";
+import { operationalSettingArtifactPath, readPublishedArtifact, type CustomizationEnv } from "@tot/public-runtime";
 import { readKv } from "@/lib/publication/shared/runtimeEnv";
 
 export interface CheckoutRequirements {
@@ -30,7 +31,7 @@ export const DEFAULT_CHECKOUT_REQUIREMENTS: Readonly<CheckoutRequirements> = Obj
 });
 
 export function checkoutRequirementsArtifactPath(tenantId: string): string {
-  return `tenants/${tenantId}/checkout-requirements.json`;
+  return operationalSettingArtifactPath(tenantId, "checkout-requirements.json");
 }
 
 /**

package/apps/storefront/src/lib/checkout/commerce/sharedStoreAdmission.ts

@@ -82,14 +82,10 @@ export async function usesSharedTestStore(commerce: { storeSubDomain?: string }
 }
 
 /**
- * Whether the storefront's checkout compliance gate runs before handoff. It follows the shared
- * test store's policy for a tenant checking out there; every other checkout keeps the gate.
+ * Whether the storefront's pre-cart compliance step runs, for a resolved policy. It follows the
+ * shared test store's policy for a tenant checking out there; `null` (every other checkout) keeps
+ * it. Decided per request by `/api/compliance/preflight`, never at page build time.
  */
-export async function checkoutComplianceGateRequired(
-  tenant: Pick<TenantConfig, "tenant_id">,
-  commerce: { storeSubDomain?: string } | null | undefined,
-  env: CustomizationEnv,
-): Promise<boolean> {
-  const policy = await sharedStorePolicy(tenant, commerce, env);
+export function complianceGateRequiredFor(policy: SharedStoreEvidencePolicy | null): boolean {
   return !policy || policy.rules === "enforce" || policy.verification === "required";
 }

package/apps/storefront/src/lib/compliance/browser/checkoutVerificationFlow.ts

@@ -52,6 +52,11 @@ export interface PreflightResponse {
   decision: CartComplianceDecision;
   /** Present only on the live-provider path; `null` on sandbox / no provider. */
   verification: LiveVerificationMeta | null;
+  /**
+   * Whether this store requires the pre-cart compliance step, decided by the server from the
+   * store's current settings at click time. Absent is read as `"required"`.
+   */
+  gate?: "required" | "not-required";
 }
 
 /**
@@ -117,9 +122,18 @@ export function parsePreflightResponse(raw: unknown): PreflightResponse | null {
   return {
     decision: r.decision,
     verification: "verification" in r ? parseVerificationMeta(r.verification) : null,
+    gate: r.gate === "not-required" ? "not-required" : "required",
   };
 }
 
+/**
+ * True when a click-time probe lets the item go straight to the cart: the store does not require
+ * the pre-cart step and the cart is already clear. Anything else, including no answer, opens it.
+ */
+export function bypassesComplianceGate(res: PreflightResponse | null): boolean {
+  return res !== null && res.gate === "not-required" && res.decision.status === "clear";
+}
+
 /** True when the decision carries the provider's real "did not pass" block. */
 function hasVerificationFailure(decision: CartComplianceDecision): boolean {
   return decision.blocks.some(

package/apps/storefront/src/pages/api/compliance/preflight.ts

@@ -34,7 +34,7 @@ import {
   type TotVerificationClient,
   type TotVerificationStatus,
 } from "@/lib/compliance/verification/totVerificationClient";
-import { sharedStorePolicy } from "@/lib/checkout/commerce/sharedStoreAdmission";
+import { complianceGateRequiredFor, sharedStorePolicy } from "@/lib/checkout/commerce/sharedStoreAdmission";
 
 export const prerender = false;
 
@@ -282,9 +282,12 @@ export async function POST(context: APIContext): Promise<Response> {
   }
 
   // The shared test store applies the store's own saved requirements, computed here from the
-  // tenant's config — never from the request, so a shopper cannot waive one.
+  // tenant's config — never from the request, so a shopper cannot waive one. `gate` tells the
+  // product page's checkout gate, at click time, whether the store asks for the pre-cart dialog
+  // at all, so a static page never carries a decision frozen at build time.
   const policy = await sharedStorePolicy(context.locals.tenant, context.locals.commerce, context.locals.customizationEnv);
-  return json(await evaluatePreflight(context, body, policy ? { verification: policy.verification, rules: policy.rules } : {}));
+  const gate = complianceGateRequiredFor(policy) ? "required" : "not-required";
+  return json({ ...(await evaluatePreflight(context, body, policy ? { verification: policy.verification, rules: policy.rules } : {})), gate });
 }
 
 export interface PreflightOptions {

package/apps/storefront/src/pages/products/[handle].astro

@@ -44,7 +44,6 @@ import type {
 import { resolveCartSigning, shopperCheckoutUnavailableHtml } from "@/lib/checkout/shared/checkoutCommerce";
 import { isLocalSampleCheckout } from "@/config/declaredTenantConfig";
 import { isRegulatedTenant } from "@/lib/compliance/enforcement";
-import { checkoutComplianceGateRequired } from "@/lib/checkout/commerce/sharedStoreAdmission";
 import { resolveMemberContext } from "@/lib/membership/eligibility";
 import { truncate } from "@/lib/content/shared/format";
 import { productLd, breadcrumbLd, reviewLd } from "@/lib/content/shared/jsonld";
@@ -240,7 +239,6 @@ let checkoutCart:
   | undefined;
 let checkoutUnavailable = false;
 const sampleHandoff = isLocalSampleCheckout(tenant.tenant_id);
-const complianceGateRequired = await checkoutComplianceGateRequired(tenant, commerce, Astro.locals.customizationEnv);
 if (commerce || sampleHandoff) {
   // Fail closed for production signed checkout: a signed tenant with no
   // cart-validation secret builds NO cart (never a tamperable form). See
@@ -434,9 +432,10 @@ const structuredData = {
         />
         {/* Regulated-tenant checkout ENFORCEMENT gate. Intercepts the
             managed-cart handoff to clear age + ship-to compliance server-side
-            before the external checkout. Only mounts when a store is wired, the
-            tenant is regulated, and that store's policy requires a check. */}
-        {checkoutCart && !sampleHandoff && isRegulatedTenant(tenant) && compliance?.minAge && complianceGateRequired && (
+            before the external checkout. Mounts when a store is wired and the
+            tenant is regulated; whether the store's policy asks for the dialog
+            is answered by preflight at click time, never frozen into this page. */}
+        {checkoutCart && !sampleHandoff && isRegulatedTenant(tenant) && compliance?.minAge && (
           <CheckoutComplianceGate
             client:load
             preflightUrl={withBase(apiBasePath, "/api/compliance/preflight")}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "3.10.4",
+  "version": "3.11.0",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/scripts/generate-managed-analytics-api-v1-schemas.mjs

@@ -9,8 +9,9 @@
 import { readdirSync, readFileSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, relative, resolve } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
 
+import { isMainModule } from "../../../scripts/lib/is-main-module.mjs";
 const here = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(here, "../../..");
 export const OUTPUT_DIR = relative(repoRoot, resolve(here, "../schemas/managed-analytics/v1"));
@@ -92,6 +93,6 @@ async function write() {
   for (const [path, text] of files) await writeFile(resolve(repoRoot, path), text, "utf8");
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+if (isMainModule(import.meta.url)) {
   await (process.argv.includes("--check") ? check() : write());
 }

package/packages/public-runtime/src/activity/catalog.ts

@@ -61,6 +61,14 @@ const HIGH_VOLUME: readonly ActivitySink[] = ["logs", "analytics"];
 const LIFECYCLE: readonly ActivitySink[] = ["logs", "timeline"];
 const PROVENANCE: readonly ActivitySink[] = ["logs", "analytics", "timeline"];
 
+// What an operational-setting save read back: which selection each env's reader resolved
+// (`readBackDiagnostics` in the storefront's operational-read-back.ts emits exactly these).
+const OPERATIONAL_READ_BACK_ARGS = [
+  "readBack",
+  "testSource", "testVersionId", "testMatches", "testRev",
+  "liveSource", "liveVersionId", "liveMatches", "liveRev",
+] as const;
+
 /**
  * THE CATALOG. Add a new action by adding a key here (and its JS mirror for the
  * CLI).
@@ -320,14 +328,14 @@ export const ACTION_CATALOG = {
     // route's own auth (resolveOwnerSession): a merchant saving their own tenant, or
     // a ToT-staff operator "operating as" another tenant via the admin picker.
     actors: ["merchant", "admin"], source: "server", sinks: LIFECYCLE,
-    argsAllow: ["versionId", "scope"], renderedAllow: [],
+    argsAllow: ["versionId", "scope", ...OPERATIONAL_READ_BACK_ARGS], renderedAllow: [],
     desc: "A tenant's checkout styling was saved to a version.",
   },
   "content.checkout_requirements.saved": {
     // A store's shared-test-store checkout requirements (Settings → Checkout requirements)
-    // were saved to a versioned test artifact. Same actors and spine as checkout styling.
+    // were saved to the store's operational selection. Same actors, spine and read-back args as checkout styling.
     actors: ["merchant", "admin"], source: "server", sinks: LIFECYCLE,
-    argsAllow: ["versionId", "scope"], renderedAllow: [],
+    argsAllow: ["versionId", "scope", ...OPERATIONAL_READ_BACK_ARGS], renderedAllow: [],
     desc: "A store's checkout requirements were saved to a version.",
   },
   "change.go_live": {

package/packages/public-runtime/src/checkout-style.ts

@@ -20,7 +20,7 @@
  */
 import type { CustomizationEnv } from "./customization-preview.js";
 import type { DeepPartial, ThemeTokens } from "./tenant.js";
-import { readPublishedArtifact, type KvGet } from "./customization-runtime.js";
+import { operationalSettingArtifactPath, readPublishedArtifact, type KvGet } from "./customization-runtime.js";
 
 /**
  * Color levers exposed on the checkout page. Deliberately a small, opinionated
@@ -187,7 +187,7 @@ function fontStackFromFamily(family: unknown, fallback: string): string {
  * per environment.
  */
 export function checkoutStyleArtifactPath(tenantId: string): string {
-  return `tenants/${tenantId}/checkout-style.json`;
+  return operationalSettingArtifactPath(tenantId, "checkout-style.json");
 }
 
 /**

package/packages/public-runtime/src/customization-runtime.ts

@@ -79,6 +79,67 @@ export function derivedArtifactPath(tenantId: string, name: string): string {
 /** The derived catalog listing projection (`catalogListingProjection` in the kit's catalog module). */
 export const CATALOG_LISTING_ARTIFACT = "catalog-listing.json";
 
+/**
+ * Operational settings (ADR 0035): records a merchant edits from /admin, in effect with no
+ * deploy and no promote. Each is saved to the store's operational selection (the pointer's
+ * per-path `test` selection) and read from there for EVERY env and channel, so a save is what the
+ * preview, the live store and the final-cart authority all read. A path not listed here is
+ * repo-authored content: a channel pointer, when engaged, owns it.
+ */
+export const OPERATIONAL_SETTING_FILES = Object.freeze(["checkout-requirements.json", "checkout-style.json"] as const);
+export type OperationalSettingFile = (typeof OPERATIONAL_SETTING_FILES)[number];
+
+export function operationalSettingArtifactPath(tenantId: string, file: OperationalSettingFile): string {
+  return `tenants/${tenantId}/${file}`;
+}
+
+export function isOperationalSettingPath(path: string): boolean {
+  const match = /^tenants\/[^/]+\/([^/]+)$/.exec(path);
+  return match?.[1] !== undefined && (OPERATIONAL_SETTING_FILES as readonly string[]).includes(match[1]);
+}
+
+/**
+ * Which selection a reader of (env, path) consults on `pointer`:
+ *   - `operational`: an operational setting the store has saved — the same selection for every env;
+ *   - `channel`: the channel's immutable site version (authoritative once engaged);
+ *   - `legacy`: the per-path selection of a tenant not cut over to channels.
+ * `null` when nothing is selected. Readers ({@link resolvePublishedArtifactKey}) and the writer
+ * (`publishToTest`, which refuses a save this does not select) both resolve through it.
+ */
+export type ArtifactSelection =
+  | { source: "operational"; versionId: string }
+  | { source: "channel"; channel: ChannelName }
+  | { source: "legacy"; env: CustomizationEnv; versionId: string };
+
+export function resolveArtifactSelection(
+  pointer: PointerRecord,
+  env: CustomizationEnv,
+  path: string,
+): ArtifactSelection | null {
+  if (isOperationalSettingPath(path)) {
+    const versionId = pointer.test?.[path];
+    if (versionId) return { source: "operational", versionId };
+  }
+  const channel = channelFromEnv(env);
+  if (pointer.channels?.[channel]) return { source: "channel", channel };
+  const versionId = pointer[env]?.[path];
+  return versionId ? { source: "legacy", env, versionId } : null;
+}
+
+/**
+ * The selection {@link resolvePublishedArtifactKey} consults for (tenant, env, path), read fresh,
+ * with the revision of the pointer record it was resolved from (`null` when there is no record).
+ */
+export async function readArtifactSelection(
+  get: KvGet,
+  tenantId: string,
+  env: CustomizationEnv,
+  path: string,
+): Promise<{ rev: number; selection: ArtifactSelection | null } | null> {
+  const pointer = await readPointer(get, tenantId);
+  return pointer ? { rev: pointer.rev, selection: resolveArtifactSelection(pointer, env, path) } : null;
+}
+
 async function readPointer(
   get: KvGet,
   tenantId: string,
@@ -269,7 +330,9 @@ export async function readVersionedArtifact(
  * content). Never throws on malformed data — returns null so the caller falls
  * back to the build-time artifact.
  *
- * Resolution is versioned-first with a legacy fallback:
+ * Resolution follows {@link resolveArtifactSelection}:
+ *   - An operational setting the store has saved resolves to that saved version
+ *     for every env and channel.
  *   - If the tenant has a channel pointer for the resolved channel
  *     (`channelFromEnv(env)`), resolve via the immutable site version. A channel
  *     pointer is AUTHORITATIVE — if the snapshot omits this path we return null
@@ -298,24 +361,18 @@ export async function resolvePublishedArtifactKey(
   env: CustomizationEnv,
   path: string,
 ): Promise<string | null> {
-  const pointer = await readPointer(get, tenantId);
-  if (!pointer) return null;
+  const selection = (await readArtifactSelection(get, tenantId, env, path))?.selection;
+  if (!selection) return null;
+  if (selection.source !== "channel") return customizationArtifactKey(tenantId, selection.versionId);
 
-  const channel = channelFromEnv(env);
-  if (pointer.channels?.[channel]) {
-    // Versioned model engaged for this channel — authoritative. The shared preview renders a
-    // version's captured images the way a pinned preview of it does; `live` never reads the
-    // overlay (its public path is the published bundle, which carries its own rewrites).
-    const { versionId } = await resolveServableChannelVersion(get, tenantId, channel);
-    if (!versionId) return null;
-    return channel === "preview"
-      ? resolveCapturedVersionArtifactKey(get, tenantId, versionId, path)
-      : resolveVersionArtifactKey(get, tenantId, versionId, path);
-  }
-
-  // Legacy per-path selection.
-  const versionId = pointer?.[env]?.[path];
-  return versionId ? customizationArtifactKey(tenantId, versionId) : null;
+  // Versioned model engaged for this channel — authoritative. The shared preview renders a
+  // version's captured images the way a pinned preview of it does; `live` never reads the
+  // overlay (its public path is the published bundle, which carries its own rewrites).
+  const { versionId } = await resolveServableChannelVersion(get, tenantId, selection.channel);
+  if (!versionId) return null;
+  return selection.channel === "preview"
+    ? resolveCapturedVersionArtifactKey(get, tenantId, versionId, path)
+    : resolveVersionArtifactKey(get, tenantId, versionId, path);
 }
 
 /**

package/scripts/dev/integration-guardrails.mjs

@@ -43,6 +43,7 @@
  */
 import { execFileSync } from "node:child_process";
 
+import { isMainModule } from "../lib/is-main-module.mjs";
 /** Umbrella branch this epic folds into. */
 export const DEFAULT_UMBRELLA = "feature/8500-storefront-integration";
 
@@ -493,6 +494,6 @@ function renderReport(r) {
 }
 
 // Run only when invoked directly (not when imported by the test).
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main();
 }

package/scripts/lib/is-main-module.mjs

@@ -0,0 +1,20 @@
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Whether the module at `moduleUrl` is the script node was asked to run. Compared by real path on
+ * both sides: node reports `import.meta.url` resolved through symlinks but leaves `process.argv[1]`
+ * as typed, so a plain comparison is false whenever the script is reached through a symlink, and
+ * then main never runs and the process exits 0 having done nothing.
+ * @param {string} moduleUrl
+ * @param {string | undefined} [argv1]
+ * @returns {boolean}
+ */
+export function isMainModule(moduleUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}

package/scripts/tenant/lint-embeds.mjs

@@ -26,6 +26,7 @@
  */
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { join, extname } from "node:path";
+import { isMainModule } from "../lib/is-main-module.mjs";
 import { EMBED_PROVIDERS } from "../../packages/public-runtime/src/embed-catalog.mjs";
 
 /**
@@ -169,4 +170,4 @@ function main() {
 }
 
 // Only run main when invoked directly, not when imported by the parity test.
-if (import.meta.url === `file://${process.argv[1]}`) main();
+if (isMainModule(import.meta.url)) main();

package/scripts/tenant/materialize-tenant-content.mjs

@@ -69,7 +69,8 @@ import {
 import { execFileSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve, sep } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
+import { isMainModule } from "../lib/is-main-module.mjs";
 import { tenantDirRelative } from "../lib/tenant-dirs.mjs";
 import { parseMappingTarget } from "../../agency-kit/tools/lib/tot-repo-mappings.mjs";
 
@@ -648,9 +649,7 @@ function main() {
   }
 }
 
-const invokedDirectly =
-  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (invokedDirectly) {
+if (isMainModule(import.meta.url)) {
   try {
     main();
   } catch (e) {

package/scripts/tenant/validate.mjs

@@ -28,6 +28,7 @@
 import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { dirname, resolve, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
+import { isMainModule } from "../lib/is-main-module.mjs";
 import { KNOWN_EMBEDS, lintTenantEmbeds } from "./lint-embeds.mjs";
 import { listTenantDirIds, tenantDirSegments } from "../lib/tenant-dirs.mjs";
 import {
@@ -352,7 +353,6 @@ function validateThemeHeadings(theme, file) {
   return out;
 }
 
-
 const SUPPORTED_BLOCK_CONTRACTS = new Set(BLOCK_PALETTE_SUPPORTED_CONTRACTS);
 const KNOWN_BLOCKS = new Set([
   "hero",
@@ -1388,8 +1388,7 @@ function resolveTenantDir(argv) {
   return { dir: tenantDir(id), tenantId: id };
 }
 
-const isMain = resolve(process.argv[1] || "") === resolve(fileURLToPath(import.meta.url));
-if (isMain) {
+if (isMainModule(import.meta.url)) {
   const argv = process.argv.slice(2);
   const asJson = argv.includes("--json");
   const profileIndex = argv.indexOf("--profile");