@chidchanun/bcp 0.1.28 → 0.2.0

package/docs/developer-tools.md

@@ -1,6 +1,8 @@
 # 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 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
 
@@ -11,35 +13,26 @@ bcp
 bcp-framework
 ```
 
-`bcp` remains the primary and backward-compatible executable name inside npm scripts.
-
-On Windows, Microsoft SQL Server also installs a native utility named `bcp.exe`. When that executable appears earlier on `PATH`, typing `bcp` directly in PowerShell can launch the SQL Server utility instead of BCP Framework.
+`bcp` remains the primary executable inside npm scripts.
 
-PowerShell also does not add an application's `node_modules/.bin` directory to its normal interactive `PATH`. Therefore the recommended interactive Windows invocation is the project-local executable through npm:
+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:
 
 ```powershell
 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
 ```
 
-Or call the generated Windows shim explicitly:
-
-```powershell
-.\node_modules\.bin\bcp-framework.cmd 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.
+Inside npm scripts, commands can continue to use `bcp ...` because npm prepends `node_modules/.bin` to `PATH`.
 
-### Framework source checkout
+## Framework source checkout
 
-The framework source repository itself is a private development workspace and is not an installed copy of the published package. Merely opening PowerShell in `D:\bcp-framework` does not make `bcp-framework` available on `PATH`.
+`bcp doctor` and `bcp inspect` are application diagnostics. They expect an application root with `app/` and an installed BCP dependency.
 
-`bcp doctor` and `bcp inspect` are application diagnostics: they expect an application root with `app/` plus an installed BCP dependency. Do not use them as the release-health command for the framework source checkout.
-
-For framework development and release validation, use:
+For the framework source checkout itself, use the release validation commands instead:
 
 ```powershell
 npm run typecheck
@@ -47,101 +40,201 @@ npm run test:unit
 npm run rc:check
 ```
 
-After a packed or published package is installed into an application such as `bcp-docs`, run:
+## `bcp doctor`
+
+Run from an installed application root:
 
 ```powershell
 npm exec -- bcp-framework doctor
-npm exec -- bcp-framework inspect
 ```
 
-## `bcp doctor`
-
-Run a health check from an installed application root. On Windows PowerShell, prefer:
+BCP reports each check as:
 
-```powershell
-npm exec -- bcp-framework doctor
+```text
+PASS  valid/healthy
+WARN  non-blocking recommendation
+FAIL  blocking project/runtime problem
 ```
 
-The command checks:
+If one or more checks fail, the command sets a non-zero process exit code.
 
-- 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,
+### 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.*` settings,
+- resolved `bcp.config.*`,
 - 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`.
+### Doctor v2 checks — 0.1.29
 
-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.
+Doctor now also checks:
 
-Example:
+- 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.
 
-```text
-BCP Doctor v0.1.22
-Project: D:\apps\my-bcp-app
-Runtime: Node.js 24.15.0 | win32 x64
+Example diagnostic IDs include:
 
-[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.
+```text
+project.lockfile
+dependencies.framework-declarations
+runtime.production-hardening
+production.build
+production.docker-lockfile
+storage.provider
 ```
 
-### Duplicate React detection
+### Duplicate framework declarations
 
-`bcp doctor` specifically checks the package locations used by the application and by BCP itself.
+A BCP application should keep one framework dependency under the application key `bcp`:
 
-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:
+```json
+{
+  "dependencies": {
+    "bcp": "npm:@chidchanun/bcp@0.1.29"
+  }
+}
+```
+
+Do not keep both:
 
 ```text
-Invalid hook call. Hooks can only be called inside of the body of a function component.
+bcp
+@chidchanun/bcp
 ```
 
-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.
+as separate application dependencies. Multiple framework copies can split shared React/framework contexts and produce misleading loader/auth errors.
 
-### Duplicate BCP package protection
+### Lockfile / Docker diagnostics
 
-A BCP application must not load `node_modules/bcp` and `node_modules/@chidchanun/bcp` as two separate framework copies.
+A lockfile is recommended for reproducible CI and Docker builds.
 
-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 npm applications with a `Dockerfile`, Doctor expects `package-lock.json` so the image can use `npm ci` deterministically.
 
-For local release verification, install the tarball under the existing `bcp` dependency key instead of adding the scoped package beside it:
+Other package-manager lockfiles can still be identified, but the Docker recommendation must match the package manager used by that project.
 
-```powershell
-npm install `
-  --no-save `
-  --package-lock=false `
-  "bcp@file:D:\bcp-framework\.package\artifacts\chidchanun-bcp-0.1.22.tgz"
+### Production-hardening diagnostics
+
+Doctor validates the current `0.1.28+` hardening environment controls:
+
+```text
+BCP_REQUEST_TIMEOUT_MS
+BCP_HEADERS_TIMEOUT_MS
+BCP_KEEP_ALIVE_TIMEOUT_MS
+BCP_SHUTDOWN_TIMEOUT_MS
+BCP_TRUST_PROXY
 ```
 
-The installed folder remains `node_modules/bcp` even when the package inside the tarball is published as `@chidchanun/bcp`.
+Invalid timeout relationships or invalid values are reported before deployment.
 
 ## `bcp inspect`
 
-Use `inspect` when you want a deterministic snapshot of the project inputs BCP sees:
+Use Inspect for a deterministic snapshot of the project inputs BCP sees:
 
 ```powershell
 npm exec -- bcp-framework inspect
 ```
 
-It prints:
+The existing report includes:
 
 - 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.
+- 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:
+
+```json
+{
+  "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/bcp@0.1.29",
+        "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:
+
+```text
+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](project-metadata.md).
 
-`inspect` validates route conflicts and client boundaries before printing its report. It does not start an HTTP server.
+## 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`:
+
+```text
+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
 
@@ -152,20 +245,20 @@ npm exec -- bcp-framework doctor --json
 npm exec -- bcp-framework inspect --json
 ```
 
-You can also target another installed BCP application directory:
+Target another installed BCP application with:
 
 ```powershell
 npm exec -- bcp-framework doctor --root ..\my-app --json
 npm exec -- bcp-framework inspect --root ..\my-app --json
 ```
 
-`--json` is intentionally limited to `doctor` and `inspect` so other CLI commands keep their existing human-oriented output contracts.
+`--json` is intentionally limited to Doctor/Inspect so other commands can retain human-oriented output contracts.
 
-## Environment and config behavior
+## Environment behavior
 
-Developer tools inspect the development environment because they are intended to diagnose `bcp dev` projects.
+Developer tools inspect the development environment because they are primarily project-development diagnostics.
 
-Environment file precedence remains the same as the normal framework environment loader:
+Environment file precedence remains:
 
 ```text
 .env
@@ -174,16 +267,20 @@ Environment file precedence remains the same as the normal framework environment
 .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.
+Inspect displays resolved configuration, not only the raw `bcp.config.*` source object.
 
 ## CI example
 
-A simple project-health gate can use:
-
 ```bash
 bcp doctor --json > bcp-doctor.json
 ```
 
-Inside npm scripts or CI package-script execution, npm already places `node_modules/.bin` on `PATH`.
+The command exits non-zero when blocking checks fail while the JSON report remains suitable for CI artifacts/logs.
+
+## Related documentation
 
-The command exits non-zero when blocking checks fail, while the JSON report remains available for CI logs or artifacts.
+- [Project Generators](generators.md)
+- [Project Metadata](project-metadata.md)
+- [Production Hardening](production-hardening.md)
+- [Configuration](configuration.md)
+- [Deployment](deployment.md)

package/docs/docs-web-manifest.json

@@ -0,0 +1,97 @@
+{
+  "schemaVersion": 1,
+  "framework": "bcp",
+  "versionTarget": "0.2.0",
+  "releaseState": "unreleased",
+  "sections": [
+    {
+      "id": "getting-started",
+      "title": "Getting Started",
+      "pages": [
+        { "route": "/docs/getting-started", "source": "getting-started.md", "title": "Getting Started" },
+        { "route": "/docs/configuration", "source": "configuration.md", "title": "Configuration" },
+        { "route": "/docs/application-modules", "source": "application-modules.md", "title": "Application Modules" },
+        { "route": "/docs/project-metadata", "source": "project-metadata.md", "title": "Project Metadata" },
+        { "route": "/docs/deployment", "source": "deployment.md", "title": "Deployment" },
+        { "route": "/docs/updating", "source": "updating.md", "title": "Updating BCP" }
+      ]
+    },
+    {
+      "id": "routing-data",
+      "title": "Routing & Data",
+      "pages": [
+        { "route": "/docs/routing", "source": "routing.md", "title": "Routing" },
+        { "route": "/docs/server-data-loaders", "source": "server-data-loaders.md", "title": "Server Data Loaders" },
+        { "route": "/docs/route-guards", "source": "route-guards.md", "title": "Route Guards" },
+        { "route": "/docs/form-actions", "source": "form-actions.md", "title": "Form Actions" },
+        { "route": "/docs/server-request-apis", "source": "server-request-apis.md", "title": "Server Request APIs" },
+        { "route": "/docs/validation", "source": "validation.md", "title": "Validation" },
+        { "route": "/docs/error-handling", "source": "error-handling.md", "title": "Error Handling" }
+      ]
+    },
+    {
+      "id": "authentication",
+      "title": "Authentication",
+      "pages": [
+        { "route": "/docs/authentication", "source": "authentication.md", "title": "Authentication" },
+        { "route": "/docs/auth-route-guards", "source": "auth-route-guards.md", "title": "Auth Route Guards" },
+        { "route": "/docs/session-auth", "source": "session-auth.md", "title": "JWT Sessions" }
+      ]
+    },
+    {
+      "id": "database",
+      "title": "Database",
+      "pages": [
+        { "route": "/docs/database", "source": "database.md", "title": "Database" },
+        { "route": "/docs/database-migrations", "source": "database-migrations.md", "title": "Database Migrations" }
+      ]
+    },
+    {
+      "id": "runtime",
+      "title": "Runtime & Infrastructure",
+      "pages": [
+        { "route": "/docs/middleware", "source": "middleware.md", "title": "Middleware" },
+        { "route": "/docs/hydration", "source": "hydration.md", "title": "Hydration" },
+        { "route": "/docs/development-logging", "source": "development-logging.md", "title": "Logging & Observability" },
+        { "route": "/docs/caching", "source": "caching.md", "title": "Caching" },
+        { "route": "/docs/security", "source": "security.md", "title": "Security" },
+        { "route": "/docs/production-hardening", "source": "production-hardening.md", "title": "Production Hardening" }
+      ]
+    },
+    {
+      "id": "storage",
+      "title": "Storage & Uploads",
+      "pages": [
+        { "route": "/docs/file-upload", "source": "file-upload.md", "title": "File Upload" },
+        { "route": "/docs/storage", "source": "storage.md", "title": "Storage & File Delivery" },
+        { "route": "/docs/storage-ecosystem", "source": "storage-ecosystem.md", "title": "Storage Ecosystem" },
+        { "route": "/docs/s3-storage", "source": "s3-storage.md", "title": "S3-Compatible Storage" }
+      ]
+    },
+    {
+      "id": "developer-experience",
+      "title": "Developer Experience",
+      "pages": [
+        { "route": "/docs/generators", "source": "generators.md", "title": "Project Generators" },
+        { "route": "/docs/developer-tools", "source": "developer-tools.md", "title": "Doctor & Inspect" }
+      ]
+    },
+    {
+      "id": "platform-compatibility",
+      "title": "Platform & Compatibility",
+      "pages": [
+        { "route": "/docs/platform-contract", "source": "platform-contract.md", "title": "Framework Platform Contract" },
+        { "route": "/docs/migration-0.2", "source": "migration-0.2.md", "title": "Migrating to 0.2.0" }
+      ]
+    }
+  ],
+  "releases": [
+    { "route": "/releases/0.2.0", "source": "releases/0.2.0.md", "version": "0.2.0", "state": "unreleased" },
+    { "route": "/releases/0.1.29", "source": "releases/0.1.29.md", "version": "0.1.29" },
+    { "route": "/releases/0.1.28", "source": "releases/0.1.28.md", "version": "0.1.28" },
+    { "route": "/releases/0.1.27", "source": "releases/0.1.27.md", "version": "0.1.27" },
+    { "route": "/releases/0.1.26", "source": "releases/0.1.26.md", "version": "0.1.26" },
+    { "route": "/releases/0.1.25", "source": "releases/0.1.25.md", "version": "0.1.25" },
+    { "route": "/releases/0.1.24", "source": "releases/0.1.24.md", "version": "0.1.24" }
+  ]
+}

package/docs/generators.md

@@ -0,0 +1,149 @@
+# Project Generators
+
+BCP Framework `0.1.29` adds project generators for common file-based application scaffolds.
+
+## Commands
+
+```bash
+bcp generate page dashboard/users
+bcp generate api users
+bcp generate middleware
+bcp generate migration create_users
+```
+
+On Windows, direct project-local execution can use the collision-free CLI alias:
+
+```powershell
+npm exec -- bcp-framework generate page dashboard/users
+```
+
+## Page generator
+
+```bash
+bcp generate page dashboard/users
+```
+
+creates:
+
+```text
+app/
+└─ dashboard/
+   └─ users/
+      └─ page.tsx
+```
+
+The generated page exports a valid default React component.
+
+Dynamic and grouped route segments are accepted when they match BCP route naming rules:
+
+```bash
+bcp generate page users/[id]
+bcp generate page docs/[...slug]
+bcp generate page catalog/[[...slug]]
+bcp generate page "(admin)/settings"
+```
+
+The generator rejects `.` / `..`, traversal attempts and invalid route characters.
+
+## API route generator
+
+```bash
+bcp generate api users
+```
+
+creates:
+
+```text
+app/
+└─ api/
+   └─ users/
+      └─ route.ts
+```
+
+The generated API route contains a minimal `GET()` handler returning JSON.
+
+Both of these are equivalent:
+
+```bash
+bcp generate api users
+bcp generate api api/users
+```
+
+## Middleware generator
+
+```bash
+bcp generate middleware
+```
+
+creates a project-root `middleware.ts` using Middleware System v2:
+
+```ts
+import type {
+    MiddlewarePipelineHandler,
+} from "bcp/middleware";
+
+export const middleware:
+    MiddlewarePipelineHandler =
+    async (
+        _request,
+        next
+    ) => {
+        return next();
+    };
+```
+
+## Migration generator
+
+```bash
+bcp generate migration create_users
+```
+
+reuses the database migration generator and creates a timestamped migration under `migrations/`.
+
+It is equivalent to:
+
+```bash
+bcp db create create_users
+```
+
+The generator intentionally reuses the existing migration implementation so migration naming and file format have one source of truth.
+
+## Existing files and `--force`
+
+Page, API and middleware generators refuse to replace existing files by default:
+
+```text
+BCP Generate: ... already exists. Pass --force to replace it.
+```
+
+Explicit replacement:
+
+```bash
+bcp generate page dashboard/users --force
+```
+
+Use `--force` carefully because it replaces the scaffold target file rather than merging source code.
+
+## Project root
+
+Generators use the same project-root resolution as other BCP CLI commands.
+
+```bash
+bcp generate page users --root ./my-app
+```
+
+## Recommended workflow
+
+```text
+create-bcp-app
+    ↓
+bcp generate page / api / middleware / migration
+    ↓
+bcp routes
+    ↓
+bcp doctor
+    ↓
+npm run typecheck
+```
+
+After generating page/API files, `bcp routes` can confirm the discovered route paths.