@chidchanun/bcp 0.1.22 → 0.1.24

package/docs/README.md

@@ -1,310 +1,161 @@
 # BCP Framework Documentation Source
 
-This directory is the documentation source of truth for the BCP Framework documentation website.
+This directory is the documentation source of truth for the BCP Framework documentation website (`bcp-docs`).
 
-The recommended documentation website project name is `bcp-docs`.
+> Documentation target: BCP Framework `0.1.24`
 
-> Documentation target: BCP Framework `0.1.22`
-
-## 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.
+When framework behavior changes, update framework source/tests first, then the matching file under `docs/`, then the release note under `docs/releases/`.
 
 ## Recommended website navigation
 
 ### Getting Started
 
-| Website route | Source file | Description |
+| Route | Source | Purpose |
 | --- | --- | --- |
 | `/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 |
+| `/docs/application-modules` | `application-modules.md` | Client/server boundaries |
+| `/docs/deployment` | `deployment.md` | Production deployment |
+| `/docs/updating` | `updating.md` | Framework upgrades |
 
 ### Routing and Data
 
-| Website route | Source file | Description |
+| Route | Source | Purpose |
 | --- | --- | --- |
 | `/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 |
-| `/docs/validation` | `validation.md` | Typed form/API validation and field errors |
-| `/docs/error-handling` | `error-handling.md` | Structured HTTP errors and standard error responses |
+| `/docs/route-guards` | `route-guards.md` | Scoped route authorization |
+| `/docs/form-actions` | `form-actions.md` | Server mutations/forms |
+| `/docs/server-request-apis` | `server-request-apis.md` | Request/cookie/response APIs |
+| `/docs/validation` | `validation.md` | Typed validation |
+| `/docs/error-handling` | `error-handling.md` | Structured HTTP errors |
+| `/docs/file-upload` | `file-upload.md` | Multipart parsing, validation and local file storage |
 
 ### Authentication
 
-| Website route | Source file | Description |
+| Route | Source | Purpose |
 | --- | --- | --- |
-| `/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 |
+| `/docs/authentication` | `authentication.md` | Authentication Core |
+| `/docs/auth-route-guards` | `auth-route-guards.md` | Auth-aware guards |
+| `/docs/session-auth` | `session-auth.md` | JWT cookie sessions |
 
 ### Database
 
-| Website route | Source file | Description |
+| Route | Source | Purpose |
 | --- | --- | --- |
-| `/docs/database` | `database.md` | `bcp/database`, MySQL and transactions |
-| `/docs/database-migrations` | `database-migrations.md` | Migration CLI and migration files |
+| `/docs/database` | `database.md` | MySQL database primitives |
+| `/docs/database-migrations` | `database-migrations.md` | Migration CLI and files |
 
 ### Runtime and Infrastructure
 
-| Website route | Source file | Description |
+| Route | Source | Purpose |
 | --- | --- | --- |
-| `/docs/middleware` | `middleware.md` | Middleware System v2 and v1 compatibility |
-| `/docs/hydration` | `hydration.md` | SSR/client transform parity, deterministic rendering and Windows line endings |
-| `/docs/developer-tools` | `developer-tools.md` | `bcp doctor`, `bcp inspect` and JSON diagnostics |
-| `/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.20
-/releases/0.1.21
-/releases/0.1.22
-```
-
-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.
+| `/docs/middleware` | `middleware.md` | Middleware System v2 |
+| `/docs/hydration` | `hydration.md` | SSR/client hydration parity |
+| `/docs/developer-tools` | `developer-tools.md` | `doctor` / `inspect` diagnostics |
+| `/docs/development-logging` | `development-logging.md` | Structured logging and observability |
+| `/docs/caching` | `caching.md` | Cache/revalidation |
+| `/docs/security` | `security.md` | Security defaults and body limits |
 
-Recommended feature groups:
+## Current capability groups
 
 ### Application
 
-- File-based routing
-- React SSR
+- React SSR and hydration
+- file-based page/API routing
+- dynamic/catch-all routes
+- layouts and metadata
 - SPA navigation
-- Persistent layouts
-- Loading and error UI
-- API routes
-- Client islands / partial hydration
-- Deterministic development hydration across server/client transform pipelines
-- LF/CRLF-safe development source handling
-
-### Server data and mutations
-
-- Server data loaders
-- Route guards
-- Form actions
-- Request-scoped server APIs
-- Cookies and redirects
-- `bcp/validation`
-- Typed form/API validation
-- Field and form error output
-- `bcp/error`
-- Structured HTTP error responses
-- Safe unknown-error fallback responses
+- loaders, guards and form actions
+- client islands / partial hydration
+- Fast Refresh and deterministic development hydration
 
-### Database
-
-- `bcp/database`
-- Lazy MySQL connection pool
-- Queries and prepared execution
-- Transactions
-- Database migrations
-- Migration status and rollback
-
-### Authentication
+### Server
 
-- `bcp/auth`
-- JWT cookie sessions
-- Typed users and session data
-- Session rotation
-- `requireAuth()`
-- `requireRole()`
-- Auth-aware route guards
+- request-scoped server APIs
+- cookies and redirects
+- JWT sessions and authentication
+- Middleware System v2
+- typed validation and structured errors
+- structured logging with request identity
+- multipart file uploads and local filesystem persistence
 
-### Middleware
+### Database
 
-- 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
+- `bcp/database`
+- MySQL pool/query helpers
+- transactions
+- migrations/status/rollback
 
-### Production and DX
+### Developer Experience
 
 - `create-bcp-app`
-- Interactive project setup
-- Tailwind preset
-- Database/auth presets
 - `bcp update`
-- `bcp doctor` project/runtime diagnostics
-- `bcp inspect` environment/config/route inspection
-- JSON developer-tool output for CI/automation
-- Duplicate React package-root diagnostics
-- 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, validation, structured errors,
-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
-  Validation
-  Error Handling
-
-Authentication
-  Authentication Core
-  Auth Route Guards
-  JWT Sessions
-
-Database
-  Database
-  Migrations
-
-Runtime
-  Middleware
-  Hydration
-  Developer Tools
-  Caching
-  Security
-
-Production
-  Deployment
-  Development Logging
-
-Releases
-  0.1.22
-  0.1.21
-  0.1.20
-```
-
-## 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:
+- `bcp doctor`
+- `bcp inspect`
+- `bcp-framework` Windows-safe CLI alias
+- standalone production build
+- release/package smoke checks
 
-- documentation search
-- version selector
-- API symbol index
-- interactive examples
-- edit-on-GitHub links
+## BCP 0.1.24 documentation priorities
 
-## Code examples
+### File Upload
 
-Examples should use the public package entrypoints that application developers actually install.
-
-Preferred:
+BCP 0.1.24 exposes upload helpers through the server-only `bcp/server` entrypoint:
 
 ```ts
 import {
-    auth,
-    requireAuth,
-} from "bcp/auth";
+    parseMultipartFormData,
+    getUploadedFile,
+    requireUploadedFile,
+    validateUploadedFile,
+    saveUploadedFile,
+    sanitizeUploadFileName,
+    UploadError,
+} from "bcp/server";
+```
 
-import {
-    db,
-} from "bcp/database";
+Documentation must make the following boundaries clear:
 
-import {
-    v,
-    validateFormData,
-} from "bcp/validation";
+- `server.bodyLimit` / `BCP_BODY_LIMIT` is the outer request-size limit enforced by the security gateway.
+- multipart and individual file limits can be stricter than the global body limit.
+- MIME type and extension are metadata checks, not file-signature verification.
+- default storage names are UUID based.
+- existing files are not overwritten unless explicitly requested.
+- saved metadata includes SHA-256 checksum.
+- local filesystem storage is the initial foundation; distributed/object storage requires a later adapter layer.
 
-import {
-    badRequest,
-    unauthorized,
-} from "bcp/error";
+See `file-upload.md`.
 
-import {
-    type MiddlewarePipelineHandler,
-} from "bcp/middleware";
-```
+### Dev route/client bundle synchronization
 
-Avoid documenting internal monorepo imports such as:
+0.1.24 also fixes a development-only graph drift that could produce:
 
 ```text
-packages/server/src/...
-packages/client/src/...
+Client bundle was not found for route "/docs/[...slug]".
 ```
 
-unless a page is explicitly explaining framework internals.
+The dev gateway now compares the actual page route topology and refreshes the internal client bundler when pathname/page/layout structure changes. Users should no longer need to manually delete `.bcp-framework` to recover a missing route bundle.
+
+### Logging & Observability
+
+0.1.23 introduced:
 
-## Version labels
+- `logger` / `createLogger()`
+- request-scoped `requestLogger()`
+- log levels and JSON format
+- `X-Request-Id` helpers
+- structured development request/SSR timing
 
-The website should distinguish:
+See `development-logging.md`.
 
-- current stable npm version
-- documentation target version
-- unreleased/main documentation if it is shown
+### Developer Tools
 
-Do not label unreleased `main` behavior as already available from npm until the corresponding package has been published.
+0.1.22 introduced `bcp doctor` and `bcp inspect`, JSON reports, duplicate React diagnostics and duplicate BCP-install protection.
 
-## Framework commands to document
+See `developer-tools.md`.
+
+## Commands
 
 ```bash
 bcp dev
@@ -324,107 +175,31 @@ bcp db status
 bcp db rollback
 ```
 
-Project creation:
-
-```bash
-npx create-bcp-app@latest my-app
-```
-
-## Middleware v2 documentation priority
+On Windows systems where SQL Server owns `bcp.exe`, direct shell commands can use:
 
-BCP 0.1.18 introduced 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
+```powershell
+bcp-framework doctor
+bcp-framework inspect
+bcp-framework dev
 ```
 
-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.
-
-## Validation documentation priority
-
-BCP 0.1.19 introduced the public `bcp/validation` entrypoint. The docs website should show validation in both form-action and API-route examples.
-
-Important concepts to surface:
-
-- `v.object`, `v.string`, `v.number`, `v.boolean`, `v.array`
-- FormData coercion with `validateFormData()`
-- `success/data` versus `issues/fieldErrors/formErrors`
-- object fields are stripped unless `allowUnknown: true`
-- `refine()` for custom application rules
-- no external validation dependency is required
+## Releases
 
-See `validation.md` for the complete API and examples.
-
-## Error Handling documentation priority
-
-BCP 0.1.20 introduced the public `bcp/error` entrypoint and a standard HTTP error envelope.
-
-The docs website should clearly distinguish:
+Recommended release routes:
 
 ```text
-notFound()          = activate page 404 UI behavior
-notFoundResponse()  = return a JSON 404 HTTP response
+/releases/0.1.24
+/releases/0.1.23
+/releases/0.1.22
+/releases/0.1.21
+/releases/0.1.20
 ```
 
-Important concepts to surface:
-
-- `HttpError` and `createHttpError()`
-- `errorResponse()` for any 4xx/5xx status
-- `toErrorResponse()` for safe catch boundaries
-- `badRequest()`, `unauthorized()`, `forbidden()`, `conflict()` and other convenience helpers
-- standard `{ error: { status, code, message, details? } }` payload
-- error responses default to `Cache-Control: no-store`
-- unknown exceptions become a generic 500 response without exposing the original exception message
-- normal field validation still belongs to `bcp/validation`
-
-See `error-handling.md` for the complete API and examples.
-
-## Hydration documentation priority
-
-BCP 0.1.20 added line-ending normalization for the development React Refresh path. That removed the Windows `CRLF` versus `LF` mismatch, but a second issue remained when Babel compiled multiline quoted JSX attributes and collapsed their whitespace differently from SSR.
-
-BCP 0.1.21 completes this fix by keeping Babel responsible for TypeScript removal and React Refresh instrumentation while leaving JSX untransformed. esbuild then performs the development JSX transform with the development JSX runtime enabled.
+Do not present unreleased `main` behavior as already available from npm. The website should distinguish the stable npm version from the documentation target when they differ.
 
-The docs website should make these points clear:
+## Release workflow
 
-- multiline quoted JSX attributes are supported,
-- multiline template-literal JSX expressions are supported,
-- developers should not need to rewrite multiline `className` values as one-line strings to avoid framework hydration warnings,
-- `CRLF` and standalone `CR` source line endings are normalized to `LF` before development instrumentation,
-- React Refresh instrumentation must not change the semantic value of JSX attributes,
-- the framework fix does not suppress genuine hydration mismatches caused by random values, locale differences, browser-only initial branches, changing external data or invalid HTML,
-- `suppressHydrationWarning` is not a general-purpose solution.
-
-See `hydration.md` for the full explanation, transform pipeline and troubleshooting steps.
-
-## Developer Tools documentation priority
-
-BCP 0.1.22 adds `bcp doctor` and `bcp inspect` as the first dedicated developer-diagnostics commands.
-
-The docs website should surface:
-
-- PASS/WARN/FAIL health checks,
-- non-zero exit codes for blocking doctor failures,
-- React / React DOM version and package-root parity,
-- config and development environment inspection,
-- page/API route summaries,
-- `--json` output for CI and automation,
-- the recommendation to verify local releases from packed `.tgz` artifacts rather than linked staging directories.
-
-See `developer-tools.md` for the full command reference.
-
-## Release roadmap
-
-`0.1.22` is the Developer Tools milestone. The next planned milestone is `0.1.23` — Logging & Observability, followed by File Upload and the remaining pre-0.2 foundation milestones unless they are regrouped.
-
-## Release workflow for documentation
-
-Before publishing a new BCP release:
+Before publishing a BCP release:
 
 ```bash
 npm run typecheck
@@ -432,6 +207,8 @@ 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 behavior. `bcp-docs` is the presentation layer for this source content.
+
+## Next milestone
 
-The framework repository remains authoritative for API correctness; `bcp-docs` is the presentation layer for that content.
+After 0.1.24, the planned follow-up is `0.1.25` for upload/storage adapters and production file-delivery hardening unless roadmap priorities are regrouped.

package/docs/auth-route-guards.md

@@ -211,6 +211,20 @@ export function guard() {
 }
 ```
 
+## Standalone production behavior
+
+BCP 0.1.24 keeps `bcp/auth` inside the same production guard runtime graph as `runWithRequestContext()`. This guarantees that `requireAuth()`, `requireRole()`, `auth()`, `getSession()` and `cookies()` observe the active request after `bcp build`, rather than resolving through a second framework request-context instance.
+
+This fixes the production-only failure:
+
+```text
+BCP Framework: server request APIs can only be used while handling a request.
+```
+
+No application guard changes are required. Continue importing authentication helpers from `bcp/auth` normally.
+
+The production form-action bundle applies the same runtime unification because route guards may execute before an action.
+
 ## 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.