@chidchanun/bcp 0.1.20 → 0.1.22

package/README.md

@@ -1,8 +1,8 @@
 # BCP Framework
 
-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.
+BCP Framework is a React full-stack framework with file-based routing, SSR, client navigation, API routes, middleware, metadata, client islands, cache/revalidation, validation, structured errors, authentication, database primitives, security defaults and standalone production builds.
 
-> Current release target: `0.1.11`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
+> Current release target: `0.1.22`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
 
 ## Quick start
 
@@ -86,6 +86,61 @@ See [Application Modules](docs/application-modules.md) for the complete boundary
 
 Generated Tailwind projects compile to `public/bcp.css`. BCP 0.1.6 inlines that stylesheet into SSR HTML when it is 8 KiB or smaller, removing the stylesheet request from the initial render-critical path. Larger stylesheets remain external so the browser can cache them normally. If the application's Content Security Policy does not allow inline styles, BCP automatically keeps the external stylesheet link.
 
+## Development hydration parity
+
+BCP 0.1.21 fixes a development-only hydration mismatch where the SSR transform and the React Refresh client transform could assign different semantic values to the same multiline JSX attribute.
+
+For example, this is supported application code:
+
+```tsx
+<div
+    className="
+        min-h-screen
+        bg-white
+        text-slate-950
+    "
+/>
+```
+
+BCP 0.1.20 already normalized Windows `CRLF` and standalone `CR` source line endings to `LF`, but Babel's JSX transform could still collapse the multiline quoted attribute to a single-space-separated string while SSR preserved the original line breaks and indentation.
+
+In 0.1.21, Babel remains responsible for TypeScript stripping and React Refresh registration, but JSX is preserved until esbuild compiles it with the development JSX runtime. This keeps static JSX attribute semantics aligned between SSR and the development client bundle.
+
+Applications should not need to rewrite multiline classes to one line or use `suppressHydrationWarning` to work around framework transform differences. Genuine runtime mismatches caused by values such as `Date.now()`, `Math.random()`, browser-only initial state, locale differences or changing external data still need to be fixed in application code.
+
+See [Hydration and deterministic rendering](docs/hydration.md) for the transform pipeline and troubleshooting guidance.
+
+## Developer diagnostics
+
+BCP 0.1.22 adds dedicated developer tooling for diagnosing application setup without starting the development server.
+
+Run a project health check:
+
+```bash
+bcp doctor
+```
+
+The doctor checks the Node.js runtime, project structure, installed BCP/React packages, React and React DOM version parity, duplicate React package roots, environment/config loading, route conflicts and client/server boundaries. Blocking failures produce a non-zero process exit code.
+
+Inspect the resolved project inputs BCP sees:
+
+```bash
+bcp inspect
+```
+
+This prints development env filenames, public environment variable names, resolved BCP configuration, dependency versions and discovered page/API routes.
+
+Both commands support JSON output:
+
+```bash
+bcp doctor --json
+bcp inspect --json
+```
+
+The duplicate React checks are especially useful when verifying local framework builds. Install packed `.tgz` artifacts for release testing instead of linking `.package/bcp` directly into another project, because a linked staging directory can make the application and SSR renderer resolve different React instances.
+
+See [Developer Tools](docs/developer-tools.md) for the complete command reference.
+
 ## Commands
 
 ```bash
@@ -93,6 +148,10 @@ bcp dev
 bcp routes
 bcp build
 bcp start
+bcp doctor
+bcp doctor --json
+bcp inspect
+bcp inspect --json
 bcp update
 bcp version
 ```
@@ -117,7 +176,7 @@ bcp update --dry-run
 Or select a published version/dist-tag explicitly:
 
 ```bash
-bcp update 0.1.11
+bcp update 0.1.22
 bcp update next
 ```
 
@@ -777,12 +836,20 @@ No real npm publish command is run automatically by the repository.
 - [Server Data Loaders](docs/server-data-loaders.md)
 - [Protected Route Guards](docs/route-guards.md)
 - [Form Actions and Server Mutations](docs/form-actions.md)
+- [Validation](docs/validation.md)
+- [Error Handling](docs/error-handling.md)
+- [Authentication](docs/authentication.md)
+- [Auth Route Guards](docs/auth-route-guards.md)
 - [JWT Cookie Sessions](docs/session-auth.md)
+- [Database](docs/database.md)
+- [Database Migrations](docs/database-migrations.md)
+- [Middleware](docs/middleware.md)
+- [Hydration and deterministic rendering](docs/hydration.md)
+- [Developer Tools](docs/developer-tools.md)
 - [Updating BCP Framework](docs/updating.md)
 - [Routing](docs/routing.md)
 - [Configuration](docs/configuration.md)
 - [Caching](docs/caching.md)
-- [Middleware](docs/middleware.md)
 - [Security](docs/security.md)
 - [Deployment](docs/deployment.md)
 - [Releasing](docs/releasing.md)

package/docs/README.md

@@ -4,7 +4,7 @@ This directory is the documentation source of truth for the BCP Framework docume
 
 The recommended documentation website project name is `bcp-docs`.
 
-> Documentation target: BCP Framework `0.1.20`
+> Documentation target: BCP Framework `0.1.22`
 
 ## Purpose
 
@@ -63,7 +63,8 @@ The website should not invent API behavior that is not documented or tested in t
 | Website route | Source file | Description |
 | --- | --- | --- |
 | `/docs/middleware` | `middleware.md` | Middleware System v2 and v1 compatibility |
-| `/docs/hydration` | `hydration.md` | SSR/client hydration, deterministic rendering and Windows CRLF behavior |
+| `/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 |
@@ -75,9 +76,9 @@ Use the files under `docs/releases/` for release pages.
 Recommended route format:
 
 ```text
-/releases/0.1.18
-/releases/0.1.19
 /releases/0.1.20
+/releases/0.1.21
+/releases/0.1.22
 ```
 
 The newest release should also be available from `/releases`.
@@ -97,7 +98,8 @@ Recommended feature groups:
 - Loading and error UI
 - API routes
 - Client islands / partial hydration
-- Deterministic development hydration across LF/CRLF source checkouts
+- Deterministic development hydration across server/client transform pipelines
+- LF/CRLF-safe development source handling
 
 ### Server data and mutations
 
@@ -150,6 +152,10 @@ Recommended feature groups:
 - 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
@@ -209,6 +215,7 @@ Database
 Runtime
   Middleware
   Hydration
+  Developer Tools
   Caching
   Security
 
@@ -217,9 +224,9 @@ Production
   Development Logging
 
 Releases
+  0.1.22
+  0.1.21
   0.1.20
-  0.1.19
-  0.1.18
 ```
 
 ## Suggested documentation page layout
@@ -304,6 +311,10 @@ bcp dev
 bcp routes
 bcp build
 bcp start
+bcp doctor
+bcp doctor --json
+bcp inspect
+bcp inspect --json
 bcp update
 bcp version
 
@@ -351,7 +362,7 @@ See `validation.md` for the complete API and examples.
 
 ## Error Handling documentation priority
 
-BCP 0.1.20 introduces the public `bcp/error` entrypoint and a standard HTTP error envelope.
+BCP 0.1.20 introduced the public `bcp/error` entrypoint and a standard HTTP error envelope.
 
 The docs website should clearly distinguish:
 
@@ -375,17 +386,41 @@ See `error-handling.md` for the complete API and examples.
 
 ## Hydration documentation priority
 
-BCP 0.1.20 also fixes a Windows development hydration mismatch caused by CRLF source line endings passing through the React Refresh/Babel transform differently from SSR.
+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 JSX attributes such as template-literal `className` values are supported,
-- developers should not need to rewrite them as one-line strings to avoid framework hydration warnings,
-- BCP normalizes `CRLF` and standalone `CR` source line endings to `LF` before the development Babel transform,
+- 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 and troubleshooting steps.
+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
 

package/docs/developer-tools.md

@@ -0,0 +1,118 @@
+# Developer Tools
+
+BCP Framework 0.1.22 adds project diagnostics and runtime inspection commands for debugging a BCP application without starting the development server.
+
+## `bcp doctor`
+
+Run a health check from the application root:
+
+```bash
+bcp doctor
+```
+
+The command checks:
+
+- the current Node.js runtime against BCP's minimum supported version,
+- `package.json` and the `app/` project structure,
+- the declared and installed BCP package,
+- installed `react` and `react-dom` versions,
+- React / React DOM resolution parity between the application and the framework,
+- development environment files,
+- resolved `bcp.config.*` settings,
+- page/API route discovery and conflicts,
+- client/server module boundaries.
+
+A successful check is printed as `PASS`, a non-blocking recommendation as `WARN`, and a blocking project/runtime problem as `FAIL`.
+
+If one or more checks fail, `bcp doctor` sets a non-zero process exit code. This makes it suitable for local scripts and CI gates.
+
+Example:
+
+```text
+BCP Doctor v0.1.22
+Project: D:\apps\my-bcp-app
+Runtime: Node.js 24.15.0 | win32 x64
+
+[PASS] Node.js runtime: Node.js 24.15.0 satisfies >=24.11.0.
+[PASS] Project package: package.json is readable.
+[PASS] App directory: app/ is present.
+[PASS] React renderer version parity: react and react-dom both resolve to 19.2.8.
+[PASS] Single React instance: BCP and the application resolve the same React package.
+
+Summary: 11 passed, 0 warning(s), 0 failed.
+```
+
+### Duplicate React detection
+
+`bcp doctor` specifically checks the package locations used by the application and by BCP itself.
+
+This catches local-development layouts where an application resolves React from one `node_modules` tree while the BCP SSR renderer resolves React DOM from another. That situation commonly produces:
+
+```text
+Invalid hook call. Hooks can only be called inside of the body of a function component.
+```
+
+For local release testing, install the packed `.tgz` artifact instead of linking `.package/bcp` directly into another project. A packed package lets the BCP peer dependencies resolve from the application's normal `node_modules` tree.
+
+## `bcp inspect`
+
+Use `inspect` when you want a deterministic snapshot of the project inputs BCP sees:
+
+```bash
+bcp inspect
+```
+
+It prints:
+
+- framework version,
+- Node.js/platform information,
+- development `.env` files that were loaded,
+- names of public `BCP_PUBLIC_*` variables (values are not exposed by the summary),
+- the fully resolved BCP configuration,
+- resolved BCP/React/React DOM package versions,
+- discovered page and API routes.
+
+`inspect` validates route conflicts and client boundaries before printing its report. It does not start an HTTP server.
+
+## JSON output
+
+Both commands support machine-readable output:
+
+```bash
+bcp doctor --json
+bcp inspect --json
+```
+
+You can also target another project directory:
+
+```bash
+bcp doctor --root ../my-app --json
+bcp inspect --root ../my-app --json
+```
+
+`--json` is intentionally limited to `doctor` and `inspect` so other CLI commands keep their existing human-oriented output contracts.
+
+## Environment and config behavior
+
+Developer tools inspect the development environment because they are intended to diagnose `bcp dev` projects.
+
+Environment file precedence remains the same as the normal framework environment loader:
+
+```text
+.env
+.env.local
+.env.development
+.env.development.local
+```
+
+Resolved configuration still follows the framework configuration precedence rules. `bcp inspect` displays the final resolved config rather than only the source `bcp.config.*` object.
+
+## CI example
+
+A simple project-health gate can use:
+
+```bash
+bcp doctor --json > bcp-doctor.json
+```
+
+The command exits non-zero when blocking checks fail, while the JSON report remains available for CI logs or artifacts.

package/docs/hydration.md

@@ -2,21 +2,21 @@
 
 BCP uses server-side rendering for the initial HTML and React hydration in the browser. The server-rendered tree and the first client-rendered tree must produce the same element attributes and text.
 
-## Windows CRLF support
+## Development transform parity
 
-BCP Framework 0.1.20 normalizes application source line endings before the development React Refresh/Babel transform.
+BCP Framework 0.1.21 fixes a development hydration mismatch caused by the server and client using different JSX transform semantics.
 
-This fixes a Windows-specific hydration warning that could appear when a JSX attribute used a multiline template literal, for example:
+A common trigger is a multiline quoted JSX attribute:
 
 ```tsx
 export default function Page() {
     return (
         <main
-            className={`
+            className="
                 min-h-screen
                 bg-white
                 text-slate-950
-            `}
+            "
         >
             Hello
         </main>
@@ -24,13 +24,63 @@ export default function Page() {
 }
 ```
 
-On a CRLF checkout, the development client transform could previously preserve carriage-return characters differently from the SSR transform. React then compared two visually equivalent class lists whose underlying strings were different and reported a hydration mismatch.
+Before 0.1.21, development SSR loaded TSX through the server runtime while the client React Refresh path transformed the same module with `@babel/preset-react`. Babel's JSX transform normalizes whitespace in multiline quoted JSX attributes, so the client could receive a value such as:
+
+```text
+" min-h-screen bg-white text-slate-950 "
+```
+
+while SSR produced the original multiline value:
+
+```text
+"\n                min-h-screen\n                bg-white\n                text-slate-950\n            "
+```
+
+Those class lists are visually equivalent to CSS but they are different JavaScript strings, so React reports a hydration mismatch.
+
+BCP 0.1.21 keeps Babel in the development pipeline for TypeScript stripping and React Refresh registration, but Babel no longer compiles JSX. JSX is handed to esbuild with the development JSX runtime enabled. This keeps development JSX semantics aligned with the framework's esbuild-based client compilation and avoids Babel rewriting multiline attribute values before hydration.
+
+## Windows CRLF support
+
+BCP Framework 0.1.20 added source line-ending normalization for the development React Refresh path.
+
+Application source is normalized from `CRLF` (`\r\n`) and standalone `CR` (`\r`) to `LF` (`\n`) before Babel processes development modules. This prevents Windows line endings from introducing carriage-return differences between SSR and the client bundle.
+
+The 0.1.20 fix correctly removed carriage-return mismatches, but a separate Babel JSX whitespace normalization issue remained for multiline quoted JSX attributes. That remaining transform-parity issue is addressed by 0.1.21.
+
+Developers do not need to rewrite multiline `className` values as one-line strings to work around either framework issue.
 
-BCP now normalizes both `CRLF` (`\r\n`) and standalone `CR` (`\r`) source line endings to `LF` (`\n`) before Babel processes development application modules. Developers do not need to rewrite multiline `className` values as one line to work around this framework issue.
+## Supported multiline patterns
+
+Both of these patterns are valid application code:
+
+```tsx
+<div
+    className="
+        min-h-screen
+        bg-white
+        text-slate-950
+    "
+/>
+```
+
+and:
+
+```tsx
+<div
+    className={`
+        min-h-screen
+        bg-white
+        text-slate-950
+    `}
+/>
+```
+
+BCP should hydrate them deterministically without requiring application-specific whitespace workarounds.
 
 ## What BCP fixes automatically
 
-The line-ending fix addresses deterministic source transformation. It does not hide genuine hydration differences caused by application behavior.
+The framework fixes deterministic source-transform differences. It does not hide genuine hydration differences caused by application behavior.
 
 BCP applications should still avoid producing different initial values on the server and client from code such as:
 
@@ -55,6 +105,7 @@ Other common application-level causes include:
 
 - locale-dependent formatting that differs between server and browser,
 - data that changes between SSR and hydration without a serialized snapshot,
+- browser-only state initialized from `localStorage`, `sessionStorage` or `matchMedia`,
 - invalid HTML nesting,
 - browser extensions that modify the DOM before React hydrates it.
 
@@ -91,22 +142,49 @@ export default function BrowserValue() {
 }
 ```
 
-## Development and production
+## Development pipeline
+
+The 0.1.21 development client transform is intentionally split by responsibility:
+
+```text
+application TS/TSX
+      ↓
+line-ending normalization
+      ↓
+Babel
+  - remove TypeScript syntax
+  - inject React Refresh registrations
+  - preserve JSX
+      ↓
+esbuild
+  - compile JSX
+  - use development JSX runtime
+  - bundle application modules
+      ↓
+React hydration
+```
+
+The key rule is that React Refresh instrumentation must not change the semantic value of JSX attributes compared with SSR.
 
-The Windows CRLF issue was specific to the development React Refresh/Babel path. Production client compilation uses the production esbuild pipeline. The 0.1.20 fix makes development source handling deterministic before Babel so development hydration matches the SSR semantics.
+Production client compilation already uses the esbuild production pipeline and does not use the development React Refresh Babel transform.
 
 ## Troubleshooting
 
-If React still reports a hydration mismatch after upgrading to a BCP release containing this fix:
+If React still reports a hydration mismatch after upgrading to a BCP release containing the 0.1.21 fix:
 
 1. stop the BCP dev server,
 2. remove `.bcp-framework/`,
 3. start `bcp dev` again,
-4. inspect the first differing server/client value in the React hydration warning,
-5. check for request-time, random, locale, browser-only or externally changing values.
+4. hard-refresh the browser,
+5. inspect the first differing server/client value in the React hydration warning,
+6. check for request-time, random, locale, browser-only or externally changing values.
+
+For framework diagnostics, compare the initial SSR HTML with the generated development client bundle. If the same static JSX attribute produces different strings, treat it as a framework transform-parity regression.
 
 Do not use `suppressHydrationWarning` as a general fix. It should only be used when a difference is intentional and understood.
 
 ## Regression coverage
 
-The framework test suite contains a Windows-style CRLF fixture with a multiline JSX `className`. The development client bundle is required to normalize source line endings before the React Refresh Babel transform.
+The framework test suite contains a Windows-style CRLF fixture using the same multiline quoted JSX `className` pattern that exposed the issue in a real BCP application.
+
+The regression test extracts the generated `className` value from the development bundle and verifies that its semantic string value still contains the expected line breaks and indentation instead of Babel's collapsed whitespace form.

package/docs/releases/0.1.21.md

@@ -0,0 +1,92 @@
+# BCP Framework 0.1.21
+
+BCP 0.1.21 is a hydration parity hotfix for development builds.
+
+## Why this release exists
+
+BCP 0.1.20 fixed a Windows-specific `CRLF` versus `LF` mismatch in the React Refresh client transform. After that fix, a second development-only mismatch was isolated: Babel's JSX transform could normalize whitespace inside multiline quoted JSX attributes differently from the SSR transform.
+
+For example:
+
+```tsx
+<div
+    className="
+        min-h-screen
+        bg-white
+        text-slate-950
+    "
+/>
+```
+
+SSR could preserve the multiline string while the development client bundle produced a collapsed value such as:
+
+```text
+" min-h-screen bg-white text-slate-950 "
+```
+
+React correctly treats those as different attribute strings and reports a hydration mismatch.
+
+## Fix
+
+The development client pipeline now separates React Refresh instrumentation from JSX compilation:
+
+```text
+TS/TSX source
+  -> normalize line endings
+  -> Babel: strip TypeScript + inject React Refresh registrations
+  -> preserve JSX
+  -> esbuild: compile JSX with the development JSX runtime
+  -> client bundle
+```
+
+This prevents `@babel/preset-react` from rewriting multiline JSX attribute whitespace before hydration while keeping Fast Refresh support.
+
+## Highlights
+
+- Preserves multiline quoted JSX attribute semantics in development client bundles.
+- Keeps the 0.1.20 `CRLF` / `CR` to `LF` source normalization.
+- Uses esbuild as the development JSX compiler after React Refresh instrumentation.
+- Enables the esbuild development JSX runtime for dev bundles.
+- Adds regression coverage using the same multiline quoted `className` pattern that reproduced the real hydration warning.
+- Regression coverage extracts the generated `className` string and compares its semantic value, rather than only checking that carriage-return characters are absent.
+- No application workaround such as rewriting multiline classes to one line is required.
+
+## Compatibility
+
+0.1.21 does not change the public application API.
+
+Existing routes, loaders, guards, actions, middleware, validation, authentication, database APIs and the 0.1.20 Error Handling System continue to work unchanged.
+
+The change is limited to development client transformation and hydration parity.
+
+## Local package verification
+
+Do not install `.package/bcp` directly into an application for release verification. A direct local-directory install can be linked back to the framework checkout. In that layout, application components may resolve `react` from the application while BCP's SSR renderer resolves `react-dom` from the framework checkout, creating two React instances and causing an `Invalid hook call` before hydration starts.
+
+Use the packed release artifact under `.package/artifacts/*.tgz` or the existing package smoke tests instead. A packed tarball is installed as a normal package under the application `node_modules` tree, so the framework's React peer dependencies resolve from the same application installation as the rendered components.
+
+A stack trace that mixes paths such as:
+
+```text
+<app>/node_modules/react/...
+<framework-checkout>/node_modules/react-dom/...
+```
+
+indicates a linked local-package test with duplicate React instances, not a hydration failure.
+
+## Upgrade verification
+
+After upgrading an application:
+
+```powershell
+Remove-Item -Recurse -Force .bcp-framework -ErrorAction SilentlyContinue
+npm run dev
+```
+
+A multiline static JSX attribute should hydrate without the server/client attribute mismatch that occurred in 0.1.20.
+
+If a hydration warning remains after 0.1.21, compare the first differing SSR/client value and check for genuine runtime differences such as `Date.now()`, `Math.random()`, locale formatting, browser-only initial state, changing external data or invalid HTML nesting.
+
+## Roadmap note
+
+Because 0.1.21 is used for this hotfix, the previously planned Developer Tools milestone moves to 0.1.22.