create-ailk 0.27.0 → 0.28.0

package/templates/apps/web/lib/pricing-page.ts

@@ -0,0 +1,430 @@
+/**
+ * The shared Pricing render (#10044 D5) — what `/pricing` and every
+ * `/pricing/<offering>` page do with the workspace's Offerings shown set.
+ *
+ * Moved unchanged from `/pricing` (#8927, spec
+ * docs/specs/8927-pricing-renders-the-shown-set-spec.md): the shown-offerings
+ * read, shared per server instance for READ_TTL_MS, and its three pages —
+ *   - unconnected (or production with no API origin) — the MDX page as
+ *     written, with `?plan=` moving the authored recommendation (#8842, D7);
+ *   - a current shown set — the workspace's Stripe cards in place of the
+ *     page's authored `pricing` sections, `?plan=` moving the recommendation
+ *     only for a `{plan}`-grammar value (D4, contract §3.7);
+ *   - anything else (expired, empty, a failed read) — the site's contact
+ *     email in place of those sections, never an error (D5).
+ * `pricingSections` runs that choice per page, narrowed to the page's own
+ * `plans` (#10044 D4); `plans: []` reads no Stripe data at all.
+ *
+ * Stripe text reaches markup only as React text through `offeringsPricing`,
+ * and JSON-LD only through renderPage's serializer (T4).
+ *
+ * Base tree: no paid import, no `oss: false`.
+ */
+import { offerings } from "@working-theory/api-client";
+import { ContactFallback } from "@working-theory/ui";
+import {
+  LOOKUP_KEY_PLAN_PATTERN,
+  type PageSection,
+} from "@working-theory/validation";
+import { getTranslations } from "next-intl/server";
+import { createElement, type ReactNode } from "react";
+
+import { contactFormText } from "../app/[locale]/contact/contact-form-text";
+import { readSiteContactEmail } from "../app/[locale]/contact/site-contact-email";
+
+import { browserApiOrigin } from "./api-origin.generated";
+import {
+  offeringsPricing,
+  type OfferingsPricing,
+  type OfferingsPricingLabels,
+} from "./offerings-pricing";
+import type { DetailPage } from "./route-family";
+
+type PricingSection = Extract<PageSection, { type: "pricing" }>;
+type PricingData = PricingSection["data"];
+type ItemsSection = Extract<PageSection, { type: "items" }>;
+type CardItem = ItemsSection["data"]["items"][number];
+
+/** The slug of `/pricing`'s own page — the hub, never an offering page. */
+export const PRICING_HUB_SLUG = "pricing";
+
+/**
+ * Every `pricing` section with `recommended` set to `plan` (#8842). Each
+ * section matches the key against its own plans, so a second plan group
+ * keeps its own default unless it carries the same key.
+ */
+export function withRecommendedPlan(
+  sections: PageSection[],
+  plan: string,
+): PageSection[] {
+  return sections.map((section) =>
+    section.type === "pricing"
+      ? {
+          ...section,
+          // `recommended` is a render-time field the section reads, not an
+          // authored one, so it is not in the validated section schema.
+          data: { ...section.data, recommended: plan } as typeof section.data,
+        }
+      : section,
+  );
+}
+
+type OfferingsRead =
+  | { kind: "unconnected" }
+  | { kind: "shown"; shownSet: unknown }
+  | { kind: "contact" };
+
+const CONTACT: OfferingsRead = { kind: "contact" };
+
+/**
+ * How long the Offerings read is shared across requests (D2): a view carries
+ * no visitor headers, so every view would otherwise count against this
+ * server's one per-IP limit at the API. A product switched off disappears
+ * within it. The contact page's window (#8731).
+ */
+const READ_TTL_MS = 15_000;
+
+const reads = new Map<string, { at: number; read: Promise<OfferingsRead> }>();
+
+/**
+ * `read()`'s result, shared per instance for READ_TTL_MS. Concurrent calls
+ * share one in-flight read, and a failed read is shared the same way, so a
+ * burst against an unreachable API is one call.
+ */
+function sharedRead(
+  key: string,
+  read: () => Promise<OfferingsRead>,
+): Promise<OfferingsRead> {
+  const now = Date.now();
+  const hit = reads.get(key);
+  if (hit && now - hit.at < READ_TTL_MS) return hit.read;
+  const fresh = read();
+  reads.set(key, { at: now, read: fresh });
+  return fresh;
+}
+
+/**
+ * Whether an API origin is configured: the three names `getApiBase()` in
+ * packages/api-client/src/http.ts reads, in step with it on a hub. Without one
+ * that function answers `localhost:3001`. The browser-facing origin comes from
+ * the topology seam (#7874 D12), which a spoke renders with no env read, so a
+ * spoke passes its own `env:check` (#9480). A spoke diverges on purpose: the
+ * browser-facing name set on one at runtime counts as no origin here.
+ */
+function apiOriginConfigured(): boolean {
+  return Boolean(
+    process.env.AILK_API_URL ||
+    browserApiOrigin() ||
+    process.env.NEXT_PUBLIC_API_URL,
+  );
+}
+
+/**
+ * The shown-offerings read (D2). A production deployment with no API has no
+ * connection to read, so it is unconnected without a call. The body is
+ * untrusted: anything but `unconnected` or `shown` — `empty`, an unknown
+ * status, a non-object body, a non-2xx, a throw — is the contact email.
+ */
+export function readShownOfferings(): Promise<OfferingsRead> {
+  if (process.env.NODE_ENV === "production" && !apiOriginConfigured()) {
+    return Promise.resolve({ kind: "unconnected" });
+  }
+  return sharedRead("shown-offerings", async () => {
+    try {
+      const res = await offerings.shown();
+      if (!res.ok) return CONTACT;
+      const body: unknown = res.body;
+      if (body === null || typeof body !== "object") return CONTACT;
+      const { status, shownSet } = body as {
+        status?: unknown;
+        shownSet?: unknown;
+      };
+      if (status === "unconnected") return { kind: "unconnected" };
+      if (status === "shown") return { kind: "shown", shownSet };
+      return CONTACT;
+    } catch {
+      return CONTACT;
+    }
+  });
+}
+
+/** Keeps the `{amount}` placeholder for `period` to fill (D6). */
+const KEEP_AMOUNT_PLACEHOLDER = { amount: "{amount}" };
+/** Keeps both placeholders for `withRequired` to fill (#10028 D9). */
+const KEEP_BUNDLE_PLACEHOLDERS = { plan: "{plan}", required: "{required}" };
+const KEEP_DEPOSIT_PLACEHOLDER = { deposit: "{deposit}" };
+
+/** The mapper's labels and the plans section's recommendation label (D6). */
+export async function offeringsCopy(locale: string): Promise<{
+  labels: OfferingsPricingLabels;
+  recommendedLabel: string;
+  addonsHeadline: string;
+}> {
+  const t = await getTranslations({ locale, namespace: "pricingOfferings" });
+  const period = (key: "monthly" | "annual" | "oneTime") => {
+    const phrase = t(key, KEEP_AMOUNT_PLACEHOLDER);
+    return (amount: string) => phrase.replace("{amount}", () => amount);
+  };
+  return {
+    labels: {
+      cta: t("cta"),
+      recommended: t("recommended"),
+      monthly: period("monthly"),
+      annual: period("annual"),
+      oneTime: period("oneTime"),
+      withRequired: (plan, required) =>
+        t("withRequired", KEEP_BUNDLE_PLACEHOLDERS)
+          .replace("{plan}", () => plan)
+          .replace("{required}", () => required),
+      depositNote: (deposit) =>
+        t("depositNote", KEEP_DEPOSIT_PLACEHOLDER).replace(
+          "{deposit}",
+          () => deposit,
+        ),
+    },
+    recommendedLabel: t("recommendedForYou"),
+    addonsHeadline: t("addonsHeadline"),
+  };
+}
+
+/** The authored section copy a Stripe section keeps — never a plan or price fact. */
+const AUTHORED_COPY_FIELDS = [
+  "eyebrow",
+  "headline",
+  "description",
+  "header",
+  "headlineSize",
+  "toggleStyle",
+  "featureListStyle",
+  "gapAbove",
+  "separation",
+  "gap",
+  "surface",
+  "note",
+  "collapseFeaturesOnMobile",
+] as const satisfies readonly (keyof PricingData)[];
+
+function authoredCopy(
+  section: PricingSection | undefined,
+  extra: readonly (keyof PricingData)[] = [],
+): Partial<PricingData> {
+  const copy: Partial<Record<keyof PricingData, unknown>> = {};
+  if (!section) return copy as Partial<PricingData>;
+  for (const field of [...AUTHORED_COPY_FIELDS, ...extra]) {
+    if (section.data[field] !== undefined) copy[field] = section.data[field];
+  }
+  return copy as Partial<PricingData>;
+}
+
+function isPricing(section: PageSection): section is PricingSection {
+  return section.type === "pricing";
+}
+
+/** Where a section with no slot goes: after a leading hero, else first. */
+function insertionIndex(sections: PageSection[]): number {
+  return sections[0]?.type === "hero" ? 1 : 0;
+}
+
+/**
+ * The page's sections with the Stripe fragments in place of its authored
+ * `pricing` sections (D4). The first non-`addons` pricing section is the
+ * plans slot and the first `addons` one the add-ons slot; every other pricing
+ * section, and a slot whose fragment is `null`, is removed. A fragment with no
+ * slot is inserted after a leading hero (the add-ons directly after the
+ * plans). No other section moves.
+ */
+export function withOfferings(
+  sections: PageSection[],
+  pricing: OfferingsPricing,
+  plan: string | undefined,
+  recommendedLabel: string,
+  addonsHeadline: string,
+): PageSection[] {
+  const plansSlot = sections.find(
+    (s): s is PricingSection => isPricing(s) && s.data.variant !== "addons",
+  );
+  const addonsSlot = sections.find(
+    (s): s is PricingSection => isPricing(s) && s.data.variant === "addons",
+  );
+  const recommend =
+    plan !== undefined && LOOKUP_KEY_PLAN_PATTERN.test(plan) ? plan : undefined;
+  const plansSection: PricingSection | null = pricing.plans && {
+    id: plansSlot?.id ?? "offerings-plans",
+    type: "pricing",
+    data: {
+      ...authoredCopy(plansSlot),
+      ...pricing.plans,
+      // A `?plan=` recommendation moves the mapper's highlight onto the named
+      // plan and wears `recommendedLabel` (#8842); the mapper's own
+      // "Recommended" pill label would ride along as a second label, so it is
+      // dropped from every card when a recommendation is in play.
+      ...(recommend !== undefined &&
+      pricing.plans.plans.some(
+        (card) => card.key?.toLowerCase() === recommend.toLowerCase(),
+      )
+        ? {
+            plans: pricing.plans.plans.map(
+              ({ highlightLabel: _, ...card }) => card,
+            ),
+          }
+        : {}),
+      // Render-time fields the section reads (#8842), not authored ones.
+      recommendedLabel,
+      ...(recommend !== undefined ? { recommended: recommend } : {}),
+    } as PricingData,
+  };
+  const addonsSection: PricingSection | null = pricing.addons && {
+    id: addonsSlot?.id ?? "offerings-addons",
+    type: "pricing",
+    data: {
+      // An inserted add-ons section (no authored slot) sits tight under the
+      // plans and carries its own headline, so a lone tile is never an
+      // unlabeled band (design review B2).
+      ...(addonsSlot ? {} : { headline: addonsHeadline, gapAbove: "tight" }),
+      ...authoredCopy(addonsSlot, ["addonLayout"]),
+      ...pricing.addons,
+    } as PricingData,
+  };
+
+  const placed: PageSection[] = [];
+  for (const section of sections) {
+    if (!isPricing(section)) placed.push(section);
+    else if (section === plansSlot && plansSection) placed.push(plansSection);
+    else if (section === addonsSlot && addonsSection)
+      placed.push(addonsSection);
+  }
+  if (plansSection && !plansSlot) {
+    placed.splice(insertionIndex(placed), 0, plansSection);
+  }
+  if (addonsSection && !addonsSlot) {
+    const plansAt = plansSection ? placed.indexOf(plansSection) : -1;
+    placed.splice(
+      plansAt >= 0 ? plansAt + 1 : insertionIndex(placed),
+      0,
+      addonsSection,
+    );
+  }
+  return placed;
+}
+
+/** The section the contact email is slotted into (D5). */
+export const CONTACT_SECTION_ID = "offerings-contact";
+
+/**
+ * The page's sections with every `pricing` section removed and one
+ * `contact-form` section in the first one's place, else after a leading hero
+ * (D5). It contributes no JSON-LD, so the page publishes no `Offer`.
+ */
+export function withContactFallback(sections: PageSection[]): PageSection[] {
+  const first = sections.findIndex(isPricing);
+  const kept: PageSection[] = sections.filter((s) => !isPricing(s));
+  const contact = {
+    id: CONTACT_SECTION_ID,
+    type: "contact-form",
+    data: { fields: [] },
+  } as PageSection;
+  kept.splice(first >= 0 ? first : insertionIndex(kept), 0, contact);
+  return kept;
+}
+
+/**
+ * The slot the contact section renders into (D5). A slot whose section is
+ * absent renders nothing, so every Pricing page carries it and only the
+ * contact path places its section (#10044 D6).
+ */
+export async function pricingSectionSlots(
+  locale: string,
+): Promise<Record<string, ReactNode>> {
+  const text = contactFormText(
+    await getTranslations({ locale, namespace: "contact" }),
+  );
+  return {
+    [CONTACT_SECTION_ID]: createElement(ContactFallback, {
+      email: readSiteContactEmail(),
+      text: {
+        heading: text.unavailableHeading,
+        body: text.unavailableBody,
+        noEmail: text.unavailableNoEmail,
+      },
+    }),
+  };
+}
+
+/**
+ * A page's `plans` frontmatter (#10044 D1) — its plan slugs, or `undefined`
+ * when the page names none. The adapter validated it; a non-array is none.
+ */
+export function pagePlans(frontmatter: unknown): string[] | undefined {
+  if (frontmatter === null || typeof frontmatter !== "object") return undefined;
+  const { plans } = frontmatter as { plans?: unknown };
+  if (!Array.isArray(plans)) return undefined;
+  return plans.filter((plan): plan is string => typeof plan === "string");
+}
+
+/**
+ * One Pricing page's sections in its Offerings state (#10044 D5): `/pricing`'s
+ * three-state choice with the page's own `plans` passed through.
+ *   - `plans: []` → the written sections, no Stripe read;
+ *   - unconnected → the written sections (`?plan=` moving the recommendation);
+ *   - shown → the page's Stripe cards in place of its `pricing` sections,
+ *     when any of its plans is shown;
+ *   - anything else → the contact email in their place.
+ */
+export async function pricingSections(
+  declared: PageSection[],
+  options: {
+    plans: readonly string[] | undefined;
+    plan: string | undefined;
+    locale: string;
+  },
+): Promise<PageSection[]> {
+  const { plans, plan, locale } = options;
+  const asWritten = () =>
+    plan ? withRecommendedPlan(declared, plan) : declared;
+  if (plans !== undefined && plans.length === 0) return asWritten();
+
+  const read = await readShownOfferings();
+  if (read.kind === "unconnected") return asWritten();
+  if (read.kind === "shown") {
+    const { labels, recommendedLabel, addonsHeadline } =
+      await offeringsCopy(locale);
+    const pricing = offeringsPricing(read.shownSet, { locale, labels, plans });
+    if (pricing && (pricing.plans || pricing.addons)) {
+      return withOfferings(
+        declared,
+        pricing,
+        plan,
+        recommendedLabel,
+        addonsHeadline,
+      );
+    }
+  }
+  return withContactFallback(declared);
+}
+
+/**
+ * The offering pricing pages `/pricing` lists (#10044 D5): those whose
+ * frontmatter `slug` is their file slug — a page served at a URL its route
+ * does not answer is left off — and is not the hub's own, in input order.
+ */
+export function offeringPricingPages(pages: DetailPage[]): DetailPage[] {
+  return pages.filter(
+    (page) =>
+      page.frontmatter.slug === page.slug && page.slug !== PRICING_HUB_SLUG,
+  );
+}
+
+/** One `/pricing` list card for an offering pricing page (#10044 D5). */
+export function pricingPageCard(
+  page: DetailPage,
+  labels: { viewPricing: string },
+): CardItem {
+  const { title, summary, description } = page.frontmatter;
+  const text = (value: unknown): string | undefined =>
+    typeof value === "string" && value.length > 0 ? value : undefined;
+  return {
+    title: text(title) ?? page.slug,
+    description: text(summary) ?? text(description) ?? "",
+    link: { label: labels.viewPricing, href: `/pricing/${page.slug}` },
+  };
+}

package/templates/apps/web/lib/relay.ts

@@ -35,22 +35,24 @@
  *     and only as strong as the platform: it holds only where the site's edge
  *     overwrites `x-forwarded-for` and `x-real-ip` (Vercel does; a bare
  *     self-hosted Next server does not).
- *   - A BOT CHECK ON THE BOOKING (#9889). `POST /v1/schedule/book` asks
- *     Vercel BotID (`checkBotId`) for a verdict after every refusal above and
- *     before the hub is called. Only a human verdict forwards; a bot is
- *     `403 bot_detected`, and a check that throws, answers no boolean or
- *     takes over 5 seconds is `503 bot_check_unavailable` — either way the
- *     hub is never called. It runs only on Vercel (`VERCEL=1`), unless
- *     `AILK_BOOKING_BOT_CHECK=off`.
+ *   - A BOT CHECK ON THE WRITES (#9889, #9255). `POST /v1/leads/submit`,
+ *     `/v1/leads/subscribe`, `/v1/leads/callback` and `/v1/schedule/book`
+ *     ask Vercel BotID (`runBotCheck`, lib/bot-check.ts) for a verdict after
+ *     every refusal above and before the hub is called. Only a human verdict
+ *     forwards; a bot is `403 bot_detected`, and a check that throws, answers
+ *     no boolean or takes over 5 seconds is `503 bot_check_unavailable` —
+ *     either way the hub is never called. It runs only on Vercel
+ *     (`VERCEL=1`); `AILK_BOT_CHECK=off` turns every check off and
+ *     `AILK_BOOKING_BOT_CHECK=off` the booking's alone.
  *
  * NO SECRET IS LOGGED. A failure logs `{ path, outcome }` and nothing else.
  */
 import { isIP } from "node:net";
 
 import { relayToApi, visitorForwardHeaders } from "@working-theory/api-client";
-import { checkBotId } from "botid/server";
 
 import { browserApiOrigin } from "./api-origin.generated";
+import { runBotCheck } from "./bot-check";
 import { readConsentVisitorFromCookieHeader } from "./consent-visitor";
 
 type RelayMethod = "GET" | "POST";
@@ -77,92 +79,33 @@ function route(method: RelayMethod, path: string): RelayRoute {
  */
 const SESSION_ROUTE = route("POST", "/v1/commerce/invoices");
 
-/** The booking pair, the one route the bot check guards (#9889 D1). */
+/** The three lead pairs (#9255 D2) and the booking pair (#9889 D1). */
+const SUBMIT_ROUTE = route("POST", "/v1/leads/submit");
+const SUBSCRIBE_ROUTE = route("POST", "/v1/leads/subscribe");
+const CALLBACK_ROUTE = route("POST", "/v1/leads/callback");
 const BOOK_ROUTE = route("POST", "/v1/schedule/book");
 
 export const RELAY_ROUTES: readonly RelayRoute[] = Object.freeze([
-  route("POST", "/v1/leads/submit"),
-  route("POST", "/v1/leads/subscribe"),
-  route("POST", "/v1/leads/callback"),
+  SUBMIT_ROUTE,
+  SUBSCRIBE_ROUTE,
+  CALLBACK_ROUTE,
   route("GET", "/v1/schedule/availability"),
   BOOK_ROUTE,
   SESSION_ROUTE,
 ]);
 
 /**
- * The entries the bot check guards (#9889 D1, D4). The locale layout passes
- * the same list to `BotIdClient`, so the browser protects exactly the pairs
- * the server checks: a checked pair the client does not protect would carry
- * no challenge header and be refused as a bot.
+ * The entries the bot check guards (#9889 D1, #9255 D2): every write a
+ * browser posts here. The locale layout's `BotIdClient` protects every
+ * same-origin POST (`BOT_CLIENT_PROTECT`), so each carries BotID's challenge.
  */
 export const BOT_CHECKED_ROUTES: readonly RelayRoute[] = Object.freeze([
+  SUBMIT_ROUTE,
+  SUBSCRIBE_ROUTE,
+  CALLBACK_ROUTE,
   BOOK_ROUTE,
 ]);
 
-/** The longest the relay waits for a verdict; the library's own fetch has no bound. */
-const BOT_CHECK_TIMEOUT_MS = 5_000;
-
-/**
- * True when the booking bot check runs (#9889 D2): on Vercel, unless
- * `AILK_BOOKING_BOT_CHECK` is `off`. Unset, empty or any other value leaves
- * it on, so a typo fails toward protection. Read on every call, never cached.
- */
-export function bookingBotCheckOn(): boolean {
-  return process.env.VERCEL === "1" && !botCheckSwitchedOff();
-}
-
-function botCheckSwitchedOff(): boolean {
-  return process.env.AILK_BOOKING_BOT_CHECK?.trim().toLowerCase() === "off";
-}
-
-let warnedBotCheckInactive = false;
-
-/**
- * Called when the check is off. Off Vercel it cannot run (D2): a production
- * site whose switch is not `off` logs that once per process, so an owner who
- * believes it is on can find out. It never refuses.
- */
-function warnBotCheckInactiveOnce(): void {
-  if (warnedBotCheckInactive || process.env.NODE_ENV !== "production") return;
-  if (botCheckSwitchedOff()) return;
-  warnedBotCheckInactive = true;
-  console.warn("[relay] booking bot check inactive", {
-    outcome: "not-on-vercel",
-  });
-}
-
-function namedError(name: string): Error {
-  const err = new Error(name);
-  err.name = name;
-  return err;
-}
-
-/**
- * BotID's verdict on this request (D1, D3): `true` for a bot, `false` for a
- * human. Throws `TimeoutError` past `BOT_CHECK_TIMEOUT_MS` and
- * `InvalidVerdictError` when `isBot` is not a boolean, as `checkBotId` returns
- * for an error answer from Vercel.
- */
-async function isBotVerdict(): Promise<boolean> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  try {
-    const verdict = await Promise.race([
-      checkBotId(),
-      new Promise<never>((_resolve, reject) => {
-        timer = setTimeout(
-          () => reject(namedError("TimeoutError")),
-          BOT_CHECK_TIMEOUT_MS,
-        );
-      }),
-    ]);
-    const isBot = (verdict as { isBot?: unknown } | undefined)?.isBot;
-    if (typeof isBot !== "boolean") throw namedError("InvalidVerdictError");
-    return isBot;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
 /**
  * The three lead routes (#8438 D11, D12): a visitor's banner choice is
  * linked to a Person only through these — a booking has no consent writer.
@@ -552,33 +495,15 @@ export async function handleRelay(request: Request): Promise<Response> {
   }
 
   if (BOT_CHECKED_ROUTES.includes(entry)) {
-    if (bookingBotCheckOn()) {
-      let isBot: boolean;
-      try {
-        isBot = await isBotVerdict();
-      } catch (err) {
-        // The error's name only — never its message (#9889 D1).
-        console.error("[relay] bot check failed", {
-          path: entry.path,
-          outcome: "bot-check-failed",
-          error: err instanceof Error ? err.name : "unknown",
-        });
-        return refusal(
-          503,
-          "bot_check_unavailable",
-          "The booking check is unavailable",
-        );
-      }
-      if (isBot) {
-        console.warn("[relay] bot refused", {
-          path: entry.path,
-          outcome: "bot-detected",
-        });
-        return refusal(403, "bot_detected", "Request refused");
-      }
-    } else {
-      warnBotCheckInactiveOnce();
+    const verdict = await runBotCheck({
+      source: "relay",
+      target: entry.path,
+      scope: entry === BOOK_ROUTE ? "booking" : "write",
+    });
+    if (verdict === "unavailable") {
+      return refusal(503, "bot_check_unavailable", "The bot check is unavailable");
     }
+    if (verdict === "bot") return refusal(403, "bot_detected", "Request refused");
   }
 
   try {

package/templates/apps/web/lib/route-family.ts

@@ -0,0 +1,69 @@
+/**
+ * The route-family helper (#10051 D5) — the generic half of a content hub
+ * that lists its detail pages automatically: read every detail page of one
+ * type, and slot a generated section in before the page's closing CTAs.
+ *
+ * The /templates hub (#10051) is its first caller. It is shaped for the next
+ * two: #10043 (a services category page listing its child `Service` pages)
+ * and #10044 (a pricing hub listing its offering `Pricing` pages). The
+ * /alternatives and /reports routes keep their own local copies (#10051
+ * § Out of scope).
+ *
+ * Base tree: no paid import, no `oss: false`.
+ */
+import {
+  getMdxSlugs,
+  getMdxSource,
+  type getPageSections,
+  type SchemaOrgType,
+} from "@working-theory/page-renderer";
+
+type Section = Awaited<ReturnType<typeof getPageSections>>[number];
+
+/** One detail page as a hub lists it: its slug and raw frontmatter. */
+export interface DetailPage {
+  slug: string;
+  frontmatter: Record<string, unknown>;
+}
+
+/**
+ * Every detail page of `type` for `locale`, loaded through `load` (the
+ * content adapter by default), a slug whose load is `null` dropped, sorted
+ * by slug so the list is stable. `listSlugs` defaults to the content adapter
+ * too; a route passes its own to stay injectable in tests.
+ */
+export async function listDetailPages(
+  type: SchemaOrgType,
+  locale: string,
+  load: typeof getMdxSource = getMdxSource,
+  listSlugs: typeof getMdxSlugs = getMdxSlugs,
+): Promise<DetailPage[]> {
+  const slugs = await listSlugs(type, locale);
+  const pages = await Promise.all(
+    slugs.map(async (slug): Promise<DetailPage | null> => {
+      const source = await load(type, slug, locale);
+      if (source === null) return null;
+      return {
+        slug,
+        frontmatter: source.frontmatter as Record<string, unknown>,
+      };
+    }),
+  );
+  return pages
+    .filter((page): page is DetailPage => page !== null)
+    .sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+/**
+ * Insert `section` before the trailing run of `cta` sections — the page's
+ * closing call to action stays last — or append it when the page does not end
+ * in a CTA (the /reports rule, #7745 D4).
+ */
+export function insertBeforeClosingCtas(
+  sections: Section[],
+  section: Section,
+): Section[] {
+  let at = sections.length;
+  while (at > 0 && sections[at - 1]?.type === "cta") at -= 1;
+  return [...sections.slice(0, at), section, ...sections.slice(at)];
+}