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

package/CLAUDE.md

@@ -1,113 +0,0 @@
-# Claude Code Instructions — vite-plugin-cer-app
-
-This file contains project-specific instructions for Claude Code. Follow all rules below without exception.
-
----
-
-## Project overview
-
-`vite-plugin-cer-app` is a Vite plugin / meta-framework built on top of `@jasonshimmy/custom-elements-runtime`. It provides file-based routing, SSR/SSG/SPA rendering modes, auto-imports, virtual modules, and a composables layer. All source code is TypeScript.
-
----
-
-## NON-NEGOTIABLE requirements
-
-Every change — feature, bug fix, refactor — MUST satisfy all of the following before it is considered complete:
-
-### 1. Documentation
-- All new features must be **fully documented** in the relevant `docs/*.md` file.
-- Documentation must include: configuration options, API reference, usage examples, and known edge cases.
-- If a feature affects auto-imports, update `docs/configuration.md` (the auto-imports list).
-- If a feature adds a composable, add a full entry to `docs/composables.md`.
-- If a feature affects routing, update `docs/routing.md`.
-- If a feature affects middleware, update `docs/middleware.md`.
-- Documentation must be 100% accurate with the actual implementation — never document behavior that does not exist.
-
-### 2. Tests — unit
-- All new features must include **unit tests** using Vitest in `src/__tests__/`.
-- Tests must cover: typical usage, edge cases, and failure/error paths.
-- Never reduce existing test coverage.
-
-### 3. Tests — e2e
-- All new features must include **Cypress e2e tests** in `e2e/cypress/e2e/`.
-- E2e tests must cover typical usage and edge cases across all applicable build modes: SPA, SSR, SSG, and dev.
-- Add any required fixtures (kitchen-sink pages, middleware, components) to `e2e/kitchen-sink/`.
-- **NEVER run Cypress yourself.** Only the user runs Cypress. When e2e tests are ready, ask the user to run `npm run e2e` and report the results.
-
-### 4. Auto-imports
-- All new framework composables must be wired into `src/plugin/transforms/auto-import.ts` (`FRAMEWORK_IMPORTS` string + `FRAMEWORK_IDENTIFIERS` array).
-- Verify the auto-import works in pages, layouts, components, and middleware by adding a test to `src/__tests__/plugin/transforms/auto-import.test.ts`.
-
-### 5. TypeScript
-- All new code must be **strongly typed** — no `any`, no implicit `any`.
-- Prefer `interface` over `type` for object shapes.
-- All new public types must be exported from `src/types/` and re-exported from the package's type entry point.
-- The TypeScript compiler must not produce new errors. Run `npm run build` to verify.
-
-### 6. Validation
-- `npm run validate` (which runs `lint && npm test && npm run build && npm run e2e`) **MUST pass** before any change is considered complete.
-- The AI-runnable subset is `npm run lint && npm test && npm run build`. Run these yourself before asking the user to run Cypress.
-- Do not mark work as done if lint errors, type errors, or failing unit tests exist.
-
----
-
-## Important behaviors
-
-### Never run Cypress
-Cypress is run exclusively by the user. The AI must:
-1. Write the Cypress test file(s).
-2. Confirm lint + unit tests + build pass.
-3. Ask the user to run `npm run e2e` (or `npm run validate`) and report the results.
-
-### Virtual modules
-Virtual module IDs follow the pattern `virtual:cer-*`. They are resolved with a `\0` prefix in the Vite plugin's `resolveId` hook. Adding a new virtual module requires updating `VIRTUAL_IDS` in `src/plugin/index.ts` and the corresponding `generateVirtualModule` switch branch.
-
-### Auto-imports
-`src/plugin/transforms/auto-import.ts` injects framework composables into page/layout/component/middleware files. Adding a new composable requires:
-- Appending the identifier to `FRAMEWORK_IMPORTS` (the import statement string).
-- Adding it to `FRAMEWORK_IDENTIFIERS` (the array used to detect usage).
-
-### SSR isolation
-Per-request state uses `AsyncLocalStorage`. New per-request stores must follow the pattern in existing stores (create → run → cleanup) and be initialized in the request handler.
-
-### Kitchen-sink app
-`e2e/kitchen-sink/` is the test harness app. Every new feature needs at least one kitchen-sink page/component that exercises the feature so Cypress has something to test.
-
----
-
-## Commands reference
-
-| Command | Purpose |
-|---|---|
-| `npm run build` | Production build (plugin + types) |
-| `npm test` | Vitest unit tests |
-| `npm run test:coverage` | Unit test coverage report |
-| `npm run lint` | ESLint + TypeScript check |
-| `npm run e2e` | Cypress e2e tests (user only) |
-| `npm run validate` | Full pipeline: lint → test → build → e2e |
-
----
-
-## File layout
-
-```
-src/
-  plugin/           — Vite plugin implementation
-    virtual/        — Virtual module generators
-    transforms/     — Code transforms (auto-import, etc.)
-  runtime/          — Composables and runtime helpers
-    composables/    — useLocale, useCookie, useState, etc.
-  cli/              — CLI commands (build, adapt, dev)
-  types/            — Shared TypeScript interfaces
-  __tests__/        — Unit tests (mirrors src/ structure)
-
-e2e/
-  kitchen-sink/     — Test harness app
-    app/pages/      — Test pages
-    app/middleware/ — Test middleware
-    cer.config.ts   — Kitchen-sink config
-  cypress/
-    e2e/            — Cypress specs
-
-docs/               — Markdown documentation
-```

package/commits.txt

@@ -1 +0,0 @@
-- fix: add siteUrl configuration for canonical links and robots.txt generation (05c53ca)

package/cypress.config.ts

@@ -1,16 +0,0 @@
-import { defineConfig } from 'cypress'
-
-export default defineConfig({
-  e2e: {
-    specPattern: 'e2e/cypress/e2e/**/*.cy.ts',
-    supportFile: 'e2e/cypress/support/e2e.ts',
-    screenshotsFolder: 'e2e/cypress/screenshots',
-    videosFolder: 'e2e/cypress/videos',
-    // Pierce shadow DOM globally so all cy.get() calls work across shadow roots
-    includeShadowDom: true,
-    viewportWidth: 1280,
-    viewportHeight: 720,
-    // Give the server time to start
-    pageLoadTimeout: 15000,
-  },
-})

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.