@chidchanun/bcp 0.2.0 → 0.2.2

package/README.md

@@ -2,38 +2,27 @@
 
 BCP Framework is a React full-stack framework for file-based routing, SSR, SPA navigation, server data loading, guarded application flows, API routes, authentication, database access, validation, uploads, storage and standalone Node.js production deployment.
 
-> **Development target:** `0.2.0 — Framework Platform`
+> **Development target:** `0.2.2 — Configuration & Environment v2`
 >
-> `0.2.0` establishes the first explicit platform baseline for BCP. It remains an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.2` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
 
-## Platform baseline — 0.2.0
+## 0.2 platform
 
-BCP `0.2.0` consolidates the capabilities built across the `0.1.x` series into a documented and testable platform contract.
+`0.2.0` established the Framework Platform baseline, `0.2.1` added the Documentation Platform, and `0.2.2` adds typed application environment validation and configuration diagnostics without intentionally removing public application entrypoints.
 
-New platform sources:
+Machine-readable platform contracts:
 
 ```text
 docs/platform-manifest.json
-  -> version, runtime target, public entrypoints and capability metadata
+  -> runtime target, capabilities and compatibility
 
 docs/docs-web-manifest.json
-  -> docs-web sections, routes, Markdown sources and releases
+  -> documentation navigation, routes and releases
 
-docs/platform-contract.md
-  -> public platform/compatibility contract
-
-docs/migration-0.2.md
-  -> application upgrade guide
+docs/api-manifest.json
+  -> public package entrypoints and guide ownership
 ```
 
-The package release pipeline now verifies the platform contract against the prepared npm artifact so accidental public-export/version drift fails package validation.
-
-Read more:
-
-- [Framework Platform Contract](docs/platform-contract.md)
-- [Migrating to 0.2.0](docs/migration-0.2.md)
-- [Platform Manifest](docs/platform-manifest.json)
-
 ## Current capabilities
 
 | Area | Capability |
@@ -45,16 +34,17 @@ Read more:
 | Authorization | `guard.ts`, `requireAuth()`, `requireRole()` |
 | Authentication | JWT cookie sessions and auth helpers |
 | Middleware | Middleware System v2 with onion execution |
-| Validation | Typed validation helpers and structured validation errors |
+| Validation | Typed validators and structured validation errors |
 | Error handling | HTTP error helpers and consistent error responses |
 | Database | MySQL helpers, transactions and migrations |
 | Logging | Structured logger, request logger and request IDs |
 | Uploads | Buffered multipart helpers and production multipart streaming |
 | Storage | Local + S3-compatible storage, streaming, list/copy/move, metadata, bulk delete and signed URLs |
 | Caching | Response cache and revalidation primitives |
+| Configuration | Typed `bcp.config.*`, optional `bcp.environment.*`, startup diagnostics and `bcp config check` |
 | Developer tools | Generators, Doctor/Inspect v2, updater, route inspection and project metadata |
 | Production | Standalone Node.js build, hardening gateway, graceful shutdown, trusted proxy controls and HTTP timeouts |
-| Documentation | Markdown source + machine-readable docs-web/platform manifests |
+| Documentation | Manifest-driven docs navigation, platform metadata and public API reference |
 
 ## Requirements
 
@@ -62,7 +52,7 @@ Read more:
 - React `19`
 - npm
 
-Database framework primitives currently target MySQL. `create-bcp-app` can also scaffold PostgreSQL, SQLite and MongoDB application helpers.
+Database framework primitives currently target MySQL.
 
 ## Quick start
 
@@ -82,45 +72,161 @@ Generated projects normally keep one framework dependency key:
 }
 ```
 
-Do not install both `bcp` and a second direct `@chidchanun/bcp` dependency in the same application; duplicate framework copies can create separate React/framework contexts.
+Do not install both `bcp` and a second direct `@chidchanun/bcp` dependency in the same application.
 
-## Application model
+## Configuration
+
+Framework configuration stays in one of:
 
 ```text
-Browser
-  ↓
-Security / middleware / cache
-  ↓
-Route guard
-  ↓
-Loader / action / API route
-  ↓
-React SSR
-  ↓
-Hydration / SPA navigation
+bcp.config.ts
+bcp.config.mts
+bcp.config.js
+bcp.config.mjs
 ```
 
-Typical route structure:
+Example:
+
+```ts
+import {
+    defineConfig,
+} from "bcp/config";
+
+export default defineConfig({
+    server: {
+        port: 3000,
+        hostname: "0.0.0.0",
+    },
+    build: {
+        minify: true,
+        sourceMaps: false,
+    },
+    security: {
+        poweredByHeader: false,
+    },
+});
+```
+
+Configuration precedence remains:
 
 ```text
-app/
-├─ layout.tsx
-├─ page.tsx
-├─ dashboard/
-│  ├─ guard.ts
-│  └─ users/
-│     └─ [id]/
-│        ├─ loader.ts
-│        ├─ actions.ts
-│        └─ page.tsx
-└─ api/
-   └─ upload/
-      └─ route.ts
+CLI override
+    ↓
+BCP_* environment
+    ↓
+bcp.config.*
+    ↓
+framework defaults
+```
+
+Read more: [Configuration](docs/configuration.md)
+
+## Environment Validation — 0.2.2
+
+Application-specific variables can be declared in an optional environment schema:
+
+```text
+bcp.environment.ts
+```
+
+Example:
+
+```ts
+import {
+    defineEnvironment,
+} from "bcp/config";
+
+export default defineEnvironment({
+    DB_HOST: {
+        type: "string",
+        required: true,
+    },
+
+    DB_PORT: {
+        type: "number",
+        default: 3306,
+        min: 1,
+        max: 65535,
+    },
+
+    SESSION_SECRET: {
+        type: "string",
+        required: true,
+        secret: true,
+        minLength: 32,
+    },
+
+    FEATURE_ENABLED: {
+        type: "boolean",
+        default: false,
+    },
+
+    BCP_PUBLIC_API_URL: {
+        type: "url",
+        required: true,
+    },
+});
+```
+
+Supported types:
+
+```text
+string
+number
+boolean
+url
+```
+
+Validate the current project:
+
+```bash
+bcp config check
+```
+
+JSON diagnostics:
+
+```bash
+bcp config check --json
+```
+
+On Windows, where Microsoft SQL Server may provide another `bcp.exe`, prefer:
+
+```powershell
+npm exec -- bcp-framework config check
+npm exec -- bcp-framework config check --json
 ```
 
+`bcp dev` and `bcp build` also validate `bcp.environment.*` before startup/build. Invalid required values fail early.
+
+The development supervisor watches:
+
+```text
+.env*
+bcp.config.*
+bcp.environment.*
+```
+
+and restarts the worker when one of those files changes.
+
+### Secret safety
+
+Variables beginning with `BCP_PUBLIC_` can be embedded into browser bundles.
+
+A variable marked:
+
+```ts
+secret: true
+```
+
+must not use `BCP_PUBLIC_`. BCP reports this as a configuration error.
+
+`secret: true` is tooling metadata; it does not encrypt environment values.
+
+Read more: [Environment Validation](docs/environment-validation.md)
+
 ## Public entrypoints
 
-The `0.2.0` platform contract recognizes these application entrypoints:
+The current `0.2.x` platform contract recognizes:
 
 ```text
 bcp
@@ -136,9 +242,13 @@ bcp/server-only
 bcp/middleware
 ```
 
-Application code should use public entrypoints rather than importing internal framework files under `packages/`.
+Application code should use public entrypoints instead of importing framework internals under `packages/`.
 
-The authoritative machine-readable list is in [docs/platform-manifest.json](docs/platform-manifest.json).
+See:
+
+- [API Reference](docs/api-reference.md)
+- [Platform Manifest](docs/platform-manifest.json)
+- [API Manifest](docs/api-manifest.json)
 
 ## CLI
 
@@ -150,6 +260,7 @@ bcp build
 bcp start
 bcp routes
 bcp update
+bcp config check
 bcp doctor
 bcp inspect
 bcp version
@@ -175,124 +286,48 @@ bcp generate migration create_users
 
 Page/API/middleware generators require `--force` before replacing an existing scaffold target.
 
-On Windows, Microsoft SQL Server may provide another `bcp.exe`. For direct PowerShell usage prefer the collision-free project-local alias:
-
-```powershell
-npm exec -- bcp-framework doctor
-npm exec -- bcp-framework inspect
-npm exec -- bcp-framework routes
-npm exec -- bcp-framework generate page dashboard/users
-```
-
-Inside npm scripts, `bcp` remains safe because npm prepends the project `node_modules/.bin` directory to `PATH`.
-
-## Routing, loaders, guards and actions
-
-BCP discovers pages from `app/**/page.tsx` and API handlers from `app/**/route.ts`.
-
-```text
-app/page.tsx                     /
-app/users/[id]/page.tsx          /users/:id
-app/docs/[...slug]/page.tsx      /docs/*
-app/catalog/[[...slug]]/page.tsx /catalog and /catalog/*
-app/(admin)/settings/page.tsx    /settings
-app/api/users/route.ts           /api/users
-```
-
-Route-owned server features stay colocated:
-
-```text
-page.tsx
-loader.ts
-guard.ts
-actions.ts
-```
-
-Guides:
-
-- [Routing](docs/routing.md)
-- [Server Data Loaders](docs/server-data-loaders.md)
-- [Route Guards](docs/route-guards.md)
-- [Form Actions](docs/form-actions.md)
-
-## Authentication and server APIs
-
-```ts
-import {
-    auth,
-    requireAuth,
-    requireRole,
-} from "bcp/auth";
-
-import {
-    cookies,
-    headers,
-    requestId,
-    requestMethod,
-    requestUrl,
-} from "bcp/server";
-```
-
-Guides:
-
-- [Authentication](docs/authentication.md)
-- [JWT Sessions](docs/session-auth.md)
-- [Server Request APIs](docs/server-request-apis.md)
-
-## Database
-
-```ts
-import {
-    db,
-} from "bcp/database";
-```
-
-BCP's database layer includes lazy MySQL pool creation, query/execute helpers, transactions and migrations.
-
-Guides:
-
-- [Database](docs/database.md)
-- [Database Migrations](docs/database-migrations.md)
-
-## Storage and uploads
-
-`create-bcp-app` can scaffold:
+## Application model
 
 ```text
-None
-Local Server
-Amazon S3
-Cloudflare R2
+Browser
+  ↓
+Security / middleware / cache
+  ↓
+Route guard
+  ↓
+Loader / action / API route
+  ↓
+React SSR
+  ↓
+Hydration / SPA navigation
 ```
 
-BCP's storage API supports local and S3-compatible storage, streaming reads/writes, ranges, object listing, copy/move, portable metadata, bulk deletion and S3 signed URLs.
-
-Local Server projects keep a visible scaffold:
+Typical route structure:
 
 ```text
-storage/
-├─ .gitkeep
-└─ README.md
+app/
+├─ layout.tsx
+├─ page.tsx
+├─ dashboard/
+│  ├─ guard.ts
+│  └─ users/
+│     └─ [id]/
+│        ├─ loader.ts
+│        ├─ actions.ts
+│        └─ page.tsx
+└─ api/
+   └─ upload/
+      └─ route.ts
 ```
 
-Runtime objects remain ignored by Git.
-
-Guides:
-
-- [File Upload](docs/file-upload.md)
-- [Storage & File Delivery](docs/storage.md)
-- [Storage Ecosystem](docs/storage-ecosystem.md)
-- [S3-Compatible Storage](docs/s3-storage.md)
-
 ## Production build
 
-Build:
-
 ```bash
 npm run build
+npm run start
 ```
 
-Output:
+Standalone output:
 
 ```text
 .bcp-framework/build/
@@ -302,99 +337,37 @@ Output:
    └─ server.mjs
 ```
 
-Run:
-
-```bash
-npm run start
-```
-
-The `0.2.0` platform build target is explicitly:
+The current production target remains:
 
 ```text
 standalone-node
 ```
 
-Native `.exe`, desktop and mobile compilation are not part of the `0.2.0` platform contract.
+Native `.exe`, desktop and mobile compilation remain later roadmap work.
 
-Production hardening supports:
-
-```dotenv
-BCP_REQUEST_TIMEOUT_MS=120000
-BCP_HEADERS_TIMEOUT_MS=66000
-BCP_KEEP_ALIVE_TIMEOUT_MS=65000
-BCP_SHUTDOWN_TIMEOUT_MS=10000
-BCP_TRUST_PROXY=false
-```
-
-Enable trusted proxy mode only when untrusted clients cannot bypass the trusted reverse proxy/load balancer.
+Production hardening includes configurable request/header/keep-alive/shutdown timeouts, trusted-proxy handling and graceful `SIGTERM` / `SIGINT` shutdown.
 
 Read more: [Production Hardening](docs/production-hardening.md)
 
-## Doctor / Inspect / project metadata
-
-Project diagnostics:
-
-```powershell
-npm exec -- bcp-framework doctor
-npm exec -- bcp-framework inspect --json
-```
-
-Doctor/Inspect v2 can report lockfile/package-manager state, duplicate framework declarations, standalone build presence, Docker/project diagnostics, storage provider and production-hardening configuration.
-
-Projects created by recent `create-bcp-app` versions include non-secret scaffold metadata:
-
-```text
-bcp.project.json
-```
-
-Credentials, database passwords, access keys, JWT/session secrets and tokens must never be stored in that file.
-
-Guides:
-
-- [Developer Tools](docs/developer-tools.md)
-- [Project Metadata](docs/project-metadata.md)
-
-## Updating from 0.1.x
-
-`0.2.0` does not intentionally remove public entrypoints from the `0.1.29` baseline.
-
-Recommended upgrade flow after publication:
-
-```powershell
-npm exec -- bcp-framework doctor
-npm exec -- bcp-framework update --check
-npm exec -- bcp-framework update 0.2.0
-npm run typecheck
-npm run build
-```
-
-Do not reuse a standalone `.bcp-framework/build` produced by an older framework version; rebuild after upgrading.
-
-Read more: [Migrating to 0.2.0](docs/migration-0.2.md)
-
-## Documentation source and bcp-docs-web
+## Documentation Platform
 
 The framework repository is the documentation source of truth.
 
-`bcp-docs-web` should consume:
+`bcp-docs-web` consumes:
 
 ```text
 docs/docs-web-manifest.json
-  -> navigation, routes, Markdown sources and release routes
-
 docs/platform-manifest.json
-  -> version, runtime target, public entrypoints and capabilities
+docs/api-manifest.json
 ```
 
-Markdown under `docs/` remains the authored content source.
+The manifests provide navigation order, routes, Markdown sources, version/release state, public entrypoints and API guide ownership.
 
-Start here:
+Read more:
 
 - [Documentation Source Map](docs/README.md)
-- [Docs-Web Manifest](docs/docs-web-manifest.json)
-- [Platform Manifest](docs/platform-manifest.json)
-- [Framework Platform Contract](docs/platform-contract.md)
-- [Migration Guide](docs/migration-0.2.md)
+- [Documentation Platform](docs/documentation-platform.md)
+- [Environment Validation](docs/environment-validation.md)
 
 ## Release validation
 
@@ -410,31 +383,41 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`0.2.0` adds a platform-contract package smoke check that verifies the prepared npm artifact's public exports, executable aliases, Node baseline, docs metadata and framework/create-app version parity.
+`0.2.2` adds Configuration & Environment v2 unit/package checks covering schema parsing, project schema loading, diagnostics, CLI parsing, public `bcp/config` exports and packed-package files.
 
-Do not tag or publish a release until the final release commit passes the complete RC sequence.
+Do not tag or publish until the final release commit passes the complete RC sequence.
 
 ## Release history
 
 | Version | Milestone |
 | --- | --- |
-| `0.1.20` | Hydration line-ending stabilization |
-| `0.1.21` | Hydration semantic parity |
-| `0.1.22` | Developer tools and diagnostics |
-| `0.1.23` | Logging and observability |
 | `0.1.24` | File Upload Foundation |
 | `0.1.25` | Storage Adapters and File Delivery |
 | `0.1.26` | S3-Compatible Storage and Production Streaming |
 | `0.1.27` | Storage Ecosystem |
 | `0.1.28` | Production Hardening |
 | `0.1.29` | Developer Experience |
-| `0.2.0` | Framework Platform baseline |
+| `0.2.0` | Framework Platform |
+| `0.2.1` | Documentation Platform |
+| `0.2.2` | Configuration & Environment v2 |
+
+## Roadmap
+
+Next planned milestone:
+
+```text
+0.2.3 — Database Platform v2
+```
 
-## Next direction
+Planned focus:
 
-After the `0.2.0` platform baseline is validated and released, later `0.2.x` work can add broader build/deployment targets and higher-level platform features without changing the existing standalone Node.js contract by accident.
+- database adapter contract,
+- PostgreSQL support,
+- SQLite support,
+- connection lifecycle improvements,
+- migration consistency across providers.
 
-Native executable/desktop/mobile packaging remains future roadmap work, not a `0.2.0` guarantee.
+Application packaging remains later `0.2.x` roadmap work.
 
 ## License