@chidchanun/bcp 0.2.1 → 0.2.3

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.3",
   "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"
       ]
     },
     {
@@ -73,7 +74,7 @@
       "source": "packages/client/src/database.ts",
       "environment": "server",
       "route": "/docs/api-reference#bcp-database",
-      "summary": "Database pool, prepared query/execute helpers and transaction primitives.",
+      "summary": "Provider-neutral MySQL, PostgreSQL and SQLite query, transaction, lifecycle and migration primitives.",
       "guides": [
         "/docs/database",
         "/docs/database-migrations"

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`
 
@@ -120,16 +130,35 @@ Related guide: [Error Handling](error-handling.md).
 
 ## `bcp/database`
 
-Server-only database primitives.
+Server-only Database Platform v2 APIs.
 
 ```ts
 import {
     createDatabase,
     db,
+    resolveDatabaseOptions,
+    type DatabaseAdapter,
+    type DatabaseAdapterFactory,
+    type DatabaseConnectionOptions,
+    type DatabaseDriver,
+    type DatabaseOptions,
+    type DatabaseParameters,
+    type ResolvedDatabaseOptions,
+    type TransactionDatabase,
 } from "bcp/database";
 ```
 
-Use the public database helpers instead of importing framework-internal pool/runtime modules.
+Built-in SQL providers are:
+
+```text
+mysql
+postgresql
+sqlite
+```
+
+`BcpDatabase` instances expose lazy query/execute/transaction operations plus explicit `connect()`, `disconnect()` and backward-compatible `close()` lifecycle methods.
+
+Use the public database helpers and adapter types instead of importing framework-internal provider/pool runtime modules.
 
 Related guides: [Database](database.md), [Database Migrations](database-migrations.md).
 

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/database-migrations.md

@@ -1,14 +1,33 @@
 # Database Migrations
 
-BCP Framework `0.1.15` adds MySQL migration commands to the `bcp` CLI.
+BCP `0.2.3` extends framework-managed SQL migrations across MySQL, PostgreSQL and SQLite.
 
-## Requirements
+## Supported providers
 
-Database migrations currently use the MySQL adapter from `bcp/database`.
+Migration bookkeeping uses the same provider selection as `bcp/database`:
 
-Configure the same environment variables used by your application:
+```text
+mysql
+postgresql
+sqlite
+```
+
+Install the optional driver used by the application:
+
+```bash
+npm install mysql2
+npm install pg
+npm install better-sqlite3
+```
+
+Only one driver is required when the project uses one database provider.
+
+## Provider configuration
+
+MySQL:
 
 ```env
+DB_DRIVER=mysql
 DB_HOST=localhost
 DB_PORT=3306
 DB_USER=root
@@ -16,7 +35,20 @@ DB_PASSWORD=
 DB_NAME=bcp_app
 ```
 
-A project using migrations must have `mysql2` installed. Applications created with the MySQL preset already include it.
+PostgreSQL:
+
+```env
+DATABASE_URL=postgresql://postgres:password@localhost:5432/bcp_app
+```
+
+SQLite:
+
+```env
+DB_DRIVER=sqlite
+DATABASE_URL=./data/bcp.sqlite
+```
+
+Database commands load the development environment before connecting, so migration commands and `bcp dev` use the same provider selection.
 
 ## Create a migration
 
@@ -24,14 +56,14 @@ A project using migrations must have `mysql2` installed. Applications created wi
 bcp db create create_users
 ```
 
-BCP creates an ordered TypeScript file in `migrations/`:
+BCP creates an ordered TypeScript file:
 
 ```text
 migrations/
-  20260827040506_create_users.ts
+  20260829090000_create_users.ts
 ```
 
-A generated migration exports `up()` and `down()`:
+Generated migrations export `up()` and `down()`:
 
 ```ts
 import type {
@@ -43,9 +75,9 @@ export async function up(
 ): Promise<void> {
     await db.execute(`
         CREATE TABLE users (
-            id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+            id INTEGER PRIMARY KEY,
             email VARCHAR(255) NOT NULL UNIQUE
-        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
+        )
     `);
 }
 
@@ -58,7 +90,24 @@ export async function down(
 }
 ```
 
-Migration filenames use a UTC timestamp prefix so migrations have a stable execution order.
+Migration filenames use a UTC timestamp prefix for stable execution order.
+
+## SQL dialect responsibility
+
+BCP keeps its own `_bcp_migrations` bookkeeping provider-aware, but it does not translate application migration SQL.
+
+This means migrations should either:
+
+- use SQL supported by every database target used by the application, or
+- intentionally target one provider and use that provider's SQL syntax.
+
+Parameter placeholders also follow the active provider:
+
+```text
+MySQL       ?
+SQLite      ?
+PostgreSQL  $1, $2, ...
+```
 
 ## Run pending migrations
 
@@ -66,9 +115,15 @@ Migration filenames use a UTC timestamp prefix so migrations have a stable execu
 bcp db migrate
 ```
 
-BCP creates the internal `_bcp_migrations` table when needed, detects files that have not been applied, and runs all pending migrations in filename order.
+BCP creates `_bcp_migrations` with provider-specific DDL, detects pending migration files, and executes them in filename order.
+
+All migrations applied by one command share the same batch number. Each migration runs inside its own transaction and its bookkeeping record is written in that same transaction.
 
-All migrations applied by one `bcp db migrate` command share the same batch number. Each individual migration runs inside its own database transaction. The migration record is inserted in the same transaction as `up()`.
+Provider-specific bookkeeping includes:
+
+- MySQL `AUTO_INCREMENT`,
+- PostgreSQL `BIGSERIAL`,
+- SQLite `INTEGER PRIMARY KEY AUTOINCREMENT`.
 
 ## Check status
 
@@ -84,22 +139,27 @@ The command reports applied and pending migration files together with the batch
 bcp db rollback
 ```
 
-Rollback reverses only the latest migration batch. Migrations in that batch run from newest to oldest, and each `down()` runs in a transaction together with removal of its migration record.
+Rollback reverses only the latest migration batch. Migrations run from newest to oldest and each `down()` executes in a transaction together with deletion of its migration record.
 
 BCP refuses to roll back an applied migration when its migration file is missing.
 
 ## Project root
 
-All database commands support the normal BCP project-root option:
+All database commands support the normal project-root option:
 
 ```bash
 bcp db status --root ./apps/admin
 ```
 
-## Environment files
+## Database Platform v2 behavior
 
-Database commands load the BCP development environment files before connecting, so the same local database settings used by `bcp dev` can be reused by migration commands.
+`0.2.3` keeps migration commands consistent across the built-in SQL providers:
 
-## Current scope
+```text
+bcp db create
+bcp db migrate
+bcp db status
+bcp db rollback
+```
 
-`0.1.15` migration execution supports MySQL. PostgreSQL, SQLite and MongoDB presets remain available to `create-bcp-app`, but framework-managed migrations for those adapters are planned for later releases.
+The command names and migration file contract stay the same regardless of whether the application uses MySQL, PostgreSQL or SQLite.