Developer Tools

BCP Framework exposes project diagnostics and runtime inspection commands for debugging an installed BCP application without starting the development server.

BCP 0.1.29 upgrades these tools with project/deployment diagnostics while keeping the previous report fields available.

CLI executable names

The published BCP package exposes two executable names that point to the same CLI:

bcp
bcp-framework

bcp remains the primary executable inside npm scripts.

On Windows, Microsoft SQL Server can also install a native bcp.exe, and normal PowerShell sessions do not automatically include the project's node_modules/.bin directory. Prefer:

npm exec -- bcp-framework doctor
npm exec -- bcp-framework inspect
npm exec -- bcp-framework generate page dashboard/users
npm exec -- bcp-framework dev
npm exec -- bcp-framework build
npm exec -- bcp-framework update

Inside npm scripts, commands can continue to use bcp ... because npm prepends node_modules/.bin to PATH.

Framework source checkout

bcp doctor and bcp inspect are application diagnostics. They expect an application root with app/ and an installed BCP dependency.

For the framework source checkout itself, use the release validation commands instead:

npm run typecheck
npm run test:unit
npm run rc:check

bcp doctor

Run from an installed application root:

npm exec -- bcp-framework doctor

BCP reports each check as:

PASS  valid/healthy
WARN  non-blocking recommendation
FAIL  blocking project/runtime problem

If one or more checks fail, the command sets a non-zero process exit code.

Core checks

Doctor continues to check:

• supported Node.js version,
• readable package.json,
• app/ project structure,
• declared/installed BCP dependency,
• installed React / React DOM,
• React renderer version parity,
• single React / React DOM resolution,
• development environment files,
• resolved bcp.config.*,
• page/API route discovery and conflicts,
• client/server module boundaries.

Doctor v2 checks — 0.1.29

Doctor now also checks:

• dependency lockfile presence,
• detected package manager,
• multiple framework dependency declarations,
• production-hardening environment validity,
• standalone production artifact presence,
• Docker + npm lockfile reproducibility guidance,
• configured storage provider when detected.

Example diagnostic IDs include:

project.lockfile
dependencies.framework-declarations
runtime.production-hardening
production.build
production.docker-lockfile
storage.provider

Duplicate framework declarations

A BCP application should keep one framework dependency under the application key bcp:

{
  "dependencies": {
    "bcp": "npm:@chidchanun/[email protected]"
  }
}

Do not keep both:

bcp
@chidchanun/bcp

as separate application dependencies. Multiple framework copies can split shared React/framework contexts and produce misleading loader/auth errors.

Lockfile / Docker diagnostics

A lockfile is recommended for reproducible CI and Docker builds.

For npm applications with a Dockerfile, Doctor expects package-lock.json so the image can use npm ci deterministically.

Other package-manager lockfiles can still be identified, but the Docker recommendation must match the package manager used by that project.

Production-hardening diagnostics

Doctor validates the current 0.1.28+ hardening environment controls:

BCP_REQUEST_TIMEOUT_MS
BCP_HEADERS_TIMEOUT_MS
BCP_KEEP_ALIVE_TIMEOUT_MS
BCP_SHUTDOWN_TIMEOUT_MS
BCP_TRUST_PROXY

Invalid timeout relationships or invalid values are reported before deployment.

bcp inspect

Use Inspect for a deterministic snapshot of the project inputs BCP sees:

npm exec -- bcp-framework inspect

The existing report includes:

• framework version,
• Node.js/platform information,
• development .env files,
• names of public BCP_PUBLIC_* variables,
• resolved BCP configuration,
• resolved BCP/React/React DOM versions,
• discovered page/API routes.

Inspect validates route conflicts and client boundaries before returning its report. It does not start an HTTP server.

Inspect v2 project report — 0.1.29

The report now adds a project object.

Representative JSON shape:

{
  "project": {
    "packageManager": "npm",
    "lockfile": "package-lock.json",
    "metadataFile": "bcp.project.json",
    "presets": {
      "tailwind": true,
      "database": "mysql",
      "auth": "jwt-cookie",
      "storage": "local"
    },
    "productionBuild": true,
    "dockerfile": "Dockerfile",
    "frameworkDeclarations": [
      {
        "name": "bcp",
        "range": "npm:@chidchanun/[email protected]",
        "section": "dependencies"
      }
    ],
    "storage": {
      "provider": "local",
      "file": "lib/storage.ts"
    },
    "hardening": {
      "valid": true,
      "message": "..."
    }
  }
}

The project field is additive; previous top-level Inspect fields remain available.

bcp.project.json integration

Projects created by create-bcp-app 0.1.29+ contain a non-secret bcp.project.json manifest.

Inspect uses this metadata for explicit preset identity where available, including:

package manager
Tailwind preset
database preset
auth preset
storage preset

For older projects without the manifest, diagnostics fall back to package files and source inspection where practical.

See Project Metadata.

Storage detection

For new generated projects, the storage provider comes from bcp.project.json.

For older projects, Inspect can infer common providers from lib/storage.ts:

local
amazon-s3
cloudflare-r2
s3-compatible
custom
none

This is diagnostic metadata only; it does not expose access keys or other credentials.

JSON output

Both commands support machine-readable output:

npm exec -- bcp-framework doctor --json
npm exec -- bcp-framework inspect --json

Target another installed BCP application with:

npm exec -- bcp-framework doctor --root ..\my-app --json
npm exec -- bcp-framework inspect --root ..\my-app --json

--json is intentionally limited to Doctor/Inspect so other commands can retain human-oriented output contracts.

Environment behavior

Developer tools inspect the development environment because they are primarily project-development diagnostics.

Environment file precedence remains:

.env
.env.local
.env.development
.env.development.local

Inspect displays resolved configuration, not only the raw bcp.config.* source object.

CI example

bcp doctor --json > bcp-doctor.json

The command exits non-zero when blocking checks fail while the JSON report remains suitable for CI artifacts/logs.

Related documentation

• Project Generators
• Project Metadata
• Production Hardening
• Configuration
• Deployment