create-ailk 0.27.0 → 0.28.0

package/templates/apps/web/lib/hub-children.tsx

@@ -0,0 +1,318 @@
+/**
+ * Hub child cards (#10121) — the /alternatives (#6878 D9) and /templates
+ * (#10051 D7) shape, shared by the content hubs that list one child page
+ * type each (/for, /case-studies, /team, …).
+ *
+ * The hub adds a generated card per child page of its type that the hub's
+ * own sections do not already link: into the authored card grid that already
+ * lists its children when there is one, else as one new `items` section
+ * before any trailing closing CTA (#7745 D4). `renderPage` builds the CollectionPage
+ * ItemList JSON-LD from the same sections, so the visible cards and the
+ * ItemList always list the same pages. A child the hub already links keeps
+ * its hand-written card and gets no second one, so a hub whose MDX already
+ * links every child renders exactly as before.
+ *
+ * A prose hub (`bodyMode: "mdx-body"`) never reaches renderPage's
+ * SectionRenderer, so its generated section renders after the MDX body
+ * through renderPage's `trailing` slot.
+ *
+ * Base tree: no paid import, no `oss: false`.
+ */
+import type {
+  getMdxSlugs as defaultGetMdxSlugs,
+  getMdxSource as defaultGetMdxSource,
+  getPageSections as defaultGetPageSections,
+  renderPage,
+  SchemaOrgType,
+} from "@working-theory/page-renderer";
+import {
+  getMdxSlugs as loadMdxSlugs,
+  getMdxSource as loadMdxSource,
+  getPageSections as loadPageSections,
+} from "@working-theory/page-renderer";
+import { SectionRenderer } from "@working-theory/ui/sections";
+
+import {
+  type DetailPage,
+  insertBeforeClosingCtas,
+  listDetailPages,
+} from "./route-family";
+
+type Section = Awaited<ReturnType<typeof defaultGetPageSections>>[number];
+
+/** One hub: its list page, its child type, and how its body renders. */
+export interface HubConfig {
+  /** The list page type, e.g. `UseCasesList`. */
+  listType: SchemaOrgType;
+  /** The hub's slug, translations namespace and route segment, e.g. `for`. */
+  slug: string;
+  /** The child page type, e.g. `UseCase`. */
+  childType: SchemaOrgType;
+  /** The card link label. */
+  linkLabel: string;
+  /** The generated section's id. */
+  sectionId: string;
+  /**
+   * The hub's existing body rule: `sections` always, `mdx-body` always, or
+   * `composed` — sections when the frontmatter carries `sections[]`, the MDX
+   * body otherwise.
+   */
+  body: "sections" | "mdx-body" | "composed";
+  /** Which child pages the hub lists (default: all). */
+  includeChild?: (page: DetailPage) => boolean;
+  /**
+   * One listed page's card (default: title, description and a link to
+   * `/<slug>/<child>` labelled `linkLabel`).
+   */
+  card?: (page: DetailPage) => HubCard;
+  /** A last pass over the hub's final sections (default: none). */
+  mapSections?: (sections: Section[]) => Section[];
+}
+
+/** One generated card. */
+export interface HubCard {
+  title: string;
+  description?: string | undefined;
+  link?: { label: string; href: string } | undefined;
+}
+
+/** A hub route's injectable loaders (tests pass their own). */
+export interface HubLoaders {
+  getMdxSource?: typeof defaultGetMdxSource;
+  getPageSections?: typeof defaultGetPageSections;
+  getMdxSlugs?: typeof defaultGetMdxSlugs;
+}
+
+/**
+ * A link's path for matching: an absolute http(s) URL's pathname, the query
+ * and hash dropped, a leading `/` ensured and trailing `/`s trimmed.
+ */
+function linkPath(href: string): string | null {
+  let path = href.trim();
+  if (/^https?:\/\//i.test(path)) {
+    try {
+      path = new URL(path).pathname;
+    } catch {
+      return null;
+    }
+  }
+  path = path.split(/[?#]/)[0] ?? "";
+  if (!path.startsWith("/")) path = `/${path}`;
+  let end = path.length;
+  while (end > 0 && path[end - 1] === "/") end -= 1;
+  return path.slice(0, end);
+}
+
+/** A BCP-47-shaped first path segment: `en`, `pt-BR`, `zh-Hant`. */
+const LOCALE_SEGMENT = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/;
+
+/** The path without one leading locale segment (`/en/for/a` → `/for/a`). */
+function withoutLocale(path: string): string {
+  const end = path.indexOf("/", 1);
+  if (end === -1) return path;
+  return LOCALE_SEGMENT.test(path.slice(1, end)) ? path.slice(end) : path;
+}
+
+/** Whether a link path names `target`, with or without a locale prefix. */
+function linksTo(path: string, target: string): boolean {
+  return path === target || withoutLocale(path) === target;
+}
+
+/**
+ * Every link path an MDX body carries: markdown link targets and `href`
+ * attributes, the forms a prose hub links its pages with.
+ */
+export function bodyLinkPaths(body: string): string[] {
+  const hrefs = [
+    ...body.matchAll(/\]\(\s*<?([^)\s>]+)/g),
+    ...body.matchAll(/\bhref\s*=\s*\{?\s*["']([^"']+)["']/g),
+  ].map((match) => match[1] ?? "");
+  return hrefs
+    .map(linkPath)
+    .filter((path): path is string => path !== null);
+}
+
+/**
+ * Every link path the sections carry: any `href` or `url` string at any
+ * depth, so an `items` card link, a `team` member's `url` and a CTA all count.
+ */
+export function linkedPaths(sections: readonly unknown[]): string[] {
+  const paths: string[] = [];
+  const walk = (value: unknown): void => {
+    if (Array.isArray(value)) {
+      value.forEach(walk);
+      return;
+    }
+    if (value === null || typeof value !== "object") return;
+    for (const [key, child] of Object.entries(value)) {
+      if ((key === "href" || key === "url") && typeof child === "string") {
+        const path = linkPath(child);
+        if (path !== null) paths.push(path);
+      } else {
+        walk(child);
+      }
+    }
+  };
+  walk(sections);
+  return paths;
+}
+
+/**
+ * The generated section: one card per child page the hub's rendered content
+ * does not already link (`linked`, from `linkedPaths` or `bodyLinkPaths`; a
+ * locale prefix or an absolute URL still counts as a link), or `null` when
+ * there is none.
+ */
+export function childCardsSection(
+  linked: readonly string[],
+  pages: readonly DetailPage[],
+  config: Pick<HubConfig, "slug" | "linkLabel" | "sectionId" | "card">,
+): Section | null {
+  // A child counts as linked at its route path or at its card's own href (a
+  // hub whose public base differs from its route, #10043).
+  const items = pages.flatMap((page) => {
+    const card = config.card?.(page) ?? defaultCard(page, config);
+    const targets = [`/${config.slug}/${page.slug}`];
+    if (card.link !== undefined) targets.push(card.link.href);
+    const linkedAlready = linked.some((path) =>
+      targets.some((t) => linksTo(path, t)),
+    );
+    return linkedAlready ? [] : [card];
+  });
+  if (items.length === 0) return null;
+  return { type: "items", id: config.sectionId, data: { items } } as Section;
+}
+
+function defaultCard(
+  { slug, frontmatter }: DetailPage,
+  config: Pick<HubConfig, "slug" | "linkLabel">,
+): HubCard {
+  const fm = frontmatter as { title?: string; description?: string };
+  return {
+    title: fm.title ?? slug,
+    description: fm.description ?? "",
+    link: { label: config.linkLabel, href: `/${config.slug}/${slug}` },
+  };
+}
+
+type CardItem = { link?: { href?: string; variant?: string } };
+
+/**
+ * Place the generated cards. When an authored `items` section already lists
+ * children of this hub (a card linking `/<hub>/…`), the cards continue that
+ * grid, taking its card link variant, so the hub shows one list. Otherwise
+ * the generated section goes before the closing CTAs (#7745 D4).
+ */
+export function placeChildCards(
+  declared: Section[],
+  generated: Section,
+  hubSlug: string,
+): Section[] {
+  const prefix = `/${hubSlug}/`;
+  const listsChildren = (section: Section): boolean =>
+    section.type === "items" &&
+    ((section.data as { items?: CardItem[] }).items ?? []).some((item) => {
+      const href = item.link?.href;
+      const path = href === undefined ? null : linkPath(href);
+      // Raw first: a short hub slug (`for`) itself looks like a locale.
+      return (
+        path !== null &&
+        (path.startsWith(prefix) || withoutLocale(path).startsWith(prefix))
+      );
+    });
+  let at = declared.length - 1;
+  while (at >= 0 && !listsChildren(declared[at] as Section)) at -= 1;
+  if (at === -1) return insertBeforeClosingCtas(declared, generated);
+
+  const host = declared[at] as Section & { data: { items: CardItem[] } };
+  const variant = host.data.items.find((item) => item.link?.variant)?.link
+    ?.variant;
+  const added = (generated.data as { items: CardItem[] }).items.map((item) =>
+    variant === undefined ? item : { ...item, link: { ...item.link, variant } },
+  );
+  const merged = {
+    ...host,
+    data: { ...host.data, items: [...host.data.items, ...added] },
+  } as Section;
+  return [...declared.slice(0, at), merged, ...declared.slice(at + 1)];
+}
+
+function hasSections(frontmatter: unknown): boolean {
+  const sections = (frontmatter as { sections?: unknown }).sections;
+  return Array.isArray(sections) && sections.length > 0;
+}
+
+type RenderPageInput = Parameters<typeof renderPage>[0];
+
+/**
+ * Everything a hub's `renderPage` call needs beyond its literal `type` and
+ * `slug`, which stay written out in each page.tsx where the content-render
+ * lint reads them.
+ */
+export async function hubPageInput(
+  config: HubConfig,
+  locale: string,
+  loaders: HubLoaders,
+): Promise<Omit<RenderPageInput, "type" | "slug">> {
+  const load = loaders.getMdxSource ?? loadMdxSource;
+  const base = {
+    locale,
+    translationsNamespace: config.slug,
+    ...(loaders.getMdxSource !== undefined && {
+      getMdxSource: loaders.getMdxSource,
+    }),
+  };
+
+  const source = await load(config.listType, config.slug, locale);
+  const mdxBody =
+    config.body === "mdx-body" ||
+    (config.body === "composed" &&
+      (source === null || !hasSections(source.frontmatter)));
+  if (source === null) {
+    // The hub's existing empty-state rule, unchanged.
+    return {
+      ...base,
+      ...(mdxBody && { bodyMode: "mdx-body" as const }),
+      ...(loaders.getPageSections !== undefined && {
+        getPageSections: loaders.getPageSections,
+      }),
+    };
+  }
+
+  const declared = await (loaders.getPageSections ?? loadPageSections)(
+    source.frontmatter,
+  );
+  const pages = await listDetailPages(
+    config.childType,
+    locale,
+    load,
+    loaders.getMdxSlugs ?? loadMdxSlugs,
+  );
+  // A prose hub renders its MDX body, never its declared sections, so its
+  // existing links are read from the body and its cards stand alone after it.
+  const linked = mdxBody
+    ? bodyLinkPaths(source.body)
+    : linkedPaths(declared);
+  const generated = childCardsSection(
+    linked,
+    config.includeChild ? pages.filter(config.includeChild) : pages,
+    config,
+  );
+  const placed =
+    generated === null
+      ? declared
+      : mdxBody
+        ? insertBeforeClosingCtas(declared, generated)
+        : placeChildCards(declared, generated, config.slug);
+  const sections = config.mapSections ? config.mapSections(placed) : placed;
+
+  return {
+    ...base,
+    getPageSections: async () => sections,
+    ...(mdxBody && { bodyMode: "mdx-body" as const }),
+    ...(mdxBody &&
+      generated !== null && {
+        trailing: <SectionRenderer sections={[generated]} locale={locale} />,
+      }),
+  };
+}

package/templates/apps/web/lib/modules.generated.ts

@@ -7,3 +7,12 @@
 
 /** The scheduling module's booking pages (/meet, /private) exist. */
 export const SCHEDULING_PAGES: boolean = false;
+
+/** The marketing module's public pages exist (#10040): false on a hub. */
+export const MARKETING_PAGES: boolean = true;
+
+/** The docs-blog module's /docs and /blog pages exist (#10040). */
+export const DOCS_BLOG_PAGES: boolean = false;
+
+/** Any public page exists: robots, sitemap, llms.txt and the noindex header read this (#10040 D6/D7). */
+export const PUBLIC_PAGES: boolean = true;

package/templates/apps/web/lib/nav-label-check.ts

@@ -0,0 +1,61 @@
+// nav-label-check.ts — find nav keys a locale's messages file does not carry
+// (#10045 D2). Run before `next build` by `scripts/check-nav-labels.ts`.
+//
+// A locale's catalog is `messages/<locale>.json` plus the site overlay
+// `messages/site/<locale>.json` (falling back to `messages/site/en.json`),
+// matching how `i18n/request.ts` loads them, so a key the site adds in its
+// overlay counts as present.
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { navMessageKeys } from "./nav-label-keys";
+
+export interface MissingNavLabel {
+  key: string;
+  /** The `messages/<locale>.json` file the key is missing from. */
+  file: string;
+}
+
+function readJson(file: string): unknown {
+  return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : undefined;
+}
+
+/** Every (key, messages file) pair where a used nav key has no text. */
+export function findMissingNavLabels(
+  messagesDir: string,
+  keys: Iterable<string>,
+): MissingNavLabel[] {
+  const wanted = [...new Set(keys)].sort();
+  const englishOverlay = join(messagesDir, "site", "en.json");
+  const missing: MissingNavLabel[] = [];
+  const catalogs = readdirSync(messagesDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .map((entry) => entry.name)
+    .sort();
+  for (const name of catalogs) {
+    const file = join(messagesDir, name);
+    const ownOverlay = join(messagesDir, "site", name);
+    const overlay = existsSync(ownOverlay) ? ownOverlay : englishOverlay;
+    const present = new Set([
+      ...navMessageKeys(readJson(file)),
+      ...navMessageKeys(readJson(overlay)),
+    ]);
+    for (const key of wanted) {
+      if (!present.has(key)) missing.push({ key, file });
+    }
+  }
+  return missing;
+}
+
+/** One line per missing key, naming the key and the file. */
+export function formatMissingNavLabels(
+  missing: readonly MissingNavLabel[],
+): string {
+  return missing
+    .map(
+      ({ key, file }) =>
+        `nav key "${key}" is used by the site nav but missing from ${file} (namespace "nav")`,
+    )
+    .join("\n");
+}

package/templates/apps/web/lib/nav-label-keys.ts

@@ -0,0 +1,78 @@
+// nav-label-keys.ts — the set of `nav` message keys the site chrome resolves
+// (#10045).
+//
+// The header and footer render translated strings, but `nav-config.ts`
+// carries only message keys. Every key is looked up in the `nav` namespace by
+// name — there is no hand-written list of allowed keys — so adding a page to
+// the nav is one entry in `nav-config.ts` plus its text in
+// `messages/<locale>.json` (or the site overlay, `messages/site/<locale>.json`).
+// `scripts/check-nav-labels.ts` fails the build when a key used here is
+// missing from a locale's catalog.
+
+import { footerColumns, navItems } from "./nav-config";
+
+/**
+ * Every field on a nav-config entry that names a `nav` message key:
+ * `labelKey` (an item or action), `headingKey` (a flyout group or footer
+ * column) and `descKey` (a flyout feature's description). These are the only
+ * three key-bearing fields in `@working-theory/ui`'s chrome types.
+ */
+const KEY_FIELDS: ReadonlySet<string> = new Set([
+  "labelKey",
+  "headingKey",
+  "descKey",
+]);
+
+/**
+ * The `nav` keys the layout itself resolves by name, beside the ones
+ * `nav-config.ts` declares: the session actions, the centred footer's FAQ
+ * link and the menu controls.
+ */
+export const LAYOUT_NAV_KEYS: readonly string[] = [
+  "account",
+  "signIn",
+  "signOut",
+  "signUp",
+  "faq",
+  "openMenu",
+  "closeMenu",
+  "moreLinks",
+];
+
+/** Every key-bearing field value in the given nav configs, at any depth. */
+export function collectNavLabelKeys(
+  ...configs: readonly unknown[]
+): Set<string> {
+  const keys = new Set<string>();
+  const walk = (value: unknown): void => {
+    if (Array.isArray(value)) {
+      for (const entry of value) walk(entry);
+      return;
+    }
+    if (typeof value !== "object" || value === null) return;
+    for (const [field, child] of Object.entries(value)) {
+      if (KEY_FIELDS.has(field)) {
+        if (typeof child === "string") keys.add(child);
+      } else {
+        walk(child);
+      }
+    }
+  };
+  for (const config of configs) walk(config);
+  return keys;
+}
+
+/** The string keys of a message catalog's `nav` namespace. */
+export function navMessageKeys(catalog: unknown): string[] {
+  if (typeof catalog !== "object" || catalog === null) return [];
+  const nav = (catalog as Record<string, unknown>)["nav"];
+  if (typeof nav !== "object" || nav === null) return [];
+  return Object.entries(nav)
+    .filter(([, value]) => typeof value === "string")
+    .map(([key]) => key);
+}
+
+/** Every `nav` key the site chrome uses: `nav-config.ts`'s keys and the layout's own. */
+export function usedNavLabelKeys(): Set<string> {
+  return new Set([...collectNavLabelKeys(navItems, footerColumns), ...LAYOUT_NAV_KEYS]);
+}

package/templates/apps/web/lib/newsletter.actions.ts

@@ -32,6 +32,11 @@
  * is success; a 503 `lead_capture_not_configured` or an unreachable API
  * (status 0, 502, 504) is `unavailable`. Otherwise (a Free build has no flow
  * route) it posts `leads.subscribe`, as before.
+ *
+ * The bot check (#9255 D4): each write path runs `runBotCheck` after its
+ * consent refusal and immediately before its hub call, so one signup is
+ * checked exactly once. A bot gets the generic error and a check that cannot
+ * decide `unavailable`; neither is sent.
  */
 
 import { flows, leads, visitorForwardHeaders } from "@working-theory/api-client";
@@ -41,8 +46,9 @@ import { cookies, headers } from "next/headers";
 import { getLocale } from "next-intl/server";
 import { z } from "zod";
 
-import { checkRateLimit, clientIpFromHeaders } from "../src/lib/rate-limit";
+import { clientIpFromHeaders, takeVisitorLimit } from "../src/lib/rate-limit";
 
+import { runBotCheck } from "./bot-check";
 import { consentVisitorHeader, readConsentVisitor } from "./consent-visitor";
 import { inPageView, readServedMagnet } from "./in-page-magnet";
 
@@ -54,6 +60,8 @@ const RATE_LIMITED = "Too many signups from here. Please try again in a few minu
 // spend the bucket every visitor shares.
 const RATE_LIMIT_MAX_CALLS = 30;
 const RATE_LIMIT_WINDOW_MS = 10 * 60 * 1000;
+/** Outside a request scope there is no address: the shared bucket. */
+const NO_HEADERS = { get: () => null };
 
 /** The form's one field; zod's default message is the field error shown. */
 const newsletterFormSchema = z.object({ email: z.string().email() });
@@ -73,6 +81,18 @@ function isApiUnreachable(res: { status: number }): boolean {
   return res.status === 0 || res.status === 502 || res.status === 504;
 }
 
+/** #9255 D4 — the spoke edge's bot check; `null` to go on to the write. */
+async function botRefusal(): Promise<LeadCaptureFormState | null> {
+  const botCheck = await runBotCheck({
+    source: "bot-check",
+    target: "subscribeNewsletterAction",
+    scope: "write",
+  });
+  if (botCheck === "bot") return { kind: "error", message: GENERIC_ERROR };
+  if (botCheck === "unavailable") return { kind: "unavailable" };
+  return null;
+}
+
 /**
  * The signup through the served newsletter magnet, or `null` when it does not
  * map (absent, draft, a Free build with no flow route, or not a one-field
@@ -102,6 +122,8 @@ async function submitThroughMagnet(
     for (const purpose of consent.purposes) values[`${consent.field}.${purpose}`] = true;
   }
   const payload = { stepKey: view.stepKey, values, locale };
+  const refused = await botRefusal();
+  if (refused !== null) return refused;
   try {
     const res = init
       ? await flows.submitStep(NEWSLETTER_FLOW_SLUG, payload, init)
@@ -142,15 +164,15 @@ export async function subscribeNewsletterAction(
     // No request scope to read — no forwarding, and the visitor is "unknown".
   }
 
-  // No readable address: skip the per-visitor limit rather than put every
-  // visitor in one shared bucket (the contact action's rule).
-  const visitor = requestHeaders ? clientIpFromHeaders(requestHeaders) : "unknown";
+  // No readable address: the shared, wider bucket, never a skip (#9967 D1,
+  // the contact action's rule).
   if (
-    visitor !== "unknown" &&
-    !checkRateLimit(`newsletter:${visitor}`, RATE_LIMIT_MAX_CALLS, RATE_LIMIT_WINDOW_MS)
+    !takeVisitorLimit("newsletter", requestHeaders ?? NO_HEADERS, RATE_LIMIT_MAX_CALLS, RATE_LIMIT_WINDOW_MS)
+      .allowed
   ) {
     return { kind: "error", message: RATE_LIMITED };
   }
+  const visitor = clientIpFromHeaders(requestHeaders ?? NO_HEADERS);
 
   let init: { headers: Record<string, string> } | undefined;
   if (requestHeaders) {
@@ -179,6 +201,9 @@ export async function subscribeNewsletterAction(
   // The Free path renders the seeded config, whose consent box gates the post.
   if (!consented) return { kind: "error", fieldErrors: { consent: CONSENT_REQUIRED } };
 
+  const refused = await botRefusal();
+  if (refused !== null) return refused;
+
   const siteId = process.env.AILK_SITE_ID ?? "default";
   const body = { siteId, source: "newsletter", email: parsed.data.email };
   try {