@chidchanun/bcp 0.2.1 → 0.2.2

package/docs/README.md

@@ -2,11 +2,11 @@
 
 The `docs/` directory is the documentation source of truth for BCP Framework and is organized for **`bcp-docs-web`**.
 
-> **Documentation target:** BCP Framework `0.2.1`
+> **Documentation target:** BCP Framework `0.2.2`
 >
-> **Release state:** unreleased development target. Do not label `0.2.1` as published until RC validation, tagging and npm publication complete.
+> **Release state:** unreleased development target. Do not label `0.2.2` as published until RC validation, tagging and npm publication complete.
 
-## Documentation architecture — 0.2.1
+## Documentation architecture
 
 BCP uses three machine-readable documentation contracts:
 
@@ -41,20 +41,31 @@ manifest-driven sync
 
 Framework source and tests remain authoritative for runtime behavior.
 
-## Documentation Platform
+## 0.2.2 — Configuration & Environment v2
 
-`0.2.1` adds a versioned contract between the framework repository and the documentation website.
+`0.2.2` adds an optional typed application environment schema while preserving the established framework configuration precedence.
 
-New sources:
+New/updated documentation sources:
 
 | Source | Purpose |
 | --- | --- |
-| `api-manifest.json` | Public API entrypoint metadata |
-| `api-reference.md` | Human-readable public package entrypoint reference |
-| `documentation-platform.md` | Docs-web synchronization/versioning contract |
-| `releases/0.2.1.md` | Documentation Platform release notes |
+| `environment-validation.md` | `bcp.environment.*`, validation rules, CLI checks and secret/public boundaries |
+| `configuration.md` | Framework configuration precedence and diagnostics workflow |
+| `platform-manifest.json` | Declares typed environment/config diagnostics capabilities |
+| `api-manifest.json` | Maps `bcp/config` to configuration and environment guides |
+| `releases/0.2.2.md` | Configuration & Environment v2 release notes |
 
-The website should not maintain a second hard-coded list of framework pages when those pages exist in `docs-web-manifest.json`.
+Primary command:
+
+```bash
+bcp config check
+```
+
+JSON diagnostics:
+
+```bash
+bcp config check --json
+```
 
 ## Update rule
 
@@ -64,14 +75,14 @@ When framework behavior or public surface changes:
 2. Add/update regression tests.
 3. Update the matching Markdown guide.
 4. Update `platform-manifest.json` when runtime/public-entrypoint/capability metadata changes.
-5. Update `api-manifest.json` when public API entrypoint ownership changes.
+5. Update `api-manifest.json` when public API ownership/guide mapping changes.
 6. Update `docs-web-manifest.json` when website routes/navigation change.
 7. Update `docs/releases/<version>.md`.
 8. Change release state only after the release workflow reaches that state.
 
 ## Docs-web navigation
 
-`docs/docs-web-manifest.json` is the ordered navigation contract.
+`docs/docs-web-manifest.json` is the authoritative ordered navigation contract.
 
 Current sections:
 
@@ -88,46 +99,104 @@ API Reference
 Releases
 ```
 
-Important `0.2.1` routes:
+Important current routes:
 
 | Website route | Markdown source |
 | --- | --- |
+| `/docs/configuration` | `configuration.md` |
+| `/docs/environment-validation` | `environment-validation.md` |
 | `/docs/platform-contract` | `platform-contract.md` |
 | `/docs/documentation-platform` | `documentation-platform.md` |
 | `/docs/migration-0.2` | `migration-0.2.md` |
 | `/docs/api-reference` | `api-reference.md` |
-| `/releases/0.2.1` | `releases/0.2.1.md` |
+| `/releases/0.2.2` | `releases/0.2.2.md` |
 
 Every route/source pair is validated by unit tests.
 
+## Configuration source model
+
+Framework settings:
+
+```text
+bcp.config.ts
+bcp.config.mts
+bcp.config.js
+bcp.config.mjs
+```
+
+Application environment schema:
+
+```text
+bcp.environment.ts
+bcp.environment.mts
+bcp.environment.js
+bcp.environment.mjs
+```
+
+Only one file from each convention may exist at a time.
+
+The environment schema is optional. Existing applications without `bcp.environment.*` continue to use the previous environment-loading behavior.
+
+Configuration precedence remains:
+
+```text
+CLI override
+    ↓
+BCP_* environment
+    ↓
+bcp.config.*
+    ↓
+framework defaults
+```
+
+See [Environment Validation](environment-validation.md).
+
+## Environment security boundary
+
+`BCP_PUBLIC_*` values may be embedded into browser bundles. They must never contain credentials/private secrets.
+
+A variable declared with:
+
+```ts
+secret: true
+```
+
+must not use the `BCP_PUBLIC_` prefix. The configuration validator treats that combination as an error.
+
+`secret: true` is validation/tooling metadata and does not encrypt a value.
+
 ## Platform manifest
 
-`docs/platform-manifest.json` describes the supported framework baseline:
+`docs/platform-manifest.json` describes the supported framework baseline, including:
 
 ```text
-schema version
 framework version/release state
 Node/React/runtime baseline
 production build target
 public package entrypoints
 CLI command families
-capabilities
-storage-provider families
-previous baseline compatibility intent
+capability flags
+previous-baseline compatibility intent
 documentation contract files
 ```
 
-Supported production target remains:
+`0.2.2` declares the additional capabilities:
 
 ```text
-standalone-node
+typedEnvironmentSchema
+configurationDiagnostics
+configCheckCli
 ```
 
-Native executable, desktop and mobile compilation remain future roadmap work.
+The supported production target remains:
+
+```text
+standalone-node
+```
 
 ## API manifest
 
-`docs/api-manifest.json` describes the public package entrypoints that documentation tooling may present as supported API surfaces.
+`docs/api-manifest.json` describes the public package entrypoints documentation tooling may present as supported API surfaces.
 
 Current entrypoints:
 
@@ -145,24 +214,18 @@ bcp/server-only
 bcp/middleware
 ```
 
-Each API entry records:
+`bcp/config` owns both:
 
 ```text
-package
-source file
-environment boundary
-reference route
-summary
-related guide routes
+/docs/configuration
+/docs/environment-validation
 ```
 
-The API-manifest entrypoint set must match the public-entrypoint set in `platform-manifest.json` exactly.
-
-See [API Reference](api-reference.md).
+The API-manifest entrypoint set must match the platform public-entrypoint set exactly.
 
 ## bcp-docs-web synchronization
 
-The `bcp-docs-web` sync should load all three manifests first.
+The docs website sync loads the manifests before Markdown content:
 
 ```text
 selected framework ref
@@ -173,41 +236,19 @@ api-manifest.json
         ↓
 validate version/release/API parity
         ↓
-load only referenced Markdown
-        ↓
-rewrite internal Markdown links to website routes
+load referenced Markdown
         ↓
 synchronize CMS/search/navigation
 ```
 
-The matching docs-web implementation supports local framework source or a selected Git ref.
-
-Examples:
+Examples from the docs-web project:
 
 ```powershell
 npm run docs:sync -- --dry-run
 npm run docs:sync -- --publish-new
-npm run docs:sync -- --ref=v0.2.0
+npm run docs:sync -- --ref=v0.2.1
 ```
 
-Using a tag/ref is the foundation for historical/versioned documentation without manually copying current Markdown into another source tree.
-
-## Public API guide ownership
-
-| Entrypoint | Primary guides |
-| --- | --- |
-| `bcp` | `routing.md`, `server-data-loaders.md`, `route-guards.md`, `form-actions.md` |
-| `bcp/island` | `hydration.md` |
-| `bcp/cache` | `caching.md` |
-| `bcp/config` | `configuration.md` |
-| `bcp/validation` | `validation.md` |
-| `bcp/error` | `error-handling.md` |
-| `bcp/database` | `database.md`, `database-migrations.md` |
-| `bcp/auth` | `authentication.md`, `auth-route-guards.md`, `session-auth.md` |
-| `bcp/server` | `server-request-apis.md`, `file-upload.md`, `storage.md`, `storage-ecosystem.md`, `production-hardening.md` |
-| `bcp/server-only` | `application-modules.md` |
-| `bcp/middleware` | `middleware.md` |
-
 ## Source conventions
 
 - one H1 per Markdown page,
@@ -220,15 +261,9 @@ Using a tag/ref is the foundation for historical/versioned documentation without
 - no framework-internal module presented as public API,
 - no secrets/runtime `.env` values in public documentation metadata.
 
-## Search and previous/next
-
-Search should index Markdown content and headings. Manifest titles/categories/API summaries may be used as metadata.
-
-Sidebar and previous/next ordering should follow `docs-web-manifest.json` order so navigation surfaces cannot drift from each other.
-
 ## Release validation
 
-Before publishing `0.2.1`:
+Before publishing `0.2.2`:
 
 ```bash
 npm run typecheck
@@ -239,14 +274,17 @@ npm run test:e2e
 npm run rc:check
 ```
 
-Documentation Platform validation covers:
+Configuration & Environment v2 validation covers:
 
-- every Markdown source exists,
-- every docs/release route is unique,
-- package/platform/docs/API versions match,
-- API entrypoints match the platform public-entrypoint set,
-- API guide routes exist,
-- prepared npm packages contain the three manifests, API reference and Documentation Platform guide.
+- typed environment rules/defaults,
+- project `bcp.environment.*` loading,
+- public/secret safety boundary,
+- production diagnostics,
+- `bcp config check` CLI parsing,
+- dev schema watching,
+- public `bcp/config` exports,
+- prepared npm package files,
+- docs/platform/API version parity.
 
 The final release tag must point to the exact commit that passed the complete RC sequence.
 
@@ -272,12 +310,13 @@ release notes
 Planned next milestone:
 
 ```text
-0.2.2 — Configuration & Environment v2
+0.2.3 — Database Platform v2
 ```
 
 Focus:
 
-- typed production configuration improvements,
-- environment validation,
-- startup configuration diagnostics,
-- configuration schema/inspection tooling.
+- database adapter contract,
+- PostgreSQL support,
+- SQLite support,
+- connection lifecycle improvements,
+- provider-consistent migration workflows.

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -43,9 +43,10 @@
       "source": "packages/client/src/config.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-config",
-      "summary": "Typed BCP configuration definition, loading and resolution APIs.",
+      "summary": "Typed BCP configuration, environment-schema validation and configuration diagnostics APIs.",
       "guides": [
-        "/docs/configuration"
+        "/docs/configuration",
+        "/docs/environment-validation"
       ]
     },
     {

package/docs/api-reference.md

@@ -62,17 +62,27 @@ Related guide: [Caching](caching.md).
 
 ## `bcp/config`
 
-Typed configuration APIs.
+Typed framework configuration, application environment-schema validation and diagnostics APIs.
 
 ```ts
 import {
+    applyEnvironmentDefaults,
     defineConfig,
+    defineEnvironment,
+    diagnoseBcpConfiguration,
+    getEnvironmentSchemaFileNames,
+    loadBcpEnvironmentSchema,
     readResolvedBcpConfig,
     resolveBcpConfig,
+    validateEnvironment,
 } from "bcp/config";
 ```
 
-Related guide: [Configuration](configuration.md).
+Use `defineConfig()` for framework runtime/build settings and `defineEnvironment()` for the optional `bcp.environment.*` application-variable schema.
+
+`validateEnvironment()` returns parsed declared values and structured issues. `applyEnvironmentDefaults()` fills only missing environment keys and does not overwrite values already supplied by the environment/runtime.
+
+Related guides: [Configuration](configuration.md), [Environment Validation](environment-validation.md).
 
 ## `bcp/validation`
 

package/docs/configuration.md

@@ -92,6 +92,101 @@ BCP_EXPERIMENTAL_ISLANDS
 
 Application environment variables prefixed with `BCP_PUBLIC_` may be embedded into browser bundles. Other application variables remain server-side.
 
+## Configuration & Environment v2
+
+BCP `0.2.2` adds an optional application environment schema in one of:
+
+```text
+bcp.environment.ts
+bcp.environment.mts
+bcp.environment.js
+bcp.environment.mjs
+```
+
+The schema validates application-specific values after `.env` files are loaded.
+
+Example:
+
+```ts
+import {
+    defineEnvironment,
+} from "bcp/config";
+
+export default defineEnvironment({
+    DATABASE_URL: {
+        type: "string",
+        required: true,
+    },
+    SESSION_SECRET: {
+        type: "string",
+        required: true,
+        secret: true,
+        minLength: 32,
+    },
+    BCP_PUBLIC_API_URL: {
+        type: "url",
+        required: true,
+    },
+});
+```
+
+This schema is additive. Projects without `bcp.environment.*` continue to use the existing environment behavior.
+
+Read more: [Environment Validation](environment-validation.md)
+
+## Configuration check
+
+Validate the current project without starting the application:
+
+```bash
+bcp config check
+```
+
+JSON diagnostics:
+
+```bash
+bcp config check --json
+```
+
+Windows project-local form:
+
+```powershell
+npm exec -- bcp-framework config check
+```
+
+The check reports the selected config file, environment files, environment schema, resolved server/build settings and diagnostics. Raw environment values are not printed.
+
+For production-mode warnings in PowerShell:
+
+```powershell
+$env:NODE_ENV = "production"
+npm exec -- bcp-framework config check
+Remove-Item Env:NODE_ENV
+```
+
+## Startup diagnostics
+
+`bcp dev` and `bcp build` run the environment-schema diagnostics before the application starts/builds.
+
+Schema errors stop startup/build early. Production safety warnings do not fail the build by themselves.
+
+Examples of production warnings include:
+
+- source maps enabled,
+- powered-by header enabled,
+- Content-Security-Policy disabled,
+- trusted proxy mode enabled.
+
+Trusted proxy mode should only be enabled when untrusted clients cannot bypass the trusted proxy/load balancer.
+
 ## Config reload in development
 
-Changes to supported `.env*` files or `bcp.config.*` restart the development worker so the new resolved configuration is applied without restarting the parent CLI manually.
+Changes to these configuration sources restart the development worker automatically:
+
+```text
+.env*
+bcp.config.*
+bcp.environment.*
+```
+
+The parent development supervisor stays running while the worker reloads the new configuration/environment state.

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.1",
+  "versionTarget": "0.2.2",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -11,6 +11,7 @@
       "pages": [
         { "route": "/docs/getting-started", "source": "getting-started.md", "title": "Getting Started" },
         { "route": "/docs/configuration", "source": "configuration.md", "title": "Configuration" },
+        { "route": "/docs/environment-validation", "source": "environment-validation.md", "title": "Environment Validation" },
         { "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" },
@@ -103,7 +104,8 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.1", "source": "releases/0.2.1.md", "version": "0.2.1", "state": "unreleased" },
+    { "route": "/releases/0.2.2", "source": "releases/0.2.2.md", "version": "0.2.2", "state": "unreleased" },
+    { "route": "/releases/0.2.1", "source": "releases/0.2.1.md", "version": "0.2.1" },
     { "route": "/releases/0.2.0", "source": "releases/0.2.0.md", "version": "0.2.0" },
     { "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" },