create-ailk 0.21.0 → 0.23.0

package/templates/apps/web/app/[locale]/flows/[slug]/__tests__/account-invite.actions.test.ts

@@ -0,0 +1,69 @@
+// oss: false
+/**
+ * #8771 AC-4 (the action) — accountInviteLinkAction builds #8757's link on the
+ * server and answers null when it cannot.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const mockGetLocale = jest.fn();
+jest.mock("next-intl/server", () => ({
+  getLocale: (...args: unknown[]) => mockGetLocale(...args),
+}));
+
+const mockInviteHref = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- accountInviteHref reads the generated topology (build output); this file asserts the action's own decision
+jest.mock("../../../../../lib/account-invite", () => ({
+  accountInviteHref: (...args: unknown[]) => mockInviteHref(...args),
+}));
+
+import { accountInviteLinkAction } from "../account-invite.actions";
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockGetLocale.mockResolvedValue("fr");
+  mockInviteHref.mockImplementation(
+    (locale: string, email: string) => `/${locale}/sign-in?email=${email}`,
+  );
+});
+
+describe("accountInviteLinkAction", () => {
+  it("returns what accountInviteHref returns for the request's locale", async () => {
+    await expect(accountInviteLinkAction("jane@example.com")).resolves.toBe(
+      "/fr/sign-in?email=jane@example.com",
+    );
+    expect(mockInviteHref).toHaveBeenCalledWith("fr", "jane@example.com");
+  });
+
+  it.each(["nope", "a\r\n@b.example", "a b@example.com"])(
+    "refuses %j",
+    async (email) => {
+      await expect(accountInviteLinkAction(email)).resolves.toBeNull();
+      expect(mockInviteHref).not.toHaveBeenCalled();
+    },
+  );
+
+  it("answers null when the locale cannot be read", async () => {
+    mockGetLocale.mockRejectedValue(new Error("no request scope"));
+    await expect(
+      accountInviteLinkAction("jane@example.com"),
+    ).resolves.toBeNull();
+  });
+
+  it("answers null for a site with no sign-in", async () => {
+    mockInviteHref.mockReturnValue(null);
+    await expect(
+      accountInviteLinkAction("jane@example.com"),
+    ).resolves.toBeNull();
+  });
+
+  it("makes no API call, and carries the oss marker on its first line", () => {
+    const source = readFileSync(
+      join(__dirname, "..", "account-invite.actions.ts"),
+      "utf8",
+    );
+    expect(source.split("\n")[0]).toBe("// oss: false");
+    expect(source).not.toMatch(/\bfetch\(/);
+    expect(source).not.toContain("@working-theory/api-client");
+  });
+});

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

@@ -0,0 +1,430 @@
+// oss: false
+/**
+ * #8840 D8 — the standard magnet page pair (`magnet-page.tsx`).
+ *
+ * AC-4 — the landing renders the flow record's `landing` copy (one H1, the
+ *        line, the meta line, a CTA to `<path>/start`) with the `Assessment`
+ *        page type's `WebApplication` JSON-LD and no robots key, falling back
+ *        to step 1's title and the generic `flow` copy; the walk renders the
+ *        back arrow and the stepper on step 1 and is `noindex, follow`.
+ * AC-5 — an unreachable hub (a rejected read or a 5xx) shows the site's
+ *        contact email on both pages, both `noindex`, and nothing throws; a
+ *        404 is `notFound()`; one slug's read is shared for 15 seconds, and a
+ *        slug the schema refuses is never read.
+ */
+import { render, screen } from "@testing-library/react";
+import type { FlowConfig } from "@working-theory/validation";
+import type { ReactElement } from "react";
+
+const mockGet = jest.fn();
+jest.mock("@working-theory/api-client", () => ({
+  __esModule: true,
+  flows: { get: (...args: unknown[]) => mockGet(...args) },
+}));
+
+const mockRedirect = jest.fn((href: string) => {
+  throw new Error(`NEXT_REDIRECT ${href}`);
+});
+jest.mock("next/navigation", () => ({
+  __esModule: true,
+  notFound: () => {
+    throw new Error("NEXT_NOT_FOUND");
+  },
+  redirect: (href: string) => mockRedirect(href),
+  useRouter: () => ({ push: jest.fn() }),
+}));
+
+jest.mock("next-intl/server", () => ({
+  __esModule: true,
+  getTranslations: async () => (key: string) => key,
+}));
+
+// The hero section's data, drawn as plain landmarks the assertions read.
+jest.mock("@working-theory/ui/sections", () => {
+  const react = require("react");
+  return {
+    __esModule: true,
+    SectionRenderer: ({ sections }: { sections: Array<{ data: Record<string, unknown> }> }) => {
+      const data = sections[0]!.data as {
+        headline: string;
+        subheadline: string;
+        body?: string;
+        variant?: string;
+        primaryCta: { label: string; href: string };
+      };
+      return react.createElement(
+        "section",
+        { "data-variant": data.variant },
+        react.createElement("h1", null, data.headline),
+        react.createElement("p", { "data-testid": "hero-line" }, data.subheadline),
+        data.body !== undefined
+          ? react.createElement("p", { "data-testid": "hero-meta" }, data.body)
+          : null,
+        react.createElement("a", { href: data.primaryCta.href, "data-testid": "hero-cta" }, data.primaryCta.label),
+      );
+    },
+  };
+});
+
+const mockStepper = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- the walk's client wiring has its own suites; this file pins the renderer
+jest.mock("../FlowStepperClient", () => ({
+  FlowStepperClient: (props: Record<string, unknown>) => {
+    mockStepper(props);
+    const react = require("react");
+    return react.createElement(
+      "div",
+      { "data-testid": "stepper" },
+      props["header"] as ReactElement,
+      (props["config"] as FlowConfig).steps[0]!.copy.title["en"],
+    );
+  },
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- the contact email is env-backed; its reader has its own suite
+jest.mock("../../../contact/site-contact-email", () => ({
+  readSiteContactEmail: () => "hello@example.com",
+}));
+
+import {
+  magnetLandingMetadata,
+  magnetStartMetadata,
+  readMagnet,
+  renderMagnetLanding,
+  renderMagnetStart,
+  renderMagnetStartMetadata,
+} from "../magnet-page";
+
+const en = (s: string) => ({ en: s });
+
+function config(withLanding = true): FlowConfig {
+  return {
+    slug: "growth",
+    defaultLocale: "en",
+    ...(withLanding
+      ? {
+          landing: {
+            title: en("How ready is your team?"),
+            description: en("Ten questions, one page of results."),
+            meta: en("About 3 minutes · Your result arrives by email"),
+            cta: en("Start the diagnostic"),
+          },
+        }
+      : {}),
+    steps: [
+      {
+        key: "team",
+        type: "field",
+        copy: { title: en("Who are you?") },
+        fields: [{ name: "email", inputType: "email", required: true, mapsTo: "email", copy: { label: en("Email") } }],
+      },
+    ],
+  } as FlowConfig;
+}
+
+// One slug's read is shared for 15 seconds; each test starts an hour later.
+let clock = 1_800_000_000_000;
+jest.spyOn(Date, "now").mockImplementation(() => clock);
+
+beforeEach(() => {
+  clock += 60 * 60 * 1000;
+  mockGet.mockReset();
+  mockStepper.mockReset();
+  mockGet.mockResolvedValue({ ok: true, body: config() });
+});
+
+const params = Promise.resolve({ locale: "en" });
+const REF = { slug: "growth", path: "/diagnostic" };
+
+describe("the landing (#8840 D8, AC-4)", () => {
+  it("renders the record's landing copy, a CTA to <path>/start and the WebApplication JSON-LD", async () => {
+    const { container } = render(
+      await renderMagnetLanding({ slug: "growth", path: "/diagnostic", locale: "en" }),
+    );
+    expect(screen.getAllByRole("heading", { level: 1 })).toHaveLength(1);
+    expect(screen.getByRole("heading", { level: 1 }).textContent).toBe("How ready is your team?");
+    expect(screen.getByTestId("hero-line").textContent).toBe("Ten questions, one page of results.");
+    expect(screen.getByTestId("hero-meta").textContent).toBe(
+      "About 3 minutes · Your result arrives by email",
+    );
+    expect(screen.getByTestId("hero-cta").getAttribute("href")).toBe("/diagnostic/start");
+    expect(screen.getByTestId("hero-cta").textContent).toBe("Start the diagnostic");
+    expect(container.querySelector("section")?.getAttribute("data-variant")).toBe("centered");
+
+    const script = container.querySelector('script[type="application/ld+json"]');
+    const jsonLd = JSON.parse(script!.textContent!) as { "@type": string; name: string };
+    expect(jsonLd["@type"]).toBe("WebApplication");
+    expect(jsonLd.name).toBe("How ready is your team?");
+  });
+
+  it("localizes the CTA for a non-default locale", async () => {
+    render(await renderMagnetLanding({ slug: "growth", path: "/diagnostic", locale: "fr" }));
+    expect(screen.getByTestId("hero-cta").getAttribute("href")).toBe("/fr/diagnostic/start");
+  });
+
+  it("falls back to step 1's title, flow.landingIntro and flow.getStarted, with no meta line", async () => {
+    mockGet.mockResolvedValue({ ok: true, body: config(false) });
+    render(await renderMagnetLanding({ slug: "growth", path: "/diagnostic", locale: "en" }));
+    expect(screen.getByRole("heading", { level: 1 }).textContent).toBe("Who are you?");
+    expect(screen.getByTestId("hero-line").textContent).toBe("landingIntro");
+    expect(screen.getByTestId("hero-cta").textContent).toBe("getStarted");
+    expect(screen.queryByTestId("hero-meta")).toBeNull();
+  });
+
+  it("is indexable: the metadata carries the title and no robots key", async () => {
+    const metadata = await magnetLandingMetadata(REF)({ params });
+    expect(metadata.robots).toBeUndefined();
+    expect(metadata.title).toBe("How ready is your team?");
+  });
+});
+
+describe("the walk (#8840 D8, AC-4)", () => {
+  it("renders a NavBackLink to the landing and the stepper on step 1", async () => {
+    render(await renderMagnetStart({ slug: "growth", locale: "en", backHref: "/diagnostic" }));
+    expect(screen.getByTestId("nav-back-link").getAttribute("href")).toBe("/diagnostic");
+    expect(screen.getByTestId("stepper").textContent).toContain("Who are you?");
+    const props = mockStepper.mock.calls[0]![0] as Record<string, unknown>;
+    expect(props["slug"]).toBe("growth");
+    expect(props).not.toHaveProperty("hiddenValues");
+  });
+
+  it("replaces step 1's title and passes hidden values when asked", async () => {
+    render(
+      await renderMagnetStart({
+        slug: "growth",
+        locale: "en",
+        backHref: "/careers/writer",
+        hiddenValues: { job: "writer" },
+        firstStepTitle: "Writer",
+      }),
+    );
+    const props = mockStepper.mock.calls[0]![0] as { config: FlowConfig; hiddenValues: unknown };
+    expect(props.config.steps[0]!.copy.title).toEqual({ en: "Writer" });
+    expect(props.hiddenValues).toEqual({ job: "writer" });
+  });
+
+  it("is noindex, follow", async () => {
+    const metadata = await magnetStartMetadata(REF)({ params });
+    expect(metadata.robots).toEqual({ index: false, follow: true });
+  });
+});
+
+describe("an unreachable hub shows the contact email (#8840 D8, AC-5)", () => {
+  // #9219 — a configured hub, so a rejected read or a plain 503 is an outage
+  // (`unavailable`), not a site with no hub to ask.
+  let savedOrigin: string | undefined;
+  beforeEach(() => {
+    savedOrigin = process.env.AILK_API_URL;
+    process.env.AILK_API_URL = "https://hub.example";
+  });
+  afterEach(() => {
+    if (savedOrigin === undefined) delete process.env.AILK_API_URL;
+    else process.env.AILK_API_URL = savedOrigin;
+  });
+
+  it.each([
+    ["a rejected read", () => mockGet.mockRejectedValue(new TypeError("fetch failed"))],
+    ["a 503", () => mockGet.mockResolvedValue({ ok: false, status: 503, body: null })],
+    // #9219 — a hub that is not configured is its own read kind, and a magnet
+    // pair treats it exactly as an outage.
+    [
+      "a 503 flows_not_configured",
+      () =>
+        mockGet.mockResolvedValue({
+          ok: false,
+          status: 503,
+          body: { ok: false, error: { code: "flows_not_configured", message: "x" } },
+        }),
+    ],
+  ])("%s: both pages render ContactFallback and both are noindex", async (_label, arrange) => {
+    arrange();
+    const landing = render(
+      await renderMagnetLanding({ slug: "growth", path: "/diagnostic", locale: "en" }),
+    );
+    expect(screen.getByTestId("contact-fallback").textContent).toContain("hello@example.com");
+    expect(screen.getByTestId("contact-fallback").textContent).toContain("unavailableHeading");
+    landing.unmount();
+
+    render(await renderMagnetStart({ slug: "growth", locale: "en", backHref: "/diagnostic" }));
+    expect(screen.getByTestId("contact-fallback").textContent).toContain("hello@example.com");
+    expect(screen.getByTestId("nav-back-link")).toBeTruthy();
+    expect(mockStepper).not.toHaveBeenCalled();
+
+    expect((await magnetLandingMetadata(REF)({ params })).robots).toEqual({ index: false, follow: true });
+    expect((await magnetStartMetadata(REF)({ params })).robots).toEqual({ index: false, follow: true });
+  });
+
+  it("a 404 is notFound() on both pages, not an outage", async () => {
+    mockGet.mockResolvedValue({ ok: false, status: 404, body: null });
+    await expect(
+      renderMagnetLanding({ slug: "growth", path: "/diagnostic", locale: "en" }),
+    ).rejects.toThrow("NEXT_NOT_FOUND");
+    await expect(
+      renderMagnetStart({ slug: "growth", locale: "en", backHref: "/diagnostic" }),
+    ).rejects.toThrow("NEXT_NOT_FOUND");
+  });
+});
+
+describe("a walk that exists apart from its flow passes a title (#9219)", () => {
+  const titled = { slug: "growth", locale: "en", backHref: "/careers", title: "Job application" };
+
+  it.each([
+    ["a 404", () => mockGet.mockResolvedValue({ ok: false, status: 404, body: null })],
+    ["a rejected read", () => mockGet.mockRejectedValue(new TypeError("fetch failed"))],
+    ["a 503", () => mockGet.mockResolvedValue({ ok: false, status: 503, body: null })],
+  ])("%s: the contact email under the page's own <h1>, never a 404", async (_label, arrange) => {
+    arrange();
+    render(await renderMagnetStart(titled));
+    expect(screen.getByRole("heading", { level: 1 }).textContent).toBe("Job application");
+    expect(screen.getByTestId("contact-fallback").textContent).toContain("hello@example.com");
+    expect(screen.getByTestId("nav-back-link").getAttribute("href")).toBe("/careers");
+    expect(mockStepper).not.toHaveBeenCalled();
+  });
+
+  it("the fallback's metadata carries the title and stays noindex", async () => {
+    mockGet.mockRejectedValue(new TypeError("fetch failed"));
+    const metadata = await renderMagnetStartMetadata({ slug: "growth", locale: "en", title: "Job application" });
+    expect(metadata).toEqual({ title: "Job application", robots: { index: false, follow: true } });
+  });
+
+  it("a served flow still walks, with no extra heading", async () => {
+    render(await renderMagnetStart(titled));
+    expect(mockStepper).toHaveBeenCalledTimes(1);
+    expect(screen.queryByRole("heading", { level: 1 })).toBeNull();
+  });
+
+  it("without a title an unreachable hub renders no <h1> of its own, and a 404 stays notFound()", async () => {
+    mockGet.mockRejectedValue(new TypeError("fetch failed"));
+    render(await renderMagnetStart({ slug: "growth", locale: "en", backHref: "/diagnostic" }));
+    expect(screen.queryByRole("heading", { level: 1 })).toBeNull();
+
+    clock += 60 * 60 * 1000;
+    mockGet.mockResolvedValue({ ok: false, status: 404, body: null });
+    await expect(
+      renderMagnetStart({ slug: "growth", locale: "en", backHref: "/diagnostic" }),
+    ).rejects.toThrow("NEXT_NOT_FOUND");
+  });
+});
+
+describe("the shared read (#8840 D8, AC-5)", () => {
+  it("two calls within 15 seconds make one flows.get call", async () => {
+    await readMagnet("growth");
+    clock += 14_000;
+    await readMagnet("growth");
+    expect(mockGet).toHaveBeenCalledTimes(1);
+    clock += 2_000;
+    await readMagnet("growth");
+    expect(mockGet).toHaveBeenCalledTimes(2);
+  });
+
+  it("holds at most 256 slugs: past the cap a read is made but not shared", async () => {
+    for (let i = 0; i < 300; i += 1) await readMagnet(`slug-${i}`);
+    expect(mockGet).toHaveBeenCalledTimes(300);
+    await readMagnet("slug-0");
+    expect(mockGet).toHaveBeenCalledTimes(300);
+    await readMagnet("slug-299");
+    expect(mockGet).toHaveBeenCalledTimes(301);
+  });
+
+  it("a slug the schema refuses is absent with no read", async () => {
+    await expect(readMagnet("Bad_Slug")).resolves.toEqual({ kind: "absent" });
+    await expect(readMagnet("Bad_Slug")).resolves.toEqual({ kind: "absent" });
+    expect(mockGet).not.toHaveBeenCalled();
+  });
+});
+
+describe("the read tells a hub that is not configured from one that is down (#9219)", () => {
+  const ORIGIN_NAMES = ["AILK_API_URL", "NEXT_PUBLIC_AILK_API_URL", "NEXT_PUBLIC_API_URL"] as const;
+  const saved: Record<string, string | undefined> = {};
+  beforeEach(() => {
+    for (const name of ORIGIN_NAMES) {
+      saved[name] = process.env[name];
+      delete process.env[name];
+    }
+  });
+  afterEach(() => {
+    for (const name of ORIGIN_NAMES) {
+      if (saved[name] === undefined) delete process.env[name];
+      else process.env[name] = saved[name];
+    }
+  });
+
+  const notConfigured503 = {
+    ok: false,
+    status: 503,
+    body: { ok: false, error: { code: "flows_not_configured", message: "x" } },
+  };
+
+  it("a 503 flows_not_configured is not-configured, origin set or not", async () => {
+    process.env.AILK_API_URL = "https://hub.example";
+    mockGet.mockResolvedValue(notConfigured503);
+    await expect(readMagnet("growth")).resolves.toEqual({ kind: "not-configured" });
+  });
+
+  it.each(ORIGIN_NAMES)("with %s set, a 5xx or a throw is unavailable", async (name) => {
+    process.env[name] = "https://hub.example";
+    mockGet.mockResolvedValue({ ok: false, status: 503, body: null });
+    await expect(readMagnet("growth")).resolves.toEqual({ kind: "unavailable" });
+    clock += 60_000;
+    mockGet.mockRejectedValue(new TypeError("fetch failed"));
+    await expect(readMagnet("growth")).resolves.toEqual({ kind: "unavailable" });
+  });
+
+  it("with no API origin, a 5xx or a throw is not-configured", async () => {
+    mockGet.mockResolvedValue({ ok: false, status: 502, body: null });
+    await expect(readMagnet("growth")).resolves.toEqual({ kind: "not-configured" });
+    clock += 60_000;
+    mockGet.mockRejectedValue(new TypeError("fetch failed"));
+    await expect(readMagnet("growth")).resolves.toEqual({ kind: "not-configured" });
+  });
+
+  it("with no API origin, a 404 is still absent and a served flow still ok", async () => {
+    mockGet.mockResolvedValue({ ok: false, status: 404, body: null });
+    await expect(readMagnet("growth")).resolves.toEqual({ kind: "absent" });
+    clock += 60_000;
+    mockGet.mockResolvedValue({ ok: true, body: config() });
+    await expect(readMagnet("growth")).resolves.toMatchObject({ kind: "ok" });
+  });
+});
+
+describe("a deliverable flow leaves the pair for /reports (#8848 D7, AC-4)", () => {
+  function deliverableConfig(): FlowConfig {
+    // As served: a gated block's target is projected out (#8848 D2).
+    const served = { ...config(), slug: "q3", deliverable: { kind: "page", gated: true, title: en("Q3 report") } };
+    // eslint-disable-next-line no-restricted-syntax -- a served gated block omits its target, which FlowConfig cannot express
+    return served as unknown as FlowConfig;
+  }
+
+  beforeEach(() => {
+    mockRedirect.mockClear();
+    mockGet.mockResolvedValue({ ok: true, body: deliverableConfig() });
+  });
+
+  it("renderMagnetLanding redirects to /reports/<slug>", async () => {
+    await expect(renderMagnetLanding({ slug: "q3", path: "/flows/q3", locale: "en" })).rejects.toThrow(
+      "NEXT_REDIRECT /reports/q3",
+    );
+    await expect(renderMagnetLanding({ slug: "q3", path: "/flows/q3", locale: "fr" })).rejects.toThrow(
+      "NEXT_REDIRECT /fr/reports/q3",
+    );
+  });
+
+  it("renderMagnetStart redirects to /reports/<slug>/start", async () => {
+    await expect(renderMagnetStart({ slug: "q3", locale: "en", backHref: "/flows/q3" })).rejects.toThrow(
+      "NEXT_REDIRECT /reports/q3/start",
+    );
+  });
+
+  it("renderMagnetStart with asDeliverable renders the walk", async () => {
+    render(await renderMagnetStart({ slug: "q3", locale: "en", backHref: "/reports/q3", asDeliverable: true }));
+    expect(mockRedirect).not.toHaveBeenCalled();
+    expect(screen.getByTestId("nav-back-link").getAttribute("href")).toBe("/reports/q3");
+    expect(screen.getByTestId("stepper")).toBeTruthy();
+  });
+
+  it("a config with no block renders as today", async () => {
+    mockGet.mockResolvedValue({ ok: true, body: config() });
+    render(await renderMagnetStart({ slug: "growth", locale: "en", backHref: "/diagnostic" }));
+    expect(mockRedirect).not.toHaveBeenCalled();
+  });
+});

package/templates/apps/web/app/[locale]/flows/[slug]/__tests__/two-route-tool.test.tsx

@@ -76,7 +76,14 @@ function fixtureConfig(): FlowConfig {
   } as FlowConfig;
 }
 
+// #8840 D8 — both routes render through `magnet-page.tsx`, which shares one
+// slug's read for 15 seconds per instance; each test starts an hour later so
+// none sees another's read.
+let clock = 1_800_000_000_000;
+jest.spyOn(Date, "now").mockImplementation(() => clock);
+
 beforeEach(() => {
+  clock += 60 * 60 * 1000;
   mockGet.mockReset();
   mockGet.mockResolvedValue({ ok: true, body: fixtureConfig() });
 });
@@ -95,16 +102,21 @@ describe("the flow route", () => {
     expect(metadata.robots).toEqual({ index: false, follow: true });
   });
 
+  // #8840 D8 — the route mounts the standard renderer, which mounts
+  // `flowRouteMetadata`; neither writes the robots value itself.
   it("gets the value from flowRouteMetadata rather than writing it", () => {
-    const code = readFileSync(
-      join(__dirname, "..", "start", "page.tsx"),
-      "utf8",
-    )
-      .replace(/\/\*[\s\S]*?\*\//g, "")
-      .replace(/\/\/.*$/gm, "");
-    expect(code).toContain("flowRouteMetadata");
-    expect(code).not.toMatch(/robots/i);
-    expect(code).not.toMatch(/noindex/i);
+    const strip = (file: string) =>
+      readFileSync(join(__dirname, "..", file), "utf8")
+        .replace(/\/\*[\s\S]*?\*\//g, "")
+        .replace(/\/\/.*$/gm, "");
+    const route = strip(join("start", "page.tsx"));
+    const renderer = strip("magnet-page.tsx");
+    expect(route).toContain("renderMagnetStartMetadata");
+    expect(renderer).toContain("flowRouteMetadata");
+    for (const code of [route, renderer]) {
+      expect(code).not.toMatch(/robots/i);
+      expect(code).not.toMatch(/noindex/i);
+    }
   });
 });
 

package/templates/apps/web/app/[locale]/flows/[slug]/account-invite.actions.ts

@@ -0,0 +1,35 @@
+// oss: false
+"use server";
+
+/**
+ * accountInviteLinkAction — the walk's "Track this in your account" link
+ * (#8771 D5). The walk's client holds the email the visitor typed; this builds
+ * the sign-in link that starts with that email prefilled, using #8757's
+ * `accountInviteHref`. It is a Server Action, not client code, because
+ * `accountInviteHref` reads the generated topology module, which lazily
+ * imports `../auth` and must never reach a client bundle.
+ *
+ * It makes no API call and writes nothing — the invite email is sent by the
+ * API at completion. No MCP twin: it builds a link from the visitor's own
+ * email for a browser to follow (`WEB_ONLY_ACTIONS` in
+ * `apps/mcp/__tests__/parity.test.ts`).
+ *
+ * Answers `null` for an email the hint schema refuses, a locale that cannot be
+ * read, or a site with no sign-in — the walk then shows no link.
+ */
+import { accountEmailHintSchema } from "@working-theory/validation";
+import { getLocale } from "next-intl/server";
+
+import { accountInviteHref } from "../../../../lib/account-invite";
+
+export async function accountInviteLinkAction(
+  email: string,
+): Promise<string | null> {
+  const hint = accountEmailHintSchema.safeParse(email);
+  if (!hint.success) return null;
+  try {
+    return accountInviteHref(await getLocale(), hint.data);
+  } catch {
+    return null;
+  }
+}