@chidchanun/bcp 0.2.1 → 0.2.3

package/README.md

@@ -2,36 +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.1 — Documentation Platform`
+> **Development target:** `0.2.3 — Database Platform v2`
 >
-> `0.2.1` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.3` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
 
 ## 0.2 platform
 
-`0.2.0` established the Framework Platform baseline. `0.2.1` builds a machine-readable Documentation Platform on top of that baseline without intentionally removing application runtime public entrypoints.
+`0.2.0` established the Framework Platform baseline, `0.2.1` added the Documentation Platform, `0.2.2` added Configuration & Environment v2, and `0.2.3` adds a provider-neutral SQL database platform with MySQL, PostgreSQL and SQLite support without intentionally removing public application entrypoints.
 
-The authoritative platform/documentation contracts are:
+Machine-readable platform contracts:
 
 ```text
 docs/platform-manifest.json
-  -> runtime target, public entrypoints, capabilities and compatibility
+  -> runtime target, capabilities and compatibility
 
 docs/docs-web-manifest.json
-  -> docs sections, routes, Markdown sources and releases
+  -> documentation navigation, routes and releases
 
 docs/api-manifest.json
-  -> public package entrypoints, source ownership and guide routes
+  -> public package entrypoints and guide ownership
 ```
 
-Authored documentation remains under `docs/*.md`.
-
-Read more:
-
-- [Framework Platform Contract](docs/platform-contract.md)
-- [Documentation Platform](docs/documentation-platform.md)
-- [API Reference](docs/api-reference.md)
-- [Migrating to 0.2.x](docs/migration-0.2.md)
-
 ## Current capabilities
 
 | Area | Capability |
@@ -45,14 +36,15 @@ Read more:
 | Middleware | Middleware System v2 with onion execution |
 | Validation | Typed validators and structured validation errors |
 | Error handling | HTTP error helpers and consistent error responses |
-| Database | MySQL helpers, transactions and migrations |
+| Database | Provider-neutral MySQL, PostgreSQL and SQLite adapters, transactions, lifecycle 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 | Manifest-driven docs navigation, platform metadata and public API entrypoint reference |
+| Documentation | Manifest-driven docs navigation, platform metadata and public API reference |
 
 ## Requirements
 
@@ -60,7 +52,13 @@ Read more:
 - React `19`
 - npm
 
-Database framework primitives currently target MySQL. `create-bcp-app` can also scaffold PostgreSQL, SQLite and MongoDB application helpers.
+Database drivers are optional and provider-specific:
+
+```text
+MySQL       mysql2
+PostgreSQL  pg
+SQLite      better-sqlite3
+```
 
 ## Quick start
 
@@ -80,45 +78,208 @@ 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)
+
+## Database Platform v2 — 0.2.3
+
+Application code uses the same server-only entrypoint across supported SQL providers:
+
+```ts
+import {
+    db,
+    createDatabase,
+} from "bcp/database";
+```
+
+Built-in providers:
+
+```text
+mysql
+postgresql
+sqlite
+```
+
+Connections remain lazy, while explicit lifecycle control is available when needed:
+
+```ts
+await db.connect();
+
+// application work
+
+await db.disconnect();
+```
+
+`db.close()` remains available for backward-compatible shutdown handling.
+
+Database migrations use the same CLI across providers:
+
+```bash
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
 ```
 
+BCP makes its internal migration bookkeeping provider-aware. Application SQL itself is not automatically translated between SQL dialects.
+
+Read more:
+
+- [Database](docs/database.md)
+- [Database Migrations](docs/database-migrations.md)
+
 ## Public entrypoints
 
-The `0.2.x` platform contract recognizes:
+The current `0.2.x` platform contract recognizes:
 
 ```text
 bcp
@@ -134,15 +295,14 @@ bcp/server-only
 bcp/middleware
 ```
 
-Application code should use these public package entrypoints rather than importing internal framework files under `packages/`.
+Application code should use public entrypoints instead of importing framework internals under `packages/`.
 
-The public list is validated in both:
+See:
 
+- [API Reference](docs/api-reference.md)
 - [Platform Manifest](docs/platform-manifest.json)
 - [API Manifest](docs/api-manifest.json)
 
-See [API Reference](docs/api-reference.md) for ownership and related guides.
-
 ## CLI
 
 Core commands:
@@ -153,6 +313,7 @@ bcp build
 bcp start
 bcp routes
 bcp update
+bcp config check
 bcp doctor
 bcp inspect
 bcp version
@@ -178,112 +339,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 project-local collision-free 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
-```
-
-## 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:
+## Application model
 
 ```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";
+Browser
+  ↓
+Security / middleware / cache
+  ↓
+Route guard
+  ↓
+Loader / action / API route
+  ↓
+React SSR
+  ↓
+Hydration / SPA navigation
 ```
 
-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:
+Typical route structure:
 
 ```text
-None
-Local Server
-Amazon S3
-Cloudflare R2
+app/
+├─ layout.tsx
+├─ page.tsx
+├─ dashboard/
+│  ├─ guard.ts
+│  └─ users/
+│     └─ [id]/
+│        ├─ loader.ts
+│        ├─ actions.ts
+│        └─ page.tsx
+└─ api/
+   └─ upload/
+      └─ route.ts
 ```
 
-BCP storage supports local and S3-compatible adapters, streaming reads/writes, ranges, object listing, copy/move, portable metadata, bulk deletion and S3 signed URLs.
-
-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/
@@ -293,81 +390,37 @@ Output:
    └─ server.mjs
 ```
 
-Run:
-
-```bash
-npm run start
-```
-
-The `0.2.x` production target remains:
+The current production target remains:
 
 ```text
 standalone-node
 ```
 
-Native `.exe`, desktop and mobile compilation are future roadmap work and are not part of the current platform contract.
+Native `.exe`, desktop and mobile compilation remain later roadmap work.
 
-Production hardening supports configurable request/header/keep-alive/shutdown timeouts, trusted-proxy handling and `SIGTERM` / `SIGINT` graceful shutdown.
+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)
 
-## Documentation Platform — 0.2.1
+## Documentation Platform
 
-`0.2.1` makes the framework repository directly consumable by `bcp-docs-web`.
+The framework repository is the documentation source of truth.
 
-Recommended website flow:
+`bcp-docs-web` consumes:
 
 ```text
-selected framework ref
-        ↓
 docs/docs-web-manifest.json
 docs/platform-manifest.json
 docs/api-manifest.json
-        ↓
-validate version + release state + public entrypoints
-        ↓
-load referenced Markdown
-        ↓
-sync CMS/search/navigation
-        ↓
-render bcp-docs-web
 ```
 
-`bcp-docs-web` should not maintain a second hard-coded framework page list.
-
-The manifests provide:
-
-```text
-sidebar/category order
-website routes
-Markdown sources
-version + release state
-release routes
-public package entrypoints
-API guide ownership
-```
-
-The docs sync may target a release ref for historical content:
-
-```powershell
-npm run docs:sync -- --ref=v0.2.0
-```
+The manifests provide navigation order, routes, Markdown sources, version/release state, public entrypoints and API guide ownership.
 
 Read more:
 
-- [Documentation Platform](docs/documentation-platform.md)
 - [Documentation Source Map](docs/README.md)
-- [Docs-Web Manifest](docs/docs-web-manifest.json)
-- [Platform Manifest](docs/platform-manifest.json)
-- [API Manifest](docs/api-manifest.json)
-
-## Updating from 0.1.x / 0.2.x
-
-`0.2.1` does not intentionally remove application public entrypoints from the `0.2.0` baseline.
-
-After upgrading, always rebuild the standalone artifact instead of reusing `.bcp-framework/build` from another framework version.
-
-Read more: [Migrating to 0.2.x](docs/migration-0.2.md)
+- [Documentation Platform](docs/documentation-platform.md)
+- [Environment Validation](docs/environment-validation.md)
 
 ## Release validation
 
@@ -383,9 +436,9 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`0.2.1` adds Documentation Platform unit/package checks that validate manifest version parity, docs source existence, API/public-entrypoint parity and prepared npm documentation artifacts.
+`0.2.3` adds Database Platform v2 unit/package checks covering the adapter contract, MySQL/PostgreSQL/SQLite provider resolution, explicit connection lifecycle, failed-initialization retry behavior and provider-specific migration bookkeeping.
 
-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
 
@@ -399,23 +452,14 @@ Do not tag or publish a release until the final release commit passes the comple
 | `0.1.29` | Developer Experience |
 | `0.2.0` | Framework Platform |
 | `0.2.1` | Documentation Platform |
+| `0.2.2` | Configuration & Environment v2 |
+| `0.2.3` | Database Platform v2 |
 
 ## Roadmap
 
-Next planned milestone:
-
-```text
-0.2.2 — Configuration & Environment v2
-```
-
-Focus:
-
-- typed production configuration improvements,
-- environment validation,
-- startup configuration diagnostics,
-- configuration schema/inspection tooling.
+`0.2.3 — Database Platform v2` completes the planned database adapter contract, PostgreSQL support, SQLite support, connection lifecycle improvements and migration consistency across the built-in SQL providers.
 
-Application packaging (`bcp package`, native executable experiments) remains later `0.2.x` roadmap work.
+The next planned `0.2.x` focus is application packaging. Native `.exe`, desktop and mobile compilation remain later roadmap work.
 
 ## License