create-ailk 0.1.0

package/templates/apps/web/__tests__/lighthouse-fixtures/improvement-image-shrink.tsx

@@ -0,0 +1,103 @@
+/**
+ * Lighthouse CI improvement fixture — image shrink
+ *
+ * Documentation-as-code, not loaded in production. Lives under
+ * `__tests__/` and is **not** imported by any file under `app/` or
+ * `components/` (asserted by spec §3.7 / AC bullet "None of the three
+ * fixtures is imported…").
+ *
+ * **Purpose**
+ *
+ * Sam's verification checklist (spec §5.1, Layer 1) calls for opening a
+ * PR that "improves performance" so the workflow's PR comment shows
+ * positive LCP/CLS deltas vs main. This fixture documents a known-good
+ * improvement pattern — swapping a hand-coded `<img>` for `next/image`
+ * with explicit dimensions and AVIF/WebP negotiation — so Sam (or any
+ * implementer running the verification) can apply it deterministically
+ * without designing a new improvement from scratch.
+ *
+ * **How to wire it in for verification**
+ *
+ * The improvement direction is "make `/` faster than baseline by enough
+ * that the PR comment shows a noticeable LCP improvement." The fixture
+ * is the *recipe*, not a runtime artifact.
+ *
+ * 1. On `main`, identify a route whose largest-contentful-paint element
+ *    is an image — e.g., the home page hero. (Use the most recent
+ *    `.lighthouseci/lhr-*.html` report's "Largest Contentful Paint
+ *    element" diagnostic to find it.)
+ * 2. If the LCP image is currently rendered via a plain `<img>`, swap
+ *    to `next/image` per the BEFORE/AFTER below.
+ * 3. If it's already `next/image`, the easier improvement is shrinking
+ *    the source image's dimensions to match the rendered size (avoid
+ *    serving a 2400×1600 image into a 800×533 slot).
+ * 4. Open a PR. The Lighthouse CI workflow's PR comment will show the
+ *    LCP delta vs main; expect a negative delta on `/` (faster).
+ *
+ * **BEFORE — plain img**
+ *
+ * ```tsx
+ * <img src="/hero.png" alt="..." />
+ * ```
+ *
+ * Issues: no width/height (CLS risk), no responsive sources, no
+ * priority hint, no format negotiation.
+ *
+ * **AFTER — next/image**
+ *
+ * ```tsx
+ * import Image from "next/image";
+ *
+ * <Image
+ *   src="/hero.png"
+ *   alt="..."
+ *   width={800}
+ *   height={533}
+ *   priority
+ * />
+ * ```
+ *
+ * Effects: dimensions reserve layout space (CLS → 0), `priority` skips
+ * lazy-load for above-the-fold content (LCP improves), Next's image
+ * pipeline negotiates AVIF/WebP and serves the right size.
+ *
+ * **Why this is documented as a fixture, not a real PR**
+ *
+ * The actual perf improvement is implementation-specific (which route's
+ * LCP element is currently a plain `<img>`?). The fixture captures the
+ * *recipe* so that when Sam runs the verification, the diff is
+ * predictable instead of one-off-discovered. The fixture ships as code
+ * (not just docs) so editor tooling can refactor it if `next/image`'s
+ * API shifts.
+ */
+
+import type { ImageProps } from "next/image";
+
+/**
+ * Reference props for the recommended `next/image` invocation. Not
+ * exported as a component; the verification PR copies this shape into
+ * the actual route file.
+ */
+export const recommendedImageProps: Partial<ImageProps> = {
+  width: 800,
+  height: 533,
+  priority: true,
+};
+
+/**
+ * Reference render demonstrating the AFTER shape. Not imported by any
+ * route — see file header.
+ */
+export function ImprovementImageShrinkFixture() {
+  // Inline `<img>` here is intentional — this fixture documents the
+  // anti-pattern (BEFORE) alongside the recommended pattern. Replacing
+  // this `<img>` is the verification step, so we keep it visible.
+  // eslint-disable-next-line @next/next/no-img-element, jsx-a11y/alt-text
+  return (
+    <img
+      data-fixture="lhci-improvement-image-shrink"
+      src="/hero.png"
+      alt="placeholder"
+    />
+  );
+}

package/templates/apps/web/__tests__/lighthouse-fixtures/override-fixture.md

@@ -0,0 +1,114 @@
+# Lighthouse CI override fixture
+
+Documentation-only, not loaded in production. Lives under `__tests__/`
+alongside the other Lighthouse fixtures. This file is markdown, not a
+component — Sam's verification checklist for the override path is a
+PR-process exercise, not a runtime artifact.
+
+## Purpose
+
+Sam's verification checklist (`docs/internal/specs/ailk-lighthouse-ci-spec.md`
+§5.1, Layer 1) calls for confirming the override mechanism: when a
+performance regression is intentional, applying `perf-override` plus a
+qualifying comment lets the PR ship despite the failing assertion. This
+fixture is the recipe.
+
+## When to override
+
+Override is for **intentional** regressions whose business value
+outweighs the perf cost — e.g., adding a one-time analytics script the
+team has decided to ship, or shipping a heavy demo asset for a launch.
+Routine code that regresses LCP without intent should be fixed, not
+overridden.
+
+If you find yourself overriding more than once per quarter, the
+thresholds are wrong. Re-run the §2.5 baseline-measurement procedure on
+post-merge `main` and commit recalibrated thresholds in a follow-up PR
+per `docs/perf.md` § How to update thresholds.
+
+## How to override (verification recipe)
+
+Run this against the `regression-bloat.tsx` fixture or any PR with a
+genuine intentional regression.
+
+1. Confirm the Lighthouse CI workflow has run and failed on the PR. The
+   PR comment posted by the workflow names the route + metric that
+   exceeded the threshold.
+2. Apply the `perf-override` label to the PR:
+
+   ```bash
+   gh pr edit <PR> --add-label perf-override
+   ```
+
+3. Post a comment whose body **starts with** the literal string
+   `perf-override:` (case-insensitive — the workflow `ascii_downcase`s
+   before checking) followed by the justification:
+
+   ```
+   perf-override: shipping the launch-day hero asset; will revisit
+   thresholds in #<follow-up-issue> after main has the new baseline.
+   ```
+
+   Bot comments are excluded — the comment must be from a non-bot
+   author. The comment must be from a non-bot login (the workflow
+   filters logins ending in `[bot]`).
+
+4. Re-trigger the workflow. The simplest trigger is to push an empty
+   commit:
+
+   ```bash
+   git commit --allow-empty -m "chore: re-run lhci with override"
+   git push
+   ```
+
+   The `pull_request: synchronize` event fires the workflow. The
+   `labeled` event also fires it, so just adding the label without
+   pushing also re-runs the gate (concurrency group will cancel the
+   prior in-flight run).
+
+5. Confirm the workflow run completes green:
+   - The original `Run Lighthouse CI` step still fails (this is
+     expected — the override does not change the assertion outcome).
+   - The `Evaluate override gate` step posts a comment naming the
+     justification: `Lighthouse CI override applied. Justification: …`.
+   - The final `Surface result` step exits 0 because the override
+     applied.
+
+6. Verify the audit trail by reading the PR's comment thread. The
+   override comment, the workflow's acknowledgement comment, and the
+   original Lighthouse failure summary should all be visible.
+
+## How the workflow evaluates the override
+
+From `.github/workflows/lighthouse-ci.yml` `Evaluate override gate`
+step:
+
+- Reads PR JSON: `gh pr view <PR> --json labels,comments`.
+- Checks `labels` for `perf-override`. If absent → no override; surface
+  the original failure.
+- Iterates `comments`, filters out bot logins (`endswith("[bot]")`),
+  and finds the first comment whose body, after `ascii_downcase`,
+  starts with `perf-override:`. If none → posts the
+  "label-without-comment" instructional comment, surfaces the original
+  failure.
+- Both present → posts the override-applied comment with the
+  justification quoted, sets `applied=true`. The final `Surface result`
+  step then exits 0.
+
+The override is per-PR-per-run; each push or label event re-evaluates
+the current state. Removing the label or deleting the comment between
+runs returns the gate to enforcing.
+
+## Anti-patterns
+
+- **Substring match.** A comment that mentions `perf-override` mid-body
+  does not count — the body must _start with_ `perf-override:`. This is
+  intentional (spec §3.6) so casual references in discussion don't
+  silently override the gate.
+- **Bot-authored override.** Comments from automated reviewers (Bugbot,
+  claude-review, the workflow itself) are filtered out. A human-author
+  comment is required.
+- **Override-only PRs.** If every PR that touches the LCP element ends
+  up overridden, recalibrate thresholds instead of overriding. The
+  override path is for one-off intent, not a workaround for stale
+  budgets.

package/templates/apps/web/__tests__/lighthouse-fixtures/regression-bloat.tsx

@@ -0,0 +1,94 @@
+/**
+ * Lighthouse CI regression fixture — bloat
+ *
+ * Documentation-as-code, not loaded in production. Lives under
+ * `__tests__/` and is **not** imported by any file under `app/` or
+ * `components/` (asserted by spec §3.7 / AC bullet "None of the three
+ * fixtures is imported…").
+ *
+ * **Purpose**
+ *
+ * Sam's verification checklist (spec §5.1, Layer 1) calls for opening a
+ * PR that adds a "deliberately wasteful 200KB+ unused dependency" to
+ * `apps/web` to confirm Lighthouse CI fails on `/` with an LCP
+ * regression. Tree-shaking is the failure mode that makes the
+ * verification a no-op — if Next.js drops the import because the value
+ * is unused, the regression never happens. This fixture is structured
+ * so Next.js cannot eliminate it.
+ *
+ * **How to wire it in for verification**
+ *
+ * 1. Move this file to a temporary location inside `app/` (e.g.,
+ *    `app/_lhci-regression-fixture.tsx`) — `__tests__/` is not part of
+ *    the Next.js compile graph.
+ * 2. Add a side-effectful import to `apps/web/app/page.tsx`:
+ *
+ *    ```ts
+ *    import "./_lhci-regression-fixture";
+ *    ```
+ *
+ *    A side-effect import (no symbol, no destructure) is the strongest
+ *    signal to bundlers that the module must be evaluated. Combined
+ *    with the eager `moment` + locales evaluation below, the bundler
+ *    will not drop the dependency.
+ * 3. Open a PR to `main` containing the move + the import line.
+ * 4. Wait for the `Lighthouse CI` workflow on the PR to fail with an
+ *    `largest-contentful-paint` assertion error on `http://localhost:3000/$`.
+ *    The PR comment will name the regressed metric and route.
+ * 5. Revert the changes after verification.
+ *
+ * **Why `moment` + locales**
+ *
+ * `moment` ships every locale by default (≈230 KB minified). Webpack
+ * tree-shaking cannot drop locales that are reachable via dynamic
+ * `require()` paths inside moment's source. The eager `moment().locale(...)`
+ * calls below force the runtime to walk the locale registry. The result
+ * is a deterministic ~250 KB JS payload added to the route's first-load
+ * bundle, which translates to a measurable LCP regression on `/` under
+ * the desktop preset.
+ *
+ * Note: this fixture is intentionally *not* shipped — it's a recipe for
+ * Sam, not a runtime artifact.
+ */
+
+// eslint-disable-next-line import/no-extraneous-dependencies, @typescript-eslint/no-require-imports
+const moment: any = (globalThis as any).require?.("moment") ?? null;
+
+const NOW = moment ? moment() : null;
+
+if (NOW) {
+  // Touch every locale to defeat tree-shaking. Each .locale() call walks
+  // moment's locale registry and pulls in the locale module.
+  for (const code of [
+    "en",
+    "fr",
+    "de",
+    "es",
+    "it",
+    "pt",
+    "nl",
+    "ru",
+    "ja",
+    "zh-cn",
+    "ko",
+    "ar",
+    "he",
+    "tr",
+    "pl",
+    "sv",
+    "da",
+    "fi",
+    "no",
+    "cs",
+  ]) {
+    NOW.locale(code);
+  }
+}
+
+export function RegressionBloatFixture() {
+  return (
+    <div data-fixture="lhci-regression-bloat">
+      {NOW ? NOW.format("YYYY-MM-DD") : "no-moment"}
+    </div>
+  );
+}

package/templates/apps/web/__tests__/page.test.tsx

@@ -0,0 +1,230 @@
+// Home page tests. The page is an async server component; jest can render
+// it by awaiting the returned ReactElement promise. getMdxSource and
+// getPageSections are injected via optional props instead of mocking internal
+// modules — the test is independent of the on-disk /content/ tree without
+// coupling to module internals.
+// next-mdx-remote/rsc is mocked (external boundary — RSC compiler not available under jsdom).
+
+import { render, screen } from "@testing-library/react";
+
+jest.mock("next-mdx-remote/rsc", () => ({
+  __esModule: true,
+  MDXRemote: ({ source }: { source: string }): React.ReactElement => (
+    <div data-testid="mdx-rendered">{source}</div>
+  ),
+}));
+
+// Renders a real <h1>/<p> for a leading hero section — mirroring the real
+// Hero section component (packages/ui) closely enough to exercise the
+// renderPage leading-hero carve-out (#3301: renderPage omits its own
+// top-level <h1>/<p> when sections[0] is a hero, trusting the hero section
+// to supply the page's sole heading + lead paragraph).
+jest.mock("@working-theory/ui", () => ({
+  __esModule: true,
+  SectionRenderer: ({
+    sections,
+  }: {
+    sections: Array<{
+      type: string;
+      data?: { headline?: string; subheadline?: string };
+    }>;
+  }): React.ReactElement => (
+    <div data-testid="section-renderer" data-section-count={sections.length}>
+      {sections.map((section, i) =>
+        section.type === "hero" ? (
+          <div key={i} data-testid="section-item">
+            <h1>{section.data?.headline}</h1>
+            {section.data?.subheadline ? (
+              <p>{section.data.subheadline}</p>
+            ) : null}
+          </div>
+        ) : (
+          <div key={i} data-testid="section-item" />
+        ),
+      )}
+    </div>
+  ),
+}));
+
+import * as React from "react";
+
+import Page from "../app/[locale]/page";
+import type { getMdxSource, getPageSections } from "@working-theory/page-renderer";
+
+type GetMdxSource = typeof getMdxSource;
+type GetPageSections = typeof getPageSections;
+
+async function renderAsync(element: Promise<React.ReactElement>): Promise<void> {
+  const resolved = await element;
+  render(resolved);
+}
+
+// Mirrors the real content-authoring convention (#3301): the hero's
+// headline/subheadline mirror the page's frontmatter title/description.
+const HERO_SECTION = {
+  id: "hero-1",
+  type: "hero" as const,
+  data: {
+    headline: "Welcome to AILK",
+    subheadline: "AX-first OSS template.",
+    primaryCta: { label: "Get started", href: "/docs" },
+  },
+};
+
+const FEATURE_SECTION = {
+  id: "feature-1",
+  type: "feature" as const,
+  data: {
+    headline: "Built for agents",
+    features: [
+      { title: "API-first", description: "Canonical write surface." },
+    ],
+  },
+};
+
+const ITEMS_SECTION = {
+  id: "items-1",
+  type: "items" as const,
+  data: {
+    headline: "What's inside",
+    items: [
+      { title: "apps/web", description: "Next.js App Router" },
+      { title: "apps/api", description: "Fastify HTTP API" },
+      { title: "apps/mcp", description: "MCP server" },
+    ],
+  },
+};
+
+const CTA_SECTION = {
+  id: "cta-1",
+  type: "cta" as const,
+  data: {
+    headline: "Ready to ship?",
+    primaryCta: { label: "Clone now", href: "https://github.com/tailwind-ai/ai-launch-kit" },
+  },
+};
+
+describe("apps/web — home page", () => {
+  describe("with HomePage MDX present and sections in frontmatter", () => {
+    const stubGetMdxSource = jest.fn<ReturnType<GetMdxSource>, Parameters<GetMdxSource>>().mockResolvedValue({
+      frontmatter: {
+        type: "HomePage",
+        slug: "home",
+        title: "Welcome to AILK",
+        description: "AX-first OSS template.",
+      },
+      body: "# Welcome\n\nBody copy.",
+    });
+    const stubGetPageSections = jest.fn<ReturnType<GetPageSections>, Parameters<GetPageSections>>().mockResolvedValue([
+      HERO_SECTION,
+      FEATURE_SECTION,
+      ITEMS_SECTION,
+      CTA_SECTION,
+    ]);
+
+    beforeEach(() => {
+      stubGetMdxSource.mockClear();
+      stubGetPageSections.mockClear();
+    });
+
+    it("renders the MDX-sourced title in the h1", async () => {
+      await renderAsync(Page({ params: Promise.resolve({ locale: "en" }), getMdxSource: stubGetMdxSource, getPageSections: stubGetPageSections }));
+      const heading = screen.getByRole("heading", { level: 1 });
+      expect(heading).toHaveTextContent("Welcome to AILK");
+    });
+
+    it("renders the description via the leading hero section, not a duplicate top-level paragraph (#3301)", async () => {
+      await renderAsync(Page({ params: Promise.resolve({ locale: "en" }), getMdxSource: stubGetMdxSource, getPageSections: stubGetPageSections }));
+      // renderPage's own <p data-testid="home-description"> is skipped when
+      // the first section is a hero — the hero renders the lead paragraph.
+      expect(screen.queryByTestId("home-description")).toBeNull();
+      expect(screen.getByText("AX-first OSS template.")).toBeInTheDocument();
+    });
+
+    it("renders exactly one h1 (no duplicate title from renderPage + hero, #3301)", async () => {
+      await renderAsync(Page({ params: Promise.resolve({ locale: "en" }), getMdxSource: stubGetMdxSource, getPageSections: stubGetPageSections }));
+      expect(screen.getAllByRole("heading", { level: 1 })).toHaveLength(1);
+    });
+
+    it("emits a parseable <script type='application/ld+json'>", async () => {
+      await renderAsync(Page({ params: Promise.resolve({ locale: "en" }), getMdxSource: stubGetMdxSource, getPageSections: stubGetPageSections }));
+      const script = screen.getByTestId("json-ld");
+      expect(script.getAttribute("type")).toBe("application/ld+json");
+      // The app's responsibility is emitting a parseable JSON-LD <script>.
+      // The emitted @graph SHAPE is pinned once in @working-theory/schema's HomePage
+      // builder test — re-asserting @type/mainEntity here duplicated that pin
+      // and turned every builder change into per-app churn (#2635).
+      expect(() => JSON.parse(script.innerHTML)).not.toThrow();
+    });
+
+    it("renders SectionRenderer with sections from frontmatter", async () => {
+      await renderAsync(Page({ params: Promise.resolve({ locale: "en" }), getMdxSource: stubGetMdxSource, getPageSections: stubGetPageSections }));
+      const renderer = screen.getByTestId("section-renderer");
+      expect(renderer).toBeInTheDocument();
+      expect(renderer.dataset.sectionCount).toBe("4");
+    });
+
+    it("renders at least 3 section items beyond the hero", async () => {
+      await renderAsync(Page({ params: Promise.resolve({ locale: "en" }), getMdxSource: stubGetMdxSource, getPageSections: stubGetPageSections }));
+      const items = screen.getAllByTestId("section-item");
+      expect(items.length).toBeGreaterThanOrEqual(4);
+    });
+
+    it("does not render the MDX body directly", async () => {
+      await renderAsync(Page({ params: Promise.resolve({ locale: "en" }), getMdxSource: stubGetMdxSource, getPageSections: stubGetPageSections }));
+      expect(screen.queryByTestId("mdx-body")).toBeNull();
+    });
+  });
+
+  describe("with HomePage MDX present but no sections in frontmatter", () => {
+    const stubGetMdxSource = jest.fn<ReturnType<GetMdxSource>, Parameters<GetMdxSource>>().mockResolvedValue({
+      frontmatter: {
+        type: "HomePage",
+        slug: "home",
+        title: "Welcome to AILK",
+        description: "AX-first OSS template.",
+      },
+      body: "# Welcome\n\nBody copy.",
+    });
+    const stubGetPageSections = jest.fn<ReturnType<GetPageSections>, Parameters<GetPageSections>>().mockResolvedValue([]);
+
+    beforeEach(() => {
+      stubGetMdxSource.mockClear();
+      stubGetPageSections.mockClear();
+    });
+
+    it("renders the page without crashing", async () => {
+      await renderAsync(Page({ params: Promise.resolve({ locale: "en" }), getMdxSource: stubGetMdxSource, getPageSections: stubGetPageSections }));
+      expect(screen.getByRole("heading", { level: 1 })).toHaveTextContent(
+        "Welcome to AILK",
+      );
+    });
+
+    it("renders a SectionRenderer with empty sections (returns 200)", async () => {
+      await renderAsync(Page({ params: Promise.resolve({ locale: "en" }), getMdxSource: stubGetMdxSource, getPageSections: stubGetPageSections }));
+      expect(screen.queryByTestId("section-item")).toBeNull();
+    });
+  });
+
+  describe("with no HomePage MDX (fresh clone)", () => {
+    const stubGetMdxSource = jest.fn<ReturnType<GetMdxSource>, Parameters<GetMdxSource>>().mockResolvedValue(null);
+    const stubGetPageSections = jest.fn<ReturnType<GetPageSections>, Parameters<GetPageSections>>().mockResolvedValue([]);
+
+    beforeEach(() => {
+      stubGetMdxSource.mockClear();
+      stubGetPageSections.mockClear();
+    });
+
+    it("falls back to the placeholder h1", async () => {
+      await renderAsync(Page({ params: Promise.resolve({ locale: "en" }), getMdxSource: stubGetMdxSource, getPageSections: stubGetPageSections }));
+      const heading = screen.getByRole("heading", { level: 1 });
+      expect(heading).toHaveTextContent("AI Launch Kit");
+    });
+
+    it("renders a non-empty fallback description", async () => {
+      await renderAsync(Page({ params: Promise.resolve({ locale: "en" }), getMdxSource: stubGetMdxSource, getPageSections: stubGetPageSections }));
+      const description = screen.getByTestId("home-description");
+      expect(description.textContent?.trim().length ?? 0).toBeGreaterThan(0);
+    });
+  });
+});