create-ailk 0.2.0 → 0.4.0

package/templates/apps/web/app/[locale]/flows/[slug]/results/[payload]/__tests__/page.test.tsx

@@ -1,396 +0,0 @@
-/**
- * Tests for the `/[locale]/flows/[slug]/results/[payload]` cold-load route
- * (#4770).
- *
- * AC3 — a payload encoding a known answer set renders exactly the offer
- *       names and matched reasons `recommend()` returns for those same
- *       answers — asserted against the SAME fixture (`FIXTURE_CONFIG` +
- *       `KNOWN_ANSWERS`) `recommend()` itself would score.
- * AC4 — four cases `redirect()` to `/[locale]/flows/[slug]` and render no
- *       results markup: invalid payload, stale-version payload, a
- *       flowSlug-mismatched payload, and a non-recommending flow.
- *
- * `next/navigation`'s `redirect` is mocked to throw (mirrors the sibling
- * `thanks/[slug]` route's `notFound` test pattern) so a redirect is
- * observable via `.rejects.toThrow` without a real Next.js router. `next-intl`
- * is mocked to an identity translator — `ResultsClient`'s only string comes
- * from the `flow` namespace's `whyThis` key, which this test does not assert
- * on by literal text.
- */
-import { render, screen } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-import type { FlowConfig } from "@working-theory/validation";
-import {
-  encodePermalink,
-  PERMALINK_VERSION,
-  recommend,
-  resolveLocalizedString,
-} from "@working-theory/validation";
-
-const mockGet = jest.fn();
-jest.mock("@working-theory/api-client", () => ({
-  __esModule: true,
-  flows: { get: (...args: unknown[]) => mockGet(...args) },
-}));
-
-const mockRedirect = jest.fn((url: string) => {
-  throw new Error(`NEXT_REDIRECT:${url}`);
-});
-jest.mock("next/navigation", () => ({
-  __esModule: true,
-  redirect: (url: string) => mockRedirect(url),
-}));
-
-jest.mock("next-intl", () => ({
-  __esModule: true,
-  useTranslations: () => (key: string) => key,
-  useMessages: () => ({}),
-}));
-
-import Page, { generateMetadata } from "../page";
-
-const SLUG = "ailk-recommender";
-
-const KNOWN_ANSWERS = { team_size: "solo", wants_seo: "yes" };
-
-function fixtureConfig(overrides: Partial<FlowConfig> = {}): FlowConfig {
-  return {
-    slug: SLUG,
-    defaultLocale: "en",
-    mode: "recommending",
-    steps: [
-      {
-        key: "team",
-        type: "segmentation",
-        copy: { title: { en: "Tell us about your team" } },
-        questions: [
-          {
-            name: "team_size",
-            options: [
-              { value: "solo", label: { en: "Solo" } },
-              { value: "agency", label: { en: "Agency" } },
-            ],
-          },
-          {
-            name: "wants_seo",
-            options: [
-              { value: "yes", label: { en: "Yes" } },
-              { value: "no", label: { en: "No" } },
-            ],
-          },
-        ],
-      },
-    ],
-    offers: [
-      {
-        key: "free_oss",
-        copy: {
-          name: { en: "Free" },
-          description: { en: "Self-serve, open source." },
-        },
-        price: { kind: "label", label: { en: "Free" } },
-        rules: [
-          {
-            when: { answer: "team_size", eq: "solo" },
-            reason: { en: "You're a solo builder." },
-          },
-        ],
-      },
-      {
-        key: "seo_addon",
-        copy: {
-          name: { en: "SEO Add-on" },
-          description: { en: "AEO + SEO tuning." },
-        },
-        price: { kind: "label", label: { en: "Add-on" } },
-        rules: [
-          {
-            when: { answer: "wants_seo", eq: "yes" },
-            reason: { en: "You want more organic reach." },
-          },
-        ],
-      },
-    ],
-    recommendation: {
-      key: "recommendation",
-      copy: { title: { en: "Your recommendation" } },
-    },
-    ...overrides,
-  } as FlowConfig;
-}
-
-beforeEach(() => {
-  mockGet.mockReset();
-  mockRedirect.mockClear();
-});
-
-async function expectRedirectTo(
-  payload: string,
-  expectedUrl: string,
-): Promise<void> {
-  await expect(
-    Page({
-      params: Promise.resolve({ locale: "en", slug: SLUG, payload }),
-    }),
-  ).rejects.toThrow(`NEXT_REDIRECT:${expectedUrl}`);
-  expect(mockRedirect).toHaveBeenCalledWith(expectedUrl);
-}
-
-describe("AC4 — invalid / stale-version / mismatched / non-recommending all redirect to step 1", () => {
-  it("redirects on an invalid payload", async () => {
-    await expectRedirectTo("not-a-valid-payload!!!", `/en/flows/${SLUG}`);
-    // Never fetched the flow config for an undecodable payload.
-    expect(mockGet).not.toHaveBeenCalled();
-  });
-
-  it("redirects on a stale-version payload", async () => {
-    const stalePayload = encodePermalink({
-      version: PERMALINK_VERSION - 1,
-      flowSlug: SLUG,
-      answers: KNOWN_ANSWERS,
-    });
-    await expectRedirectTo(stalePayload, `/en/flows/${SLUG}`);
-    expect(mockGet).not.toHaveBeenCalled();
-  });
-
-  it("redirects when the payload's own flowSlug differs from the route's [slug]", async () => {
-    const mismatchedPayload = encodePermalink({
-      version: PERMALINK_VERSION,
-      flowSlug: "a-different-flow",
-      answers: KNOWN_ANSWERS,
-    });
-    await expectRedirectTo(mismatchedPayload, `/en/flows/${SLUG}`);
-    expect(mockGet).not.toHaveBeenCalled();
-  });
-
-  it("redirects when the served flow is not a recommending flow (no offers)", async () => {
-    const payload = encodePermalink({
-      version: PERMALINK_VERSION,
-      flowSlug: SLUG,
-      answers: KNOWN_ANSWERS,
-    });
-    const {
-      offers: _offers,
-      mode: _mode,
-      ...nonRecommending
-    } = fixtureConfig();
-    mockGet.mockResolvedValueOnce({ ok: true, body: nonRecommending });
-
-    await expectRedirectTo(payload, `/en/flows/${SLUG}`);
-  });
-
-  it("redirects when the served flow declares mode !== 'recommending'", async () => {
-    const payload = encodePermalink({
-      version: PERMALINK_VERSION,
-      flowSlug: SLUG,
-      answers: KNOWN_ANSWERS,
-    });
-    mockGet.mockResolvedValueOnce({
-      ok: true,
-      body: fixtureConfig({ mode: "qualifying" }),
-    });
-
-    await expectRedirectTo(payload, `/en/flows/${SLUG}`);
-  });
-
-  it("no results markup renders on any redirect path (renders nothing before throwing)", async () => {
-    await expect(
-      Page({
-        params: Promise.resolve({
-          locale: "en",
-          slug: SLUG,
-          payload: "garbage",
-        }),
-      }),
-    ).rejects.toThrow();
-    expect(screen.queryByTestId("flow-results")).not.toBeInTheDocument();
-  });
-});
-
-describe("AC3 — a valid payload against a recommending flow renders exactly recommend()'s fits", () => {
-  it("renders exactly the offer names and matched reasons recommend() itself returns for the same answers", async () => {
-    const user = userEvent.setup();
-    const config = fixtureConfig();
-    const payload = encodePermalink({
-      version: PERMALINK_VERSION,
-      flowSlug: SLUG,
-      answers: KNOWN_ANSWERS,
-    });
-    mockGet.mockResolvedValueOnce({ ok: true, body: config });
-
-    // The SAME fixture (`config` + `KNOWN_ANSWERS`) drives BOTH the mocked
-    // server response AND this expectation — `recommend()` is the one
-    // source of truth for "which fits, in what order, with which reason,"
-    // never a second hand-typed list that could silently drift from it.
-    const expected = recommend(
-      {
-        key: SLUG,
-        offers: config.offers,
-        pairings: config.pairings,
-        rateTable: config.rateTable,
-        scoring: config.scoring,
-      },
-      KNOWN_ANSWERS,
-    );
-    expect(expected.fits.length).toBeGreaterThan(0);
-
-    const element = await Page({
-      params: Promise.resolve({ locale: "en", slug: SLUG, payload }),
-    });
-    render(element);
-
-    expect(mockRedirect).not.toHaveBeenCalled();
-    expect(screen.getByTestId("flow-results")).toBeInTheDocument();
-    expect(
-      screen.getByRole("heading", {
-        name: resolveLocalizedString(
-          config.recommendation!.copy.title,
-          "en",
-          config.defaultLocale,
-        ),
-      }),
-    ).toBeInTheDocument();
-
-    for (const fit of expected.fits) {
-      const offer = config.offers!.find((o) => o.key === fit.offerKey)!;
-      const name = resolveLocalizedString(
-        offer.copy.name,
-        "en",
-        config.defaultLocale,
-      );
-      // #4842 FR1 — the top fit's name is ALSO the safe-default side panel's
-      // `offerName`, so the FIRST fit renders exactly twice (panel + card)
-      // and every other fit exactly once.
-      expect(screen.getAllByText(name)).toHaveLength(
-        fit.offerKey === expected.fits[0]!.offerKey ? 2 : 1,
-      );
-      if (offer.copy.description) {
-        expect(
-          screen.getByText(
-            resolveLocalizedString(
-              offer.copy.description,
-              "en",
-              config.defaultLocale,
-            ),
-          ),
-        ).toBeInTheDocument();
-      }
-
-      // The matched reason renders inside the "Why this?" Popover
-      // disclosure — reveal it (mirrors packages/ui/src/blocks/__tests__/
-      // RecommendationCard.test.tsx's own click-to-reveal pattern).
-      await user.click(
-        screen.getByTestId(`recommendation-card-${fit.offerKey}-why-trigger`),
-      );
-      expect(
-        await screen.findByText(
-          resolveLocalizedString(fit.reason, "en", config.defaultLocale),
-        ),
-      ).toBeInTheDocument();
-    }
-  });
-});
-
-describe("generateMetadata", () => {
-  it("resolves the page title from the compiled recommendation marker", async () => {
-    const payload = encodePermalink({
-      version: PERMALINK_VERSION,
-      flowSlug: SLUG,
-      answers: KNOWN_ANSWERS,
-    });
-    mockGet.mockResolvedValueOnce({ ok: true, body: fixtureConfig() });
-
-    const metadata = await generateMetadata({
-      params: Promise.resolve({ locale: "en", slug: SLUG, payload }),
-    });
-    expect(metadata.title).toBe("Your recommendation");
-  });
-
-  it("returns an empty metadata object for an invalid payload", async () => {
-    const metadata = await generateMetadata({
-      params: Promise.resolve({
-        locale: "en",
-        slug: SLUG,
-        payload: "garbage",
-      }),
-    });
-    expect(metadata).toEqual({});
-    expect(mockGet).not.toHaveBeenCalled();
-  });
-});
-
-// ─── #4842 AC-5 — the `?checkout=` return states (additive; the cases above
-// are the regression floor and stay as they were) ───────────────────────────
-
-describe("AC-5 (#4842) — ?checkout= return states render over the same recommendation", () => {
-  function validPayload(): string {
-    return encodePermalink({
-      version: PERMALINK_VERSION,
-      flowSlug: SLUG,
-      answers: KNOWN_ANSWERS,
-    });
-  }
-
-  async function renderWithSearch(
-    checkout: string | undefined,
-  ): Promise<ReturnType<typeof recommend>> {
-    const config = fixtureConfig();
-    mockGet.mockResolvedValueOnce({ ok: true, body: config });
-    const expected = recommend(
-      {
-        key: SLUG,
-        offers: config.offers,
-        pairings: config.pairings,
-        rateTable: config.rateTable,
-        scoring: config.scoring,
-      },
-      KNOWN_ANSWERS,
-    );
-    const element = await Page({
-      params: Promise.resolve({ locale: "en", slug: SLUG, payload: validPayload() }),
-      searchParams: Promise.resolve(checkout === undefined ? {} : { checkout }),
-    });
-    render(element);
-    expect(mockRedirect).not.toHaveBeenCalled();
-    return expected;
-  }
-
-  function expectIdenticalFits(expected: ReturnType<typeof recommend>): void {
-    expect(expected.fits.length).toBeGreaterThan(0);
-    for (const fit of expected.fits) {
-      expect(screen.getByTestId(`recommendation-card-${fit.offerKey}`)).toBeInTheDocument();
-    }
-    expect(screen.getAllByTestId(/^recommendation-card-[a-z_]+$/)).toHaveLength(
-      expected.fits.length,
-    );
-  }
-
-  it("?checkout=success renders the success status line AND the identical fit cards", async () => {
-    const expected = await renderWithSearch("success");
-    expect(screen.getByTestId("flow-results-return-state")).toHaveTextContent("checkoutSuccess");
-    expect(screen.getByRole("status")).toBeInTheDocument();
-    expectIdenticalFits(expected);
-  });
-
-  it("?checkout=cancelled renders the cancelled status line AND the identical fit cards", async () => {
-    const expected = await renderWithSearch("cancelled");
-    expect(screen.getByTestId("flow-results-return-state")).toHaveTextContent("checkoutCancelled");
-    expectIdenticalFits(expected);
-  });
-
-  it("an unrecognised value renders no status line; the fits are unchanged", async () => {
-    const expected = await renderWithSearch("bogus");
-    expect(screen.queryByTestId("flow-results-return-state")).not.toBeInTheDocument();
-    expectIdenticalFits(expected);
-  });
-
-  it("a return param never changes which redirect guard fires (invalid payload still redirects to step 1)", async () => {
-    await expect(
-      Page({
-        params: Promise.resolve({ locale: "en", slug: SLUG, payload: "not-a-valid-payload!!!" }),
-        searchParams: Promise.resolve({ checkout: "success" }),
-      }),
-    ).rejects.toThrow(`NEXT_REDIRECT:/en/flows/${SLUG}`);
-    expect(mockGet).not.toHaveBeenCalled();
-  });
-});

package/templates/apps/web/app/[locale]/flows/[slug]/results/[payload]/page.tsx

@@ -1,114 +0,0 @@
-/**
- * /[locale]/flows/[slug]/results/[payload] — the cold-load results route
- * (#4770).
- *
- * Server-fetches the flow config exactly as `flows/[slug]/page.tsx` does
- * (`flows.get(slug)`, always dynamically rendered — the config is DB-backed
- * live data).
- * Decodes the versioned, answers-only permalink (`decodePermalink`,
- * `@working-theory/validation`) and `redirect()`s to `/[locale]/flows/[slug]`
- * — step 1, never an error page — on ANY of: an invalid payload (FR6), a
- * stale-version payload (FR6), a payload whose own `flowSlug` does not match
- * this route's `[slug]` (D2/FR6), or a served flow that is not a
- * recommending register (D8 — `mode !== "recommending" || !offers`, checked
- * against the field `recommend()` is about to be handed rather than
- * inferring the compiler's five-keys-travel-together guarantee).
- *
- * On a valid payload against a recommending flow, renders `ResultsClient`,
- * which runs the already-shipped pure `recommend()` in the browser and
- * renders the returned fits through the existing `RecommendationCard`
- * (D10 — a minimal render; Epic #4759 recomposes it against the LOCKED
- * DESIGN.md).
- *
- * `?checkout=success|cancelled` (#4842 FR7/D6) is read only after every
- * guard above and rendered by `ResultsClient` as a one-line status over the
- * identical recommendation.
- */
-import { flows } from "@working-theory/api-client";
-import {
-  decodePermalink,
-  resolveLocalizedString,
-} from "@working-theory/validation";
-import type { Metadata } from "next";
-import { redirect } from "next/navigation";
-import type { ReactElement } from "react";
-
-import type { ResultsReturnState } from "./ResultsClient";
-import { ResultsClient } from "./ResultsClient";
-
-export const dynamic = "force-dynamic";
-
-interface Props {
-  params: Promise<{ locale: string; slug: string; payload: string }>;
-  /** FR7 (#4842) — `?checkout=success|cancelled` after Stripe's hosted page. */
-  searchParams?: Promise<Record<string, string | string[] | undefined>>;
-}
-
-/**
- * D6 (#4842) — the return micro-state, validated against the two literals;
- * anything else (absent, an array, an unknown value) renders no status line.
- */
-function resolveReturnState(
-  value: string | string[] | undefined,
-): ResultsReturnState | undefined {
-  return value === "success" || value === "cancelled" ? value : undefined;
-}
-
-export async function generateMetadata({ params }: Props): Promise<Metadata> {
-  const { locale, slug, payload } = await params;
-
-  const decoded = decodePermalink(payload);
-  if (!decoded.ok || decoded.value.flowSlug !== slug) return {};
-
-  const res = await flows.get(slug);
-  if (!res.ok) return {};
-
-  const { recommendation } = res.body;
-  if (!recommendation) return {};
-
-  return {
-    title: resolveLocalizedString(
-      recommendation.copy.title,
-      locale,
-      res.body.defaultLocale,
-    ),
-  };
-}
-
-export default async function Page({
-  params,
-  searchParams,
-}: Props): Promise<ReactElement> {
-  const { locale, slug, payload } = await params;
-
-  const decoded = decodePermalink(payload);
-  if (!decoded.ok) {
-    redirect(`/${locale}/flows/${slug}`);
-  }
-  if (decoded.value.flowSlug !== slug) {
-    redirect(`/${locale}/flows/${slug}`);
-  }
-
-  const res = await flows.get(slug);
-  if (!res.ok) {
-    redirect(`/${locale}/flows/${slug}`);
-  }
-  if (res.body.mode !== "recommending" || res.body.offers === undefined) {
-    redirect(`/${locale}/flows/${slug}`);
-  }
-
-  // FR7 — read AFTER every redirect guard above, so a return param never
-  // changes which guard fires or where it sends the visitor.
-  const returnState = resolveReturnState((await searchParams)?.checkout);
-
-  return (
-    <ResultsClient
-      config={res.body}
-      locale={locale}
-      answers={decoded.value.answers}
-      slug={slug}
-      payload={payload}
-      {...(returnState !== undefined ? { returnState } : {})}
-    />
-  );
-}

package/templates/apps/web/app/[locale]/projects/apply/ListingApplicationClient.tsx

@@ -1,110 +0,0 @@
-"use client";
-
-/**
- * ListingApplicationClient — the REFERENCE MOUNT for the founder application
- * (#5048).
- *
- * This file is the whole per-site cost of the consumer surface, and it is
- * deliberately this short. Before it, a site had to hand-write three proxy
- * routes, a form that saved on every advance, and a decision about where a
- * bearer token lives. What is left is: bind `projectListings` to the section,
- * and decide what to do with the token when `start` mints one.
- *
- * IT IS NOT A BFF, and a site must not copy it into one (the placement
- * decision's D4). `apps/api` is called DIRECTLY: an agent-mediated caller
- * (#5039) cannot use any site's proxy, so the direct path has to be safe on
- * its own terms regardless — and it is, because `siteId` is resolved
- * server-side from the public site key rather than taken from the body. A
- * proxy would be convenience, not a security boundary.
- *
- * TOKEN CUSTODY (#5048 (a)). The token is caller-held. This mount reads a
- * resume link's `id` and `token` query parameters and passes them straight to
- * the section; when `start` mints a new pair it replaces the URL's query
- * parameters with them, so a founder who reloads or navigates back keeps their
- * draft. That is a deliberate choice with a cost: a token in a URL lands in
- * browser history and in any `Referer` the page sends. It is the accepted cost
- * of a resume link that has to survive being EMAILED and opened in a cold
- * browser (samhenry #316 D6b), which is the constraint that rules out an
- * httpOnly cookie entirely. A site with different constraints replaces this
- * one function; nothing else here changes.
- *
- * NO ANTI-AUTOMATION CONTROLS. No honeypot, no timing check, deliberately —
- * see #316 D6b and #5039.
- *
- * SHIPS NO COPY, AND NO ROUTE. Every string comes from the `config` and
- * `messages` a caller passes in. There is deliberately no `page.tsx` beside
- * this file: a route would need a question set, and a question set is the
- * SITE's content — shipping a placeholder one here would put founder-readable
- * copy in the template, which is exactly what this unit exists to stop. A site
- * adds its own route, imports this wrapper, and passes its own config.
- */
-
-import { projectListings } from "@working-theory/api-client";
-import { ListingApplicationFlow } from "@working-theory/ui";
-import type {
-  FlowStepperMessages,
-  ListingApplicationDraftClient,
-  ListingApplicationMessages,
-} from "@working-theory/ui";
-import type { ListingApplicationConfig } from "@working-theory/validation";
-import { useRouter, useSearchParams } from "next/navigation";
-import type { ReactElement, ReactNode } from "react";
-
-/**
- * `projectListings` satisfies the section's structural client contract as-is —
- * `start`, `patchDraft` and `submit` already have the right shapes, and the
- * section defines the interface rather than importing this package so that
- * `packages/ui` stays transport-agnostic (#3957 D2).
- */
-const client: ListingApplicationDraftClient = projectListings;
-
-/** The query parameters an emailed resume link carries. */
-const DRAFT_ID_PARAM = "draft";
-const RESUME_TOKEN_PARAM = "token";
-
-interface Props {
-  config: ListingApplicationConfig;
-  locale: string;
-  messages: FlowStepperMessages & ListingApplicationMessages;
-  /** Rendered under the live tile — the per-listing privacy notice goes here. */
-  tileFooter?: ReactNode;
-}
-
-export function ListingApplicationClient({
-  config,
-  locale,
-  messages,
-  tileFooter,
-}: Props): ReactElement {
-  const router = useRouter();
-  const params = useSearchParams();
-
-  const draftId = params.get(DRAFT_ID_PARAM);
-  const resumeToken = params.get(RESUME_TOKEN_PARAM);
-  const resume =
-    draftId && resumeToken ? { id: draftId, resumeToken } : undefined;
-
-  return (
-    <ListingApplicationFlow
-      config={config}
-      locale={locale}
-      messages={messages}
-      client={client}
-      {...(resume ? { resume } : {})}
-      {...(tileFooter !== undefined ? { tileFooter } : {})}
-      onDraftStarted={({ id, resumeToken: token }) => {
-        // Put the pair in the URL so a reload or a back-navigation resumes
-        // rather than starting a second draft. `replace`, not `push`: the
-        // founder should not have to walk back through one history entry per
-        // step. The site's own email send goes here too — the same two values
-        // are what its resume link carries.
-        const next = new URLSearchParams(params.toString());
-        next.set(DRAFT_ID_PARAM, id);
-        next.set(RESUME_TOKEN_PARAM, token);
-        router.replace(`?${next.toString()}`, { scroll: false });
-      }}
-    />
-  );
-}
-
-export default ListingApplicationClient;