@chidchanun/bcp 0.1.16 → 0.1.18

package/docs/README.md

@@ -0,0 +1,325 @@
+# BCP Framework Documentation Source
+
+This directory is the documentation source of truth for the BCP Framework documentation website.
+
+The recommended documentation website project name is `bcp-docs`.
+
+> Documentation target: BCP Framework `0.1.18`
+
+## Purpose
+
+The `bcp-docs` website should turn the Markdown files in this directory into a structured developer documentation experience without duplicating framework behavior in a separate source of truth.
+
+When framework behavior changes:
+
+1. update the framework source and tests,
+2. update the relevant file in `docs/`,
+3. update the release note in `docs/releases/`,
+4. then publish or synchronize the content to `bcp-docs`.
+
+The website should not invent API behavior that is not documented or tested in the framework repository.
+
+## Recommended website navigation
+
+### Getting Started
+
+| Website route | Source file | Description |
+| --- | --- | --- |
+| `/docs/getting-started` | `getting-started.md` | Create and run a BCP application |
+| `/docs/configuration` | `configuration.md` | Framework configuration |
+| `/docs/application-modules` | `application-modules.md` | Client/server module boundaries |
+| `/docs/deployment` | `deployment.md` | Production and deployment guidance |
+| `/docs/updating` | `updating.md` | Upgrade an existing BCP project |
+
+### Routing and Data
+
+| Website route | Source file | Description |
+| --- | --- | --- |
+| `/docs/routing` | `routing.md` | File-based routing |
+| `/docs/server-data-loaders` | `server-data-loaders.md` | Server-side page data |
+| `/docs/route-guards` | `route-guards.md` | Scoped page authorization |
+| `/docs/form-actions` | `form-actions.md` | Server mutations and forms |
+| `/docs/server-request-apis` | `server-request-apis.md` | Request, cookie, redirect and response APIs |
+
+### Authentication
+
+| Website route | Source file | Description |
+| --- | --- | --- |
+| `/docs/authentication` | `authentication.md` | Authentication Core and `bcp/auth` |
+| `/docs/auth-route-guards` | `auth-route-guards.md` | `requireAuth`, `requireRole` and guard integration |
+| `/docs/session-auth` | `session-auth.md` | Low-level JWT cookie sessions |
+
+### Database
+
+| Website route | Source file | Description |
+| --- | --- | --- |
+| `/docs/database` | `database.md` | `bcp/database`, MySQL and transactions |
+| `/docs/database-migrations` | `database-migrations.md` | Migration CLI and migration files |
+
+### Runtime and Infrastructure
+
+| Website route | Source file | Description |
+| --- | --- | --- |
+| `/docs/middleware` | `middleware.md` | Middleware System v2 and v1 compatibility |
+| `/docs/caching` | `caching.md` | Cache and revalidation |
+| `/docs/security` | `security.md` | Framework security defaults |
+| `/docs/development-logging` | `development-logging.md` | Development request logging |
+
+### Releases
+
+Use the files under `docs/releases/` for release pages.
+
+Recommended route format:
+
+```text
+/releases/0.1.16
+/releases/0.1.17
+/releases/0.1.18
+```
+
+The newest release should also be available from `/releases`.
+
+## Homepage content for bcp-docs
+
+The documentation homepage should describe BCP as a React full-stack framework and highlight the currently implemented capabilities.
+
+Recommended feature groups:
+
+### Application
+
+- File-based routing
+- React SSR
+- SPA navigation
+- Persistent layouts
+- Loading and error UI
+- API routes
+- Client islands / partial hydration
+
+### Server data and mutations
+
+- Server data loaders
+- Route guards
+- Form actions
+- Request-scoped server APIs
+- Cookies and redirects
+
+### Database
+
+- `bcp/database`
+- Lazy MySQL connection pool
+- Queries and prepared execution
+- Transactions
+- Database migrations
+- Migration status and rollback
+
+### Authentication
+
+- `bcp/auth`
+- JWT cookie sessions
+- Typed users and session data
+- Session rotation
+- `requireAuth()`
+- `requireRole()`
+- Auth-aware route guards
+
+### Middleware
+
+- Middleware System v2
+- Middleware chains
+- Real `await next()` downstream execution
+- Before/after response interception
+- Shared request context state
+- Matchers
+- Rewrite and redirect
+- Backward-compatible Middleware v1 handlers
+
+### Production and DX
+
+- `create-bcp-app`
+- Interactive project setup
+- Tailwind preset
+- Database/auth presets
+- `bcp update`
+- Standalone production builds
+- Critical CSS
+- Cache/revalidation
+- Security defaults
+- Unit/integration/E2E/package smoke testing in the framework repository
+
+## Suggested homepage hero
+
+Suggested content, not a required exact copy:
+
+```text
+BCP Framework
+A React full-stack framework for building server-rendered applications with routing,
+data loading, server mutations, authentication, databases, middleware and production tooling.
+```
+
+Primary actions:
+
+```text
+Get Started
+Read the Docs
+View on GitHub
+```
+
+The website may display the current release version from project metadata instead of hard-coding it in multiple UI files.
+
+## Suggested documentation sidebar
+
+```text
+Getting Started
+  Introduction
+  Installation
+  Project Structure
+  Configuration
+  Updating
+
+Core
+  Routing
+  Application Modules
+  Server Request APIs
+  Server Data Loaders
+  Route Guards
+  Form Actions
+
+Authentication
+  Authentication Core
+  Auth Route Guards
+  JWT Sessions
+
+Database
+  Database
+  Migrations
+
+Runtime
+  Middleware
+  Caching
+  Security
+
+Production
+  Deployment
+  Development Logging
+
+Releases
+  0.1.18
+  0.1.17
+  0.1.16
+```
+
+## Suggested documentation page layout
+
+Each documentation page should support:
+
+- title
+- short summary
+- previous/next page navigation
+- table of contents generated from headings
+- syntax-highlighted code blocks
+- copy-code button
+- deep links to headings
+- responsive sidebar
+- mobile navigation
+- light/dark appearance
+- framework version label
+- link to the corresponding source Markdown file in GitHub
+
+Optional later additions:
+
+- documentation search
+- version selector
+- API symbol index
+- interactive examples
+- edit-on-GitHub links
+
+## Code examples
+
+Examples should use the public package entrypoints that application developers actually install.
+
+Preferred:
+
+```ts
+import {
+    auth,
+    requireAuth,
+} from "bcp/auth";
+
+import {
+    db,
+} from "bcp/database";
+
+import {
+    type MiddlewarePipelineHandler,
+} from "bcp/middleware";
+```
+
+Avoid documenting internal monorepo imports such as:
+
+```text
+packages/server/src/...
+packages/client/src/...
+```
+
+unless a page is explicitly explaining framework internals.
+
+## Version labels
+
+The website should distinguish:
+
+- current stable npm version
+- documentation target version
+- unreleased/main documentation if it is shown
+
+Do not label unreleased `main` behavior as already available from npm until the corresponding package has been published.
+
+## Framework commands to document
+
+```bash
+bcp dev
+bcp routes
+bcp build
+bcp start
+bcp update
+bcp version
+
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
+```
+
+Project creation:
+
+```bash
+npx create-bcp-app@latest my-app
+```
+
+## Middleware v2 documentation priority
+
+BCP 0.1.18 introduces a meaningful middleware architecture change, so the `bcp-docs` website should make the distinction between v1 and v2 clear.
+
+The middleware page should prominently explain:
+
+```text
+v1 next()        = return a pass-through instruction
+v2 await next()  = execute downstream middleware/application and receive Response
+```
+
+Existing v1 code remains supported, so migration documentation should describe v2 as an additive upgrade rather than a mandatory rewrite.
+
+See `middleware.md` for the full API and examples.
+
+## Release workflow for documentation
+
+Before publishing a new BCP release:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run rc:check
+```
+
+After npm publication, the docs website can update its displayed stable version.
+
+The framework repository remains authoritative for API correctness; `bcp-docs` is the presentation layer for that content.

package/docs/auth-route-guards.md

@@ -0,0 +1,216 @@
+# Auth Route Guards
+
+BCP Framework `0.1.17` integrates the Authentication Core with route guards through the server-only `bcp/auth` entrypoint.
+
+## Protect a route tree
+
+Create `guard.ts` in the route directory you want to protect:
+
+```ts
+import {
+    createAuthGuard,
+} from "bcp/auth";
+
+export const guard =
+    createAuthGuard({
+        redirectTo:
+            "/login",
+    });
+```
+
+The guard redirects unauthenticated requests to `/login` with status `303` by default. A `303` is suitable for guards that may run before form actions because it converts a redirected mutation request into a normal GET request to the login page.
+
+To return `401 Unauthorized` instead of redirecting:
+
+```ts
+import {
+    createAuthGuard,
+} from "bcp/auth";
+
+export const guard =
+    createAuthGuard({
+        redirectTo:
+            null,
+    });
+```
+
+## Require a role
+
+```ts
+import {
+    createRoleGuard,
+} from "bcp/auth";
+
+interface User {
+    id: number;
+    email: string;
+    role: string;
+}
+
+export const guard =
+    createRoleGuard<User>(
+        "admin",
+        {
+            redirectTo:
+                "/login",
+        }
+    );
+```
+
+An authenticated user without the required role receives `403 Forbidden` by default.
+
+You can redirect forbidden users instead:
+
+```ts
+export const guard =
+    createRoleGuard<User>(
+        "admin",
+        {
+            forbiddenRedirectTo:
+                "/forbidden",
+        }
+    );
+```
+
+## Require one of several roles
+
+The default role matching mode is `any`:
+
+```ts
+export const guard =
+    createRoleGuard<User>([
+        "admin",
+        "manager",
+    ]);
+```
+
+A user with either role is allowed.
+
+## Require all permissions
+
+`requireRole()` and `createRoleGuard()` can read another user field and require every value:
+
+```ts
+interface User {
+    id: number;
+    permissions: string[];
+}
+
+export const guard =
+    createRoleGuard<User>(
+        [
+            "users.read",
+            "users.write",
+        ],
+        {
+            roleField:
+                "permissions",
+            match:
+                "all",
+        }
+    );
+```
+
+## Inline guard logic
+
+Use `requireAuth()` when a guard needs additional application-specific checks:
+
+```ts
+import {
+    requireAuth,
+} from "bcp/auth";
+
+export async function guard() {
+    const result =
+        await requireAuth<AppUser>();
+
+    if (
+        result instanceof
+        Response
+    ) {
+        return result;
+    }
+
+    if (
+        !result.auth.user.active
+    ) {
+        return new Response(
+            "Forbidden",
+            {
+                status:
+                    403,
+            }
+        );
+    }
+
+    return result;
+}
+```
+
+## Auth data in child guards and loaders
+
+Successful auth helpers return guard data in this shape:
+
+```ts
+{
+    auth: {
+        sid,
+        user,
+        data,
+        iat,
+        exp,
+        iss,
+        aud,
+    },
+}
+```
+
+Because BCP merges parent guard data into child guards and page loaders, descendants can read the authenticated session without verifying the cookie again.
+
+Use `getGuardAuth()` for typed access:
+
+```ts
+import {
+    getGuardAuth,
+} from "bcp/auth";
+
+export async function loader({
+    guardData,
+}) {
+    const session =
+        getGuardAuth<AppUser>(
+            guardData
+        );
+
+    if (!session) {
+        throw new Error(
+            "Protected loader did not receive auth guard data."
+        );
+    }
+
+    return {
+        userId:
+            session.user.id,
+    };
+}
+```
+
+## Low-level role checks
+
+`requireRole()` is also available directly:
+
+```ts
+import {
+    requireRole,
+} from "bcp/auth";
+
+export function guard() {
+    return requireRole<AppUser>(
+        "admin"
+    );
+}
+```
+
+## Security boundary
+
+`bcp/auth` is server-only. BCP blocks it from page/client graphs and maps its browser export to the server-only runtime guard. Authentication and authorization checks should stay in guards, loaders, actions, API routes, or other server modules.