@yosr-ai/template-next-fullstack 0.0.0-stage → 0.1.0-alpha.1

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@yosr-ai/template-next-fullstack",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.1",
+  "description": "Yosr Seed next-fullstack template.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getyosr/yosr-seed.git",
+    "directory": "packages/template-next-fullstack"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    "./seed.template.json": "./seed.template.json"
+  },
+  "files": [
+    "README.md",
+    "CHANGELOG.md",
+    "seed.template.json",
+    "files",
+    "features",
+    "style",
+    "rules"
+  ],
+  "engines": {
+    "node": ">=24"
+  }
+}

package/rules/api-server-actions.md

@@ -0,0 +1 @@
+Mutations go through **server actions** (`"use server"` files such as `actions.ts`). Actions validate input with zod, call feature functions, and `revalidatePath` what changed. No ad-hoc API routes for app data.

package/rules/api-trpc.md

@@ -0,0 +1 @@
+App data mutations go through tRPC procedures under `__seed_serverDir__/api`. The HTTP handler is `src/app/api/trpc/[trpc]/route.ts`. The notes form calls `notes.create`, which calls `createNote` from `@domain/notes`. Do not call `db()` at module scope.

package/rules/architecture.md

@@ -0,0 +1,11 @@
+# Architecture: __seed_projectName__
+
+Generated by Yosr Seed from `__seed_templateName__@__seed_templateVersion__`. This note is for humans and AI agents; keep it current when the structure changes.
+
+## Stack
+
+Next.js (App Router) + TypeScript, Tailwind CSS v4 + shadcn/ui, Vitest (unit) + Playwright (e2e smoke), package manager `__seed_packageManager__`. Data: __seed_storageLabel__. Deploy target: __seed_deploy__.
+
+## Request flow
+
+`src/app/page.tsx` (Server Component) reads notes through the feature store, renders `NoteForm` (client) and `NoteList` (server). The form posts to a server action, which validates with zod, stores the note and revalidates the page.

package/rules/auth-authjs.md

@@ -0,0 +1 @@
+Sign-in is GitHub OAuth and Google OAuth only. No email, magic link, or credentials. Sessions are stored in Postgres (`session.strategy: "database"`). The route is `src/app/api/auth/[...nextauth]/route.ts`. Read the server session with `auth()` from `@server/auth`. Stripe checkout uses `sessionEmail()` from the same module. Do not call `db()` at module scope; the adapter calls it from `authOptions()`. Auth tables live in the active ORM schema (`__seed_serverDir__/db/schema.ts` for Drizzle, `prisma/schema.prisma` for Prisma). After changing them, run `__seed_pmRun__ db:push`.

package/rules/auth-clerk.md

@@ -0,0 +1 @@
+Sign-in is Clerk. It works with or without a database. The provider is `ClerkAppProvider` in `src/app/providers.tsx`. The request gate is `src/proxy.ts`, which calls `clerkMiddleware` from `@clerk/nextjs/server` only when `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` are both set. Sign-in is `src/app/sign-in/[[...sign-in]]/page.tsx`. Sign-up is `src/app/sign-up/[[...sign-up]]/page.tsx`. When the publishable key is unset, those pages render local markup and do not call Clerk. `sessionEmail()` in `__seed_serverDir__/auth/index.ts` calls `currentUser()` only when checkout runs.

package/rules/commands.md

@@ -0,0 +1,5 @@
+Use the project's package manager (`__seed_packageManager__`):
+
+- `__seed_pmRun__ lint`, `__seed_pmRun__ typecheck`, `__seed_pmRun__ build`, `__seed_pmRun__ test` must all pass before you finish a change.
+- `__seed_pmRun__ format` formats with Prettier; don't hand-format.
+- `__seed_pmRun__ test:e2e` runs the Playwright smoke test (builds and starts the app).

package/rules/data-drizzle.md

@@ -0,0 +1 @@
+Postgres via Drizzle. Tables are defined in `__seed_serverDir__/db/schema.ts`; get the client with `db()` from `@server/db`. Database access belongs in the feature's store module (see the notes store), not in components or routes. After changing the schema run `__seed_pmExec__ drizzle-kit push` (dev) or generate a migration with `__seed_pmRun__ db:generate`.

package/rules/data-none.md

@@ -0,0 +1 @@
+There is **no database**. The example store keeps data in memory and resets on restart. If the app needs persistence, add a database deliberately (ask first); don't write to the filesystem as a substitute.

package/rules/data-prisma.md

@@ -0,0 +1 @@
+Postgres via Prisma. The schema is `prisma/schema.prisma`; get the client with `db()` from `@server/db`. Database access belongs in the feature's store module (see the notes store), not in components or routes. After changing the schema run `__seed_pmRun__ db:push` (dev) or regenerate the client with `__seed_pmRun__ db:generate`.

package/rules/data-server-first.md

@@ -0,0 +1 @@
+Fetch data on the server: in Server Components or server functions. Use client components only for interactivity (forms, state), and mutate through server actions.

package/rules/errors-result.md

@@ -0,0 +1 @@
+Expected failures **return a `Result`** from `@shared/result` (`ok(value)` / `err(message)`) instead of throwing. Callers must check `result.ok`. Only unexpected failures (bugs, outages) throw.

package/rules/errors-throw.md

@@ -0,0 +1 @@
+Expected failures (bad input, not found) **throw** a named `Error` subclass (see `NoteValidationError`). Server actions catch those and return a user-facing message; anything else is re-thrown.

package/rules/forms-zod.md

@@ -0,0 +1 @@
+Validate every input with a zod schema in the feature folder (the example is the notes schema module). The same schema types the data (`z.infer`) and validates it on the server.

package/rules/layout-feature.md

@@ -0,0 +1,5 @@
+Code is grouped **by feature**:
+
+- `__seed_domainDir__/<feature>/` holds that feature's server functions, server actions, zod schemas, and tests. Feature UI lives in `__seed_featureUiDir__/` (on the default tree, the `components/` folder inside the feature).
+- Code shared by several features goes in `__seed_sharedDir__/`.
+- Routes in `src/app/` stay thin: they compose feature components and call feature functions.

package/rules/layout-flat.md

@@ -0,0 +1,5 @@
+**Flat** means one folder per area under `src/lib/` and `src/components/`, no deeper nesting.
+
+- Notes logic is `src/lib/notes/`. Shared helpers are `src/lib/shared/`. Feature UI is `src/components/notes/`. shadcn/ui stays in `src/components/ui/`.
+- Routes stay in `src/app/`.
+- `src/lib/server/` is the server-infrastructure area. It has one level for `db/` and `auth/` (`src/lib/server/db/`, `src/lib/server/auth/`). Don't add a folder inside any other area, and don't nest further under `db/` or `auth/`.

package/rules/layout-layer.md

@@ -0,0 +1,6 @@
+Code is grouped **by technical layer**:
+
+- Domain logic lives in `__seed_domainDir__/<area>/` (server functions, actions, schemas).
+- Feature UI lives in `__seed_featureUiDir__/`.
+- Shared helpers go in `__seed_sharedDir__/`; shadcn/ui stays in `src/components/ui/`.
+- Routes in `src/app/` stay thin.

package/rules/payments-stripe.md

@@ -0,0 +1 @@
+Payments use Stripe Checkout. Create the client with `stripeClient()` in `__seed_serverDir__/billing/stripe.ts` inside the request that needs it. Do not construct Stripe at module scope. Checkout is `src/app/api/checkout/route.ts`. It reads `sessionEmail()` from `@server/auth`. Auth.js and Clerk each provide that function for the active auth feature. The webhook is `src/app/api/webhooks/stripe/route.ts`. It checks `STRIPE_WEBHOOK_SECRET` and the `stripe-signature` header, then `webhooks.constructEvent`, before writing a billing row. Leave `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` empty in `.env.example`.

package/rules/project-overview.md

@@ -0,0 +1,5 @@
+`__seed_projectName__` is a Next.js (App Router) + TypeScript app with Tailwind CSS and shadcn/ui, generated by Yosr Seed from `__seed_templateName__@__seed_templateVersion__`. Data: __seed_storageLabel__. API style: __seed_api__.
+
+- Read `docs/architecture.md` before larger changes; it lists the folder map and where new code goes.
+- Import across folders through the path aliases in `tsconfig.json` (__seed_aliasList__).
+- `.seed/` is a record of what Yosr Seed generated. The app never reads it. It is not edited by hand. It can drift from the project after later changes such as adding a database.

package/rules/tests-colocated.md

@@ -0,0 +1 @@
+Unit tests (Vitest) sit **next to the code**: `create-note.ts` → `create-note` plus the applied unit-test suffix. Import the unit under test through its alias. Every new server function gets a test.

package/rules/tests-folder.md

@@ -0,0 +1 @@
+Unit tests (Vitest) live in a **`__tests__/` folder next to the code**: `<area>/<file>.ts` → `<area>/__tests__/<file>` plus the applied unit-test suffix. Import the unit under test through its alias. Every new server function gets a test.

package/rules/tests-separate.md

@@ -0,0 +1 @@
+Unit tests (Vitest) live under **`tests/unit/`**, mirroring `src/`. Import the unit under test through its alias. Every new server function gets a test.

package/rules/ui-shadcn.md

@@ -0,0 +1 @@
+UI uses Tailwind CSS v4 and shadcn/ui components in `src/components/ui/` (add more with `__seed_pmExec__ shadcn add <name>`). Don't edit generated shadcn files for one-off styling; pass `className` instead. Merge classes with `cn()` from `@shared/utils`.