create-ailk 0.5.0 → 0.6.0

package/templates/apps/web/app/[locale]/purchase/__tests__/module-scope.test.ts

@@ -0,0 +1,68 @@
+/**
+ * T-8 (#6084) — neither `/purchase/success` nor `/purchase/cancel` may hold
+ * a TOP-LEVEL STATIC import of `@working-theory/ui-commerce`.
+ *
+ * Superseded from its original form (a module-scope
+ * `registerCommerceSections()` call + a static import — the shape the pages
+ * shipped with initially). That shape is a genuine build-breaking defect:
+ * both pages ship in the BASE TREE (`CORE_ROUTE_DIRS`, D12), but a keyless
+ * `create-ailk` scaffold carries NO `@working-theory/ui-commerce` dependency
+ * by design — `packages/create-ailk/scripts/build-templates.mjs`'s
+ * `transformPaidUiPackages()` strips it, and
+ * `__tests__/paid-module-honest-states.test.ts`'s "#5581 U6" suite pins a
+ * keyless scaffold declaring none of the four paid `ui-*` packages as a
+ * dependency. Webpack resolves a static top-level import at BUILD time
+ * regardless of whether the importing code path ever executes, so the
+ * original shape failed every keyless customer's build with
+ * `ERR_MODULE_NOT_FOUND` (a code-review finding on this issue's own PR).
+ *
+ * The fix — `../../../../src/lib/commerce-sections.ts`'s
+ * `ensureCommerceSectionsRegistered()` — registers the module LAZILY, via a
+ * `webpackIgnore`-annotated `import()` wrapped in try/catch, so the build
+ * never needs the package to resolve. This test now pins the ABSENCE of the
+ * static import (the regression this file exists to catch) and the
+ * PRESENCE of the lazy-registration call site instead.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const PURCHASE_DIR = join(__dirname, "..");
+
+function readPageSource(page: "success" | "cancel"): string {
+  return readFileSync(join(PURCHASE_DIR, page, "page.tsx"), "utf8");
+}
+
+describe("ui-commerce registration is LAZY, never a top-level static import (T-8, D5, #6084 code-review fix)", () => {
+  for (const page of ["success", "cancel"] as const) {
+    it(`purchase/${page}/page.tsx holds NO static top-level import of @working-theory/ui-commerce`, () => {
+      const source = readPageSource(page);
+      expect(source.includes('from "@working-theory/ui-commerce"')).toBe(
+        false,
+      );
+      // The retired specifier may still appear in a doc comment (warning
+      // readers away from it); what must be absent is an actual IMPORT of it.
+      expect(
+        source.includes('from "@working-theory/ui/slices/commerce"'),
+      ).toBe(false);
+    });
+
+    it(`purchase/${page}/page.tsx imports ensureCommerceSectionsRegistered from the shared lazy-registration lib`, () => {
+      const source = readPageSource(page);
+      expect(
+        source.includes(
+          'import { ensureCommerceSectionsRegistered } from "../../../../src/lib/commerce-sections";',
+        ),
+      ).toBe(true);
+    });
+
+    it(`purchase/${page}/page.tsx never calls registerCommerceSections() at module scope (only through the lazy wrapper)`, () => {
+      const source = readPageSource(page);
+      // A doc comment MAY still name it in prose (both pages do, warning
+      // readers off the direct call) — what must be absent is the
+      // unindented, top-level CALL EXPRESSION statement itself.
+      expect(
+        source.split("\n").some((line) => line === "registerCommerceSections();"),
+      ).toBe(false);
+    });
+  }
+});

package/templates/apps/web/app/[locale]/purchase/__tests__/success.test.tsx

@@ -0,0 +1,361 @@
+/**
+ * Tests for /[locale]/purchase/success (#6084).
+ *
+ * D6's five-row degrade table is the load-bearing surface here: only a 2xx
+ * read with `paymentStatus === "paid"` may construct a `payment-receipt`
+ * section — AC-8 pins the negative directly (no `outcome: "success"` DOM
+ * marker on any other reachable state). AC-1/AC-7 cover the happy path and
+ * the never-a-dead-end guarantee; T-16 covers the D12 request-time gate in
+ * all three states (claimed / unclaimed / a throwing read).
+ */
+import React from "react";
+import { render } from "@testing-library/react";
+
+jest.mock("next/navigation", () => ({
+  __esModule: true,
+  notFound: jest.fn(() => {
+    throw new Error("NEXT_NOT_FOUND");
+  }),
+}));
+
+const mockHeadersGet = jest.fn();
+jest.mock("next/headers", () => ({
+  __esModule: true,
+  headers: jest.fn().mockResolvedValue({ get: (key: string) => mockHeadersGet(key) }),
+}));
+
+const requestedKeys: string[] = [];
+jest.mock("next-intl/server", () => ({
+  __esModule: true,
+  getTranslations: jest
+    .fn()
+    .mockResolvedValue((key: string, values?: Record<string, unknown>) => {
+      requestedKeys.push(key);
+      if (values) return `copy:${key}:${JSON.stringify(values)}`;
+      return `copy:${key}`;
+    }),
+}));
+
+const capturedSections: unknown[] = [];
+jest.mock("@working-theory/ui/sections", () => ({
+  __esModule: true,
+  SectionRenderer: ({ sections }: { sections: unknown[] }) => {
+    capturedSections.splice(0, capturedSections.length, ...sections);
+    return React.createElement("div", {
+      "data-testid": "section-renderer",
+      "data-section-count": String(sections.length),
+    });
+  },
+}));
+
+const mockGetSession = jest.fn();
+jest.mock("@working-theory/api-client", () => ({
+  __esModule: true,
+  checkout: { getSession: (...args: unknown[]) => mockGetSession(...args) },
+}));
+
+// Mocks the REAL boundary `resolveCommerceClaim()` itself calls
+// (`checkLicense` from `@working-theory/license`), not the internal wrapper
+// module — matching the eslint "no internal-module mocks" rule (#507).
+const mockCheckLicense = jest.fn();
+jest.mock("@working-theory/license", () => ({
+  __esModule: true,
+  checkLicense: (...args: unknown[]) => mockCheckLicense(...args),
+}));
+
+// `../../../../src/lib/commerce-sections` wraps a lazy, webpack-ignored
+// `import()` of the paid `@working-theory/ui-commerce` package — mocked
+// directly here (an internal wrapper, but there is no OTHER boundary to
+// mock: the real thing it wraps is a dynamic import expression, not an
+// importable named export this file could bind instead) so a test can
+// simulate the package being genuinely absent (a keyless scaffold) without
+// needing to hide a real node_modules entry.
+const mockEnsureCommerceSectionsRegistered = jest.fn();
+// The wrapped thing is a bare, webpack-ignored `import()` expression, not a
+// named export of some other module — there is no external HTTP/DB/env
+// boundary to mock instead, mirroring team-page.test.tsx's identical
+// exception for auth.ts's lazy singleton.
+// eslint-disable-next-line no-restricted-syntax -- see comment above
+jest.mock("../../../../src/lib/commerce-sections", () => ({
+  __esModule: true,
+  ensureCommerceSectionsRegistered: () =>
+    mockEnsureCommerceSectionsRegistered(),
+}));
+
+import { checkout } from "@working-theory/api-client";
+import { notFound } from "next/navigation";
+
+import Page, { generateMetadata } from "../success/page";
+
+const mockNotFound = notFound as jest.MockedFunction<typeof notFound>;
+void checkout; // referenced only to satisfy the mock import above
+
+function sectionTypes(): string[] {
+  return capturedSections.map((s) => (s as { type: string }).type);
+}
+
+const PAID_SESSION = {
+  id: "cs_test_abc123",
+  status: "complete" as const,
+  paymentStatus: "paid" as const,
+  currency: "usd",
+  amountTotal: 4800,
+  lineItems: [
+    {
+      description: "Pro plan",
+      quantity: 2,
+      amountTotal: 4800,
+      currency: "usd",
+    },
+  ],
+};
+
+async function renderPage(sessionId?: string) {
+  const searchParams = sessionId
+    ? Promise.resolve({ session_id: sessionId })
+    : Promise.resolve({});
+  const element = await Page({
+    params: Promise.resolve({ locale: "en" }),
+    searchParams,
+  });
+  return render(element);
+}
+
+describe("/purchase/success", () => {
+  beforeEach(() => {
+    capturedSections.length = 0;
+    requestedKeys.length = 0;
+    mockGetSession.mockReset();
+    mockCheckLicense.mockReset();
+    mockCheckLicense.mockResolvedValue({ revoked: false, features: ["commerce"] });
+    mockNotFound.mockClear();
+    mockEnsureCommerceSectionsRegistered.mockReset();
+    mockEnsureCommerceSectionsRegistered.mockResolvedValue(true);
+    mockHeadersGet.mockReset();
+    mockHeadersGet.mockReturnValue(null);
+  });
+
+  // ── AC-1 — the paid render ────────────────────────────────────────────────
+
+  it("renders payment-receipt → items → cta on a 2xx paid read (AC-1)", async () => {
+    mockGetSession.mockResolvedValue({ ok: true, body: PAID_SESSION });
+
+    await renderPage("cs_test_abc123");
+
+    expect(sectionTypes()).toEqual(["payment-receipt", "items", "cta"]);
+  });
+
+  it("calls checkout.getSession with the exact session_id from the query, and undefined init when no forwarding header is present", async () => {
+    mockGetSession.mockResolvedValue({ ok: true, body: PAID_SESSION });
+    mockHeadersGet.mockReturnValue(null);
+
+    await renderPage("cs_test_abc123");
+
+    expect(mockGetSession).toHaveBeenCalledWith("cs_test_abc123", undefined);
+  });
+
+  it("forwards the visitor's x-forwarded-for as init.headers on the server-side read (security-review finding, #6084)", async () => {
+    mockGetSession.mockResolvedValue({ ok: true, body: PAID_SESSION });
+    mockHeadersGet.mockImplementation((key: string) =>
+      key === "x-forwarded-for" ? "203.0.113.7" : null,
+    );
+
+    await renderPage("cs_test_abc123");
+
+    expect(mockGetSession).toHaveBeenCalledWith("cs_test_abc123", {
+      headers: { "x-forwarded-for": "203.0.113.7" },
+    });
+  });
+
+  it("threads the session id + amount + currency into the payment-receipt section", async () => {
+    mockGetSession.mockResolvedValue({ ok: true, body: PAID_SESSION });
+
+    await renderPage("cs_test_abc123");
+
+    const receipt = capturedSections[0] as {
+      type: string;
+      data: Record<string, unknown>;
+    };
+    expect(receipt.type).toBe("payment-receipt");
+    expect(receipt.data.outcome).toBe("success");
+    expect(receipt.data.sessionId).toBe("cs_test_abc123");
+    expect(receipt.data.amount).toEqual({ amountMinor: 4800, currency: "usd" });
+  });
+
+  it("renders one items card per paid line item, with quantity and formatted money", async () => {
+    mockGetSession.mockResolvedValue({ ok: true, body: PAID_SESSION });
+
+    await renderPage("cs_test_abc123");
+
+    const items = capturedSections[1] as {
+      type: string;
+      data: { items: { title: string; description: string }[] };
+    };
+    expect(items.type).toBe("items");
+    expect(items.data.items).toHaveLength(1);
+    expect(items.data.items[0]!.title).toBe("Pro plan");
+    // The translated line renders through the t() mock, carrying the raw
+    // interpolation values — quantity is threaded, and formatMoney ran (the
+    // string contains a currency-formatted amount, not the raw minor units).
+    expect(items.data.items[0]!.description).toContain("success.lineItem");
+    expect(items.data.items[0]!.description).toContain('"quantity":2');
+  });
+
+  it("falls back to content-block instead of payment-receipt when @working-theory/ui-commerce is not installed", async () => {
+    mockGetSession.mockResolvedValue({ ok: true, body: PAID_SESSION });
+    mockEnsureCommerceSectionsRegistered.mockResolvedValue(false);
+
+    await renderPage("cs_test_abc123");
+
+    // Never the bare `payment-receipt` type — SectionRenderer would
+    // otherwise fall back to `ModuleAbsent`, which renders nothing in
+    // production. The line items and CTA are unaffected either way.
+    expect(sectionTypes()).toEqual(["content-block", "items", "cta"]);
+    const fallback = capturedSections[0] as {
+      type: string;
+      data: { headline: string; body: string };
+    };
+    expect(fallback.data.headline).toBe("copy:success.title");
+    expect(fallback.data.body).toContain("copy:success.message");
+  });
+
+  // ── D6 — the five-row degrade table ─────────────────────────────────────
+
+  it("renders content-block → cta with NO payment-receipt when there is no session_id (D6 row 3)", async () => {
+    await renderPage(undefined);
+
+    expect(sectionTypes()).toEqual(["content-block", "cta"]);
+    expect(mockGetSession).not.toHaveBeenCalled();
+  });
+
+  it("renders content-block → cta with NO payment-receipt on a non-2xx read (D6 row 5)", async () => {
+    mockGetSession.mockResolvedValue({
+      ok: false,
+      status: 404,
+      body: { error: "unknown-session" },
+    });
+
+    await renderPage("cs_test_unknown");
+
+    expect(sectionTypes()).toEqual(["content-block", "cta"]);
+  });
+
+  it("renders content-block → cta with NO payment-receipt when checkout.getSession REJECTS (a network failure, not a non-2xx response)", async () => {
+    // `checkout.getSession()` calls `fetch()` with no try/catch of its own
+    // (`packages/api-client/src/http.ts`) — a network-level failure rejects
+    // the promise rather than resolving `{ ok: false }`. Code-review finding
+    // on this issue's PR: without a catch here, this crashes the page
+    // instead of degrading like every other unreachable-session case.
+    mockGetSession.mockRejectedValue(new Error("fetch failed"));
+
+    await renderPage("cs_test_unreachable");
+
+    expect(sectionTypes()).toEqual(["content-block", "cta"]);
+  });
+
+  it("renders content-block → items → cta with NO payment-receipt when paymentStatus is unpaid (D6 row 2)", async () => {
+    mockGetSession.mockResolvedValue({
+      ok: true,
+      body: { ...PAID_SESSION, paymentStatus: "unpaid" },
+    });
+
+    await renderPage("cs_test_pending");
+
+    expect(sectionTypes()).toEqual(["content-block", "items", "cta"]);
+  });
+
+  it("renders content-block → items → cta when paymentStatus is no_payment_required (D6 row 2)", async () => {
+    mockGetSession.mockResolvedValue({
+      ok: true,
+      body: { ...PAID_SESSION, paymentStatus: "no_payment_required" },
+    });
+
+    await renderPage("cs_test_pending");
+
+    expect(sectionTypes()).toEqual(["content-block", "items", "cta"]);
+  });
+
+  // ── AC-8 — the paid render is not forgeable ─────────────────────────────
+
+  it("no session_id: the DOM carries no data-outcome=success and no PaymentComplete string (AC-8)", async () => {
+    await renderPage(undefined);
+
+    const serialized = JSON.stringify(capturedSections);
+    expect(serialized).not.toContain('"outcome":"success"');
+    expect(serialized).not.toContain("PaymentComplete");
+  });
+
+  it("unpaid session: the DOM carries no data-outcome=success and no PaymentComplete string (AC-8)", async () => {
+    mockGetSession.mockResolvedValue({
+      ok: true,
+      body: { ...PAID_SESSION, paymentStatus: "unpaid" },
+    });
+
+    await renderPage("cs_test_pending");
+
+    const serialized = JSON.stringify(capturedSections);
+    expect(serialized).not.toContain('"outcome":"success"');
+    expect(serialized).not.toContain("PaymentComplete");
+  });
+
+  // ── AC-7 — degrade, never crash ──────────────────────────────────────────
+
+  it("every degraded row still ends in a cta section (AC-7 — never a dead end)", async () => {
+    await renderPage(undefined);
+    expect(sectionTypes()[sectionTypes().length - 1]).toBe("cta");
+
+    mockGetSession.mockResolvedValue({ ok: false, status: 502, body: {} });
+    await renderPage("cs_test_outage");
+    expect(sectionTypes()[sectionTypes().length - 1]).toBe("cta");
+  });
+
+  // ── AC-2/AC-5 — noindex ───────────────────────────────────────────────────
+
+  it("is not indexable", async () => {
+    const metadata = await generateMetadata({
+      params: Promise.resolve({ locale: "en" }),
+    });
+    expect(metadata.robots).toEqual({ index: false, follow: true });
+  });
+
+  // ── T-16 / D12 — the request-time commerce-claim gate ───────────────────
+
+  it("answers notFound() when the commerce claim is NOT held, before any API call (D12)", async () => {
+    mockCheckLicense.mockResolvedValue({ revoked: false, features: [] });
+
+    await expect(renderPage("cs_test_abc123")).rejects.toThrow(
+      "NEXT_NOT_FOUND",
+    );
+    expect(mockNotFound).toHaveBeenCalledTimes(1);
+    expect(mockGetSession).not.toHaveBeenCalled();
+  });
+
+  it("renders normally when the commerce claim IS held", async () => {
+    mockCheckLicense.mockResolvedValue({ revoked: false, features: ["commerce"] });
+    mockGetSession.mockResolvedValue({ ok: true, body: PAID_SESSION });
+
+    await renderPage("cs_test_abc123");
+
+    expect(mockNotFound).not.toHaveBeenCalled();
+    expect(sectionTypes()).toEqual(["payment-receipt", "items", "cta"]);
+  });
+
+  it("fail-closed: answers notFound() when the licence read THROWS (D12's fail-closed direction)", async () => {
+    mockCheckLicense.mockRejectedValue(new Error("licence read blew up"));
+
+    await expect(renderPage("cs_test_abc123")).rejects.toThrow();
+    // resolveCommerceClaim() itself is fail-closed (returns false on a
+    // throw, never propagates) — this page never has to catch anything; it
+    // just reads the resolver's own answer.
+  });
+
+  // ── FR-3 — never writes ──────────────────────────────────────────────────
+
+  it("never calls prisma, stripe writes, .create(), .update() or .upsert() (FR-3, grep-style)", async () => {
+    mockGetSession.mockResolvedValue({ ok: true, body: PAID_SESSION });
+    await renderPage("cs_test_abc123");
+
+    // The page's only Stripe-adjacent call is the READ wrapper.
+    expect(mockGetSession).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -0,0 +1,115 @@
+// oss: false
+/**
+ * /[locale]/purchase/cancel — the checkout-canceled return page (#6084).
+ *
+ * NOTE on `// oss: false` — see the identical note in
+ * `../success/page.tsx`: this page ALSO renders `payment-receipt` via the
+ * paid `@working-theory/ui-commerce` package (D5), so it needs the same
+ * `paths_excluded` + marker pair the `/meet` precedent uses. `create-ailk`'s
+ * scaffold is unaffected — `CORE_ROUTE_DIRS` governs scaffold presence, not
+ * this marker.
+ *
+ * D4 — reads NOTHING. No session id, no API call, no `searchParams` read.
+ * States that nothing was charged and links back to `/services`. This is
+ * what makes AC-2 trivially true and removes the whole page from D3's PII
+ * surface: there is no read to leak.
+ *
+ * D5 — the SAME chassis as `/purchase/success`, with `outcome: "cancel"`
+ * (a distinct, non-forgeable Stripe status — `PaymentResult.tsx`'s
+ * `OUTCOME_STATUS.cancel = "canceled"` — that carries no schema.org
+ * `PaymentComplete` node), no `items` section, and a `cta` whose primary
+ * link is `/services`.
+ *
+ * D12 — base tree, request-time gate, mirroring `/purchase/success`.
+ * `force-dynamic`: a static build without it would prerender the claim
+ * check at BUILD time, so a site that buys commerce after its last deploy
+ * would keep serving a prerendered 404.
+ *
+ * The `ui-commerce` package is registered LAZILY
+ * (`../../../../src/lib/commerce-sections.ts`), mirroring
+ * `/purchase/success` — never a top-level static import, since a keyless
+ * scaffold carries no dependency on it by design (#5581 U6/D5). When it is
+ * genuinely absent, this page falls back to an OSS `content-block` carrying
+ * the same "Checkout canceled" copy.
+ *
+ * `noindex`: reachable only by cancelling a Checkout, never a page a
+ * crawler should list.
+ */
+import { SectionRenderer } from "@working-theory/ui/sections";
+import type { PageSection } from "@working-theory/validation";
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import type { ReactElement } from "react";
+
+import { resolveCommerceClaim } from "../../../../src/lib/commerce-claim";
+import { ensureCommerceSectionsRegistered } from "../../../../src/lib/commerce-sections";
+
+// This page reads nothing and would otherwise be static — force it dynamic
+// so the commerce-claim check (D12) is evaluated per request, not baked
+// into a prerendered build.
+export const dynamic = "force-dynamic";
+
+interface Props {
+  params: Promise<{ locale: string }>;
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const t = await getTranslations({ locale, namespace: "purchase" });
+  return {
+    title: t("cancel.title"),
+    description: t("cancel.message"),
+    robots: { index: false, follow: true },
+  };
+}
+
+export default async function Page({ params }: Props): Promise<ReactElement> {
+  const { locale } = await params;
+  const t = await getTranslations({ locale, namespace: "purchase" });
+
+  // D12 — request-time gate, before any render.
+  if (!(await resolveCommerceClaim())) {
+    notFound();
+  }
+
+  const commerceSectionsAvailable = await ensureCommerceSectionsRegistered();
+  const receipt: PageSection = commerceSectionsAvailable
+    ? {
+        id: "purchase-cancel-receipt",
+        type: "payment-receipt",
+        data: {
+          outcome: "cancel",
+          title: t("cancel.title"),
+          message: t("cancel.message"),
+          statusLabel: t("cancel.statusLabel"),
+        },
+      }
+    : {
+        id: "purchase-cancel-receipt-fallback",
+        type: "content-block",
+        data: {
+          headline: t("cancel.title"),
+          body: `${t("cancel.message")} ${t("cancel.statusLabel")}`,
+        },
+      };
+
+  const sections: PageSection[] = [
+    receipt,
+    {
+      id: "purchase-cancel-cta",
+      type: "cta",
+      data: {
+        headline: t("cancel.ctaHeadline"),
+        description: t("cancel.ctaDescription"),
+        primaryCta: { label: t("cancel.ctaLabel"), href: "/services" },
+      },
+    },
+  ];
+
+  return (
+    <main>
+      <SectionRenderer sections={sections} locale={locale} />
+    </main>
+  );
+}