create-ailk 0.11.2 → 0.11.3

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");
+  });
+});

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

@@ -0,0 +1,127 @@
+/**
+ * GET /openapi.json
+ *
+ * The OpenAPI document `/.well-known/ai-plugin.json` advertises as its
+ * `api.url` (#7396). apps/api renders it at `/v1/openapi.json`; this route
+ * serves that same document on the web host, so the URL the manifest names
+ * answers here instead of 404ing. It is read over HTTP — apps/web never
+ * imports apps/api.
+ *
+ * A `servers[]` URL that is relative (apps/api emits `/` when
+ * AILK_PUBLIC_API_URL is unset) is resolved against the API origin before the
+ * document is served. Left relative, it would resolve against THIS host,
+ * which serves none of the API's paths.
+ *
+ * When the API cannot be reached, or answers anything but an OpenAPI
+ * document with a 200, this route answers 502 with a JSON error that names no
+ * upstream origin, and is never cached.
+ */
+
+// Read per request: the document is the running API's, and `next build` has
+// no API to read it from.
+export const dynamic = "force-dynamic";
+
+const UPSTREAM_PATH = "/v1/openapi.json";
+const UPSTREAM_TIMEOUT_MS = 10_000;
+
+const LOCAL_API_ORIGIN = "http://localhost:3001";
+
+/**
+ * The apps/api origin this server reads from — the server-side resolution
+ * order of `getApiBase()` in `@working-theory/api-client`, which the package
+ * root does not export. The deprecated `NEXT_PUBLIC_API_URL` is not read.
+ */
+function apiBase(): string {
+  return stripSlash(
+    process.env["AILK_API_URL"] ||
+      process.env["NEXT_PUBLIC_AILK_API_URL"] ||
+      LOCAL_API_ORIGIN,
+  );
+}
+
+/**
+ * The apps/api origin an agent reading the document calls — the
+ * browser-facing name first, since AILK_API_URL may be a private address.
+ */
+function publicApiBase(): string {
+  return stripSlash(
+    process.env["NEXT_PUBLIC_AILK_API_URL"] ||
+      process.env["AILK_API_URL"] ||
+      LOCAL_API_ORIGIN,
+  );
+}
+
+function stripSlash(url: string): string {
+  return url.replace(/\/+$/, "");
+}
+
+interface OpenApiDocument {
+  openapi: string;
+  servers?: Array<{ url?: unknown; description?: unknown }>;
+}
+
+function isOpenApiDocument(value: unknown): value is OpenApiDocument {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { openapi?: unknown }).openapi === "string"
+  );
+}
+
+/** Resolve every relative `servers[].url` against the public API origin. */
+function withAbsoluteServers(spec: OpenApiDocument): OpenApiDocument {
+  if (!Array.isArray(spec.servers)) return spec;
+  const origin = publicApiBase();
+  return {
+    ...spec,
+    servers: spec.servers.map((server) =>
+      typeof server.url === "string" && !/^[a-z][a-z\d+.-]*:/i.test(server.url)
+        ? {
+            ...server,
+            url: stripSlash(new URL(server.url, `${origin}/`).href),
+            description: "This deployment's API",
+          }
+        : server,
+    ),
+  };
+}
+
+function badGateway(message: string): Response {
+  return Response.json(
+    { error: { code: "upstream_unavailable", message } },
+    { status: 502, headers: { "cache-control": "no-store" } },
+  );
+}
+
+export async function GET(): Promise<Response> {
+  let upstream: Response;
+  try {
+    upstream = await fetch(`${apiBase()}${UPSTREAM_PATH}`, {
+      cache: "no-store",
+      signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
+    });
+  } catch {
+    return badGateway("The API did not answer.");
+  }
+
+  if (upstream.status !== 200) {
+    await upstream.body?.cancel();
+    return badGateway(`The API answered ${upstream.status}.`);
+  }
+
+  let spec: unknown;
+  try {
+    spec = await upstream.json();
+  } catch {
+    return badGateway("The API answered a body that is not JSON.");
+  }
+
+  if (!isOpenApiDocument(spec)) {
+    return badGateway("The API answered JSON that is not an OpenAPI document.");
+  }
+
+  return Response.json(withAbsoluteServers(spec), {
+    status: 200,
+    headers: { "cache-control": "public, max-age=3600" },
+  });
+}

package/templates/apps/web/auth.ts

@@ -29,9 +29,11 @@ import type { PrismaClient } from "@working-theory/database";
 import { betterAuth } from "better-auth";
 import { prismaAdapter } from "better-auth/adapters/prisma";
 import { nextCookies } from "better-auth/next-js";
+import { magicLink } from "better-auth/plugins";
 
 import {
   authEmailTransport,
+  makeMagicLinkOptions,
   makeSendPasswordChangedNotice,
   makeSendResetPassword,
   makeSendVerificationEmail,
@@ -164,10 +166,9 @@ function buildSocialProviders(): SocialProviders {
     };
   }
 
-  // "email" is reported by getActiveProviderIds when AUTH_EMAIL_SERVER +
-  // AUTH_EMAIL_FROM are set, but Better Auth core does not ship a built-in
-  // magic-link provider — that wiring is deferred to a follow-up
-  // (see spec §7 "Out of Scope").
+  // "email" (the password method) and "magic-link" (the emailed sign-in
+  // link, #7435) are not social providers: `createAuth()` wires them as
+  // `emailAndPassword` and the `magicLink` plugin respectively.
 
   return providers;
 }
@@ -300,6 +301,12 @@ export function createAuth(deps: CreateAuthDeps = {}) {
    */
   const resetConfigured = resetSendConfigured();
 
+  /**
+   * The emailed sign-in link (#7435 § D1). The SAME predicate `/sign-in` and
+   * the `(authed)` gate read, so the form renders iff the endpoint exists.
+   */
+  const magicLinkActive = getActiveProviderIds().includes("magic-link");
+
   const trustedProxies = resolveTrustedProxies();
 
   /** Plain assignment, no cast — see `VerificationStore`. */
@@ -517,6 +524,11 @@ export function createAuth(deps: CreateAuthDeps = {}) {
               "/request-password-reset": { window: 900, max: 5 },
               "/reset-password": { window: 900, max: 10 },
               "/send-verification-email": { window: 900, max: 5 },
+              // #7435 § D6. Without a resolvable IP the plugin's own
+              // 5 / 60 s rule applies — for the shared-bucket reason above.
+              ...(magicLinkActive
+                ? { "/sign-in/magic-link": { window: 900, max: 5 } }
+                : {}),
             },
           }
         : {}),
@@ -586,7 +598,19 @@ export function createAuth(deps: CreateAuthDeps = {}) {
       expiresIn: 60 * 60 * 24 * 7, // 7 days
       updateAge: 60 * 60 * 24, // refresh in DB once per day
     },
-    plugins: [nextCookies()],
+    /**
+     * `magicLink` only when its predicate holds (#7435 § D2): absent, its
+     * `/sign-in/magic-link` and `/magic-link/verify` endpoints do not exist.
+     * Sign-in only — the callback mails existing users and nobody else, and
+     * `disableSignUp` refuses to create one even for a live token
+     * (lib/auth-email.ts).
+     */
+    plugins: magicLinkActive
+      ? [
+          nextCookies(),
+          magicLink(makeMagicLinkOptions({ send: authEmailTransport })),
+        ]
+      : [nextCookies()],
   });
 }
 

package/templates/apps/web/jest.config.cjs

@@ -60,6 +60,11 @@ module.exports = {
       "<rootDir>/node_modules/@working-theory/sections-registry/dist/index.js",
     "^@working-theory/templates/shells$":
       "<rootDir>/node_modules/@working-theory/templates/dist/shells/index.js",
+    // The account-area subpath (#7429, spec 7423 D7) — the contribution
+    // contract `lib/account-config.ts` types against, and the Inbox pieces
+    // the /account routes render.
+    "^@working-theory/templates/account$":
+      "<rootDir>/node_modules/@working-theory/templates/dist/account/index.js",
     // Pure-data routes-map subpath (#5572 U2) — mapped directly to source so
     // a consumer of the lightweight `./routes` export (routes.ts,
     // next.config.mjs, this suite) never pulls in the templates package's