@chidchanun/bcp 0.1.9 → 0.1.11

package/docs/form-actions.md

@@ -0,0 +1,314 @@
+# Form Actions and Server Mutations
+
+BCP form actions provide a route-scoped server mutation primitive for application forms without requiring an API route for every create, update or delete operation.
+
+This feature is intentionally separate from future BCP Server Actions. In this release, client pages do **not** import a server function directly. A page submits a named action such as `"saveUser"`, and BCP resolves that name from the sibling `actions.ts` / `actions.tsx` file on the server.
+
+## Route convention
+
+```text
+app/users/[id]/
+├─ guard.ts        # optional
+├─ loader.ts       # optional read path
+├─ actions.ts      # server-only mutation path
+└─ page.tsx
+```
+
+Only one of `actions.ts` or `actions.tsx` may exist next to a page.
+
+## Defining an action
+
+```ts
+// app/users/[id]/actions.ts
+import "bcp/server-only";
+
+import {
+    cookies,
+    redirect,
+    type PageActionContext,
+} from "bcp/server";
+
+import {
+    revalidatePath,
+    revalidateTag,
+} from "bcp/cache";
+
+export async function saveUser(
+    formData: FormData,
+    context: PageActionContext
+) {
+    const name =
+        String(
+            formData.get("name") ?? ""
+        ).trim();
+
+    // Perform the database mutation here.
+
+    const cookieStore =
+        await cookies();
+
+    cookieStore.set(
+        "last-user",
+        context.params.id,
+        {
+            httpOnly: true,
+            sameSite: "lax",
+            path: "/",
+        }
+    );
+
+    revalidatePath("/users");
+    revalidateTag("users");
+
+    return {
+        ok: true,
+        id: context.params.id,
+        name,
+    };
+}
+
+export async function removeUser(
+    _formData: FormData,
+    context: PageActionContext
+) {
+    // Delete from the database.
+
+    revalidatePath("/users");
+
+    return redirect(
+        "/users",
+        303
+    );
+}
+```
+
+An action receives:
+
+- `formData` — the submitted browser `FormData`.
+- `context.params` — matched dynamic route parameters.
+- `context.searchParams` — a fresh `URLSearchParams` for the target page URL.
+- `context.guardData` — merged data from route guards that ran before the action.
+- `context.method` — the semantic mutation method: `POST`, `PUT`, `PATCH`, or `DELETE`.
+
+The normal `bcp/server` request context is active while the action runs, so `cookies()`, `headers()`, `requestUrl()`, `requestMethod()`, `requestId()`, `getSession()` and other server helpers work directly. `requestMethod()` reflects the semantic action method rather than the internal POST transport.
+
+## Rendering a form
+
+```tsx
+"use client";
+
+import {
+    Form,
+    useActionData,
+    useActionError,
+    useFormStatus,
+} from "bcp";
+
+interface SaveResult {
+    ok: boolean;
+    id: string;
+    name: string;
+}
+
+export default function UserEditor() {
+    return (
+        <Form
+            action="saveUser"
+            method="patch"
+        >
+            <input
+                name="name"
+                required
+            />
+
+            <SubmitButton />
+            <Result />
+        </Form>
+    );
+}
+
+function SubmitButton() {
+    const status =
+        useFormStatus();
+
+    return (
+        <button
+            type="submit"
+            disabled={status.pending}
+        >
+            {status.pending
+                ? "Saving..."
+                : "Save"}
+        </button>
+    );
+}
+
+function Result() {
+    const data =
+        useActionData<SaveResult>();
+    const error =
+        useActionError();
+
+    if (error) {
+        return (
+            <p role="alert">
+                {error.message}
+            </p>
+        );
+    }
+
+    if (!data) {
+        return null;
+    }
+
+    return (
+        <p>
+            Saved {data.name}
+        </p>
+    );
+}
+```
+
+## Supported mutation methods
+
+`<Form>` supports:
+
+```tsx
+<Form action="createUser" method="post" />
+<Form action="replaceUser" method="put" />
+<Form action="updateUser" method="patch" />
+<Form action="deleteUser" method="delete" />
+```
+
+Browsers only support GET and POST as native HTML form methods. BCP therefore uses POST as the wire transport for progressive enhancement and preserves the intended method separately. The action context and `requestMethod()` still report `PUT`, `PATCH`, or `DELETE` as requested.
+
+GET is deliberately not an action method. Reads belong in page loaders or API GET handlers.
+
+## Action return values
+
+A mutation may return either:
+
+1. JSON-safe action data.
+2. `undefined`, which BCP normalizes to `null`.
+3. A Web `Response`, commonly `redirect()`.
+
+Serializable action data follows the same safety model as loader data: primitives, arrays and plain objects are allowed. Functions, symbols, BigInt, non-finite numbers, Date/Map/Set/class instances and circular references are rejected before transport.
+
+For validation-style UI in this release, return a serializable object such as:
+
+```ts
+return {
+    ok: false,
+    fieldErrors: {
+        email: "Email is required",
+    },
+};
+```
+
+Typed validation helpers and CSRF-specific APIs are planned as a separate security/validation milestone.
+
+## Pending, data, and transport errors
+
+Inside a `<Form>` subtree:
+
+- `useFormStatus()` exposes `pending`, `action`, `method`, and the current transport/server error.
+- `useActionData<T>()` exposes the most recent serializable action result.
+- `useActionError()` exposes the most recent thrown transport/runtime error.
+
+Submitting the form again clears the previous action data before the new request begins.
+
+## Redirects
+
+Actions can return a normal BCP redirect:
+
+```ts
+return redirect(
+    "/users",
+    303
+);
+```
+
+With JavaScript enabled, BCP converts the redirect into an action transport payload and continues with client navigation. Without JavaScript, the browser receives the normal HTTP redirect.
+
+Cookies set before the redirect are preserved in both paths.
+
+## Revalidation and refreshing loaders
+
+`revalidatePath()` and `revalidateTag()` can be called directly inside an action to invalidate BCP data cache entries:
+
+```ts
+revalidatePath("/users");
+revalidateTag("users");
+```
+
+If the current page should immediately rerun its loader after a successful data-returning action, enable the form's `refresh` option:
+
+```tsx
+<Form
+    action="saveUser"
+    method="patch"
+    refresh
+>
+    ...
+</Form>
+```
+
+`refresh` uses the existing BCP router refresh path after the action result is received. Redirecting actions do not need `refresh`.
+
+## Progressive enhancement
+
+The rendered HTML form posts to BCP's internal action endpoint using a normal browser POST. The target page is recovered from the same-origin referrer when JavaScript is unavailable.
+
+When an action returns serializable data and no explicit `Response`, the no-JavaScript path uses POST/Redirect/GET with HTTP `303` back to the original target page. This prevents duplicate browser resubmission on refresh.
+
+With JavaScript enabled, `<Form>` intercepts the submit and sends the same `FormData` through the action transport without reloading the document.
+
+## Middleware, guards, and request order
+
+For a mutation, the effective server order is:
+
+```text
+Security gateway
+    ↓
+Project middleware
+    ↓
+Resolve target page
+    ↓
+Route guards (root → child)
+    ↓
+Named action
+    ↓
+Response cookies / redirect / data
+```
+
+A guard redirect prevents the action from running. Guard data is passed into `context.guardData`, so an authorization lookup does not need to be repeated in the action.
+
+## Why action names are strings
+
+This release intentionally uses:
+
+```tsx
+<Form action="saveUser">
+```
+
+and not:
+
+```tsx
+<Form action={saveUser}>
+```
+
+Passing a server function through a client bundle requires a compiler-generated server reference, serialization protocol and action identifier system. That belongs to the later BCP Server Actions milestone. Keeping named route actions separate now prevents server/database modules from being pulled into hydrated client graphs.
+
+## When to use an API route instead
+
+Use a form action when the mutation belongs to a BCP page UI.
+
+Keep an API route when the caller is an external client such as:
+
+- a mobile application,
+- another backend service,
+- a webhook provider,
+- Postman/API consumers,
+- a public or versioned HTTP API.
+
+A project can use both patterns: loaders for page reads, guards for authorization, form actions for page-owned mutations, and API routes for external HTTP contracts.

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.