create-ailk 0.11.2 → 0.11.4

package/templates/apps/web/app/[locale]/(authed)/account/account-data.ts

@@ -0,0 +1,183 @@
+/**
+ * account-data.ts — the base account area's server reads (#7430, spec 7423
+ * U4 · D6a, D8, D9, D12).
+ *
+ * One module the layout (the For-you aside), the Inbox and the item detail
+ * share, so every page reads the contributions in `lib/account-config.ts`
+ * the same way:
+ *
+ *   - `accountSession(locale)` — the `AccountContext` every contribution
+ *     receives (locale, the session's person, the `account` translator and
+ *     the caller's forwarded cookie), or `null` with no session.
+ *   - `loadInboxItems(ctx)` — every kind's items, newest first, with
+ *     `failed` set when any kind's read rejected (D12: the Inbox then shows
+ *     an error row with Retry, never a silently partial or empty list).
+ *   - `loadForYou(locale)` — every For-you source's items plus the area's own
+ *     "Add your name" item (an accepted applicant arrives with no name,
+ *     #7418), with the same `failed` flag.
+ *
+ * `cache()` dedupes the reads within one request: the layout's aside and the
+ * Inbox's phone For you tab render the same items from one set of API calls.
+ */
+
+import type {
+  AccountContext,
+  AccountInboxItem,
+  AccountInboxKind,
+  AccountTranslate,
+  ForYouItem,
+} from "@working-theory/templates/account";
+import { localeHref } from "@working-theory/ui";
+import { Icon } from "@working-theory/ui/primitives";
+import { UserRound } from "lucide-react";
+import { headers } from "next/headers";
+import { getTranslations } from "next-intl/server";
+import { cache, createElement } from "react";
+
+import { auth } from "../../../../auth";
+import { accountForYouSources, accountInboxKinds } from "../../../../lib/account-config";
+import { forwardedCookieInit } from "../../../../lib/server-api";
+
+/** The session's person, plus what the frame shows beyond the contract. */
+export interface AccountSession {
+  ctx: AccountContext;
+  /** ISO-8601 time the person's account was created, when the session carries it. */
+  createdAt?: string | undefined;
+}
+
+/** The `AccountContext` for this request, or `null` when there is no session. */
+export const accountSession = cache(
+  async (locale: string): Promise<AccountSession | null> => {
+    const session = await auth.api.getSession({ headers: await headers() });
+    if (!session) return null;
+    // The contract's translator takes any key: a contribution's keys (a
+    // kind's `label`, a section's `title`) are data, which next-intl's
+    // literal-key typing cannot see. The runtime call is the same function.
+    const t = (await getTranslations({ locale, namespace: "account" })) as unknown as AccountTranslate;
+    const { name, email, emailVerified, createdAt } = session.user as {
+      name?: string | null;
+      email: string;
+      emailVerified: boolean;
+      createdAt?: Date | string | null;
+    };
+    return {
+      ctx: {
+        locale,
+        user: { name: name ? name : null, email, emailVerified },
+        t,
+        init: await forwardedCookieInit(),
+      },
+      ...(createdAt ? { createdAt: new Date(createdAt).toISOString() } : {}),
+    };
+  },
+);
+
+/**
+ * Logs a failed contribution read, PII-safe (`err.name` only — the
+ * `actions.ts` idiom): the person sees the error row; the operator sees why.
+ */
+export function logReadFailure(source: string, err: unknown): void {
+  console.error(
+    `[account] read failed source=${source} errName=${err instanceof Error ? err.name : "unknown"}`,
+  );
+}
+
+/** The detail route of one Inbox item. */
+export function inboxItemHref(locale: string, kind: string, id: string): string {
+  return localeHref(
+    locale,
+    `/account/inbox/${encodeURIComponent(kind)}/${encodeURIComponent(id)}`,
+  );
+}
+
+// ── Inbox rows ───────────────────────────────────────────────────────────────
+
+/** One loaded item with the kind it came from — what a tab's row is built from. */
+export interface LoadedInboxItem {
+  kind: AccountInboxKind;
+  item: AccountInboxItem;
+}
+
+export interface LoadedInbox {
+  items: LoadedInboxItem[];
+  /** True when any kind's read rejected (D12). */
+  failed: boolean;
+}
+
+const newestFirst = (a: LoadedInboxItem, b: LoadedInboxItem): number =>
+  (b.item.at ?? "").localeCompare(a.item.at ?? "");
+
+/** Every kind's items, newest first. A rejected kind sets `failed`. */
+export async function loadInboxItems(ctx: AccountContext): Promise<LoadedInbox> {
+  const settled = await Promise.allSettled(
+    accountInboxKinds.map(async (kind) =>
+      (await kind.load(ctx)).map((item) => ({ kind, item })),
+    ),
+  );
+  settled.forEach((r, i) => {
+    if (r.status === "rejected") logReadFailure(`kind:${accountInboxKinds[i]!.kind}`, r.reason);
+  });
+  const items = settled.flatMap((r) => (r.status === "fulfilled" ? r.value : []));
+  return {
+    items: items.sort(newestFirst),
+    failed: settled.some((r) => r.status === "rejected"),
+  };
+}
+
+// ── For you ──────────────────────────────────────────────────────────────────
+
+export interface LoadedForYou {
+  items: ForYouItem[];
+  /** True when any source's read rejected (D12). */
+  failed: boolean;
+}
+
+/**
+ * The area's own For-you item: a member with no name is asked for one
+ * (operator fold-in 2026-10-01). It waits on them from the moment their
+ * account exists; with no creation time on the session, from now.
+ */
+function addNameItem(session: AccountSession, now: string): ForYouItem[] {
+  const { ctx } = session;
+  if (ctx.user.name) return [];
+  return [
+    {
+      id: "add-name",
+      type: {
+        id: "profile",
+        label: ctx.t("forYou.types.profile"),
+        // The tag's glyph (DESIGN.md §5.4c: icon + label). An element, not a
+        // component, so it crosses the server → client boundary.
+        icon: createElement(Icon, { icon: UserRound, size: "xs", decorative: true }),
+        tone: "needs-you",
+      },
+      title: ctx.t("forYou.addName"),
+      time: { kind: "waiting", at: session.createdAt ?? now },
+      action: { kind: "open", href: localeHref(ctx.locale, "/account/settings#general") },
+      dismissible: true,
+    },
+  ];
+}
+
+/** Every For-you source's items, plus the area's own. Deduped per request. */
+export const loadForYou = cache(
+  async (locale: string): Promise<LoadedForYou & { now: string }> => {
+    const now = new Date().toISOString();
+    const session = await accountSession(locale);
+    if (!session) return { items: [], failed: false, now };
+    const settled = await Promise.allSettled(
+      accountForYouSources.map((source) => source.load(session.ctx)),
+    );
+    settled.forEach((r, i) => {
+      if (r.status === "rejected") logReadFailure(`foryou:${accountForYouSources[i]!.id}`, r.reason);
+    });
+    return {
+      items: [
+        ...addNameItem(session, now),
+        ...settled.flatMap((r) => (r.status === "fulfilled" ? r.value : [])),
+      ],
+      failed: settled.some((r) => r.status === "rejected"),
+      now,
+    };
+  },
+);

package/templates/apps/web/app/[locale]/(authed)/account/account-frame.tsx

@@ -0,0 +1,169 @@
+"use client"; // the shell owns collapse state; sign-out is a client-side Better Auth call + router navigation
+
+/**
+ * AccountFrame — the account area's SignedInShell composition (#7430, spec
+ * 7423 D13; DESIGN.md §2b). The layout (an RSC) resolves the strings, the
+ * logo and the For-you items; this component wires them to the shell with
+ * what only the client has: the current path and the sign-out call.
+ *
+ * `createAuthClient()` at module scope is the `sign-in-gate.tsx` idiom. Log
+ * out ends the session, then navigates home and refreshes so every RSC under
+ * the `(authed)` gate re-reads the (now absent) session.
+ *
+ * #7469 (DESIGN.md §2b as amended 2026-10-01, matching the Admin's §5.15) —
+ * below `md` the bar reads avatar · Inbox · For you · Help, with no count
+ * on any tab. For you is a page of the Inbox route (`?tab=for-you`): the
+ * frame reads the URL and hands the tab to the page (`PhoneTabProvider`),
+ * which shows one panel per tab. At `md`+ nothing changes — For you stays
+ * the aside.
+ */
+
+import {
+  ForYouPanel,
+  PhoneTabProvider,
+  useForYouDismissed,
+  type ForYouItem,
+  type ForYouLabels,
+} from "@working-theory/templates/account";
+import {
+  SignedInShell,
+  type SignedInShellLabels,
+  type SignedInShellProps,
+} from "@working-theory/templates/shells";
+import { localeHref } from "@working-theory/ui";
+import { Link } from "@working-theory/ui/primitives";
+import { createAuthClient } from "better-auth/react";
+import { Inbox, Settings, Sparkles } from "lucide-react";
+import { usePathname, useRouter, useSearchParams } from "next/navigation";
+import type { ReactElement, ReactNode } from "react";
+
+import { ACCOUNT_PERSIST_KEY } from "./for-you-labels";
+
+const authClient = createAuthClient();
+
+/** The phone For you tab's `?tab=` value (#7469). */
+const FOR_YOU_TAB = "for-you";
+
+export interface AccountFrameLabels extends SignedInShellLabels {
+  /** The logo link's accessible name. */
+  home: string;
+  inbox: string;
+  /** The phone's For you tab label (#7469). */
+  forYou: string;
+  settings: string;
+}
+
+export interface AccountFrameProps {
+  locale: string;
+  user: { name: string; email: string };
+  /** The site's logo (the layout's `siteLogo()`), at most 32px tall. */
+  logo: ReactNode;
+  helpItems: NonNullable<SignedInShellProps["helpItems"]>;
+  forYou: { items: readonly ForYouItem[]; now: string; labels: ForYouLabels };
+  labels: AccountFrameLabels;
+  children: ReactNode;
+}
+
+export function AccountFrame({
+  locale,
+  user,
+  logo,
+  helpItems,
+  forYou,
+  labels,
+  children,
+}: AccountFrameProps): ReactElement {
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const [dismissed] = useForYouDismissed(ACCOUNT_PERSIST_KEY);
+
+  const homeHref = localeHref(locale, "/");
+  const inboxHref = localeHref(locale, "/account");
+  // The Inbox row stays selected on an item's own page (/account/inbox/…).
+  const onInbox = pathname === inboxHref || pathname.startsWith(`${inboxHref}/inbox/`);
+  // #7469 — the phone tab: For you only on the Inbox route itself.
+  const phoneTab =
+    pathname === inboxHref && searchParams?.get("tab") === FOR_YOU_TAB ? FOR_YOU_TAB : "inbox";
+
+  const onSignOut = (): void => {
+    void (async () => {
+      try {
+        await authClient.signOut();
+      } catch {
+        // The refresh below re-reads the session either way: a sign-out that
+        // failed lands the person back on a page that still knows them.
+      }
+      router.push(homeHref);
+      router.refresh();
+    })();
+  };
+
+  const { home, inbox, forYou: forYouLabel, settings, ...shellLabels } = labels;
+
+  // D13 — the logo only: no box, no name, no popover; it links home. The
+  // same link is the phone top bar's leading cell.
+  const logoLink = (
+    <Link
+      href={homeHref}
+      variant="unstyled"
+      aria-label={home}
+      className="flex h-8 max-h-8 items-center rounded-control focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-(--color-accent)"
+      data-testid="account-site-logo"
+    >
+      {logo}
+    </Link>
+  );
+
+  const forYouLeft = forYou.items.filter((item) => !dismissed.has(item.id));
+
+  return (
+    <SignedInShell
+      persistKey={ACCOUNT_PERSIST_KEY}
+      locale={locale}
+      navItems={[{ labelKey: "inbox", label: inbox, path: "/account", icon: Inbox }]}
+      tabItems={[
+        { key: "inbox", label: inbox, href: inboxHref, icon: Inbox, isActive: onInbox && phoneTab === "inbox" },
+        {
+          key: FOR_YOU_TAB,
+          label: forYouLabel,
+          href: `${inboxHref}?tab=${FOR_YOU_TAB}`,
+          icon: Sparkles,
+          isActive: phoneTab === FOR_YOU_TAB,
+        },
+      ]}
+      {...(onInbox ? { activePath: inboxHref } : {})}
+      user={user}
+      userMenuItems={[
+        {
+          id: "settings",
+          label: settings,
+          icon: Settings,
+          href: localeHref(locale, "/account/settings"),
+        },
+      ]}
+      onSignOut={onSignOut}
+      userDisplay="avatar"
+      accountMenuLayout="card"
+      helpItems={helpItems}
+      railHeader={logoLink}
+      topBarStart={logoLink}
+      {...(forYouLeft.length > 0
+        ? {
+            aside: (
+              <ForYouPanel
+                items={forYouLeft}
+                persistKey={ACCOUNT_PERSIST_KEY}
+                labels={forYou.labels}
+                locale={locale}
+                now={forYou.now}
+              />
+            ),
+          }
+        : {})}
+      labels={shellLabels}
+    >
+      <PhoneTabProvider tab={phoneTab}>{children}</PhoneTabProvider>
+    </SignedInShell>
+  );
+}

package/templates/apps/web/app/[locale]/(authed)/account/actions.ts

@@ -1,7 +1,9 @@
 "use server";
 
 /**
- * account/actions.ts — the update-your-card banner's Server Action (#6038,
+ * account/actions.ts — User settings › Billing's Server Action.
+ *
+ * `openBillingPortal` — User settings › Billing's Manage billing (#6038,
  * D5): mints a Stripe billing-portal session on SUBMIT, never on render, and
  * hands the browser straight to it via `redirect()`.
  *

package/templates/apps/web/app/[locale]/(authed)/account/error-row.tsx

@@ -0,0 +1,35 @@
+/**
+ * ErrorRow — the account area's "a read failed" row (#7430, spec 7423 D12):
+ * the message and a Retry control, inside the same bordered row box the
+ * Inbox list uses. Never an empty list in its place.
+ */
+
+import { RowGroup } from "@working-theory/ui/blocks";
+import { InlineMessage } from "@working-theory/ui/primitives";
+import type { ReactElement } from "react";
+
+import { RetryButton } from "./retry-button";
+
+export function ErrorRow({
+  message,
+  retryLabel,
+  className,
+}: {
+  message: string;
+  retryLabel: string;
+  className?: string;
+}): ReactElement {
+  return (
+    <RowGroup aria-label={message} {...(className ? { className } : {})}>
+      <li
+        className="flex flex-wrap items-center justify-between gap-3 px-4 py-3"
+        data-testid="inbox-error"
+      >
+        <InlineMessage variant="error" className="text-body-sm">
+          {message}
+        </InlineMessage>
+        <RetryButton label={retryLabel} />
+      </li>
+    </RowGroup>
+  );
+}

package/templates/apps/web/app/[locale]/(authed)/account/for-you-labels.ts

@@ -0,0 +1,36 @@
+/**
+ * for-you-labels.ts — the For-you panel's strings from the `account`
+ * namespace (#7430, spec §5.2 i18n), and the frame's persist key. Shared by
+ * the layout's aside and the Inbox's phone For you tab.
+ */
+
+import type { AccountTranslate, ForYouLabels } from "@working-theory/templates/account";
+
+/**
+ * The account frame's `persistKey`: the shell's remembered collapse
+ * (`ailk:shell:account:*`) and the For-you dismissals
+ * (`ailk:account:foryou:dismissed`), shared by the aside and the Inbox's
+ * phone For you tab so a dismissal holds on both.
+ */
+export const ACCOUNT_PERSIST_KEY = "account";
+
+export function forYouLabels(t: AccountTranslate): ForYouLabels {
+  return {
+    title: t("forYou.title"),
+    filter: t("forYou.filter"),
+    allTypes: t("forYou.allTypes"),
+    sort: t("forYou.sort"),
+    mostRelevant: t("forYou.mostRelevant"),
+    mostRecent: t("forYou.mostRecent"),
+    view: t("forYou.view"),
+    open: t("forYou.open"),
+    dismiss: t("forYou.dismiss"),
+    whyItMatters: t("forYou.whyItMatters"),
+    expectedOutcome: t("forYou.expectedOutcome"),
+    // The panel fills `{duration}` itself, so the placeholder passes through.
+    waiting: t("forYou.waiting", { duration: "{duration}" }),
+    empty: t("forYou.empty"),
+    showAll: t("forYou.showAll"),
+    close: t("forYou.close"),
+  };
+}

package/templates/apps/web/app/[locale]/(authed)/account/inbox/[kind]/[id]/page.tsx

@@ -0,0 +1,96 @@
+/**
+ * /[locale]/account/inbox/[kind]/[id] — one Inbox item (#7430, spec 7423 U4;
+ * the D8 detail contract).
+ *
+ * RSC, inside the account layout's SignedInShell (the rail keeps Inbox
+ * selected here). The item is found the way the contract says: its kind's
+ * `load` runs again and the `[id]` is matched — so the page shows only what
+ * the caller's own reads return. The kind's `renderDetail` fills the shared
+ * `InboxItemFrame`; the area supplies the back link, the caption (the kind's
+ * label) and the title, so every kind's detail reads as one frame.
+ *
+ * An unknown kind, or an id the kind did not load, is a not-found — never an
+ * empty frame. A failed read is not a not-found: it renders an error with
+ * Retry (D12's posture).
+ */
+
+import { InboxItemFrame } from "@working-theory/templates/account";
+import { localeHref } from "@working-theory/ui";
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import type { ReactElement } from "react";
+
+import { accountInboxKinds } from "../../../../../../../lib/account-config";
+import { accountSession, logReadFailure } from "../../../account-data";
+import { ErrorRow } from "../../../error-row";
+
+interface Props {
+  params: Promise<{ locale: string; kind: string; id: string }>;
+}
+
+/**
+ * A segment, percent-decoded when it decodes. The route param is matched in
+ * both forms (`matches` below), so an id is found whether or not the
+ * framework already decoded it — and an id that itself contains `%XX` still
+ * matches its raw form.
+ */
+function decodeSegment(segment: string): string {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const t = await getTranslations({ locale, namespace: "account" });
+  return { title: t("inbox.title") };
+}
+
+export default async function AccountInboxItemPage({ params }: Props): Promise<ReactElement> {
+  const { locale, kind: kindSegment, id: idSegment } = await params;
+  const matches = (value: string, segment: string): boolean =>
+    value === segment || value === decodeSegment(segment);
+  const kind = accountInboxKinds.find((k) => matches(k.kind, kindSegment));
+  if (!kind) notFound();
+
+  const t = await getTranslations({ locale, namespace: "account" });
+  const session = await accountSession(locale);
+  if (!session) notFound();
+
+  const back = { href: localeHref(locale, "/account"), label: t("inbox.back") };
+
+  let items;
+  try {
+    items = await kind.load(session.ctx);
+  } catch (err) {
+    logReadFailure(`kind:${kind.kind}`, err);
+    return (
+      <div className="max-w-3xl py-8" data-testid="account-item">
+        <ErrorRow message={t("inbox.itemError")} retryLabel={t("inbox.retry")} />
+      </div>
+    );
+  }
+
+  const item = items.find((candidate) => matches(candidate.id, idSegment));
+  if (!item) notFound();
+
+  const detail = kind.renderDetail(item, session.ctx);
+
+  return (
+    <InboxItemFrame
+      back={back}
+      caption={session.ctx.t(kind.label)}
+      title={item.title}
+      lead={detail.lead}
+      status={detail.status}
+      {...(detail.actions ? { actions: detail.actions } : {})}
+      fields={detail.fields}
+      testIdPrefix="account-item"
+    >
+      {detail.body}
+    </InboxItemFrame>
+  );
+}

package/templates/apps/web/app/[locale]/(authed)/account/layout.tsx

@@ -0,0 +1,89 @@
+/**
+ * The account layout — the base account area's frame (#7430, spec 7423 U4 ·
+ * D4, D13; DESIGN.md §2b).
+ *
+ * RSC. Every `/account` route renders inside `SignedInShell` (through the
+ * client `AccountFrame`): the site's logo as the rail's top tile, linking
+ * home; Inbox as the rail's only row; a footer of the avatar and ? alone;
+ * the card avatar menu (name, then Settings and Log out); the ? help menu
+ * (Contact support, and Help center when `AILK_HELP_CENTER_URL` is set);
+ * and below `md` a tab bar reading avatar · Inbox · For you · Help (#7469).
+ * The locale layout renders no marketing frame and no consent Banner on
+ * these paths (D4, `isAccountPath`).
+ *
+ * The aside is the For-you panel, fed by `accountForYouSources` plus the
+ * area's own "Add your name" item (`loadForYou`, deduped per request with
+ * the Inbox's phone For you tab); with no items there is no aside.
+ *
+ * The `(authed)` layout above owns the signed-out gate, so a missing session
+ * here is a race (it expired between the two layouts): the page renders
+ * unframed and degrades on its own.
+ */
+
+import { localeHref } from "@working-theory/ui";
+import { getTranslations } from "next-intl/server";
+import type { ReactElement, ReactNode } from "react";
+
+import { siteLogo } from "../../../../lib/site-logo";
+
+import { accountSession, loadForYou } from "./account-data";
+import { AccountFrame } from "./account-frame";
+import { forYouLabels } from "./for-you-labels";
+
+interface Props {
+  children: ReactNode;
+  params: Promise<{ locale: string }>;
+}
+
+export default async function AccountLayout({
+  children,
+  params,
+}: Props): Promise<ReactElement> {
+  const { locale } = await params;
+  const session = await accountSession(locale);
+  if (!session) return <>{children}</>;
+
+  const t = await getTranslations({ locale, namespace: "account" });
+  const forYou = await loadForYou(locale);
+  const { name, email } = session.ctx.user;
+  const helpCenterUrl = process.env.AILK_HELP_CENTER_URL;
+
+  return (
+    <AccountFrame
+      locale={locale}
+      user={{ name: name ?? email, email }}
+      logo={siteLogo()}
+      helpItems={[
+        {
+          id: "support",
+          label: t("frame.contactSupport"),
+          href: localeHref(locale, "/account/support"),
+        },
+        ...(helpCenterUrl
+          ? [{ id: "help-center", label: t("frame.helpCenter"), href: helpCenterUrl }]
+          : []),
+      ]}
+      forYou={{ items: forYou.items, now: forYou.now, labels: forYouLabels(session.ctx.t) }}
+      labels={{
+        home: t("frame.home"),
+        inbox: t("frame.inbox"),
+        forYou: t("frame.forYou"),
+        settings: t("frame.settings"),
+        signOut: t("frame.signOut"),
+        help: t("frame.help"),
+        accountMenu: t("frame.accountMenu"),
+        tabBar: t("frame.tabBar"),
+        sidebar: t("frame.sidebar"),
+        collapseSidebar: t("frame.collapseSidebar"),
+        expandSidebar: t("frame.expandSidebar"),
+        collapseAside: t("frame.collapseAside"),
+        expandAside: t("frame.expandAside"),
+        aside: t("forYou.title"),
+        openAside: t("frame.openAside"),
+        closeAside: t("frame.closeAside"),
+      }}
+    >
+      {children}
+    </AccountFrame>
+  );
+}