@chidchanun/bcp 0.1.22 → 0.1.23

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.22`
+> Documentation target: BCP Framework `0.1.23`
 
 ## Purpose
 
@@ -65,9 +65,9 @@ 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
 
@@ -76,9 +76,9 @@ 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
+/releases/0.1.23
 ```
 
 The newest release should also be available from `/releases`.
@@ -155,7 +155,13 @@ Recommended feature groups:
 - `bcp doctor` project/runtime diagnostics
 - `bcp inspect` environment/config/route inspection
 - JSON developer-tool output for CI/automation
-- Duplicate React package-root diagnostics
+- 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
@@ -170,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:
@@ -216,17 +222,17 @@ 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
 ```
 
 ## Suggested documentation page layout
@@ -280,6 +286,11 @@ import {
     unauthorized,
 } from "bcp/error";
 
+import {
+    logger,
+    requestLogger,
+} from "bcp/server";
+
 import {
     type MiddlewarePipelineHandler,
 } from "bcp/middleware";
@@ -324,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
@@ -411,16 +424,35 @@ 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 rather than linked staging directories.
+- 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.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.
+`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

@@ -2,6 +2,37 @@
 
 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:
@@ -54,6 +85,23 @@ Invalid hook call. Hooks can only be called inside of the body of a function com
 
 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:

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
+```

package/docs/releases/0.1.22.md

@@ -12,6 +12,35 @@ BCP 0.1.22 adds the first dedicated Developer Tools milestone.
 - Added route conflict and client-boundary validation without starting the dev server.
 - Added development environment diagnostics without printing private environment values.
 - Added unit coverage for CLI parsing, version checks, missing-project diagnostics and deterministic inspection output.
+- Added the `bcp-framework` executable alias for Windows systems where the `bcp` command is already occupied by Microsoft SQL Server's `bcp.exe` utility.
+- Fixed `<Form>` SSR so framework runtime rendering no longer depends on a global `React` binding when an application uses the classic JSX transform.
+- Added CLI preflight protection against installing `bcp` and `@chidchanun/bcp` as two separate framework copies, which can split loader/context state across package instances.
+
+## CLI executable compatibility
+
+The published package now exposes both executable names:
+
+```text
+bcp
+bcp-framework
+```
+
+Both names execute the same BCP Framework CLI. Existing applications and npm scripts can continue using `bcp` unchanged.
+
+On Windows installations that include Microsoft SQL Server tools, use the collision-free alias for direct shell commands:
+
+```powershell
+bcp-framework doctor
+bcp-framework inspect
+bcp-framework dev
+bcp-framework build
+```
+
+Alternatively, explicitly run the project-local `bcp` executable through npm:
+
+```powershell
+npm exec -- bcp doctor
+```
 
 ## `bcp doctor`
 
@@ -66,11 +95,47 @@ If an application is linked directly to a framework staging directory, the appli
 
 For local release verification, continue using packed `.tgz` artifacts rather than installing `.package/bcp` as a linked directory.
 
+## Duplicate BCP package protection
+
+Local tarball verification must keep one BCP package root in the application.
+
+Installing a tarball directly when the application already declares an npm alias named `bcp` can leave both of these paths installed:
+
+```text
+node_modules/bcp
+node_modules/@chidchanun/bcp
+```
+
+That layout is unsafe because application imports can use one `BcpLoaderDataProvider` context while the CLI/SSR runtime uses the other package copy. The visible error can therefore incorrectly say that `useLoaderData()` has no loader data.
+
+BCP 0.1.22 now checks this before runtime commands start and fails with an actionable duplicate-install message.
+
+For local tarball verification, install the artifact under the existing dependency key:
+
+```powershell
+npm install `
+  --no-save `
+  --package-lock=false `
+  "bcp@file:D:\bcp-framework\.package\artifacts\chidchanun-bcp-0.1.22.tgz"
+```
+
+## SSR JSX-runtime compatibility
+
+Framework runtime components must not inherit JSX runtime assumptions from the consuming application's `tsconfig.json`.
+
+`<Form>` now renders its provider and native `<form>` element through `createElement()`. This keeps SSR compatible with both automatic JSX runtime projects and projects that still use the classic JSX transform, where unbound generated `React.createElement(...)` calls would otherwise produce:
+
+```text
+ReferenceError: React is not defined
+```
+
+Regression coverage includes server rendering and a classic-JSX transform check that rejects implicit `React.createElement` output from the Form runtime source.
+
 ## Compatibility
 
 0.1.22 does not change public rendering, routing, database, authentication, validation, middleware or error-handling APIs.
 
-The new functionality is additive CLI tooling. Existing BCP applications can continue using the current commands unchanged.
+The Developer Tools commands and `bcp-framework` executable alias are additive. Existing BCP applications can continue using current commands unchanged.
 
 ## Next milestone
 

package/docs/releases/0.1.23.md

@@ -0,0 +1,131 @@
+# BCP Framework 0.1.23
+
+BCP 0.1.23 introduces the Logging & Observability foundation and carries forward the stabilization fixes verified against the BCP documentation application during the 0.1.22 release-candidate cycle.
+
+## Highlights
+
+- Added structured server logging through `bcp/server`.
+- Added `logger.debug()`, `logger.info()`, `logger.warn()` and `logger.error()`.
+- Added child loggers with persistent structured bindings.
+- Added `requestLogger()` for request-scoped `requestId`, HTTP method and path bindings.
+- Added `attachRequestId()` for explicit `X-Request-Id` response propagation.
+- Added `BCP_LOG_LEVEL=debug|info|warn|error|silent`.
+- Added `BCP_LOG_FORMAT=pretty|json`.
+- Added safe serialization for `Error`, `bigint` and circular structured fields.
+- Development API request logs now flow through the structured logger while framework bootstrap traffic remains filtered.
+- Development module-import and SSR timing lines are normalized into `module.import` and `ssr.render` debug events.
+- Added regression coverage for log filtering, JSON records, error serialization, request-scoped identity and response request IDs.
+
+## Server logger
+
+```ts
+import {
+    logger,
+} from "bcp/server";
+
+logger.info(
+    "User loaded",
+    {
+        userId: 42,
+    }
+);
+```
+
+The default logger reads its level and format from the environment at log time, so normal application configuration can set:
+
+```text
+BCP_LOG_LEVEL=info
+BCP_LOG_FORMAT=json
+```
+
+## Request-scoped logger
+
+```ts
+import {
+    requestLogger,
+} from "bcp/server";
+
+export async function loader() {
+    const log =
+        await requestLogger({
+            feature: "categories",
+        });
+
+    log.info(
+        "Loading categories"
+    );
+
+    return {
+        items: [],
+    };
+}
+```
+
+The child logger binds:
+
+```text
+requestId
+method
+path
+```
+
+using the same request context already used by `requestId()`, `requestMethod()` and `requestUrl()`.
+
+## Request ID response helper
+
+```ts
+import {
+    attachRequestId,
+    json,
+} from "bcp/server";
+
+export async function GET() {
+    return attachRequestId(
+        json({
+            ok: true,
+        })
+    );
+}
+```
+
+The response contains `X-Request-Id` with the active request identity.
+
+## Development observability
+
+Application API request logs retain the existing development noise filter but are now emitted as structured events with:
+
+```text
+event=http.request
+method
+path
+status
+durationMs
+```
+
+SSR and module import measurements are emitted at `debug` level as:
+
+```text
+ssr.render
+module.import
+```
+
+Set `BCP_LOG_LEVEL=debug` when profiling development rendering.
+
+## Stabilization fixes included
+
+The 0.1.23 source line also contains the fixes completed while validating 0.1.22 against `bcp-docs`:
+
+- the `bcp-framework` Windows-safe executable alias avoids the Microsoft SQL Server `bcp.exe` command collision,
+- `<Form>` SSR no longer depends on an implicit global `React` binding under classic JSX transforms,
+- the CLI detects duplicate `bcp` / `@chidchanun/bcp` installations before they produce split React contexts or misleading `useLoaderData()` failures,
+- local release verification guidance uses packed tarballs under the existing `bcp` dependency key so only one framework copy is installed.
+
+## Compatibility
+
+Logging is additive and server-only. Existing rendering, routing, loaders, guards, actions, middleware, validation, database and authentication APIs remain compatible.
+
+Existing application code does not need to adopt the logger to upgrade to 0.1.23.
+
+## Next milestone
+
+The next planned milestone is BCP 0.1.24 — File Upload foundation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",
@@ -24,7 +24,8 @@
     "node": ">=24.11.0"
   },
   "bin": {
-    "bcp": "packages/cli/bin/bcp.mjs"
+    "bcp": "packages/cli/bin/bcp.mjs",
+    "bcp-framework": "packages/cli/bin/bcp.mjs"
   },
   "exports": {
     ".": {