@chidchanun/bcp 0.1.21 → 0.1.23

package/docs/releases/0.1.22.md

@@ -0,0 +1,142 @@
+# BCP Framework 0.1.22
+
+BCP 0.1.22 adds the first dedicated Developer Tools milestone.
+
+## Highlights
+
+- Added `bcp doctor` for project/runtime health diagnostics.
+- Added `bcp inspect` for environment, resolved config, dependency and route inspection.
+- Added `--json` output for both developer-tool commands.
+- `bcp doctor` returns a non-zero exit code when blocking checks fail, so it can be used as a CI health gate.
+- Added React / React DOM version and package-location checks to detect duplicate React installations before they surface as `Invalid hook call` runtime failures.
+- 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`
+
+```bash
+bcp doctor
+```
+
+The health report checks:
+
+- Node.js support,
+- `package.json`, `app/` and optional `public/`,
+- declared and installed BCP dependencies,
+- React and React DOM versions,
+- whether BCP and the application resolve the same React/React DOM package roots,
+- development environment loading,
+- resolved framework config,
+- page/API route discovery,
+- client/server module boundaries.
+
+Use JSON output in automation:
+
+```bash
+bcp doctor --json
+```
+
+## `bcp inspect`
+
+```bash
+bcp inspect
+```
+
+The inspection report includes:
+
+- framework/runtime identity,
+- loaded development env filenames,
+- public environment variable names,
+- resolved BCP configuration,
+- installed BCP/React/React DOM versions,
+- page and API route mappings.
+
+Machine-readable output:
+
+```bash
+bcp inspect --json
+```
+
+## Duplicate React diagnostics
+
+The Developer Tools milestone includes a check motivated by the 0.1.21 local release verification workflow.
+
+If an application is linked directly to a framework staging directory, the application may resolve React from its own `node_modules` while the BCP SSR renderer resolves React DOM from the framework checkout. `bcp doctor` detects this package-root split and reports it as a failure before SSR reaches the `Invalid hook call` error.
+
+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 Developer Tools commands and `bcp-framework` executable alias are additive. Existing BCP applications can continue using current commands unchanged.
+
+## Next milestone
+
+The next planned milestone is BCP 0.1.23 — Logging & Observability.

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.21",
+  "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": {
     ".": {

package/packages/cli/bin/bcp.mjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 
+import fs from "node:fs";
+import path from "node:path";
 import {
     spawn,
 } from "node:child_process";
@@ -7,6 +9,46 @@ import {
     fileURLToPath,
 } from "node:url";
 
+const command =
+    process.argv[2] ??
+    "dev";
+
+const duplicateInstall =
+    findDuplicateFrameworkInstall(
+        process.cwd()
+    );
+
+if (duplicateInstall) {
+    const message = [
+        "BCP Framework: duplicate framework installations detected.",
+        "",
+        `bcp: ${duplicateInstall.bcp}`,
+        `@chidchanun/bcp: ${duplicateInstall.scoped}`,
+        "",
+        "The application and the BCP CLI can load different framework copies. This breaks shared React contexts such as useLoaderData() and may produce misleading missing-loader errors.",
+        "",
+        "Keep only one application dependency named bcp. For local tarball verification install it under the bcp dependency key, for example:",
+        "npm install --no-save --package-lock=false \"bcp@file:D:\\\\path\\\\to\\\\chidchanun-bcp-0.1.22.tgz\"",
+    ].join("\n");
+
+    if (
+        command !== "doctor" &&
+        command !== "inspect"
+    ) {
+        console.error(
+            message
+        );
+        process.exitCode =
+            1;
+        process.exit();
+    }
+
+    console.warn(
+        message
+    );
+    console.warn("");
+}
+
 const bootstrapFile =
     fileURLToPath(
         new URL(
@@ -91,3 +133,72 @@ child.once(
             code ?? 1;
     }
 );
+
+function findDuplicateFrameworkInstall(
+    rootDirectory
+) {
+    const bcp =
+        resolvePackageRoot(
+            path.join(
+                rootDirectory,
+                "node_modules",
+                "bcp"
+            )
+        );
+    const scoped =
+        resolvePackageRoot(
+            path.join(
+                rootDirectory,
+                "node_modules",
+                "@chidchanun",
+                "bcp"
+            )
+        );
+
+    if (
+        !bcp ||
+        !scoped ||
+        normalizePath(bcp) ===
+            normalizePath(scoped)
+    ) {
+        return null;
+    }
+
+    return {
+        bcp,
+        scoped,
+    };
+}
+
+function resolvePackageRoot(
+    directory
+) {
+    if (
+        !fs.existsSync(
+            path.join(
+                directory,
+                "package.json"
+            )
+        )
+    ) {
+        return null;
+    }
+
+    try {
+        return fs.realpathSync(
+            directory
+        );
+    } catch {
+        return path.resolve(
+            directory
+        );
+    }
+}
+
+function normalizePath(
+    value
+) {
+    return process.platform === "win32"
+        ? value.toLowerCase()
+        : value;
+}

package/packages/cli/src/args.ts

@@ -8,6 +8,8 @@ export type CliCommand =
   | "routes"
   | "update"
   | "db"
+  | "doctor"
+  | "inspect"
   | "help"
   | "version";
 
@@ -33,6 +35,8 @@ export interface CliOptions {
 
   updateDryRun?: boolean;
 
+  json?: boolean;
+
   dbAction?: DatabaseCliAction;
 
   dbMigrationName?: string;
@@ -61,6 +65,9 @@ export function parseCliArgs(
   let updateDryRun =
     false;
 
+  let json =
+    false;
+
   let dbAction:
     DatabaseCliAction | undefined;
 
@@ -209,6 +216,14 @@ export function parseCliArgs(
       continue;
     }
 
+    if (
+      argument === "--json"
+    ) {
+      json =
+        true;
+      continue;
+    }
+
     if (
       argument.startsWith("-")
     ) {
@@ -297,6 +312,8 @@ export function parseCliArgs(
       argument === "routes" ||
       argument === "update" ||
       argument === "db" ||
+      argument === "doctor" ||
+      argument === "inspect" ||
       argument === "help" ||
       argument === "version"
     ) {
@@ -322,6 +339,16 @@ export function parseCliArgs(
     );
   }
 
+  if (
+    json &&
+    command !== "doctor" &&
+    command !== "inspect"
+  ) {
+    throw new Error(
+      "Option --json is only valid with `bcp doctor` or `bcp inspect`."
+    );
+  }
+
   return {
     command,
     rootDirectory,
@@ -330,6 +357,11 @@ export function parseCliArgs(
     updateTarget,
     updateCheck,
     updateDryRun,
+    ...(json
+      ? {
+          json: true,
+        }
+      : {}),
     ...(command === "db"
       ? {
           dbAction,