Add Next.js auth proof to setup scaffolds

Author: fforootd

.changeset/lean-agent-auth-proof.md

@@ -0,0 +1,6 @@
+---
+"@zitadel/cli": minor
+"@zitadel/components": patch
+---
+
+Make the generated Next.js auth app easier for agents and developers to prove end-to-end registration, logout, and login in a visible browser.

apps/cli-journey-e2e/src/user-journey.spec.ts

@@ -212,16 +212,30 @@ async function clickAction(
   name: RegExp,
   actionNames: readonly string[] = [],
 ): Promise<void> {
-  let locator = page.getByRole("button", { name }).or(page.getByRole("link", { name }));
+  const candidates: Locator[] = [];
   for (const actionName of actionNames) {
-    locator = page
-      .getByTestId(`zitadel-action-${actionName}-button`)
-      .or(page.getByTestId(`zitadel-action-${actionName}`))
-      .or(page.getByTestId(`zitadel-action-${actionName}-link`))
-      .or(actionLocator(page, actionName))
-      .or(locator);
+    candidates.push(
+      page.getByTestId(`zitadel-action-${actionName}-button`),
+      page.getByTestId(`zitadel-action-${actionName}`),
+      page.getByTestId(`zitadel-action-${actionName}-link`),
+      actionLocator(page, actionName),
+    );
   }
-  await locator.first().click();
+  candidates.push(page.getByRole("button", { name }), page.getByRole("link", { name }));
+
+  for (const candidate of candidates) {
+    const target = candidate.first();
+    if (await target.isVisible({ timeout: 1000 }).catch(() => false)) {
+      await target.click();
+      return;
+    }
+  }
+
+  const fallback = candidates[candidates.length - 1];
+  if (!fallback) {
+    throw new Error("No action candidates configured");
+  }
+  await fallback.first().click();
 }
 
 function actionLocator(page: Page, actionName: string) {

apps/cli/README.md

@@ -37,13 +37,15 @@ back to `ghcr.io/zitadel/nextgen:latest`. Override with `--image` or
 `ZITADEL_LOCAL_IMAGE` for advanced debugging.
 `setup --server local` creates a project on that local server, asks which
 framework to scaffold when the directory is fresh, writes the Next.js app into
-the current directory, scaffolds `app/login`, `app/register`, and `proxy.ts`
-for Next 16+ or `middleware.ts` for older Next versions, writes `.env.local`
-and `.zitadel/`, and installs dependencies with the detected package manager.
-Pass `--skip-install` to install them yourself. The project's default user
-schema and login flow are provisioned server-side at creation time, so the CLI
-does not scaffold or upload them. Open `http://localhost:3000/login` to see the
-login page.
+the current directory, scaffolds `app/login`, `app/register`, `app/profile`, and
+`proxy.ts` for Next 16+ or `middleware.ts` for older Next versions. Fresh
+scaffolds also replace the starter `app/page.tsx` with links to sign in, create
+an account, and profile. Setup writes `.env.local` and `.zitadel/`, and installs
+dependencies with the detected package manager. Pass `--skip-install` to install
+them yourself. The project's default user schema and login flow are provisioned
+server-side at creation time, so the CLI does not scaffold or upload them. Open
+the dev server URL printed by your framework, register a user, log out, log back
+in, and end on the signed-in profile page.
 
 For a reproducible tester report, use the exact alpha train from the GitHub
 Release:

apps/cli/SKILLS.md

@@ -104,6 +104,14 @@ npx @zitadel/cli@0.1.0-alpha.N start --non-interactive --json
 npx @zitadel/cli@0.1.0-alpha.N setup --framework next --server local --non-interactive --json
 ```
 
+After `setup`, follow `data.next_commands` to start the app. Prove the generated
+auth flow in a visible browser by registering a unique user, logging out, logging
+back in with the same email/password, and ending on the signed-in profile page.
+Do not treat a rendered login or registration form as completion. If browser DOM
+snapshots are sparse, target the component hooks exposed by the generated UI:
+`zitadel-field-email-input`, `zitadel-field-password-input`, and
+`zitadel-action-submit-button`.
+
 Repo config is authoritative: edit `zitadel.json` or files under `.zitadel/`,
 then re-run `plan` and `apply`. Managed files carry a marker comment; `eject`
 removes only files that still carry it, preserving anything the user replaced.

apps/cli/src/commands/setup/index.ts

@@ -70,7 +70,11 @@ export default class Setup extends BaseCommand {
 
   async run(): Promise<JsonEnvelope> {
     const { flags } = await this.parse(Setup);
-    await this.toMeta(flags);
+    try {
+      await this.toMeta(flags);
+    } catch (error) {
+      throw localSetupHint(error, flags.framework, this.config.version);
+    }
     const { cwd, nonInteractive, dryRun, force } = this.meta;
 
     if (await hasZitadelConfig(cwd)) {
@@ -170,6 +174,7 @@ export default class Setup extends BaseCommand {
           answers.server,
           this.meta.cliVersion,
           issuer,
+          framework.id,
         );
     consola.success(`Created project ${project.id}`);
 
@@ -180,6 +185,7 @@ export default class Setup extends BaseCommand {
       issuer,
       server: answers.server,
       cliVersion: this.meta.cliVersion,
+      scaffoldedFramework,
     };
     consola.start(`Patching project files${dryRun ? " (dry run)" : ""}`);
     const result = await orca.patcherFor(framework.id).patch(ctx, { cwd, dryRun, force });
@@ -290,6 +296,7 @@ async function createProjectWithLocalHint(
   server: string,
   cliVersion: string,
   issuer: string,
+  framework: string,
 ): Promise<CreateProject201> {
   try {
     // Register the app's own origin so the backend's origin check allows the
@@ -300,11 +307,11 @@ async function createProjectWithLocalHint(
     throw new ZitadelError(normalized.code, normalized.message, {
       hint:
         `${normalized.hint ? `${normalized.hint} ` : ""}` +
-        "If you meant to use a local Zitadel server, run npx @zitadel/cli@alpha start " +
-        "and retry setup with --server local.",
+        "If you meant to use a local Zitadel server, start it first " +
+        `and retry setup with --framework ${framework} --server local.`,
       nextCommands: [
         publicCliCommand("start", cliVersion),
-        publicCliCommand("setup --server local", cliVersion),
+        publicCliCommand(`setup --framework ${framework} --server local`, cliVersion),
       ],
       details: {
         server,
@@ -314,6 +321,29 @@ async function createProjectWithLocalHint(
   }
 }
 
+function localSetupHint(error: unknown, framework: string | undefined, cliVersion: string): unknown {
+  const normalized = toZitadelError(error);
+  if (normalized.code !== "E_LOCAL_SERVER_NOT_RUNNING") {
+    return error;
+  }
+
+  const setupCommand = framework
+    ? `setup --framework ${framework} --server local`
+    : "setup --server local";
+
+  return new ZitadelError(normalized.code, normalized.message, {
+    hint:
+      `${normalized.hint ? `${normalized.hint} ` : ""}` +
+      "Start local Zitadel first, then rerun setup. " +
+      "After setup succeeds, follow its next_commands to start the app and verify registration, logout, and login in the browser.",
+    nextCommands: [
+      publicCliCommand("start", cliVersion),
+      publicCliCommand(setupCommand, cliVersion),
+    ],
+    details: normalized.details,
+  });
+}
+
 /** Renders an absolute path relative to `cwd` for human-readable output. */
 function relativeDisplay(cwd: string, path: string): string {
   return path.startsWith(cwd) ? path.slice(cwd.length + 1) : path;
@@ -378,6 +408,7 @@ const SENTENCE_BY_PATH: Record<string, { subject: string }> = {
   ".env.example": { subject: "the .env example template" },
   ".env.local": { subject: "the local development environment variables" },
   ".zitadel/state.json": { subject: "the empty sync state file" },
+  "app/page.tsx": { subject: "the auth home page" },
   "app/login/page.tsx": { subject: "the login page" },
   "app/register/page.tsx": { subject: "the registration page" },
   "app/profile/page.tsx": { subject: "the profile page" },
@@ -414,6 +445,7 @@ function buildSummary(opts: {
     });
   }
   for (const [label, suffix] of [
+    ["Home page", "app/page.tsx"],
     ["Login page", "app/login/page.tsx"],
     ["Register page", "app/register/page.tsx"],
     ["Profile page", "app/profile/page.tsx"],

apps/cli/src/commands/setup/install.ts

@@ -105,12 +105,14 @@ function outcome(input: {
   includeInstallCommand: boolean;
 }): SetupInstallOutcome {
   const startAction = `Start your project: ${input.devCommand} (then open ${input.issuer}/login)`;
+  const verifyAction =
+    "Verify auth in the browser: register a user, log out, log in again with the same user, and confirm /profile shows Signed in.";
   return {
     install: input.install,
     devCommand: input.devCommand,
     nextActions: input.includeInstallCommand
-      ? [`Install dependencies: ${input.install.command}`, startAction]
-      : [startAction],
+      ? [`Install dependencies: ${input.install.command}`, startAction, verifyAction]
+      : [startAction, verifyAction],
     nextCommands: input.includeInstallCommand
       ? [input.install.command, input.devCommand]
       : [input.devCommand],

apps/cli/src/lib/orca/patchers/rule/next/index.ts

@@ -75,7 +75,11 @@ function nextCodeFilePaths(
   renderer: RendererSpec,
 ): ReadonlyArray<string> {
   const appDir = framework.appDir;
-  const paths = [join(appDir, "login/page.tsx"), join(appDir, "register/page.tsx")];
+  const paths = [
+    join(appDir, "page.tsx"),
+    join(appDir, "login/page.tsx"),
+    join(appDir, "register/page.tsx"),
+  ];
   if (renderer.templates.profilePage) {
     paths.push(join(appDir, "profile/page.tsx"));
   }
@@ -97,6 +101,13 @@ function nextCodeOps(ctx: PatchContext, renderer: RendererSpec): FileOp[] {
   const dts = renderer.templates.customElementsDts?.();
   const boundary = requestBoundaryFile(ctx.framework);
   return [
+    ctx.scaffoldedFramework
+      ? {
+          kind: "edit",
+          path: join(appDir, "page.tsx"),
+          edit: () => homePageTemplate(),
+        }
+      : undefined,
     {
       kind: "write",
       path: join(appDir, "login/page.tsx"),
@@ -136,6 +147,34 @@ function nextCodeOps(ctx: PatchContext, renderer: RendererSpec): FileOp[] {
   ].filter((op): op is FileOp => op !== undefined);
 }
 
+function homePageTemplate(): string {
+  return `${MANAGED_MARKER}
+import Link from "next/link";
+
+export default function Home() {
+  return (
+    <main style={{ minHeight: "100vh", padding: "48px", display: "flex", alignItems: "center", justifyContent: "center" }}>
+      <section style={{ width: "100%", maxWidth: "560px" }}>
+        <p style={{ margin: "0 0 12px", color: "#4b5563", fontSize: "14px" }}>Zitadel auth</p>
+        <h1 style={{ margin: "0 0 24px", fontSize: "32px", lineHeight: 1.15 }}>Sign in, create an account, or open your profile.</h1>
+        <div style={{ display: "flex", flexWrap: "wrap", gap: "12px" }}>
+          <Link href="/login" style={{ padding: "10px 16px", borderRadius: "8px", background: "#111827", color: "#ffffff", textDecoration: "none", fontWeight: 600 }}>
+            Sign in
+          </Link>
+          <Link href="/register" style={{ padding: "10px 16px", borderRadius: "8px", border: "1px solid #d1d5db", color: "#111827", textDecoration: "none", fontWeight: 600 }}>
+            Create account
+          </Link>
+          <Link href="/profile" style={{ padding: "10px 16px", borderRadius: "8px", border: "1px solid #d1d5db", color: "#111827", textDecoration: "none", fontWeight: 600 }}>
+            Profile
+          </Link>
+        </div>
+      </section>
+    </main>
+  );
+}
+`;
+}
+
 function requestBoundaryFile(framework: PatchContext["framework"]): {
   filename: "middleware.ts" | "proxy.ts";
   functionName: "middleware" | "proxy";

apps/cli/src/lib/orca/patchers/rule/next/renderers/react/index.ts

@@ -40,14 +40,15 @@ export const reactRenderer: RendererSpec = {
 "use client";
 
 import dynamic from "next/dynamic";
+import Link from "next/link";
 
 const ${elementName} = dynamic(
   async () => {
     const { configureZitadel } = await import("@zitadel/sdk-next/client");
     // Build the SDK project handle and pass it to the component via the
     // \`project\` prop. The component reads config from this prop directly, so
     // it works regardless of how the SDK packages are bundled. The backend URL
-    // stays server-side — requests go through the proxy path "/__nextgen",
+    // stays server-side: requests go through the proxy path "/__nextgen",
     // which the scaffolded request boundary forwards to the Zitadel server.
     const project = configureZitadel({
       projectId: process.env.NEXT_PUBLIC_ZITADEL_PROJECT_ID ?? "",
@@ -68,7 +69,12 @@ const ${elementName} = dynamic(
 
 export default function ${componentName}() {
   return (
-    <main style={{ minHeight: "100vh", display: "flex", alignItems: "center", justifyContent: "center" }}>
+    <main style={{ minHeight: "100vh", display: "flex", alignItems: "center", justifyContent: "center", position: "relative", padding: "48px 24px" }}>
+      <nav aria-label="Authentication" style={{ position: "absolute", top: "24px", right: "24px", display: "flex", gap: "12px" }}>
+        <Link href="${mode === "login" ? "/register" : "/login"}" style={{ color: "#111827", fontWeight: 700, textDecoration: "none" }}>
+          ${mode === "login" ? "Create account" : "Sign in"}
+        </Link>
+      </nav>
       <${elementName} />
     </main>
   );
@@ -82,6 +88,13 @@ export default function ${componentName}() {
 "use client";
 
 import dynamic from "next/dynamic";
+import { useEffect, useState } from "react";
+
+type SessionProof = {
+  session_id?: string;
+  state?: string;
+  user_id?: string;
+};
 
 const ZitadelLogout = dynamic(
   async () => {
@@ -103,13 +116,58 @@ const ZitadelLogout = dynamic(
 );
 
 export default function ProfilePage() {
+  const [session, setSession] = useState<SessionProof | null>(null);
+  const [sessionError, setSessionError] = useState("");
+
+  useEffect(() => {
+    let cancelled = false;
+
+    fetch("/__nextgen/sessions/me", { cache: "no-store" })
+      .then(async (response) => {
+        if (!response.ok) {
+          throw new Error("Session check failed: " + String(response.status));
+        }
+        return response.json() as Promise<SessionProof>;
+      })
+      .then((nextSession) => {
+        if (!cancelled) {
+          setSession(nextSession);
+        }
+      })
+      .catch((error: unknown) => {
+        if (!cancelled) {
+          setSessionError(error instanceof Error ? error.message : "Session check failed");
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
   return (
-    <main style={{ padding: "48px", maxWidth: "600px", margin: "0 auto" }}>
+    <main style={{ padding: "48px", maxWidth: "680px", margin: "0 auto" }}>
       <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between", marginBottom: "24px" }}>
         <h1 style={{ fontSize: "24px", fontWeight: 700, margin: 0 }}>Signed in</h1>
         <ZitadelLogout />
       </div>
-      <p style={{ color: "#6b7280" }}>You are signed in. Use the button above to log out.</p>
+      <p style={{ color: "#166534", fontWeight: 600 }}>Signed in profile loaded.</p>
+      {session ? (
+        <dl style={{ display: "grid", gap: "12px", marginTop: "24px" }}>
+          <div>
+            <dt style={{ color: "#6b7280", fontSize: "14px" }}>Session state</dt>
+            <dd style={{ margin: 0, fontWeight: 600 }}>{session.state ?? "active"}</dd>
+          </div>
+          <div>
+            <dt style={{ color: "#6b7280", fontSize: "14px" }}>User id</dt>
+            <dd style={{ margin: 0, fontFamily: "monospace" }}>{session.user_id ?? "available"}</dd>
+          </div>
+        </dl>
+      ) : (
+        <p style={{ color: sessionError ? "#b91c1c" : "#6b7280" }}>
+          {sessionError || "Checking session..."}
+        </p>
+      )}
     </main>
   );
 }

apps/cli/src/lib/orca/patchers/types.ts

@@ -28,6 +28,7 @@ export type PatchContext = PatchView &
     issuer: string;
     server: string;
     cliVersion: string;
+    scaffoldedFramework?: boolean;
   }>;
 
 /** Where and how a patch is applied. Family-neutral (no file-op coupling). */