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

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @yosr-ai/template-next-fullstack
+
+## 0.1.0-alpha.1
+
+### Patch Changes
+
+- An interactive Yosr Seed run closes with the next command when the gate is green, and points at `.seed/report.md` when the project was still written. On a terminal, the written folder, git, and the gate stay inside the prompt rail. The published Yosr Seed package rewrites every bundled `@yosr-ai/engine` import.
+- Generated Yosr Seed projects record the choices made at setup and ask before departing from them. Flat aliases and unit-test paths match the layout, the home page follows the database choice, and standalone output is only for the Docker image build.
+- Generated Yosr Seed projects pass every `ts.typeDefinitions` setting. Flat layout names `src/lib/server/` as the server-infrastructure area, with one level for `db/` and `auth/`.
+
+## 0.1.0-alpha.0
+
+### Major Changes
+
+- First alpha of the Yosr Seed next-fullstack template.

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# `@yosr-ai/template-next-fullstack`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Yosr Seed next-fullstack template. License: MIT. Node.js: `>=24`. CLI usage is in the [repository README](https://github.com/getyosr/yosr-seed#readme).
+
+For template authors; not rendered. Layout follows the template format spec.
+
+- `seed.template.json`: manifest. Started from `examples/next-fullstack/seed.template.json`; dependency versions pinned from the npm registry on 2026-10-19. `x-prototype.stubbedFeatures` is empty. The selftest stub is fixture-only.
+- `files/`: the base. It is a real Next.js app that installs, lints, type-checks, builds and tests on its own (checked). Files sit at the **default** layout's concrete paths (`src/features`, `src/shared`, `src/server`); the renderer relocates them for other layouts. `gitignore` is renamed to `.gitignore` on render (npm strips `.gitignore` from published packages).
+- `features/orm-drizzle/`: Postgres + Drizzle overlay (replaces the in-memory notes store). `database: none` is the base without this overlay.
+- `features/orm-prisma/`: Postgres + Prisma overlay (same role as Drizzle: schema, client, notes store via `replaces`). `prisma generate` runs on install. The generated client is not committed.
+- `features/deploy-vercel/`: README section only.
+- `features/deploy-docker/`: Dockerfile, `.dockerignore`, and `compose.yaml` for `deploy: docker`. The `next-config` anchor turns on `output: "standalone"` only when `YOSR_STANDALONE=1`, which the Dockerfile sets for the image build. Local `next start` does not use standalone output. `features/deploy-docker-postgres/` adds a Postgres service to that compose file when `database` is `postgres`. The image build is a non-required gate step (`--image`).
+- `style/errors-result/`: variant tree for `errors.pattern = result`.
+- `rules/`: agent-rule fragments and the architecture note source.
+
+Anchors (`@seed:anchor <name>`) must be alone on their line; inserted content takes the anchor line's indentation; anchors are removed from output.

package/features/api-trpc/files/src/app/api/trpc/[trpc]/route.ts

@@ -0,0 +1,15 @@
+import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
+
+import { createContext } from "@server/api/context";
+import { appRouter } from "@server/api/root";
+
+function handler(req: Request) {
+  return fetchRequestHandler({
+    endpoint: "/api/trpc",
+    req,
+    router: appRouter,
+    createContext: () => createContext(),
+  });
+}
+
+export { handler as GET, handler as POST };

package/features/api-trpc/files/src/app/trpc-provider.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { httpBatchLink } from "@trpc/client";
+import { createTRPCReact } from "@trpc/react-query";
+import type { ReactNode } from "react";
+import { useState } from "react";
+
+import type { AppRouter } from "@server/api/root";
+
+export const trpc = createTRPCReact<AppRouter>();
+
+/** One registry entry: tRPC client inside React Query. */
+export function TrpcProvider({ children }: { children: ReactNode }) {
+  const [queryClient] = useState(() => new QueryClient());
+  const [trpcClient] = useState(() =>
+    trpc.createClient({
+      links: [httpBatchLink({ url: "/api/trpc" })],
+    }),
+  );
+
+  return (
+    <trpc.Provider client={trpcClient} queryClient={queryClient}>
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    </trpc.Provider>
+  );
+}

package/features/api-trpc/files/src/features/notes/components/note-form.tsx

@@ -0,0 +1,48 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import { useState } from "react";
+
+import { trpc } from "@/app/trpc-provider";
+import { Button } from "@ui/button";
+import { Input } from "@ui/input";
+
+export function NoteForm() {
+  const router = useRouter();
+  const [title, setTitle] = useState("");
+  const create = trpc.notes.create.useMutation({
+    onSuccess: () => {
+      setTitle("");
+      router.refresh();
+    },
+  });
+
+  return (
+    <form
+      className="flex flex-col gap-2"
+      onSubmit={(event) => {
+        event.preventDefault();
+        create.mutate({ title });
+      }}
+    >
+      <div className="flex gap-2">
+        <Input
+          name="title"
+          value={title}
+          onChange={(event) => setTitle(event.target.value)}
+          placeholder="Write a note"
+          aria-label="Note title"
+          maxLength={120}
+        />
+        <Button type="submit" disabled={create.isPending}>
+          Add
+        </Button>
+      </div>
+      {create.error ? (
+        <p role="alert" className="text-sm text-destructive">
+          {create.error.message}
+        </p>
+      ) : null}
+    </form>
+  );
+}

package/features/api-trpc/files/src/server/api/context.ts

@@ -0,0 +1,8 @@
+import { insertNote } from "@domain/notes/notes-store";
+
+/** Request context. Importing the store does not open a database. */
+export function createContext() {
+  return { insertNote };
+}
+
+export type ApiContext = ReturnType<typeof createContext>;

package/features/api-trpc/files/src/server/api/notes.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { ApiContext } from "./context";
+import { appRouter } from "./root";
+
+describe("notes.create", () => {
+  it("stores a trimmed title through createNote", async () => {
+    const insertNote: ApiContext["insertNote"] = vi.fn(async (input) => ({
+      id: "1",
+      title: input.title,
+      createdAt: new Date(0),
+    }));
+    const caller = appRouter.createCaller({ insertNote });
+
+    const note = await caller.notes.create({ title: "  Buy milk  " });
+
+    expect(insertNote).toHaveBeenCalledWith({ title: "Buy milk" });
+    expect(note.title).toBe("Buy milk");
+  });
+
+  it("rejects an empty title without storing", async () => {
+    const insertNote: ApiContext["insertNote"] = vi.fn();
+    const caller = appRouter.createCaller({ insertNote });
+
+    await expect(caller.notes.create({ title: " " })).rejects.toThrow(
+      "Title is required",
+    );
+    expect(insertNote).not.toHaveBeenCalled();
+  });
+});

package/features/api-trpc/files/src/server/api/notes.ts

@@ -0,0 +1,42 @@
+import { TRPCError } from "@trpc/server";
+import { z } from "zod";
+
+import { createNote } from "@domain/notes/create-note";
+import type { Note } from "@domain/notes/note-schema";
+
+import { publicProcedure, router } from "./trpc";
+
+function asNote(value: unknown): Note {
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    "id" in value &&
+    typeof value.id === "string" &&
+    "title" in value &&
+    typeof value.title === "string" &&
+    "createdAt" in value &&
+    value.createdAt instanceof Date
+  ) {
+    return { id: value.id, title: value.title, createdAt: value.createdAt };
+  }
+  throw new TRPCError({ code: "INTERNAL_SERVER_ERROR", message: "Invalid note" });
+}
+
+export const notesRouter = router({
+  create: publicProcedure.input(z.unknown()).mutation(async ({ ctx, input }) => {
+    const created = await createNote(input, ctx.insertNote);
+    if (typeof created === "object" && created !== null && "ok" in created) {
+      if (created.ok === false) {
+        const message =
+          "error" in created && typeof created.error === "string"
+            ? created.error
+            : "Invalid note";
+        throw new TRPCError({ code: "BAD_REQUEST", message });
+      }
+      if ("value" in created) {
+        return asNote(created.value);
+      }
+    }
+    return asNote(created);
+  }),
+});

package/features/api-trpc/files/src/server/api/root.ts

@@ -0,0 +1,8 @@
+import { notesRouter } from "./notes";
+import { router } from "./trpc";
+
+export const appRouter = router({
+  notes: notesRouter,
+});
+
+export type AppRouter = typeof appRouter;

package/features/api-trpc/files/src/server/api/trpc.ts

@@ -0,0 +1,8 @@
+import { initTRPC } from "@trpc/server";
+
+import type { ApiContext } from "./context";
+
+const t = initTRPC.context<ApiContext>().create();
+
+export const router = t.router;
+export const publicProcedure = t.procedure;

package/features/api-trpc/snippets/providers-imports.tsx

@@ -0,0 +1,2 @@
+
+import { TrpcProvider } from "./trpc-provider";

package/features/api-trpc/snippets/providers.tsx

@@ -0,0 +1 @@
+TrpcProvider,

package/features/auth-authjs/files/e2e/sign-in.spec.ts

@@ -0,0 +1,10 @@
+import { expect, test } from "@playwright/test";
+
+test("sign-in page lists GitHub and Google only", async ({ page }) => {
+  await page.goto("/sign-in");
+  await expect(page.getByRole("button", { name: "GitHub" })).toBeVisible();
+  await expect(page.getByRole("button", { name: "Google" })).toBeVisible();
+  await expect(page.getByLabel(/email/i)).toHaveCount(0);
+  await expect(page.getByRole("button", { name: /magic link/i })).toHaveCount(0);
+  await expect(page.getByText(/magic link/i)).toHaveCount(0);
+});

package/features/auth-authjs/files/src/app/api/auth/[...nextauth]/route.ts

@@ -0,0 +1,13 @@
+import type { NextRequest } from "next/server";
+import NextAuth from "next-auth";
+
+import { authOptions } from "@server/auth/config";
+
+async function handler(
+  req: NextRequest,
+  context: { params: Promise<{ nextauth: string[] }> },
+) {
+  return NextAuth(req, context, authOptions());
+}
+
+export { handler as GET, handler as POST };

package/features/auth-authjs/files/src/app/auth-session-provider.tsx

@@ -0,0 +1,8 @@
+"use client";
+
+import { SessionProvider } from "next-auth/react";
+import type { ReactNode } from "react";
+
+export function AuthSessionProvider({ children }: { children: ReactNode }) {
+  return <SessionProvider>{children}</SessionProvider>;
+}

package/features/auth-authjs/files/src/app/sign-in/page.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import { signIn } from "next-auth/react";
+
+import { Button } from "@ui/button";
+
+export default function SignInPage() {
+  return (
+    <main className="mx-auto flex w-full max-w-sm flex-col gap-3 p-6">
+      <h1 className="text-xl font-semibold">Sign in</h1>
+      <Button type="button" onClick={() => void signIn("github")}>
+        GitHub
+      </Button>
+      <Button type="button" onClick={() => void signIn("google")}>
+        Google
+      </Button>
+    </main>
+  );
+}

package/features/auth-authjs/files/src/server/auth/config.ts

@@ -0,0 +1,28 @@
+// @seed:anchor adapter-imports
+import type { NextAuthOptions } from "next-auth";
+import GitHubProvider from "next-auth/providers/github";
+import GoogleProvider from "next-auth/providers/google";
+
+// @seed:anchor adapter-db-imports
+
+/** Auth.js options. The adapter calls `db()`, so this runs per request, not at import. */
+export function authOptions(): NextAuthOptions {
+  return {
+    // @seed:anchor adapter
+    ...(process.env.AUTH_SECRET !== undefined
+      ? { secret: process.env.AUTH_SECRET }
+      : {}),
+    session: { strategy: "database" },
+    pages: { signIn: "/sign-in" },
+    providers: [
+      GitHubProvider({
+        clientId: process.env.GITHUB_ID ?? "",
+        clientSecret: process.env.GITHUB_SECRET ?? "",
+      }),
+      GoogleProvider({
+        clientId: process.env.GOOGLE_CLIENT_ID ?? "",
+        clientSecret: process.env.GOOGLE_CLIENT_SECRET ?? "",
+      }),
+    ],
+  };
+}

package/features/auth-authjs/files/src/server/auth/index.ts

@@ -0,0 +1,15 @@
+import { getServerSession } from "next-auth";
+
+import { authOptions } from "./config";
+
+/** Server session. Opens the database only when called. */
+export function auth() {
+  return getServerSession(authOptions());
+}
+
+/** Signed-in email. Opens the database only when called. */
+export async function sessionEmail(): Promise<string | null> {
+  const session = await auth();
+  const email = session?.user?.email;
+  return typeof email === "string" && email.length > 0 ? email : null;
+}

package/features/auth-authjs/snippets/providers-imports.tsx

@@ -0,0 +1,2 @@
+
+import { AuthSessionProvider } from "./auth-session-provider";

package/features/auth-authjs/snippets/providers.tsx

@@ -0,0 +1 @@
+AuthSessionProvider,

package/features/auth-authjs-drizzle/files/src/server/db/auth-tables.ts

@@ -0,0 +1,86 @@
+import {
+  boolean,
+  integer,
+  pgTable,
+  primaryKey,
+  text,
+  timestamp,
+} from "drizzle-orm/pg-core";
+
+/** Columns from `@auth/drizzle-adapter` 1.11.3 `defineTables` (`src/lib/pg.ts`). */
+export const users = pgTable("user", {
+  id: text("id")
+    .primaryKey()
+    .$defaultFn(() => crypto.randomUUID()),
+  name: text("name"),
+  email: text("email").unique(),
+  emailVerified: timestamp("emailVerified", { mode: "date" }),
+  image: text("image"),
+});
+
+export const accounts = pgTable(
+  "account",
+  {
+    userId: text("userId")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    type: text("type").notNull(),
+    provider: text("provider").notNull(),
+    providerAccountId: text("providerAccountId").notNull(),
+    refresh_token: text("refresh_token"),
+    access_token: text("access_token"),
+    expires_at: integer("expires_at"),
+    token_type: text("token_type"),
+    scope: text("scope"),
+    id_token: text("id_token"),
+    session_state: text("session_state"),
+  },
+  (account) => ({
+    compositePk: primaryKey({
+      columns: [account.provider, account.providerAccountId],
+    }),
+  }),
+);
+
+export const sessions = pgTable("session", {
+  sessionToken: text("sessionToken").primaryKey(),
+  userId: text("userId")
+    .notNull()
+    .references(() => users.id, { onDelete: "cascade" }),
+  expires: timestamp("expires", { mode: "date" }).notNull(),
+});
+
+export const verificationTokens = pgTable(
+  "verificationToken",
+  {
+    identifier: text("identifier").notNull(),
+    token: text("token").notNull(),
+    expires: timestamp("expires", { mode: "date" }).notNull(),
+  },
+  (verificationToken) => ({
+    compositePk: primaryKey({
+      columns: [verificationToken.identifier, verificationToken.token],
+    }),
+  }),
+);
+
+export const authenticators = pgTable(
+  "authenticator",
+  {
+    credentialID: text("credentialID").notNull().unique(),
+    userId: text("userId")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    providerAccountId: text("providerAccountId").notNull(),
+    credentialPublicKey: text("credentialPublicKey").notNull(),
+    counter: integer("counter").notNull(),
+    credentialDeviceType: text("credentialDeviceType").notNull(),
+    credentialBackedUp: boolean("credentialBackedUp").notNull(),
+    transports: text("transports"),
+  },
+  (authenticator) => ({
+    compositePK: primaryKey({
+      columns: [authenticator.userId, authenticator.credentialID],
+    }),
+  }),
+);

package/features/auth-authjs-drizzle/snippets/adapter-db-imports.ts

@@ -0,0 +1,8 @@
+import { db } from "@server/db";
+import {
+  accounts,
+  authenticators,
+  sessions,
+  users,
+  verificationTokens,
+} from "@server/db/schema";

package/features/auth-authjs-drizzle/snippets/adapter-imports.ts

@@ -0,0 +1 @@
+import { DrizzleAdapter } from "@auth/drizzle-adapter";

package/features/auth-authjs-drizzle/snippets/adapter.ts

@@ -0,0 +1,7 @@
+adapter: DrizzleAdapter(db(), {
+  usersTable: users,
+  accountsTable: accounts,
+  sessionsTable: sessions,
+  verificationTokensTable: verificationTokens,
+  authenticatorsTable: authenticators,
+}),

package/features/auth-authjs-drizzle/snippets/auth-tables.ts

@@ -0,0 +1,7 @@
+export {
+  accounts,
+  authenticators,
+  sessions,
+  users,
+  verificationTokens,
+} from "./auth-tables";

package/features/auth-authjs-prisma/snippets/adapter-db-imports.ts

@@ -0,0 +1 @@
+import { db } from "@server/db";

package/features/auth-authjs-prisma/snippets/adapter-imports.ts

@@ -0,0 +1 @@
+import { PrismaAdapter } from "@auth/prisma-adapter";

package/features/auth-authjs-prisma/snippets/adapter.ts

@@ -0,0 +1 @@
+adapter: PrismaAdapter(db()),

package/features/auth-authjs-prisma/snippets/auth-models.prisma

@@ -0,0 +1,58 @@
+model User {
+  id            String    @id @default(cuid())
+  name          String?
+  email         String    @unique
+  emailVerified DateTime?
+  image         String?
+  accounts      Account[]
+  sessions      Session[]
+  Authenticator Authenticator[]
+}
+
+model Account {
+  userId            String
+  type              String
+  provider          String
+  providerAccountId String
+  refresh_token     String?
+  access_token      String?
+  expires_at        Int?
+  token_type        String?
+  scope             String?
+  id_token          String?
+  session_state     String?
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@id([provider, providerAccountId])
+}
+
+model Session {
+  sessionToken String   @unique
+  userId       String
+  expires      DateTime
+  user         User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+}
+
+model VerificationToken {
+  identifier String
+  token      String
+  expires    DateTime
+
+  @@id([identifier, token])
+}
+
+model Authenticator {
+  credentialID         String  @unique
+  userId               String
+  providerAccountId    String
+  credentialPublicKey  String
+  counter              Int
+  credentialDeviceType String
+  credentialBackedUp   Boolean
+  transports           String?
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@id([userId, credentialID])
+}

package/features/auth-clerk/files/e2e/sign-in.spec.ts

@@ -0,0 +1,15 @@
+import { expect, test } from "@playwright/test";
+
+test("sign-in page renders offline", async ({ page }) => {
+  const clerkCalls: string[] = [];
+  page.on("request", (request) => {
+    const url = request.url();
+    if (/clerk\.(com|dev)|accounts\.dev|clerk\.accounts|clerk-telemetry/i.test(url)) {
+      clerkCalls.push(url);
+    }
+  });
+
+  await page.goto("/sign-in");
+  await expect(page.getByRole("heading", { name: "Sign in" })).toBeVisible();
+  expect(clerkCalls).toEqual([]);
+});

package/features/auth-clerk/files/src/app/clerk-app-provider.tsx

@@ -0,0 +1,13 @@
+"use client";
+
+import { ClerkProvider } from "@clerk/nextjs";
+import type { ReactNode } from "react";
+
+/** Mounts Clerk only when a publishable key is set, so the gate does not call Clerk. */
+export function ClerkAppProvider({ children }: { children: ReactNode }) {
+  if (!process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY) {
+    return children;
+  }
+
+  return <ClerkProvider>{children}</ClerkProvider>;
+}

package/features/auth-clerk/files/src/app/sign-in/[[...sign-in]]/page.tsx

@@ -0,0 +1,18 @@
+export default async function SignInPage() {
+  if (!process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY) {
+    return (
+      <main className="mx-auto flex w-full max-w-sm flex-col gap-3 p-6">
+        <h1 className="text-xl font-semibold">Sign in</h1>
+      </main>
+    );
+  }
+
+  const { SignIn } = await import("@clerk/nextjs");
+
+  return (
+    <main className="mx-auto flex w-full max-w-sm flex-col gap-3 p-6">
+      <h1 className="text-xl font-semibold">Sign in</h1>
+      <SignIn />
+    </main>
+  );
+}

package/features/auth-clerk/files/src/app/sign-up/[[...sign-up]]/page.tsx

@@ -0,0 +1,18 @@
+export default async function SignUpPage() {
+  if (!process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY) {
+    return (
+      <main className="mx-auto flex w-full max-w-sm flex-col gap-3 p-6">
+        <h1 className="text-xl font-semibold">Sign up</h1>
+      </main>
+    );
+  }
+
+  const { SignUp } = await import("@clerk/nextjs");
+
+  return (
+    <main className="mx-auto flex w-full max-w-sm flex-col gap-3 p-6">
+      <h1 className="text-xl font-semibold">Sign up</h1>
+      <SignUp />
+    </main>
+  );
+}

package/features/auth-clerk/files/src/proxy.ts

@@ -0,0 +1,24 @@
+import { clerkMiddleware } from "@clerk/nextjs/server";
+import type { NextFetchEvent, NextRequest } from "next/server";
+import { NextResponse } from "next/server";
+
+const gate = clerkMiddleware();
+
+/** Next.js 16 proxy. `clerkMiddleware` runs only when both Clerk keys are set. */
+export function proxy(request: NextRequest, event: NextFetchEvent) {
+  if (
+    !process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY ||
+    !process.env.CLERK_SECRET_KEY
+  ) {
+    return NextResponse.next();
+  }
+
+  return gate(request, event);
+}
+
+export const config = {
+  matcher: [
+    "/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)",
+    "/(api|trpc)(.*)",
+  ],
+};

package/features/auth-clerk/files/src/server/auth/index.ts

@@ -0,0 +1,11 @@
+import { currentUser } from "@clerk/nextjs/server";
+
+/** Signed-in email. Calls Clerk only when this function runs. */
+export async function sessionEmail(): Promise<string | null> {
+  const user = await currentUser();
+  if (user === null) return null;
+  const fromPrimary = user.primaryEmailAddress?.emailAddress;
+  if (typeof fromPrimary === "string" && fromPrimary.length > 0) return fromPrimary;
+  const first = user.emailAddresses[0]?.emailAddress;
+  return typeof first === "string" && first.length > 0 ? first : null;
+}

package/features/auth-clerk/snippets/providers-imports.tsx

@@ -0,0 +1,2 @@
+
+import { ClerkAppProvider } from "./clerk-app-provider";

package/features/auth-clerk/snippets/providers.tsx

@@ -0,0 +1 @@
+ClerkAppProvider,

package/features/deploy-docker/files/.dockerignore

@@ -0,0 +1,6 @@
+node_modules
+.next
+out
+.env
+.env.*
+!.env.example