@chidchanun/bcp 0.1.23 → 0.1.24

package/docs/README.md

@@ -1,321 +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.23`
-
-## 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/development-logging` | `development-logging.md` | Structured logging, request identity and development observability |
-| `/docs/caching` | `caching.md` | Cache and revalidation |
-| `/docs/security` | `security.md` | Framework security defaults |
-
-### Releases
-
-Use the files under `docs/releases/` for release pages.
+| `/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 route format:
-
-```text
-/releases/0.1.21
-/releases/0.1.22
-/releases/0.1.23
-```
-
-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:
+## 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
-
-### Database
+- loaders, guards and form actions
+- client islands / partial hydration
+- Fast Refresh and deterministic development hydration
 
-- `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 and duplicate BCP installation diagnostics
+- `bcp doctor`
+- `bcp inspect`
 - `bcp-framework` Windows-safe CLI alias
-- Structured server logger
-- Request-scoped loggers with request identity
-- Pretty and JSON log formats
-- Configurable log levels
-- Structured development HTTP/SSR timing events
-- 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, observability 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
+- standalone production build
+- release/package smoke checks
 
-```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
-  Logging & Observability
-  Caching
-  Security
-
-Production
-  Deployment
-
-Releases
-  0.1.23
-  0.1.22
-  0.1.21
-```
-
-## 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 0.1.24 documentation priorities
 
-- documentation search
-- version selector
-- API symbol index
-- interactive examples
-- edit-on-GitHub links
+### File Upload
 
-## Code examples
-
-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";
-
-import {
-    db,
-} from "bcp/database";
+    parseMultipartFormData,
+    getUploadedFile,
+    requireUploadedFile,
+    validateUploadedFile,
+    saveUploadedFile,
+    sanitizeUploadFileName,
+    UploadError,
+} from "bcp/server";
+```
 
-import {
-    v,
-    validateFormData,
-} from "bcp/validation";
+Documentation must make the following boundaries clear:
 
-import {
-    badRequest,
-    unauthorized,
-} from "bcp/error";
+- `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 {
-    logger,
-    requestLogger,
-} from "bcp/server";
+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
 
-## Version labels
+0.1.23 introduced:
 
-The website should distinguish:
+- `logger` / `createLogger()`
+- request-scoped `requestLogger()`
+- log levels and JSON format
+- `X-Request-Id` helpers
+- structured development request/SSR timing
 
-- current stable npm version
-- documentation target version
-- unreleased/main documentation if it is shown
+See `development-logging.md`.
 
-Do not label unreleased `main` behavior as already available from npm until the corresponding package has been published.
+### Developer Tools
 
-## Framework commands to document
+0.1.22 introduced `bcp doctor` and `bcp inspect`, JSON reports, duplicate React diagnostics and duplicate BCP-install protection.
+
+See `developer-tools.md`.
+
+## Commands
 
 ```bash
 bcp dev
@@ -335,128 +175,31 @@ bcp db status
 bcp db rollback
 ```
 
-On Windows systems where Microsoft SQL Server owns the `bcp` executable name, document the equivalent collision-free commands with `bcp-framework`.
-
-Project creation:
+On Windows systems where SQL Server owns `bcp.exe`, direct shell commands can use:
 
-```bash
-npx create-bcp-app@latest my-app
+```powershell
+bcp-framework doctor
+bcp-framework inspect
+bcp-framework dev
 ```
 
-## Middleware v2 documentation priority
-
-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
-```
-
-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
-
-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.
+## Releases
 
-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.
-
-The docs website should make these points clear:
-
-- 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
+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.
 
-BCP 0.1.22 adds `bcp doctor` and `bcp inspect` as the first dedicated developer-diagnostics commands.
+## Release workflow
 
-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,
-- duplicate `bcp` / `@chidchanun/bcp` installation detection,
-- 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 installed under the existing `bcp` dependency key rather than linked staging directories.
-
-See `developer-tools.md` for the full command reference.
-
-## Logging and observability documentation priority
-
-BCP 0.1.23 adds the structured logging foundation through `bcp/server`.
-
-The docs website should surface:
-
-- `logger.debug/info/warn/error`,
-- `createLogger()` and child loggers,
-- `requestLogger()` and its request ID/method/path bindings,
-- `attachRequestId()` for `X-Request-Id` response propagation,
-- `BCP_LOG_LEVEL`,
-- `BCP_LOG_FORMAT=pretty|json`,
-- JSON-safe `Error`, `bigint` and circular value handling,
-- structured `http.request`, `module.import` and `ssr.render` development events,
-- the existing dev noise filter for framework-internal requests.
-
-See `development-logging.md` for the complete API and examples.
-
-## Release roadmap
-
-`0.1.23` is the Logging & Observability milestone. The next planned milestone is `0.1.24` — File Upload foundation, followed by Background Jobs, Testing Utilities, Production Build Hardening and Plugin Architecture unless milestones are regrouped.
-
-## Release workflow for documentation
-
-Before publishing a new BCP release:
+Before publishing a BCP release:
 
 ```bash
 npm run typecheck
@@ -464,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.