@woodsportal/hubspot-kit 1.0.41-dev.5 → 1.0.41-dev.6

package/examples/greenfield/module-hybrid-cdn-auth-sso/src/routes/__root.tsx

@@ -0,0 +1,12 @@
+import { createRootRouteWithContext } from '@tanstack/react-router'
+
+import AppLayoutWrapper from '@/components/Layouts/AppLayoutWrapper'
+import { Provider } from '@/integrations/tanstack-query/root-provider'
+
+export const Route = createRootRouteWithContext()({
+  component: () => (
+    <Provider>
+      <AppLayoutWrapper />
+    </Provider>
+  ),
+})

package/examples/greenfield/module-hybrid-cdn-auth-sso/src/routes/_app/portal.tsx

@@ -0,0 +1,10 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { StarterProtectedPage } from '@/features/starter/components/starter-protected-page'
+
+export const Route = createFileRoute('/_app/portal')({
+  component: StarterProtectedPage,
+  beforeLoad: () => ({
+    layout: 'MainLayout' as const,
+    requiresAuth: true,
+  }),
+})

package/examples/greenfield/module-hybrid-cdn-auth-sso/src/routes/_auth/login/sso.tsx

@@ -0,0 +1,27 @@
+import { createFileRoute, useRouter } from '@tanstack/react-router'
+import Loader from '@/components/ui/loader/loader'
+import { useSsoCallbackHandler } from '@/features/auth/use-sso-callback-handler'
+
+function SsoCallbackPage() {
+  const router = useRouter()
+  const search = Route.useSearch()
+  const { isLoading } = useSsoCallbackHandler({ router, routeSearch: search })
+
+  if (isLoading) {
+    return <Loader text="Completing SSO sign-in…" />
+  }
+
+  return null
+}
+
+export const Route = createFileRoute('/_auth/login/sso')({
+  component: SsoCallbackPage,
+  validateSearch: (search: Record<string, unknown>) => ({
+    code: typeof search.code === 'string' ? search.code : undefined,
+    state: typeof search.state === 'string' ? search.state : undefined,
+  }),
+  beforeLoad: () => ({
+    layout: 'AuthLayout' as const,
+    requiresAuth: false,
+  }),
+})

package/examples/greenfield/module-hybrid-cdn-auth-sso/src/routes/_auth/login.tsx

@@ -0,0 +1,10 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { StarterLogin } from '@/features/auth/components/starter-login'
+
+export const Route = createFileRoute('/_auth/login')({
+  component: StarterLogin,
+  beforeLoad: () => ({
+    layout: 'AuthLayout' as const,
+    requiresAuth: false,
+  }),
+})

package/examples/greenfield/module-hybrid-cdn-auth-sso/src/routes/guide.tsx

@@ -0,0 +1,9 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { StarterGuidePage } from '@/features/starter/components/starter-guide-page'
+
+export const Route = createFileRoute('/guide')({
+  component: StarterGuidePage,
+  beforeLoad: () => ({
+    layout: 'MainLayout' as const,
+  }),
+})

package/examples/greenfield/module-hybrid-cdn-auth-sso/src/routes/index.tsx

@@ -0,0 +1,8 @@
+import { createFileRoute, redirect } from '@tanstack/react-router'
+import { Routes } from '@/config/routes'
+
+export const Route = createFileRoute('/')({
+  beforeLoad: () => {
+    throw redirect({ to: Routes.guide })
+  },
+})

package/examples/greenfield/module-hybrid-cdn-auth-sso/src/routes/unauthorized.tsx

@@ -0,0 +1,50 @@
+import { createFileRoute, useNavigate, useRouter } from '@tanstack/react-router'
+import { useEffect } from 'react'
+import { Button } from '@/components/ui/Button'
+import { Routes } from '@/config/routes'
+import { readPersistedAuthError, WP_STORAGE_KEYS } from 'woodsportal-client-sdk'
+import { clearClientAuthSession } from '@/features/auth/clear-client-auth-session'
+import { isHubSpotCmsEditor } from '@/hubspot/is-cms-editor'
+
+function Unauthorized() {
+  const router = useRouter()
+  const navigate = useNavigate()
+  const inCmsEditor = isHubSpotCmsEditor()
+  const authError = readPersistedAuthError()
+
+  useEffect(() => {
+    if (authError != null) {
+      clearClientAuthSession()
+    } else if (!inCmsEditor) {
+      router.navigate({ to: Routes.guide })
+    }
+  }, [authError, inCmsEditor, router])
+
+  useEffect(() => {
+    return () => {
+      sessionStorage.removeItem(WP_STORAGE_KEYS.c.auth.err)
+    }
+  }, [])
+
+  return (
+    <div className="flex min-h-screen items-center justify-center p-4">
+      <div className="w-full max-w-md rounded-lg border border-gray-200 bg-white p-6 text-center shadow-sm">
+        <h1 className="mb-2 text-xl font-semibold">401 Unauthorized</h1>
+        <p className="mb-6 text-sm text-gray-600">
+          {authError?.errorMessage ??
+            'Your session may have expired. Please sign in again to continue.'}
+        </p>
+        <Button className="w-full" onClick={() => navigate({ to: Routes.login })}>
+          Go to login
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+export const Route = createFileRoute('/unauthorized')({
+  component: Unauthorized,
+  beforeLoad: () => ({
+    layout: 'UnauthorizedLayout' as const,
+  }),
+})

package/examples/greenfield/module-hybrid-cdn-auth-sso/src/utils/ValidationSchema.ts

@@ -0,0 +1 @@
+export { isProtectedHashPath as skipCurrentPublicPath } from '@/features/auth/auth-route-paths'

package/examples/greenfield/module-hybrid-cdn-auth-sso/src/utils/cookie.ts

@@ -0,0 +1,23 @@
+import { env } from '@/env'
+
+const COOKIE_KEYS = [
+  env.VITE_LOGIN_DETAILS,
+  env.VITE_REFRESH_TOKEN,
+  env.VITE_PORTAL,
+  env.VITE_SUBSCRIPTION_TYPE,
+  env.VITE_AUTH_USER_KEY,
+  env.VITE_PAGINATION_DATA,
+  env.VITE_ROUTE_MENU_CONFIG_KEY,
+  env.VITE_ASSOCIATION_VIEW_URL_KEY,
+  env.VITE_AUTH_TOKEN_KEY,
+]
+
+export function clearClientAuthCookies(): void {
+  if (typeof document === 'undefined') {
+    return
+  }
+  for (const name of COOKIE_KEYS) {
+    document.cookie = `${name}=; Max-Age=0; path=/`
+    document.cookie = `${name}=; Max-Age=0; path=/; domain=${window.location.hostname}`
+  }
+}

package/examples/greenfield/module-hybrid-cdn-auth-sso/src/utils/normalize-router-path.ts

@@ -0,0 +1,10 @@
+import { Routes } from '@/config/routes'
+
+export function normalizeRouterPath(path: string): string {
+  const trimmed = (path ?? '').trim()
+  if (!trimmed || trimmed === '/') {
+    return Routes.app
+  }
+  const withLeadingSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`
+  return withLeadingSlash.replace(/\/{2,}/g, '/')
+}

package/examples/greenfield/module-hybrid-cdn-auth-sso/src/utils/private-route.tsx

@@ -0,0 +1,100 @@
+import React, { useEffect, useMemo, useState } from 'react'
+import { useRouter } from '@tanstack/react-router'
+import Loader from '@/components/ui/loader/loader'
+import { Routes } from '@/config/routes'
+import { isPublicAuthRoute } from '@/features/auth/auth-route-paths'
+import { isHubSpotCmsEditor } from '@/hubspot/is-cms-editor'
+import { api, resolveAuthRouteAction } from '@/integrations/woodsportal-sdk'
+import { useAuthSessionRevision } from '@/features/auth/use-portal-session'
+import { navigateToLogin, navigateToMfaGate } from '@/features/auth/auth-navigation'
+import { isMfaPendingSession } from '@/features/auth/auth-session'
+
+const SESSION_RESTORE_LOADER_MS = 5_000
+
+function redirectUnauthenticatedToLogin(
+  router: ReturnType<typeof useRouter>,
+  inCmsEditor: boolean,
+): void {
+  const currentPath = router?.state?.location?.pathname
+  if (inCmsEditor) {
+    navigateToLogin(router)
+    return
+  }
+  const redirectPath =
+    currentPath !== Routes.login ? `?r=${router?.state?.location?.href}` : ''
+  navigateToLogin(router, `${Routes.login}${redirectPath}`)
+}
+
+const PrivateRoute: React.FC<{ children?: React.ReactNode }> = ({ children }) => {
+  const router = useRouter()
+  const sessionRevision = useAuthSessionRevision()
+  const inCmsEditor = isHubSpotCmsEditor()
+  const sessionRefreshExhausted = api.auth.session.isSessionRefreshExhausted?.() ?? false
+  const refreshInFlight = api.auth.session.isRefreshInFlight?.() ?? false
+  const hasRefreshHint = api.auth.session.hasRefreshSession()
+  const hasValidAccess = api.auth.session.hasValidAccessToken()
+
+  const sessionRestoring =
+    !sessionRefreshExhausted && refreshInFlight && hasRefreshHint && !hasValidAccess
+
+  const [restoreLoaderTimedOut, setRestoreLoaderTimedOut] = useState(false)
+
+  useEffect(() => {
+    if (!sessionRestoring) {
+      setRestoreLoaderTimedOut(false)
+      return
+    }
+    const id = window.setTimeout(() => setRestoreLoaderTimedOut(true), SESSION_RESTORE_LOADER_MS)
+    return () => window.clearTimeout(id)
+  }, [sessionRestoring])
+
+  const effectiveSessionRestoring = sessionRestoring && !restoreLoaderTimedOut
+
+  const routeAction = useMemo(() => {
+    const currentPath = router?.state?.location?.pathname
+    const session = api.auth.session.contract()
+    return resolveAuthRouteAction({
+      pathname: currentPath,
+      isPublicAuthRoute,
+      session: {
+        ...session,
+        isMfaPending: () => isMfaPendingSession(),
+      },
+      mfaRoute: Routes.twoFa,
+      previewMode: false,
+      sessionRestoring: effectiveSessionRestoring,
+      sessionRefreshExhausted,
+    })
+  }, [
+    router,
+    sessionRefreshExhausted,
+    effectiveSessionRestoring,
+    sessionRevision,
+    refreshInFlight,
+    hasRefreshHint,
+    hasValidAccess,
+  ])
+
+  useEffect((): void => {
+    if (routeAction.kind === 'redirect_mfa') {
+      navigateToMfaGate(router)
+      return
+    }
+    if (
+      routeAction.kind === 'redirect_login' ||
+      (routeAction.kind === 'show_loader' && restoreLoaderTimedOut)
+    ) {
+      redirectUnauthenticatedToLogin(router, inCmsEditor)
+    }
+  }, [routeAction, router, inCmsEditor, restoreLoaderTimedOut])
+
+  if (routeAction.kind === 'allow') {
+    return <>{children}</>
+  }
+  if (routeAction.kind === 'show_loader' && !restoreLoaderTimedOut) {
+    return <Loader showText={false} />
+  }
+  return null
+}
+
+export default PrivateRoute

package/examples/greenfield/module-hybrid-cdn-auth-sso/src/utils/public-route.tsx

@@ -0,0 +1,64 @@
+import React, { useLayoutEffect } from 'react'
+import { useRouter, useRouterState } from '@tanstack/react-router'
+import Loader from '@/components/ui/loader/loader'
+import { Routes } from '@/config/routes'
+import { isPublicAuthRoute } from '@/features/auth/auth-route-paths'
+import {
+  isRouterAtPath,
+  navigateAfterFullAuth,
+  navigateToLogin,
+  navigateToMfaGate,
+} from '@/features/auth/auth-navigation'
+import { resolvePostLoginPath } from '@/features/auth/resolve-post-login-path'
+import {
+  useAuthSessionRevision,
+  useIsMfaPendingSession,
+  usePortalSession,
+} from '@/features/auth/use-portal-session'
+import { isHubSpotCmsEditor } from '@/hubspot/is-cms-editor'
+
+const PublicRoute: React.FC<{ children?: React.ReactNode }> = ({ children }) => {
+  const router = useRouter()
+  const routeState = useRouterState()
+  const currentRoute = routeState.location.pathname
+  const isAuthenticated = usePortalSession()
+  const isMfaPending = useIsMfaPendingSession()
+  const sessionRevision = useAuthSessionRevision()
+  const inCmsEditor = isHubSpotCmsEditor()
+  const postLoginTarget = resolvePostLoginPath(router)
+
+  useLayoutEffect(() => {
+    const isPublicPath = isPublicAuthRoute(currentRoute)
+
+    if (isMfaPending && currentRoute !== Routes.twoFa) {
+      navigateToMfaGate(router)
+      return
+    }
+
+    if (!isAuthenticated && !isMfaPending && !isPublicPath) {
+      navigateToLogin(router)
+      return
+    }
+
+    if (isAuthenticated && isPublicPath && !(inCmsEditor && currentRoute === Routes.twoFa)) {
+      navigateAfterFullAuth(router)
+    }
+  }, [router, isAuthenticated, isMfaPending, inCmsEditor, currentRoute, sessionRevision])
+
+  if (isMfaPending) {
+    return currentRoute === Routes.twoFa ? <>{children}</> : <Loader showText={false} />
+  }
+
+  if (isAuthenticated && isPublicAuthRoute(currentRoute)) {
+    return isRouterAtPath(router, postLoginTarget) ? <>{children}</> : <Loader showText={false} />
+  }
+
+  if (!isAuthenticated) {
+    return <>{children}</>
+  }
+
+  // Authenticated on a general public page (e.g. /guide) — no redirect gate.
+  return <>{children}</>
+}
+
+export default PublicRoute

package/examples/greenfield/module-hybrid-cdn-auth-sso/src/utils/resolve-api-base-url.ts

@@ -0,0 +1,44 @@
+import { env } from '@/env'
+
+type HubSpotRuntimeData = {
+  developerOption?: boolean
+  developerOptionTempUrl?: string
+}
+
+type HubSpotRuntimeWindow = Window & {
+  hubSpotData?: HubSpotRuntimeData
+  /** Module-config live exports in `wp dev` / `yarn local` (see wphs.adapter.ts). */
+  __WPHS_DATA__?: HubSpotRuntimeData
+}
+
+function readHubSpotRuntimeData(): HubSpotRuntimeData | undefined {
+  if (typeof window === 'undefined') {
+    return undefined
+  }
+  const win = window as HubSpotRuntimeWindow
+  return win.hubSpotData ?? win.__WPHS_DATA__
+}
+
+/**
+ * API host for woodsportal-client-sdk.
+ * Priority: developer temp URL (HubSpot embed) → `VITE_PUBLIC_REST_API_ENDPOINT`.
+ * WoodsCLI dev (`__WPHS_DATA__` without HubL `hubSpotData`) always uses the Vite env URL.
+ */
+export function resolveWoodsPortalApiBaseUrl(
+  hubSpotData: HubSpotRuntimeData | undefined = readHubSpotRuntimeData(),
+): string {
+  const envApi = env.VITE_PUBLIC_REST_API_ENDPOINT
+
+  if (import.meta.env.DEV && typeof window !== 'undefined') {
+    const win = window as HubSpotRuntimeWindow
+    if (win.__WPHS_DATA__ != null && win.hubSpotData == null) {
+      return envApi
+    }
+  }
+
+  if (hubSpotData?.developerOption === true && hubSpotData.developerOptionTempUrl) {
+    return hubSpotData.developerOptionTempUrl
+  }
+
+  return envApi
+}

package/examples/greenfield/module-hybrid-cdn-auth-sso/src/utils/safe-router-navigation.ts

@@ -0,0 +1,82 @@
+export type SafeAuthRouter = {
+  navigate: (opts: { to: string; replace?: boolean }) => void | Promise<void>
+  history?: { replace: (path: string) => unknown }
+  state?: { location?: { pathname?: string; href?: string } }
+}
+
+export const NAVIGATION_WAIT_MS = 2500
+
+const PATHNAME_VERIFY_DELAY_MS = 100
+
+export function hashPath(path: string): string {
+  const trimmed = (path ?? '').trim()
+  if (!trimmed) {
+    return '#/'
+  }
+  if (trimmed.startsWith('#')) {
+    return trimmed
+  }
+  return trimmed.startsWith('/') ? `#${trimmed}` : `#/${trimmed}`
+}
+
+export function syncHashToPath(path: string): void {
+  if (typeof window === 'undefined') {
+    return
+  }
+  const expectedHash = hashPath(path)
+  if (window.location.hash !== expectedHash) {
+    window.location.hash = expectedHash
+  }
+}
+
+export async function raceNavigation(
+  router: SafeAuthRouter,
+  target: string,
+  timeoutMs: number = NAVIGATION_WAIT_MS,
+): Promise<void> {
+  await Promise.race([
+    Promise.resolve(router.navigate({ to: target, replace: true })).catch(() => undefined),
+    new Promise<void>((resolve) => window.setTimeout(resolve, timeoutMs)),
+  ])
+}
+
+export async function historyReplaceFirstNavigate(
+  router: SafeAuthRouter,
+  target: string,
+): Promise<void> {
+  const normalized = target.trim()
+  if (!normalized) {
+    return
+  }
+  try {
+    router.history?.replace(normalized)
+  } catch {
+    // fall through
+  }
+  await raceNavigation(router, normalized, NAVIGATION_WAIT_MS)
+  syncHashToPath(normalized)
+}
+
+export function hardReplaceToHashPath(target: string): void {
+  if (typeof window === 'undefined') {
+    return
+  }
+  const hash = hashPath(target)
+  window.location.replace(`${window.location.pathname}${hash}`)
+}
+
+export function readRouterPathname(router: SafeAuthRouter): string {
+  return router.state?.location?.pathname ?? ''
+}
+
+export function readHashPathname(): string {
+  if (typeof window === 'undefined') {
+    return ''
+  }
+  const raw = window.location.hash.replace(/^#/, '').split('?')[0]
+  return raw || '/'
+}
+
+export function safeRouterReplace(router: SafeAuthRouter, path: string): void {
+  void historyReplaceFirstNavigate(router, path.trim())
+}

package/examples/greenfield/module-hybrid-cdn-auth-sso/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"],
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "wphs.adapter.ts"]
+}

package/examples/greenfield/module-hybrid-cdn-auth-sso/vite.config.cdn-app.mjs

@@ -0,0 +1 @@
+export { default } from '@woodsportal/hubspot-kit/vite/vite.config.cdn-app.mjs'

package/examples/greenfield/module-hybrid-cdn-auth-sso/vite.config.cdn-esm.mjs

@@ -0,0 +1 @@
+export { default } from '@woodsportal/hubspot-kit/vite/vite.config.cdn-esm.mjs'

package/examples/greenfield/module-hybrid-cdn-auth-sso/vite.config.cdn-vendor.mjs

@@ -0,0 +1 @@
+export { default } from '@woodsportal/hubspot-kit/vite/vite.config.cdn-vendor.mjs'

package/examples/greenfield/module-hybrid-cdn-auth-sso/vite.config.dev.mjs

@@ -0,0 +1 @@
+export { default } from '@woodsportal/hubspot-kit/vite/vite.config.dev.mjs'

package/examples/greenfield/module-hybrid-cdn-auth-sso/vite.config.hubspot.mjs

@@ -0,0 +1 @@
+export { default } from '@woodsportal/hubspot-kit/vite/vite.config.hubspot.mjs'

package/examples/greenfield/module-hybrid-cdn-auth-sso/vite.config.monolith.mjs

@@ -0,0 +1,8 @@
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+if (!process.env.WP_HS_PROJECT_ROOT?.trim()) {
+  process.env.WP_HS_PROJECT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)))
+}
+
+export { default } from '@woodsportal/hubspot-kit/vite/vite.config.monolith.mjs'

package/examples/greenfield/module-hybrid-cdn-auth-sso/woodscli.json

@@ -0,0 +1,38 @@
+{
+  "configVersion": 1,
+  "projectType": "module-hybrid-cdn",
+  "module": {
+    "name": "module-hybrid-cdn-auth-sso",
+    "uploadPath": "dw-modules/module-hybrid-cdn-auth-sso.module",
+    "outDir": "dist/ModuleHybridCdnAuthSso.Module"
+  },
+  "cdn": {
+    "mode": "jsdelivr",
+    "buildIdFile": ".module-build-id",
+    "mirror": "portal.cdn.json"
+  },
+  "entries": {
+    "app": "src/cdn/app-entry.ts",
+    "vendor": "src/cdn/vendor-entry.ts",
+    "hubspotBootstrap": "src/hubspot/bootstrap.ts",
+    "module": "src/hubspot/module-entry.tsx",
+    "localDev": "src/main.tsx"
+  },
+  "env": {
+    "tiers": [
+      "dev",
+      "stg",
+      "prod"
+    ]
+  },
+  "dev": {
+    "moduleConfigDir": ".wphs",
+    "adapter": "./wphs.adapter.ts",
+    "fieldsJson": "public/fields.json"
+  },
+  "scaffold": {
+    "router": "hash",
+    "auth": "sso",
+    "nav": "top"
+  }
+}

package/examples/greenfield/module-hybrid-cdn-auth-sso/wphs.adapter.ts

@@ -0,0 +1,7 @@
+import type { HubSpotKitAdapter } from '@woodsportal/hubspot-kit'
+const adapter: HubSpotKitAdapter = {
+  syncLiveData(built) {
+    ;(window as Window & { __WPHS_DATA__?: Record<string, unknown> }).__WPHS_DATA__ = built
+  },
+}
+export default adapter

package/examples/greenfield/module-hybrid-cdn-auth-starter/.env.dev.example

@@ -0,0 +1,3 @@
+# Deployed dev CDN build (deploy:dev, ci:release-module:dev) — copy to .env.dev
+VITE_NODE_ENV=dev
+VITE_PUBLIC_REST_API_ENDPOINT=https://api.dev.woodsportal.com

package/examples/greenfield/module-hybrid-cdn-auth-starter/.env.local.example

@@ -0,0 +1,6 @@
+# Localhost SPA (yarn local / wp local) — copy to .env.local
+VITE_NODE_ENV=local
+VITE_DEV_MODE=live
+VITE_PUBLIC_REST_API_ENDPOINT=https://api.dev.woodsportal.com
+# VITE_DEV_PORTAL_ID=1
+# VITE_LOCAL_HUB_ID=12345678

package/examples/greenfield/module-hybrid-cdn-auth-starter/.env.prod.example

@@ -0,0 +1,5 @@
+# Production CDN build — copy to .env.prod (or run wp setup)
+VITE_NODE_ENV=prod
+VITE_PORTAL_EMBED_MODE=cdn
+VITE_PUBLIC_REST_API_ENDPOINT=https://api.woodsportal.com
+# PORTAL_CDN_PUBLISH_TOKEN is written to .env.local by wp init / wp setup (hybrid CDN) — gitignored

package/examples/greenfield/module-hybrid-cdn-auth-starter/.env.stg.example

@@ -0,0 +1,3 @@
+# Reserved — future staging CDN (wp build --tier stg). Copy to .env.stg when a staging API exists.
+VITE_NODE_ENV=stg
+# VITE_PUBLIC_REST_API_ENDPOINT=https://api.stg.woodsportal.com

package/examples/greenfield/module-hybrid-cdn-auth-starter/.wphs/README.md

@@ -0,0 +1,17 @@
+# WoodsCLI workspace (.wphs/)
+
+Local state for **WoodsCLI** (`@woodsportal/hubspot-kit`). Not shipped to HubSpot.
+
+| Path | Purpose |
+|------|---------|
+| `config/module-config.local.json` | Live Content/Styles values (gitignored) |
+| `config/module-config.example.json` | Example generated from `fields.json` |
+| `assets/branding/` | Dev-tool uploaded images (gitignored) |
+| `fixtures/` | Optional preview / hubspot-data overrides |
+| `cache/` | CLI caches (gitignored) |
+| `audit/baseline/` | Build parity snapshots (gitignored) |
+| `.kit-module-config` | Symlink to kit dev-module-config |
+| `.kit-bootstrap.tsx` | Symlink to kit dev bootstrap (full portal) |
+| `.kit-bootstrap-greenfield.tsx` | Symlink to kit greenfield dev bootstrap |
+
+Run `wp doctor` to recreate missing folders.

package/examples/greenfield/module-hybrid-cdn-auth-starter/README.md

@@ -0,0 +1,59 @@
+# Getting started
+
+This project was scaffolded with **WoodsCLI** (`@woodsportal/hubspot-kit`).
+
+## Daily dev
+
+```bash
+yarn install
+wp doctor
+wp dev
+```
+
+Open the local URL, then **Ctrl+Shift+Z** (Mac **⌃⇧Z**) to edit module fields. Click **Apply changes** to refresh the starter preview.
+
+## Routing (`wp init`)
+
+Default is **hash history** — same as `woodsportal-client-frontend` (`#/guide` URLs work in HubSpot CMS).
+
+| `wp init --router` | Behavior |
+|--------------------|----------|
+| `hash` (default) | `createHashHistory()` — production-safe in HubSpot embeds |
+| `browser` | Clean `/guide` URLs for local dev only |
+| `none` | Single-page starter, no TanStack Router |
+
+Recorded in `woodscli.json` → `scaffold.router`.
+
+## `src/` layout
+
+| Path | Purpose |
+|------|---------|
+| `main.tsx` | Dev entry — loads styles and `mountDevPreview()` |
+| `app.tsx` | `RouterProvider` shell (client-frontend pattern) |
+| `config/router.ts` | Hash vs browser history |
+| `portal/` | Dev vs production mount (`mount-dev-preview`, `mount-portal`) |
+| `routes/` | TanStack file routes — keep thin; import from `features/` |
+| `features/starter/` | Demo home + developer guide (replace with your app) |
+| `components/` | Shared layout and UI |
+| `integrations/` | Router and third-party wiring |
+| `hubspot/` | HubSpot types and dev fixtures |
+| `config/` | Route constants and app config |
+| `assets/css/` | Tailwind entry for local dev |
+
+Kit runtime expects `src/defaultData.ts` (re-exports `hubspot/default-data.ts`).
+
+## Docs (in the kit package)
+
+After `npm install`, see:
+
+- `node_modules/@woodsportal/hubspot-kit/docs/CLI-REFERENCE.md`
+- `node_modules/@woodsportal/hubspot-kit/docs/MODULES.md`
+- `node_modules/@woodsportal/hubspot-kit/docs/HUBSPOT-CLI-SETUP.md`
+
+## HubSpot upload
+
+```bash
+cp hubspot.config.yml.example hubspot.config.yml
+# add portal + personal access key
+wp upload
+```