create-ailk 0.1.0 → 0.2.0

package/templates/apps/web/lib/__tests__/structured-data.test.tsx

@@ -0,0 +1,499 @@
+/**
+ * Day-one structured-data check for the site this app ships (#5021).
+ *
+ * Two checks, both delegating to `@working-theory/schema-validator` so they
+ * get stricter as the validator does (the #5019 `mainEntity` rule included):
+ *
+ *   1. Content-driven — every content page under `content/<locale>/<Type>/`
+ *      is built into JSON-LD through `pageToJsonLd`, the same path the app
+ *      takes at render time (builders + pack + breadcrumb + section
+ *      contributions), flattened, and validated for its type.
+ *   2. Route-emission — every `page.tsx` under `app/[locale]/` is rendered
+ *      with the site's own content and must emit a
+ *      `<script type="application/ld+json">` that validates for the route's
+ *      type. A route that renders nothing, or that is not built on
+ *      `renderPage`, fails unless it is listed in `NO_STRUCTURED_DATA_ROUTES`
+ *      with a reason.
+ *
+ * Nothing here is a fixture list: the content walk reads whatever the site
+ * has under `content/`, and the route walk reads whatever the app has under
+ * `app/[locale]/`. A page written today is checked today.
+ *
+ * Lives in `lib/__tests__/` because `create-ailk`'s template snapshot strips
+ * `apps/web/__tests__` and `apps/web/app/[locale]/__tests__` (#4154) — a
+ * scaffolded site keeps this file. `packages/create-ailk/__tests__/
+ * structured-data-check.test.ts` pins that.
+ *
+ * Pages are enumerated through the content adapter rather than
+ * `content/.compiled/manifest.json`: the manifest is written by
+ * `tools/content-compile`, which the scaffold does not ship, and the adapter
+ * reads the same files with the same frontmatter schema the manifest is
+ * compiled from. See docs/internal/decisions/scaffold-structured-data-check.md.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+
+import { render } from "@testing-library/react";
+import type {
+  ContentPage,
+  SchemaOrgType as PageType,
+} from "@working-theory/content-adapters";
+import {
+  SCHEMA_ORG_TYPES,
+  createMdxAdapter,
+} from "@working-theory/content-adapters";
+import {
+  getPageSections,
+  pageToJsonLd,
+  type JsonLdObject,
+} from "@working-theory/page-renderer";
+import {
+  knownSchemaOrgTypes,
+  validatePageGraph,
+  type SchemaOrgType,
+  type ValidationError,
+} from "@working-theory/schema-validator";
+import type { ReactElement } from "react";
+import { parse as parseYaml } from "yaml";
+
+// Detail routes call notFound() on a missing page; a thrown error is how the
+// test sees it (the same shape the per-surface suites use).
+jest.mock("next/navigation", () => ({
+  __esModule: true,
+  ...jest.requireActual<Record<string, unknown>>("next/navigation"),
+  notFound: jest.fn(() => {
+    throw new Error("NEXT_NOT_FOUND");
+  }),
+}));
+
+// Telemetry is a side-effect boundary (the contact route's intake wrapper
+// reports through it); the same mock the contact suites use.
+jest.mock("@working-theory/analytics/server", () => ({
+  track: jest.fn().mockResolvedValue(undefined),
+}));
+
+// ── Where the site's content and routes live ────────────────────────────────
+
+const CONTENT_ROOT =
+  process.env.AILK_CONTENT_ROOT ?? resolve(__dirname, "../../../../content");
+const ROUTE_ROOT = resolve(__dirname, "../../app/[locale]");
+const SITE_ROOT = resolve(__dirname, "../../../..");
+
+/**
+ * The site's default locale, read the way `next.config.mjs` bakes it
+ * (`project.yaml` → `product.default_locale`, "en" when absent). The env var
+ * is the baked value at build time; under jest it is normally unset, so the
+ * file is the source and the env var only an override.
+ */
+function readDefaultLocale(): string {
+  const fromEnv = process.env.NEXT_PUBLIC_DEFAULT_LOCALE;
+  if (fromEnv !== undefined && fromEnv.length > 0) return fromEnv;
+  const file = join(SITE_ROOT, "project.yaml");
+  if (!existsSync(file)) return "en";
+  const doc = parseYaml(readFileSync(file, "utf8")) as {
+    product?: { default_locale?: unknown };
+  } | null;
+  const value = doc?.product?.default_locale;
+  return typeof value === "string" && value.length > 0 ? value : "en";
+}
+const DEFAULT_LOCALE = readDefaultLocale();
+
+// `pageToJsonLd`'s content selector resolves `content/` from cwd; pin it to
+// the same root this file walks so the route check renders the same pages.
+if (process.env.AILK_CONTENT_ROOT === undefined) {
+  process.env.AILK_CONTENT_ROOT = CONTENT_ROOT;
+}
+
+// Mirrors the locale-directory rule in tools/content-compile and the adapter.
+const LOCALE_RE = /^[a-z]{2}(-[A-Z]{2})?$/;
+
+function subdirs(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+}
+
+/** `content/<locale>/<TypeDir>` → every (locale, type dir) pair on disk. */
+function contentTypeDirs(): Array<{ locale: string; typeDir: string }> {
+  const out: Array<{ locale: string; typeDir: string }> = [];
+  for (const locale of subdirs(CONTENT_ROOT).filter((n) => LOCALE_RE.test(n))) {
+    for (const typeDir of subdirs(join(CONTENT_ROOT, locale))) {
+      // `_drafts/`-style hidden dirs are invisible to the adapter too.
+      if (typeDir.startsWith("_") || typeDir.startsWith(".")) continue;
+      out.push({ locale, typeDir });
+    }
+  }
+  return out;
+}
+
+const adapter = createMdxAdapter({
+  contentRoot: CONTENT_ROOT,
+  defaultLocale: DEFAULT_LOCALE,
+});
+
+// ── JSON-LD flatten + validate (the ten lines from tools/scrape-jsonld.ts) ──
+
+function flattenBlocks(parsed: unknown): JsonLdObject[] {
+  if (parsed === null || typeof parsed !== "object") return [];
+  if (Array.isArray(parsed))
+    return parsed.flatMap((item) => flattenBlocks(item));
+  const obj = parsed as Record<string, unknown>;
+  if (Array.isArray(obj["@graph"])) {
+    const ctx = obj["@context"] as JsonLdObject["@context"] | undefined;
+    return (obj["@graph"] as unknown[]).flatMap((child) =>
+      flattenBlocks(child).map((b) =>
+        ctx === undefined || b["@context"] !== undefined
+          ? b
+          : { ...b, "@context": ctx },
+      ),
+    );
+  }
+  return [obj as JsonLdObject];
+}
+
+function formatErrors(errors: ValidationError[]): string {
+  return errors
+    .map(
+      (e) => `  [${e.rule}] ${e.path}: expected ${e.expected}, got ${e.actual}`,
+    )
+    .join("\n");
+}
+
+/** Validate flattened blocks for a page type; returns a readable failure or null. */
+function validateFor(
+  blocks: JsonLdObject[],
+  type: string,
+  label: string,
+): string | null {
+  if (!knownSchemaOrgTypes.has(type)) {
+    return `${label}: type "${type}" has no validator rule — it is not a registered page type (see packages/schema-validator/src/rules.ts)`;
+  }
+  const result = validatePageGraph(blocks, type as SchemaOrgType);
+  if (result.valid) return null;
+  return `${label} (${type}):\n${formatErrors(result.errors)}`;
+}
+
+/** Every `application/ld+json` block in rendered HTML, flattened. */
+function extractJsonLdBlocks(container: HTMLElement): JsonLdObject[] {
+  const scripts = container.querySelectorAll<HTMLScriptElement>(
+    'script[type="application/ld+json"]',
+  );
+  const blocks: JsonLdObject[] = [];
+  for (const script of Array.from(scripts)) {
+    blocks.push(...flattenBlocks(JSON.parse(script.textContent ?? "")));
+  }
+  return blocks;
+}
+
+// ── 1. Content-driven: every content page builds valid JSON-LD ──────────────
+
+describe("structured data — every content page builds valid JSON-LD", () => {
+  const typeDirs = contentTypeDirs();
+
+  it("finds content to check", () => {
+    // A site with no content directory at all is misconfigured, not clean.
+    expect(existsSync(CONTENT_ROOT)).toBe(true);
+    expect(typeDirs.length).toBeGreaterThan(0);
+  });
+
+  it.each(typeDirs)(
+    "content/$locale/$typeDir — every page validates as its type",
+    async ({ locale, typeDir }) => {
+      if (!(SCHEMA_ORG_TYPES as readonly string[]).includes(typeDir)) {
+        // Identity + sub-entity types (Organization, Person, BreadcrumbList,
+        // ContactPoint) hold sub-objects other pages' builders embed — never
+        // rendered as pages, and skipped by tools/content-compile the same
+        // way. Anything else is a directory nothing will ever render.
+        if (!knownSchemaOrgTypes.has(typeDir)) {
+          throw new Error(
+            `content/${locale}/${typeDir}: "${typeDir}" is not a registered page type — no route or builder will ever render it (see packages/content-adapters/src/types.ts SCHEMA_ORG_TYPES)`,
+          );
+        }
+        console.info(
+          `structured-data: content/${locale}/${typeDir} holds sub-objects, not pages — not checked`,
+        );
+        return;
+      }
+      const type = typeDir as PageType;
+
+      const pages: ContentPage[] = await adapter.listDetail(type, locale);
+      const dirPath = join(CONTENT_ROOT, locale, typeDir);
+      const mdxCount = readdirSync(dirPath).filter(
+        (n) => n.endsWith(".mdx") && !n.startsWith("_"),
+      ).length;
+      // The adapter drops a page whose frontmatter fails the schema; that
+      // page would render nothing, so count it here rather than lose it.
+      expect(pages.length).toBe(mdxCount);
+
+      const failures: string[] = [];
+      for (const page of pages) {
+        const sections = await getPageSections(page);
+        const jsonLd = await pageToJsonLd(page, locale, sections);
+        const failure = validateFor(
+          flattenBlocks(jsonLd),
+          page.type,
+          `${locale}/${page.type}/${page.slug}`,
+        );
+        if (failure !== null) failures.push(failure);
+      }
+      expect(failures).toEqual([]);
+    },
+  );
+});
+
+// ── 2. Route-emission: every route renders a valid JSON-LD script ───────────
+
+/**
+ * Routes (relative to `app/[locale]/`) that do not emit page-level JSON-LD
+ * through `renderPage`, each with the reason. An entry matches its own
+ * directory only; `subtree: true` extends it to every route below it. A route
+ * that is neither a `renderPage` route nor listed here fails — that is the
+ * "fourteen routes emitting nothing" failure class this check exists for.
+ *
+ * Listing a route here is a statement that its JSON-LD is someone else's job
+ * (or that it has none to emit) — not a way to make a red route green: an
+ * exempt route whose page.tsx does render through `renderPage` fails too,
+ * because the reason given for it is false.
+ */
+const NO_STRUCTURED_DATA_ROUTES: ReadonlyArray<{
+  route: string;
+  reason: string;
+  subtree?: true;
+}> = [
+  // Fumadocs routes: JSON-LD is emitted by @working-theory/fumadocs-schema
+  // from the fumadocs `.source` collection, which is not built in this
+  // harness. Not checked here.
+  {
+    route: "blog",
+    reason: "fumadocs route — emits via @working-theory/fumadocs-schema",
+    subtree: true,
+  },
+  {
+    route: "docs",
+    reason: "fumadocs route — emits via @working-theory/fumadocs-schema",
+    subtree: true,
+  },
+  // Hub routes that enumerate a detail type with no list page type of their
+  // own; they hand-compose a listing and emit no JSON-LD today. The hub only:
+  // each one's `[slug]` detail route renders through renderPage and is checked.
+  {
+    route: "how-to",
+    reason: "hand-composed listing; no HowTo list type exists",
+  },
+  {
+    route: "software",
+    reason: "hand-composed listing; no SoftwareProduct list type exists",
+  },
+  {
+    route: "tech-articles",
+    reason: "hand-composed listing; no TechArticle list type exists",
+  },
+  {
+    route: "whitepapers",
+    reason: "hand-composed listing; no Whitepaper list type exists",
+  },
+  // App-shaped routes with no content page behind them.
+  {
+    route: "(authed)",
+    reason: "authenticated app surface, not a content page",
+    subtree: true,
+  },
+  {
+    route: "dev",
+    reason: "development-only purchase harness",
+    subtree: true,
+  },
+  {
+    route: "flows",
+    reason: "interactive flow engine, API-backed",
+    subtree: true,
+  },
+  { route: "schedule", reason: "booking surface, API-backed", subtree: true },
+  { route: "sign-in", reason: "auth surface, not a content page" },
+];
+
+interface RouteEntry {
+  /** Route directory relative to `app/[locale]/` ("" for the home page). */
+  route: string;
+  file: string;
+}
+
+function walkRoutes(dir: string, out: RouteEntry[] = []): RouteEntry[] {
+  for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  )) {
+    if (entry.name === "__tests__" || entry.name === "node_modules") continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) walkRoutes(full, out);
+    else if (entry.name === "page.tsx") {
+      out.push({
+        route: relative(ROUTE_ROOT, dirname(full)).split(sep).join("/"),
+        file: full,
+      });
+    }
+  }
+  return out;
+}
+
+function exemption(route: string): string | undefined {
+  return NO_STRUCTURED_DATA_ROUTES.find(
+    (e) =>
+      route === e.route ||
+      (e.subtree === true && route.startsWith(e.route + "/")),
+  )?.reason;
+}
+
+// The page identity a route renders — the two `renderPage({ type, slug })`
+// shapes tools/lint-check-content-renders.ts recognises (a literal slug, or a
+// slug taken from params). A route that reads its identity another way
+// (e.g. a page-type manifest) is not recognised and must be declared.
+const RENDER_PAGE_EXACT_RE =
+  /renderPage\s*\(\s*\{[^}]*type\s*:\s*["']([A-Za-z]+)["'][^}]*slug\s*:\s*["']([^"']+)["']/s;
+const RENDER_PAGE_DYNAMIC_RE =
+  /renderPage\s*\(\s*\{[^}]*type\s*:\s*["']([A-Za-z]+)["'][^}]*\bslug\s*(?!:\s*["'])/s;
+
+function routeIdentity(
+  file: string,
+): { type: string; slug: string | null } | null {
+  const src = readFileSync(file, "utf8");
+  const exact = RENDER_PAGE_EXACT_RE.exec(src);
+  if (exact) return { type: exact[1] as string, slug: exact[2] as string };
+  const dynamic = RENDER_PAGE_DYNAMIC_RE.exec(src);
+  if (dynamic) return { type: dynamic[1] as string, slug: null };
+  return null;
+}
+
+type PageModule = {
+  default: (props: {
+    params: Promise<{ locale: string; slug?: string }>;
+  }) => Promise<ReactElement>;
+};
+
+async function renderRoute(
+  file: string,
+  slug: string | undefined,
+): Promise<HTMLElement> {
+  // Resolved at test time from the walk above — a static import would dangle
+  // in a scaffold that gated the surface off.
+  const mod = require(file) as PageModule;
+  const params: { locale: string; slug?: string } = { locale: DEFAULT_LOCALE };
+  if (slug !== undefined) params.slug = slug;
+  const element = await mod.default({ params: Promise.resolve(params) });
+  return render(element).container;
+}
+
+describe("structured data — every route emits a valid JSON-LD script", () => {
+  const routes = walkRoutes(ROUTE_ROOT);
+
+  it("finds routes to check", () => {
+    expect(routes.length).toBeGreaterThan(0);
+  });
+
+  it.each(routes)("$route", async ({ route, file }) => {
+    const label = `/${DEFAULT_LOCALE}${route === "" ? "" : "/" + route}`;
+    const exempt = exemption(route);
+    const identity = routeIdentity(file);
+    if (exempt !== undefined) {
+      // Declared, with a reason, in NO_STRUCTURED_DATA_ROUTES above. The
+      // reason is false for a route that does render through renderPage —
+      // that route is checkable, so declaring it would only hide it.
+      if (identity !== null) {
+        throw new Error(
+          `${label} is listed in NO_STRUCTURED_DATA_ROUTES but renders through renderPage (${identity.type}); remove it from the list so it is checked.`,
+        );
+      }
+      console.info(`structured-data: ${label} not checked — ${exempt}`);
+      return;
+    }
+
+    if (identity === null) {
+      throw new Error(
+        `${label}: ${basename(dirname(file))}/page.tsx has no renderPage({ type, slug }) call this check can read, so nothing is known to emit its JSON-LD. ` +
+          `Render it through renderPage, or add it to NO_STRUCTURED_DATA_ROUTES in ${basename(__filename)} with the reason.`,
+      );
+    }
+    expect(knownSchemaOrgTypes.has(identity.type)).toBe(true);
+    const type = identity.type as PageType;
+
+    // The pages this route serves from the site's own content, in the
+    // default locale. A fixed route names one page: if that page is missing
+    // the route 404s in production, which for `/` or `/about` is a broken
+    // site, not a route with nothing to check. A `[slug]` route with no
+    // pages of its type is simply empty — say so, do not fail.
+    let slugs: string[];
+    if (identity.slug !== null) {
+      const page = await adapter.getPageSource(
+        type,
+        identity.slug,
+        DEFAULT_LOCALE,
+      );
+      if (page === null) {
+        throw new Error(
+          `${label}: renders ${type}/${identity.slug}, but content/${DEFAULT_LOCALE}/${type}/${identity.slug}.mdx does not exist — the route serves 404 in production.`,
+        );
+      }
+      slugs = [identity.slug];
+    } else {
+      slugs = (await adapter.listDetail(type, DEFAULT_LOCALE)).map(
+        (p: ContentPage) => p.slug,
+      );
+      if (slugs.length === 0) {
+        console.info(
+          `structured-data: ${label} has no ${type} content in ${DEFAULT_LOCALE}; every slug serves 404 in production — nothing to check`,
+        );
+        return;
+      }
+    }
+
+    const failures: string[] = [];
+    for (const slug of slugs) {
+      const container = await renderRoute(
+        file,
+        identity.slug === null ? slug : undefined,
+      );
+      const blocks = extractJsonLdBlocks(container);
+      const pageLabel =
+        identity.slug === null
+          ? `${label.replace(/\[slug\]$/, "")}${slug}`
+          : label;
+      if (blocks.length === 0) {
+        failures.push(
+          `${pageLabel}: rendered no <script type="application/ld+json">`,
+        );
+        continue;
+      }
+      const failure = validateFor(blocks, type, pageLabel);
+      if (failure !== null) failures.push(failure);
+    }
+    expect(failures).toEqual([]);
+  });
+});
+
+// ── 3. The two defect shapes that shipped, pinned ───────────────────────────
+//
+// These prove the checks above reach the validator rule that rejects each
+// shape, so a change that quietly loosens the validator or the flatten step
+// shows up here rather than in a customer's launch review.
+
+describe("structured data — the check rejects the shapes that shipped", () => {
+  it("a rendered route with no JSON-LD script yields no blocks", () => {
+    const { container } = render(<main>{"no structured data here"}</main>);
+    expect(extractJsonLdBlocks(container)).toEqual([]);
+  });
+
+  it("a mainEntity carrying only @type and headline fails validation (#5019)", () => {
+    const thin: JsonLdObject = {
+      "@context": "https://schema.org",
+      "@type": "WebPage",
+      inLanguage: "en",
+      name: "x",
+      description: "x",
+      mainEntity: { "@type": "BlogPosting", headline: "x" },
+    };
+    const failure = validateFor([thin], "BlogPosting", "fixture");
+    expect(failure).not.toBeNull();
+    expect(failure).toContain("mainEntity.description");
+  });
+});

package/templates/apps/web/lib/account-config.ts

@@ -0,0 +1,13 @@
+// account-config.ts — Experiment registry for the /account Results section (#4984)
+//
+// Mirrors `nav-config.ts`: the OSS template declares NO experiments — nothing
+// in `apps/web` runs a diagnostic today, so this list ships empty and the
+// Results section renders its empty state. A consuming site lists the
+// `experimentKey`s of the diagnostics it runs (the `key` of each
+// `waitlistExperiment` it registers) so `/account` can read the signed-in
+// respondent's own newest signup for each via `waitlistSignups.me(key)`
+// (`GET /v1/waitlist-signups/me?experimentKey=…`, #4731 D5). Keys the caller
+// has no signup for come back 404 and are skipped, so listing every
+// experiment a site runs is safe.
+
+export const accountExperimentKeys: string[] = [];

package/templates/apps/web/lib/server-api.ts

@@ -0,0 +1,85 @@
+/**
+ * Server-side (RSC) helper for reading the operator-dashboard read API
+ * (#4665 D9).
+ *
+ * Forwards the incoming request's cookies to `@working-theory/api-client`'s
+ * `waitlistExperiments` namespace (B0, #4671) so `apps/api`'s cookie-session
+ * auth preHandler resolves the SAME Better Auth session the browser holds —
+ * both apps share the session store. GETs only, every page is an RSC; there
+ * is no client fetch and no `NEXT_PUBLIC_` credential (D9).
+ *
+ * `apps/web` may not import `apps/api` directly (architecture.yaml) — every
+ * read goes through `@working-theory/api-client`'s typed namespace, never a
+ * hand-rolled `fetch`. This module supplies exactly the two things that
+ * namespace doesn't own: the cookie-forwarding `init` (B0's additive
+ * `init?: { headers }` on `http.get`) and the envelope→`ApiError` unwrap
+ * (mirrors `apps-paid/workspace/lib/api-error.ts`'s `unwrapEnvelope`, adapted to
+ * the `@working-theory/api-client` `ApiResult<T>` shape B0 already returns
+ * rather than re-parsing the wire envelope by hand).
+ */
+
+import { cookies } from "next/headers";
+
+/**
+ * Structural mirror of `@working-theory/api-client`'s `ApiResult<T>`
+ * (`packages/api-client/src/http.ts`) — not imported, because that type is
+ * not re-exported from the package root and this module's scope (#4665 UI)
+ * does not touch `packages/api-client` (B0's). Every `waitlistExperiments.*`
+ * call already returns exactly this shape, so TypeScript's structural typing
+ * accepts it here without a cast.
+ */
+type ApiResult<T> =
+  | { ok: true; body: T }
+  | { ok: false; status: number; body: unknown };
+
+/**
+ * ApiError — thrown when the API responds with `{ ok: false }` (or the
+ * response body doesn't parse as the expected envelope). Carries the HTTP
+ * status + the envelope's `error.code` so callers can branch (404 →
+ * `notFound()`, 401/403 → an `EmptyState`) without string-matching on
+ * messages.
+ */
+export class ApiError extends Error {
+  readonly status: number;
+  readonly code: string;
+
+  constructor(status: number, code: string, message: string) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/** The subset of an error response body every route's envelope carries. */
+interface ErrorBody {
+  error?: { code?: string; message?: string };
+}
+
+/**
+ * Forward the incoming request's cookies as the `init` every
+ * `waitlistExperiments.*` call accepts. Call once per request — `cookies()`
+ * reads the current RSC request context.
+ */
+export async function forwardedCookieInit(): Promise<{
+  headers: { cookie: string };
+}> {
+  const cookieHeader = (await cookies()).toString();
+  return { headers: { cookie: cookieHeader } };
+}
+
+/**
+ * Unwrap an `ApiResult<T>` — the shape every `@working-theory/api-client`
+ * call returns — into `T`, throwing `ApiError` on `{ ok: false }`.
+ */
+export async function unwrapApiResult<T>(
+  result: Promise<ApiResult<T>>,
+): Promise<T> {
+  const res = await result;
+  if (res.ok) return res.body;
+
+  const body = res.body as ErrorBody | null;
+  const code = body?.error?.code ?? "invalid_response";
+  const message = body?.error?.message ?? "Malformed API response";
+  throw new ApiError(res.status, code, message);
+}