@thorprovider/storefront 0.4.0-mvp.0 → 0.4.0-mvp.2

package/skills/nextjs-shadcn/references/architecture.md

@@ -1,499 +0,0 @@
-# Architecture
-
-## Best Practices
-
-- Avoid `useEffect` - prefer Server Components, Server Actions, or event handlers
-- `"use client"` only at leaf components (smallest boundary)
-- Props must be serializable (data or Server Actions, no functions/classes)
-- Prefer Tailwind v4 `globals.css` theme variables over hardcoded values
-
-## Component Patterns
-
-### Server vs Client Decision Tree
-
-```
-Need state/effects/browser APIs?
-├── Yes → "use client" at smallest boundary
-└── No → Server Component (default)
-
-Passing data to client?
-├── Functions/classes → ❌ Not serializable
-├── Plain objects/arrays → ✅ Props
-└── Server logic → ✅ Server Actions
-```
-
-### Component Placement
-
-```
-app/
-├── (protected)/             # Auth required routes
-│   ├── dashboard/
-│   ├── settings/
-│   ├── components/          # Route-specific components
-│   └── lib/                 # Route-specific types/utils
-├── (public)/                # Public routes
-│   ├── login/
-│   └── register/
-├── actions/                 # Server Actions (global)
-├── api/                     # API routes
-components/                  # Shared across routes
-├── ui/                      # shadcn primitives
-└── shared/                  # Business components
-hooks/                       # Custom React hooks
-lib/                         # Shared utilities
-data/                        # Database queries
-ai/                          # AI logic (tools, agents, prompts)
-```
-
-### AI Directory Structure
-
-When building AI applications, organize the `ai/` directory:
-
-```
-ai/
-├── model-names.ts      # Model definitions & DEFAULT_MODEL_NAME
-├── actions/            # AI-related server actions
-│   ├── model.ts        # saveModelId, getModelId (cookie-based)
-│   └── chat.ts         # Chat-related actions
-├── utils.ts            # findSources, getLastUserMessageText, etc.
-├── agents/             # Agent definitions (if using agents)
-│   └── assistant.ts
-└── tools/              # Tool definitions (if using tools)
-```
-
-**model-names.ts example:**
-
-```ts
-export interface Model {
-  id: string
-  label: string
-  description: string
-}
-
-export const models: Model[] = [
-  { id: "gpt-5.6-luna", label: "GPT 5.6 Luna", description: "Fast, lightweight tasks" },
-  { id: "gpt-5.6", label: "GPT 5.6", description: "Complex, multi-step tasks" },
-]
-
-export const DEFAULT_MODEL_NAME = "gpt-5.6-luna"
-```
-
-**Cookie-based model storage:**
-
-```ts
-// ai/actions/model.ts - Server Action for MUTATION only
-"use server"
-import { cookies } from "next/headers"
-
-export async function saveModelId(model: string) {
-  const cookieStore = await cookies()
-  cookieStore.set("model-id", model)
-}
-
-// ❌ WRONG: Don't use Server Action for reading data
-// export async function getModelId() { ... }
-
-// ✅ CORRECT: Read cookies directly in Server Component
-// page.tsx
-import { cookies } from "next/headers"
-
-export default async function Page() {
-  const cookieStore = await cookies()
-  const modelId = cookieStore.get("model-id")?.value ?? DEFAULT_MODEL_NAME
-  return <Chat modelId={modelId} />
-}
-```
-
-### className Pattern
-
-Always accept and merge `className`:
-
-```tsx
-import { cn } from "@/lib/utils"
-
-interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
-  variant?: "default" | "outline"
-}
-
-export function Card({ className, variant = "default", ...props }: CardProps) {
-  return (
-    <div
-      className={cn(
-        "rounded-lg p-4",
-        variant === "outline" && "border",
-        className
-      )}
-      {...props}
-    />
-  )
-}
-```
-
-## Data Fetching Patterns
-
-### Server Component (default)
-
-Fetch data directly in Server Components:
-
-```tsx
-export default async function Page() {
-  const data = await fetchData()
-  return <Component data={data} />
-}
-```
-
-### Cached Data Function
-
-Use `'use cache'` for reusable cached queries. `"use cache"` (and `cacheTag`/`cacheLife`/`updateTag`) requires the Cache Components opt-in flag — Next.js 16 does not enable it by default:
-
-```ts
-// next.config.ts
-const nextConfig = { cacheComponents: true }
-```
-
-```tsx
-// data/products.ts
-export async function getProducts() {
-  "use cache"
-  cacheTag("products")
-  cacheLife("hours")
-  return await db.products.findMany()
-}
-```
-
-### Streaming to Client (React `use` hook)
-
-Pass promises to Client Components for streaming:
-
-```tsx
-// Server Component
-export default function Page() {
-  const dataPromise = fetchData() // Don't await
-  return (
-    <Suspense fallback={<Loading />}>
-      <ClientDisplay dataPromise={dataPromise} />
-    </Suspense>
-  )
-}
-
-// Client Component
-"use client"
-import { use } from "react"
-
-export function ClientDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
-  const data = use(dataPromise) // Suspends until resolved
-  return <Chart data={data} />
-}
-```
-
-### Explicit Request-time with connection()
-
-Use `connection()` to explicitly defer to request time without accessing runtime APIs:
-
-```tsx
-import { connection } from "next/server"
-import { Suspense } from "react"
-
-async function UniqueContent() {
-  await connection() // Defer to request time
-  const uuid = crypto.randomUUID()
-  const timestamp = Date.now()
-  return <div>{uuid} - {timestamp}</div>
-}
-
-export default function Page() {
-  return (
-    <Suspense fallback={<Loading />}>
-      <UniqueContent />
-    </Suspense>
-  )
-}
-```
-
-**When to use `connection()`:**
-
-| Scenario | Use connection()? |
-|----------|-------------------|
-| Need unique values per request | ✅ Yes |
-| Using `Math.random()`, `Date.now()`, `crypto.randomUUID()` | ✅ Yes |
-| Already using `cookies()` or `headers()` | ❌ No (not needed) |
-| Data is cacheable | ❌ No (use `'use cache'`) |
-
-## Routing
-
-### Route Groups
-
-Group routes without affecting URL:
-
-```
-app/
-├── (protected)/         # Auth required - /dashboard, /settings
-│   ├── dashboard/
-│   ├── settings/
-│   └── layout.tsx       # Shared chrome (sidebar, auth check)
-├── (public)/            # Public - /login, /register, /about
-│   ├── login/
-│   ├── register/
-│   └── about/
-└── (marketing)/         # Marketing - /pricing, /features
-    ├── pricing/
-    └── features/
-```
-
-### Layout vs Template
-
-| Aspect | layout.tsx | template.tsx |
-|--------|------------|--------------|
-| State | Persists across navigation | Resets on navigation |
-| Effects | Run once | Run on every navigation |
-| Use when | Shared chrome (nav, footer) | Analytics, animations that reset |
-
-**Decision tree:**
-```
-State/effects should reset on navigation?
-├── Yes → template.tsx
-└── No → layout.tsx (default)
-```
-
-### Async Params (Next.js 16)
-
-```tsx
-// Always await params and searchParams
-export default async function Page({
-  params,
-  searchParams,
-}: {
-  params: Promise<{ slug: string }>
-  searchParams: Promise<{ page?: string }>
-}) {
-  const { slug } = await params
-  const { page = "1" } = await searchParams
-
-  const data = await fetchData(slug, parseInt(page))
-  return <Content data={data} />
-}
-```
-
-## Suspense Strategy
-
-### When to Use Suspense
-
-```
-Slow data fetch in Server Component?
-├── Yes → Wrap in <Suspense>
-└── No → Direct render
-
-Multiple independent slow sections?
-├── Yes → Separate <Suspense> boundaries
-└── No → Single boundary or loading.tsx
-```
-
-### Patterns
-
-**loading.tsx** - Entire route fallback:
-```tsx
-// app/dashboard/loading.tsx
-export default function Loading() {
-  return <DashboardSkeleton />
-}
-```
-
-**Suspense** - Granular streaming:
-```tsx
-export default function Page() {
-  return (
-    <>
-      <Header />  {/* Renders immediately */}
-      <Suspense fallback={<StatsSkeleton />}>
-        <SlowStats />  {/* Streams when ready */}
-      </Suspense>
-      <Suspense fallback={<ChartSkeleton />}>
-        <SlowChart />  {/* Streams independently */}
-      </Suspense>
-    </>
-  )
-}
-```
-
-**Skeleton pattern** - Create a skeleton component for each loadable content:
-```tsx
-// components/skeletons.tsx
-export function CardSkeleton() {
-  return (
-    <div className="animate-pulse">
-      <div className="h-4 bg-muted rounded w-3/4 mb-2" />
-      <div className="h-4 bg-muted rounded w-1/2" />
-    </div>
-  )
-}
-
-export function TableSkeleton({ rows = 5 }: { rows?: number }) {
-  return (
-    <div className="space-y-2">
-      {Array.from({ length: rows }).map((_, i) => (
-        <div key={i} className="h-10 bg-muted rounded animate-pulse" />
-      ))}
-    </div>
-  )
-}
-```
-
-**Passing promises to client**:
-```tsx
-// Server Component
-export default function Page() {
-  const dataPromise = fetchData()  // Start fetch, don't await
-  return <ClientChart dataPromise={dataPromise} />
-}
-
-// Client Component
-"use client"
-import { use } from "react"
-
-export function ClientChart({ dataPromise }) {
-  const data = use(dataPromise)  // Suspends until resolved
-  return <Chart data={data} />
-}
-```
-
-## State Management
-
-### useTransition Pattern
-
-Wrap non-urgent UI updates to keep interactions smooth:
-
-```tsx
-"use client"
-import { useTransition } from "react"
-
-function SubmitButton({ action }: { action: () => Promise<void> }) {
-  const [isPending, startTransition] = useTransition()
-
-  return (
-    <button
-      onClick={() => startTransition(() => action())}
-      disabled={isPending}
-    >
-      {isPending ? "Saving..." : "Save"}
-    </button>
-  )
-}
-```
-
-**Guidelines:**
-- Use `isPending` for feedback (disable buttons, show spinners)
-- Don't wrap controlled input state in transitions
-- After `await` inside transition, wrap subsequent `setState` in another `startTransition`
-
-## Data Patterns
-
-### "use cache" (Next.js 16)
-
-Function-level caching:
-
-```tsx
-"use cache"
-
-export async function getProducts() {
-  const products = await db.query.products.findMany()
-  return products
-}
-
-// With cache tags
-import { cacheTag } from "next/cache"
-
-export async function getProduct(id: string) {
-  "use cache"
-  cacheTag(`product-${id}`)
-  return db.query.products.findFirst({ where: eq(products.id, id) })
-}
-```
-
-### Server Actions
-
-```tsx
-"use server"
-
-import { updateTag, revalidateTag } from "next/cache"
-import { z } from "zod"
-
-const schema = z.object({
-  title: z.string().min(1),
-  content: z.string(),
-})
-
-export async function createPost(formData: FormData) {
-  const parsed = schema.parse({
-    title: formData.get("title"),
-    content: formData.get("content"),
-  })
-
-  await db.insert(posts).values(parsed)
-
-  // Read-your-writes (immediate)
-  updateTag("posts")
-
-  // Or SWR-style revalidation
-  // revalidateTag("posts", "max")
-}
-
-// Refresh uncached data
-import { refresh } from "next/cache"
-
-export async function updateProfile(data: FormData) {
-  await db.update(...)
-  refresh() // Triggers client router refresh
-}
-```
-
-### Proxy API (Next.js 16)
-
-Replaces middleware for request interception. Place at project root (same level as `app/`):
-
-```tsx
-// proxy.ts (project root)
-import { NextResponse } from "next/server"
-import type { NextRequest } from "next/server"
-
-export async function proxy(request: NextRequest) {
-  const session = request.cookies.get("session")
-
-  if (!session && request.nextUrl.pathname.startsWith("/dashboard")) {
-    return NextResponse.redirect(new URL("/login", request.url))
-  }
-
-  return NextResponse.next()
-}
-
-export const config = {
-  matcher: ['/dashboard/:path*', '/api/:path*'],
-}
-```
-
-### Request APIs
-
-All request APIs are async in Next.js 16:
-
-```tsx
-import { cookies, headers, draftMode } from "next/headers"
-
-export default async function Page() {
-  const cookieStore = await cookies()
-  const headersList = await headers()
-  const { isEnabled } = await draftMode()
-}
-```
-
-## Error Handling
-
-Define only when custom UX needed:
-
-```
-app/
-├── error.tsx           # Route-level errors
-├── global-error.tsx    # Root layout errors
-├── not-found.tsx       # 404 pages
-└── loading.tsx         # Loading states
-```
-
-Otherwise inherit from parent segment.

package/skills/nextjs-shadcn/references/project-setup.md

@@ -1,162 +0,0 @@
-# Project Setup
-
-## Create New Project
-
-### Minimal Setup
-
-Use the CLI to scaffold a Next.js project directly. Supply every prompt value as
-a flag so the command never reads stdin:
-
-```bash
-yarn dlx shadcn@latest init \
-  --template next --base base --preset <preset> \
-  --no-monorepo --no-rtl --yes --name <project-name>
-```
-
-`--base` picks the primitive library: `base` (Base UI, default), `radix`, or
-`aria` (React Aria). Component APIs differ per base — see
-[shadcn-platform.md](shadcn-platform.md). Add `--rtl` if the app needs
-right-to-left support.
-
-`--name <project-name>` makes the CLI create a **new nested project directory**
-(`<cwd>/<project-name>/`). Omit it to initialize **in place** in the current
-directory (or in `--cwd`). In-place init requires an existing `package.json` —
-with an empty directory the wizard always creates the nested project, and the
-escape `--name .` fails with `dest already exists`. For an empty directory, run
-`yarn create next-app . --ts --tailwind --app --import-alias "@/*"` first
-(moving any `.opencode/` aside and restoring it
-after — `create-next-app` refuses non-empty dirs), then `shadcn init` in place.
-The Thor scaffold flow (`npx @thorprovider/storefront create`) follows exactly that
-two-step flow and never uses shadcn's `--name`, so the project has a single root. Any
-interactive prompt means a flag is missing — resolve it from `--help`, never by guessing.
-
-### Yarn linker (required)
-
-Write `.yarnrc.yml` at the project root **before installing dependencies**:
-
-```yaml
-nodeLinker: node-modules
-```
-
-Yarn 4 defaults to the Plug'n'Play (PnP) linker, which Next.js 16 Turbopack cannot
-resolve from (`Could not find the Next.js package`). The `node-modules` linker makes
-Yarn create a real `node_modules/`, which Turbopack reads. Vercel does not plan PnP
-support for Turbopack.
-
-### With Preset Code
-
-```bash
-yarn dlx shadcn@latest init \
-  --template next --base base --preset <CODE> \
-  --no-monorepo --no-rtl --yes --name <project-name>
-```
-
-Preset codes are short opaque strings from [ui.shadcn.com/create](https://ui.shadcn.com/create) — pass them through verbatim rather than expanding them into individual flags. Prefer this when you want a specific visual system without hardcoding individual style, font, or icon choices into the skill:
-
-```bash
-yarn dlx shadcn@latest init \
-  --template next --base base --preset b4h07r5A1 \
-  --no-monorepo --no-rtl --yes --name my-app
-```
-
-`shadcn preset decode <code>` prints what a code contains (style, base color,
-theme, font, icon library, radius) if you need to read it before applying.
-
-For a project that already exists, apply a preset instead of re-running `init`:
-
-```bash
-yarn dlx shadcn@latest apply <CODE>              # theme, fonts, components
-yarn dlx shadcn@latest apply <CODE> --only theme # just the theme
-```
-
-### Monorepo
-
-```bash
-yarn dlx shadcn@latest init \
-  --template next \
-  --monorepo
-```
-
-### Existing Project
-
-If the Next.js app already exists, run the initializer from the project root:
-
-```bash
-yarn dlx shadcn@latest init \
-  --template next --base base --preset <preset> \
-  --no-monorepo --no-rtl --yes
-```
-
-### Inspect Before Changing
-
-Use the CLI to inspect project state or preview registry changes before writing files:
-
-```bash
-yarn dlx shadcn@latest info
-yarn dlx shadcn@latest add button --dry-run
-yarn dlx shadcn@latest docs button
-```
-
-## Add Components
-
-```bash
-# Single component
-yarn dlx shadcn@latest add button
-
-# Multiple components
-yarn dlx shadcn@latest add button card input
-
-# All components
-yarn dlx shadcn@latest add --all
-```
-
-## Common Dependencies
-
-```bash
-# Forms
-yarn add react-hook-form @hookform/resolvers zod
-
-# AI
-yarn add ai @ai-sdk/anthropic
-
-# Animation
-yarn add motion              # For Motion
-yarn add gsap @gsap/react    # For GSAP
-
-# Icons (pick one)
-yarn add lucide-react        # Default
-```
-
-## Project Structure After Setup
-
-```
-project/
-├── app/
-│   ├── globals.css         # Theme tokens
-│   ├── layout.tsx          # Root layout
-│   └── page.tsx            # Home page
-├── components/
-│   └── ui/                 # shadcn components
-├── lib/
-│   └── utils.ts            # cn() helper
-├── public/
-├── components.json         # shadcn config
-├── tsconfig.json
-└── package.json
-```
-
-## Yarn Commands Reference
-
-| Task | Command |
-|------|---------|
-| Install deps | `yarn install` |
-| Add package | `yarn add package` |
-| Dev server | `yarn dev` |
-| Build | `yarn build` |
-| Start prod | `yarn start` |
-| Add shadcn component | `yarn dlx shadcn@latest add component` |
-| Create project | `yarn dlx shadcn@latest init --template next --base base --preset <preset> --no-monorepo --no-rtl --yes --name <project-name>` |
-| Read project config | `yarn dlx shadcn@latest info --json` |
-| Component API docs | `yarn dlx shadcn@latest docs component` |
-
-