create-ailk 0.1.0

package/templates/apps/web/app/[locale]/whitepapers/page.tsx

@@ -0,0 +1,39 @@
+// Whitepapers list page. Enumerates Whitepaper slugs via the content adapter
+// and renders a directory listing. No dedicated list MDX type exists for Whitepaper.
+import { getMdxSlugs as defaultGetMdxSlugs } from "@working-theory/page-renderer";
+import { getTranslations } from "next-intl/server";
+import type { ReactElement } from "react";
+
+interface Props {
+  params: Promise<{ locale: string }>;
+  getMdxSlugs?: typeof defaultGetMdxSlugs;
+}
+
+export default async function Page({
+  params,
+  getMdxSlugs = defaultGetMdxSlugs,
+}: Props): Promise<ReactElement> {
+  const { locale } = await params;
+  const t = await getTranslations("whitepapers");
+  const slugs = await getMdxSlugs("Whitepaper", locale);
+
+  return (
+    <main>
+      <h1>{t("heading")}</h1>
+      <p data-testid="whitepapers-description">
+        {t("description")}
+      </p>
+      {slugs.length === 0 ? (
+        <p data-testid="section-empty-state">{t("emptyState")}</p>
+      ) : (
+        <ul data-testid="whitepapers-list">
+          {slugs.map((slug) => (
+            <li key={slug}>
+              <a href={`/${locale}/whitepapers/${slug}`}>{slug}</a>
+            </li>
+          ))}
+        </ul>
+      )}
+    </main>
+  );
+}

package/templates/apps/web/app/__tests__/error-boundaries.test.tsx

@@ -0,0 +1,152 @@
+import React from "react";
+import { render, screen, fireEvent } from "@testing-library/react";
+import "@testing-library/jest-dom";
+
+import RootError from "../error";
+import NotFound from "../not-found";
+import ContactError from "../[locale]/contact/error";
+import PurchaseError from "../[locale]/dev/purchase/error";
+
+function buildError(message = "Test error"): Error & { digest?: string } {
+  const err = new Error(message) as Error & { digest?: string };
+  err.digest = "test-digest-1";
+  return err;
+}
+
+describe("RootError", () => {
+  beforeEach(() => {
+    jest.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    (console.error as jest.Mock).mockRestore();
+  });
+
+  it("renders a fallback heading when an error is provided", () => {
+    const err = buildError("Something bad");
+    const reset = jest.fn();
+    render(<RootError error={err} reset={reset} />);
+    expect(screen.getByRole("heading", { level: 1 })).toBeInTheDocument();
+  });
+
+  it("renders a Try again button", () => {
+    const err = buildError();
+    const reset = jest.fn();
+    render(<RootError error={err} reset={reset} />);
+    expect(
+      screen.getByRole("button", { name: /try again/i }),
+    ).toBeInTheDocument();
+  });
+
+  it("calls reset when Try again is clicked", () => {
+    const err = buildError();
+    const reset = jest.fn();
+    render(<RootError error={err} reset={reset} />);
+    fireEvent.click(screen.getByRole("button", { name: /try again/i }));
+    expect(reset).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls console.error with the error on mount", () => {
+    const err = buildError("logged error");
+    const reset = jest.fn();
+    render(<RootError error={err} reset={reset} />);
+    expect(console.error).toHaveBeenCalledWith(err);
+  });
+});
+
+describe("NotFound", () => {
+  it("renders a 404 heading", () => {
+    render(<NotFound />);
+    expect(screen.getByRole("heading", { level: 1 })).toBeInTheDocument();
+  });
+
+  it("renders a link back to the home page", () => {
+    render(<NotFound />);
+    const link = screen.getByRole("link");
+    expect(link).toHaveAttribute("href", "/");
+  });
+});
+
+describe("ContactError", () => {
+  beforeEach(() => {
+    jest.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    (console.error as jest.Mock).mockRestore();
+  });
+
+  it("renders a heading specific to the lead-capture flow (message/contact)", () => {
+    const err = buildError("Contact error");
+    const reset = jest.fn();
+    render(<ContactError error={err} reset={reset} />);
+    const heading = screen.getByRole("heading", { level: 1 });
+    expect(heading.textContent?.toLowerCase()).toMatch(/message|contact/);
+  });
+
+  it("does NOT render generic 'something went wrong' as the heading", () => {
+    const err = buildError();
+    const reset = jest.fn();
+    render(<ContactError error={err} reset={reset} />);
+    const heading = screen.getByRole("heading", { level: 1 });
+    expect(heading.textContent?.toLowerCase()).not.toBe("something went wrong");
+  });
+
+  it("renders a Try again button that calls reset", () => {
+    const err = buildError();
+    const reset = jest.fn();
+    render(<ContactError error={err} reset={reset} />);
+    fireEvent.click(screen.getByRole("button", { name: /try again/i }));
+    expect(reset).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls console.error with the error on mount", () => {
+    const err = buildError("contact logged");
+    const reset = jest.fn();
+    render(<ContactError error={err} reset={reset} />);
+    expect(console.error).toHaveBeenCalledWith(err);
+  });
+});
+
+describe("PurchaseError", () => {
+  beforeEach(() => {
+    jest.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    (console.error as jest.Mock).mockRestore();
+  });
+
+  it("renders a heading specific to the checkout flow (checkout/purchase)", () => {
+    const err = buildError("Purchase error");
+    const reset = jest.fn();
+    render(<PurchaseError error={err} reset={reset} />);
+    const heading = screen.getByRole("heading", { level: 1 });
+    expect(heading.textContent?.toLowerCase()).toMatch(/checkout|purchase/);
+  });
+
+  it("does NOT claim payment was or was not processed in the heading", () => {
+    const err = buildError();
+    const reset = jest.fn();
+    render(<PurchaseError error={err} reset={reset} />);
+    const heading = screen.getByRole("heading", { level: 1 });
+    expect(heading.textContent?.toLowerCase()).not.toMatch(
+      /payment (was|not|failed|charged)/,
+    );
+  });
+
+  it("renders a Try again button that calls reset", () => {
+    const err = buildError();
+    const reset = jest.fn();
+    render(<PurchaseError error={err} reset={reset} />);
+    fireEvent.click(screen.getByRole("button", { name: /try again/i }));
+    expect(reset).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls console.error with the error on mount", () => {
+    const err = buildError("purchase logged");
+    const reset = jest.fn();
+    render(<PurchaseError error={err} reset={reset} />);
+    expect(console.error).toHaveBeenCalledWith(err);
+  });
+});

package/templates/apps/web/app/api/auth/[...all]/route.ts

@@ -0,0 +1,16 @@
+/**
+ * Better Auth catch-all route handler.
+ *
+ * Mounts Better Auth at /api/auth/* per its convention. This is the only
+ * api-shaped code permitted in apps/web — all other HTTP logic lives in
+ * apps/api (architecture.yaml).
+ *
+ * Replaces the deleted NextAuth catch-all at app/api/auth/[...nextauth]/.
+ * Better Auth's toNextJsHandler returns GET + POST Web Fetch handlers that
+ * Next.js App Router calls directly.
+ */
+import { toNextJsHandler } from "better-auth/next-js";
+
+import { auth } from "../../../../auth";
+
+export const { GET, POST } = toNextJsHandler(auth.handler);

package/templates/apps/web/app/error-fallback.tsx

@@ -0,0 +1,75 @@
+/* eslint-disable no-restricted-syntax -- i18n-allow: error boundary renders outside the [locale] intl provider context; translations unavailable at this segment (ADR 0019) */
+"use client";
+// Shared base for all per-segment error boundaries in apps/web.
+// Each boundary supplies flow-specific heading and body copy; this component
+// owns the token-sourced styling and the reset button.
+import { clientError } from "@working-theory/page-renderer/edge";
+import { tokens } from "@working-theory/theme";
+import type { ReactElement } from "react";
+import { useEffect } from "react";
+
+export interface ErrorFallbackProps {
+  error: Error & { digest?: string };
+  reset: () => void;
+  heading: string;
+  body: string;
+}
+
+const styles = {
+  main: {
+    background: tokens.colors.light.bg,
+    color: tokens.colors.light.fg,
+    minHeight: "100vh",
+    display: "flex",
+    flexDirection: "column" as const,
+    alignItems: "center",
+    justifyContent: "center",
+    padding: tokens.radius.lg,
+    gap: tokens.radius.md,
+  },
+  heading: {
+    fontSize: "1.5rem",
+    lineHeight: tokens.lineHeight.md,
+    color: tokens.colors.light.errorFg,
+    background: tokens.colors.light.errorBg,
+    padding: `${tokens.radius.sm} ${tokens.radius.md}`,
+    borderRadius: tokens.radius.sm,
+    margin: 0,
+  },
+  body: {
+    fontSize: "1rem",
+    lineHeight: tokens.lineHeight.md,
+    margin: 0,
+  },
+  button: {
+    fontSize: "1rem",
+    lineHeight: tokens.lineHeight.md,
+    background: tokens.colors.light.brand,
+    color: tokens.colors.light.bg,
+    border: "none",
+    borderRadius: tokens.radius.sm,
+    padding: `${tokens.radius.sm} ${tokens.radius.md}`,
+    cursor: "pointer",
+  },
+} as const;
+
+export function ErrorFallback({
+  error,
+  reset,
+  heading,
+  body,
+}: ErrorFallbackProps): ReactElement {
+  useEffect(() => {
+    clientError(error);
+  }, [error]);
+
+  return (
+    <main style={styles.main}>
+      <h1 style={styles.heading}>{heading}</h1>
+      <p style={styles.body}>{body}</p>
+      <button type="button" onClick={reset} style={styles.button}>
+        Try again
+      </button>
+    </main>
+  );
+}

package/templates/apps/web/app/error.tsx

@@ -0,0 +1,23 @@
+"use client";
+// Next.js App Router root error boundary. Must be a Client Component.
+// Renders when an unhandled error is thrown inside any route segment that
+// does not have its own error.tsx.
+import type { ReactElement } from "react";
+
+import { ErrorFallback } from "./error-fallback";
+
+interface ErrorProps {
+  error: Error & { digest?: string };
+  reset: () => void;
+}
+
+export default function Error({ error, reset }: ErrorProps): ReactElement {
+  return (
+    <ErrorFallback
+      error={error}
+      reset={reset}
+      heading="Something went wrong"
+      body="An unexpected error occurred. Please try again."
+    />
+  );
+}

package/templates/apps/web/app/layout.tsx

@@ -0,0 +1,18 @@
+// Root shell layout — i18n S2 (#949)
+//
+// Kept as a thin passthrough. The full HTML tree (<html lang>, <head>, <body>)
+// is now owned by app/[locale]/layout.tsx which has access to the locale param.
+// This root layout exists because Next.js requires a root layout at app/layout.tsx
+// when [locale] is a catch-segment; it renders children directly.
+//
+// Do NOT add <html> or <body> here — that would conflict with the locale layout.
+
+import type { ReactElement, ReactNode } from "react";
+
+export default function RootLayout({
+  children,
+}: {
+  children: ReactNode;
+}): ReactElement {
+  return <>{children}</>;
+}

package/templates/apps/web/app/llms.txt/route.ts

@@ -0,0 +1,101 @@
+/**
+ * GET /llms.txt
+ *
+ * Returns a plain-text index of AILK's content surface for LLM consumption,
+ * following the llms.txt convention (https://llmstxt.org).
+ *
+ * Aggregates two surfaces:
+ *   1. Section-catalog (MDX seeds in content/) via @working-theory/content-adapters
+ *   2. Fumadocs blog corpus via blogSource.getPages()
+ *
+ * Format per entry:
+ *   - Title: <title>
+ *     URL: <url>
+ *     Description: <description>
+ *
+ * DI note: `createLlmsHandler` accepts optional `getContentAdapter` and
+ * `getBlogPages` deps for testing — tests inject stubs to avoid mocking
+ * internal modules. The exported `GET` uses the real implementations.
+ */
+
+import { SCHEMA_ORG_TYPES } from "@working-theory/content-adapters";
+import type { ContentAdapter, SchemaOrgType } from "@working-theory/content-adapters";
+import { getContentAdapter as defaultGetContentAdapter } from "@working-theory/page-renderer";
+
+import { blogSource as defaultBlogSource } from "../../lib/source";
+import { resolveBaseUrl, slugToPath } from "../../src/lib/routes";
+
+export interface LlmsHandlerDeps {
+  /**
+   * Content adapter factory. Defaults to the real implementation.
+   * Override in tests to inject a stub adapter without mocking the internal module.
+   */
+  getContentAdapter?: () => ContentAdapter;
+  /**
+   * Blog pages getter. Defaults to the real blogSource.getPages().
+   * Override in tests to inject stub pages without mocking lib/source.
+   */
+  getBlogPages?: () => Array<{ url: string; data: { title: string; description?: string } }>;
+}
+
+/**
+ * Build an llms.txt GET handler parameterised by deps.
+ * Tests inject stubs to avoid mocking internal modules.
+ */
+export function createLlmsHandler(deps: LlmsHandlerDeps = {}) {
+  const resolveAdapter = deps.getContentAdapter ?? defaultGetContentAdapter;
+  const resolveBlogPages = deps.getBlogPages ?? (() => defaultBlogSource.getPages() as Array<{ url: string; data: { title: string; description?: string } }>);
+
+  return async function llmsGET(): Promise<Response> {
+    const adapter = resolveAdapter();
+    const baseUrl = resolveBaseUrl();
+    const lines: string[] = ["# AI Launch Kit — content index", ""];
+
+    // llms.txt is default-locale-only per Phase 3 roadmap §3 (AEO MVP is
+    // default-locale; per-locale AEO grading is deferred). Pass the default
+    // locale explicitly so the adapter returns the default-locale list (not
+    // legacy fallback) once content is fully migrated to locale-prefixed dirs.
+    const defaultLocale = process.env.NEXT_PUBLIC_DEFAULT_LOCALE ?? "en";
+
+    const types = SCHEMA_ORG_TYPES as readonly SchemaOrgType[];
+    const pageLists = await Promise.all(
+      types.map((type) => adapter.listPages(type, defaultLocale)),
+    );
+
+    for (const pages of pageLists) {
+      for (const page of pages) {
+        const path = slugToPath(page.type, page.slug);
+        const url = `${baseUrl}${path}`;
+        lines.push(`- Title: ${page.title}`);
+        lines.push(`  URL: ${url}`);
+        if (page.description) {
+          lines.push(`  Description: ${page.description}`);
+        }
+        lines.push("");
+      }
+    }
+
+    // Fumadocs blog corpus — blog index entry first, then per-post entries.
+    // blogSource.getPages() returns pages ordered by Fumadocs; the index page
+    // (/blog) sorts first naturally because its slug array is empty.
+    lines.push("");
+    for (const page of resolveBlogPages()) {
+      lines.push(`- Title: ${page.data.title}`);
+      lines.push(`  URL: ${baseUrl}${page.url}`);
+      if (page.data.description) {
+        lines.push(`  Description: ${page.data.description}`);
+      }
+      lines.push("");
+    }
+
+    return new Response(lines.join("\n"), {
+      status: 200,
+      headers: {
+        "content-type": "text/plain; charset=utf-8",
+        "cache-control": "public, max-age=3600",
+      },
+    });
+  };
+}
+
+export const GET = createLlmsHandler();

package/templates/apps/web/app/not-found.tsx

@@ -0,0 +1,48 @@
+/* eslint-disable no-restricted-syntax -- i18n-allow: not-found boundary renders outside the [locale] intl provider; translations unavailable at this segment (ADR 0019) */
+// Next.js App Router not-found boundary. Renders for any route that calls
+// notFound() or when no route matches. Server Component by default.
+import { tokens } from "@working-theory/theme";
+import type { ReactElement } from "react";
+
+const styles = {
+  main: {
+    background: tokens.colors.light.bg,
+    color: tokens.colors.light.fg,
+    minHeight: "100vh",
+    display: "flex",
+    flexDirection: "column" as const,
+    alignItems: "center",
+    justifyContent: "center",
+    padding: tokens.radius.lg,
+    gap: tokens.radius.md,
+  },
+  heading: {
+    fontSize: "1.5rem",
+    lineHeight: tokens.lineHeight.md,
+    margin: 0,
+  },
+  body: {
+    fontSize: "1rem",
+    lineHeight: tokens.lineHeight.md,
+    margin: 0,
+  },
+  link: {
+    color: tokens.colors.light.brand,
+    fontSize: "1rem",
+    lineHeight: tokens.lineHeight.md,
+  },
+} as const;
+
+export default function NotFound(): ReactElement {
+  return (
+    <main style={styles.main}>
+      <h1 style={styles.heading}>We couldn&apos;t find that page</h1>
+      <p style={styles.body}>
+        The page you are looking for does not exist or may have moved.
+      </p>
+      <a href="/" style={styles.link}>
+        Return home
+      </a>
+    </main>
+  );
+}

package/templates/apps/web/app/og/__tests__/route.test.ts

@@ -0,0 +1,164 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * Tests for the OG image route handler.
+ *
+ * Contract (AC from spec):
+ *   - Returns 200 + image/png MIME for valid params
+ *   - Sanitization strips control characters (\x00-\x1F\x7F) from title
+ *   - Sanitization caps title at 200 chars and schemaType at 50 chars
+ *   - Post-sanitization empty title triggers fallback (302 redirect to static PNG)
+ *   - On ImageResponse throw, falls back via 302 redirect to /og-default.png
+ *
+ * Fallback is a 302 redirect to /og-default.png (edge-compatible; no fs access).
+ * Per spec § 3: "redirecting is simpler but exposes the fallback URL; both acceptable."
+ *
+ * Note: next/og's ImageResponse runs in an edge runtime. In tests we mock it
+ * to return a minimal Response so we can verify the handler contract without
+ * spinning up an actual V8 isolate.
+ */
+
+// --- Mocks set up BEFORE imports ---
+
+// Mock next/og ImageResponse
+const mockImageResponseBody = Buffer.from("PNG_MOCK");
+let shouldImageResponseThrow = false;
+
+jest.mock("next/og", () => ({
+  ImageResponse: jest.fn().mockImplementation(() => {
+    if (shouldImageResponseThrow) {
+      throw new Error("ImageResponse failed");
+    }
+    return new Response(mockImageResponseBody, {
+      status: 200,
+      headers: { "Content-Type": "image/png" },
+    });
+  }),
+}));
+
+import { GET } from "../route";
+
+function makeRequest(params: Record<string, string>): Request {
+  const searchParams = new URLSearchParams(params).toString();
+  const url = `http://localhost/og${searchParams ? "?" + searchParams : ""}`;
+  return new Request(url, { method: "GET" });
+}
+
+describe("OG route GET handler", () => {
+  beforeEach(() => {
+    shouldImageResponseThrow = false;
+    jest.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    (console.error as jest.Mock).mockRestore();
+  });
+
+  describe("happy path — valid params", () => {
+    it("returns 200 for valid title and schemaType", async () => {
+      const req = makeRequest({
+        title: "AI Launch Kit",
+        schemaType: "WebSite",
+      });
+      const res = await GET(req);
+      expect(res.status).toBe(200);
+    });
+
+    it("returns image/png content-type for valid params", async () => {
+      const req = makeRequest({
+        title: "AI Launch Kit",
+        schemaType: "WebSite",
+      });
+      const res = await GET(req);
+      expect(res.headers.get("content-type")).toContain("image/png");
+    });
+
+    it("works with only title (no schemaType)", async () => {
+      const req = makeRequest({ title: "Hello World" });
+      const res = await GET(req);
+      expect(res.status).toBe(200);
+    });
+
+    it("works with no params (uses defaults)", async () => {
+      const req = makeRequest({});
+      const res = await GET(req);
+      expect(res.status).toBe(200);
+    });
+  });
+
+  describe("sanitization — control characters stripped", () => {
+    it("strips null bytes from title", async () => {
+      // Control chars are stripped — should not throw; handler proceeds with sanitized value
+      const req = makeRequest({
+        title: "Hello\x00World",
+        schemaType: "WebSite",
+      });
+      const res = await GET(req);
+      expect(res.status).toBe(200);
+    });
+
+    it("strips other control characters from title", async () => {
+      const req = makeRequest({
+        title: "Bad\x01\x1FTitle",
+        schemaType: "WebSite",
+      });
+      const res = await GET(req);
+      expect(res.status).toBe(200);
+    });
+
+    it("returns fallback when title is empty after sanitization (all control chars)", async () => {
+      // A title consisting only of control characters sanitizes to "" → 302 fallback redirect
+      const req = makeRequest({
+        title: "\x00\x01\x1F\x7F",
+        schemaType: "WebSite",
+      });
+      const res = await GET(req);
+      // Must not be 500 — handler always returns a non-error response
+      expect(res.status).not.toBe(500);
+      // Fallback is a 302 redirect to the static PNG
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toContain("og-default.png");
+    });
+
+    it("caps title at 200 characters", async () => {
+      const longTitle = "A".repeat(300);
+      const req = makeRequest({ title: longTitle, schemaType: "WebSite" });
+      const res = await GET(req);
+      expect(res.status).toBe(200);
+    });
+
+    it("caps schemaType at 50 characters", async () => {
+      const longType = "B".repeat(100);
+      const req = makeRequest({ title: "Test", schemaType: longType });
+      const res = await GET(req);
+      expect(res.status).toBe(200);
+    });
+  });
+
+  describe("fallback — ImageResponse throws", () => {
+    beforeEach(() => {
+      shouldImageResponseThrow = true;
+    });
+
+    it("does not return 500 when ImageResponse throws", async () => {
+      const req = makeRequest({ title: "Test", schemaType: "WebSite" });
+      const res = await GET(req);
+      expect(res.status).not.toBe(500);
+    });
+
+    it("returns 302 redirect to static PNG when ImageResponse throws", async () => {
+      const req = makeRequest({ title: "Test", schemaType: "WebSite" });
+      const res = await GET(req);
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toContain("og-default.png");
+    });
+
+    it("calls console.error when ImageResponse throws", async () => {
+      const req = makeRequest({ title: "Test", schemaType: "WebSite" });
+      await GET(req);
+      expect(console.error).toHaveBeenCalled();
+    });
+  });
+});