@helloleo/plugins 0.2.16 → 0.2.19

package/src/tools/setup-netsuite.ts

@@ -1,21 +1,800 @@
-import { mkdir } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import type { Plugin } from "@opencode-ai/plugin";
 import { tool } from "@opencode-ai/plugin";
 
 /**
- * Adds NetSuite OAuth wiring on top of an existing scaffold: the netsuite
- * OAuth client, a NetSuite auth context (auth.tsx), and the AuthLayout /
- * LoginPage / SignInWithNetSuite components. It never overwrites a
- * scaffold file -- the one manual step is wrapping the root route's
- * <Outlet /> with <AuthLayout> (the tool's output shows the snippet).
- * All NetSuite-specific templates live in this file -- one place to read
- * or change anything NetSuite-related.
+ * NetSuite runtime OAuth (end-user LOGIN). Two variants:
+ *
+ * - DEFAULT (every scaffold type): client-only files; the OAuth backend is
+ *   the per-project HelloLeo Cloud Worker (VITE_WORKER_URL), sign-in runs in
+ *   a popup + postMessage so it works inside the HelloLeo preview iframe.
+ *   This matches prod: the platform wizard registers the Worker's fixed
+ *   /auth/netsuite/callback as the ONE redirect URI on Integration Record #2
+ *   (provision-first, see webapp netsuiteRuntimeSetup).
+ * - IN-APP (opt-in: PLUGINS_NETSUITE_IN_APP=1 + tanstack-start scaffold):
+ *   the app IS the backend. Emits server routes (/auth/netsuite/* + /api/me),
+ *   netsuite_flows + netsuite_sessions drizzle tables, and a same-origin
+ *   client. Only valid when the deployment registers the APP's own callback
+ *   on the Integration Record instead of the Worker's.
+ *
+ * Both variants share the same component names (AuthLayout / LoginPage /
+ * SignInWithNetSuite) and the same wiring step: wrap the root route's
+ * <Outlet /> with <AuthLayout>. LoginPage is a deliberately bare placeholder
+ * in both -- Leo designs it per app.
+ *
+ * This login uses NetSuite Integration Record #2 (scope: rest_webservices),
+ * a SEPARATE record from the MCP one (scope: mcp) used only to BUILD the app.
  *
  * Called AFTER `scaffold`, never instead of it.
  */
 
-function netsuiteTs(): string {
+/**
+ * Scaffold id recorded by the scaffold tool in .leo/project.json, or null if
+ * the file is missing/unreadable (pre-project.json workspaces).
+ */
+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;
+	}
+}
+
+// --- emitted: src/db/schema.ts (appended) --------------------------------
+function schemaAppend(): string {
+	return `
+// --- NetSuite OAuth (added by setup_netsuite) ---
+// Short-lived PKCE + return-to state between /auth/netsuite/start and its
+// callback. Single-use: the callback deletes the row after reading it.
+export const netsuiteFlows = sqliteTable('netsuite_flows', {
+  flowId: text('flow_id').primaryKey(),
+  codeVerifier: text('code_verifier').notNull(),
+  returnTo: text('return_to').notNull(),
+  createdAt: integer('created_at')
+    .notNull()
+    .default(sql\`(unixepoch())\`),
+})
+
+// Opaque session id -> NetSuite tokens. Tokens stay server-side; the browser
+// only ever holds the sid (sent as a bearer).
+export const netsuiteSessions = sqliteTable('netsuite_sessions', {
+  sid: text('sid').primaryKey(),
+  accountId: text('account_id').notNull(),
+  accessToken: text('access_token').notNull(),
+  refreshToken: text('refresh_token'),
+  expiresAt: integer('expires_at'),
+  userId: text('user_id'),
+  email: text('email'),
+  createdAt: integer('created_at')
+    .notNull()
+    .default(sql\`(unixepoch())\`),
+})
+`;
+}
+
+// --- emitted: src/lib/netsuite-server.ts ---------------------------------
+function netsuiteServerTs(): string {
+	return `/*
+ * NetSuite runtime OAuth -- server side (TanStack Start server routes).
+ *
+ * Runs wherever the app runs: \`vite dev\` (workerd) in the Fly preview machine
+ * in dev, and the published Cloudflare Worker in prod. There is no separate
+ * backend Worker -- these helpers back the /auth/netsuite/* + /api/me routes.
+ *
+ * Config is read from the Cloudflare env binding via @helloleo/runtime.
+ * Set NETSUITE_ACCOUNT_ID / _CLIENT_ID / _CLIENT_SECRET (secret optional for a
+ * PKCE public client) and optional PUBLIC_APP_URL as HelloLeo Cloud secrets
+ * (prod) or dev vars (preview). They never reach the browser.
+ */
+import { eq } from 'drizzle-orm'
+import { env as runtimeEnv } from '@helloleo/runtime'
+import { db } from '#/db'
+import { netsuiteSessions } from '#/db/schema'
+
+interface NsEnv {
+  NETSUITE_ACCOUNT_ID?: string
+  NETSUITE_CLIENT_ID?: string
+  NETSUITE_CLIENT_SECRET?: string
+  PUBLIC_APP_URL?: string
+  HELLOLEO_URL?: string
+}
+const nsEnv = runtimeEnv as unknown as NsEnv
+
+// Runtime record scope. The app signs end-users in for REST/SuiteQL.
+export const SCOPE = 'rest_webservices'
+const REFRESH_LEEWAY_SECONDS = 60
+
+export function requireConfig() {
+  const accountId = nsEnv.NETSUITE_ACCOUNT_ID
+  const clientId = nsEnv.NETSUITE_CLIENT_ID
+  if (!accountId || !clientId) {
+    throw new Error(
+      'NetSuite not configured: set NETSUITE_ACCOUNT_ID and NETSUITE_CLIENT_ID (and NETSUITE_CLIENT_SECRET for a confidential client) as HelloLeo Cloud secrets / dev vars.',
+    )
+  }
+  return { accountId, clientId, clientSecret: nsEnv.NETSUITE_CLIENT_SECRET || '' }
+}
+
+// Account id -> DNS host form: lowercase, underscores to hyphens.
+function host(accountId: string) {
+  return accountId.trim().toLowerCase().replace(/_/g, '-')
+}
+export function authorizeUrl(accountId: string) {
+  return \`https://\${host(accountId)}.app.netsuite.com/app/login/oauth2/authorize.nl\`
+}
+export function tokenUrl(accountId: string) {
+  return \`https://\${host(accountId)}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token\`
+}
+export function restBase(accountId: string) {
+  return \`https://\${host(accountId)}.suitetalk.api.netsuite.com\`
+}
+
+function stripTrailingSlash(s: string) {
+  return s.endsWith('/') ? s.slice(0, -1) : s
+}
+
+// Public origin of THIS app, used to build the redirect URI. Prefer an explicit
+// PUBLIC_APP_URL; else derive from the request (honouring the preview proxy's
+// forwarded headers). Must match a redirect URI registered on the NetSuite
+// Integration Record exactly.
+export function appOrigin(request: Request) {
+  // 1) Explicit override wins (set by the platform per environment).
+  if (nsEnv.PUBLIC_APP_URL) return stripTrailingSlash(nsEnv.PUBLIC_APP_URL)
+  // 2) HELLOLEO_URL is injected on every deploy (the app's canonical origin,
+  //    a bare host with no scheme), so it's set even when the NetSuite
+  //    wizard's PUBLIC_APP_URL pin wasn't.
+  if (nsEnv.HELLOLEO_URL) return \`https://\${stripTrailingSlash(nsEnv.HELLOLEO_URL)}\`
+  // 3) Preview/prod proxies rewrite Host, so trust the forwarded/original host
+  //    they set (HelloLeo's nginx sends X-Original-Host) — that's the public URL
+  //    the browser loaded, not an internal upstream host.
+  const url = new URL(request.url)
+  const proto = request.headers.get('x-forwarded-proto') || url.protocol.replace(':', '')
+  const hostHeader =
+    request.headers.get('x-forwarded-host') ||
+    request.headers.get('x-original-host') ||
+    url.host
+  return \`\${proto}://\${hostHeader}\`
+}
+export function redirectUri(request: Request) {
+  return \`\${appOrigin(request)}/auth/netsuite/callback\`
+}
+
+// Coerce ?return_to= to our OWN origin. The callback appends the session bearer
+// as a #nssid=... fragment; an off-origin return_to would leak that live
+// credential to an attacker-controlled page (open-redirect -> token theft).
+export function safeReturnTo(request: Request, raw: string | null): string {
+  const origin = appOrigin(request)
+  if (!raw) return origin
+  try {
+    const u = new URL(raw, origin)
+    return u.origin === origin ? u.toString() : origin
+  } catch {
+    return origin
+  }
+}
+
+// --- PKCE (Web Crypto: works on workerd and Node) ---
+function b64url(bytes: Uint8Array) {
+  let s = ''
+  for (const b of bytes) s += String.fromCharCode(b)
+  return btoa(s).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '')
+}
+export async function pkce() {
+  const verifier = b64url(crypto.getRandomValues(new Uint8Array(48)))
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
+  const challenge = b64url(new Uint8Array(digest))
+  return { verifier, challenge }
+}
+
+interface TokenResponse {
+  access_token?: string
+  refresh_token?: string
+  expires_in?: number
+  error?: string
+  error_description?: string
+}
+
+// Confidential client -> HTTP Basic. Public (PKCE-only) -> client_id in body.
+function authHeaders(clientId: string, clientSecret: string, params: Record<string, string>) {
+  const headers: Record<string, string> = { 'Content-Type': 'application/x-www-form-urlencoded' }
+  if (clientSecret) headers.Authorization = 'Basic ' + btoa(\`\${clientId}:\${clientSecret}\`)
+  else params.client_id = clientId
+  return headers
+}
+
+// POST the token endpoint and parse tolerantly. NetSuite returns JSON for both
+// success and OAuth errors, but a gateway (502/504) can return HTML -- never let
+// res.json() throw into the route handler (that would surface as an opaque 500
+// instead of a clean "token exchange failed").
+async function postToken(
+  accountId: string,
+  params: Record<string, string>,
+  headers: Record<string, string>,
+): Promise<TokenResponse> {
+  let res: Response
+  try {
+    res = await fetch(tokenUrl(accountId), { method: 'POST', headers, body: new URLSearchParams(params) })
+  } catch (e) {
+    return { error: 'network_error', error_description: String(e) }
+  }
+  const text = await res.text()
+  let data: TokenResponse = {}
+  try {
+    data = JSON.parse(text) as TokenResponse
+  } catch {
+    // non-JSON body (e.g. gateway HTML) -- leave data empty, fall through
+  }
+  if (!res.ok && !data.error) {
+    data = { error: 'token_request_failed', error_description: 'HTTP ' + res.status }
+  }
+  return data
+}
+
+export async function exchangeCode(request: Request, code: string, verifier: string) {
+  const { accountId, clientId, clientSecret } = requireConfig()
+  const params: Record<string, string> = {
+    grant_type: 'authorization_code',
+    code,
+    redirect_uri: redirectUri(request),
+    code_verifier: verifier,
+  }
+  return postToken(accountId, params, authHeaders(clientId, clientSecret, params))
+}
+
+async function refreshToken(refresh: string) {
+  const { accountId, clientId, clientSecret } = requireConfig()
+  const params: Record<string, string> = { grant_type: 'refresh_token', refresh_token: refresh }
+  return postToken(accountId, params, authHeaders(clientId, clientSecret, params))
+}
+
+export interface NsSession {
+  sid: string
+  accountId: string
+  accessToken: string
+  refreshToken: string | null
+  expiresAt: number | null
+  userId: string | null
+  email: string | null
+}
+
+// Load a session by sid, transparently refreshing the access token when it's
+// within the leeway of expiry. Returns null if unknown or unrefreshable.
+export async function getSession(sid: string): Promise<NsSession | null> {
+  if (!sid) return null
+  const rows = await db.select().from(netsuiteSessions).where(eq(netsuiteSessions.sid, sid)).limit(1)
+  const s = rows[0]
+  if (!s) return null
+  const now = Math.floor(Date.now() / 1000)
+  // A missing expiry is treated as EXPIRED (force a refresh) rather than trusting
+  // the token forever -- NetSuite normally sends expires_in, so this is defensive.
+  const expired = s.expiresAt == null ? true : now + REFRESH_LEEWAY_SECONDS >= s.expiresAt
+  if (expired) {
+    // Token expired (or about to). It MUST refresh; if it can't, the session is
+    // dead — delete it and return null so /api/me reports signed-out and the user
+    // re-auths, rather than a "logged in" app whose every NetSuite call 401s.
+    if (!s.refreshToken) { await deleteSession(sid); return null }
+    const tok = await refreshToken(s.refreshToken)
+    if (!tok.access_token) { await deleteSession(sid); return null }
+    const expiresAt = now + (tok.expires_in || 3600)
+    const refreshTok = tok.refresh_token ?? s.refreshToken
+    await db
+      .update(netsuiteSessions)
+      .set({ accessToken: tok.access_token, refreshToken: refreshTok, expiresAt })
+      .where(eq(netsuiteSessions.sid, sid))
+    return { ...s, accessToken: tok.access_token, refreshToken: refreshTok, expiresAt }
+  }
+  return s
+}
+
+export async function deleteSession(sid: string) {
+  if (sid) await db.delete(netsuiteSessions).where(eq(netsuiteSessions.sid, sid))
+}
+
+export function bearer(request: Request) {
+  const h = request.headers.get('authorization') || ''
+  return h.startsWith('Bearer ') ? h.slice(7) : ''
+}
+
+/**
+ * Call NetSuite REST / SuiteQL for the signed-in session. Use this from your
+ * data routes (src/routes/api/*). \`path\` is relative to the account's
+ * suitetalk host, e.g. '/services/rest/query/v1/suiteql'. Returns the raw
+ * fetch Response (401 if the sid is unknown). Access token is auto-refreshed.
+ */
+export async function netsuiteFetch(sid: string, path: string, init: RequestInit = {}): Promise<Response> {
+  const session = await getSession(sid)
+  if (!session) return new Response(JSON.stringify({ error: 'unauthorized' }), { status: 401 })
+  const url = path.startsWith('http') ? path : \`\${restBase(session.accountId)}\${path}\`
+  const headers = new Headers(init.headers)
+  headers.set('Authorization', \`Bearer \${session.accessToken}\`)
+  if (init.body && !headers.has('Content-Type')) headers.set('Content-Type', 'application/json')
+  return fetch(url, { ...init, headers })
+}
+`;
+}
+
+// --- emitted: src/routes/auth/netsuite/start.ts --------------------------
+function startRouteTs(): string {
+	return `import { createFileRoute } from '@tanstack/react-router'
+import { db } from '#/db'
+import { netsuiteFlows } from '#/db/schema'
+import {
+  authorizeUrl,
+  pkce,
+  redirectUri,
+  requireConfig,
+  safeReturnTo,
+  SCOPE,
+} from '#/lib/netsuite-server'
+
+// GET /auth/netsuite/start -- begin the NetSuite OAuth (PKCE) flow.
+export const Route = createFileRoute('/auth/netsuite/start')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const { accountId, clientId } = requireConfig()
+        const url = new URL(request.url)
+        // Same-origin only: the callback returns the bearer in a URL fragment.
+        const returnTo = safeReturnTo(request, url.searchParams.get('return_to'))
+
+        const { verifier, challenge } = await pkce()
+        const flowId = crypto.randomUUID()
+        await db.insert(netsuiteFlows).values({ flowId, codeVerifier: verifier, returnTo })
+
+        const authorize = new URL(authorizeUrl(accountId))
+        authorize.searchParams.set('response_type', 'code')
+        authorize.searchParams.set('client_id', clientId)
+        authorize.searchParams.set('redirect_uri', redirectUri(request))
+        authorize.searchParams.set('scope', SCOPE)
+        authorize.searchParams.set('state', flowId)
+        authorize.searchParams.set('code_challenge', challenge)
+        authorize.searchParams.set('code_challenge_method', 'S256')
+
+        return new Response(null, { status: 302, headers: { Location: authorize.toString() } })
+      },
+    },
+  },
+})
+`;
+}
+
+// --- emitted: src/routes/auth/netsuite/callback.ts -----------------------
+function callbackRouteTs(): string {
+	return `import { createFileRoute } from '@tanstack/react-router'
+import { eq } from 'drizzle-orm'
+import { db } from '#/db'
+import { netsuiteFlows, netsuiteSessions } from '#/db/schema'
+import { exchangeCode, requireConfig } from '#/lib/netsuite-server'
+
+// GET /auth/netsuite/callback -- exchange the code, mint a session, hand the
+// bearer back to the SPA via the URL fragment (#nssid=...). The fragment
+// survives the HelloLeo preview iframe, where third-party cookies are dropped.
+export const Route = createFileRoute('/auth/netsuite/callback')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const url = new URL(request.url)
+        const err = url.searchParams.get('error')
+        if (err) return new Response(\`NetSuite authorization failed: \${err}\`, { status: 400 })
+
+        const code = url.searchParams.get('code')
+        const state = url.searchParams.get('state')
+        if (!code || !state) return new Response('Missing code or state', { status: 400 })
+
+        const rows = await db
+          .select()
+          .from(netsuiteFlows)
+          .where(eq(netsuiteFlows.flowId, state))
+          .limit(1)
+        const flow = rows[0]
+        if (!flow) return new Response('Unknown or expired flow -- start again', { status: 400 })
+        // Single-use: burn the flow row immediately.
+        await db.delete(netsuiteFlows).where(eq(netsuiteFlows.flowId, state))
+        // Reject stale flows: the PKCE verifier must not stay valid indefinitely
+        // for an abandoned or leaked authorize URL (createdAt is unixepoch seconds).
+        const nowSec = Math.floor(Date.now() / 1000)
+        if (flow.createdAt && nowSec - flow.createdAt > 600) {
+          return new Response('Flow expired -- start again', { status: 400 })
+        }
+
+        const tok = await exchangeCode(request, code, flow.codeVerifier)
+        if (!tok.access_token) {
+          return new Response(
+            \`Token exchange failed: \${tok.error_description || tok.error || 'unknown error'}\`,
+            { status: 400 },
+          )
+        }
+
+        const sid = crypto.randomUUID()
+        const now = Math.floor(Date.now() / 1000)
+        await db.insert(netsuiteSessions).values({
+          sid,
+          accountId: requireConfig().accountId,
+          accessToken: tok.access_token,
+          refreshToken: tok.refresh_token ?? null,
+          expiresAt: now + (tok.expires_in || 3600),
+        })
+
+        const dest = new URL(flow.returnTo)
+        dest.hash = \`nssid=\${sid}\`
+        return new Response(null, { status: 302, headers: { Location: dest.toString() } })
+      },
+    },
+  },
+})
+`;
+}
+
+// --- emitted: src/routes/auth/netsuite/logout.ts -------------------------
+function logoutRouteTs(): string {
+	return `import { createFileRoute } from '@tanstack/react-router'
+import { bearer, deleteSession } from '#/lib/netsuite-server'
+
+// POST /auth/netsuite/logout -- destroy the current session.
+export const Route = createFileRoute('/auth/netsuite/logout')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        await deleteSession(bearer(request))
+        return Response.json({ ok: true })
+      },
+    },
+  },
+})
+`;
+}
+
+// --- emitted: src/routes/api/me.ts ---------------------------------------
+function meRouteTs(): string {
+	return `import { createFileRoute } from '@tanstack/react-router'
+import { bearer, getSession } from '#/lib/netsuite-server'
+
+// GET /api/me -- resolve the bearer sid to a session. The ONLY authoritative
+// auth check; the client must never trust sessionStorage on its own.
+export const Route = createFileRoute('/api/me')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const session = await getSession(bearer(request))
+        if (!session) return Response.json({ authenticated: false })
+        return Response.json({
+          authenticated: true,
+          account_id: session.accountId,
+        })
+      },
+    },
+  },
+})
+`;
+}
+
+// --- emitted: src/routes/auth/netsuite/config.ts -------------------------
+function configRouteTs(): string {
+	return `import { createFileRoute } from '@tanstack/react-router'
+import { env as runtimeEnv } from '@helloleo/runtime'
+import { appOrigin, redirectUri } from '#/lib/netsuite-server'
+
+// GET /auth/netsuite/config -- single source of truth for the redirect URI.
+// Whatever this returns is EXACTLY what /auth/netsuite/start sends NetSuite, so
+// show the user THIS value to register on their Integration Record. Never
+// hardcode or guess a callback URL.
+export const Route = createFileRoute('/auth/netsuite/config')({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const e = runtimeEnv as unknown as {
+          NETSUITE_ACCOUNT_ID?: string
+          NETSUITE_CLIENT_ID?: string
+        }
+        return Response.json({
+          redirect_uri: redirectUri(request),
+          origin: appOrigin(request),
+          configured: Boolean(e.NETSUITE_ACCOUNT_ID && e.NETSUITE_CLIENT_ID),
+        })
+      },
+    },
+  },
+})
+`;
+}
+
+// --- emitted: src/lib/netsuite.ts (client) -------------------------------
+function netsuiteClientTs(): string {
+	return `/*
+ * NetSuite auth -- client (same-origin). The OAuth backend is THIS app's own
+ * server routes (src/routes/auth/netsuite/* + src/routes/api/me.ts), so every
+ * call is relative -- no separate Worker, no VITE_WORKER_URL.
+ *
+ * The browser only ever holds an opaque session id (sid), handed back in the
+ * callback's URL fragment (#nssid=...) so it survives the HelloLeo preview
+ * iframe (third-party cookies are partitioned/dropped there). The sid rides as
+ * Authorization: Bearer on every call; NetSuite tokens stay server-side. The
+ * only authoritative auth check is GET /api/me.
+ *
+ * NEVER use a password gate. NEVER trust sessionStorage as the auth state --
+ * it's just a cache of the bearer.
+ */
+const TOKEN_KEY = 'nssid'
+
+// Capture-and-strip #nssid=... as early as possible so URLs stay clean.
+;(function bootstrapTokenFromHash() {
+  if (typeof window === 'undefined') return
+  const hash = window.location.hash.replace(/^#/, '')
+  if (!hash) return
+  const params = new URLSearchParams(hash)
+  const sid = params.get(TOKEN_KEY)
+  if (sid) {
+    try {
+      sessionStorage.setItem(TOKEN_KEY, sid)
+    } catch {}
+    params.delete(TOKEN_KEY)
+    const rest = params.toString()
+    window.history.replaceState(
+      null,
+      '',
+      window.location.pathname + window.location.search + (rest ? '#' + rest : ''),
+    )
+  }
+})()
+
+export function getSessionToken(): string | null {
+  try {
+    return sessionStorage.getItem(TOKEN_KEY)
+  } catch {
+    return null
+  }
+}
+
+export function signInWithNetSuite(returnTo: string = window.location.href) {
+  const url = new URL('/auth/netsuite/start', window.location.origin)
+  url.searchParams.set('return_to', returnTo)
+  // The app renders inside the HelloLeo preview iframe; /start 302s to
+  // NetSuite, whose OAuth page sends X-Frame-Options: DENY. Navigate the TOP
+  // frame so the flow runs at top level and the callback lands there to read
+  // #nssid=. Assign .href (NOT .assign(): reading .assign off a cross-origin
+  // window.top.location throws, dropping us into the iframe fallback ->
+  // "refused to connect").
+  try {
+    if (window.top && window.top !== window) {
+      window.top.location.href = url.toString()
+      return
+    }
+  } catch {
+    /* top window unreachable -- fall through to same-frame navigation */
+  }
+  window.location.href = url.toString()
+}
+
+export interface NetSuiteSession {
+  authenticated: boolean
+  account_id?: string
+}
+
+export async function getNetSuiteSession(): Promise<NetSuiteSession> {
+  const sid = getSessionToken()
+  if (!sid) return { authenticated: false }
+  const res = await fetch('/api/me', { headers: { Authorization: 'Bearer ' + sid } })
+  if (!res.ok) return { authenticated: false }
+  // res.json() is \`unknown\` under workers-types -- assert the /api/me shape.
+  const data = (await res.json()) as NetSuiteSession
+  return { ...data, authenticated: Boolean(data?.authenticated) }
+}
+
+export async function signOutNetSuite(): Promise<void> {
+  const sid = getSessionToken()
+  if (sid) {
+    try {
+      await fetch('/auth/netsuite/logout', {
+        method: 'POST',
+        headers: { Authorization: 'Bearer ' + sid },
+      })
+    } catch {}
+  }
+  try {
+    sessionStorage.removeItem(TOKEN_KEY)
+  } catch {}
+  window.location.reload()
+}
+
+/**
+ * Fetch YOUR data routes (src/routes/api/*) with the bearer attached. Use this
+ * instead of bare fetch for authenticated calls.
+ */
+export async function apiFetch(path: string, init: RequestInit = {}): Promise<Response> {
+  const sid = getSessionToken()
+  const headers = new Headers(init.headers)
+  if (sid) headers.set('Authorization', 'Bearer ' + sid)
+  return fetch(path, { ...init, headers })
+}
+
+/**
+ * The exact redirect URI this app will send NetSuite, read from the server so
+ * it can never drift from what /auth/netsuite/start actually uses. Show it to
+ * whoever registers the Integration Record; never hardcode a callback URL.
+ */
+export async function getNetSuiteRedirectUri(): Promise<string | null> {
+  try {
+    const res = await fetch('/auth/netsuite/config')
+    if (!res.ok) return null
+    const data = (await res.json()) as { redirect_uri?: string }
+    return data?.redirect_uri ?? null
+  } catch {
+    return null
+  }
+}
+`;
+}
+
+// --- emitted: src/lib/auth.tsx (client) ----------------------------------
+function startAuthTsx(): string {
+	return `import * as React from 'react'
+import {
+  getNetSuiteSession,
+  signInWithNetSuite,
+  signOutNetSuite,
+  type NetSuiteSession,
+} from './netsuite'
+
+/**
+ * NetSuite auth context. Holds the session (resolved client-side from /api/me
+ * via getNetSuiteSession) and exposes sign-in / sign-out. /api/me is the only
+ * authoritative check -- never trust sessionStorage directly.
+ */
+export interface NetSuiteAuthContextValue {
+  pending: boolean
+  isAuthenticated: boolean
+  session: NetSuiteSession | null
+  signIn: () => void
+  signOut: () => Promise<void>
+  refresh: () => Promise<void>
+}
+
+const NetSuiteAuthContext = React.createContext<NetSuiteAuthContextValue | null>(null)
+
+export function NetSuiteAuthProvider({ children }: { children: React.ReactNode }) {
+  const [session, setSession] = React.useState<NetSuiteSession | null>(null)
+  // Start pending on BOTH server and client render so SSR and first paint match
+  // (a spinner), avoiding a hydration mismatch. The effect (client-only)
+  // resolves it.
+  const [pending, setPending] = React.useState(true)
+
+  const refresh = React.useCallback(async () => {
+    setPending(true)
+    try {
+      setSession(await getNetSuiteSession())
+    } finally {
+      setPending(false)
+    }
+  }, [])
+
+  React.useEffect(() => {
+    refresh()
+  }, [refresh])
+
+  const value: NetSuiteAuthContextValue = {
+    pending,
+    isAuthenticated: Boolean(session?.authenticated),
+    session,
+    signIn: () => signInWithNetSuite(),
+    signOut: signOutNetSuite,
+    refresh,
+  }
+
+  return <NetSuiteAuthContext.Provider value={value}>{children}</NetSuiteAuthContext.Provider>
+}
+
+export function useNetSuiteAuth(): NetSuiteAuthContextValue {
+  const ctx = React.useContext(NetSuiteAuthContext)
+  if (!ctx) {
+    throw new Error('useNetSuiteAuth must be used within <NetSuiteAuthProvider>')
+  }
+  return ctx
+}
+`;
+}
+
+// --- emitted: src/components/auth/AuthLayout.tsx --------------------------
+function startAuthLayoutTsx(): string {
+	return `import type { ReactNode } from 'react'
+import { NetSuiteAuthProvider, useNetSuiteAuth } from '../../lib/auth'
+import { LoginPage } from './LoginPage'
+
+/**
+ * NetSuite auth layout. The ONE manual wiring step: wrap the root route's
+ * <Outlet /> with it in src/routes/__root.tsx:
+ *
+ *   import { AuthLayout } from '../components/auth/AuthLayout'
+ *   ...
+ *   function RootComponent() {
+ *     return (
+ *       <RootDocument>
+ *         <AuthLayout>
+ *           <Outlet />
+ *         </AuthLayout>
+ *       </RootDocument>
+ *     )
+ *   }
+ *
+ * It provides auth context and gates rendering: a spinner while the session
+ * resolves, <LoginPage /> for signed-out users, your routes once signed in.
+ * NEVER swap this for a password gate -- real OAuth is the only login.
+ */
+export function AuthLayout({ children }: { children: ReactNode }) {
+  return (
+    <NetSuiteAuthProvider>
+      <Gate>{children}</Gate>
+    </NetSuiteAuthProvider>
+  )
+}
+
+function Gate({ children }: { children: ReactNode }) {
+  const { pending, isAuthenticated } = useNetSuiteAuth()
+
+  if (pending) {
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-background">
+        <div className="h-8 w-8 rounded-full border-2 border-primary border-t-transparent animate-spin" />
+      </div>
+    )
+  }
+
+  if (!isAuthenticated) return <LoginPage />
+
+  return <>{children}</>
+}
+`;
+}
+
+// --- emitted: src/components/auth/LoginPage.tsx ---------------------------
+function startLoginPageTsx(): string {
+	return `import { SignInWithNetSuite } from './SignInWithNetSuite'
+
+/**
+ * Unauthenticated gate -- a deliberately bare placeholder. DESIGN THIS PAGE
+ * to match the app you are building: its real name, its brand, its layout
+ * language. Do NOT ship this default as-is.
+ *
+ * The only hard requirements:
+ *   - keep <SignInWithNetSuite /> as the ONLY call-to-action (it starts the
+ *     OAuth flow at /auth/netsuite/start)
+ *   - never add a password form -- real OAuth is the only login
+ */
+export function LoginPage() {
+  return (
+    <main className="min-h-screen flex items-center justify-center bg-background text-foreground p-4">
+      <div className="flex flex-col items-center gap-4 text-center">
+        <h1 className="text-2xl font-semibold">Sign in</h1>
+        <p className="text-sm text-muted-foreground">
+          Connect your NetSuite account to continue.
+        </p>
+        <SignInWithNetSuite />
+      </div>
+    </main>
+  )
+}
+`;
+}
+
+// --- emitted: src/components/auth/SignInWithNetSuite.tsx ------------------
+function startSignInButtonTsx(): string {
+	return `import { signInWithNetSuite } from '../../lib/netsuite'
+
+export function SignInWithNetSuite() {
+  return (
+    <button
+      onClick={() => signInWithNetSuite()}
+      className="inline-flex items-center justify-center gap-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground shadow hover:bg-primary/90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      Sign in with NetSuite
+    </button>
+  )
+}
+`;
+}
+
+function spaNetsuiteTs(): string {
 	return `/*
  * NetSuite OAuth client helper (bearer-token-in-fragment).
  *
@@ -173,7 +952,7 @@ export async function workerFetch(pathOrUrl: string, init: RequestInit = {}): Pr
 `;
 }
 
-function signInButtonTsx(): string {
+function spaSignInButtonTsx(): string {
 	return `import { signInWithNetSuite } from '../../lib/netsuite';
 
 export function SignInWithNetSuite() {
@@ -189,52 +968,36 @@ export function SignInWithNetSuite() {
 `;
 }
 
-function netsuiteLoginPageTsx(): string {
+function spaLoginPageTsx(): string {
 	return `import { SignInWithNetSuite } from './SignInWithNetSuite';
 
 /**
- * Default unauthenticated landing page. Replaces any password gate.
- * Customise copy / imagery freely but keep <SignInWithNetSuite /> as the
- * only call-to-action -- it points to the Worker's /auth/netsuite/start.
+ * Unauthenticated gate -- a deliberately bare placeholder. DESIGN THIS PAGE
+ * to match the app you are building: its real name, its brand, its layout
+ * language. Do NOT ship this default as-is.
+ *
+ * The only hard requirements:
+ *   - keep <SignInWithNetSuite /> as the ONLY call-to-action (it starts the
+ *     OAuth flow on the Worker's /auth/netsuite/start)
+ *   - never add a password form -- real OAuth is the only login
  */
 export function LoginPage() {
   return (
-    <div className="min-h-screen bg-background text-foreground flex">
-      <div className="hidden lg:flex lg:w-1/2 bg-primary text-primary-foreground p-12 flex-col justify-between">
-        <div className="text-xl font-semibold">NetSuite App</div>
-        <div>
-          <h1 className="text-4xl font-bold leading-tight">
-            Connect your NetSuite account
-          </h1>
-          <p className="mt-4 text-primary-foreground/80 max-w-md">
-            Sign in with your NetSuite credentials to access your data securely.
-            Tokens stay server-side on HelloLeo Cloud -- they never reach the
-            browser.
-          </p>
-        </div>
-        <div className="text-xs text-primary-foreground/60">
-          Powered by HelloLeo
-        </div>
+    <main className="min-h-screen flex items-center justify-center bg-background text-foreground p-4">
+      <div className="flex flex-col items-center gap-4 text-center">
+        <h1 className="text-2xl font-semibold">Sign in</h1>
+        <p className="text-sm text-muted-foreground">
+          Connect your NetSuite account to continue.
+        </p>
+        <SignInWithNetSuite />
       </div>
-      <div className="flex-1 flex items-center justify-center px-6 py-12">
-        <div className="w-full max-w-sm space-y-6">
-          <div>
-            <h2 className="text-2xl font-semibold">Welcome</h2>
-            <p className="mt-2 text-sm text-muted-foreground">
-              Use the button below to sign in. You'll be redirected to NetSuite
-              to authorise access, then back here.
-            </p>
-          </div>
-          <SignInWithNetSuite />
-        </div>
-      </div>
-    </div>
+    </main>
   );
 }
 `;
 }
 
-function authTsx(): string {
+function spaAuthTsx(): string {
 	return `import * as React from 'react';
 import {
   getNetSuiteSession,
@@ -307,7 +1070,7 @@ export function useNetSuiteAuth(): NetSuiteAuthContextValue {
 `;
 }
 
-function authLayoutTsx(): string {
+function spaAuthLayoutTsx(): string {
 	return `import type { ReactNode } from 'react';
 import { NetSuiteAuthProvider, useNetSuiteAuth } from '../../lib/auth';
 import { LoginPage } from './LoginPage';
@@ -362,65 +1125,211 @@ function Gate({ children }: { children: ReactNode }) {
 `;
 }
 
+// --- variant: tanstack-start (in-app server routes) ----------------------
+async function executeStart(dir: string): Promise<string> {
+	await mkdir(path.join(dir, "src", "lib"), { recursive: true });
+	await mkdir(path.join(dir, "src", "components", "auth"), {
+		recursive: true,
+	});
+	await mkdir(path.join(dir, "src", "routes", "auth", "netsuite"), {
+		recursive: true,
+	});
+	await mkdir(path.join(dir, "src", "routes", "api"), { recursive: true });
+
+	// Append the NetSuite tables to the drizzle schema (single source of
+	// truth; migrations are generated from it and applied automatically).
+	// Idempotent -- skip if already present. The 2026-07-30 start template
+	// ships schema.ts as comments only (no imports), so prepend the drizzle
+	// imports whenever the file has no real (uncommented) import of its own.
+	const schemaImports = `import { sql } from 'drizzle-orm'\nimport { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'\n`;
+	const schemaPath = path.join(dir, "src", "db", "schema.ts");
+	let schemaAppended = false;
+	try {
+		const current = await readFile(schemaPath, "utf8");
+		if (!current.includes("netsuite_flows")) {
+			const hasImports = /^import .*drizzle-orm/m.test(current);
+			await Bun.write(
+				schemaPath,
+				(hasImports ? current : schemaImports + current) + schemaAppend(),
+			);
+			schemaAppended = true;
+		}
+	} catch {
+		// No base schema.ts -- scaffold wasn't run. Write a minimal one.
+		await Bun.write(schemaPath, schemaImports + schemaAppend());
+		schemaAppended = true;
+	}
+
+	const files: [string, string][] = [
+		[path.join("src", "lib", "netsuite-server.ts"), netsuiteServerTs()],
+		[
+			path.join("src", "routes", "auth", "netsuite", "start.ts"),
+			startRouteTs(),
+		],
+		[
+			path.join("src", "routes", "auth", "netsuite", "callback.ts"),
+			callbackRouteTs(),
+		],
+		[
+			path.join("src", "routes", "auth", "netsuite", "logout.ts"),
+			logoutRouteTs(),
+		],
+		[
+			path.join("src", "routes", "auth", "netsuite", "config.ts"),
+			configRouteTs(),
+		],
+		[path.join("src", "routes", "api", "me.ts"), meRouteTs()],
+		[path.join("src", "lib", "netsuite.ts"), netsuiteClientTs()],
+		[path.join("src", "lib", "auth.tsx"), startAuthTsx()],
+		[
+			path.join("src", "components", "auth", "AuthLayout.tsx"),
+			startAuthLayoutTsx(),
+		],
+		[
+			path.join("src", "components", "auth", "LoginPage.tsx"),
+			startLoginPageTsx(),
+		],
+		[
+			path.join("src", "components", "auth", "SignInWithNetSuite.tsx"),
+			startSignInButtonTsx(),
+		],
+	];
+
+	for (const [filePath, content] of files) {
+		await Bun.write(path.join(dir, filePath), content);
+	}
+
+	return [
+		`Wrote ${files.length} NetSuite files${schemaAppended ? " + appended src/db/schema.ts" : ""}:`,
+		"DOCS -- the authoritative setup guide is https://docs.helloleo.dev/integrations/netsuite . When you tell the user what to do in NetSuite, follow and link these steps verbatim; do not invent steps.",
+		"  - Record #2 (runtime): https://docs.helloleo.dev/integrations/netsuite#step-4-%E2%80%94-create-integration-record-2-runtime",
+		"  - Send runtime creds to Leo: https://docs.helloleo.dev/integrations/netsuite#step-5-%E2%80%94-send-the-runtime-credentials-to-leo",
+		"",
+		"  server (OAuth backend lives in the app -- no separate Worker):",
+		"  - src/lib/netsuite-server.ts (env, PKCE, token exchange, session refresh, netsuiteFetch)",
+		"  - src/routes/auth/netsuite/start.ts    GET  begin PKCE flow",
+		"  - src/routes/auth/netsuite/callback.ts GET  code -> tokens -> session",
+		"  - src/routes/auth/netsuite/logout.ts   POST destroy session",
+		"  - src/routes/auth/netsuite/config.ts   GET  the exact redirect URI to register",
+		"  - src/routes/api/me.ts                 GET  bearer -> session (auth check)",
+		"  - src/db/schema.ts += netsuite_flows + netsuite_sessions",
+		"  client:",
+		"  - src/lib/netsuite.ts (same-origin: signIn, session, apiFetch)",
+		"  - src/lib/auth.tsx (NetSuiteAuthProvider + useNetSuiteAuth)",
+		"  - src/components/auth/{AuthLayout,LoginPage,SignInWithNetSuite}.tsx",
+		"",
+		"WIRE IT UP (one manual step): in src/routes/__root.tsx, wrap <Outlet /> with <AuthLayout>:",
+		"",
+		"    import { AuthLayout } from '../components/auth/AuthLayout'",
+		"",
+		"    <AuthLayout>",
+		"      <Outlet />",
+		"    </AuthLayout>",
+		"",
+		"Then:",
+		"- DESIGN THE LOGIN PAGE: src/components/auth/LoginPage.tsx is a bare placeholder on purpose. Restyle it to match THIS app (name, brand, layout) as part of building the UI -- do not ship the default. Keep <SignInWithNetSuite /> as the only call-to-action; never add a password form.",
+		"- Build your dashboard inside <AuthLayout>. Read the session with useNetSuiteAuth().",
+		"- Data routes: add src/routes/api/*.ts and call netsuiteFetch(bearer(request), '/services/rest/query/v1/suiteql', {...}) from the handler.",
+		"- MIGRATIONS: schema.ts changed (netsuite_flows + netsuite_sessions). Migrations are generated and applied automatically; if the dev server complains about missing tables, run `bun run db:generate` once (never hand-edit files under drizzle/).",
+		"",
+		"TWO INTEGRATION RECORDS -- do not confuse them:",
+		"- Record #1 (scope: mcp): already connected, used ONLY to build the app (schema discovery). This login does NOT use it.",
+		"- Record #2 (scope: rest_webservices): THIS login uses it -- the end user signs into NetSuite through it, and the redirect URI is registered on THIS record. If it doesn't exist yet, tell the user to create it (a second Integration Record, scope rest_webservices only).",
+		"",
+		"CONFIG -- NETSUITE_ACCOUNT_ID, NETSUITE_CLIENT_ID, NETSUITE_CLIENT_SECRET (secret optional for PKCE public clients). Never hardcode; never put in code. Same var names in every environment, different SOURCE:",
+		"- DEV (Fly preview): read from the project .env. HelloLeo writes them there (the setup wizard, or the env tooling). In dev the app uses .env -- do NOT tell the user to use HelloLeo Cloud here.",
+		"- PROD (published Worker): the SAME names live as HelloLeo Cloud secrets; the publish step promotes them from .env onto the Worker automatically. Same code path (@helloleo/runtime env), just a different source per environment.",
+		"- PUBLIC_APP_URL / HELLOLEO_URL are set by the platform per environment; don't hardcode them.",
+		"- REDIRECT URI -- never guess or hardcode it. It is derived server-side and auto-corrects behind the preview proxy. Read the exact value from GET /auth/netsuite/config (or getNetSuiteRedirectUri() on the client) and tell the user to register THAT on Integration Record #2 (scope: rest_webservices). ONE redirect URI per record: register exactly the value /auth/netsuite/config returns for the environment the user signs into. If login must work in BOTH the preview and the published app, use a separate Integration Record per environment (same env var names, different NETSUITE_CLIENT_ID/_SECRET values per environment) -- do not stack URLs on one record.",
+		"- Never replace <AuthLayout> with a password gate. Real OAuth is the only supported login.",
+	].join("\n");
+}
+
+// --- variant: SPA + HelloLeo Cloud Worker --------------------------------
+async function executeSpa(dir: string): Promise<string> {
+	await mkdir(path.join(dir, "src", "components", "auth"), {
+		recursive: true,
+	});
+
+	// All additive -- nothing the base scaffold wrote is touched.
+	const nsFiles: [string, string][] = [
+		[path.join("src", "lib", "netsuite.ts"), spaNetsuiteTs()],
+		[path.join("src", "lib", "auth.tsx"), spaAuthTsx()],
+		[
+			path.join("src", "components", "auth", "AuthLayout.tsx"),
+			spaAuthLayoutTsx(),
+		],
+		[
+			path.join("src", "components", "auth", "LoginPage.tsx"),
+			spaLoginPageTsx(),
+		],
+		[
+			path.join("src", "components", "auth", "SignInWithNetSuite.tsx"),
+			spaSignInButtonTsx(),
+		],
+	];
+
+	for (const [filePath, content] of nsFiles) {
+		await Bun.write(path.join(dir, filePath), content);
+	}
+
+	return [
+		`Wrote ${nsFiles.length} NetSuite OAuth files (all additive, nothing overwritten):`,
+		"  - src/lib/netsuite.ts (OAuth client: signIn, session, workerFetch)",
+		"  - src/lib/auth.tsx (NetSuiteAuthProvider and useNetSuiteAuth)",
+		"  - src/components/auth/AuthLayout.tsx (provider and auth gate)",
+		"  - src/components/auth/LoginPage.tsx (unauthenticated view)",
+		"  - src/components/auth/SignInWithNetSuite.tsx (sign-in button)",
+		"",
+		"Notes:",
+		"- DESIGN THE LOGIN PAGE: src/components/auth/LoginPage.tsx is a bare placeholder on purpose. Restyle it to match THIS app (name, brand, layout) as part of building the UI -- do not ship the default. Keep <SignInWithNetSuite /> as the only call-to-action; never add a password form.",
+		"- AuthLayout shows LoginPage to signed-out users and renders the app's routes once they sign in with NetSuite.",
+		"- Read the session anywhere with useNetSuiteAuth() from src/lib/auth.tsx.",
+		"- Never replace AuthLayout with a password gate. Real OAuth is the only supported login.",
+		"- The auth worker (deployed via the cloudflare-backend MCP) serves /auth/netsuite/start, /auth/netsuite/callback, /api/me and /auth/netsuite/logout. It reads env.NETSUITE_ACCOUNT_ID, _CLIENT_ID and _CLIENT_SECRET. VITE_WORKER_URL must be set (HelloLeo Cloud seeds it).",
+		"- POPUP FLOW (required so login works inside the HelloLeo preview iframe): the client opens /auth/netsuite/start in a popup with ?popup=1. The worker MUST carry that flag through OAuth (persist it on the flow row in /start, read it back in /callback via state). In /auth/netsuite/callback, when the flow was popup, DO NOT redirect to return_to#nssid — instead return an HTML page whose script does: window.opener.postMessage({ type: 'netsuite-auth', nssid: SID }, '*'); window.close(); (fall back to the return_to#nssid redirect only when there is no opener / not a popup). Without this, the preview iframe (partitioned sessionStorage) keeps showing the login after sign-in.",
+		"",
+		"Next: in src/routes/__root.tsx, import AuthLayout and wrap <Outlet /> with it. Keep any existing providers.",
+		"",
+		"    import { AuthLayout } from '../components/auth/AuthLayout'",
+		"",
+		"    <AuthLayout>",
+		"      <Outlet />",
+		"    </AuthLayout>",
+	].join("\n");
+}
+
 export const setupNetsuite = tool({
 	description:
-		"Add NetSuite OAuth wiring to an existing project. Call scaffold first, " +
-		"then this. Writes the OAuth client, auth provider and login components. " +
-		"All files are additive, nothing is overwritten. Real OAuth is wired " +
-		"from day one, never replace <AuthLayout> with a password placeholder.",
+		"Add NetSuite runtime OAuth (end-user LOGIN) to an existing project. " +
+		"Call scaffold first, then this. Works on both scaffold types: it " +
+		"writes the client + auth components, and the OAuth backend is the " +
+		"project's HelloLeo Cloud Worker (VITE_WORKER_URL) -- the platform " +
+		"wizard registers the Worker's fixed /auth/netsuite/callback on the " +
+		"Integration Record, so the app never hosts the OAuth routes itself. " +
+		"This login uses NetSuite Integration Record #2 " +
+		"(scope: rest_webservices) -- a SEPARATE record from the MCP one " +
+		"(scope: mcp) that was used only to BUILD the app; do not confuse " +
+		"them. Real OAuth from day one -- never replace <AuthLayout> with a " +
+		"password placeholder. Setup guide (link the user to it): " +
+		"https://docs.helloleo.dev/integrations/netsuite",
 	args: {},
 	async execute(_args, context) {
 		const dir = context.directory;
-
-		await mkdir(path.join(dir, "src", "components", "auth"), {
-			recursive: true,
-		});
-
-		// All additive -- nothing the base scaffold wrote is touched.
-		const nsFiles: [string, string][] = [
-			[path.join("src", "lib", "netsuite.ts"), netsuiteTs()],
-			[path.join("src", "lib", "auth.tsx"), authTsx()],
-			[
-				path.join("src", "components", "auth", "AuthLayout.tsx"),
-				authLayoutTsx(),
-			],
-			[
-				path.join("src", "components", "auth", "LoginPage.tsx"),
-				netsuiteLoginPageTsx(),
-			],
-			[
-				path.join("src", "components", "auth", "SignInWithNetSuite.tsx"),
-				signInButtonTsx(),
-			],
-		];
-
-		for (const [filePath, content] of nsFiles) {
-			await Bun.write(path.join(dir, filePath), content);
+		// Prod model: Integration Record #2 carries ONE fixed redirect URI --
+		// the per-project HelloLeo Cloud Worker's /auth/netsuite/callback
+		// (provision-first wizard, see webapp netsuiteRuntimeSetup). So the
+		// Worker variant is the default for EVERY scaffold type. The in-app
+		// server-route variant (app-origin redirect URI) only makes sense when
+		// a deployment's wizard registers the app's own callback instead --
+		// opt in per deployment with PLUGINS_NETSUITE_IN_APP=1 on a
+		// tanstack-start scaffold.
+		const scaffoldId = await readScaffoldId(dir);
+		const inAppOptIn = process.env.PLUGINS_NETSUITE_IN_APP === "1";
+		if (inAppOptIn && scaffoldId?.startsWith("tanstack-start")) {
+			return executeStart(dir);
 		}
-
-		return [
-			`Wrote ${nsFiles.length} NetSuite OAuth files (all additive, nothing overwritten):`,
-			"  - src/lib/netsuite.ts (OAuth client: signIn, session, workerFetch)",
-			"  - src/lib/auth.tsx (NetSuiteAuthProvider and useNetSuiteAuth)",
-			"  - src/components/auth/AuthLayout.tsx (provider and auth gate)",
-			"  - src/components/auth/LoginPage.tsx (unauthenticated view)",
-			"  - src/components/auth/SignInWithNetSuite.tsx (sign-in button)",
-			"",
-			"Notes:",
-			"- AuthLayout shows LoginPage to signed-out users and renders the app's routes once they sign in with NetSuite.",
-			"- Read the session anywhere with useNetSuiteAuth() from src/lib/auth.tsx.",
-			"- Never replace AuthLayout with a password gate. Real OAuth is the only supported login.",
-			"- The auth worker (deployed via the cloudflare-backend MCP) serves /auth/netsuite/start, /auth/netsuite/callback, /api/me and /auth/netsuite/logout. It reads env.NETSUITE_ACCOUNT_ID, _CLIENT_ID and _CLIENT_SECRET. VITE_WORKER_URL must be set (HelloLeo Cloud seeds it).",
-			"- POPUP FLOW (required so login works inside the HelloLeo preview iframe): the client opens /auth/netsuite/start in a popup with ?popup=1. The worker MUST carry that flag through OAuth (persist it on the flow row in /start, read it back in /callback via state). In /auth/netsuite/callback, when the flow was popup, DO NOT redirect to return_to#nssid — instead return an HTML page whose script does: window.opener.postMessage({ type: 'netsuite-auth', nssid: SID }, '*'); window.close(); (fall back to the return_to#nssid redirect only when there is no opener / not a popup). Without this, the preview iframe (partitioned sessionStorage) keeps showing the login after sign-in.",
-			"",
-			"Next: in src/routes/__root.tsx, import AuthLayout and wrap <Outlet /> with it. Keep any existing providers.",
-			"",
-			"    import { AuthLayout } from '../components/auth/AuthLayout'",
-			"",
-			"    <AuthLayout>",
-			"      <Outlet />",
-			"    </AuthLayout>",
-		].join("\n");
+		return executeSpa(dir);
 	},
 });