@chidchanun/bcp 0.1.9 → 0.1.10

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 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

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.9`. 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,10 +33,13 @@ app/
 ├─ loading.tsx
 ├─ error.tsx
 ├─ not-found.tsx
-├─ users/
-│  └─ [id]/
-│     ├─ loader.ts
-│     └─ page.tsx
+├─ dashboard/
+│  ├─ guard.ts
+│  ├─ page.tsx
+│  └─ users/
+│     └─ [id]/
+│        ├─ loader.ts
+│        └─ page.tsx
 └─ api/
    └─ hello/
       └─ route.ts
@@ -74,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 hydrated page/client graph. Use an API route or, for page data in BCP 0.1.9+, a route-level `loader.ts` that runs only on the server.
+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.
 
@@ -89,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:
@@ -124,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`. These helpers are server-only and are available from API handlers and server data loaders.
+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 {
@@ -273,6 +307,98 @@ Loader-backed pages now use the same SPA navigation model as normal BCP routes.
 
 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:
@@ -412,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. Loader-backed pages are excluded from the automatic production response-cache manifest in 0.1.9; cache loader data explicitly only when the application has a safe user-aware cache key and invalidation strategy.
+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
 
@@ -437,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
@@ -488,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:
@@ -523,7 +654,9 @@ No real npm publish command is run automatically by the repository.
 - [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/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
 

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.