create-restack-pattern 0.1.0

package/template/frontend/domains/auth/components/login-form.tsx

@@ -0,0 +1,75 @@
+"use client"
+
+import { useState } from "react"
+import Link from "next/link"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@/components/ui/card"
+import { useLogin } from "../hooks/use-login"
+
+/**
+ * LoginForm UI Component (Auth Domain).
+ * Handles rendering the login form and calling the `useLogin` hook.
+ * 
+ * Semi-DDD rules:
+ * - UI components should stay isolated from direct backend API fetching logic.
+ * - Local react state controls input values, and mutation runs through the domain hook.
+ */
+export function LoginForm() {
+  const { login, error, isPending } = useLogin()
+  const [email, setEmail] = useState("")
+  const [password, setPassword] = useState("")
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    login({ email, password })
+  }
+
+  return (
+    <Card className="w-full max-w-sm">
+      <CardHeader>
+        <CardTitle>Login</CardTitle>
+        <CardDescription>Enter your credentials to continue</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <form onSubmit={handleSubmit} className="flex flex-col gap-4">
+          <div className="flex flex-col gap-1">
+            <Label htmlFor="email">Email</Label>
+            <Input
+              id="email"
+              type="email"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              placeholder="you@example.com"
+              required
+            />
+          </div>
+          <div className="flex flex-col gap-1">
+            <Label htmlFor="password">Password</Label>
+            <Input
+              id="password"
+              type="password"
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+              placeholder="••••••••"
+              required
+            />
+          </div>
+          {error && <p className="text-sm text-red-500">{error}</p>}
+          <Button type="submit" disabled={isPending} className="w-full">
+            {isPending ? "Logging in..." : "Login"}
+          </Button>
+        </form>
+      </CardContent>
+      <CardFooter className="justify-center">
+        <p className="text-sm text-muted-foreground">
+          Don&apos;t have an account?{" "}
+          <Link href="/register" className="text-primary underline underline-offset-4">
+            Register
+          </Link>
+        </p>
+      </CardFooter>
+    </Card>
+  )
+}

package/template/frontend/domains/auth/components/logout-button.tsx

@@ -0,0 +1,30 @@
+"use client"
+
+import { useState } from "react"
+import { useRouter } from "next/navigation"
+import { Button } from "@/components/ui/button"
+import { authApi } from "../services/auth.api"
+
+/**
+ * LogoutButton Component (Auth Domain).
+ * Simple action component to trigger sessions termination and redirect.
+ * 
+ * Semi-DDD rules:
+ * - Simple action triggers can invoke services directly if no reactive local states/business orchestration is required.
+ */
+export function LogoutButton() {
+  const router = useRouter()
+  const [isPending, setIsPending] = useState(false)
+
+  const handleLogout = async () => {
+    setIsPending(true)
+    await authApi.logout()
+    router.push("/login")
+  }
+
+  return (
+    <Button variant="outline" onClick={handleLogout} disabled={isPending}>
+      {isPending ? "Logging out..." : "Logout"}
+    </Button>
+  )
+}

package/template/frontend/domains/auth/components/register-form.tsx

@@ -0,0 +1,87 @@
+"use client"
+
+import { useState } from "react"
+import Link from "next/link"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@/components/ui/card"
+import { useRegister } from "../hooks/use-register"
+
+/**
+ * RegisterForm UI Component (Auth Domain).
+ * Handles rendering the register form and calling the `useRegister` hook.
+ * 
+ * Semi-DDD rules:
+ * - UI components should stay isolated from direct backend API fetching logic.
+ * - Local react state controls input values, and mutation runs through the domain hook.
+ */
+export function RegisterForm() {
+  const { register, error, isPending } = useRegister()
+  const [name, setName] = useState("")
+  const [email, setEmail] = useState("")
+  const [password, setPassword] = useState("")
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    register({ name, email, password })
+  }
+
+  return (
+    <Card className="w-full max-w-sm">
+      <CardHeader>
+        <CardTitle>Create an account</CardTitle>
+        <CardDescription>Fill in the details below to get started</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <form onSubmit={handleSubmit} className="flex flex-col gap-4">
+          <div className="flex flex-col gap-1">
+            <Label htmlFor="name">Name</Label>
+            <Input
+              id="name"
+              type="text"
+              value={name}
+              onChange={(e) => setName(e.target.value)}
+              placeholder="Your name"
+              required
+            />
+          </div>
+          <div className="flex flex-col gap-1">
+            <Label htmlFor="email">Email</Label>
+            <Input
+              id="email"
+              type="email"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              placeholder="you@example.com"
+              required
+            />
+          </div>
+          <div className="flex flex-col gap-1">
+            <Label htmlFor="password">Password</Label>
+            <Input
+              id="password"
+              type="password"
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+              placeholder="••••••••"
+              required
+            />
+          </div>
+          {error && <p className="text-sm text-red-500">{error}</p>}
+          <Button type="submit" disabled={isPending} className="w-full">
+            {isPending ? "Registering..." : "Register"}
+          </Button>
+        </form>
+      </CardContent>
+      <CardFooter className="justify-center">
+        <p className="text-sm text-muted-foreground">
+          Already have an account?{" "}
+          <Link href="/login" className="text-primary underline underline-offset-4">
+            Login
+          </Link>
+        </p>
+      </CardFooter>
+    </Card>
+  )
+}

package/template/frontend/domains/auth/hooks/use-login.ts

@@ -0,0 +1,17 @@
+"use client"
+
+import { LoginSchema, type LoginInput } from "@restack/shared"
+import { useAuthMutation } from "@/shared/hooks/use-auth-mutation"
+import { authApi } from "../services/auth.api"
+
+/**
+ * Domain-specific hook for Login (Auth Domain).
+ * Orchestrates login form mutation by wrapping the reusable useAuthMutation hook.
+ * 
+ * Semi-DDD rules:
+ * - Domain hooks hide specific Zod validation schemas, API calls, and loading states from components.
+ */
+export function useLogin() {
+  const { submit, error, isPending } = useAuthMutation<LoginInput>(LoginSchema, authApi.login)
+  return { login: submit, error, isPending }
+}

package/template/frontend/domains/auth/hooks/use-register.ts

@@ -0,0 +1,17 @@
+"use client"
+
+import { RegisterSchema, type RegisterInput } from "@restack/shared"
+import { useAuthMutation } from "@/shared/hooks/use-auth-mutation"
+import { authApi } from "../services/auth.api"
+
+/**
+ * Domain-specific hook for Registration (Auth Domain).
+ * Orchestrates registration form mutation by wrapping the reusable useAuthMutation hook.
+ * 
+ * Semi-DDD rules:
+ * - Domain hooks hide specific Zod validation schemas, API calls, and loading states from components.
+ */
+export function useRegister() {
+  const { submit, error, isPending } = useAuthMutation<RegisterInput>(RegisterSchema, authApi.register)
+  return { register: submit, error, isPending }
+}

package/template/frontend/domains/auth/services/auth.api.ts

@@ -0,0 +1,27 @@
+import type { AuthUser, LoginInput, RegisterInput } from "@restack/shared"
+import { apiClient } from "@/shared/lib/api-client"
+
+/**
+ * Service API layer for the Auth domain.
+ * Thin wrappers that perform API calls to the Hono backend endpoints.
+ * 
+ * Semi-DDD rules:
+ * - Domain services (`domains/[feature]/services/*.api.ts`) handle only raw HTTP calls.
+ * - Request and response structures are mapped using schemas shared from `@restack/shared`.
+ */
+export const authApi = {
+  register: (data: RegisterInput) =>
+    apiClient<{ user: AuthUser }>("/api/auth/register", {
+      method: "POST",
+      body: JSON.stringify(data),
+    }),
+
+  login: (data: LoginInput) =>
+    apiClient<{ user: AuthUser }>("/api/auth/login", {
+      method: "POST",
+      body: JSON.stringify(data),
+    }),
+
+  logout: () =>
+    apiClient<{ success: boolean }>("/api/auth/logout", { method: "POST" }),
+}

package/template/frontend/domains/user/components/profile-card.tsx

@@ -0,0 +1,33 @@
+"use client"
+
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
+import { useProfile } from "../hooks/use-profile"
+
+/**
+ * ProfileCard UI component.
+ * Displays the loaded user profile information in a card layout.
+ * 
+ * Semi-DDD rules:
+ * - Domain components (`domains/[feature]/components/*`) are responsible for UI layout and rendering.
+ * - They should never perform direct HTTP calls or manage global state; instead, they consume data
+ *   and actions via domain-specific hooks (`useProfile`).
+ */
+export function ProfileCard() {
+  const { profile, isLoading, error } = useProfile()
+
+  if (isLoading) return <p className="text-sm text-muted-foreground">Loading profile...</p>
+  if (error) return <p className="text-sm text-red-500">{error}</p>
+  if (!profile) return null
+
+  return (
+    <Card className="w-full max-w-sm">
+      <CardHeader>
+        <CardTitle>{profile.name}</CardTitle>
+        <CardDescription>{profile.email}</CardDescription>
+      </CardHeader>
+      <CardContent className="text-xs text-muted-foreground">
+        User ID: {profile.id}
+      </CardContent>
+    </Card>
+  )
+}

package/template/frontend/domains/user/hooks/use-profile.ts

@@ -0,0 +1,39 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import { useRouter } from "next/navigation"
+import type { AuthUser } from "@restack/shared"
+import { userApi } from "../services/user.api"
+
+/**
+ * Domain-specific Hook for user profiles.
+ * Manages loading, error, and profile states, abstracting backend calls.
+ *
+ * Redirects to /login on failure: there is no server-side (proxy.ts) auth gate
+ * anymore — presence-only cookie checks can't work once frontend and backend
+ * sit on unrelated domains (see docs/deployment-verification.md, Topology B),
+ * so this client-side check is the only thing actually protecting this page.
+ *
+ * Semi-DDD rules:
+ * - Domain hooks (`domains/[feature]/hooks/*.ts`) manage the reactive state and orchestrate calls to `services/`.
+ * - UI components should import hooks to retrieve state and trigger actions, keeping the components themselves focused purely on layout/rendering.
+ */
+export function useProfile() {
+  const router = useRouter()
+  const [profile, setProfile] = useState<AuthUser | null>(null)
+  const [isLoading, setIsLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    userApi
+      .me()
+      .then((res) => setProfile(res.user))
+      .catch((e) => {
+        setError(e instanceof Error ? e.message : "Failed to load profile")
+        router.replace("/login")
+      })
+      .finally(() => setIsLoading(false))
+  }, [router])
+
+  return { profile, isLoading, error }
+}

package/template/frontend/domains/user/services/user.api.ts

@@ -0,0 +1,21 @@
+import type { AuthUser, UpdateProfileInput } from "@restack/shared"
+import { apiClient } from "@/shared/lib/api-client"
+
+/**
+ * Service API layer for the User domain.
+ * Thin wrappers that perform API calls to the Hono backend endpoints.
+ * 
+ * Semi-DDD rules:
+ * - Domain services (`domains/[feature]/services/*.api.ts`) handle only raw HTTP calls.
+ * - They must not contain UI state or react state; delegate that strictly to domain hooks.
+ * - Request and response structures are mapped using schemas shared from `@restack/shared`.
+ */
+export const userApi = {
+  me: () => apiClient<{ user: AuthUser }>("/api/user/me"),
+
+  updateProfile: (data: UpdateProfileInput) =>
+    apiClient<{ user: AuthUser }>("/api/user/profile", {
+      method: "PUT",
+      body: JSON.stringify(data),
+    }),
+}

package/template/frontend/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

package/template/frontend/gitignore

@@ -0,0 +1,43 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+.vercel

package/template/frontend/lib/utils.ts

@@ -0,0 +1,11 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+/**
+ * Global utility class merger.
+ * Combines `clsx` (conditional classes) and `tailwind-merge` (overrides duplicate Tailwind classes)
+ * to safely handle dynamic styling inputs without layout conflicts.
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/template/frontend/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  transpilePackages: ["@restack/shared"],
+};
+
+export default nextConfig;

package/template/frontend/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "frontend",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "@restack/shared": "workspace:*",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "next": "16.2.9",
+    "radix-ui": "^1.6.1",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "shadcn": "^4.12.0",
+    "sharp": "^0.35.3",
+    "tailwind-merge": "^3.6.0",
+    "tw-animate-css": "^1.4.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.9",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}

package/template/frontend/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/template/frontend/shared/components/require-auth.tsx

@@ -0,0 +1,25 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import { useRouter } from "next/navigation"
+import { apiClient } from "../lib/api-client"
+
+/**
+ * Client-side auth gate for pages with no data fetch of their own to piggyback
+ * a redirect on (see use-profile.ts for pages that need both). Necessary
+ * because there is no server-side proxy.ts guard anymore — see the Next.js 16
+ * caveat in CLAUDE.md for why.
+ */
+export function RequireAuth({ children }: { children: React.ReactNode }) {
+  const router = useRouter()
+  const [checked, setChecked] = useState(false)
+
+  useEffect(() => {
+    apiClient("/api/user/me")
+      .then(() => setChecked(true))
+      .catch(() => router.replace("/login"))
+  }, [router])
+
+  if (!checked) return null
+  return <>{children}</>
+}

package/template/frontend/shared/hooks/use-auth-mutation.ts

@@ -0,0 +1,37 @@
+"use client"
+
+import { useState } from "react"
+import { useRouter } from "next/navigation"
+import type { ZodType } from "zod"
+
+/**
+ * Reusable mutation hook for authorization forms (Login, Register).
+ * Standardizes Zod input validation, pending state tracking, error handling,
+ * and automatic client-side redirection on successful mutation.
+ */
+export function useAuthMutation<TInput>(schema: ZodType<TInput>, mutate: (data: TInput) => Promise<unknown>) {
+  const router = useRouter()
+  const [error, setError] = useState<string | null>(null)
+  const [isPending, setIsPending] = useState(false)
+
+  const submit = async (data: TInput) => {
+    const parsed = schema.safeParse(data)
+    if (!parsed.success) {
+      setError(parsed.error.issues[0].message)
+      return
+    }
+
+    setIsPending(true)
+    setError(null)
+    try {
+      await mutate(parsed.data)
+      router.push("/dashboard")
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Something went wrong")
+    } finally {
+      setIsPending(false)
+    }
+  }
+
+  return { submit, error, isPending }
+}

package/template/frontend/shared/lib/api-client.ts

@@ -0,0 +1,73 @@
+/**
+ * Global HTTP client helper for frontend domains.
+ * Wraps global fetch and configures default options such as content types,
+ * credentials handling (sending HTTP cookies), and base API URL resolution.
+ */
+const BASE_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3001"
+
+/**
+ * Custom API Error wrapping utility.
+ * Captures both the backend error message payload and the raw HTTP response status code.
+ */
+class ApiError extends Error {
+  constructor(message: string, public status: number) {
+    super(message)
+  }
+}
+
+interface ApiErrorBody {
+  error?: string
+}
+
+async function request<T>(path: string, options?: RequestInit): Promise<T> {
+  const res = await fetch(`${BASE_URL}${path}`, {
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...options?.headers,
+    },
+    credentials: "include",
+  })
+
+  const contentType = res.headers.get("content-type")
+  const data: unknown =
+    contentType && contentType.includes("application/json")
+      ? await res.json()
+      : { error: (await res.text()) || "Request failed" }
+
+  if (!res.ok) throw new ApiError((data as ApiErrorBody).error ?? "Request failed", res.status)
+  return data as T
+}
+
+// The refresh token is single-use (backend rotates it atomically), so if several
+// requests 401 at once they must share one refresh call, not each fire their own —
+// only the first would succeed and the rest would wrongly fail as "logged out".
+let refreshPromise: Promise<unknown> | null = null
+
+function refreshSession() {
+  if (!refreshPromise) {
+    refreshPromise = request("/api/auth/refresh", { method: "POST" }).finally(() => {
+      refreshPromise = null
+    })
+  }
+  return refreshPromise
+}
+
+export async function apiClient<T>(
+  path: string,
+  options?: RequestInit
+): Promise<T> {
+  try {
+    return await request<T>(path, options)
+  } catch (e) {
+    // The access_token cookie is short-lived by design (15m). On a 401, silently
+    // exchange the refresh_token for a new pair once, then retry the original call.
+    // Auth routes are excluded so a failed refresh can't loop back into itself.
+    const isAuthRoute = path.startsWith("/api/auth/")
+    if (e instanceof ApiError && e.status === 401 && !isAuthRoute) {
+      await refreshSession()
+      return request<T>(path, options)
+    }
+    throw e
+  }
+}