@jasonshimmy/vite-plugin-cer-app 0.23.1 → 0.24.0

package/docs/authentication.md

@@ -1,285 +0,0 @@
-# Authentication
-
-The framework includes a built-in OAuth 2.0 authentication system. Enabling it auto-generates three API routes and provides `useAuth()` for reading the current user anywhere in your app.
-
----
-
-## Setup
-
-Install the providers you need in `cer.config.ts`:
-
-```ts
-// cer.config.ts
-import { defineConfig } from '@jasonshimmy/vite-plugin-cer-app'
-
-export default defineConfig({
-  auth: {
-    providers: {
-      github: {
-        clientId: process.env.GITHUB_CLIENT_ID!,
-        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-      },
-      google: {
-        clientId: process.env.GOOGLE_CLIENT_ID!,
-        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
-      },
-    },
-    redirectAfterLogin: '/dashboard',
-    redirectAfterLogout: '/',
-    sessionKey: 'auth',  // optional — defaults to 'auth'
-  },
-})
-```
-
-Configure the OAuth callback URL in your provider's developer console:
-
-```
-https://yourdomain.com/api/auth/callback/github
-https://yourdomain.com/api/auth/callback/google
-```
-
----
-
-## Generated routes
-
-When `auth` is configured, the framework automatically registers:
-
-| Route | Description |
-|---|---|
-| `GET /api/auth/:provider` | Initiates the OAuth flow — redirects the browser to the provider's authorization page |
-| `GET /api/auth/callback/:provider` | Handles the OAuth callback — exchanges the code for tokens, fetches the user profile, writes the auth session cookie, and redirects to `redirectAfterLogin` |
-| `GET /api/auth/logout` | Clears the auth session cookie and redirects to `redirectAfterLogout` |
-
-### OAuth error handling
-
-All network calls in the callback route (token exchange and user-info fetch) are wrapped in try/catch. If a provider is unreachable or returns an unexpected response, the handler responds with HTTP 502 and a plain-text diagnostic message rather than crashing the server:
-
-| Failure | Status | Response body |
-|---|---|---|
-| Token exchange network error | 502 | `[cer-app] OAuth token exchange request failed` |
-| Token exchange non-OK HTTP status | 502 | `[cer-app] OAuth token exchange returned non-OK status` |
-| Token exchange invalid JSON | 502 | `[cer-app] OAuth token exchange returned invalid JSON` |
-| User-info network error | 502 | `[cer-app] OAuth user-info request failed` |
-| User-info non-OK HTTP status | 502 | `[cer-app] OAuth user-info returned non-OK status` |
-| User-info invalid JSON | 502 | `[cer-app] OAuth user-info returned invalid JSON` |
-| Unknown provider | 404 | `[cer-app] Unknown OAuth provider: <name>` |
-| Missing state / code param | 400 | `[cer-app] OAuth callback missing code or state parameter` |
-| State mismatch (CSRF) | 400 | `[cer-app] OAuth state mismatch — possible CSRF attempt` |
-
-These responses are intentionally terse — they are server-to-server error messages, not end-user UI. To show a branded error page when OAuth fails, redirect in a top-level error boundary or handle the 502 at your reverse proxy / CDN layer.
-
----
-
-## `useAuth(sessionKey?)`
-
-`useAuth()` reads the authenticated user and provides helpers for login and logout. The optional `sessionKey` parameter specifies which session cookie to read (defaults to the value of `auth.sessionKey` in `cer.config.ts`, which itself defaults to `'auth'`). It works isomorphically:
-
-- **Server (SSR/SSG)** — reads the auth session from the per-request `AsyncLocalStorage` context (populated by the entry-server handler before rendering).
-- **Client** — reads from `globalThis.__CER_AUTH_USER__` (injected into the HTML by the server and captured by the client entry before the app boots).
-
-```ts
-// app/pages/profile.ts
-component('page-profile', () => {
-  const { user, loggedIn, login, logout } = useAuth()
-
-  return html`
-    ${loggedIn
-      ? html`
-          <p>Hello, ${user?.name}</p>
-          <img src="${user?.avatar}" alt="avatar" />
-          <button @click="${logout}">Log out</button>
-        `
-      : html`
-          <button @click="${() => login('github')}">Log in with GitHub</button>
-          <button @click="${() => login('google')}">Log in with Google</button>
-        `
-    }
-  `
-})
-```
-
-### `AuthComposable`
-
-| Member | Type | Description |
-|---|---|---|
-| `user` | `AuthUser \| null` | The authenticated user, or `null` if not logged in |
-| `loggedIn` | `boolean` | `true` when a user is authenticated |
-| `login(provider)` | `void` | Redirects to `/api/auth/:provider` to start the OAuth flow (client only) |
-| `logout()` | `void` (client) / `Promise<void>` (server) | Client: assigns `window.location.href` to `/api/auth/logout` (synchronous, no promise). Server: clears the auth session cookie directly and returns a promise. |
-
-### `AuthUser`
-
-| Field | Type | Description |
-|---|---|---|
-| `provider` | `string` | OAuth provider name, e.g. `'github'`, `'google'`, `'discord'` |
-| `id` | `string` | Provider-issued user ID |
-| `name` | `string?` | Display name |
-| `email` | `string?` | Email address |
-| `avatar` | `string?` | Profile picture URL |
-| `[key: string]` | `unknown` | Any additional fields from `mapUser` or the default normalisation |
-
----
-
-## Protecting routes with middleware
-
-Use `useAuth()` inside a middleware to guard protected pages:
-
-```ts
-// app/middleware/require-auth.ts
-export default defineMiddleware(() => {
-  const { loggedIn } = useAuth()
-  if (!loggedIn) return '/login'
-})
-```
-
-Attach it to a page via `meta.middleware`:
-
-```ts
-// app/pages/dashboard.ts
-component('page-dashboard', () => {
-  const { user } = useAuth()
-  return html`<h1>Welcome, ${user?.name}</h1>`
-})
-
-export const meta = { middleware: ['require-auth'] }
-```
-
----
-
-## Built-in providers
-
-Three providers are pre-configured. Supply only `clientId` and `clientSecret`:
-
-| Provider | Scopes | PKCE |
-|---|---|---|
-| `google` | `openid email profile` | ✅ S256 |
-| `github` | `read:user user:email` | ❌ not supported |
-| `discord` | `identify email` | ✅ S256 |
-
-Override scopes per provider:
-
-```ts
-github: {
-  clientId: process.env.GITHUB_CLIENT_ID!,
-  clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-  scope: ['read:user', 'repo'],  // add repo access
-},
-```
-
----
-
-## Custom providers
-
-Supply all three endpoint URLs for providers not built in:
-
-```ts
-export default defineConfig({
-  auth: {
-    providers: {
-      myProvider: {
-        clientId: process.env.MY_CLIENT_ID!,
-        clientSecret: process.env.MY_CLIENT_SECRET!,
-        authorizationUrl: 'https://auth.example.com/oauth/authorize',
-        tokenUrl: 'https://auth.example.com/oauth/token',
-        userInfoUrl: 'https://auth.example.com/oauth/userinfo',
-        scope: ['profile', 'email'],
-      },
-    },
-  },
-})
-```
-
----
-
-## Customising the user shape
-
-By default the framework normalises the provider's profile to `{ provider, id, name, email, avatar }`. Use `mapUser` to store additional or differently-shaped data in the session:
-
-```ts
-github: {
-  clientId: process.env.GITHUB_CLIENT_ID!,
-  clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-  mapUser: (profile, tokens) => ({
-    provider: 'github',
-    id: String(profile.id),
-    name: String(profile.name ?? profile.login),
-    email: String(profile.email ?? ''),
-    avatar: String(profile.avatar_url ?? ''),
-    login: String(profile.login),  // extra field
-    accessToken: tokens.accessToken,
-  }),
-},
-```
-
-The object returned by `mapUser` becomes `useAuth().user` on both server and client.
-
----
-
-## `auth.sessionKey`
-
-The auth session is stored in a signed `httpOnly` cookie. `sessionKey` sets the cookie name (default `'auth'`). It must not collide with other `useSession()` names in your app.
-
-Reading the session key explicitly is only needed if you call `useSession` manually for auth data:
-
-```ts
-const session = useSession({ name: 'auth' })
-const user = await session.get<AuthUser>()
-```
-
-`useAuth()` reads this automatically — prefer `useAuth()` over reading the session directly.
-
----
-
-## Security
-
-- **PKCE (S256)** is used for all providers that support it (Google, Discord). The code verifier is stored in a short-lived `_oauth_pkce` session cookie (10-minute TTL) and cleared after the callback.
-- **State parameter** — a 16-byte random value is generated per flow and verified in the callback, preventing CSRF.
-- **Client secrets** never appear in the client bundle. The auth handler is only imported by the server-side virtual module.
-
----
-
-## `defineOAuthProvider(config)`
-
-A type-safe helper for declaring providers in `cer.config.ts`. It is an identity function — it returns the config unchanged and exists purely so TypeScript infers the correct type for each field.
-
-Built-in providers (`google`, `github`, `discord`) only require `clientId` and `clientSecret`. Any endpoint URL or scope can be overridden. For a fully custom provider, all three endpoint URLs are required.
-
-```ts
-// cer.config.ts
-import { defineConfig } from '@jasonshimmy/vite-plugin-cer-app'
-import { defineOAuthProvider } from '@jasonshimmy/vite-plugin-cer-app/oauth'
-
-export default defineConfig({
-  auth: {
-    providers: {
-      github: defineOAuthProvider({
-        clientId: process.env.GITHUB_CLIENT_ID!,
-        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-        scope: ['read:user', 'user:email'],  // override default scopes
-      }),
-      myProvider: defineOAuthProvider({
-        clientId: process.env.MY_CLIENT_ID!,
-        clientSecret: process.env.MY_CLIENT_SECRET!,
-        authorizationUrl: 'https://auth.example.com/authorize',
-        tokenUrl: 'https://auth.example.com/token',
-        userInfoUrl: 'https://auth.example.com/userinfo',
-      }),
-    },
-  },
-})
-```
-
-Using `defineOAuthProvider` is optional — a plain object literal is also accepted. The helper exists only for TypeScript inference convenience.
-
----
-
-## TypeScript
-
-```ts
-import { useAuth } from '@jasonshimmy/vite-plugin-cer-app/composables'
-import { defineOAuthProvider } from '@jasonshimmy/vite-plugin-cer-app/oauth'
-import type { AuthUser, AuthComposable } from '@jasonshimmy/vite-plugin-cer-app/composables'
-import type { AuthConfig, OAuthProviderConfig } from '@jasonshimmy/vite-plugin-cer-app/types'
-```
-
-`useAuth` is auto-imported in `app/pages/`, `app/layouts/`, `app/components/`, `app/middleware/`, and `app/composables/`. No import statement is needed in those directories.

package/docs/cli.md

@@ -1,324 +0,0 @@
-# CLI Reference
-
-The framework provides two CLI programs:
-
-- **`cer-app`** — dev server, build, preview, and generate commands
-- **`create-cer-app`** — project scaffolding
-
-Both are available after installing `@jasonshimmy/vite-plugin-cer-app` as a dev dependency, or globally:
-
-```sh
-npm install -g @jasonshimmy/vite-plugin-cer-app
-```
-
----
-
-## `cer-app`
-
-### `cer-app dev`
-
-Starts the Vite development server. Reads `cer.config.ts` from the current directory.
-
-```sh
-cer-app dev [options]
-```
-
-| Option | Default | Description |
-|---|---|---|
-| `-p, --port <port>` | `3000` | Port to listen on |
-| `--host <host>` | `localhost` | Host to bind to |
-| `--root <root>` | `process.cwd()` | Project root directory |
-
-**Examples:**
-
-```sh
-cer-app dev
-cer-app dev --port 4000
-cer-app dev --host 0.0.0.0 --port 8080
-cer-app dev --root ./packages/my-app
-```
-
-**Behavior:**
-
-- Loads and transpiles `cer.config.ts` (or `cer.config.js`)
-- Starts the Vite dev server with `cerApp()` plugins applied
-- In SSR mode: intercepts HTML requests and renders server-side
-- In SPA mode: standard Vite HMR
-- Watches `app/` and `server/` directories; full-reloads when pages or components are added/removed
-- Responds to `SIGTERM` and `SIGINT` with graceful shutdown
-
----
-
-### `cer-app build`
-
-Builds the application for production.
-
-```sh
-cer-app build [options]
-```
-
-| Option | Default | Description |
-|---|---|---|
-| `--root <root>` | `process.cwd()` | Project root directory |
-| `--mode <mode>` | From `cer.config.ts` | Override rendering mode: `spa`, `ssr`, or `ssg` |
-
-**Examples:**
-
-```sh
-cer-app build
-cer-app build --mode ssr
-cer-app build --mode ssg
-cer-app build --root ./packages/my-app
-```
-
-**Per-mode behavior:**
-
-| Mode | Actions |
-|---|---|
-| `spa` | Standard `vite build` to `dist/` |
-| `ssr` | Dual build: client bundle to `dist/client/`, server bundle to `dist/server/server.js` |
-| `ssg` | Dual build + enumerate routes + render all paths to `dist/<path>/index.html` |
-
----
-
-### `cer-app preview`
-
-Serves the production build locally.
-
-```sh
-cer-app preview [options]
-```
-
-| Option | Default | Description |
-|---|---|---|
-| `-p, --port <port>` | `4173` | Port to listen on |
-| `--host <host>` | `localhost` | Host to bind to |
-| `--root <root>` | `process.cwd()` | Project root directory |
-| `--ssr` | Auto-detected | Load `dist/server/server.js` as the request handler |
-
-**Examples:**
-
-```sh
-cer-app preview                     # SPA/SSG static file server
-cer-app preview --ssr               # SSR server using dist/server/server.js
-cer-app preview --port 8080
-```
-
-**Behavior:**
-
-- If `dist/server/server.js` exists (or `--ssr` is passed), starts an SSR preview server
-- Static assets from `dist/client/` are served first; HTML requests fall through to the SSR handler
-- Otherwise, starts a static file server with SPA fallback (serves `index.html` for unknown paths)
-- Returns 404 for paths not found in `dist/` (static mode only)
-- **Path traversal protection:** all file requests are validated against the `dist/` root — requests attempting to escape it (e.g. `GET /../../../../etc/passwd`) receive a `400` response
-- **Security headers:** every response includes `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, and `Referrer-Policy: strict-origin-when-cross-origin`
-- **Smart Cache-Control:** Vite content-hashes assets placed in `/assets/` — these are served with `Cache-Control: public, max-age=31536000, immutable`. All other files (HTML, etc.) use `Cache-Control: no-cache` so browsers always revalidate
-- **Graceful shutdown:** on `SIGTERM` or `SIGINT`, the server stops accepting new connections and waits for in-flight requests to finish before exiting. A 10-second timeout triggers a forced exit if connections do not drain
-- **Request timeouts:** `headersTimeout` (10 s) aborts connections that stall while sending headers; `requestTimeout` (30 s) limits the total time allowed per request/response cycle, protecting against slow-client attacks
-
----
-
-### `cer-app generate`
-
-Runs the SSG build pipeline. Alias for `cer-app build --mode ssg`.
-
-```sh
-cer-app generate [options]
-```
-
-| Option | Default | Description |
-|---|---|---|
-| `--root <root>` | `process.cwd()` | Project root directory |
-
-**Example:**
-
-```sh
-cer-app generate
-```
-
-**Output:**
-
-```
-dist/
-  index.html
-  about/index.html
-  blog/
-    hello-world/index.html
-  ssg-manifest.json
-```
-
----
-
-### `cer-app adapt`
-
-Adapts the production build for a deployment platform.
-
-Run this after `cer-app build` to produce the platform-specific output alongside `dist/`.
-You can also configure `adapter` in `cer.config.ts` so the adapter runs automatically at the end of every build.
-
-```sh
-cer-app adapt [options]
-```
-
-| Option | Default | Description |
-|---|---|---|
-| `--platform <platform>` | *(required)* | Target platform: `vercel`, `netlify`, or `cloudflare` |
-| `--root <root>` | `process.cwd()` | Project root directory |
-
-**Examples:**
-
-```sh
-cer-app adapt --platform vercel
-cer-app adapt --platform netlify
-cer-app adapt --platform cloudflare
-cer-app adapt --platform vercel --root ./packages/my-app
-```
-
-**Vercel behavior (`--platform vercel`):**
-
-- Writes `.vercel/output/` following the [Vercel Build Output API v3](https://vercel.com/docs/build-output-api/v3).
-- SSR builds: creates a Node.js Serverless Function at `.vercel/output/functions/index.func/` that routes `/api/*` to the exported API handlers and passes everything else to the SSR handler. Content-hashed assets are copied to `.vercel/output/static/` for CDN delivery.
-- SPA/SSG builds: copies static files to `.vercel/output/static/` with a SPA fallback route.
-- Deploy with `vercel deploy --prebuilt`.
-
-**Netlify behavior (`--platform netlify`):**
-
-- Writes `netlify/functions/ssr.mjs` — a Netlify Functions v2 bridge that converts the Web `Request`/`Response` API to the Node.js-style handler used by the server bundle. Handles `/api/*` routing inline.
-- Copies content-hashed assets to `.netlify/publish/` (no `index.html` — HTML is served by the function).
-- Writes `netlify.toml` with the publish directory, `Cache-Control` headers for assets, and a catch-all redirect to the SSR function.
-- SPA/SSG builds: writes `netlify.toml` only (no function needed).
-- SSR responses are streamed via the Web Streams `TransformStream` API — HTML chunks are forwarded to the client as they are written rather than waiting for the full page to render.
-- Deploy with `netlify deploy`.
-
-**Cloudflare behavior (`--platform cloudflare`):**
-
-- Writes `dist/_worker.js` — a Cloudflare Pages [Advanced Mode](https://developers.cloudflare.com/pages/functions/advanced-mode/) worker. The client HTML template is inlined in the worker as a string constant so `node:fs` is never needed at runtime.
-- Requires the `nodejs_compat` compatibility flag (written automatically into `wrangler.toml`) for `AsyncLocalStorage` and `node:stream` support.
-- Copies content-hashed assets to `dist/` alongside the worker. Cloudflare Pages CDN serves matched static files first; all other requests fall through to `_worker.js`.
-- SPA/SSG builds: no worker generated — Cloudflare Pages serves `dist/` as a static site.
-- SSR responses are streamed via the Web Streams `TransformStream` API — HTML chunks are forwarded to the client as they are written rather than waiting for the full page to render.
-- Deploy with `wrangler pages deploy dist`.
-
-**Auto-run via `cer.config.ts`:**
-
-```ts
-// cer.config.ts — built-in adapter
-export default defineConfig({
-  mode: 'ssr',
-  adapter: 'vercel',  // 'vercel' | 'netlify' | 'cloudflare'
-})
-```
-
-```ts
-// cer.config.ts — custom adapter (Railway, Fly.io, bare Node.js, Docker, …)
-export default defineConfig({
-  mode: 'ssr',
-  adapter: async (root) => {
-    const { cp, mkdir } = await import('node:fs/promises')
-    await mkdir(`${root}/deploy`, { recursive: true })
-    await cp(`${root}/dist`, `${root}/deploy/dist`, { recursive: true })
-  },
-})
-```
-
-Pass `--platform custom` to `cer-app adapt` to run a function adapter without re-building:
-
-```sh
-cer-app adapt --platform custom
-```
-
-See [`adapter` in configuration.md](./configuration.md#adapter) for the full options reference.
-
----
-
-## `create-cer-app`
-
-Scaffolds a new project from a template.
-
-> **Note:** Because the scaffolder is bundled inside `@jasonshimmy/vite-plugin-cer-app` rather than published as a standalone `create-cer-app` package, you must use the `--package` flag with `npx`:
->
-> ```sh
-> npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app [project-name] [options]
-> ```
-
-| Argument / Option | Description |
-|---|---|
-| `[project-name]` | Name of the project (also used as the output directory) |
-| `--mode <mode>` | Rendering mode: `spa`, `ssr`, or `ssg` (skips interactive prompt) |
-| `--dir <dir>` | Output directory (defaults to `project-name`) |
-
-**Examples:**
-
-```sh
-npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app                          # interactive prompts
-npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-app                   # prompts for mode
-npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-app --mode ssr        # no prompts
-npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-blog --mode ssg --dir ./sites/blog
-```
-
-**Scaffolded files (all modes):**
-
-```
-my-app/
-  app/
-    app.ts          ← framework bootstrap (router, plugins, layout shell)
-    pages/index.ts
-    layouts/default.ts
-  index.html
-  cer.config.ts
-  package.json
-```
-
-**Per-mode differences:**
-
-| Mode | `cer.config.ts` | `package.json` scripts |
-|---|---|---|
-| SPA | `mode: 'spa'` | `dev`, `build`, `preview` |
-| SSR | `mode: 'ssr'` | `dev`, `build`, `preview --ssr` |
-| SSG | `mode: 'ssg'`, `ssg.routes: 'auto'` | `dev`, `build`, `preview`, `generate` |
-
----
-
-## Config file loading
-
-Both `cer-app dev` and `cer-app build` load `cer.config.ts` by:
-
-1. Bundling it with Vite into a temporary `.mjs` file in `node_modules/.cer-app-cache/`
-2. Dynamically importing the result
-
-This allows TypeScript syntax in `cer.config.ts` with full type checking. The cached bundle is regenerated on every CLI invocation.
-
-If no `cer.config.ts` or `cer.config.js` is found, defaults are used and a warning is printed.
-
----
-
-## Using with `npm run`
-
-After scaffolding, scripts are already set up in `package.json`:
-
-```json
-{
-  "scripts": {
-    "dev": "cer-app dev",
-    "build": "cer-app build",
-    "preview": "cer-app preview",
-    "generate": "cer-app generate"
-  }
-}
-```
-
-```sh
-npm run dev
-npm run build
-npm run preview
-```
-
----
-
-## Using with `npx` (no global install)
-
-```sh
-npx cer-app dev
-npx cer-app build
-npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-app
-```