@chidchanun/bcp 0.1.21 → 0.1.22

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.22`
 
 ## Purpose
 
@@ -64,6 +64,7 @@ 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/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.19
 /releases/0.1.20
 /releases/0.1.21
+/releases/0.1.22
 ```
 
 The newest release should also be available from `/releases`.
@@ -151,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
@@ -210,6 +215,7 @@ Database
 Runtime
   Middleware
   Hydration
+  Developer Tools
   Caching
   Security
 
@@ -218,9 +224,9 @@ Production
   Development Logging
 
 Releases
+  0.1.22
   0.1.21
   0.1.20
-  0.1.19
 ```
 
 ## Suggested documentation page layout
@@ -305,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
 
@@ -392,11 +402,25 @@ 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
 
-`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.
+BCP 0.1.22 adds `bcp doctor` and `bcp inspect` as the first dedicated developer-diagnostics commands.
 
-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.
+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/releases/0.1.22.md

@@ -0,0 +1,77 @@
+# 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.
+
+## `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.
+
+## 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.
+
+## Next milestone
+
+The next planned milestone is BCP 0.1.23 — Logging & Observability.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "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",

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,