create-ailk 0.11.1 → 0.11.3

package/templates/apps/web/app/[locale]/layout.tsx

@@ -5,6 +5,7 @@
 // Shell/Chrome composition — Nav + Footer wrap via @working-theory/templates MarketingShell (#2820)
 // Session-aware Nav actions — Sign in / Account + Sign out from the server-read session (#4984)
 // Auth route group — the marketing chrome is dropped on the five (auth) paths (#5963)
+// Account area — the marketing chrome AND the consent Banner are dropped on /account paths (#7430)
 // Site-declared theme — `_site.mdx` `theme:` block → token overlay → CSS vars
 //
 // Sits under app/[locale]/ and sets the <html lang> attribute to the
@@ -48,8 +49,11 @@ import type { ReactElement, ReactNode } from "react";
 
 import { auth } from "../../auth";
 import { GoogleAnalytics } from "../../components/google-analytics";
-import { SignOutTrigger } from "../../components/sign-out-trigger";
-import { isAuthPath } from "../../lib/auth-routes";
+import {
+  SignedInNav,
+  type SignedInNavProps,
+} from "../../components/signed-in-nav";
+import { isAccountPath, isAuthPath } from "../../lib/auth-routes";
 import { assertEnabledLocale } from "../../lib/locale-guard";
 import { footerColumns, navItems } from "../../lib/nav-config";
 import { getOgImageUrl } from "../../lib/og";
@@ -83,10 +87,11 @@ type ThemeMode = "light" | "dark";
  * and `flow` (open a StepFlow lightbox). The `flow` kind + Nav's
  * `renderFlowTrigger` composer is Nav's ONE caller-composed seam (#4341): the
  * caller receives the rendered trigger `<Button>` and decides what wraps it.
- * The layout uses that seam WITHOUT a lightbox — `renderFlowTrigger` below
- * replaces both signed-in triggers (Account → a non-navigating name label,
- * Sign out → `SignOutTrigger`), so this flow config is NEVER rendered. It only
- * has to satisfy the type: one minimal fields-step and a dead `action`.
+ * The layout uses that seam WITHOUT a lightbox — `SignedInNav`'s
+ * `renderFlowTrigger` replaces both signed-in triggers (Account → a
+ * non-navigating name label, Sign out → `SignOutTrigger`), so this flow config
+ * is NEVER rendered. It only has to satisfy the type: one minimal fields-step
+ * and a dead `action`.
  */
 const NAV_CLIENT_ACTION_FLOW: NavActionFlow["flow"] = {
   steps: [
@@ -314,7 +319,8 @@ export default async function LocaleLayout({
   // the service shapes now roster both). Signed in → the user's name (a
   // non-navigating label) + an outline-strong "Sign out"; both authored as
   // `kind: "flow"` so Nav hands their triggers back through
-  // `renderFlowTrigger` (see NAV_CLIENT_ACTION_FLOW above).
+  // `renderFlowTrigger`, which `SignedInNav` owns (see NAV_CLIENT_ACTION_FLOW
+  // above).
   const navActions: NavAction[] = session
     ? [
         { labelKey: "account", kind: "flow", flow: NAV_CLIENT_ACTION_FLOW },
@@ -331,15 +337,17 @@ export default async function LocaleLayout({
         { labelKey: "signUp", path: "/sign-up", variant: "primary" },
       ];
 
-  // Only compose the flow seam when there is a flow action to compose. This
-  // layout is a Server Component and `renderFlowTrigger` is a function, so
-  // passing it is only legal when Nav actually consumes it here rather than
-  // forwarding it across the RSC boundary into NavMobileMenu ("use client").
-  // Passing it unconditionally crashed EVERY signed-out render — the whole of a
-  // fresh scaffold, which configures no auth provider — with "Functions cannot
-  // be passed directly to Client Components". Nav itself already guards its own
-  // forward the same way (chrome/Nav.tsx: `{...(renderFlowTrigger ? … : {})}`);
-  // this is the caller half of that contract.
+  // A flow action needs `renderFlowTrigger`, a function — and this layout is a
+  // Server Component. Nav forwards that function into NavMobileMenu ("use
+  // client"), and React cannot serialize a function across the RSC boundary:
+  // passing it from here crashed EVERY signed-in page with "Functions cannot be
+  // passed directly to Client Components" (#7402). Nav's own
+  // `{...(renderFlowTrigger ? … : {})}` guard only skips the forward when the
+  // function is undefined; it never makes passing one legal. So a flow action
+  // routes the whole Nav through `SignedInNav` ("use client"), which defines
+  // `renderFlowTrigger` and imports `navItems` (icon components are functions
+  // too) on the client side. Without one, Nav stays a Server Component and
+  // nothing callable crosses.
   const hasFlowAction = navActions.some((action) => action.kind === "flow");
 
   // Shared brand mark injected into both Nav and Footer chrome slots. The
@@ -388,6 +396,41 @@ export default async function LocaleLayout({
   // `(marketing)` group — a ~35-directory move for a five-page delta (spec D1).
   const isAuthRoute = isAuthPath(pathname, enabledLocales);
 
+  // The account branch (#7430, spec 7423 D4) — the same mechanism for the
+  // signed-in account area, which renders inside its own SignedInShell: no
+  // Nav, no Footer, no announcement Banner, and no cookie consent Banner
+  // either (the auth branch keeps that one). Cookie settings stay reachable
+  // from User settings › Privacy (`/privacy#cookie-settings`). The same
+  // fail-safe direction: an absent `x-pathname` keeps the full frame.
+  const isAccountRoute = isAccountPath(pathname, enabledLocales);
+
+  // Every Nav prop that is safe to serialize — shared verbatim by the
+  // server-rendered Nav (signed out) and `SignedInNav` (signed in), which adds
+  // `navItems` and `renderFlowTrigger` on its own side of the RSC boundary.
+  const navProps: SignedInNavProps = {
+    locale,
+    labels: navLabels,
+    // Deck home (#5697): the two forwards that join #5426 D4 to a real deck.
+    // `sticky` pins the bar — MarketingShell renders {nav} as a plain child of
+    // the scroll container, so under `scroll-snap-type: y mandatory` the
+    // browser snaps slide 1 to the top on load and the unpinned bar is gone
+    // before the reader touches anything. `deckMorph` is what puts BrandLogo's
+    // `.ailk-deck-brand-mark` / `.ailk-deck-brand-wordmark` hooks in the
+    // document for the D4 CSS to key off; it requires both `logo` and
+    // `wordmark` (Nav.tsx:344), which are passed below. Scoped to the SAME
+    // `isDeckHome` gate MarketingShell's snap/deckHero use, so a non-deck
+    // route's render is byte-identical to before this branch existed.
+    ...(isDeckHome ? { sticky: true, deckMorph: true } : {}),
+    siteName: SITE_NAME,
+    frame: "contained",
+    navAlignment: "right",
+    showThemeToggle: false,
+    logo: brandLogo,
+    wordmark: brandWordmark,
+    overflowLabel: navOverflowLabel,
+    actions: navActions,
+  };
+
   // Placeholder social handles (#5469 D5): `{{COMPANY_HANDLE}}` is a
   // create-ailk marker substituted at scaffold time
   // (packages/create-ailk/src/programmatic.ts), so a customer's site never
@@ -519,14 +562,16 @@ export default async function LocaleLayout({
            * emitted unconditionally in OSS forks; paying customers install
            * @working-theory/branding and gate it in their own layout.
            */}
-          {isAuthRoute ? (
+          {isAuthRoute || isAccountRoute ? (
             /*
              * The (auth) branch (#5963): the five auth paths render their own
              * `(auth)/layout.tsx` — AuthShell — with no Nav and no marketing
              * Footer above or below it. Everything outside this ternary (the
              * document, the flash-prevention script, the theme vars, the
              * favicons, NextIntlClientProvider, the consent Banner and
-             * Telemetry) is shared by both branches and written once.
+             * Telemetry) is shared by both branches and written once. The
+             * account paths (#7430) take this branch too, and also skip the
+             * consent Banner below.
              */
             children
           ) : (
@@ -582,47 +627,14 @@ export default async function LocaleLayout({
                 ? { snap: "mandatory" as const, deckHero: true }
                 : {})}
               nav={
-                <Nav
-                  locale={locale}
-                  labels={navLabels}
-                  navItems={siteChrome.nav === "mark-only" ? [] : navItems}
-                  // Deck home (#5697): the two forwards that join #5426 D4 to a
-                  // real deck. `sticky` pins the bar — MarketingShell renders
-                  // {nav} as a plain child of the scroll container, so under
-                  // `scroll-snap-type: y mandatory` the browser snaps slide 1 to
-                  // the top on load and the unpinned bar is gone before the
-                  // reader touches anything. `deckMorph` is what puts BrandLogo's
-                  // `.ailk-deck-brand-mark` / `.ailk-deck-brand-wordmark` hooks in
-                  // the document for the D4 CSS to key off; it requires both
-                  // `logo` and `wordmark` (Nav.tsx:344), which the layout already
-                  // passes above. Scoped to the SAME `isDeckHome` gate
-                  // MarketingShell's snap/deckHero use, so a non-deck route's
-                  // render is byte-identical to before this branch existed.
-                  {...(isDeckHome ? { sticky: true, deckMorph: true } : {})}
-                  siteName={SITE_NAME}
-                  frame="contained"
-                  navAlignment="right"
-                  showThemeToggle={false}
-                  logo={brandLogo}
-                  wordmark={brandWordmark}
-                  overflowLabel={navOverflowLabel}
-                  actions={navActions}
-                  {...(hasFlowAction
-                    ? {
-                        renderFlowTrigger: (action, trigger) =>
-                          action.labelKey === "signOut" ? (
-                            <SignOutTrigger>{trigger}</SignOutTrigger>
-                          ) : (
-                            <span
-                              className="text-body-sm text-(--color-text-muted)"
-                              data-testid="nav-account-name"
-                            >
-                              {navLabels.items.account}
-                            </span>
-                          ),
-                      }
-                    : {})}
-                />
+                hasFlowAction ? (
+                  <SignedInNav {...navProps} />
+                ) : (
+                  <Nav
+                    {...navProps}
+                    navItems={siteChrome.nav === "mark-only" ? [] : navItems}
+                  />
+                )
               }
               footer={
                 <Footer
@@ -672,31 +684,33 @@ export default async function LocaleLayout({
            * reserves its own space (D1) and carries a close-without-choosing
            * control (D2) instead of a hard server-side hide.
            */}
-          <Banner
-            variant="info"
-            placement="bottom"
-            consentCookieName={CONSENT_COOKIE_NAME}
-            consentDecided={consentDecided}
-            title={tConsent("title")}
-            message={
-              <>
-                {tConsent("body")}{" "}
-                <Link
-                  href={localeHref(locale, "/privacy")}
-                  variant="unstyled"
-                  className="font-semibold text-current underline underline-offset-4"
-                >
-                  {tConsent("policyLinkLabel")}
-                </Link>
-              </>
-            }
-            dismissible={false}
-            dismissLabel={tConsent("dismissLabel")}
-            acceptLabel={tConsent("acceptLabel")}
-            secondaryAction={{ label: tConsent("rejectLabel") }}
-            rejectLabel={tConsent("rejectLabel")}
-            locale={locale}
-          />
+          {isAccountRoute ? null : (
+            <Banner
+              variant="info"
+              placement="bottom"
+              consentCookieName={CONSENT_COOKIE_NAME}
+              consentDecided={consentDecided}
+              title={tConsent("title")}
+              message={
+                <>
+                  {tConsent("body")}{" "}
+                  <Link
+                    href={localeHref(locale, "/privacy")}
+                    variant="unstyled"
+                    className="font-semibold text-current underline underline-offset-4"
+                  >
+                    {tConsent("policyLinkLabel")}
+                  </Link>
+                </>
+              }
+              dismissible={false}
+              dismissLabel={tConsent("dismissLabel")}
+              acceptLabel={tConsent("acceptLabel")}
+              secondaryAction={{ label: tConsent("rejectLabel") }}
+              rejectLabel={tConsent("rejectLabel")}
+              locale={locale}
+            />
+          )}
           <Telemetry />
         </NextIntlClientProvider>
       </body>

package/templates/apps/web/app/[locale]/newsletter/__tests__/newsletter.actions.test.ts

@@ -5,12 +5,25 @@
 
 import { subscribeNewsletterAction } from "../newsletter.actions.js";
 
+// `visitorForwardHeaders` stays real (#7394) so AC-9 compares the action's
+// `init` with the helper's own output.
 jest.mock("@working-theory/api-client", () => ({
   leads: { subscribe: jest.fn() },
+  visitorForwardHeaders: jest.requireActual("@working-theory/api-client")
+    .visitorForwardHeaders,
 }));
 
-import { leads } from "@working-theory/api-client";
+// next/headers' `headers()` is request-scoped in Next; outside it, it is
+// mocked here the way flow.actions.test.ts does (#7394 AC-9).
+jest.mock("next/headers", () => ({
+  __esModule: true,
+  headers: jest.fn().mockResolvedValue({ get: () => null }),
+}));
+
+import { leads, visitorForwardHeaders } from "@working-theory/api-client";
+import { headers } from "next/headers";
 const mockSubscribe = leads.subscribe as jest.Mock;
+const mockHeaders = headers as jest.Mock;
 
 function formWith(email: string): FormData {
   const fd = new FormData();
@@ -19,7 +32,10 @@ function formWith(email: string): FormData {
   return fd;
 }
 
-afterEach(() => jest.clearAllMocks());
+afterEach(() => {
+  jest.clearAllMocks();
+  mockHeaders.mockResolvedValue({ get: () => null });
+});
 
 describe("subscribeNewsletterAction", () => {
   it("calls leads.subscribe with source newsletter and the address", async () => {
@@ -73,3 +89,51 @@ describe("subscribeNewsletterAction", () => {
     expect(mockSubscribe).not.toHaveBeenCalled();
   });
 });
+
+// #7394 AC-9 — a spoke forwards its visitor to the hub's leads rate limit.
+describe("subscribeNewsletterAction — visitor forwarding (#7394)", () => {
+  const FORWARD_KEY = "0123456789abcdef".repeat(4); // gitleaks:allow — test fixture, not a credential (#7394)
+  const ENV_KEYS = ["AILK_VISITOR_FORWARD_KEY", "AILK_API_URL"] as const;
+  const priorEnv = new Map(ENV_KEYS.map((name) => [name, process.env[name]]));
+
+  beforeEach(() => {
+    process.env.AILK_VISITOR_FORWARD_KEY = FORWARD_KEY;
+    process.env.AILK_API_URL = "https://hub.example";
+  });
+
+  afterAll(() => {
+    for (const [name, value] of priorEnv) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  });
+
+  it("passes the helper's two headers as init", async () => {
+    const incoming = {
+      get: (name: string) => (name === "x-forwarded-for" ? "203.0.113.5" : null),
+    };
+    mockHeaders.mockResolvedValue(incoming);
+    mockSubscribe.mockResolvedValueOnce({ ok: true, body: { id: "subscr_1", persisted: "db" } });
+
+    const result = await subscribeNewsletterAction(null, formWith("ada@example.com"));
+
+    expect(result).toEqual({ kind: "success" });
+    const expected = visitorForwardHeaders(incoming, FORWARD_KEY);
+    expect(expected).toEqual({
+      "x-ailk-visitor-ip": "203.0.113.5",
+      "x-ailk-visitor-forward-key": FORWARD_KEY,
+    });
+    expect(mockSubscribe).toHaveBeenCalledWith(expect.any(Object), { headers: expected });
+  });
+
+  it("calls leads.subscribe with one argument when headers() throws, and still succeeds", async () => {
+    mockHeaders.mockRejectedValue(new Error("outside a request scope"));
+    mockSubscribe.mockResolvedValueOnce({ ok: true, body: { id: "subscr_1", persisted: "db" } });
+
+    const result = await subscribeNewsletterAction(null, formWith("ada@example.com"));
+
+    expect(result).toEqual({ kind: "success" });
+    expect(mockSubscribe).toHaveBeenCalledTimes(1);
+    expect(mockSubscribe.mock.calls[0]).toHaveLength(1);
+  });
+});

package/templates/apps/web/app/[locale]/newsletter/newsletter.actions.ts

@@ -12,11 +12,17 @@
  * `captureLeadAction` does: the API's 503 `lead_capture_not_configured` →
  * `unavailable`; any other non-2xx or thrown error → the generic `error`;
  * only a 2xx is `success`.
+ *
+ * Visitor forwarding (#7394): forwards the visitor exactly as
+ * `captureLeadAction` does, through `visitorForwardHeaders` and the
+ * server-only `AILK_VISITOR_FORWARD_KEY`; without them the call is made
+ * with one argument, as before.
  */
 
-import { leads } from "@working-theory/api-client";
+import { leads, visitorForwardHeaders } from "@working-theory/api-client";
 import { LEAD_CAPTURE_HONEYPOT, type LeadCaptureFormState } from "@working-theory/ui";
 import { subscribeNewsletterInputSchema } from "@working-theory/validation";
+import { headers } from "next/headers";
 
 const GENERIC_ERROR = "Something went wrong, please try again.";
 
@@ -40,12 +46,22 @@ export async function subscribeNewsletterAction(
   }
 
   const siteId = process.env.AILK_SITE_ID ?? "default";
+  const body = { siteId, source: "newsletter", email: parsed.data.email };
+  let init: { headers: Record<string, string> } | undefined;
+  try {
+    const forwarded = visitorForwardHeaders(
+      await headers(),
+      process.env.AILK_VISITOR_FORWARD_KEY,
+    );
+    if (forwarded) init = { headers: forwarded };
+  } catch {
+    // No request scope to read — subscribe without forwarding.
+  }
+
   try {
-    const res = await leads.subscribe({
-      siteId,
-      source: "newsletter",
-      email: parsed.data.email,
-    });
+    const res = init
+      ? await leads.subscribe(body, init)
+      : await leads.subscribe(body);
     if (!res.ok) {
       const error =
         typeof res.body === "object" && res.body !== null

package/templates/apps/web/app/openapi.json/__tests__/route.test.ts

@@ -0,0 +1,176 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * Route handler tests: GET /openapi.json (#7396)
+ *
+ * `/.well-known/ai-plugin.json` advertises `${baseUrl}/openapi.json` as its
+ * `api.url`. This route serves that document on the web host by proxying the
+ * API's own `/v1/openapi.json`; when the API cannot answer it, the route
+ * answers 502 — never the 404 an agent following the manifest used to get.
+ * A relative `servers[]` URL is resolved against the API origin, so the
+ * document never sends an agent to this (web) host for an API call.
+ */
+
+import { GET } from "../route";
+
+const SPEC = {
+  openapi: "3.1.0",
+  info: { title: "Example API", version: "1.0.0" },
+  paths: { "/v1/content/search": {} },
+};
+
+const API_ENV = ["AILK_API_URL", "NEXT_PUBLIC_AILK_API_URL"] as const;
+const saved: Record<string, string | undefined> = {};
+let fetchSpy: jest.SpyInstance;
+
+beforeEach(() => {
+  for (const name of API_ENV) {
+    saved[name] = process.env[name];
+    delete process.env[name];
+  }
+  fetchSpy = jest.spyOn(globalThis, "fetch");
+});
+
+afterEach(() => {
+  for (const name of API_ENV) {
+    if (saved[name] === undefined) delete process.env[name];
+    else process.env[name] = saved[name];
+  }
+  fetchSpy.mockRestore();
+});
+
+function apiAnswers(status: number, body: string): void {
+  fetchSpy.mockResolvedValue(
+    new Response(body, {
+      status,
+      headers: { "content-type": "application/json" },
+    }),
+  );
+}
+
+/** The URL the route asked the API for. */
+function requestedUrl(): string {
+  return String(fetchSpy.mock.calls[0]?.[0]);
+}
+
+describe("GET /openapi.json", () => {
+  it("answers 200 with the API's OpenAPI document, unchanged", async () => {
+    apiAnswers(200, JSON.stringify(SPEC));
+
+    const response = await GET();
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("content-type")).toMatch(/application\/json/);
+    expect(await response.json()).toEqual(SPEC);
+  });
+
+  it("reads the API's /v1/openapi.json at AILK_API_URL", async () => {
+    process.env["AILK_API_URL"] = "http://api.internal:4000";
+    apiAnswers(200, JSON.stringify(SPEC));
+
+    await GET();
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    expect(requestedUrl()).toBe("http://api.internal:4000/v1/openapi.json");
+  });
+
+  it("falls back to NEXT_PUBLIC_AILK_API_URL, then the local-dev API origin", async () => {
+    apiAnswers(200, JSON.stringify(SPEC));
+    await GET();
+    expect(requestedUrl()).toBe("http://localhost:3001/v1/openapi.json");
+
+    fetchSpy.mockClear();
+    process.env["NEXT_PUBLIC_AILK_API_URL"] = "https://api.example.com/";
+    apiAnswers(200, JSON.stringify(SPEC));
+    await GET();
+    expect(requestedUrl()).toBe("https://api.example.com/v1/openapi.json");
+  });
+
+  it("answers 502, not 404, when the API cannot be reached", async () => {
+    fetchSpy.mockRejectedValue(new TypeError("fetch failed"));
+
+    const response = await GET();
+
+    expect(response.status).toBe(502);
+    expect(response.headers.get("content-type")).toMatch(/application\/json/);
+    expect(response.headers.get("cache-control")).toBe("no-store");
+    const body = (await response.json()) as { error?: { code?: string } };
+    expect(body.error?.code).toBe("upstream_unavailable");
+  });
+
+  it("answers 502 when the API answers anything but 200", async () => {
+    apiAnswers(404, JSON.stringify({ error: { code: "not_found" } }));
+
+    const response = await GET();
+
+    expect(response.status).toBe(502);
+    expect(response.headers.get("cache-control")).toBe("no-store");
+  });
+
+  it("resolves a relative servers[] URL against the public API origin", async () => {
+    process.env["AILK_API_URL"] = "http://api.internal:4000";
+    process.env["NEXT_PUBLIC_AILK_API_URL"] = "https://api.example.com/";
+    apiAnswers(
+      200,
+      JSON.stringify({ ...SPEC, servers: [{ url: "/", description: "x" }] }),
+    );
+
+    const body = (await (await GET()).json()) as typeof SPEC & {
+      servers: Array<{ url: string }>;
+    };
+
+    expect(requestedUrl()).toBe("http://api.internal:4000/v1/openapi.json");
+    expect(body.servers).toEqual([
+      { url: "https://api.example.com", description: "This deployment's API" },
+    ]);
+  });
+
+  it("resolves a relative servers[] URL against AILK_API_URL when no public origin is set", async () => {
+    process.env["AILK_API_URL"] = "http://localhost:3700";
+    apiAnswers(200, JSON.stringify({ ...SPEC, servers: [{ url: "/" }] }));
+
+    const body = (await (await GET()).json()) as {
+      servers: Array<{ url: string }>;
+    };
+
+    expect(body.servers[0]?.url).toBe("http://localhost:3700");
+  });
+
+  it("leaves an absolute servers[] URL as the API declared it", async () => {
+    const servers = [
+      { url: "https://api.example.com", description: "This deployment" },
+    ];
+    apiAnswers(200, JSON.stringify({ ...SPEC, servers }));
+
+    const body = (await (await GET()).json()) as { servers: unknown };
+
+    expect(body.servers).toEqual(servers);
+  });
+
+  it("answers 502 when the API answers JSON that is not an OpenAPI document", async () => {
+    apiAnswers(200, JSON.stringify({ status: "ok" }));
+
+    const response = await GET();
+
+    expect(response.status).toBe(502);
+  });
+
+  it("answers 502 when the API's 200 body is not JSON", async () => {
+    apiAnswers(200, "<html>not a spec</html>");
+
+    const response = await GET();
+
+    expect(response.status).toBe(502);
+  });
+
+  it("never names the API's internal origin in its error body", async () => {
+    process.env["AILK_API_URL"] = "http://api.internal:4000";
+    fetchSpy.mockRejectedValue(new TypeError("fetch failed"));
+
+    const response = await GET();
+
+    expect(await response.text()).not.toContain("api.internal");
+  });
+});