@forgecart/cli 2.202610141948.0 → 2.202610150140.0

package/templates/storefront/src/lib/seo/noindex.ts

@@ -31,6 +31,10 @@ import { getPublicOrigin } from './public-origin';
  * no content of its own, identical for every visitor, so there is nothing for a
  * search result to be about. One entry covers every language: this set is
  * matched against the locale-STRIPPED path.
+ *
+ * `/account` (#1093) is here for the same funnel reason as `/register`: the
+ * server renders a skeleton, identical for every visitor, and everything the
+ * page shows is one shopper's own — sign-in form or greeting.
  */
 export const NOINDEX_PATHS: readonly string[] = [
   '/cart',
@@ -38,6 +42,7 @@ export const NOINDEX_PATHS: readonly string[] = [
   '/verify',
   '/reset-password',
   '/register',
+  '/account',
 ];
 
 /**

package/templates/storefront/src/lib/seo/sitemap-entries.ts

@@ -49,6 +49,8 @@ export const STATIC_ROUTES: readonly StaticRoute[] = [
   // The register page (#1471). Suppressed for the same reason `/cart` is — a
   // form with no content of its own — and listed for this table's stated one.
   { path: '/register', indexable: false },
+  // The account page (#1093): sign-in form or greeting, one shopper's own.
+  { path: '/account', indexable: false },
 ];
 
 /**

package/templates/storefront/src/lib/shop-session.ts

@@ -29,6 +29,10 @@ import { syncShopSession } from './session-actions';
  *     it from result extensions on the first mutation) is synced back into
  *     BOTH cookies via the `syncShopSession` server action — the next SSR
  *     pass sees the cart this socket built.
+ *   - A sign-in or sign-out changes WHO the session is, and that never rides
+ *     the capture: `replaceShopSession(token)` disposes the socket, opens a
+ *     fresh one on the new session (or none) and writes both cookies before
+ *     it resolves (`lib/account-session.ts` is its caller).
  *
  * Every operation returns the same `ActionResult` envelope the old Server
  * Actions used, so calling components keep their error contract: typed
@@ -96,6 +100,24 @@ export function isSessionReady(): boolean {
   return config !== null && typeof window !== 'undefined';
 }
 
+/** A client on the channel coordinates, carrying `token` — or no session when null. */
+function openClient(coordinates: ShopSessionConfig, token: string | null): ForgeCartShopClient {
+  const opened = new ForgeCartShopClient({
+    endpoint: coordinates.apiUrl,
+    channelToken: coordinates.channelToken,
+    // Fixed at handshake — the cart, checkout and every error message on
+    // this socket answer in the language the URL resolved to.
+    languageCode: coordinates.languageCode,
+    // The visitor mirror is minted by the middleware before any page can
+    // mount the provider, so it is present on every real navigation; when
+    // it is somehow absent the client simply sends no visitor header and
+    // visitor-subject goals stay unstamped (never guess — #1079).
+    visitorId: readMirrorCookie(VISITOR_MIRROR_COOKIE) ?? undefined,
+  });
+  if (token) opened.setAuthToken(token);
+  return opened;
+}
+
 function ensureClient(): ForgeCartShopClient {
   if (!config) {
     throw new Error(
@@ -103,32 +125,63 @@ function ensureClient(): ForgeCartShopClient {
     );
   }
   if (!client) {
-    client = new ForgeCartShopClient({
-      endpoint: config.apiUrl,
-      channelToken: config.channelToken,
-      // Fixed at handshake — the cart, checkout and every error message on
-      // this socket answer in the language the URL resolved to.
-      languageCode: config.languageCode,
-      // The visitor mirror is minted by the middleware before any page can
-      // mount the provider, so it is present on every real navigation; when
-      // it is somehow absent the client simply sends no visitor header and
-      // visitor-subject goals stay unstamped (never guess — #1079).
-      visitorId: readMirrorCookie(VISITOR_MIRROR_COOKIE) ?? undefined,
-    });
     const existing = readMirrorSession();
-    if (existing) {
-      client.setAuthToken(existing);
-      syncedToken = existing;
-    }
+    client = openClient(config, existing);
+    if (existing) syncedToken = existing;
   }
   return client;
 }
 
+/**
+ * Move this tab onto another session — the ONE path an identity change takes
+ * (#1093): a sign-in hands over the session it minted, a sign-out hands over
+ * `null`.
+ *
+ * The socket is REPLACED, never re-pointed. Its identity was fixed at its
+ * handshake, and a sign-in that left the live socket speaking for the session
+ * it opened with was refused UNAUTHORIZED on its very next operation — the
+ * greeting — and rendered as a failed sign-in (#1089). So the old client is
+ * disposed, which is terminal (nothing still in flight on it can complete
+ * under the wrong identity), and a fresh one carrying `token` takes its place;
+ * its first operation handshakes as the new session. The platform now rebinds
+ * a connection that signs in, and the SDK re-handshakes on `setAuthToken`; the
+ * replacement stays regardless, so which identity every later operation runs
+ * under is a fact of this module rather than of the platform and SDK versions
+ * a workspace happens to run.
+ *
+ * A sign-out also clears the token the SDK persists in the browser's storage.
+ * A fresh client restores that token when it is constructed, so without the
+ * clear the replacement would carry the very session it was meant to leave.
+ *
+ * Both cookies are written next, and AWAITED — unlike the capture in
+ * `runSessionOp` — so a caller that resolves after this has left the next
+ * server render and the next visit's socket on the same session as this tab.
+ * A failed write is absorbed exactly as the capture absorbs one: the socket
+ * is the authority for this tab, and a lost mirror costs the next visit its
+ * session, never this interaction.
+ *
+ * Before the cart provider has armed the singleton there is no socket to
+ * replace, and only the cookies move.
+ */
+export async function replaceShopSession(token: string | null): Promise<void> {
+  client?.dispose();
+  client = config ? openClient(config, token) : null;
+  if (token === null) client?.clearAuthToken();
+  syncedToken = token;
+  try {
+    await syncShopSession(token);
+  } catch {
+    // Absorbed by design — see above: the socket already carries `token`.
+  }
+}
+
 /**
  * Run one session operation on the shopper's socket and return the typed
  * envelope. Session capture: when the operation minted or rotated the
  * session, the new token is synced into the cookies fire-and-forget —
- * a sync failure never breaks the shopper's interaction.
+ * a sync failure never breaks the shopper's interaction. An operation whose
+ * socket was replaced while it ran captures nothing: its session is no longer
+ * this tab's, and writing it would undo the replacement.
  */
 export async function runSessionOp<T>(
   op: (client: ForgeCartShopClient) => Promise<T>,
@@ -140,7 +193,7 @@ export async function runSessionOp<T>(
   try {
     const data = await op(live);
     const token = live.getAuthToken();
-    if (token && token !== syncedToken) {
+    if (token && token !== syncedToken && live === client) {
       syncedToken = token;
       void syncShopSession(token).catch(() => undefined);
     }

package/templates/storefront-shadcn/README.md

@@ -155,10 +155,49 @@ defers its first flush so a fast add-to-cart wins the first-touch race. The
 mirror is what the browser's shop socket boots its auth from: written without
 it, a relay-established session would never reach the client at all.
 
+## Customer account
+
+The scaffold ships the shopper's account surface, so a store starts with
+sign-in, sign-out and registration working — extend it rather than rebuild it:
+
+| Route       | What it does                                                 |
+| ----------- | ------------------------------------------------------------ |
+| `/account`  | signs a shopper in, greets them by name, signs them out      |
+| `/register` | creates an account; its confirmation mail links to `/verify` |
+
+The header links `/account`, the footer `/register`. Five rules keep it
+working — each one was learned from a store that broke it:
+
+- **Account pages are static shells.**
+  [`src/app/account/page.tsx`](src/app/account/page.tsx) reads no session on
+  the server — no `next/headers`, no `connection()`, no session module. The
+  session lives on the shopper's own socket, in the `AccountPanel` client
+  island, which waits for the `CartProvider` to arm it (`useCart().hydrated`).
+  A session read on the server path throws during the render and 500s the page.
+- **Sign in and out only through the session helpers.** `loginCustomer` and
+  `logoutCustomer` ([`src/lib/account-session.ts`](src/lib/account-session.ts))
+  replace the socket with one carrying the new session (or none) and write both
+  session cookies before they resolve: a socket left on the session it opened
+  with refuses the very next call. `findSignedInCustomer` says who is signed in.
+- **Every refusal renders through `shopperMessage`**
+  ([`src/lib/error-messages.ts`](src/lib/error-messages.ts)): it has copy for
+  every account refusal the shop API answers, and appends the raw code to its
+  generic line for any code it does not know. A new refusal's copy goes there,
+  once.
+- **Registration requires the password.** The API treats it as optional, and an
+  account registered without one can never sign in.
+- **`lib/shop-config` is server-only**, so no client component imports it, and
+  **the header links only routes the template ships**.
+
+A store scaffolded before the surface shipped adopts it with `forgecart
+refresh`: the account files it never had are rendered, the files it never
+edited are replaced, and a file it edited — its `Header.tsx`, say — is reported
+as a conflict and left as it is.
+
 ## Account links
 
 Two routes exist because the PLATFORM links to them from the e-mails it sends
-a shopper, not because anything in this storefront navigates there:
+a shopper:
 
 | Route                        | Mail                | What it does                                                 |
 | ---------------------------- | ------------------- | ------------------------------------------------------------ |
@@ -194,11 +233,14 @@ src/
     cart-actions.ts      # cart Server Actions (incl. coupons)
     checkout-actions.ts  # checkout Server Actions
     cart-context.tsx     # client cart state + typed error channel
-    account-actions.ts   # password-reset Server Actions
-    account/             # pure account-link rules (token, states, ErrorCode map)
+    shop-session.ts      # the shopper's own socket + session cookie sync
+    account-session.ts   # register, sign-in, sign-out on that socket
+    account-actions.ts   # password-reset + verification-resend Server Actions
+    account/             # pure account rules (token, states, ErrorCode map)
+    error-messages.ts    # shopper copy for every typed error code
   components/
     ui/                  # the vendored shadcn/ui components + their cn helper
-    Header.tsx           # top nav with live cart count
+    Header.tsx           # top nav (Home / Products / Cart / Account) + cart count
     ProductCard.tsx      # product tile
     ProductPurchase.tsx  # variant picker + purchase options + add-to-cart
     CartView.tsx         # cart lines, coupons, totals, checkout CTA
@@ -208,7 +250,10 @@ src/
       RatesStep.tsx        # grouped radio-card rate selection
       PaymentFormEmbed.tsx # origin-checked hosted-form host
     account/
-      AccountMessage.tsx           # the one outcome block both account pages use
+      AccountPanel.tsx             # sign-in form, greeting, sign-out (/account)
+      RegisterForm.tsx             # create an account (/register)
+      VerificationResend.tsx       # send the confirmation mail again
+      AccountMessage.tsx           # the one outcome block the account pages use
       ResetPasswordForm.tsx        # set a new password from a reset token
       RequestPasswordResetForm.tsx # ask for a reset link
   app/
@@ -220,6 +265,8 @@ src/
     products/            # grid + [slug] detail
     cart/page.tsx        # cart
     checkout/page.tsx    # the stepped checkout
+    account/page.tsx     # sign-in + greeting: a static shell around AccountPanel
+    register/page.tsx    # create an account
     verify/page.tsx          # e-mail verification link target
     reset-password/page.tsx  # password-reset link target + request form
 ```

package/templates/storefront-shadcn/src/app/account/page.tsx

@@ -0,0 +1,51 @@
+import type { Metadata } from 'next';
+
+import { AccountPanel } from '../../components/account/AccountPanel';
+import { getRequestLocale } from '../../lib/locale/request-binding';
+import { routeMetadata } from '../../lib/seo/metadata';
+
+/**
+ * `/account` — where a shopper signs in, is greeted, and signs out (#1093).
+ *
+ * A STATIC SHELL, and that is the law this file exists to keep: the server
+ * reads no session here — no cookie, no `connection()`, no session module. A
+ * storefront agent once read the session on the server path; the render threw
+ * `EmptyError: no elements in sequence`, and the 500 made the promote gate roll
+ * back the whole changeset. The session is the shopper's, on their own socket:
+ * `AccountPanel` asks it in the browser, and the server paints the skeleton it
+ * starts from. `tool/storefront-template-spec` holds this file to that.
+ *
+ * Locale-prefixable like `/register` — a shopper addresses it from a link on
+ * this storefront, never out of a mail — so `account` is absent from the
+ * grammar's unprefixed set and `/de/account` serves the German render.
+ */
+
+const PAGE_TITLE = 'Your account';
+
+/**
+ * Noindex via `NOINDEX_PATHS`, and no alternates — for the reasons `/register`'s
+ * metadata states: one shopper's own page has nothing for a search result to be
+ * about, and a page that declines indexing has no preferred address to claim.
+ */
+export async function generateMetadata(): Promise<Metadata> {
+  const { binding, shopName, channelResolved } = await getRequestLocale();
+  return routeMetadata({
+    binding,
+    shopName,
+    channelResolved,
+    pathname: '/account',
+    pathsByLocale: {},
+    title: PAGE_TITLE,
+  });
+}
+
+export default async function AccountPage() {
+  const { binding } = await getRequestLocale();
+
+  return (
+    <div className="mx-auto max-w-xl space-y-6">
+      <h1 className="text-2xl font-bold tracking-tight">{PAGE_TITLE}</h1>
+      <AccountPanel locale={binding} />
+    </div>
+  );
+}

package/templates/storefront-shadcn/src/app/layout.tsx

@@ -149,11 +149,10 @@ export default async function RootLayout({ children }: { children: ReactNode })
                   >
                     Cart
                   </LocaleLink>
-                  {/* The only affordance for `/register` (#1471). It sits in the
-                      footer rather than the header nav on purpose: the template
-                      ships no sign-in surface yet, and an account entry in the
-                      primary nav would advertise an account AREA that does not
-                      exist. A merchant who adds sign-in moves it up. */}
+                  {/* The direct way to `/register` (#1471). The header's Account
+                      link (#1093) is the account entry — sign-in, with
+                      registration one link away — and this is the shortcut for
+                      a shopper who already knows they are new. */}
                   <LocaleLink
                     href="/register"
                     locale={binding}

package/templates/storefront-shadcn/src/app/verify/page.tsx

@@ -70,39 +70,51 @@ export async function generateMetadata(): Promise<Metadata> {
  * first thing a rebrand rewrites, while the state set is the contract.
  */
 
-/** What each outcome tells the shopper, and where it sends them next. */
+/**
+ * What each outcome tells the shopper, and where it sends them next. A verified
+ * account's next step is signing in (#1093), so that state links the account
+ * page; every other state sends the shopper back to the store.
+ */
 const VERIFY_COPY: Readonly<
-  Record<VerifyState, { tone: AccountMessageTone; title: string; body: string; cta: string }>
+  Record<
+    VerifyState,
+    { tone: AccountMessageTone; title: string; body: string; cta: string; href: string }
+  >
 > = {
   verified: {
     tone: 'success',
     title: 'Your e-mail address is verified',
     body: 'Your account is ready — you can sign in with the address you registered.',
-    cta: 'Start shopping',
+    cta: 'Sign in',
+    href: '/account',
   },
   'no-token': {
     tone: 'warning',
     title: 'This link is missing its verification token',
     body: 'Open the link straight from the e-mail we sent you. It carries a one-time token this page needs, and copying only part of the address leaves it behind.',
     cta: 'Go to the store',
+    href: '/',
   },
   'link-invalid': {
     tone: 'warning',
     title: 'This verification link is no longer valid',
     body: 'It has either been used already or it has expired. If your account is still unverified, request a new verification e-mail and open the newest link.',
     cta: 'Go to the store',
+    href: '/',
   },
   'wrong-store': {
     tone: 'warning',
     title: 'This link belongs to a different store',
     body: 'The account it verifies does not shop here. Open the link from the e-mail that store sent you — every store sends its own.',
     cta: 'Go to the store',
+    href: '/',
   },
   failed: {
     tone: 'error',
     title: 'We could not verify your e-mail address',
     body: 'Something went wrong on our side. Please open the link again in a few minutes — and if it has stopped working by then, request a new verification e-mail.',
     cta: 'Go to the store',
+    href: '/',
   },
 };
 
@@ -140,7 +152,7 @@ async function VerifyOutcome({ searchParams }: { searchParams: Promise<RouteSear
       <AccountMessage tone={copy.tone} title={copy.title}>
         {copy.body}
       </AccountMessage>
-      <LocaleLink href="/" locale={binding} className={buttonVariants()}>
+      <LocaleLink href={copy.href} locale={binding} className={buttonVariants()}>
         {copy.cta}
       </LocaleLink>
     </div>

package/templates/storefront-shadcn/src/components/Header.tsx

@@ -21,7 +21,16 @@ export interface HeaderProps {
   languageCodes: readonly string[];
 }
 
-/** Top navigation: Home / Products / Cart, with a live cart item count. */
+/**
+ * Top navigation: Home / Products / Cart / Account, with a live cart item count.
+ *
+ * Every link names a route this template SHIPS (#1093): a link to a page the
+ * scaffold does not carry is a 404 for the shopper and a false lead for the
+ * agent extending the store, and `tool/storefront-template-spec` holds this
+ * file to it. The Account link is static — it never renders who is signed in —
+ * so nothing here depends on the session and no promote can trip a hydration
+ * mismatch on it; the account page itself says who is signed in.
+ */
 export function Header({ locale, languageCodes }: HeaderProps) {
   const { itemCount } = useCart();
 
@@ -65,6 +74,13 @@ export function Header({ locale, languageCodes }: HeaderProps) {
             Cart
             {mounted && itemCount > 0 && <Badge className="font-semibold">{itemCount}</Badge>}
           </LocaleLink>
+          <LocaleLink
+            href="/account"
+            locale={locale}
+            className={buttonVariants({ variant: 'ghost', size: 'sm' })}
+          >
+            Account
+          </LocaleLink>
           <LanguageSwitcher locale={locale} languageCodes={languageCodes} />
         </nav>
       </div>