@chidchanun/bcp 0.1.8 → 0.1.10

package/docs/route-guards.md

@@ -0,0 +1,240 @@
+# Protected Route Guards
+
+BCP route guards provide server-side protection for pages and page subtrees without repeating authentication checks in every `loader.ts`.
+
+A guard lives in `guard.ts` or `guard.tsx` inside the `app/` tree. It protects pages in that directory and descendant route directories.
+
+```text
+app/
+└─ dashboard/
+   ├─ guard.ts
+   ├─ page.tsx
+   └─ users/
+      └─ [id]/
+         ├─ loader.ts
+         └─ page.tsx
+```
+
+## Authentication guard
+
+```ts
+// app/dashboard/guard.ts
+import {
+    getSession,
+    redirect,
+} from "bcp/server";
+
+export async function guard() {
+    const session =
+        await getSession<{
+            userId: number;
+            email: string;
+            role: string;
+        }>();
+
+    if (!session) {
+        return redirect(
+            "/login",
+            303
+        );
+    }
+
+    return {
+        session,
+        role:
+            session.role,
+    };
+}
+```
+
+The guard runs before the route loader and page render. Returning a Web `Response`, including `redirect()`, stops the pipeline immediately.
+
+## Guard context
+
+A guard receives:
+
+```ts
+interface GuardContext {
+    params: Record<string, string | string[] | undefined>;
+    searchParams: URLSearchParams;
+    parentData: Readonly<Record<string, unknown>>;
+}
+```
+
+`params` contains the matched route params and `searchParams` represents the target page URL. `parentData` contains the JSON-safe values returned by ancestor guards.
+
+Example nested role guard:
+
+```ts
+// app/dashboard/admin/guard.ts
+import {
+    redirect,
+} from "bcp/server";
+
+export async function guard({
+    parentData,
+}) {
+    if (
+        parentData.role !==
+        "admin"
+    ) {
+        return redirect(
+            "/dashboard",
+            303
+        );
+    }
+
+    return {
+        section:
+            "admin",
+    };
+}
+```
+
+Guards execute from the app root toward the page directory. Later guards receive the merged output of earlier guards.
+
+## Using guard data in a loader
+
+Loaders receive the final merged guard data as `guardData`:
+
+```ts
+// app/dashboard/users/[id]/loader.ts
+export async function loader({
+    params,
+    guardData,
+}) {
+    return {
+        id:
+            params.id,
+        currentUser:
+            guardData.session,
+        role:
+            guardData.role,
+    };
+}
+```
+
+This avoids calling `getSession()` again after the guard has already validated the request.
+
+## Using guard data in a page
+
+Pages can read the same serialized guard result with `useGuardData<T>()`:
+
+```tsx
+"use client";
+
+import {
+    useGuardData,
+} from "bcp";
+
+export default function DashboardPage() {
+    const guard =
+        useGuardData<{
+            session: {
+                userId: number;
+                email: string;
+            };
+            role: string;
+        }>();
+
+    return (
+        <main>
+            Signed in as {
+                guard.session.email
+            }
+        </main>
+    );
+}
+```
+
+Guard data is available during SSR, hydration and SPA navigation. A guarded page does not need a `loader.ts` just to expose guard data.
+
+## Serialization rules
+
+Guard return values must be JSON-safe because they are passed to loaders and, when the page reads them, serialized into framework navigation/SSR data.
+
+Supported values include:
+
+- `null`
+- strings
+- booleans
+- finite numbers
+- arrays containing supported values
+- plain objects containing supported values
+
+Unsupported values include functions, symbols, BigInt, non-finite numbers, class instances, Date/Map/Set objects and circular references.
+
+Do not place passwords, raw authentication secrets, private keys or other sensitive server-only secrets in guard data. Guard data may be serialized to the browser when the page uses the route framework data pipeline.
+
+## Cookies and sessions
+
+Guards run inside the normal BCP request context, so they can use:
+
+```ts
+import {
+    cookies,
+    getSession,
+    headers,
+    requestId,
+    requestMethod,
+    requestUrl,
+} from "bcp/server";
+```
+
+Cookies set while an allowed guard runs are preserved on the final document or SPA navigation response. Cookies set before a guard redirect are preserved on that redirect as well.
+
+## Direct requests and SPA navigation
+
+The same guard rules apply to:
+
+- direct browser requests
+- `<Link>` navigation
+- `navigate()`
+- `router.push()`
+- `router.replace()`
+- browser history navigation
+- loader-backed SPA navigation
+
+For SPA navigation, the guard evaluates the target page URL rather than the internal `/_bcp/navigation` transport URL.
+
+A guard redirect is converted to a navigation redirect payload when appropriate so same-origin navigation can continue through the BCP router while preserving response cookies.
+
+## Middleware and guard order
+
+Production request order is intentionally layered:
+
+```text
+Security gateway
+    ↓
+Response cache gateway
+    ↓
+Project middleware
+    ↓
+Route guard
+    ↓
+Page loader
+    ↓
+SSR / navigation payload
+```
+
+Project middleware therefore remains the outer application interception layer. Route guards are intended for page authorization and route-specific access policy.
+
+## Cache safety
+
+Pages protected by route guards are excluded from the automatic production page response cache. Guard results may depend on sessions, cookies, roles or user-specific state, so caching a guarded document without a user-aware key would be unsafe.
+
+Applications can still use explicit server data caching where the cache key and invalidation strategy are safe for the data being cached.
+
+## Internal transport hardening
+
+Standalone production transports evaluated guard data to the inner page runtime through a private framework header. Incoming user-supplied values for that header are removed before guard evaluation and before proxying so a browser cannot forge a successful guard result.
+
+The serialized internal guard payload is size-limited. Applications should return only the small identity/authorization data required by descendant guards, loaders and pages.
+
+## Guard versus middleware
+
+Use a route guard when access policy belongs to a page subtree and should integrate directly with loaders and page data.
+
+Use middleware when a request-wide concern needs to run before route execution, such as rewrites, global redirects, shared request policy or non-page request interception.
+
+Both can be used together; middleware runs before route guards.

package/docs/server-data-loaders.md

@@ -0,0 +1,240 @@
+# Server data loaders
+
+BCP 0.1.9 adds route-level server data loading for pages. A loader lives next to a page and runs on the server before that page is rendered. Loader-backed routes also participate in BCP client navigation: a navigation request executes the target loader on the server, returns fresh loader data, and renders the next route without requiring a full document reload.
+
+## File convention
+
+```text
+app/
+└─ users/
+   └─ [id]/
+      ├─ loader.ts
+      └─ page.tsx
+```
+
+`loader.ts` must export a named `loader()` function:
+
+```ts
+import {
+    getSession,
+    redirect,
+} from "bcp/server";
+
+export async function loader({
+    params,
+    searchParams,
+}: {
+    params: {
+        id: string;
+    };
+    searchParams: URLSearchParams;
+}) {
+    const session =
+        await getSession();
+
+    if (!session) {
+        return redirect(
+            "/login",
+            303
+        );
+    }
+
+    return {
+        id:
+            params.id,
+        filter:
+            searchParams.get(
+                "filter"
+            ),
+        user:
+            session,
+    };
+}
+```
+
+The matching page reads the loader result with `useLoaderData<T>()`:
+
+```tsx
+"use client";
+
+import {
+    useLoaderData,
+} from "bcp";
+
+interface UserLoaderData {
+    id: string;
+    filter: string | null;
+    user: {
+        sub: string;
+    };
+}
+
+export default function UserPage() {
+    const data =
+        useLoaderData<
+            UserLoaderData
+        >();
+
+    return (
+        <main>
+            <h1>
+                User {data.id}
+            </h1>
+        </main>
+    );
+}
+```
+
+## Loader context
+
+A loader receives:
+
+- `params` — the matched file-route parameters, including dynamic segments.
+- `searchParams` — a fresh `URLSearchParams` instance for the target request URL.
+
+Loaders run inside the normal BCP request context. Server-only helpers from `bcp/server`, including `headers()`, `cookies()`, `requestUrl()`, `requestMethod()`, `requestId()`, `clientIp()`, `bearerToken()`, `getSession()` and `redirect()`, are available while the loader is running.
+
+For both initial document requests and SPA navigations, the loader request context is created for the target page URL rather than the internal `/_bcp/navigation` transport URL. For example, navigating to `/users/42?filter=active` makes `requestUrl()` observe `/users/42?filter=active` and gives the loader the matching query string.
+
+This makes the recommended authenticated page flow:
+
+```text
+Initial document request
+    ↓
+loader.ts
+    ↓
+Session / database / authorization
+    ↓
+serializable loader data
+    ↓
+SSR page
+    ↓
+useLoaderData() during hydration
+
+Later <Link> / router navigation
+    ↓
+/_bcp/navigation
+    ↓
+loader.ts runs for the target URL
+    ↓
+fresh session / cookie / database state
+    ↓
+navigation payload with loader data
+    ↓
+client renders the target route
+```
+
+Database modules should remain server-only and can be imported directly by `loader.ts`.
+
+## Return values
+
+A loader can return either serializable data or a Web `Response`.
+
+### Data
+
+Loader data must contain only JSON-compatible values:
+
+- `null`
+- strings
+- booleans
+- finite numbers
+- arrays of supported values
+- plain objects containing supported values
+
+Values such as `Date`, `Map`, `Set`, functions, symbols, `BigInt`, class instances, `NaN`, `Infinity` and circular object graphs are rejected. Convert database-specific values to JSON-safe values before returning them.
+
+```ts
+export async function loader() {
+    const user =
+        await findUser();
+
+    return {
+        id:
+            user.id,
+        createdAt:
+            user.createdAt.toISOString(),
+    };
+}
+```
+
+The result is rendered through a server-side loader-data provider and serialized into BCP framework data. During SPA navigation the same data is carried in the navigation payload and written into the framework data before the target client bundle renders. `loader.ts` itself is never imported by the browser entry.
+
+### Redirects and other responses
+
+A loader can return a standard `Response`, including the BCP `redirect()` helper:
+
+```ts
+import {
+    cookies,
+    redirect,
+} from "bcp/server";
+
+export async function loader() {
+    const cookieStore =
+        await cookies();
+
+    cookieStore.set(
+        "last_guard",
+        "private-page",
+        {
+            httpOnly: true,
+            sameSite: "lax",
+            path: "/",
+        }
+    );
+
+    return redirect(
+        "/login",
+        303
+    );
+}
+```
+
+Response cookies created during the loader are merged into the returned response, including redirects.
+
+For an SPA navigation, BCP converts an HTTP redirect into a navigation redirect payload while preserving all `Set-Cookie` values. Same-origin redirects continue through the BCP router without a full page reload. Cross-origin redirects are handed to normal browser navigation. The client router limits a single navigation chain to 10 redirects to prevent redirect loops.
+
+A loader may also return another Web `Response`. If that response is not a navigation payload or supported redirect response, the client router falls back to a normal document request so the original HTTP semantics are preserved.
+
+## Client navigation behavior in 0.1.9
+
+Routes with and without loaders both support BCP SPA navigation.
+
+When `<Link>`, `navigate()`, `router.push()`, `router.replace()`, browser history navigation, or `router.refresh()` targets a loader-backed page, BCP performs the following work:
+
+1. Starts navigation state immediately and aborts the previous in-flight navigation request.
+2. Requests `/_bcp/navigation` with the target pathname and query string.
+3. Runs the target route loader on the server inside a fresh request context.
+4. Returns route metadata, client asset information and the fresh loader data in one navigation payload.
+5. Writes the payload into `__BCP_DATA__` before importing/rendering the target client bundle.
+6. Reuses the existing React root so persistent layouts can keep client state where React reconciliation allows it.
+
+`AbortController` cancels superseded network requests. BCP also assigns each navigation a monotonically increasing sequence so a stale response that completes after a newer navigation is not allowed to update router state. The route bundle import receives the navigation identifier as its cache-busting query parameter as well.
+
+`loading.tsx` remains part of the navigation payload. `useNavigation()` is set to navigating before the server request starts; once the payload arrives, the matching loading markup can be shown while target assets/runtime work completes.
+
+## Middleware and security
+
+SPA loader navigation still travels through the normal BCP middleware and security gateway chain before reaching the loader navigation runtime. Applications should still enforce page authorization inside the loader itself because the loader owns the target page data and can make the authorization decision using `getSession()`, cookies, headers or database state.
+
+The internal `/_bcp/navigation` endpoint is transport infrastructure and is not a substitute for loader-level authorization checks.
+
+## Response cache behavior
+
+Loader-backed pages are excluded from the production response-cache manifest by default. A loader can depend on cookies, sessions, authorization headers, request identity or user-specific database state, so automatically placing the resulting HTML in a public route cache would be unsafe.
+
+Caching inside a loader can still be implemented explicitly with application-aware data caching where the cache key and invalidation model are known.
+
+Navigation payloads are sent with `Cache-Control: no-store` and `X-Content-Type-Options: nosniff`.
+
+## Error and not-found behavior
+
+Errors thrown by a loader enter the same page error handling path as SSR errors. For navigation requests, server errors or unsupported response shapes cause the router to fall back to a normal document request so the page-level error/not-found rendering path remains authoritative.
+
+A loader can also call existing server/runtime primitives that throw the framework not-found signal; the matching `not-found.tsx` boundary remains responsible for rendering the 404 page.
+
+## Development reloads
+
+`loader.ts` and `loader.tsx` are watched as server files during development. Loader modules use a server-side cache-busting version during document rendering and navigation, so edits are reflected without putting loader code in the browser dependency graph.
+
+Only one loader file may exist next to a page. Having both `loader.ts` and `loader.tsx` is treated as a framework configuration error.

package/docs/updating.md

@@ -0,0 +1,130 @@
+# Updating BCP Framework
+
+BCP includes a project updater that can move an existing application to a newer published framework version and refresh the active package-manager lockfile.
+
+## First update from 0.1.9 or older
+
+BCP versions published before the updater do not know the `update` command. Run the newest CLI explicitly once:
+
+```bash
+npx @chidchanun/bcp@latest update
+```
+
+The updater adds this project script when the application does not already define its own `update` script:
+
+```json
+{
+  "scripts": {
+    "update": "bcp update"
+  }
+}
+```
+
+Normal future updates can therefore use either:
+
+```bash
+bcp update
+```
+
+or, without a global BCP installation:
+
+```bash
+npm run update
+```
+
+## Update to latest
+
+```bash
+bcp update
+```
+
+This resolves `@chidchanun/bcp@latest` from npm, pins that exact resolved release in `package.json`, detects the project's package manager and runs its install command.
+
+For example, if `latest` resolves to `0.1.10`, a generated application becomes:
+
+```json
+{
+  "dependencies": {
+    "bcp": "npm:@chidchanun/bcp@0.1.10"
+  }
+}
+```
+
+The exact pin is intentional. A later plain `npm install` should not silently move the framework to a release that the BCP updater did not explicitly resolve.
+
+Generated applications use the dependency key `bcp` with an npm alias to `@chidchanun/bcp`. The updater also recognizes a direct `@chidchanun/bcp` dependency.
+
+## Update to a specific version or dist-tag
+
+```bash
+bcp update 0.1.10
+bcp update next
+```
+
+The target may be an exact published version or an npm dist-tag. The updater always records the exact version that the registry resolves.
+
+## Check without changing files
+
+```bash
+bcp update --check
+```
+
+The command resolves the current `latest` target and prints the installed/declaration state without modifying `package.json` or the lockfile.
+
+## Dry run
+
+```bash
+bcp update 0.1.10 --dry-run
+```
+
+A dry run resolves the target and shows the dependency/script changes without writing files or installing packages.
+
+## Project root
+
+Use `--root` when updating a project from another directory:
+
+```bash
+bcp update --root ./apps/admin
+```
+
+## Package-manager detection
+
+BCP detects the package manager from its lockfile:
+
+- `package-lock.json` -> npm
+- `pnpm-lock.yaml` -> pnpm
+- `yarn.lock` -> Yarn
+- `bun.lock` / `bun.lockb` -> Bun
+
+If no lockfile exists, BCP uses the invoking package-manager user agent when available and otherwise falls back to npm. If lockfiles from multiple package managers are present, the updater stops instead of guessing.
+
+Registry version discovery currently uses npm's registry CLI (`npm view`) even when the project itself installs dependencies with pnpm, Yarn or Bun.
+
+## Failure safety
+
+Before installation BCP keeps the original `package.json` and detected lockfile in memory. If the package-manager install fails, those files are restored before the command exits with an error.
+
+A package manager may still have touched `node_modules` before failing, so run the normal install command again after resolving the underlying package-manager or network problem.
+
+## What the updater changes
+
+The updater changes the framework dependency, adds `scripts.update = "bcp update"` when no update script exists, and refreshes the package-manager lockfile. An existing custom `update` script is never overwritten.
+
+It does not overwrite application source code, environment files, authentication implementations, database schemas or custom configuration.
+
+Features that were originally generator presets, such as JWT auth scaffolding, are not automatically injected into an existing application merely by updating the framework package.
+
+## Recommended verification
+
+After an update, run the checks used by your project, for example:
+
+```bash
+npm run typecheck
+npm run build
+```
+
+Commit `package.json` and the lockfile together after verification.
+
+## Release channels
+
+Stable BCP releases use the npm `latest` dist-tag. A release maintainer can still publish an explicit pre-release channel with `BCP_DIST_TAG`, for example `BCP_DIST_TAG=next`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",