@forgecart/cli 2.202610141948.0 → 2.202610142335.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgecart/cli",
-  "version": "2.202610141948.0",
+  "version": "2.202610142335.0",
   "type": "module",
   "description": "CLI for scaffolding and operating ForgeCart channel storefronts",
   "bin": {

package/templates/storefront/README.md

@@ -140,10 +140,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                                                 |
 | ---------------------------- | ------------------- | ------------------------------------------------------------ |
@@ -178,10 +217,13 @@ 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/
-    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
@@ -191,7 +233,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/
@@ -202,6 +247,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/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/src/app/layout.tsx

@@ -136,11 +136,10 @@ export default async function RootLayout({ children }: { children: ReactNode })
                 <LocaleLink href="/cart" locale={binding} className="link link-hover">
                   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} className="link link-hover">
                   Create account
                 </LocaleLink>

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

@@ -68,39 +68,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: '/',
   },
 };
 
@@ -138,7 +150,7 @@ async function VerifyOutcome({ searchParams }: { searchParams: Promise<RouteSear
       <AccountMessage tone={copy.tone} title={copy.title}>
         {copy.body}
       </AccountMessage>
-      <LocaleLink href="/" locale={binding} className="btn btn-primary">
+      <LocaleLink href={copy.href} locale={binding} className="btn btn-primary">
         {copy.cta}
       </LocaleLink>
     </div>

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

@@ -19,7 +19,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();
 
@@ -57,6 +66,9 @@ export function Header({ locale, languageCodes }: HeaderProps) {
               <span className="badge badge-primary badge-sm font-semibold">{itemCount}</span>
             )}
           </LocaleLink>
+          <LocaleLink href="/account" locale={locale} className="btn btn-ghost btn-sm">
+            Account
+          </LocaleLink>
           <LanguageSwitcher locale={locale} languageCodes={languageCodes} />
         </nav>
       </div>

package/templates/storefront/src/components/account/AccountPanel.tsx

@@ -0,0 +1,289 @@
+'use client';
+
+import type { NativeAuthInput } from '@forgecart/sdk/shop';
+import { useEffect, useState } from 'react';
+
+import { AccountMessage, type AccountMessageTone } from './AccountMessage';
+import { VerificationResend } from './VerificationResend';
+import { LocaleLink } from '../LocaleLink';
+import { findSignedInCustomer, loginCustomer, logoutCustomer } from '../../lib/account-session';
+import {
+  LOADING_VIEW,
+  greetingView,
+  offersVerificationResend,
+  signInRefusedView,
+  signInView,
+  signedOutView,
+  type AccountRefusal,
+  type AccountStep,
+  type AccountView,
+  type SignedInCustomer,
+} from '../../lib/account/account-state';
+import { useCart } from '../../lib/cart-context';
+import { shopperMessage } from '../../lib/error-messages';
+import type { LocaleBinding } from '../../lib/locale/localized-path';
+
+/**
+ * The account page's client island (#1093): the sign-in form, the greeting, and
+ * the way out.
+ *
+ * Everything here runs on the shopper's OWN socket, never on the server: the
+ * page around it is a static shell, because a session read on the server path
+ * threw `EmptyError: no elements in sequence` and 500'd the render. Signing in
+ * and out goes through `lib/account-session.ts`, whose helpers own the socket's
+ * rotation — a panel cannot get it wrong, because it never touches the socket.
+ *
+ * The island waits for the cart provider's `hydrated` before it asks anything.
+ * The provider is what arms the session singleton, and a parent's effects run
+ * AFTER its children's: an island that asked on its own mount would find no
+ * socket. Until then it renders the skeleton the server painted, so a returning
+ * customer lands on their greeting without a flash of the sign-in form first.
+ *
+ * Which view an answer IS is decided in `lib/account/account-state.ts`, and
+ * every refusal renders through `shopperMessage` — this component renders.
+ */
+
+/** How each call's refusal is introduced; the body is `shopperMessage`'s copy. */
+const REFUSAL_HEADINGS: Readonly<Record<AccountStep, { tone: AccountMessageTone; title: string }>> =
+  {
+    greeting: { tone: 'error', title: 'We could not check your account' },
+    'sign-in': { tone: 'error', title: 'We could not sign you in' },
+    'sign-out': { tone: 'warning', title: 'You are signed out on this device' },
+  };
+
+/** The message a refusal renders as, or nothing when the form has nothing to report. */
+function refusalNotice(
+  refusal: AccountRefusal | null,
+): { tone: AccountMessageTone; title: string; body: string } | null {
+  if (refusal === null) return null;
+  return { ...REFUSAL_HEADINGS[refusal.step], body: shopperMessage(refusal) };
+}
+
+export function AccountPanel({ locale }: { locale: LocaleBinding }) {
+  const { hydrated, refresh } = useCart();
+  const [view, setView] = useState<AccountView>(LOADING_VIEW);
+  const [refusedAddress, setRefusedAddress] = useState('');
+  const [pending, setPending] = useState(false);
+
+  useEffect(() => {
+    if (!hydrated) return;
+    let cancelled = false;
+    void (async () => {
+      const outcome = await findSignedInCustomer();
+      if (!cancelled) setView(greetingView(outcome));
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [hydrated]);
+
+  /**
+   * `pending` refuses a re-entrant call: a keyboard Enter can fire while a click
+   * is already in flight, before `disabled` has painted. A sign-in that lands
+   * re-reads the cart, because the session it belongs to is now the shopper's.
+   * An accepted sign-in whose greeting fails is signed out again before the
+   * refusal renders: the tab never stays signed in behind a failed sign-in.
+   */
+  async function signIn(credentials: NativeAuthInput): Promise<void> {
+    if (pending) return;
+    setPending(true);
+    const outcome = await loginCustomer(credentials);
+    if (outcome.kind === 'error') {
+      setRefusedAddress(credentials.emailAddress);
+      setView(signInRefusedView(outcome.code));
+      setPending(false);
+      return;
+    }
+    const next = signInView(await findSignedInCustomer());
+    if (next.state !== 'signed-in') await logoutCustomer();
+    refresh();
+    setView(next);
+    setPending(false);
+  }
+
+  /** Same guard. The cart is re-read: this tab no longer carries the session it belonged to. */
+  async function signOut(): Promise<void> {
+    if (pending) return;
+    setPending(true);
+    const outcome = await logoutCustomer();
+    refresh();
+    setView(signedOutView(outcome));
+    setPending(false);
+  }
+
+  if (view.state === 'loading') return <AccountSkeleton />;
+
+  if (view.state === 'signed-in') {
+    return (
+      <Greeting
+        customer={view.customer}
+        locale={locale}
+        pending={pending}
+        onSignOut={() => void signOut()}
+      />
+    );
+  }
+
+  return (
+    <SignInForm
+      locale={locale}
+      refusal={view.refusal}
+      resendTo={offersVerificationResend(view) ? refusedAddress : null}
+      pending={pending}
+      onSignIn={signIn}
+    />
+  );
+}
+
+function Greeting({
+  customer,
+  locale,
+  pending,
+  onSignOut,
+}: {
+  customer: SignedInCustomer;
+  locale: LocaleBinding;
+  pending: boolean;
+  onSignOut: () => void;
+}) {
+  return (
+    <div className="space-y-6" data-fc-account-mode="account" data-fc-account-state="signed-in">
+      <div className="card border border-base-300 bg-base-100">
+        <div className="card-body">
+          <h2 className="card-title">Hello, {customer.firstName}</h2>
+          <p className="text-sm text-base-content/70">
+            You are signed in as {customer.emailAddress}.
+          </p>
+        </div>
+      </div>
+
+      <div className="flex flex-wrap gap-3">
+        <LocaleLink href="/products" locale={locale} className="btn btn-primary">
+          Continue shopping
+        </LocaleLink>
+        <button type="button" className="btn btn-ghost" disabled={pending} onClick={onSignOut}>
+          {pending ? 'Signing out…' : 'Sign out'}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function SignInForm({
+  locale,
+  refusal,
+  resendTo,
+  pending,
+  onSignIn,
+}: {
+  locale: LocaleBinding;
+  /** The refusal that put the form here, if any. */
+  refusal: AccountRefusal | null;
+  /** The address to offer the confirmation mail to, when the refusal calls for one. */
+  resendTo: string | null;
+  pending: boolean;
+  onSignIn: (credentials: NativeAuthInput) => Promise<void>;
+}) {
+  const [emailAddress, setEmailAddress] = useState('');
+  const [password, setPassword] = useState('');
+
+  async function submit(): Promise<void> {
+    await onSignIn({ emailAddress, password });
+    // The password only ever lived in this component's state; drop it as soon
+    // as the answer is in, whatever the answer was.
+    setPassword('');
+  }
+
+  const notice = refusalNotice(refusal);
+  return (
+    <form
+      className="space-y-4"
+      data-fc-account-mode="account"
+      data-fc-account-state="signed-out"
+      onSubmit={(event) => {
+        event.preventDefault();
+        void submit();
+      }}
+    >
+      <p className="text-sm text-base-content/60">
+        Sign in with the e-mail address and password you registered with.
+      </p>
+
+      {notice && (
+        <AccountMessage tone={notice.tone} title={notice.title}>
+          {notice.body}
+        </AccountMessage>
+      )}
+
+      {resendTo !== null && <VerificationResend key={resendTo} emailAddress={resendTo} />}
+
+      <div>
+        <label
+          className="mb-1 block text-sm font-medium text-base-content/70"
+          htmlFor="sign-in-email"
+        >
+          E-mail address
+        </label>
+        <input
+          id="sign-in-email"
+          type="email"
+          required
+          autoComplete="email"
+          value={emailAddress}
+          onChange={(event) => setEmailAddress(event.target.value)}
+          className="input w-full"
+        />
+      </div>
+
+      <div>
+        <label
+          className="mb-1 block text-sm font-medium text-base-content/70"
+          htmlFor="sign-in-password"
+        >
+          Password
+        </label>
+        <input
+          id="sign-in-password"
+          type="password"
+          required
+          autoComplete="current-password"
+          value={password}
+          onChange={(event) => setPassword(event.target.value)}
+          className="input w-full"
+        />
+      </div>
+
+      <div className="flex flex-wrap items-center gap-4">
+        <button type="submit" className="btn btn-primary" disabled={pending}>
+          {pending ? 'Signing in…' : 'Sign in'}
+        </button>
+        <LocaleLink href="/reset-password" locale={locale} className="link link-hover text-sm">
+          Forgot your password?
+        </LocaleLink>
+      </div>
+
+      <p className="text-sm text-base-content/60">
+        New here?{' '}
+        <LocaleLink href="/register" locale={locale} className="link link-hover">
+          Create an account
+        </LocaleLink>
+      </p>
+    </form>
+  );
+}
+
+function AccountSkeleton() {
+  return (
+    <div
+      className="space-y-4"
+      aria-busy="true"
+      aria-label="Loading your account"
+      data-fc-account-mode="account"
+      data-fc-account-state="loading"
+    >
+      <div className="skeleton h-10 w-full"></div>
+      <div className="skeleton h-10 w-full"></div>
+      <div className="skeleton h-10 w-32"></div>
+    </div>
+  );
+}