@chidchanun/bcp 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -2,6 +2,88 @@
 
 All notable framework changes are tracked here before release.
 
+## 0.1.11 - Form actions and server mutations
+
+### Route mutations
+
+- Added route-level `actions.ts` / `actions.tsx` files next to `page.tsx` for server-only create, update and delete operations without requiring an API route for every page-owned mutation.
+- Actions are named exports and receive browser `FormData` plus route `params`, target `searchParams`, merged `guardData` and the semantic mutation `method`.
+- Supported action methods are `POST`, `PUT`, `PATCH` and `DELETE`; GET remains a loader/API read concern.
+- Added `PageAction`, `PageActionContext` and `PageActionMethod` types through the server-only `bcp/server` entrypoint.
+- Action modules may use normal server-only application/database imports plus request/session APIs such as `cookies()`, `getSession()`, `requestUrl()` and `requestMethod()`.
+- `requestMethod()` reflects the semantic action method even though progressive HTML forms use POST as the browser transport.
+- Actions may return JSON-safe data, `undefined` (normalized to `null`) or a Web `Response` such as `redirect()`.
+- Action data uses JSON-safe validation and rejects unsupported/circular values before browser transport.
+
+### Form client API and progressive enhancement
+
+- Added public `<Form action="name">` with `post`, `put`, `patch` and `delete` semantic methods.
+- Added `useFormStatus()` for pending/action/method/error state, `useActionData<T>()` for the latest serializable mutation result and `useActionError()` for transport/runtime failures.
+- Enhanced submissions send the original `FormData` through the internal `/_bcp/action` transport without a document reload.
+- Named actions use strings instead of importing server functions into the client graph, preserving server-only boundaries until the later compiler-backed Server Actions milestone.
+- Same-origin redirects from enhanced actions continue through BCP client navigation while response cookies remain intact.
+- Forms without JavaScript use normal HTML POST and POST/Redirect/GET `303` behavior for data-returning actions, preventing duplicate resubmission on browser refresh.
+- Added optional `<Form refresh>` support to rerun the current BCP navigation/loader after a successful data-returning mutation.
+
+### Authorization, caching and production
+
+- Route guards execute before matching actions and can stop a mutation with a redirect/Response; merged authorization data is passed to the action through `context.guardData`.
+- Project middleware and framework security remain outside the action gateway, so mutation requests keep the existing request interception and body-limit policy.
+- Cookies created by actions or guards are preserved for data and redirect responses in both enhanced and progressive paths.
+- `revalidatePath()` and `revalidateTag()` can be called directly inside actions using the shared process-local BCP cache runtime.
+- Pages with sibling form actions are excluded from the automatic production response-cache manifest to avoid stale POST/Redirect/GET pages after mutations.
+- Standalone builds generate `server/actions.mjs` only when action routes exist and execute bundled action modules entirely on the server.
+- Added development and standalone action gateways without exposing action/database modules to browser bundles.
+
+### Reliability and documentation
+
+- Added `/action-demo/[id]` plus guarded mutation fixtures for FormData, semantic methods, cookies, redirects, cache revalidation hooks, progressive enhancement and guard-data handoff.
+- Added unit coverage for action naming, method normalization, route context, Response returns and serialization rejection.
+- Added development integration and standalone E2E coverage for enhanced mutations, no-JavaScript PRG behavior, response cookies and guards-before-actions ordering.
+- Added publish-artifact smoke checks for the public Form API, server mutation runtime, dev gateway, standalone action gateway and production action bundle.
+- Added dedicated Form Actions and Server Mutations documentation.
+
+## 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 `guardData`.
+- 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
@@ -24,7 +106,7 @@ All notable framework changes are tracked here before release.
 - 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.
+- Client navigation explicitly sends same-origin credentials, aborts superseded requests and uses a monotonically increasing navigation sequence so stale responses cannot update the active route 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.

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.11`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
 
 ## Quick start
 
@@ -33,10 +33,14 @@ app/
 ├─ loading.tsx
 ├─ error.tsx
 ├─ not-found.tsx
-├─ users/
-│  └─ [id]/
-│     ├─ loader.ts
-│     └─ page.tsx
+├─ dashboard/
+│  ├─ guard.ts
+│  ├─ page.tsx
+│  └─ users/
+│     └─ [id]/
+│        ├─ loader.ts
+│        ├─ actions.ts
+│        └─ page.tsx
 └─ api/
    └─ hello/
       └─ route.ts
@@ -74,7 +78,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`, `guard.ts` or `actions.ts`.
 
 See [Application Modules](docs/application-modules.md) for the complete boundary model and examples.
 
@@ -89,11 +93,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.11
+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 +159,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, route guards and form actions.
 
 ```ts
 import {
@@ -273,6 +308,217 @@ 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
+
+BCP 0.1.10 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 merged ancestor output as `guardData`. 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.
+
+## Form actions and server mutations
+
+BCP 0.1.11 adds route-owned server mutations with `actions.ts` / `actions.tsx`. Actions stay on the server and let page forms perform create, update and delete operations without creating a dedicated API route for every mutation.
+
+```text
+app/users/[id]/
+├─ guard.ts
+├─ loader.ts
+├─ actions.ts
+└─ page.tsx
+```
+
+```ts
+// app/users/[id]/actions.ts
+import "bcp/server-only";
+
+import {
+    redirect,
+    type PageActionContext,
+} from "bcp/server";
+
+import {
+    revalidatePath,
+} from "bcp/cache";
+
+export async function saveUser(
+    formData: FormData,
+    context: PageActionContext
+) {
+    const name =
+        String(
+            formData.get("name") ?? ""
+        ).trim();
+
+    // await db.execute(...)
+
+    revalidatePath("/users");
+
+    if (!name) {
+        return {
+            ok: false,
+            message: "Name is required",
+        };
+    }
+
+    if (
+        context.searchParams.get("done") === "1"
+    ) {
+        return redirect(
+            "/users",
+            303
+        );
+    }
+
+    return {
+        ok: true,
+        id: context.params.id,
+        name,
+        method: context.method,
+    };
+}
+```
+
+Client forms reference the named server action without importing it into the browser graph:
+
+```tsx
+"use client";
+
+import {
+    Form,
+    useActionData,
+    useActionError,
+    useFormStatus,
+} from "bcp";
+
+function SubmitButton() {
+    const status =
+        useFormStatus();
+
+    return (
+        <button
+            type="submit"
+            disabled={status.pending}
+        >
+            {status.pending
+                ? "Saving..."
+                : "Save"}
+        </button>
+    );
+}
+
+export default function UserForm() {
+    const result =
+        useActionData<{
+            ok: boolean;
+            message?: string;
+        }>();
+    const error =
+        useActionError();
+
+    return (
+        <Form
+            action="saveUser"
+            method="patch"
+            refresh
+        >
+            <input name="name" />
+            <SubmitButton />
+            {result?.message}
+            {error?.message}
+        </Form>
+    );
+}
+```
+
+Supported semantic methods are POST, PUT, PATCH and DELETE. Guards execute before actions and pass merged authorization state through `context.guardData`. Actions can use cookies, JWT sessions, `requestMethod()`, redirects and cache revalidation. Enhanced forms submit through the BCP SPA transport; forms without JavaScript fall back to standard HTML POST with POST/Redirect/GET semantics. Action-backed pages are excluded from automatic production response caching.
+
+See [Form Actions and Server Mutations](docs/form-actions.md) for action return values, pending/error state, progressive enhancement, guards, redirects, cookies, cache invalidation and standalone behavior.
+
 ## 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 +658,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, route-guarded and action-backed pages are excluded from the automatic production response-cache manifest when their output or mutation flow may depend on request/session state. Cache server data explicitly only when the application has a safe user-aware cache key and invalidation strategy.
 
 ## Middleware
 
@@ -437,6 +683,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, actions and pages. In standalone production, project middleware runs before route guards and form actions.
+
 ## Configuration
 
 ```ts
@@ -488,10 +736,14 @@ The standalone output is generated under:
 └─ server/
    ├─ server.mjs
    ├─ middleware.mjs
+   ├─ guards.mjs
+   ├─ actions.mjs
    ├─ cache-manifest.json
    └─ config.json
 ```
 
+`guards.mjs` is generated only when the application contains protected route guards. `actions.mjs` is generated only when the application contains route form actions.
+
 ## Package preparation
 
 The development monorepo stays private. Publishable artifacts are produced separately:
@@ -523,7 +775,10 @@ 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)
+- [Form Actions and Server Mutations](docs/form-actions.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)