create-ailk 0.27.0 → 0.28.0

package/templates/apps/web/lib/service-listing.ts

@@ -0,0 +1,89 @@
+/**
+ * The services listing (#10043 D8) — a service's public URL under the site's
+ * services base and its category, the list a category page shows of its
+ * services, and the hub's own section links re-pointed onto the base. Pure,
+ * no I/O: the routes load the pages and the translated labels and pass them
+ * in, so no user-facing copy lives here (customer-facing-i18n, ADR 0019).
+ *
+ * Base tree: no paid import, no `oss: false`.
+ */
+import { pagePath } from "@working-theory/templates/routes";
+import type { PageSection } from "@working-theory/validation";
+
+import type { DetailPage } from "./route-family";
+import {
+  SERVICES_PATH,
+  SERVICES_ROUTE,
+  toPublicServicesHref,
+} from "./services-path";
+
+type ItemsSection = Extract<PageSection, { type: "items" }>;
+
+/** The `services` messages namespace labels a category's list reads (#10043 D11). */
+export interface ServiceListingLabels {
+  childrenHeading: string;
+  viewService: string;
+}
+
+/** A service's public path: `<base>[/<category>]/<slug>`. */
+export function servicePublicPath(slug: string, parent?: string): string {
+  return pagePath({ type: "Service", slug, parent }, SERVICES_PATH);
+}
+
+/** The services whose `parent` is `category`, from a slug-sorted page list. */
+export function childServices(
+  pages: DetailPage[],
+  category: string,
+): DetailPage[] {
+  return pages.filter((page) => page.frontmatter.parent === category);
+}
+
+/** The list a category page renders after its body: one card per child service. */
+export function serviceChildrenSection(
+  children: DetailPage[],
+  labels: ServiceListingLabels,
+): ItemsSection {
+  const text = (value: unknown): string | undefined =>
+    typeof value === "string" && value.length > 0 ? value : undefined;
+  return {
+    type: "items",
+    id: "service-children",
+    data: {
+      headline: labels.childrenHeading,
+      items: children.map((child) => ({
+        title: text(child.frontmatter.title) ?? child.slug,
+        description:
+          text(child.frontmatter.summary) ??
+          text(child.frontmatter.description) ??
+          "",
+        link: {
+          label: labels.viewService,
+          href: servicePublicPath(child.slug, text(child.frontmatter.parent)),
+        },
+      })),
+    },
+  };
+}
+
+function mapHrefs(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(mapHrefs);
+  if (value === null || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [
+      key,
+      key === "href" && typeof entry === "string"
+        ? toPublicServicesHref(entry)
+        : mapHrefs(entry),
+    ]),
+  );
+}
+
+/**
+ * The hub's sections with every site `href` starting `/services` re-pointed
+ * onto the base, at any depth; the same array on a site with no
+ * `services.path`.
+ */
+export function withPublicServicesSections<S>(sections: S[]): S[] {
+  if (SERVICES_PATH === SERVICES_ROUTE) return sections;
+  return sections.map((section) => mapHrefs(section) as S);
+}

package/templates/apps/web/lib/services-path.ts

@@ -0,0 +1,97 @@
+// services-path.ts — where the services live (#10043 D5).
+//
+// A site sets `services: { path: /capabilities }` in `content/_site.mdx`;
+// `next.config.mjs` parses it at build and bakes it into
+// `NEXT_PUBLIC_AILK_SERVICES_PATH`. The services routes never move — they stay
+// at `app/[locale]/services/` (`SERVICES_ROUTE`) — and the middleware maps the
+// public path onto them and answers the old `/services` URLs with a 308. Every
+// surface that names a services URL reads `SERVICES_PATH` here.
+//
+// Edge-safe and client-safe: this file imports nothing at runtime (the
+// `NavItem` import is type-only), so the middleware and the client signed-in
+// nav can both read it. The shape is `docs-path.ts`'s (#10041).
+import type { NavItem } from "@working-theory/ui";
+
+/** The internal services route — the directory under `app/[locale]/`. Always `/services`. */
+export const SERVICES_ROUTE = "/services";
+
+/** The services' public base: the site's `services.path`, or `/services` when it sets none. */
+export const SERVICES_PATH: string =
+  process.env.NEXT_PUBLIC_AILK_SERVICES_PATH || SERVICES_ROUTE;
+
+/**
+ * `href` at the internal services route — `/services`, or starting
+ * `/services/`, `/services?` or `/services#` — with that prefix replaced by
+ * `SERVICES_PATH`. Anything else (absolute URLs, `/servicesx`, a
+ * locale-prefixed path) is returned unchanged. The identity on a site with no
+ * `services.path`.
+ */
+export function toPublicServicesHref(href: string): string {
+  if (SERVICES_PATH === SERVICES_ROUTE) return href;
+  const rest = href.slice(SERVICES_ROUTE.length);
+  if (href.startsWith(SERVICES_ROUTE) && (rest === "" || /^[/?#]/.test(rest))) {
+    return SERVICES_PATH + rest;
+  }
+  return href;
+}
+
+/**
+ * A locale-less pathname at or under `SERVICES_PATH`, mapped onto the internal
+ * route (`/services` + the rest); `null` for anything else, and always `null`
+ * on a site with no `services.path`.
+ */
+export function toInternalServicesPath(bare: string): string | null {
+  if (SERVICES_PATH === SERVICES_ROUTE) return null;
+  if (bare === SERVICES_PATH) return SERVICES_ROUTE;
+  if (bare.startsWith(`${SERVICES_PATH}/`)) {
+    return SERVICES_ROUTE + bare.slice(SERVICES_PATH.length);
+  }
+  return null;
+}
+
+type NavFlyout = NonNullable<NavItem["flyout"]>;
+
+function mapPath<T extends { path: string }>(entry: T): T {
+  return { ...entry, path: toPublicServicesHref(entry.path) };
+}
+
+function mapFlyout(flyout: NavFlyout): NavFlyout {
+  return {
+    ...flyout,
+    features: flyout.features.map(mapPath),
+    ...(flyout.groups
+      ? {
+          groups: flyout.groups.map((group) => ({
+            ...group,
+            items: group.items.map(mapPath),
+          })),
+        }
+      : {}),
+    actions: flyout.actions.map(mapPath),
+  };
+}
+
+/**
+ * Copies of the nav items with every services path mapped onto
+ * `SERVICES_PATH` — the item's own `path` and each flyout feature, group item
+ * and action. Every other field is carried by reference.
+ */
+export function withPublicServicesPaths(items: NavItem[]): NavItem[] {
+  return items.map((item) => ({
+    ...item,
+    ...(item.path !== undefined
+      ? { path: toPublicServicesHref(item.path) }
+      : {}),
+    ...(item.flyout ? { flyout: mapFlyout(item.flyout) } : {}),
+  }));
+}
+
+/** Copies of the footer columns with every item's services path mapped onto `SERVICES_PATH`. */
+export function withPublicServicesColumns<
+  C extends { items: { path: string }[] },
+>(columns: C[]): C[] {
+  return columns.map((column) => ({
+    ...column,
+    items: column.items.map(mapPath),
+  }));
+}

package/templates/apps/web/lib/site-header.ts

@@ -0,0 +1,94 @@
+/**
+ * The site's header settings (#10046) — `_site.mdx`'s top-level `header`.
+ *
+ * `header.cta` replaces the signed-out Sign in / Sign up pair with the site's
+ * own button; `header.signIn` keeps Sign in beside it as a quieter text link
+ * (`link`, the default) or hides it. Signed in, the header is unchanged.
+ *
+ * A local frontmatter read rather than `@working-theory/site-config/server`,
+ * for the same reason as `app/[locale]/contact/site-contact-email.ts`:
+ * `architecture.yaml` keeps `node:fs` out of a tree that also carries edge
+ * routes (#1567). The value is validated against the canonical schema from
+ * the client-safe `/schema` entry.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  SiteConfigSchema,
+  type SiteHeader,
+} from "@working-theory/site-config/schema";
+import type { NavAction } from "@working-theory/ui/chrome";
+import { parse as parseYaml } from "yaml";
+
+import { resolveContentRoot } from "./site-brand";
+
+/** The `labelKey` the CTA action carries; its test id is `nav-action-headerCta`. */
+export const HEADER_CTA_LABEL_KEY = "headerCta";
+
+type LinkAction = Extract<NavAction, { path: string }>;
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+const HeaderSchema = SiteConfigSchema.shape.header.unwrap();
+
+let warned = false;
+
+/**
+ * The validated `header`, else `undefined`. An absent file, frontmatter or
+ * key is silent; an invalid `header` warns once per process, naming the field
+ * path and never the value.
+ */
+export function readSiteHeader(): SiteHeader | undefined {
+  try {
+    const raw = readFileSync(join(resolveContentRoot(), "_site.mdx"), "utf8");
+    const match = FRONTMATTER_RE.exec(raw);
+    if (!match) return undefined;
+    const fm: unknown = parseYaml(match[1] ?? "");
+    if (!fm || typeof fm !== "object") return undefined;
+
+    const { header } = fm as { header?: unknown };
+    if (header === undefined) return undefined;
+
+    // #10049 — `style` is page-chrome.ts's to validate and warn about; set it
+    // aside so a bad style never drops the button.
+    const parsed = HeaderSchema.safeParse(
+      header !== null && typeof header === "object" ? { ...header, style: undefined } : header,
+    );
+    if (parsed.success) return parsed.data;
+    if (!warned) {
+      warned = true;
+      const issue = parsed.error.issues[0];
+      console.warn(
+        `[site-header] ignoring _site.mdx header: ${["header", ...(issue?.path ?? [])].join(".")} ${issue?.message ?? ""}`,
+      );
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The signed-out header actions. No `cta` → the auth pair as given. A `cta`
+ * → Sign in restyled as a text link (unless `signIn: hidden`), then the CTA
+ * as the primary button; Sign up is dropped. Never mutates `authActions`.
+ */
+export function signedOutHeaderActions(
+  header: SiteHeader | undefined,
+  authActions: readonly LinkAction[],
+): LinkAction[] {
+  const cta = header?.cta;
+  if (!cta) return [...authActions];
+
+  const signIn = authActions.find((action) => action.labelKey === "signIn");
+  const signInPart: LinkAction[] =
+    signIn && header.signIn !== "hidden"
+      ? [{ ...signIn, variant: "ghost" }]
+      : [];
+  return [
+    ...signInPart,
+    { labelKey: HEADER_CTA_LABEL_KEY, path: cta.href, variant: "primary" },
+  ];
+}

package/templates/apps/web/lib/telemetry-scrub.ts

@@ -13,10 +13,45 @@
 // carries the submitter's address as `/sign-in?email=…` and the hub's
 // authorize step as `login_hint=…` — personal data GA and Sentry must not get.
 //
+// `ref` joined by #9966 (D2, SEC-9966-7): the hub's consent page,
+// `/account/connect?ref=…`, carries a sealed authorize continuation.
+//
 // Mirrored (duplicated, not shared) in packages/analytics/src/scrub.ts,
 // since apps/* must not import @working-theory/* packages — keep both lists
 // in sync (#5613).
-export const TOKEN_QUERY_PARAMS = ["g", "session_id", "email", "login_hint"];
+export const TOKEN_QUERY_PARAMS = [
+  "g",
+  "session_id",
+  "email",
+  "login_hint",
+  "ref",
+];
+
+// The same grant id rides a PATH too: `deliverables.openGrant` fetches
+// `<hub>/v1/deliverables/<grantId>` server-side, so a sampled server trace or
+// a fetch breadcrumb would carry it (#9162, PR #9152's security review). The
+// id segment is replaced anywhere in the string, so a span description
+// (`GET <url>`) is redacted too when a caller passes one. `/v1/deliverables/open/<slug>` is the ungated
+// read; a slug is not a credential. apps/web only: the analytics mirror sees
+// page URLs, never this server-side fetch.
+const GRANT_PATH = /(\/v1\/deliverables\/)(?!open(?:[/?#\s]|$))[^/?#\s]+/g;
+const GRANT_PATH_REDACTED = "$1:grantId";
+
+// #9969 D9 (#8329) — the Stripe SDK's own request URLs carry a customer id:
+// `customers.retrieve` in the path (`/v1/customers/cus_…`) and
+// `subscriptions.list` in the query (`?customer=cus_…`), and server-side
+// Sentry records those outgoing requests. A changeset once stated this as a
+// precondition for turning server telemetry on; it now lives here, with its
+// enforcement. Server-side only, so not mirrored into packages/analytics:
+// GA sees page URLs, never a Stripe API URL.
+const STRIPE_ID_QUERY_PARAMS = ["customer"];
+const STRIPE_CUSTOMER_SEGMENT = /\/cus_[A-Za-z0-9]+(?=[/?#\s]|$)/g;
+const STRIPE_CUSTOMER_SEGMENT_REDACTED = "/cus_redacted";
+
+const SCRUBBED_QUERY_PARAMS = [
+  ...TOKEN_QUERY_PARAMS,
+  ...STRIPE_ID_QUERY_PARAMS,
+];
 
 // Sentry navigation breadcrumbs (`data.to`/`data.from`) are relative
 // (`path?search`, no origin) rather than the absolute URLs GA and
@@ -29,7 +64,10 @@ function hasScheme(url: string): boolean {
   return /^[a-zA-Z][a-zA-Z\d+\-.]*:\/\//.test(url) || url.startsWith("//");
 }
 
-export function scrubTelemetryUrl(url: string): string {
+export function scrubTelemetryUrl(input: string): string {
+  const url = input
+    .replace(GRANT_PATH, GRANT_PATH_REDACTED)
+    .replace(STRIPE_CUSTOMER_SEGMENT, STRIPE_CUSTOMER_SEGMENT_REDACTED);
   const relative = !hasScheme(url);
   let parsed: URL;
   try {
@@ -39,7 +77,7 @@ export function scrubTelemetryUrl(url: string): string {
   }
 
   let changed = false;
-  for (const param of TOKEN_QUERY_PARAMS) {
+  for (const param of SCRUBBED_QUERY_PARAMS) {
     if (parsed.searchParams.has(param)) {
       parsed.searchParams.delete(param);
       changed = true;
@@ -52,3 +90,30 @@ export function scrubTelemetryUrl(url: string): string {
   const result = parsed.toString();
   return relative ? result.slice(RELATIVE_URL_BASE.length) : result;
 }
+
+/**
+ * A bare query string (`?a=1&b=2`, with or without the `?`) with the same
+ * params dropped — the SDK records an outgoing request's query under
+ * `http.query` apart from its URL (#9969 D9).
+ */
+export function scrubTelemetryQuery(query: string): string {
+  const params = new URLSearchParams(query);
+  let changed = false;
+  for (const param of SCRUBBED_QUERY_PARAMS) {
+    if (params.has(param)) {
+      params.delete(param);
+      changed = true;
+    }
+  }
+  if (!changed) return query;
+  const rest = params.toString();
+  return rest === "" ? "" : `${query.startsWith("?") ? "?" : ""}${rest}`;
+}
+
+/** An HTTP client span's `<METHOD> <url>` with its URL scrubbed (#9969 D9). */
+export function scrubSpanDescription(description: string): string {
+  const match = /^([A-Z]+) (\S+)$/.exec(description);
+  return match
+    ? `${match[1]} ${scrubTelemetryUrl(match[2]!)}`
+    : scrubTelemetryUrl(description);
+}

package/templates/apps/web/lib/template-listing.ts

@@ -0,0 +1,169 @@
+/**
+ * The template-listing mapping (#10051 D6) — a TemplatePage's frontmatter to
+ * the /templates hub's card and to the generated sections of its own
+ * /templates/<slug> page. Pure, no I/O: the routes load the pages and the
+ * translated labels and pass them in, so no user-facing copy lives here
+ * (customer-facing-i18n, ADR 0019).
+ *
+ * Base tree: no paid import, no `oss: false`.
+ */
+import { SITE_CATEGORIES } from "@working-theory/schema/categories";
+import type { PageSection } from "@working-theory/validation";
+
+/** The `templates` messages namespace, read by the routes (#10051 D8). */
+export interface TemplateLabels {
+  getIt: string;
+  startFree: string;
+  viewDemo: string;
+  viewTemplate: string;
+  included: string;
+  demoBadge: string;
+  /** The tail of a category label cut at {@link MAX_CATEGORY_NAMES}: "+9 more". */
+  moreCategories: (count: number) => string;
+}
+
+/** Read the labels from the `templates` namespace's translator. */
+export function templateLabels(
+  t: (key: keyof TemplateLabels, values?: { count: number }) => string,
+): TemplateLabels {
+  return {
+    getIt: t("getIt"),
+    startFree: t("startFree"),
+    viewDemo: t("viewDemo"),
+    viewTemplate: t("viewTemplate"),
+    included: t("included"),
+    demoBadge: t("demoBadge"),
+    moreCategories: (count) => t("moreCategories", { count }),
+  };
+}
+
+/**
+ * At most this many category names show in a card or hero label; the rest
+ * collapse into "+N more", so a template listed under twelve categories keeps
+ * a one-line label and the card titles in a row stay aligned (design review
+ * round 1, B2).
+ */
+export const MAX_CATEGORY_NAMES = 3;
+
+/** The TemplatePage frontmatter fields this mapping reads. */
+interface TemplateFrontmatter {
+  title?: string;
+  description?: string;
+  summary?: string;
+  thumbnail?: string;
+  categories?: readonly string[];
+  demoUrl?: string;
+  getItUrl?: string;
+  price?: number;
+  includes?: readonly { title: string; description: string }[];
+}
+
+type CardItem = Extract<
+  PageSection,
+  { type: "items" }
+>["data"]["items"][number];
+
+function fields(frontmatter: unknown): TemplateFrontmatter {
+  return (frontmatter ?? {}) as TemplateFrontmatter;
+}
+
+/**
+ * The known category display names, the first {@link MAX_CATEGORY_NAMES}
+ * joined and the rest counted; undefined when none is known.
+ */
+function categoryNames(
+  categories: readonly string[] | undefined,
+  labels: TemplateLabels,
+): string | undefined {
+  const names = (categories ?? []).flatMap((slug) => {
+    const found = SITE_CATEGORIES.find((category) => category.slug === slug);
+    return found === undefined ? [] : [found.name];
+  });
+  if (names.length === 0) return undefined;
+  const shown = names.slice(0, MAX_CATEGORY_NAMES);
+  const hidden = names.length - shown.length;
+  return hidden > 0
+    ? [...shown, labels.moreCategories(hidden)].join(" · ")
+    : shown.join(" · ");
+}
+
+/** One /templates card for a TemplatePage. */
+export function templateCard(
+  page: { slug: string; frontmatter: unknown },
+  labels: TemplateLabels,
+): CardItem {
+  const fm = fields(page.frontmatter);
+  const title = fm.title ?? page.slug;
+  const eyebrow = categoryNames(fm.categories, labels);
+  return {
+    title,
+    description: fm.summary ?? fm.description ?? "",
+    ...(fm.thumbnail !== undefined && {
+      image: { src: fm.thumbnail, alt: title },
+    }),
+    ...(eyebrow !== undefined && { eyebrow }),
+    ...(fm.demoUrl !== undefined && { badge: labels.demoBadge }),
+    link: { label: labels.viewTemplate, href: `/templates/${page.slug}` },
+  };
+}
+
+/** "Start free" for a template priced at exactly 0, else "Get it". */
+export function templateActionLabel(
+  price: number | undefined,
+  labels: TemplateLabels,
+): string {
+  return price === 0 ? labels.startFree : labels.getIt;
+}
+
+/**
+ * The generated top of a /templates/<slug> page: a hero carrying the name,
+ * summary, thumbnail, categories, the Get it / Start free action and the
+ * View demo link, then the "What's included" list.
+ */
+export function templateDetailSections(
+  frontmatter: unknown,
+  labels: TemplateLabels,
+): [PageSection, PageSection] {
+  const fm = fields(frontmatter);
+  const title = fm.title ?? "";
+  const subheadline = fm.summary ?? fm.description;
+  const eyebrow = categoryNames(fm.categories, labels);
+  const hero: PageSection = {
+    type: "hero",
+    id: "template-hero",
+    data: {
+      headline: title,
+      ...(subheadline !== undefined && { subheadline }),
+      ...(eyebrow !== undefined && { eyebrow }),
+      ...(fm.thumbnail !== undefined && {
+        image: { src: fm.thumbnail, alt: title },
+      }),
+      ...(fm.getItUrl !== undefined && {
+        primaryCta: {
+          label: templateActionLabel(fm.price, labels),
+          href: fm.getItUrl,
+        },
+      }),
+      ...(fm.demoUrl !== undefined && {
+        secondaryCta: {
+          label: labels.viewDemo,
+          href: fm.demoUrl,
+          variant: "outline" as const,
+        },
+      }),
+    },
+  };
+  const included: PageSection = {
+    type: "items",
+    id: "template-included",
+    data: {
+      headline: labels.included,
+      variant: "minimal",
+      items: (fm.includes ?? []).map(({ title: rowTitle, description }) => ({
+        title: rowTitle,
+        description,
+      })),
+    },
+  };
+  return [hero, included];
+}