create-ailk 0.27.0 → 0.28.0

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

@@ -13,7 +13,9 @@
  *   - T2 — every Stripe string is emitted as a plain text field, with format
  *     characters removed; nothing is parsed as HTML or Markdown (D8).
  *   - T3 — every link is `OFFERINGS_CHECKOUT_PATH` plus a lookup key that
- *     `parseLookupKey` accepts; no href is built from any other field (D5).
+ *     `parseLookupKey` accepts — plus, for a bundled plan, `?with=` and the
+ *     required product's key (#10028 D9); no href is built from any other
+ *     field (D5).
  *   - §3.7 — `yearly` reads as annual and `once` as one-time at render, never
  *     in the key (D2).
  *
@@ -49,6 +51,10 @@ export interface OfferingsPricingLabels {
   monthly(amount: string): string;
   annual(amount: string): string;
   oneTime(amount: string): string;
+  /** A bundled plan's phrase: its one-time phrase plus its required product's recurring phrase (#10028 D9). */
+  withRequired(plan: string, required: string): string;
+  /** A deposit plan's footnote, from the formatted deposit (#10030 D10). */
+  depositNote(deposit: string): string;
 }
 
 export interface OfferingsPricing {
@@ -69,6 +75,21 @@ export function offeringsCheckoutHref(lookupKey: string): string | null {
     : null;
 }
 
+/**
+ * The CTA target for a bundled plan (#10028 D9): the plan's key plus the
+ * required product's key as `?with=`, or `null` when either is outside the
+ * grammar. Both keys are `[a-z0-9_-]` only, so neither needs encoding.
+ */
+export function offeringsBundleHref(
+  planKey: string,
+  requiredKey: string,
+): string | null {
+  const base = offeringsCheckoutHref(planKey);
+  return base && parseLookupKey(requiredKey)
+    ? `${base}?with=${requiredKey}`
+    : null;
+}
+
 /**
  * Whether `lookupKey` is a grammar key of a Price in a current, non-empty
  * shown set — the keys `/pricing`'s cards are built from (#9051 D4).
@@ -194,6 +215,63 @@ function firstRecommended(products: OfferingsProduct[]): string | undefined {
   return products.find((p) => p.recommended)?.plan;
 }
 
+/**
+ * A bundled plan's card (#10028 D9): the plan's one-time Price with its
+ * required product's recurring Prices — one link per shown recurring
+ * interval. With monthly and yearly, the monthly link is the CTA and the
+ * yearly one the annual link, each mode phrasing both amounts; with one,
+ * that link alone and the phrase as the custom price. No card when the plan's
+ * own one-time Price, or a recurring Price of the required product, is not
+ * shown.
+ */
+function bundleCard(
+  product: OfferingsProduct,
+  required: OfferingsProduct,
+  highlighted: boolean,
+  locale: string,
+  labels: OfferingsPricingLabels,
+): PricingPlanCard | null {
+  const once = priceFor(product, PERIOD.once);
+  const monthly = priceFor(required, PERIOD.monthly);
+  const yearly = priceFor(required, PERIOD.yearly);
+  const first = monthly ?? yearly;
+  if (!once || !first) return null;
+  const href = offeringsBundleHref(once.lookupKey, first.lookupKey);
+  if (!href) return null;
+  const oneTime = phrase(once, locale, labels);
+  const combined = (recurring: OfferingsPrice) =>
+    labels.withRequired(oneTime, phrase(recurring, locale, labels));
+  const price: PricingPlanCard["price"] = {};
+  if (monthly && yearly) {
+    price.monthly = combined(monthly);
+    price.annual = combined(yearly);
+  } else {
+    price.custom = combined(first);
+  }
+  const card: PricingPlanCard = {
+    key: product.plan,
+    name: stripFormatCharacters(product.name),
+    price,
+    features: features(product),
+    cta: { label: labels.cta, href },
+  };
+  // The deposit note wins the footnote; the terms note shows only without one.
+  // NO_HAND_IMPLEMENT_OK: builder-assessors run for #10030 — the builder is the implementer.
+  if (product.deposit !== undefined)
+    card.priceFootnote = labels.depositNote(formatMinorUnits(product.deposit, once.currency, locale));
+  else if (product.termsNote)
+    card.priceFootnote = stripFormatCharacters(product.termsNote);
+  const annualHref =
+    monthly && yearly && offeringsBundleHref(once.lookupKey, yearly.lookupKey);
+  if (annualHref) card.annualCtaHref = annualHref;
+  if (highlighted) {
+    card.highlighted = true;
+    card.highlightStyle = "pill";
+    card.highlightLabel = labels.recommended;
+  }
+  return card;
+}
+
 function planCard(
   product: OfferingsProduct,
   highlighted: boolean,
@@ -227,6 +305,10 @@ function planCard(
   if (product.note) card.priceSubhead = stripFormatCharacters(product.note);
   if (product.termsNote)
     card.priceFootnote = stripFormatCharacters(product.termsNote);
+  // A deposit plan's footnote (#10030 D10), in its one-time Price's currency;
+  // it takes the footnote over a terms note (the rarer field).
+  if (product.deposit !== undefined && once)
+    card.priceFootnote = labels.depositNote(formatMinorUnits(product.deposit, once.currency, locale));
   // Annual mode shows the yearly Price only when a monthly one is beside it,
   // so only then does the card need a second link (D5, D6).
   const annualHref =
@@ -280,28 +362,75 @@ function isPresent<T>(value: T | null): value is T {
   return value !== null;
 }
 
+/**
+ * The products whose `{plan}` is in `plans`, plus every product a kept one
+ * `requires`, in the snapshot's order (#10044 D4); `plans` absent → all.
+ * One level of `requires` is followed: a required product is sold only
+ * inside its bundle and requires nothing itself (#10028 decision 6).
+ */
+function narrowToPlans(
+  offerings: OfferingsProduct[],
+  plans: readonly string[] | undefined,
+): OfferingsProduct[] {
+  if (plans === undefined) return offerings;
+  const listed = new Set(plans);
+  const kept = new Set(
+    offerings.filter((o) => listed.has(o.plan)).map((o) => o.plan),
+  );
+  for (const o of offerings) {
+    if (kept.has(o.plan) && o.requires !== undefined) kept.add(o.requires);
+  }
+  return offerings.filter((o) => kept.has(o.plan));
+}
+
 /**
  * The shown set as Pricing section data, or `null` when there is nothing to
  * show: a value the shown-set schema refuses, a snapshot that is not
  * `current`, or no offerings. Each fragment is `null` when its group is empty.
+ *
+ * `plans` (#10044 D4) narrows the set to an offering page's own products:
+ * those whose `{plan}` it lists, plus every product a kept one `requires`, in
+ * the snapshot's order. Absent, every shown product is mapped, as before.
  */
 export function offeringsPricing(
   shownSet: unknown,
-  options: { locale: string; labels: OfferingsPricingLabels },
+  options: {
+    locale: string;
+    labels: OfferingsPricingLabels;
+    plans?: readonly string[] | undefined;
+  },
 ): OfferingsPricing | null {
   const parsed = shownSetSchema.safeParse(shownSet);
   if (!parsed.success) return null;
-  const { state, offerings } = parsed.data;
-  if (state !== "current" || offerings.length === 0) return null;
+  const { state, offerings: shown } = parsed.data;
+  if (state !== "current" || shown.length === 0) return null;
   const { locale, labels } = options;
 
-  const planProducts = offerings.filter((o) => o.ailkGroup === "plan");
+  // #10028 D9 — a product some shown plan requires is sold only inside that
+  // bundle (decision 6), so it gets no card of its own. Read over the whole
+  // shown set, so a page listing only that product still shows it no card.
+  const requiredPlans = new Set(
+    shown.map((o) => o.requires).filter((plan) => plan !== undefined),
+  );
+  const offerings = narrowToPlans(shown, options.plans);
+  const planProducts = offerings.filter(
+    (o) => o.ailkGroup === "plan" && !requiredPlans.has(o.plan),
+  );
   const addonProducts = offerings.filter((o) => o.ailkGroup === "addon");
   const recommendedPlan = firstRecommended(planProducts);
   const recommendedAddon = firstRecommended(addonProducts);
 
   const plans = planProducts
-    .map((p) => planCard(p, p.plan === recommendedPlan, locale, labels))
+    .map((p) => {
+      const required =
+        p.requires === undefined
+          ? undefined
+          : offerings.find((o) => o.plan === p.requires);
+      if (p.requires !== undefined) {
+        return required ? bundleCard(p, required, p.plan === recommendedPlan, locale, labels) : null;
+      }
+      return planCard(p, p.plan === recommendedPlan, locale, labels);
+    })
     .filter(isPresent);
   const addons = addonProducts
     .map((p) => addonTile(p, p.plan === recommendedAddon, locale, labels))

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

@@ -0,0 +1,367 @@
+/**
+ * Per-page chrome (#10049 D3) — which header and footer a page wears, and
+ * whether the home is a deck.
+ *
+ * Four levels, most specific first: the page's own frontmatter (`header:`,
+ * `footer:`, `layout:`), its route family's key in `_site.mdx` (`blog:`,
+ * `docs:`, …), the site defaults in `_site.mdx` (`header.style`,
+ * `footer.style`, `layout`), and last the design's own knobs in the
+ * generated `site-chrome.ts`. A site that sets nothing resolves to exactly
+ * the chrome the design gave it before this file existed.
+ *
+ * Blog posts and docs pages are served by the docs-blog slice, which this
+ * base file must never import, so they take their `blog:` / `docs:` family
+ * or the site default; their own frontmatter is not read here.
+ *
+ * `_site.mdx` is read locally rather than through
+ * `@working-theory/site-config/server`, as `site-header.ts` does (#1567).
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  getMdxSource,
+  type SchemaOrgType,
+} from "@working-theory/page-renderer";
+import {
+  HeaderStyleSchema,
+  ROUTE_FAMILY_KEYS,
+  SiteConfigSchema,
+  type FooterStyle,
+  type HeaderStyle,
+  type RouteFamilyChrome,
+  type RouteFamilyKey,
+  type SiteLayout,
+} from "@working-theory/site-config/schema";
+import { ROUTES } from "@working-theory/templates/routes";
+import { readLocales } from "@working-theory/web-i18n";
+import { cache } from "react";
+import { parse as parseYaml } from "yaml";
+import type { ZodType } from "zod";
+
+import { normalizeRoutePath } from "./closing-footer-path";
+import {
+  isAlwaysScaffolded,
+  matchesRoute,
+  resolveTypeAndSlug,
+} from "./deck-page";
+import { toInternalDocsPath } from "./docs-path";
+import { SERVICES_ROUTE, toInternalServicesPath } from "./services-path";
+import { resolveContentRoot } from "./site-brand";
+
+/** The chrome settings a site sets in `_site.mdx`. */
+export interface SiteChromeSettings {
+  headerStyle?: HeaderStyle;
+  footerStyle?: FooterStyle;
+  layout?: SiteLayout;
+  families: Partial<Record<RouteFamilyKey, RouteFamilyChrome>>;
+}
+
+/** The chrome fields a page's own frontmatter sets. */
+export interface PageChromeFields {
+  header?: HeaderStyle;
+  footer?: FooterStyle;
+  layout?: SiteLayout;
+}
+
+/**
+ * The design knobs the template level reads — a structural slice of the
+ * generated `SiteChrome`, so a scaffold generated before `innerPages` or
+ * `chromeStyle` existed still compiles.
+ */
+export interface ChromeKnobs {
+  home: SiteLayout;
+  footer: "columns" | "centered";
+  innerPages?: "bare";
+  chromeStyle?: "minimal";
+}
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+const warnedPaths = new Set<string>();
+
+/** One warning per field path per process, naming the path and the Zod message — never the value. */
+function warnOnce(path: string, message: string): void {
+  if (warnedPaths.has(path)) return;
+  warnedPaths.add(path);
+  console.warn(`[page-chrome] ignoring _site.mdx ${path}: ${message}`);
+}
+
+/** `value` parsed by `schema`, else `undefined` with a warning under `path`. */
+function validated<T>(
+  schema: ZodType<T>,
+  value: unknown,
+  path: string,
+): T | undefined {
+  if (value === undefined) return undefined;
+  const parsed = schema.safeParse(value);
+  if (parsed.success) return parsed.data;
+  const issue = parsed.error.issues[0];
+  warnOnce(
+    [path, ...(issue?.path ?? [])].join("."),
+    issue?.message ?? "invalid",
+  );
+  return undefined;
+}
+
+/**
+ * `_site.mdx`'s chrome keys. Each key validates on its own, so one bad key
+ * drops only itself; an absent file, frontmatter or key is silent.
+ */
+export const readSiteChromeSettings = cache(
+  function readSiteChromeSettings(): SiteChromeSettings {
+    try {
+      const raw = readFileSync(join(resolveContentRoot(), "_site.mdx"), "utf8");
+      const match = FRONTMATTER_RE.exec(raw);
+      if (!match) return { families: {} };
+      const fm: unknown = parseYaml(match[1] ?? "");
+      if (!fm || typeof fm !== "object") return { families: {} };
+      const record = fm as Record<string, unknown>;
+
+      const settings: SiteChromeSettings = { families: {} };
+      const header = record["header"];
+      const headerStyle =
+        header && typeof header === "object"
+          ? validated(
+              HeaderStyleSchema,
+              (header as Record<string, unknown>)["style"],
+              "header.style",
+            )
+          : undefined;
+      if (headerStyle !== undefined) settings.headerStyle = headerStyle;
+      const footerStyle = validated(
+        SiteConfigSchema.shape.footer,
+        record["footer"],
+        "footer",
+      )?.style;
+      if (footerStyle !== undefined) settings.footerStyle = footerStyle;
+      const layout = validated(
+        SiteConfigSchema.shape.layout,
+        record["layout"],
+        "layout",
+      );
+      if (layout !== undefined) settings.layout = layout;
+      for (const key of ROUTE_FAMILY_KEYS) {
+        const family = validated(SiteConfigSchema.shape[key], record[key], key);
+        if (family !== undefined) settings.families[key] = family;
+      }
+      return settings;
+    } catch (err) {
+      // An absent file is silent; unreadable frontmatter is worth one warning.
+      if ((err as { code?: unknown }).code !== "ENOENT") {
+        warnOnce("frontmatter", "could not be read");
+      }
+      return { families: {} };
+    }
+  },
+);
+
+function camelCase(prefix: string): string {
+  return prefix
+    .replace(/^\//, "")
+    .replace(/-([a-z])/g, (_m, c: string) => c.toUpperCase());
+}
+
+/** Whether `segments` match a routes-map pattern, `:...slug` taking one or more segments. */
+function matchesPattern(pattern: string, segments: readonly string[]): boolean {
+  const parts = pattern.split("/").filter((part) => part.length > 0);
+  for (let i = 0; i < parts.length; i += 1) {
+    const part = parts[i] ?? "";
+    if (part.startsWith(":...")) return segments.length > i;
+    if (i >= segments.length) return false;
+    if (!part.startsWith(":") && part !== segments[i]) return false;
+  }
+  return parts.length === segments.length;
+}
+
+/**
+ * The route family a pathname belongs to, else `null`: the first routes-map
+ * hub whose prefix is the path, prefixes it, or whose detail pattern matches
+ * it. A site's moved docs are mapped back onto `/docs` first, and its moved
+ * services onto `/services` (#10043 D9).
+ */
+export function routeFamilyOf(
+  pathname: string,
+  locales: readonly string[],
+): RouteFamilyKey | null {
+  const bare = normalizeRoutePath(pathname, locales);
+  const path = toInternalDocsPath(bare) ?? toInternalServicesPath(bare) ?? bare;
+  const segments = path.split("/").filter((segment) => segment.length > 0);
+  for (const row of ROUTES) {
+    if (!row.hub) continue;
+    const { prefix, detailPattern } = row.hub;
+    if (
+      path === prefix ||
+      path.startsWith(`${prefix}/`) ||
+      matchesPattern(detailPattern, segments)
+    ) {
+      const key = camelCase(prefix);
+      return (ROUTE_FAMILY_KEYS as readonly string[]).includes(key)
+        ? (key as RouteFamilyKey)
+        : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * The MDX content pages that could serve `pathname`, in the order Next.js
+ * tries them — `deckCandidates`' walk over every content row rather than the
+ * deck routes. Blog posts and docs pages live outside `content/`, so they are
+ * never candidates.
+ */
+export function chromePageCandidates(
+  pathname: string,
+  locales: readonly string[],
+): Array<{ type: SchemaOrgType; slug: string }> {
+  const normalized = normalizeRoutePath(pathname, locales);
+  // #10043 D9 — a site's moved services are mapped back onto `/services`.
+  const path = toInternalServicesPath(normalized) ?? normalized;
+  if (path === "/") return [{ type: "HomePage", slug: "home" }];
+  const segments = path.split("/").filter((segment) => segment.length > 0);
+  // A service under its category (`/services/<category>/<slug>`): the nested
+  // row names no content directory, so the walk below would never name it.
+  if (segments.length === 3 && segments[0] === SERVICES_ROUTE.slice(1)) {
+    return [{ type: "Service", slug: segments[2]! }];
+  }
+  const candidates: Array<{ type: SchemaOrgType; slug: string }> = [];
+
+  for (const row of ROUTES) {
+    if (!row.contentPath?.startsWith("content/")) continue;
+    if (!matchesRoute(row.route, segments)) continue;
+    const resolved = resolveTypeAndSlug(row, row.route, segments);
+    if (resolved) {
+      candidates.push(resolved);
+      break;
+    }
+  }
+
+  if (segments.length === 1 && !isAlwaysScaffolded(path)) {
+    const slug = segments[0];
+    if (slug !== undefined) {
+      candidates.push({ type: "LandingPage", slug });
+      candidates.push({ type: "BlogList", slug });
+    }
+  }
+  return candidates;
+}
+
+/**
+ * The page's own chrome frontmatter — the first candidate with a source —
+ * else `{}`. A read that throws answers `{}`: the page's own render surfaces
+ * the error. Per-request memoised.
+ */
+export const resolveChromePage = cache(async function resolveChromePage(
+  pathname: string,
+  locale: string,
+): Promise<PageChromeFields> {
+  try {
+    for (const candidate of chromePageCandidates(pathname, readLocales())) {
+      const source = await getMdxSource(candidate.type, candidate.slug, locale);
+      if (!source) continue;
+      const { header, footer, layout } = source.frontmatter as PageChromeFields;
+      return {
+        ...(header !== undefined ? { header } : {}),
+        ...(footer !== undefined ? { footer } : {}),
+        ...(layout !== undefined ? { layout } : {}),
+      };
+    }
+  } catch {
+    return {};
+  }
+  return {};
+});
+
+/** The home's layout: its own frontmatter, else the site's, else the design's. */
+export function resolveHomeLayout(
+  site: SiteChromeSettings,
+  home: PageChromeFields,
+  chrome: Pick<ChromeKnobs, "home">,
+): SiteLayout {
+  return home.layout ?? site.layout ?? chrome.home;
+}
+
+export interface PageChromeInput {
+  isHome: boolean;
+  /** The resolved home layout is a deck. */
+  homeIsDeck: boolean;
+  family: RouteFamilyKey | null;
+  page: PageChromeFields;
+  site: SiteChromeSettings;
+  chrome: ChromeKnobs;
+  /** The page is listed in the design's `closingFooterPaths`. */
+  closingListed: boolean;
+}
+
+export interface ResolvedChrome {
+  header: HeaderStyle;
+  /** No page, family or site value set the header — the design's own treatment applies. */
+  headerFromTemplate: boolean;
+  /** `line` is the design's one-bar footer on a bare inner page; never a site value. */
+  footer: FooterStyle | "line";
+}
+
+/** The design's own header and footer for a page (#10049 D3's template table). */
+function templateChrome(
+  input: PageChromeInput,
+): Pick<ResolvedChrome, "header" | "footer"> {
+  const { chrome } = input;
+  if (input.isHome) {
+    if (input.homeIsDeck && chrome.home === "deck") {
+      return {
+        header: "bare",
+        footer: chrome.chromeStyle === "minimal" ? "closing" : chrome.footer,
+      };
+    }
+    return { header: "full", footer: chrome.footer };
+  }
+  if (input.closingListed) {
+    return {
+      header: chrome.innerPages === "bare" ? "bare" : "full",
+      footer: "closing",
+    };
+  }
+  if (chrome.innerPages === "bare") return { header: "bare", footer: "line" };
+  return { header: "full", footer: chrome.footer };
+}
+
+/**
+ * The home's layout and chrome — the one resolution both the layout and the
+ * home page read, so the bar and the landing can never disagree.
+ */
+export async function resolveHomeChrome(
+  locale: string,
+  chrome: ChromeKnobs,
+): Promise<{ layout: SiteLayout; chrome: ResolvedChrome; site: SiteChromeSettings }> {
+  const site = readSiteChromeSettings();
+  const page = await resolveChromePage("/", locale);
+  const layout = resolveHomeLayout(site, page, chrome);
+  return {
+    layout,
+    site,
+    chrome: resolvePageChrome({
+      isHome: true,
+      homeIsDeck: layout === "deck",
+      family: null,
+      page,
+      site,
+      chrome,
+      closingListed: false,
+    }),
+  };
+}
+
+/** Each axis takes the first value set: page → route family → site → design. */
+export function resolvePageChrome(input: PageChromeInput): ResolvedChrome {
+  const template = templateChrome(input);
+  const family =
+    input.family !== null ? input.site.families[input.family] : undefined;
+  const header = input.page.header ?? family?.header ?? input.site.headerStyle;
+  const footer = input.page.footer ?? family?.footer ?? input.site.footerStyle;
+  return {
+    header: header ?? template.header,
+    headerFromTemplate: header === undefined,
+    footer: footer ?? template.footer,
+  };
+}

package/templates/apps/web/lib/posting-title.ts

@@ -5,13 +5,35 @@
  * is `/careers/<slug>`'s. In `lib/` (#8849 D9), not a route directory, so
  * every scaffold carries it: the `signal-collectors` walk and the Free apply
  * page (`careers/[slug]/[action]`) both read it.
+ *
+ * #10054 D2 — both pages read the posting through `postingForApply`, which
+ * also returns the magnet the posting names (`applicationFlow`, checked as a
+ * flow slug by the frontmatter schema); one read serves both.
  */
 import { getMdxSource } from "@working-theory/page-renderer";
 
-/** The posting's title in `locale`, or `null` when no posting has this slug. */
-export async function postingTitle(slug: string, locale: string): Promise<string | null> {
+/** What an apply page needs from its posting. */
+export interface ApplyPosting {
+  title: string;
+  /** The magnet this posting's apply page runs; absent, the Job application. */
+  applicationFlow?: string;
+}
+
+/** The posting in `locale`, or `null` when no posting has this slug or it has no title. */
+export async function postingForApply(slug: string, locale: string): Promise<ApplyPosting | null> {
   const source = await getMdxSource("JobPosting", slug, locale);
   if (source === null) return null;
-  const title = (source.frontmatter as { title?: unknown }).title;
-  return typeof title === "string" && title.trim() !== "" ? title : null;
+  const { title, applicationFlow } = source.frontmatter as {
+    title?: unknown;
+    applicationFlow?: unknown;
+  };
+  if (typeof title !== "string" || title.trim() === "") return null;
+  return typeof applicationFlow === "string" && applicationFlow !== ""
+    ? { title, applicationFlow }
+    : { title };
+}
+
+/** The posting's title in `locale`, or `null` when no posting has this slug. */
+export async function postingTitle(slug: string, locale: string): Promise<string | null> {
+  return (await postingForApply(slug, locale))?.title ?? null;
 }