@chidchanun/bcp 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -2,6 +2,88 @@
 
 All notable framework changes are tracked here before release.
 
+## 0.1.10 - Framework updater and protected route guards
+
+### Framework updater
+
+- Added `bcp update` to resolve and install the current `@chidchanun/bcp@latest` release from an existing BCP application.
+- Added `bcp update <version-or-tag>` for explicitly targeting a published version or npm dist-tag.
+- Added `bcp update --check` and `bcp update --dry-run` so projects can inspect an available update without changing package metadata or lockfiles.
+- Existing generated `bcp` npm aliases and direct `@chidchanun/bcp` dependencies are detected automatically.
+- Package-manager detection supports npm, pnpm, Yarn and Bun lockfiles and refuses to guess when conflicting lockfiles are present.
+- Failed installs restore the original `package.json` and detected lockfile before returning an error.
+- Projects published before the updater can bootstrap it once with `npx @chidchanun/bcp@latest update`; subsequent releases can use `bcp update` or the generated `npm run update` script directly.
+- Generated applications pin the exact resolved BCP version so a normal package-manager install does not silently cross framework releases.
+- Added unit coverage for updater argument parsing, dependency planning, package-manager detection and ambiguous dependency rejection.
+- Added publish-artifact smoke checks requiring the updater source and CLI dispatch wiring.
+
+### Protected routes and auth guards
+
+- Added scoped `guard.ts` / `guard.tsx` files that protect pages in their route directory and descendant page directories.
+- Guards execute from app root toward the matched page and receive `params`, target `searchParams` and merged ancestor `parentData`.
+- A guard may return JSON-safe authorization data or a Web `Response`; redirects stop the pipeline before loader/page execution.
+- Guards run inside the normal BCP request context, so sessions, cookies, headers, request URLs, request IDs and other `bcp/server` helpers are available directly.
+- Loader context now receives merged `guardData`, avoiding repeated session/role lookups after a guard has already validated the request.
+- Added public `useGuardData<T>()` so pages can consume the same guard result during SSR, hydration and SPA navigation.
+- Guard-only routes are supported without requiring a page loader.
+- Response cookies set by allowed guards or redirecting guards are preserved on document and navigation responses.
+- Guard return values use the same JSON-safe validation rules as loader data and reject unsupported/circular values before transport.
+- Direct requests and SPA navigation use the same authorization policy, including target-page params/query values and redirects.
+- Standalone production generates a server-only `guards.mjs` evaluator and places the guard gateway after project middleware but before loader/page execution.
+- User-supplied internal guard transport headers are stripped before authorization evaluation so clients cannot forge guard results.
+- Internal serialized guard data is size-limited before it is proxied to the inner standalone runtime.
+- Route-guarded pages are excluded from the automatic production response cache because their output may depend on session/role identity.
+- Added `/guard-demo/[id]` and guard-only fixtures covering parent/child guard data, roles, cookies, loader integration and redirects.
+- Added unit, development integration and standalone E2E coverage for guards, including forged-header rejection and guard-only production routes.
+- Added publish-artifact smoke checks for the guard evaluator, standalone guard runtime, public hook and loader/guard bridge.
+- Added dedicated protected-route documentation and updated README guidance for middleware versus route guards.
+
+### Release channel
+
+- Stable BCP releases now publish to the npm `latest` dist-tag by default even while the framework is pre-1.0.
+- Maintainers can still select `next`, `beta` or another channel explicitly through `BCP_DIST_TAG`.
+
+## 0.1.9 - Server data loaders
+
+### Server rendering and data
+
+- Added route-level `loader.ts` / `loader.tsx` files next to `page.tsx` for server-only page data loading before SSR.
+- Added public `useLoaderData<T>()` through `bcp` so the page consumes the same loader value during SSR, browser hydration and later client navigations.
+- Loader context includes matched route `params` and a fresh `URLSearchParams` instance for the target request query string.
+- Loaders run inside the normal request context, so `cookies()`, `headers()`, `requestUrl()`, request/auth helpers and JWT session APIs can be used directly.
+- Loader modules may import application server-only/database modules without placing those dependencies in the browser bundle.
+- Loaders may return either JSON-safe data or a Web `Response`, including `redirect()` responses.
+- Response cookies created while a loader runs are merged into the final page, navigation or redirect response.
+- Loader results are serialized into framework data with the existing script-safe serialization rules and are provided to SSR through an internal loader-data provider.
+- Loader data rejects unsupported values such as functions, symbols, BigInt, non-finite numbers, class instances, Date/Map/Set objects and circular graphs.
+- Having both `loader.ts` and `loader.tsx` next to one page is rejected as an ambiguous route configuration.
+
+### SPA navigation and cache safety
+
+- Loader-backed routes now participate in BCP SPA navigation instead of requiring a full document reload.
+- `/_bcp/navigation` executes the target route loader on the server and returns fresh loader data together with route metadata and client asset information.
+- Navigation loaders receive a request context for the target page URL rather than the internal navigation transport URL, preserving target query parameters, cookies, sessions and request helpers.
+- Loader redirects are converted to a navigation redirect payload while preserving all response cookies; same-origin redirects continue through the SPA router and cross-origin redirects use normal browser navigation.
+- Non-navigation Web `Response` values continue to fall back to a document request so their original HTTP semantics remain authoritative.
+- Client navigation explicitly sends same-origin credentials, aborts superseded requests and uses a monotonically increasing navigation sequence so stale responses cannot update router state after a newer navigation has started.
+- Navigation redirect chains are capped at 10 redirects to prevent loops.
+- `useNavigation()` becomes active before the server request starts and route loading markup can be displayed while the target client runtime/assets finish after the payload arrives.
+- Standalone loader navigation is placed inside the existing middleware/security chain rather than bypassing application middleware or framework security gateways.
+- Production response-cache manifests continue to exclude loader-backed pages automatically because loader output may be user/request specific.
+- Navigation payload responses use `Cache-Control: no-store` and `X-Content-Type-Options: nosniff`.
+
+### Production and reliability
+
+- Standalone production entries bundle each loader into the server artifact only and attach it to the corresponding page route definition.
+- Added a standalone loader-navigation gateway only when an application actually has loader-backed routes; applications without loaders keep the existing production runtime path.
+- Development loader imports use a server-side cache-busting version so edits are reflected without creating a client dependency edge.
+- Added a `/loader-demo/[id]` fixture covering route params, query params, cookies, request method, request URL, SSR serialization and redirect response cookies.
+- Added unit coverage for loader discovery, execution, response returns, serialization validation, duplicate-loader detection and SPA redirect/cookie transport.
+- Added development integration coverage for SSR loader data plus SPA navigation data, target request context, sessions and redirect cookies.
+- Added standalone production E2E coverage to verify the same SPA loader protocol after production bundling.
+- Expanded package artifact smoke checks to require the client router, dev navigation target runtime, navigation response transport and standalone loader navigation runtime.
+- Added dedicated server data loader documentation and updated the main README/application boundary guidance.
+
 ## 0.1.8 - JWT cookie sessions and auth preset
 
 ### Authentication

package/README.md

@@ -2,7 +2,7 @@
 
 BCP Framework is a React full-stack framework with file-based routing, SSR, client navigation, API routes, middleware, metadata, client islands, cache/revalidation, security defaults and standalone production builds.
 
-> Current development version: `0.1.8`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
+> Current release target: `0.1.10`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
 
 ## Quick start
 
@@ -33,9 +33,13 @@ app/
 ├─ loading.tsx
 ├─ error.tsx
 ├─ not-found.tsx
-├─ users/
-│  └─ [id]/
-│     └─ page.tsx
+├─ dashboard/
+│  ├─ guard.ts
+│  ├─ page.tsx
+│  └─ users/
+│     └─ [id]/
+│        ├─ loader.ts
+│        └─ page.tsx
 └─ api/
    └─ hello/
       └─ route.ts
@@ -73,7 +77,7 @@ Server-only modules can declare:
 import "bcp/server-only";
 ```
 
-Database helpers generated by `create-bcp-app` include the server-only marker automatically. A server-only helper must not be imported from a page/client graph; put database work behind an API route instead.
+Database helpers generated by `create-bcp-app` include the server-only marker automatically. A server-only helper must not be imported from a hydrated page/client graph. Use an API route or a server-only route primitive such as `loader.ts` or `guard.ts`.
 
 See [Application Modules](docs/application-modules.md) for the complete boundary model and examples.
 
@@ -88,11 +92,42 @@ bcp dev
 bcp routes
 bcp build
 bcp start
+bcp update
 bcp version
 ```
 
 CLI server overrides are available with `--port` and `--hostname`.
 
+## Updating an existing project
+
+Once a project is on a BCP version that contains the updater, update to the current npm `latest` release with:
+
+```bash
+bcp update
+```
+
+Preview an update without changing files:
+
+```bash
+bcp update --check
+bcp update --dry-run
+```
+
+Or select a published version/dist-tag explicitly:
+
+```bash
+bcp update 0.1.10
+bcp update next
+```
+
+Versions published before the updater do not recognize `bcp update`. Bootstrap the newest CLI once from those projects:
+
+```bash
+npx @chidchanun/bcp@latest update
+```
+
+The updater changes the framework dependency and package-manager lockfile, detects npm/pnpm/Yarn/Bun from the project lockfile, and restores package metadata if installation fails. It does not overwrite application source files, database schemas or authentication code. See [Updating BCP Framework](docs/updating.md) for the complete behavior and migration notes.
+
 ## Routing
 
 BCP supports:
@@ -123,7 +158,7 @@ Supported methods include GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS. HEAD
 
 ## Server request APIs
 
-BCP 0.1.7 adds request-scoped server helpers through `bcp/server`. In the current 0.1.x client pipeline these helpers are intended for API routes and are rejected from page/client module graphs.
+BCP 0.1.7 adds request-scoped server helpers through `bcp/server`. These helpers are server-only and are available from API handlers, server data loaders and route guards.
 
 ```ts
 import {
@@ -196,6 +231,174 @@ export async function POST() {
 
 `redirect()` defaults to status `307`; supported statuses are `301`, `302`, `303`, `307` and `308`. Use `cookieStore.delete("session")` to expire a cookie. See [Server Request APIs](docs/server-request-apis.md) for proxy trust, URL handling, response helpers, request isolation, cookie options and boundary details.
 
+## Server data loaders
+
+BCP 0.1.9 adds a server-only `loader.ts` convention next to `page.tsx`. The loader runs before SSR, receives route `params` plus `searchParams`, and can use `bcp/server` APIs, sessions and server-only database modules.
+
+```text
+app/users/[id]/
+├─ loader.ts
+└─ page.tsx
+```
+
+```ts
+// app/users/[id]/loader.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,
+        query:
+            searchParams.get("q"),
+        session,
+    };
+}
+```
+
+Pages consume the serializable result with `useLoaderData<T>()`:
+
+```tsx
+"use client";
+
+import {
+    useLoaderData,
+} from "bcp";
+
+export default function UserPage() {
+    const data =
+        useLoaderData<{
+            id: string;
+            query: string | null;
+        }>();
+
+    return (
+        <main>
+            User {data.id}
+        </main>
+    );
+}
+```
+
+Loader data is validated as JSON-safe before SSR and is serialized into framework data so hydration reads the same value without importing `loader.ts` into the browser graph. A loader may also return a Web `Response`; response cookies are preserved on redirects.
+
+Loader-backed pages now use the same SPA navigation model as normal BCP routes. `<Link>`, `navigate()`, `router.push()`, `router.replace()`, history navigation and `router.refresh()` request `/_bcp/navigation`; the server executes the target loader inside a fresh target-page request context and returns current loader data with the route payload. Same-origin loader redirects continue through the router while preserving `Set-Cookie` headers. Superseded navigations are aborted and sequence-checked so stale responses cannot update the active route. Loader pages remain excluded from the production response-cache manifest by default because their output may depend on session, cookie, request identity or user-specific database state.
+
+See [Server Data Loaders](docs/server-data-loaders.md) for serialization rules, authentication patterns, redirect behavior, SPA navigation, cache safety and request-context semantics.
+
+## Protected routes and auth guards
+
+The `0.1.10` release target adds scoped `guard.ts` / `guard.tsx` files for page authorization. A guard protects the pages in its directory and descendant route directories, runs before the page loader, and can use the same request/session APIs as a loader.
+
+```text
+app/dashboard/
+├─ guard.ts
+├─ page.tsx
+└─ users/
+   └─ [id]/
+      ├─ loader.ts
+      └─ page.tsx
+```
+
+```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,
+    };
+}
+```
+
+Descendant loaders receive the merged result as `guardData`, so they do not need to repeat `getSession()`:
+
+```ts
+export async function loader({
+    params,
+    guardData,
+}) {
+    return {
+        id:
+            params.id,
+        user:
+            guardData.session,
+        role:
+            guardData.role,
+    };
+}
+```
+
+A page can consume the same authorization data with `useGuardData<T>()`:
+
+```tsx
+"use client";
+
+import {
+    useGuardData,
+} from "bcp";
+
+export default function DashboardPage() {
+    const guard =
+        useGuardData<{
+            session: {
+                email: string;
+            };
+            role: string;
+        }>();
+
+    return (
+        <main>
+            {guard.session.email}
+        </main>
+    );
+}
+```
+
+Nested guards execute from root to child and receive ancestor output as `parentData`. Guard redirects and response cookies work for both direct document requests and SPA navigation. Guarded pages are excluded from the automatic production response cache, and standalone production strips user-supplied internal guard transport headers before evaluating authorization.
+
+See [Protected Route Guards](docs/route-guards.md) for nested role policies, serialization rules, middleware ordering, cookie behavior and production hardening.
+
 ## JWT cookie sessions
 
 BCP 0.1.8 adds HS256 JWT cookie sessions directly to `bcp/server`. Configure a server-only secret of at least 32 bytes:
@@ -335,7 +538,7 @@ import {
 } from "bcp/cache";
 ```
 
-The current cache implementation is process-local and intentionally does not provide distributed invalidation across multiple Node.js instances.
+The current cache implementation is process-local and intentionally does not provide distributed invalidation across multiple Node.js instances. Loader-backed and route-guarded pages are excluded from the automatic production response-cache manifest because their output may depend on request/session identity. Cache server data explicitly only when the application has a safe user-aware cache key and invalidation strategy.
 
 ## Middleware
 
@@ -360,6 +563,8 @@ export function middleware(
 }
 ```
 
+Use middleware for request-wide interception and `guard.ts` for page-subtree authorization that needs to feed identity/role data into loaders and pages. In standalone production, project middleware runs before route guards.
+
 ## Configuration
 
 ```ts
@@ -411,10 +616,13 @@ The standalone output is generated under:
 └─ server/
    ├─ server.mjs
    ├─ middleware.mjs
+   ├─ guards.mjs
    ├─ cache-manifest.json
    └─ config.json
 ```
 
+`guards.mjs` is generated only when the application contains protected route guards.
+
 ## Package preparation
 
 The development monorepo stays private. Publishable artifacts are produced separately:
@@ -445,7 +653,10 @@ No real npm publish command is run automatically by the repository.
 - [Getting Started](docs/getting-started.md)
 - [Application Modules](docs/application-modules.md)
 - [Server Request APIs](docs/server-request-apis.md)
+- [Server Data Loaders](docs/server-data-loaders.md)
+- [Protected Route Guards](docs/route-guards.md)
 - [JWT Cookie Sessions](docs/session-auth.md)
+- [Updating BCP Framework](docs/updating.md)
 - [Routing](docs/routing.md)
 - [Configuration](docs/configuration.md)
 - [Caching](docs/caching.md)

package/docs/application-modules.md

@@ -8,7 +8,7 @@ import {
 } from "@/lib/database";
 ```
 
-The generated `tsconfig.json` maps `@/*` to the project root. BCP also installs a Node.js resolver during development so the same alias works in SSR and API route modules. Production builds resolve the alias through the application bundler.
+The generated `tsconfig.json` maps `@/*` to the project root. BCP also installs a Node.js resolver during development so the same alias works in SSR, loader and API route modules. Production builds resolve the alias through the application bundler.
 
 ## Client modules
 
@@ -79,7 +79,7 @@ import {
 } from "@/lib/database";
 ```
 
-Put the database operation behind an API route instead:
+For browser-driven data operations, put the database operation behind an API route:
 
 ```ts
 // app/api/users/route.ts
@@ -111,6 +111,66 @@ const result =
     await response.json();
 ```
 
+## Server data loaders
+
+BCP 0.1.9 adds a server-only page data path. A `loader.ts` next to `page.tsx` is not part of the hydrated page graph and may import server-only database helpers directly.
+
+```text
+app/users/
+├─ loader.ts
+└─ page.tsx
+```
+
+```ts
+// app/users/loader.ts
+import {
+    db,
+} from "@/lib/database";
+
+export async function loader() {
+    const [rows] =
+        await db.query(
+            "SELECT id, name FROM users"
+        );
+
+    return {
+        users: rows,
+    };
+}
+```
+
+The page consumes only the serializable result:
+
+```tsx
+"use client";
+
+import {
+    useLoaderData,
+} from "bcp";
+
+export default function UsersPage() {
+    const data =
+        useLoaderData<{
+            users: Array<{
+                id: number;
+                name: string;
+            }>;
+        }>();
+
+    return (
+        <pre>
+            {JSON.stringify(
+                data.users,
+                null,
+                2
+            )}
+        </pre>
+    );
+}
+```
+
+The loader itself stays server-only; only its validated JSON-safe result is serialized for hydration. See [Server Data Loaders](server-data-loaders.md) for request context, authentication, redirects and cache behavior.
+
 ## Current boundary model
 
-BCP 0.1.x is not a React Server Components implementation. Pages and layouts can participate in browser hydration, so server-only dependencies must remain behind API routes or other server execution paths. The boundary checks are designed to make that rule explicit and prevent accidental database or secret-bearing code from entering client bundles.
+BCP 0.1.x is not a React Server Components implementation. Pages and layouts can participate in browser hydration, so server-only dependencies must remain behind explicit server execution paths: API routes, route-level server data loaders, middleware, or other framework server runtimes. The boundary checks are designed to prevent accidental database or secret-bearing code from entering client bundles.

package/docs/releasing.md

@@ -18,7 +18,7 @@ Application source continues importing from `bcp`. `create-bcp-app` stores the s
 Use the version helper instead of editing package metadata manually:
 
 ```bash
-npm run version:set -- 0.1.1
+npm run version:set -- 0.1.10
 ```
 
 It synchronizes the release version across:
@@ -187,24 +187,29 @@ and the executable:
 bcp
 ```
 
-A generated application's `package.json` should therefore contain a dependency equivalent to:
+A newly generated application's `package.json` pins the selected framework release exactly so a later plain package-manager install cannot silently move BCP to a different release:
 
 ```json
 {
+  "scripts": {
+    "update": "bcp update"
+  },
   "dependencies": {
-    "bcp": "npm:@chidchanun/bcp@^0.1.1"
+    "bcp": "npm:@chidchanun/bcp@0.1.10"
   }
 }
 ```
 
+The explicit updater is responsible for resolving and installing later framework releases.
+
 ## 8. Create the release tag
 
 Only after `npm run rc:check` passes and `CHANGELOG.md` is ready:
 
 ```bash
 git status
-git tag -a v0.1.1 -m "BCP Framework v0.1.1"
-git push origin v0.1.1
+git tag -a v0.1.10 -m "BCP Framework v0.1.10"
+git push origin v0.1.10
 ```
 
 Use the actual version from `package.json` in the tag.
@@ -231,19 +236,13 @@ The command refuses to publish unless all of these conditions are true:
 - staged package names and versions match the selected release
 - the target version has not already been accepted by npm
 
-For `0.x` releases the default npm dist-tag is:
-
-```text
-next
-```
-
-For `1.x` and later it defaults to:
+Stable BCP releases use this npm dist-tag by default, including stable `0.x` releases:
 
 ```text
 latest
 ```
 
-Override the tag explicitly when needed:
+Use `BCP_DIST_TAG` only when intentionally publishing a separate channel such as `next` or `beta`:
 
 ```bash
 BCP_DIST_TAG=beta npm run release:publish:yes
@@ -258,6 +257,8 @@ npm run release:publish:yes
 
 The framework publishes first. After `npm publish` succeeds, the release script accepts either normal version visibility or the selected dist-tag pointing at the new version. This prevents npm registry/security-processing delays from being misclassified as a failed publish.
 
+Using `latest` for stable releases is also part of the updater contract: `bcp update` resolves `@chidchanun/bcp@latest` by default.
+
 ## 10. Recover from a partial publish
 
 If the framework package was accepted by npm but publishing `create-bcp-app` failed, fix the external issue without changing that release commit or tag, then use:
@@ -270,18 +271,32 @@ Resume mode intentionally does not run `release:version-check` or `npm publish -
 
 Do not use resume mode to overwrite or replace an existing npm version; npm versions are immutable.
 
-## 11. Install the preview release
+## 11. Install or update the stable release
+
+The recommended new-project path is:
+
+```bash
+npx create-bcp-app@latest my-app
+```
+
+A generated application keeps the documented `bcp` import name through an npm alias and pins the selected framework version exactly.
+
+For an existing project already on an updater-capable release:
+
+```bash
+npm run update
+```
 
-The recommended path is the generator:
+For a project on BCP 0.1.9 or older, bootstrap the updater once with:
 
 ```bash
-npx create-bcp-app@next my-app
+npx @chidchanun/bcp@latest update
 ```
 
-For a `0.x` release published with the default `next` dist-tag, a manual install that preserves the `bcp` import name is:
+A manual install that preserves the `bcp` import name is:
 
 ```bash
-npm install bcp@npm:@chidchanun/bcp@next react react-dom
+npm install bcp@npm:@chidchanun/bcp@latest react react-dom
 ```
 
 Application code then continues using:
@@ -292,7 +307,7 @@ import {
 } from "bcp";
 ```
 
-The scoped package can also be installed directly as `@chidchanun/bcp@next`, but applications using the framework's documented `bcp` import path should prefer the alias form above.
+The scoped package can also be installed directly as `@chidchanun/bcp@latest`, but applications using the framework's documented `bcp` import path should prefer the alias form above.
 
 ## 12. Trusted publishing