create-ailk 0.19.1 → 0.20.0

package/templates/apps/web/app/[locale]/unsubscribe/__tests__/unsubscribe-rsc-boundary.test.tsx

@@ -0,0 +1,209 @@
+/**
+ * @jest-environment node
+ * @jest-environment-options {"customExportConditions": ["react-server", "node", "require", "default"]}
+ */
+// /[locale]/unsubscribe → real RSC render regression test (#8438 D17, the
+// #7402 class).
+//
+// The create-ailk scaffold matrix's `organization-product · Free` leg answered
+// `GET /unsubscribe` with a 500: `page.tsx` (a Server Component) handed
+// `UnsubscribeButton` ("use client") a `labels.done` FUNCTION, and React
+// refuses to serialize a function into the Flight payload ("Functions cannot
+// be passed directly to Client Components"). `unsubscribe.test.tsx` renders
+// the island in the same jsdom process, so it never crosses the boundary and
+// stayed green while the real page crashed.
+//
+// This suite runs the page through React's own Flight serializer — the same
+// `react-server-dom-webpack` server Next uses — under the `react-server`
+// export condition, with every `"use client"` module in the render graph
+// replaced by a real client reference, exactly as
+// `apps/web/__tests__/signed-in-nav-rsc-boundary.test.tsx` does for the
+// layout. A function crossing any server→client edge throws the production
+// error here.
+
+import fs from "node:fs";
+import path from "node:path";
+import { Writable } from "node:stream";
+
+import type { ReactElement, ReactNode } from "react";
+
+// Next's compiled Flight server ships no types; it is the renderer Next itself runs.
+const flight =
+  require("next/dist/compiled/react-server-dom-webpack/server.node") as {
+    createClientModuleProxy: (moduleId: string) => Record<string, unknown>;
+    renderToPipeableStream: (
+      model: ReactNode,
+      manifest: unknown,
+      options: { onError: (error: unknown) => void },
+    ) => { pipe: (destination: Writable) => void };
+  };
+
+// ── The "use client" boundary ────────────────────────────────────────────────
+
+const REPO_ROOT = path.resolve(__dirname, "../../../../../..");
+
+/** This app and every workspace package its imports can resolve into. */
+const WORKSPACE_DIRS = [
+  path.join(REPO_ROOT, "apps/web"),
+  // `packages-paid` is absent from the public tree the strip derives.
+  ...["packages", "packages-paid"]
+    .map((dir) => path.join(REPO_ROOT, dir))
+    .filter((dir) => fs.existsSync(dir))
+    .flatMap((dir) => fs.readdirSync(dir).map((pkg) => path.join(dir, pkg))),
+];
+
+/** A file's directive prologue opens with "use client" (comments may precede it). */
+const USE_CLIENT = /^(?:\s|\/\/[^\n]*\n|\/\*[\s\S]*?\*\/)*["']use client["']/;
+
+/**
+ * Every source module that marks itself `"use client"` in the trees jest maps
+ * this app's imports onto: the app itself and the workspace packages' `src/`.
+ */
+function clientModules(): string[] {
+  const roots = WORKSPACE_DIRS.map((dir) =>
+    dir.endsWith(path.join("apps", "web")) ? dir : path.join(dir, "src"),
+  );
+  const found: string[] = [];
+  const walk = (dir: string): void => {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (["node_modules", ".next", "__tests__", "dist"].includes(entry.name))
+        continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (
+        /\.tsx?$/.test(entry.name) &&
+        !/\.(stories|test)\.tsx?$/.test(entry.name)
+      ) {
+        if (USE_CLIENT.test(fs.readFileSync(full, "utf8"))) found.push(full);
+      }
+    }
+  };
+  roots.forEach(walk);
+  return found;
+}
+
+/**
+ * The installed `@working-theory/*` packages' built `dist/` trees — the shape a
+ * create-ailk scaffold runs this test in (#8557). There jest maps nothing onto
+ * `src/`: `@working-theory/ui` is a tarball under `node_modules`, and its
+ * Radix-backed primitives carry the directive in their built files. Unmocked,
+ * they load as server code under the `react-server` condition and throw
+ * (`React.createContext is not a function`). In the monorepo the symlinked
+ * workspace package's `dist/` (when built) is walked too; those files are never
+ * reached, since jest maps the imports onto `src/`, so the extra mocks are inert.
+ */
+function installedClientModules(): string[] {
+  const scope = path.join(REPO_ROOT, "apps/web/node_modules/@working-theory");
+  if (!fs.existsSync(scope)) return [];
+  const found: string[] = [];
+  const walk = (dir: string): void => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (/\.(?:m|c)?js$/.test(entry.name)) {
+        if (USE_CLIENT.test(fs.readFileSync(full, "utf8"))) found.push(full);
+      }
+    }
+  };
+  for (const pkg of fs.readdirSync(scope)) {
+    let dist: string;
+    try {
+      dist = path.join(fs.realpathSync(path.join(scope, pkg)), "dist");
+    } catch {
+      continue;
+    }
+    if (fs.existsSync(dist)) walk(dist);
+  }
+  return found;
+}
+
+for (const file of [...clientModules(), ...installedClientModules()]) {
+  jest.doMock(file, () => flight.createClientModuleProxy(file));
+}
+// Third-party client entries the primitives barrel reaches (`next/image` via
+// `Image.tsx`). pnpm can link a physically distinct `next` per workspace, so
+// each entry is mocked at every copy a workspace resolves.
+for (const specifier of ["next/link", "next/image", "next/script"]) {
+  const copies = new Set<string>();
+  for (const dir of WORKSPACE_DIRS) {
+    try {
+      copies.add(require.resolve(specifier, { paths: [dir] }));
+    } catch {
+      // This workspace does not depend on `next`.
+    }
+  }
+  for (const file of copies) {
+    jest.doMock(file, () => flight.createClientModuleProxy(specifier));
+  }
+}
+// `next-intl` is path-independent: jest.config.cjs maps every copy onto one stub.
+jest.doMock("next-intl", () => flight.createClientModuleProxy("next-intl"));
+
+// ── Render ───────────────────────────────────────────────────────────────────
+
+/** Any client-reference id resolves to a chunk-less manifest entry. */
+const CLIENT_MANIFEST = new Proxy(
+  {},
+  { get: (_target, id) => ({ id: String(id), chunks: [], name: "*" }) },
+);
+
+interface FlightResult {
+  errors: string[];
+  payload: string;
+}
+
+/** Serialize the unsubscribe page to a Flight payload, collecting render errors. */
+async function renderPageToFlight(
+  token: string | undefined,
+): Promise<FlightResult> {
+  // Required, not imported: an `import` would be hoisted above the doMock calls.
+  const { default: UnsubscribePage } = require("../page") as {
+    default: (props: {
+      params: Promise<{ locale: string }>;
+      searchParams: Promise<{ t?: string }>;
+    }) => Promise<ReactElement>;
+  };
+
+  const errors: string[] = [];
+  const chunks: string[] = [];
+  await new Promise<void>((resolve, reject) => {
+    const destination = new Writable({
+      write(chunk: Buffer, _encoding, done) {
+        chunks.push(chunk.toString());
+        done();
+      },
+      final(done) {
+        done();
+        resolve();
+      },
+    });
+    destination.on("error", reject);
+    flight
+      .renderToPipeableStream(
+        <UnsubscribePage
+          params={Promise.resolve({ locale: "en" })}
+          searchParams={Promise.resolve(
+            token === undefined ? {} : { t: token },
+          )}
+        />,
+        CLIENT_MANIFEST,
+        { onError: (error) => void errors.push(String(error)) },
+      )
+      .pipe(destination);
+  });
+  return { errors, payload: chunks.join("") };
+}
+
+describe("/[locale]/unsubscribe crosses the RSC → client boundary cleanly", () => {
+  it("serializes with a token: nothing callable is handed to the island", async () => {
+    const { errors, payload } = await renderPageToFlight("tok_1");
+    expect(errors).toEqual([]);
+    expect(payload).toContain("unsubscribe-page");
+  });
+
+  it("serializes with no token", async () => {
+    const { errors } = await renderPageToFlight(undefined);
+    expect(errors).toEqual([]);
+  });
+});

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

@@ -0,0 +1,158 @@
+/**
+ * Tests for /[locale]/unsubscribe (#8438 D17, AC-3 unsubscribe).
+ */
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+/**
+ * One interpolating translator for both halves of the page: the server half
+ * (`getTranslations`, the heading and lead) and the client island
+ * (`useTranslations`, whose done line formats `{description}` in). The
+ * workspace's mapped `next-intl` stub ignores ICU values, so it is replaced
+ * here, the way this file already replaces `next-intl/server`.
+ */
+function mockTranslator(ns: string): (key: string, values?: Record<string, unknown>) => string {
+  const msgs: unknown = require("../../../../messages/en.json");
+  const dig = (obj: unknown, path: string): unknown =>
+    path.split(".").reduce<unknown>(
+      (acc, k) => (acc !== null && typeof acc === "object" ? (acc as Record<string, unknown>)[k] : undefined),
+      obj,
+    );
+  const messages = dig(msgs, ns);
+  return (key, values) => {
+    const value = dig(messages, key);
+    if (typeof value !== "string") return `${ns}.${key}`;
+    return value.replace(/\{(\w+)\}/g, (m, name: string) =>
+      values && name in values ? String(values[name]) : m,
+    );
+  };
+}
+
+jest.mock("next-intl/server", () => ({
+  __esModule: true,
+  getTranslations: async (arg: string | { namespace?: string; locale?: string }) =>
+    mockTranslator(typeof arg === "string" ? arg : (arg.namespace ?? "")),
+}));
+
+jest.mock("next-intl", () => ({
+  __esModule: true,
+  useTranslations: (ns: string) => mockTranslator(ns),
+}));
+
+const mockUnsubscribe = jest.fn();
+jest.mock("@working-theory/api-client", () => ({
+  __esModule: true,
+  consent: { unsubscribe: (...args: unknown[]) => mockUnsubscribe(...args) },
+  visitorForwardHeaders: () => undefined,
+}));
+
+jest.mock("next/headers", () => ({
+  __esModule: true,
+  headers: jest.fn().mockResolvedValue(new Headers()),
+}));
+
+import Page, { generateMetadata } from "../page";
+
+const ok = <T,>(body: T) => ({ ok: true, body });
+const refusal = (status: number) => ({ ok: false, status, body: null });
+
+beforeEach(() => {
+  mockUnsubscribe.mockReset();
+});
+
+async function renderPage(token: string | undefined): Promise<void> {
+  render(
+    await Page({
+      params: Promise.resolve({ locale: "en" }),
+      searchParams: Promise.resolve(token === undefined ? {} : { t: token }),
+    }),
+  );
+}
+
+describe("metadata — noindex, no-referrer (D17, SEC-8438-9)", () => {
+  it("is noindex and sends no-referrer", async () => {
+    const meta = await generateMetadata({
+      params: Promise.resolve({ locale: "en" }),
+      searchParams: Promise.resolve({}),
+    });
+    expect(meta.robots).toEqual({ index: false, follow: true });
+    expect(meta.referrer).toBe("no-referrer");
+  });
+});
+
+describe("the page performs no write on GET", () => {
+  it("renders with no call to unsubscribeAction", async () => {
+    await renderPage("tok_1");
+    expect(mockUnsubscribe).not.toHaveBeenCalled();
+    expect(screen.getByTestId("unsubscribe-page")).toBeInTheDocument();
+    expect(screen.getByRole("heading", { level: 1 })).toHaveTextContent("Unsubscribe");
+    expect(screen.getByText("Stop these emails?")).toBeInTheDocument();
+  });
+});
+
+describe("with no token", () => {
+  it("shows the invalid-link line and no button", async () => {
+    await renderPage(undefined);
+    expect(screen.getByTestId("unsubscribe-invalid")).toHaveTextContent("This link isn't valid.");
+    expect(screen.queryByTestId("unsubscribe-button")).not.toBeInTheDocument();
+    expect(mockUnsubscribe).not.toHaveBeenCalled();
+  });
+});
+
+describe("clicking Unsubscribe", () => {
+  it("a changed answer shows the done line with the purpose's description", async () => {
+    mockUnsubscribe.mockResolvedValue(
+      ok({ purpose: { id: "marketing_email", description: "product news and offers" }, changed: true }),
+    );
+    await renderPage("tok_1");
+    await userEvent.click(screen.getByTestId("unsubscribe-button"));
+    expect(mockUnsubscribe).toHaveBeenCalledWith({ token: "tok_1" });
+    expect(await screen.findByTestId("unsubscribe-done")).toHaveTextContent(
+      "You're unsubscribed from product news and offers.",
+    );
+  });
+
+  it("changed: false shows the already-unsubscribed line, with no second write implied", async () => {
+    mockUnsubscribe.mockResolvedValue(
+      ok({ purpose: { id: "marketing_email", description: "product news and offers" }, changed: false }),
+    );
+    await renderPage("tok_1");
+    await userEvent.click(screen.getByTestId("unsubscribe-button"));
+    expect(await screen.findByTestId("unsubscribe-already")).toHaveTextContent(
+      "You were already unsubscribed.",
+    );
+  });
+
+  it("any 400 shows the invalid-link line", async () => {
+    mockUnsubscribe.mockResolvedValue(refusal(400));
+    await renderPage("tok_1");
+    await userEvent.click(screen.getByTestId("unsubscribe-button"));
+    expect(await screen.findByTestId("unsubscribe-invalid")).toHaveTextContent("This link isn't valid.");
+  });
+
+  it("a 429 (rate-limited) shows the unavailable line, never the invalid-link line", async () => {
+    mockUnsubscribe.mockResolvedValue(refusal(429));
+    await renderPage("tok_1");
+    await userEvent.click(screen.getByTestId("unsubscribe-button"));
+    expect(await screen.findByTestId("unsubscribe-unavailable")).toHaveTextContent(
+      "Unsubscribing isn't available right now.",
+    );
+    expect(screen.queryByTestId("unsubscribe-invalid")).not.toBeInTheDocument();
+  });
+
+  it("a 5xx shows the unavailable line", async () => {
+    mockUnsubscribe.mockResolvedValue(refusal(503));
+    await renderPage("tok_1");
+    await userEvent.click(screen.getByTestId("unsubscribe-button"));
+    expect(await screen.findByTestId("unsubscribe-unavailable")).toHaveTextContent(
+      "Unsubscribing isn't available right now.",
+    );
+  });
+
+  it("a thrown error shows the unavailable line, never a crash", async () => {
+    mockUnsubscribe.mockRejectedValue(new TypeError("fetch failed"));
+    await renderPage("tok_1");
+    await userEvent.click(screen.getByTestId("unsubscribe-button"));
+    expect(await screen.findByTestId("unsubscribe-unavailable")).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,54 @@
+/**
+ * /[locale]/unsubscribe — the one unsubscribe landing every signed link
+ * calls (#8438 D17, NEW). Public, `noindex`, `referrer: no-referrer` so the
+ * `?t=` token never leaks through a Referer header off this page (D17,
+ * SEC-8438-9).
+ *
+ * RSC: reads `?t=` and renders the heading, the lead and the one
+ * interactive piece (`UnsubscribeButton`, "use client") that posts
+ * `unsubscribeAction(token)` ON CLICK — never on this GET, so a mail
+ * scanner's prefetch writes nothing. The island gets the token and nothing
+ * else: it reads its own strings, because anything callable handed across
+ * this server→client edge fails Flight serialization (the scaffold matrix's
+ * `GET /unsubscribe -> 500`; `__tests__/unsubscribe-rsc-boundary.test.tsx`).
+ */
+
+import { Heading, Text } from "@working-theory/ui/primitives";
+import type { Metadata } from "next";
+import { getTranslations } from "next-intl/server";
+import type { ReactElement } from "react";
+
+import { UnsubscribeButton } from "./unsubscribe-button";
+
+interface Props {
+  params: Promise<{ locale: string }>;
+  searchParams: Promise<{ t?: string }>;
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const t = await getTranslations({ locale, namespace: "unsubscribe" });
+  return {
+    title: t("title"),
+    robots: { index: false, follow: true },
+    referrer: "no-referrer",
+  };
+}
+
+export default async function UnsubscribePage({ params, searchParams }: Props): Promise<ReactElement> {
+  const { locale } = await params;
+  const { t: token } = await searchParams;
+  const t = await getTranslations({ locale, namespace: "unsubscribe" });
+
+  return (
+    <div className="mx-auto flex max-w-md flex-col gap-4 px-4 py-16" data-testid="unsubscribe-page">
+      <Heading level={1} visual={2}>
+        {t("title")}
+      </Heading>
+      <Text as="p" variant="body">
+        {t("lead")}
+      </Text>
+      <UnsubscribeButton token={token ?? null} />
+    </div>
+  );
+}

package/templates/apps/web/app/[locale]/unsubscribe/unsubscribe-button.tsx

@@ -0,0 +1,73 @@
+"use client"; // owns the click → unsubscribeAction → result state
+
+/**
+ * UnsubscribeButton — the unsubscribe page's one interactive piece (#8438
+ * D17). Posts `unsubscribeAction(token)` on click only — never on render,
+ * so a mail scanner's GET prefetch of the page writes nothing.
+ *
+ * Reads its own strings through `useTranslations` (the island idiom
+ * `FlowStepperClient` uses) rather than taking them as props: the done line
+ * needs the purpose's description formatted in, and a formatting FUNCTION
+ * handed across from the page (a Server Component) cannot be serialized
+ * into the Flight payload — the scaffold matrix's `GET /unsubscribe -> 500`
+ * (`unsubscribe-rsc-boundary.test.tsx` holds the regression).
+ */
+
+import { Button, InlineMessage } from "@working-theory/ui/primitives";
+import { useTranslations } from "next-intl";
+import { useState, useTransition, type ReactElement } from "react";
+
+import { unsubscribeAction, type UnsubscribeResult } from "./unsubscribe.actions";
+
+export function UnsubscribeButton({ token }: { token: string | null }): ReactElement {
+  const t = useTranslations("unsubscribe");
+  const [result, setResult] = useState<UnsubscribeResult | null>(null);
+  const [pending, startTransition] = useTransition();
+
+  if (token === null || result?.kind === "invalid") {
+    return (
+      <InlineMessage variant="error" role="alert" data-testid="unsubscribe-invalid">
+        {t("invalid")}
+      </InlineMessage>
+    );
+  }
+
+  if (result?.kind === "done") {
+    return (
+      <InlineMessage variant="success" role="status" data-testid="unsubscribe-done">
+        {t("done", { description: result.description })}
+      </InlineMessage>
+    );
+  }
+
+  if (result?.kind === "already") {
+    return (
+      <InlineMessage variant="success" role="status" data-testid="unsubscribe-already">
+        {t("already")}
+      </InlineMessage>
+    );
+  }
+
+  if (result?.kind === "unavailable") {
+    return (
+      <InlineMessage variant="error" role="alert" data-testid="unsubscribe-unavailable">
+        {t("unavailable")}
+      </InlineMessage>
+    );
+  }
+
+  return (
+    <Button
+      type="button"
+      disabled={pending}
+      onClick={() => {
+        startTransition(async () => {
+          setResult(await unsubscribeAction(token));
+        });
+      }}
+      data-testid="unsubscribe-button"
+    >
+      {t("button")}
+    </Button>
+  );
+}

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

@@ -0,0 +1,55 @@
+"use server";
+
+/**
+ * unsubscribeAction — the unsubscribe page's one write (#8438 D9, D17).
+ *
+ * Calls `POST /v1/consent/unsubscribe` (`consent.unsubscribe`) through
+ * `@working-theory/api-client`, carrying the visitor-forward headers a
+ * spoke attaches today — the same idiom `contact.actions.ts` uses. Never
+ * writes anything on its own: the page's GET never calls this, so a mail
+ * scanner's prefetch of the link changes nothing (D17).
+ *
+ * The token is the only authority (D9) — this action never names an email,
+ * a workspace or a person.
+ */
+
+import { consent, visitorForwardHeaders } from "@working-theory/api-client";
+import { headers } from "next/headers";
+
+export type UnsubscribeResult =
+  | { kind: "done"; description: string }
+  | { kind: "already" }
+  | { kind: "invalid" }
+  | { kind: "unavailable" };
+
+export async function unsubscribeAction(token: string): Promise<UnsubscribeResult> {
+  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 — call with no forwarding.
+  }
+
+  try {
+    const res = init
+      ? await consent.unsubscribe({ token }, init)
+      : await consent.unsubscribe({ token });
+    if (!res.ok) {
+      // 429 is transient (a rate limit), never the token's fault — "invalid"
+      // would tell a visitor the link itself is bad when retrying would work.
+      if (res.status >= 400 && res.status < 500 && res.status !== 429) return { kind: "invalid" };
+      return { kind: "unavailable" };
+    }
+    if (!res.body.changed) return { kind: "already" };
+    return { kind: "done", description: res.body.purpose.description };
+  } catch (err) {
+    // The api-client never attaches the request payload to a thrown error,
+    // so logging `err` carries no token.
+    console.error("[unsubscribeAction]", err);
+    return { kind: "unavailable" };
+  }
+}

package/templates/apps/web/app/robots.txt/route.ts

@@ -8,28 +8,31 @@
  *     (comma-separated paths, e.g. "/admin/,/private/")
  *   - STEALTH=true disallows every path for every crawler — layer 1 of the
  *     three-layer stealth posture (#884, #7374); it subsumes any
- *     AILK_ROBOTS_DISALLOW paths
+ *     AILK_ROBOTS_DISALLOW paths and drops the Sitemap line, so a hidden
+ *     site advertises no URLs (#8519). STEALTH is read through the shared
+ *     parse (#8511), so 1, yes and on count too, and an unknown value throws.
  */
 
+import { parseStealth } from "@working-theory/web-i18n/stealth";
+
 import { resolveBaseUrl } from "../../src/lib/routes";
 
 export function GET(): Response {
   const baseUrl = resolveBaseUrl();
   const disallowEnv = process.env["AILK_ROBOTS_DISALLOW"] ?? "";
+  const stealth = parseStealth(process.env["STEALTH"]);
 
-  const disallowPaths =
-    process.env["STEALTH"] === "true"
-      ? ["/"]
-      : disallowEnv
-          .split(",")
-          .map((p) => p.trim())
-          .filter((p) => p.length > 0);
+  const disallowPaths = stealth
+    ? ["/"]
+    : disallowEnv
+        .split(",")
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
 
   const lines = [
     "User-agent: *",
     ...disallowPaths.map((p) => `Disallow: ${p}`),
-    "",
-    `Sitemap: ${baseUrl}/sitemap.xml`,
+    ...(stealth ? [] : ["", `Sitemap: ${baseUrl}/sitemap.xml`]),
   ];
 
   return new Response(lines.join("\n"), {

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

@@ -89,6 +89,9 @@ module.exports = {
       "<rootDir>/node_modules/@working-theory/site-config/dist/schema/index.js",
     "^@working-theory/validation$": "<rootDir>/node_modules/@working-theory/validation/dist/index.js",
     "^@working-theory/web-i18n$": "<rootDir>/node_modules/@working-theory/web-i18n/dist/index.js",
+    // The Edge-safe `./stealth` subpath (#8511) → source, like the root entry.
+    "^@working-theory/web-i18n/stealth$":
+      "<rootDir>/node_modules/@working-theory/web-i18n/dist/stealth-metadata.js",
     // The dependency-free tenancy-constants subpath (database/tenancy.ts).
     // Mapped to source like every sibling above; `database/dist` is not
     // built in this workspace pre-`pnpm build`.