create-ailk 0.22.0 → 0.24.0

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

@@ -107,6 +107,17 @@ const VALID_FIELDS = {
 const INITIAL_STATE = null;
 
 describe("captureLeadAction — valid input", () => {
+  it("#8847 D7 — the success state carries the posted name, for the ending's {name}", async () => {
+    mockSubmit.mockResolvedValueOnce({
+      ok: true,
+      body: { id: "lead_abc123", persisted: "db" },
+    });
+
+    const result = await captureLeadAction(INITIAL_STATE, makeFormData(VALID_FIELDS));
+
+    expect(result).toStrictEqual({ kind: "success", name: "Jane Smith" });
+  });
+
   it("returns success state when api-client responds ok", async () => {
     mockSubmit.mockResolvedValueOnce({
       ok: true,
@@ -270,7 +281,7 @@ describe("captureLeadAction — outcome mapping (#6730)", () => {
 
     const result = await captureLeadAction(INITIAL_STATE, makeFormData(VALID_FIELDS));
 
-    expect(result).toEqual({ kind: "success" });
+    expect(result).toEqual({ kind: "success", name: expect.any(String) });
   });
 });
 
@@ -382,7 +393,7 @@ describe("captureLeadAction — visitor forwarding (#7394)", () => {
 
     const result = await captureLeadAction(INITIAL_STATE, makeFormData(VALID_FIELDS));
 
-    expect(result).toEqual({ kind: "success" });
+    expect(result).toEqual({ kind: "success", name: expect.any(String) });
     const expected = visitorForwardHeaders(incoming, FORWARD_KEY);
     expect(expected).toEqual({
       "x-ailk-visitor-ip": "203.0.113.5",
@@ -397,7 +408,7 @@ describe("captureLeadAction — visitor forwarding (#7394)", () => {
 
     const result = await captureLeadAction(INITIAL_STATE, makeFormData(VALID_FIELDS));
 
-    expect(result).toEqual({ kind: "success" });
+    expect(result).toEqual({ kind: "success", name: expect.any(String) });
     expect(mockSubmit).toHaveBeenCalledTimes(1);
     expect(mockSubmit.mock.calls[0]).toHaveLength(1);
   });
@@ -438,7 +449,7 @@ describe("captureLeadAction — consent and source (#8661 D8)", () => {
       makeFormData({ ...VALID_FIELDS, source: "flow:contact", subject: "Support" }),
     );
 
-    expect(result).toEqual({ kind: "success" });
+    expect(result).toEqual({ kind: "success", name: expect.any(String) });
     expect(mockSubmit).toHaveBeenCalledTimes(1);
     const body = mockSubmit.mock.calls[0][0] as {
       source: string;
@@ -505,7 +516,7 @@ describe("captureLeadAction — consent and source (#8661 D8)", () => {
       makeFormData({ ...VALID_FIELDS, source: "conversational-intake" }),
     );
 
-    expect(result).toEqual({ kind: "success" });
+    expect(result).toEqual({ kind: "success", name: expect.any(String) });
     const body = mockSubmit.mock.calls[0][0] as { source: string; consent: unknown };
     expect(body.source).toBe("conversational-intake");
     expect(body.consent).toBe(true);
@@ -611,6 +622,7 @@ describe("captureLeadAction — the per-visitor limit (#8747)", () => {
     for (let i = 0; i < 30; i += 1) {
       expect(await captureLeadAction(INITIAL_STATE, makeFormData(VALID_FIELDS))).toEqual({
         kind: "success",
+        name: expect.any(String),
       });
     }
     expect(mockSubmit).toHaveBeenCalledTimes(30);
@@ -628,6 +640,7 @@ describe("captureLeadAction — the per-visitor limit (#8747)", () => {
     for (let i = 0; i < 31; i += 1) {
       expect(await captureLeadAction(INITIAL_STATE, makeFormData(VALID_FIELDS))).toEqual({
         kind: "success",
+        name: expect.any(String),
       });
     }
     expect(mockSubmit).toHaveBeenCalledTimes(31);
@@ -643,6 +656,7 @@ describe("captureLeadAction — the per-visitor limit (#8747)", () => {
     mockHeaders.mockResolvedValue(visitor("198.51.100.7"));
     expect(await captureLeadAction(INITIAL_STATE, makeFormData(VALID_FIELDS))).toEqual({
       kind: "success",
+      name: expect.any(String),
     });
   });
 });
@@ -705,6 +719,7 @@ describe("captureLeadAction — the account link (#8757 D8)", () => {
 
     expect(await captureLeadAction(INITIAL_STATE, makeFormData(INVITE_FIELDS))).toEqual({
       kind: "success",
+      name: expect.any(String),
       next: { href: "/sign-in?next=%2Faccount&email=a%40b.example", label: LABEL },
     });
   });
@@ -715,6 +730,7 @@ describe("captureLeadAction — the account link (#8757 D8)", () => {
 
     expect(await captureLeadAction(INITIAL_STATE, makeFormData(INVITE_FIELDS))).toEqual({
       kind: "success",
+      name: expect.any(String),
       next: { href: "/fr/sign-in?next=%2Ffr%2Faccount&email=a%40b.example", label: LABEL },
     });
   });
@@ -724,6 +740,7 @@ describe("captureLeadAction — the account link (#8757 D8)", () => {
 
     expect(await captureLeadAction(INITIAL_STATE, makeFormData(INVITE_FIELDS))).toStrictEqual({
       kind: "success",
+      name: expect.any(String),
     });
   });
 
@@ -733,6 +750,7 @@ describe("captureLeadAction — the account link (#8757 D8)", () => {
 
     expect(await captureLeadAction(INITIAL_STATE, makeFormData(INVITE_FIELDS))).toEqual({
       kind: "success",
+      name: expect.any(String),
       next: { href: "/api/hub-session/sign-in?next=%2Faccount&email=a%40b.example", label: LABEL },
     });
   });
@@ -743,6 +761,7 @@ describe("captureLeadAction — the account link (#8757 D8)", () => {
 
     expect(await captureLeadAction(INITIAL_STATE, makeFormData(INVITE_FIELDS))).toStrictEqual({
       kind: "success",
+      name: expect.any(String),
     });
   });
 
@@ -752,6 +771,7 @@ describe("captureLeadAction — the account link (#8757 D8)", () => {
 
     expect(await captureLeadAction(INITIAL_STATE, makeFormData(INVITE_FIELDS))).toEqual({
       kind: "success",
+      name: expect.any(String),
       next: { href: "/sign-in?next=%2Faccount&email=a%40b.example", label: LABEL },
     });
   });
@@ -761,6 +781,7 @@ describe("captureLeadAction — the account link (#8757 D8)", () => {
 
     expect(await captureLeadAction(INITIAL_STATE, makeFormData(INVITE_FIELDS))).toStrictEqual({
       kind: "success",
+      name: expect.any(String),
     });
   });
 });
@@ -818,6 +839,7 @@ describe("captureLeadAction — a checkout magnet redirects after the write (#87
 
       expect(await captureLeadAction(INITIAL_STATE, makeFormData(VALID_FIELDS))).toStrictEqual({
         kind: "success",
+        name: expect.any(String),
       });
       expect(mockRedirect).not.toHaveBeenCalled();
     },
@@ -830,6 +852,7 @@ describe("captureLeadAction — a checkout magnet redirects after the write (#87
 
       expect(await captureLeadAction(INITIAL_STATE, makeFormData(VALID_FIELDS))).toStrictEqual({
         kind: "success",
+        name: expect.any(String),
       });
       expect(mockSubmit).toHaveBeenCalledTimes(1);
       expect(mockRedirect).not.toHaveBeenCalled();

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

@@ -3,8 +3,10 @@
 /**
  * captureLeadAction — Server Action paired with ailkCaptureLead MCP tool.
  *
- * Validates contact-form input with submitLeadInputSchema (shared schema per
- * ADR 0013), calls POST /v1/leads/submit via @working-theory/api-client, and returns
+ * Validates contact-form input with its own `contactFormSchema` (the form's
+ * field set is the page's, not a wire contract — the `capture_lead` MCP tool
+ * takes the route body since #7171), calls POST /v1/leads/submit via
+ * @working-theory/api-client, and returns
  * the shared `LeadCaptureForm` block's `LeadCaptureFormState`.
  *
  * Canonical filename: contact.actions.ts (*.actions.ts per ADR 0013 / U0 spec
@@ -102,11 +104,11 @@ import {
   CONTACT_LEAD_SOURCES,
   flowCheckoutOfferingSchema,
   leadSubmitNextSchema,
-  submitLeadInputSchema,
 } from "@working-theory/validation";
 import { cookies, headers } from "next/headers";
 import { redirect } from "next/navigation";
 import { getLocale, getTranslations } from "next-intl/server";
+import { z } from "zod";
 
 import { accountInviteHref } from "../../../lib/account-invite";
 import { consentVisitorHeader, readConsentVisitor } from "../../../lib/consent-visitor";
@@ -139,6 +141,14 @@ const DEFAULT_SOURCE = "contact-form";
 const CONSENT_REQUIRED = "Please accept the terms to send your message.";
 const MAX_EXTRA_FIELD_LENGTH = 2000;
 
+/** The form's four fields and bounds; each field error is zod's own message. */
+const contactFormSchema = z.object({
+  name: z.string().min(1).max(200),
+  email: z.string().email(),
+  message: z.string().max(2000).optional(),
+  phone: z.string().max(50).optional(),
+});
+
 /**
  * The declared extra fields, or `null` when they exceed the bounds. Non-string
  * entries (files) and Next's own `$ACTION_…` keys are skipped.
@@ -203,7 +213,10 @@ function checkoutOfferingOf(next: unknown): string | null {
  * the API answered `next: { completion: "invite" }` and this site can build
  * one, else exactly `{ kind: "success" }`. Never throws.
  */
-async function successState(next: unknown, email: string): Promise<LeadCaptureFormState> {
+async function successState(
+  next: unknown,
+  email: string,
+): Promise<Extract<LeadCaptureFormState, { kind: "success" }>> {
   const parsed = leadSubmitNextSchema.safeParse(next);
   if (!parsed.success || parsed.data.completion !== "invite") return { kind: "success" };
   let locale = "en";
@@ -250,7 +263,7 @@ export async function captureLeadAction(
     fieldErrors.consent = CONSENT_REQUIRED;
   }
 
-  const parsed = submitLeadInputSchema.safeParse(raw);
+  const parsed = contactFormSchema.safeParse(raw);
   if (!parsed.success) {
     for (const issue of parsed.error.issues) {
       const field = String(issue.path[0] ?? "form");
@@ -321,5 +334,6 @@ export async function captureLeadAction(
   // #8757 D11 — after the write, outside any try: redirect() throws by design.
   const checkoutOffering = checkoutOfferingOf(res.body.next);
   if (checkoutOffering !== null) redirect(`/api/checkout/${checkoutOffering}`);
-  return successState(res.body.next, email);
+  // #8847 D7 — the parsed name, which the magnet's ending fills `{name}` with.
+  return { ...(await successState(res.body.next, email)), name };
 }

package/templates/apps/web/app/[locale]/contact/intake-script.ts

@@ -4,7 +4,7 @@
  * leg).
  *
  * Three open questions, deliberately keyed `name` / `message` / `email` —
- * the SAME field names `submitLeadInputSchema` (packages/validation)
+ * the SAME field names `contactFormSchema` (`./contact.actions.ts`)
  * expects. `ConversationalIntakeWrapper` reads `IntakeEngineState.answers`
  * by these exact ids to build the `FormData` it hands to the existing
  * `captureLeadAction` (`./contact.actions.ts`), so the script's question

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

@@ -11,22 +11,25 @@
 // API, an older API without the status route, or any other failed read is
 // treated as accepting: the form renders, and its submit reports honestly.
 //
-// The form's fields (#8661 D6), first usable wins: the workspace's Contact
-// form magnet (`flows.get("contact")`, the public flow read — the API resolves
-// the workspace, the site alias keyless and a spoke by its key); else the
-// page's `contact-form` section fields when it declares any; else the
-// built-in form: the seeded magnet's own config, its name, email and message
-// labels from the `contact` catalog. The submit label is the magnet's, else
-// the section's; the success message is the section's. A magnet-driven
-// post is stamped `source: "flow:contact"`, so it is an Inbox submission of
-// the Contact form; the other two post as `contact-form` (#8747). The page is rendered on
-// every request, but its two hub reads (the magnet and the capture status) are
-// shared across requests for HUB_READ_TTL_MS (#8731): a visitor view carries no
-// forwarding headers, so on a spoke every view would otherwise count against
-// the spoke server's one per-IP limit at the hub. An Admin edit shows within
-// that window. The terms statement
-// links Terms, Privacy Policy and Working Agreement from a page-built map —
-// a magnet label can name a link key, never an href.
+// The form (#8661 D6, #8847 D7), first usable wins: the workspace's Contact
+// form magnet (`flows.get("contact")`, the public flow read — the API
+// resolves the workspace, the site alias keyless and a spoke by its key);
+// else the page's `contact-form` section fields when it declares any; else
+// the built-in form: the seeded magnet's own config, its name, email and
+// message labels from the `contact` catalog. Every visible fact on the page
+// comes from the magnet (#8847): its field step's title is the page's H1 and
+// `<title>`, its body the line under it (`framedSources`), and its ending
+// the success message. The built-in config stands in when the hub cannot be
+// read, so a fresh deploy looks the same either way. The section's own
+// `successMessage` and `submitLabel` apply only when its own fields are
+// used. A magnet-driven post is stamped `source: "flow:contact"`, so it is
+// an Inbox submission of the Contact form; the other two post as
+// `contact-form` (#8747). The page is rendered on every request, but its two
+// hub reads (the magnet and the capture status) are shared across requests
+// for HUB_READ_TTL_MS (`lib/in-page-magnet.ts`, #8731). The terms statement
+// links Terms and Privacy Policy from a page-built map — a magnet label can
+// name a link key, never an href. Under the form, "Prefer email?" and the
+// `_site.mdx` contact email, when the site has one.
 //
 // A `contact-form` section in the `column` variant (the minimalism Contact
 // page, #8661 D12) gets the stacked form look and a Send that stays enabled,
@@ -35,7 +38,6 @@
 // The chat-style intake (ConversationalIntakeWrapper, #4534) remains
 // available to a site that prefers it. JSON-LD and translations handled by
 // renderPage.
-import { flows, leads } from "@working-theory/api-client";
 import type {
   getMdxSource as defaultGetMdxSource,
   getPageSections as defaultGetPageSections,
@@ -53,22 +55,30 @@ import {
   type LeadCaptureFormText,
   localeHref,
 } from "@working-theory/ui";
+import { Link, Text } from "@working-theory/ui/primitives";
 import {
   CONTACT_FORM_FLOW_SLUG,
   contactFormFlowConfig,
   flowLeadSource,
-  type FlowConfig,
 } from "@working-theory/validation";
 import type { Metadata } from "next";
 import { getTranslations } from "next-intl/server";
 import type { ReactElement } from "react";
 
-import { contactFormFromConfig } from "./contact-form-magnet";
+import {
+  framedSources,
+  inPageView,
+  readCaptureStatus,
+  readServedMagnet,
+  type InPageView,
+} from "../../../lib/in-page-magnet";
+
+import { contactFormFromConfig, type ContactFormView } from "./contact-form-magnet";
 import { contactFormText } from "./contact-form-text";
 import { captureLeadAction } from "./contact.actions";
 import { readSiteContactEmail } from "./site-contact-email";
 
-// #8661 D6 — rendered on every request; the magnet read behind it is shared for HUB_READ_TTL_MS (#8731).
+// #8661 D6 — rendered on every request; the magnet read behind it is shared for HUB_READ_TTL_MS (#8731, lib/in-page-magnet.ts).
 export const dynamic = "force-dynamic";
 
 interface Props {
@@ -77,11 +87,6 @@ interface Props {
   getPageSections?: typeof defaultGetPageSections;
 }
 
-type CaptureStatus = Extract<
-  Awaited<ReturnType<typeof leads.captureStatus>>,
-  { ok: true }
->["body"]["data"];
-
 type Section = Awaited<ReturnType<typeof defaultGetPageSections>>[number];
 type ContactFormSection = Extract<Section, { type: "contact-form" }>;
 
@@ -118,63 +123,43 @@ function builtInFields(text: LeadCaptureFormText, locale: string): ContactFormFi
 }
 
 /**
- * How long the two hub reads are shared across requests (#8731). Short, so an
- * Admin edit to the magnet shows within seconds; long enough that a burst of
- * views makes one read of each, not one per view.
- */
-const HUB_READ_TTL_MS = 15_000;
-
-const hubReads = new Map<string, { at: number; read: Promise<unknown> }>();
-
-/**
- * `read()`'s result, shared per instance for HUB_READ_TTL_MS. Concurrent calls
- * share one in-flight read. A read that settles to `null` (any failed read,
- * see the two readers below) is shared the same way, so a burst against an
- * unreachable hub is not a burst of retries.
- */
-function sharedHubRead<T>(key: string, read: () => Promise<T>): Promise<T> {
-  const now = Date.now();
-  const hit = hubReads.get(key);
-  if (hit && now - hit.at < HUB_READ_TTL_MS) return hit.read as Promise<T>;
-  const fresh = read();
-  hubReads.set(key, { at: now, read: fresh });
-  return fresh;
-}
-
-/** The API's capture status, or `null` for any failed read (see header). */
-function readCaptureStatus(): Promise<CaptureStatus | null> {
-  return sharedHubRead("capture-status", async () => {
-    try {
-      const res = await leads.captureStatus();
-      return res.ok && res.body.ok === true ? res.body.data : null;
-    } catch {
-      return null;
-    }
-  });
-}
-
-/**
- * The served Contact form magnet's config, or `null` for any failed read: a
- * non-2xx (absent, draft, a build with no flow route) or a throw. The
- * property access sits inside the `try`, so a client with no `flows` is a
- * failed read too.
+ * The page's view of the Contact form (#8847 D7): the served magnet's when it
+ * maps, else the built-in config's. `served` says which.
  */
-function readContactMagnet(): Promise<FlowConfig | null> {
-  return sharedHubRead("contact-magnet", async () => {
-    try {
-      const res = await flows.get(CONTACT_FORM_FLOW_SLUG);
-      return res.ok ? res.body : null;
-    } catch {
-      return null;
-    }
-  });
+async function contactView(
+  locale: string,
+  fallbackHeadline: string,
+): Promise<{ view: InPageView; served: boolean }> {
+  const magnet = await readServedMagnet(CONTACT_FORM_FLOW_SLUG);
+  const served = magnet ? inPageView(magnet, locale, "contact", fallbackHeadline) : null;
+  if (served) return { view: served, served: true };
+  // The built-in config always maps: its first step has name and email.
+  return {
+    view: inPageView(contactFormFlowConfig, locale, "contact", fallbackHeadline)!,
+    served: false,
+  };
 }
 
 export async function generateMetadata({
   params,
-}: Pick<Props, "params">): Promise<Metadata> {
+  getMdxSource,
+  getPageSections,
+}: Props): Promise<Metadata> {
   const { locale } = await params;
-  return renderPageMetadata({ type: "ContactPage", slug: "contact", locale });
+  const t = await getTranslations({ locale, namespace: "contact" });
+  const { view } = await contactView(locale, t("successMessage"));
+  // #8847 D7 — the `<title>` is the magnet's step title, like the H1.
+  const framed = framedSources({
+    getMdxSource: getMdxSource ?? loadMdxSource,
+    getPageSections: getPageSections ?? loadPageSections,
+    view,
+  });
+  return renderPageMetadata({
+    type: "ContactPage",
+    slug: "contact",
+    locale,
+    getMdxSource: framed.getMdxSource,
+  });
 }
 
 export default async function Page({
@@ -183,17 +168,22 @@ export default async function Page({
   getPageSections,
 }: Props): Promise<ReactElement> {
   const { locale } = await params;
-  const [status, t, magnet] = await Promise.all([
+  const [status, t] = await Promise.all([
     readCaptureStatus(),
     getTranslations({ locale, namespace: "contact" }),
-    readContactMagnet(),
   ]);
   const accepting = status?.contact ?? true;
   const contactEmail = readSiteContactEmail();
   const text = contactFormText(t);
+  const { view, served } = await contactView(locale, text.success);
+  const framed = framedSources({
+    getMdxSource: getMdxSource ?? loadMdxSource,
+    getPageSections: getPageSections ?? loadPageSections,
+    view,
+  });
 
-  const source = await (getMdxSource ?? loadMdxSource)("ContactPage", "contact", locale);
-  const sections = source ? await (getPageSections ?? loadPageSections)(source.frontmatter) : [];
+  const source = await framed.getMdxSource("ContactPage", "contact", locale);
+  const sections = source ? await framed.getPageSections(source.frontmatter) : [];
   const formSection = sections.find(
     (s): s is ContactFormSection => s.type === "contact-form",
   );
@@ -205,19 +195,23 @@ export default async function Page({
     (lead?.type === "hero" && lead.data.variant === "split" ? lead.id : undefined);
 
   // #8661 D6 — the magnet's fields, else the section's, else the built-in form.
-  const served = magnet ? contactFormFromConfig(magnet, locale) : null;
-  const declared = formSection && formSection.data.fields.length > 0 ? formSection : undefined;
-  const fields: ContactFormField[] =
-    served?.fields ?? (declared ? sectionFields(declared) : builtInFields(text, locale));
-  // A magnet's own submit label wins; the section's copy fills what it leaves.
-  const submitLabel = served?.submitLabel ?? formSection?.data.submitLabel;
-  const successMessage = formSection?.data.successMessage;
+  const form = view.form as ContactFormView;
+  const declared =
+    !served && formSection && formSection.data.fields.length > 0 ? formSection : undefined;
+  const fields: ContactFormField[] = served
+    ? form.fields
+    : declared
+      ? sectionFields(declared)
+      : builtInFields(text, locale);
+  // #8847 D7 — the section's submit label and success message apply only to
+  // its own fields; otherwise the magnet's (or the built-in config's) ending.
+  const submitLabel = served ? form.submitLabel : declared?.data.submitLabel;
   const column = formSection?.data.variant === "column";
 
-  const surface = accepting ? (
+  const leadForm = accepting ? (
     <LeadCaptureForm
       action={captureLeadAction}
-      text={served?.consentStatement ? { ...text, consentStatement: served.consentStatement } : text}
+      text={served && form.consentStatement ? { ...text, consentStatement: form.consentStatement } : text}
       termsHref={localeHref(locale, "/terms")}
       policies={{
         terms: localeHref(locale, "/terms"),
@@ -227,7 +221,7 @@ export default async function Page({
       fallbackEmail={fallbackEmail}
       fields={fields}
       submitLabel={submitLabel}
-      successMessage={successMessage}
+      {...(declared ? { successMessage: declared.data.successMessage } : { ending: view.ending })}
       {...(served && { source: flowLeadSource(CONTACT_FORM_FLOW_SLUG) })}
       {...(column && { look: "column" as const, consentGate: "on-submit" as const })}
     />
@@ -241,14 +235,27 @@ export default async function Page({
       }}
     />
   );
+  // #8847 D7 — one muted line under the form; absent with no address.
+  const surface = (
+    <>
+      {leadForm}
+      {contactEmail !== undefined && (
+        <div className="mt-block-tight text-center" data-testid="contact-prefer-email">
+          <Text tone="muted" variant="body-sm">
+            {t("preferEmail")} <Link href={`mailto:${contactEmail}`}>{contactEmail}</Link>
+          </Text>
+        </div>
+      )}
+    </>
+  );
 
   const rendered = await renderPage({
     type: "ContactPage",
     slug: "contact",
     locale,
     translationsNamespace: "contact",
-    ...(getMdxSource !== undefined && { getMdxSource }),
-    ...(getPageSections !== undefined && { getPageSections }),
+    getMdxSource: framed.getMdxSource,
+    getPageSections: framed.getPageSections,
     ...(slotted !== undefined && { sectionSlots: { [slotted]: surface } }),
   });
   return (