@chidchanun/bcp 0.1.21 → 0.1.23

package/README.md

@@ -2,7 +2,7 @@
 
 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.21`. 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
 
@@ -110,6 +110,37 @@ Applications should not need to rewrite multiline classes to one line or use `su
 
 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
@@ -117,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
 ```
@@ -141,7 +176,7 @@ bcp update --dry-run
 Or select a published version/dist-tag explicitly:
 
 ```bash
-bcp update 0.1.21
+bcp update 0.1.22
 bcp update next
 ```
 
@@ -810,6 +845,7 @@ No real npm publish command is run automatically by the repository.
 - [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)

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.21`
+> Documentation target: BCP Framework `0.1.23`
 
 ## Purpose
 
@@ -64,9 +64,10 @@ The website should not invent API behavior that is not documented or tested in t
 | --- | --- | --- |
 | `/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 |
-| `/docs/development-logging` | `development-logging.md` | Development request logging |
 
 ### Releases
 
@@ -75,9 +76,9 @@ Use the files under `docs/releases/` for release pages.
 Recommended route format:
 
 ```text
-/releases/0.1.19
-/releases/0.1.20
 /releases/0.1.21
+/releases/0.1.22
+/releases/0.1.23
 ```
 
 The newest release should also be available from `/releases`.
@@ -151,6 +152,16 @@ 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 and duplicate BCP installation diagnostics
+- `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
@@ -165,7 +176,7 @@ Suggested content, not a required exact copy:
 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.
+middleware, observability and production tooling.
 ```
 
 Primary actions:
@@ -210,17 +221,18 @@ Database
 Runtime
   Middleware
   Hydration
+  Developer Tools
+  Logging & Observability
   Caching
   Security
 
 Production
   Deployment
-  Development Logging
 
 Releases
+  0.1.23
+  0.1.22
   0.1.21
-  0.1.20
-  0.1.19
 ```
 
 ## Suggested documentation page layout
@@ -274,6 +286,11 @@ import {
     unauthorized,
 } from "bcp/error";
 
+import {
+    logger,
+    requestLogger,
+} from "bcp/server";
+
 import {
     type MiddlewarePipelineHandler,
 } from "bcp/middleware";
@@ -305,6 +322,10 @@ bcp dev
 bcp routes
 bcp build
 bcp start
+bcp doctor
+bcp doctor --json
+bcp inspect
+bcp inspect --json
 bcp update
 bcp version
 
@@ -314,6 +335,8 @@ 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:
 
 ```bash
@@ -392,11 +415,44 @@ The docs website should make these points clear:
 
 See `hydration.md` for the full explanation, transform pipeline and troubleshooting steps.
 
-## Release roadmap adjustment
+## 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,
+- 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.
 
-`0.1.21` is reserved for the hydration parity hotfix because `0.1.20` was already published before the remaining Babel JSX whitespace mismatch was isolated.
+## Release roadmap
 
-The previously planned Developer Tools release moves to `0.1.22`, and later roadmap items should shift forward accordingly unless they are regrouped into a larger milestone.
+`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
 

package/docs/developer-tools.md

@@ -0,0 +1,166 @@
+# Developer Tools
+
+BCP Framework 0.1.22 adds project diagnostics and runtime inspection commands for debugging a BCP application without starting the development server.
+
+## CLI executable names
+
+The published BCP package exposes two executable names that point to the same CLI:
+
+```text
+bcp
+bcp-framework
+```
+
+`bcp` remains the primary and backward-compatible command.
+
+On Windows, Microsoft SQL Server also installs a native utility named `bcp.exe`. When that executable appears earlier on `PATH`, typing `bcp` in PowerShell can launch the SQL Server utility instead of BCP Framework.
+
+Use the Windows-safe alias in that situation:
+
+```powershell
+bcp-framework doctor
+bcp-framework inspect
+bcp-framework dev
+bcp-framework build
+bcp-framework update
+```
+
+You can also explicitly run the project-local executable with npm:
+
+```powershell
+npm exec -- bcp doctor
+```
+
+BCP application npm scripts can continue using `bcp dev`, `bcp build`, and other existing commands because npm places the project's `node_modules/.bin` directory on the script `PATH` before system executables.
+
+## `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.
+
+### Duplicate BCP package protection
+
+A BCP application must not load `node_modules/bcp` and `node_modules/@chidchanun/bcp` as two separate framework copies.
+
+The CLI performs a startup preflight. If both package roots exist, runtime commands such as `dev`, `build`, and `start` stop before SSR starts. Two framework copies create separate React contexts, which can make APIs such as `useLoaderData()` incorrectly report missing loader data even when the route loader executed successfully.
+
+For local release verification, install the tarball under the existing `bcp` dependency key instead of adding the scoped package beside it:
+
+```powershell
+npm install `
+  --no-save `
+  --package-lock=false `
+  "bcp@file:D:\bcp-framework\.package\artifacts\chidchanun-bcp-0.1.22.tgz"
+```
+
+The installed folder remains `node_modules/bcp` even when the package inside the tarball is published as `@chidchanun/bcp`.
+
+## `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/development-logging.md

@@ -1,13 +1,241 @@
-# Development request logging
+# Logging and observability
 
-BCP keeps development request output focused on application API traffic.
+BCP Framework 0.1.23 adds a structured server logger and upgrades development request timing output while keeping framework-internal browser/bootstrap traffic quiet by default.
 
-By default, request-style console lines are shown for application API routes such as:
+## Server logger
+
+Import logging APIs from the server-only `bcp/server` entry:
+
+```ts
+import {
+    logger,
+} from "bcp/server";
+
+logger.info(
+    "Application started",
+    {
+        service: "catalog",
+    }
+);
+```
+
+Available levels are:
+
+```text
+debug
+info
+warn
+error
+silent
+```
+
+The default level is `info`.
+
+Structured fields can contain strings, numbers, booleans, objects, arrays, `Error` values and `bigint` values. Circular references are replaced with `[Circular]` rather than crashing the logger.
+
+## Request-scoped logging
+
+Use `requestLogger()` while handling an API route, loader, guard or form action:
+
+```ts
+import {
+    requestLogger,
+} from "bcp/server";
+
+export async function loader() {
+    const log =
+        await requestLogger({
+            feature: "categories",
+        });
+
+    log.info(
+        "Loading categories"
+    );
+
+    return {
+        items: [],
+    };
+}
+```
+
+The returned child logger automatically binds the current request identity:
+
+```text
+requestId
+method
+path
+```
+
+`requestId` uses the same request-scoped value exposed by `requestId()`: a valid incoming `X-Request-Id` is reused, otherwise BCP creates a UUID for the request.
+
+## Response request ID
+
+When an application wants to return the request identity to a caller, wrap a response with `attachRequestId()`:
+
+```ts
+import {
+    attachRequestId,
+    json,
+} from "bcp/server";
+
+export async function GET() {
+    return attachRequestId(
+        json({
+            ok: true,
+        })
+    );
+}
+```
+
+The returned response includes:
 
 ```text
-GET /api/users 200 1.24ms
+X-Request-Id: <current request id>
+```
+
+This helper preserves the original response status, status text, body and headers.
+
+## Child loggers
+
+Bind shared fields once with `child()`:
+
+```ts
+import {
+    logger,
+} from "bcp/server";
+
+const dbLog =
+    logger.child({
+        component: "database",
+    });
+
+dbLog.debug(
+    "Executing query",
+    {
+        operation: "users.list",
+    }
+);
 ```
 
-BCP suppresses framework and browser bootstrap traffic such as `/_bcp/*`, page/document requests, public static assets, and the generated Tailwind stylesheet endpoint `/api/bcp-styles`.
+Child bindings are inherited by further child loggers.
+
+## Log level
+
+Set the minimum log level with:
+
+```bash
+BCP_LOG_LEVEL=debug
+```
+
+Supported values:
+
+```text
+debug
+info
+warn
+error
+silent
+```
+
+Invalid or missing values fall back to `info`.
+
+Use `debug` during framework/application diagnostics to see development SSR and module-import timing events.
+
+## Log format
 
-Build, SSR, Fast Refresh, watcher and error diagnostics are not affected by this filter.
+Human-readable output is the default:
+
+```bash
+BCP_LOG_FORMAT=pretty
+```
+
+Example:
+
+```text
+[2026-08-27T10:00:00.000Z] [INFO] [bcp] User loaded userId=42
+```
+
+For containers, log collectors and CI systems use JSON lines:
+
+```bash
+BCP_LOG_FORMAT=json
+```
+
+Example:
+
+```json
+{"timestamp":"2026-08-27T10:00:00.000Z","level":"info","logger":"bcp","message":"User loaded","userId":42}
+```
+
+Each log call emits exactly one line.
+
+## Development HTTP logging
+
+Development request output remains focused on application API traffic. BCP suppresses request-style logs for framework and browser bootstrap traffic such as:
+
+```text
+/_bcp/*
+/api/bcp-styles
+page/document requests
+public static assets
+```
+
+An application API request is converted into the structured logger format. With pretty output it resembles:
+
+```text
+[2026-08-27T10:00:00.000Z] [INFO] [bcp-dev] HTTP request event=http.request method=GET path=/api/users status=200 durationMs=1.24
+```
+
+With `BCP_LOG_FORMAT=json` the same event is emitted as one JSON object containing:
+
+```text
+event=http.request
+method
+path
+status
+durationMs
+```
+
+Existing development `Import: ...ms` and `SSR: ...ms` measurements are converted into `debug` events:
+
+```text
+module.import
+ssr.render
+```
+
+They are therefore visible when `BCP_LOG_LEVEL=debug` and stay out of normal `info` output.
+
+## Errors
+
+Pass an `Error` as a structured field:
+
+```ts
+try {
+    // ...
+} catch (error) {
+    logger.error(
+        "Operation failed",
+        {
+            error,
+        }
+    );
+}
+```
+
+`Error` values are serialized with their name, message, stack and cause when available.
+
+## Environment example
+
+A development `.env.local` can use:
+
+```text
+BCP_LOG_LEVEL=debug
+BCP_LOG_FORMAT=pretty
+```
+
+A production/container environment can use:
+
+```text
+BCP_LOG_LEVEL=info
+BCP_LOG_FORMAT=json
+```