@helloleo/plugins 0.2.11 → 0.2.13

package/src/templates/tanstack-start-2026-07-30/src/routes/README.md

@@ -0,0 +1,94 @@
+# Routes
+
+TanStack Start uses file-based routing. Every `.ts` and `.tsx` file in this directory is a route. Do not create `src/pages/`, `app/layout.tsx`, or similar, those are Next.js / Remix conventions. The only root layout is `src/routes/__root.tsx`.
+
+## Conventions
+
+| File | URL |
+| --- | --- |
+| `index.tsx` | `/` |
+| `about.tsx` | `/about` |
+| `users/index.tsx` | `/users` |
+| `users/$id.tsx` | `/users/:id` (dynamic — bare `$`, no curly braces) |
+| `posts.$postId.tsx` | `/posts/:postId` (dots nest without folders) |
+| `admin/route.tsx` | layout for every `/admin/*` page; must render `<Outlet />` |
+| `admin_.login.tsx` | `/admin/login`, but outside the admin layout (trailing `_` escapes it) |
+| `_auth.tsx` | pathless layout; wraps `_auth/*` files without adding a URL segment |
+| `api/health.ts` | server route for defining API endpoints |
+| `__root.tsx` | app shell, wraps every page; preserve `<Outlet />` |
+
+## Rules
+
+- A layout route without `<Outlet />` renders its children nowhere.
+- Do not `export default` route components, it breaks code splitting. Use a named function passed as `component:`.
+- `routeTree.gen.ts` is auto-generated. Don't edit it by hand.
+
+## API routes vs server functions
+
+TanStack Start offers two ways to run server-side code:
+
+- [Server routes](https://tanstack.com/start/latest/docs/framework/react/guide/server-routes) — files under `src/routes/api/` that export HTTP handlers.
+- [Server functions](https://tanstack.com/start/latest/docs/framework/react/guide/server-functions) — `createServerFn()` calls colocated with components.
+
+Prefer API routes. Create them under `src/routes/api/` following the same convention as `src/routes/api/health.ts` (one handler per HTTP method under `server.handlers`, returning `Response.json()`). This is more scalable and gives the user visually readable endpoints (`/api/todos`, `/api/todos/:id`) they can recognize in the network monitor. Server functions are served from generated URLs that read as random gibberish, which makes requests hard to identify and debug.
+
+## Authenticated routes
+
+Put protected pages inside a pathless `_authed` layout and keep login/signup
+at the top level, outside it. Never special-case the login pathname inside
+the layout guard.
+
+```
+routes/
+  __root.tsx          loads the session into router context (context.user)
+  _authed.tsx         pathless guard — no URL segment of its own
+  _authed/
+    dashboard.tsx     /dashboard (protected)
+    posts.tsx         /posts     (protected)
+  index.tsx           /          (public)
+  login.tsx           /login     (public)
+  logout.tsx          /logout
+```
+
+`_authed.tsx` does the guarding, all children inherit it:
+
+```tsx _authed.tsx
+export const Route = createFileRoute('/_authed')({
+  beforeLoad: ({ context }) => {
+    if (!context.user) {
+      throw redirect({ to: '/login' })
+    }
+  },
+})
+```
+
+The session is loaded once in `__root.tsx`'s `beforeLoad` and returned into
+the router context so every route can read `context.user`. `getUser()` is
+whatever your auth uses (e.g. verify a JWT from localStorage) and resolves to
+the user or null:
+
+```tsx __root.tsx
+// (keep the existing head() and component, add this)
+export const Route = createRootRouteWithContext<{ queryClient: QueryClient }>()({
+  beforeLoad: async () => {
+    const user = await getUser()
+    return { user }
+  },
+  // ...head, component unchanged
+})
+```
+
+Components read it with `Route.useRouteContext()` (e.g. to swap a Login link
+for a Logout button in the shell):
+
+```tsx
+function Route() {
+  const { user } = Route.useRouteContext()
+  
+  return (
+    <nav>
+      {user ? <Link to="/logout">Logout</Link> : <Link to="/login">Login</Link>}
+    </nav>
+  )
+}
+```

package/src/templates/tanstack-start-2026-07-30/src/routes/__root.tsx

@@ -0,0 +1,65 @@
+import {
+  HeadContent,
+  Outlet,
+  Scripts,
+  createRootRouteWithContext,
+} from '@tanstack/react-router'
+import type { QueryClient } from '@tanstack/react-query'
+import type { ReactNode } from 'react'
+import { Toaster } from '@/components/ui/sonner'
+
+// Side-effect order matters: Tailwind needs to be linked into the SSR'd
+// document. Importing the stylesheet as a URL and listing it in `head.links`
+// is the Start-native way (a bare `import './styles.css'` only works client-side).
+import appCss from '../styles.css?url'
+
+export const Route = createRootRouteWithContext<{ queryClient: QueryClient }>()({
+  head: () => ({
+    meta: [
+      { charSet: 'utf-8' },
+      { name: 'viewport', content: 'width=device-width, initial-scale=1.0' },
+      { title: '{{LEO_NAME}}' },
+      { name: 'description', content: '{{LEO_DESCRIPTION}}' },
+      { property: 'og:title', content: '{{LEO_NAME}}' },
+      { property: 'og:description', content: '{{LEO_DESCRIPTION}}' },
+      { property: 'og:type', content: 'website' },
+    ],
+    links: [
+      { rel: 'stylesheet', href: appCss },
+      { rel: 'preconnect', href: 'https://fonts.googleapis.com' },
+      {
+        rel: 'preconnect',
+        href: 'https://fonts.gstatic.com',
+        crossOrigin: 'anonymous',
+      },
+      {
+        rel: 'stylesheet',
+        href: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Space+Grotesk:wght@400;500;600;700&display=swap',
+      },
+    ],
+  }),
+  component: RootComponent,
+})
+
+function RootComponent() {
+  return (
+    <RootDocument>
+      <Outlet />
+    </RootDocument>
+  )
+}
+
+function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
+  return (
+    <html lang="en">
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        {children}
+        <Toaster richColors position="top-right" />
+        <Scripts />
+      </body>
+    </html>
+  )
+}

package/src/templates/tanstack-start-2026-07-30/src/routes/api/health.ts

@@ -0,0 +1,81 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { db } from '#/db'
+import { entries } from '#/db/schema'
+
+/**
+ * Server route example: GET /api/health. Use this file as the base for
+ * building JSON APIs (CRUD endpoints, webhooks) with TanStack Start
+ * server routes:
+ * https://tanstack.com/start/latest/docs/framework/react/guide/server-routes
+ *
+ * How server routes work:
+ * - Files under src/routes/ can export server handlers. The URL matches
+ *   the file path: src/routes/api/health.ts serves /api/health.
+ * - Add one handler per HTTP method under server.handlers (GET, POST,
+ *   PUT, PATCH, DELETE). A handler receives ({ request, params }) and
+ *   returns a Response, usually Response.json().
+ * - Dynamic segments use $: src/routes/api/todos/$id.ts serves
+ *   /api/todos/:id and the handler reads params.id.
+ * - Read the request body with await request.json() and validate it
+ *   before use. Return proper status codes (201 created, 404 not found).
+ * - Query the database with `import { db } from '#/db'` INSIDE the
+ *   handler, never at module scope (the binding only exists per request).
+ */
+export const Route = createFileRoute('/api/health')({
+  server: {
+    handlers: {
+      GET: async () => {
+        const startedAt = Date.now()
+
+        const server = {
+          status: 'ok' as const,
+          uptimeSeconds: Math.round(
+            typeof process !== 'undefined' &&
+              typeof process.uptime === 'function'
+              ? process.uptime()
+              : 0,
+          ),
+          timestamp: new Date().toISOString(),
+          runtime: 'cloudflare-workers',
+        }
+
+        // Database health: lightweight query against a known table
+        let database: {
+          status: 'ok' | 'error'
+          latencyMs: number
+          error: string | null
+        }
+        const dbStart = Date.now()
+        try {
+          await db.select({ id: entries.id }).from(entries).limit(1)
+          database = {
+            status: 'ok',
+            latencyMs: Date.now() - dbStart,
+            error: null,
+          }
+        } catch (err) {
+          database = {
+            status: 'error',
+            latencyMs: Date.now() - dbStart,
+            error: err instanceof Error ? err.message : String(err),
+          }
+        }
+
+        const overall =
+          server.status === 'ok' && database.status === 'ok'
+            ? 'ok'
+            : 'degraded'
+
+        return Response.json(
+          {
+            status: overall,
+            server,
+            database,
+            checkedInMs: Date.now() - startedAt,
+          },
+          { status: overall === 'ok' ? 200 : 503 },
+        )
+      },
+    },
+  },
+})

package/src/templates/tanstack-start-2026-07-30/src/routes/index.tsx

@@ -0,0 +1,33 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+
+// Server functions run only on the server (dev: node + cf-shim; prod: the
+// worker). This is the seam where you read your bindings — import { db } from
+// '#/db' and query Drizzle, or import { kv, storage } from '@helloleo/runtime'.
+// Keep binding access INSIDE the handler, never at module scope.
+const getMessage = createServerFn({ method: 'GET' }).handler(() => {
+  return { message: 'Hello from the server' }
+})
+
+export const Route = createFileRoute('/')({
+  component: Home,
+  loader: () => getMessage(),
+})
+
+/**
+ * Do not `export default function Home()`. This breaks the default
+ * codesplitting by Tanstack Router.
+ */
+function Home() {
+  const { message } = Route.useLoaderData()
+
+  return (
+    <div className="p-8">
+      <h1 className="text-4xl font-bold">Welcome to HelloLeo</h1>
+      <p className="mt-4 text-lg">{message}</p>
+      <p className="mt-2 text-sm text-muted-foreground">
+        Edit <code>src/routes/index.tsx</code> to get started.
+      </p>
+    </div>
+  )
+}

package/src/templates/tanstack-start-2026-07-30/src/server.ts

@@ -0,0 +1,32 @@
+// Cloudflare Worker entry (the Worker `main`, configured by @helloleo/vite-config).
+// Wraps the TanStack Start server entry so an SSR failure renders a clean 500
+// instead of a raw stack.
+type ServerEntry = {
+  fetch: (request: Request, env: unknown, ctx: unknown) => Promise<Response> | Response
+}
+
+let serverEntryPromise: Promise<ServerEntry> | undefined
+
+async function getServerEntry(): Promise<ServerEntry> {
+  if (!serverEntryPromise) {
+    serverEntryPromise = import('@tanstack/react-start/server-entry').then(
+      (m) => ((m as { default?: ServerEntry }).default ?? m) as ServerEntry,
+    )
+  }
+  return serverEntryPromise
+}
+
+export default {
+  async fetch(request: Request, env: unknown, ctx: unknown) {
+    try {
+      const handler = await getServerEntry()
+      return await handler.fetch(request, env, ctx)
+    } catch (error) {
+      console.error(error)
+      return new Response('<h1>Something went wrong</h1>', {
+        status: 500,
+        headers: { 'content-type': 'text/html; charset=utf-8' },
+      })
+    }
+  },
+}

package/src/templates/tanstack-start-2026-07-30/src/styles.css

@@ -0,0 +1,214 @@
+/*
+ * HelloLeo Design System -- READ BEFORE STYLING.
+ *
+ * Design tokens are the single source of truth and power the no-code Design
+ * panel (the user edits colors / fonts / radius visually). Conventions:
+ *   - Raw tokens live in :root (light) and .dark (dark). The @media
+ *     (prefers-color-scheme: dark) block mirrors .dark so apps follow the OS
+ *     by default; adding the `dark` class still forces dark explicitly.
+ *   - @theme inline maps each raw token to a Tailwind utility
+ *     (bg-background, text-foreground, rounded-lg, ...). Edit the raw token,
+ *     not the component class. Never hardcode #hex in components.
+ *   - When you add a color token, add it to :root, .dark, AND the media block,
+ *     or one theme breaks.
+ *
+ * UI primitives live in src/components/ui (shadcn/ui) and consume these
+ * tokens. One responsibility per file.
+ */
+
+@import "tailwindcss" source(none);
+@source "../src";
+@import "tw-animate-css";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --font-sans: "Inter", system-ui, sans-serif;
+  --font-display: "Space Grotesk", "Inter", sans-serif;
+}
+
+:root {
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --destructive-foreground: oklch(0.985 0 0);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.205 0 0);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
+}
+
+/* Dark palette -- kept identical in .dark (explicit) and the media block
+ * (system default). Edit BOTH when changing a token. */
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --destructive-foreground: oklch(0.985 0 0);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+  --sidebar: oklch(0.205 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.269 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.556 0 0);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: oklch(0.145 0 0);
+    --foreground: oklch(0.985 0 0);
+    --card: oklch(0.205 0 0);
+    --card-foreground: oklch(0.985 0 0);
+    --popover: oklch(0.205 0 0);
+    --popover-foreground: oklch(0.985 0 0);
+    --primary: oklch(0.922 0 0);
+    --primary-foreground: oklch(0.205 0 0);
+    --secondary: oklch(0.269 0 0);
+    --secondary-foreground: oklch(0.985 0 0);
+    --muted: oklch(0.269 0 0);
+    --muted-foreground: oklch(0.708 0 0);
+    --accent: oklch(0.269 0 0);
+    --accent-foreground: oklch(0.985 0 0);
+    --destructive: oklch(0.704 0.191 22.216);
+    --destructive-foreground: oklch(0.985 0 0);
+    --border: oklch(1 0 0 / 10%);
+    --input: oklch(1 0 0 / 15%);
+    --ring: oklch(0.556 0 0);
+    --chart-1: oklch(0.488 0.243 264.376);
+    --chart-2: oklch(0.696 0.17 162.48);
+    --chart-3: oklch(0.769 0.188 70.08);
+    --chart-4: oklch(0.627 0.265 303.9);
+    --chart-5: oklch(0.645 0.246 16.439);
+    --sidebar: oklch(0.205 0 0);
+    --sidebar-foreground: oklch(0.985 0 0);
+    --sidebar-primary: oklch(0.488 0.243 264.376);
+    --sidebar-primary-foreground: oklch(0.985 0 0);
+    --sidebar-accent: oklch(0.269 0 0);
+    --sidebar-accent-foreground: oklch(0.985 0 0);
+    --sidebar-border: oklch(1 0 0 / 10%);
+    --sidebar-ring: oklch(0.556 0 0);
+  }
+}
+
+@layer base {
+  * {
+    border-color: var(--color-border);
+  }
+  html,
+  body {
+    font-family: var(--font-sans);
+  }
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+    min-height: 100vh;
+  }
+  h1, h2, h3, h4 {
+    font-family: var(--font-display);
+    letter-spacing: -0.02em;
+  }
+}
+
+@layer utilities {
+  .prose-note {
+    color: var(--color-foreground);
+  }
+  .prose-note h1 { font-size: 1.875rem; font-weight: 700; margin: 1.25rem 0 0.75rem; font-family: var(--font-display); }
+  .prose-note h2 { font-size: 1.5rem; font-weight: 600; margin: 1rem 0 0.5rem; font-family: var(--font-display); }
+  .prose-note h3 { font-size: 1.25rem; font-weight: 600; margin: 0.875rem 0 0.5rem; }
+  .prose-note p { margin: 0.5rem 0; line-height: 1.7; }
+  .prose-note ul { list-style: disc; padding-left: 1.5rem; margin: 0.5rem 0; }
+  .prose-note ol { list-style: decimal; padding-left: 1.5rem; margin: 0.5rem 0; }
+  .prose-note li { margin: 0.25rem 0; }
+  .prose-note a { color: var(--color-primary); text-decoration: underline; }
+  .prose-note code { background: var(--color-muted); padding: 0.125rem 0.375rem; border-radius: 0.25rem; font-size: 0.875em; }
+  .prose-note pre { background: var(--color-muted); padding: 1rem; border-radius: 0.5rem; overflow-x: auto; margin: 0.75rem 0; }
+  .prose-note pre code { background: transparent; padding: 0; }
+  .prose-note blockquote { border-left: 3px solid var(--color-primary); padding-left: 1rem; margin: 0.75rem 0; color: var(--color-muted-foreground); }
+  .prose-note hr { border-color: var(--color-border); margin: 1.5rem 0; }
+  .prose-note table { border-collapse: collapse; margin: 0.75rem 0; }
+  .prose-note th, .prose-note td { border: 1px solid var(--color-border); padding: 0.375rem 0.75rem; }
+}

package/src/templates/tanstack-start-2026-07-30/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "include": ["**/*.ts", "**/*.tsx"],
+  "compilerOptions": {
+    "target": "ES2022",
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "paths": {
+      "#/*": ["./src/*"],
+      "@/*": ["./src/*"]
+    },
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["@cloudflare/workers-types", "vite/client"],
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+
+    /* Linting */
+    "skipLibCheck": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  }
+}

package/src/templates/tanstack-start-2026-07-30/vite.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from '@helloleo/vite-config'
+
+// @helloleo/vite-config owns the whole build/dev/sandbox pipeline: in dev it
+// aliases `cloudflare:workers` -> @helloleo/runtime/cf-shim (libsql .dev.db for
+// D1+KV, local disk for R2) and runs plain Vite SSR; at build it adds
+// @cloudflare/vite-plugin to emit a workerd Worker bound to wrangler.jsonc. It
+// also binds host:true/port:5173 itself (>=0.1.2).
+//
+// The one thing the wrapper doesn't set: HMR over the HelloLeo preview proxy,
+// which terminates HTTPS on :443 — so point the HMR client at wss://…:443.
+export default defineConfig({
+  vite: {
+    server: {
+      hmr: { clientPort: 443, protocol: 'wss' },
+    },
+  },
+})

package/src/tools/scaffold.ts

@@ -18,7 +18,7 @@ import { renderTemplate } from "../template-render.ts";
  *   no database.
  */
 export const SCAFFOLD_TEMPLATES = {
-	"tanstack-start": "tanstack-start-2026-06-18",
+	"tanstack-start": "tanstack-start-2026-07-30",
 	"tanstack-router": "tanstack-router-2026-06-15",
 } as const;
 
@@ -152,7 +152,7 @@ export const scaffold = tool({
 			? [
 					"- This is a TanStack Start project. The server entry is src/server.ts. There is no index.html or client entrypoint.",
 					"- For JSON/CRUD APIs, add server routes under src/routes/api/. Read src/routes/api/health.ts first, add routes as needed.",
-					"- The database schema lives in src/db/schema.ts. Migrations run automatically.",
+					"- The database schema lives in src/db/schema.ts and is the single source of truth. Migration files under drizzle/ are generated and applied automatically. Never create, edit or delete them. Prefer adding new columns/tables over renaming existing ones.",
 				]
 			: [
 					"- This is a TanStack Router SPA. The client entry is index.html -> src/main.tsx. There is no server: no API routes, no server functions, no database.",

package/src/tools/setup-authentication/index.ts

@@ -29,14 +29,32 @@ import {
  *
  * Mutually exclusive with setup_netsuite: both own src/routes/login.tsx and
  * the app's one auth strategy. Called AFTER `scaffold`, never instead of it.
+ *
+ * Only applies to full-stack (tanstack-start) scaffolds: the files it writes
+ * assume a server (API routes, drizzle schema). On a tanstack-router SPA it
+ * returns an error instead of writing broken server code.
+ */
+
+/**
+ * Scaffold id recorded by the scaffold tool in .leo/project.json, or null if
+ * the file is missing/unreadable (pre-project.json workspaces: don't block).
  */
+async function readScaffoldId(dir: string): Promise<string | null> {
+	try {
+		const meta = await Bun.file(path.join(dir, ".leo", "project.json")).json();
+		return typeof meta?.scaffold === "string" ? meta.scaffold : null;
+	} catch {
+		return null;
+	}
+}
 export const setupAuthentication = tool({
 	description:
 		"Add authentication to an existing project via better-auth. Call scaffold first, " +
 		"then this. providers: 'password' for email/password, plus any of " +
 		"'google' | 'github' | 'discord' | 'microsoft' for social sign-in -- pass any " +
 		"combination. Mutually exclusive with setup_netsuite: an app has one auth " +
-		"strategy, not two.",
+		"strategy, not two. Only for full-stack (tanstack-start) scaffolds; errors " +
+		"on client-only SPA projects.",
 	args: {
 		providers: z
 			.array(z.enum(PROVIDERS))
@@ -45,6 +63,16 @@ export const setupAuthentication = tool({
 	},
 	async execute({ providers }, context) {
 		const dir = context.directory;
+
+		const scaffoldId = await readScaffoldId(dir);
+		if (scaffoldId !== null && !scaffoldId.startsWith("tanstack-start")) {
+			return [
+				"Error: setup_authentication is for full-stack applications and is not applicable to HelloLeo Cloud.",
+				"This project is a client-only SPA (tanstack-router): no server, no API routes, no database, so the files this tool writes cannot work here.",
+				"Do not mention this error to the user. Continue by setting up authentication manually by activating HelloLeo Backend and using the MCP.",
+			].join("\n");
+		}
+
 		const hasPassword = providers.includes("password");
 		const oauth = providers.filter((p): p is OAuthProvider => p !== "password");