@chidchanun/bcp 0.2.2 → 0.2.4

package/README.md

@@ -2,13 +2,13 @@
 
 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.2 — Configuration & Environment v2`
+> **Development target:** `0.2.4 — Application Packaging`
 >
-> `0.2.2` is an unreleased development target until local validation, RC checks, tagging and npm publication complete.
+> `0.2.4` 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` added the Documentation Platform, and `0.2.2` adds typed application environment validation and configuration diagnostics without intentionally removing public application entrypoints.
+`0.2.0` established the Framework Platform baseline, `0.2.1` added the Documentation Platform, `0.2.2` added Configuration & Environment v2, `0.2.3` added Database Platform v2, and `0.2.4` adds deployment-oriented application packaging without intentionally removing the existing public application model.
 
 Machine-readable platform contracts:
 
@@ -36,14 +36,14 @@ docs/api-manifest.json
 | 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 |
+| Production | Standalone Node.js build, application packaging, production dependency pruning, deployment manifests, Docker starter, hardening and graceful shutdown |
 | Documentation | Manifest-driven docs navigation, platform metadata and public API reference |
 
 ## Requirements
@@ -52,7 +52,13 @@ docs/api-manifest.json
 - React `19`
 - npm
 
-Database framework primitives currently target MySQL.
+Database drivers are optional and provider-specific:
+
+```text
+MySQL       mysql2
+PostgreSQL  pg
+SQLite      better-sqlite3
+```
 
 ## Quick start
 
@@ -74,7 +80,7 @@ Generated projects normally keep one framework dependency key:
 
 Do not install both `bcp` and a second direct `@chidchanun/bcp` dependency in the same application.
 
-## Configuration
+## Configuration & environment
 
 Framework configuration stays in one of:
 
@@ -85,29 +91,16 @@ bcp.config.js
 bcp.config.mjs
 ```
 
-Example:
+Application environment validation can be declared in:
 
-```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,
-    },
-});
+```text
+bcp.environment.ts
+bcp.environment.mts
+bcp.environment.js
+bcp.environment.mjs
 ```
 
-Configuration precedence remains:
+Configuration precedence is:
 
 ```text
 CLI override
@@ -119,110 +112,124 @@ bcp.config.*
 framework defaults
 ```
 
-Read more: [Configuration](docs/configuration.md)
+Validate configuration and declared environment values with:
 
-## Environment Validation — 0.2.2
+```bash
+bcp config check
+bcp config check --json
+```
 
-Application-specific variables can be declared in an optional environment schema:
+Variables beginning with `BCP_PUBLIC_` may be embedded in browser output. Never expose application secrets through public-prefixed variables.
 
-```text
-bcp.environment.ts
-```
+Read more:
 
-Example:
+- [Configuration](docs/configuration.md)
+- [Environment Validation](docs/environment-validation.md)
+
+## Database Platform v2 — 0.2.3
+
+Application code uses one server-only database entrypoint across supported SQL providers:
 
 ```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,
-    },
-});
+    db,
+    createDatabase,
+} from "bcp/database";
 ```
 
-Supported types:
+Built-in SQL providers:
 
 ```text
-string
-number
-boolean
-url
+mysql
+postgresql
+sqlite
 ```
 
-Validate the current project:
+Lifecycle control:
 
-```bash
-bcp config check
+```ts
+await db.connect();
+
+// application work
+
+await db.disconnect();
 ```
 
-JSON diagnostics:
+`db.close()` remains available for backward-compatible shutdown handling.
+
+Migration CLI:
 
 ```bash
-bcp config check --json
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
 ```
 
-On Windows, where Microsoft SQL Server may provide another `bcp.exe`, prefer:
+BCP makes framework migration bookkeeping provider-aware. Application migration SQL itself is not automatically translated between SQL dialects.
 
-```powershell
-npm exec -- bcp-framework config check
-npm exec -- bcp-framework config check --json
+Read more:
+
+- [Database](docs/database.md)
+- [Database Migrations](docs/database-migrations.md)
+
+## Application Packaging — 0.2.4
+
+Create a fresh production build and convert it into a deployment-oriented package:
+
+```bash
+bcp package
 ```
 
-`bcp dev` and `bcp build` also validate `bcp.environment.*` before startup/build. Invalid required values fail early.
+Framework-repository development can also run:
+
+```bash
+npm run package
+```
 
-The development supervisor watches:
+Output:
 
 ```text
-.env*
-bcp.config.*
-bcp.environment.*
+.bcp-framework/package/
+├─ client/
+├─ server/
+│  └─ server.mjs
+├─ public/                 # when present
+├─ manifest.json
+├─ package.json
+├─ package-lock.json       # when a safe npm v3 production lock can be derived
+├─ bcp.package.json
+├─ bcp.deployment.json
+├─ bcp.env.json
+├─ Dockerfile
+├─ .dockerignore
+└─ README.md
 ```
 
-and restarts the worker when one of those files changes.
+The package layer:
 
-### Secret safety
+- runs a fresh `bcp build` before packaging,
+- strips application `devDependencies` from the deployment package,
+- derives a production-only npm v3 lock graph when safe,
+- records `npm ci --omit=dev` when the production lock is available,
+- falls back explicitly to `npm install --omit=dev` when a safe lock cannot be produced,
+- writes deployment/runtime metadata,
+- records environment variable names without copying `.env` values,
+- creates SHA-256 file integrity metadata,
+- generates a Node 24 Alpine Docker starter.
 
-Variables beginning with `BCP_PUBLIC_` can be embedded into browser bundles.
+The current package target is:
 
-A variable marked:
-
-```ts
-secret: true
+```text
+standalone-node
 ```
 
-must not use `BCP_PUBLIC_`. BCP reports this as a configuration error.
+Native executable, desktop, Android and iOS packaging remain later roadmap work.
 
-`secret: true` is tooling metadata; it does not encrypt environment values.
+Read more:
 
-Read more: [Environment Validation](docs/environment-validation.md)
+- [Application Packaging](docs/application-packaging.md)
+- [Deployment](docs/deployment.md)
 
 ## Public entrypoints
 
@@ -257,6 +264,7 @@ Core commands:
 ```bash
 bcp dev
 bcp build
+bcp package
 bcp start
 bcp routes
 bcp update
@@ -322,12 +330,14 @@ app/
 
 ## Production build
 
+Raw standalone build:
+
 ```bash
 npm run build
 npm run start
 ```
 
-Standalone output:
+Output:
 
 ```text
 .bcp-framework/build/
@@ -337,17 +347,13 @@ Standalone output:
    └─ server.mjs
 ```
 
-The current production target remains:
+Deployment package:
 
-```text
-standalone-node
+```bash
+bcp package
 ```
 
-Native `.exe`, desktop and mobile compilation remain later roadmap work.
-
-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)
+Both current targets remain Node.js `standalone-node` applications. Production hardening includes configurable request/header/keep-alive/shutdown timeouts, trusted-proxy handling and graceful `SIGTERM` / `SIGINT` shutdown.
 
 ## Documentation Platform
 
@@ -367,7 +373,7 @@ Read more:
 
 - [Documentation Source Map](docs/README.md)
 - [Documentation Platform](docs/documentation-platform.md)
-- [Environment Validation](docs/environment-validation.md)
+- [Application Packaging](docs/application-packaging.md)
 
 ## Release validation
 
@@ -383,7 +389,7 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`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.
+`0.2.4` adds Application Packaging unit and prepared-package smoke checks covering production dependency metadata, production lock pruning, environment-value exclusion, deployment metadata and the `bcp package` CLI surface.
 
 Do not tag or publish until the final release commit passes the complete RC sequence.
 
@@ -400,24 +406,14 @@ Do not tag or publish until the final release commit passes the complete RC sequ
 | `0.2.0` | Framework Platform |
 | `0.2.1` | Documentation Platform |
 | `0.2.2` | Configuration & Environment v2 |
+| `0.2.3` | Database Platform v2 |
+| `0.2.4` | Application Packaging |
 
 ## Roadmap
 
-Next planned milestone:
-
-```text
-0.2.3 — Database Platform v2
-```
-
-Planned focus:
-
-- database adapter contract,
-- PostgreSQL support,
-- SQLite support,
-- connection lifecycle improvements,
-- migration consistency across providers.
+`0.2.4 — Application Packaging` establishes the deployment artifact contract for the existing standalone Node.js runtime.
 
-Application packaging remains later `0.2.x` roadmap work.
+The next planned framework milestone can build on this package contract without changing the current Node.js deployment model. Native `.exe`, desktop and mobile compilation remain later roadmap work.
 
 ## License
 

package/docs/api-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [
@@ -74,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

@@ -130,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/application-packaging.md

@@ -0,0 +1,243 @@
+# Application Packaging
+
+BCP Framework `0.2.4` adds an application packaging layer on top of the standalone Node.js production build.
+
+The goal is to turn a BCP project into a deployment-oriented directory that contains the built application, production dependency metadata, deployment metadata and container starter files without copying source-only development dependencies or project secrets.
+
+## Create a package
+
+From the application root:
+
+```bash
+bcp package
+```
+
+`bcp package` always runs a fresh production build first. This prevents an older `.bcp-framework/build` directory from being packaged accidentally.
+
+The output is written to:
+
+```text
+.bcp-framework/
+└── package/
+    ├── client/
+    ├── server/
+    │   └── server.mjs
+    ├── public/                 # when the application has public assets
+    ├── manifest.json
+    ├── package.json
+    ├── package-lock.json       # when a safe npm v3 production lock can be derived
+    ├── bcp.package.json
+    ├── bcp.deployment.json
+    ├── bcp.env.json
+    ├── Dockerfile
+    ├── .dockerignore
+    └── README.md
+```
+
+The current packaging target is:
+
+```text
+standalone-node
+```
+
+Native executable, desktop and mobile packaging are not part of `0.2.4`.
+
+## Production dependencies
+
+The generated package-level `package.json` keeps runtime metadata only:
+
+- `dependencies`
+- `optionalDependencies`
+- `peerDependencies`
+- supported peer metadata / overrides when present
+- `engines.node`
+- the standalone `start` script
+
+`devDependencies` are intentionally excluded.
+
+When the project has an npm lockfile v3 that can be safely converted to the production dependency graph, BCP writes a pruned `package-lock.json` and records:
+
+```bash
+npm ci --omit=dev
+```
+
+as the deployment install command.
+
+If a safe production lock cannot be derived, packaging continues without copying an unsafe lockfile and records:
+
+```bash
+npm install --omit=dev
+```
+
+instead. The CLI prints a warning in that case.
+
+This fallback is intentional: an application package must not pretend to be reproducibly locked when the framework cannot prove the lock metadata is safe for the standalone artifact.
+
+## Package manifest
+
+`bcp.package.json` describes the produced artifact. It includes:
+
+- schema version
+- target runtime
+- BCP Framework version
+- application name/version
+- Node.js requirement
+- entrypoint and start command
+- dependency installation command
+- whether a production lockfile is included
+- build/deployment/environment manifest paths
+- package file inventory
+- byte size and SHA-256 digest for each packaged file
+
+Example shape:
+
+```json
+{
+  "schemaVersion": 1,
+  "target": "standalone-node",
+  "frameworkVersion": "0.2.4",
+  "application": {
+    "name": "my-app",
+    "version": "0.1.0"
+  },
+  "runtime": {
+    "node": ">=24.11.0",
+    "entrypoint": "server/server.mjs",
+    "startCommand": "npm start"
+  },
+  "install": {
+    "command": "npm ci --omit=dev",
+    "lockfile": true,
+    "devDependenciesIncluded": false
+  }
+}
+```
+
+The file inventory allows deployment tooling to verify an application package before shipping it to a server or container image.
+
+## Deployment manifest
+
+`bcp.deployment.json` is a small deployment contract for the current package target. It records:
+
+```text
+runtime: Node.js
+install: npm ci --omit=dev (or npm install --omit=dev fallback)
+start: npm start
+entrypoint: server/server.mjs
+container starter: Dockerfile
+```
+
+Future deployment adapters can consume this manifest without changing the current standalone Node.js contract.
+
+## Environment manifest and secret safety
+
+BCP application packages do **not** copy project `.env` files.
+
+`bcp.env.json` contains metadata only. When files such as `.env.example` exist, BCP can record declared variable names, but it does not record their values.
+
+For example:
+
+```dotenv
+DATABASE_URL=postgresql://user:password@example/db
+BCP_SESSION_SECRET=secret
+```
+
+is represented only as names such as:
+
+```json
+{
+  "declaredKeys": [
+    "BCP_SESSION_SECRET",
+    "DATABASE_URL"
+  ],
+  "valuesIncluded": false,
+  "environmentFilesIncluded": false
+}
+```
+
+Supply real secrets through your deployment environment, secret manager or container/orchestrator configuration.
+
+Runtime server overrides remain available through:
+
+```text
+BCP_HOSTNAME
+BCP_PORT
+```
+
+## Run the package
+
+After copying `.bcp-framework/package` to the target machine:
+
+```bash
+cd package
+npm ci --omit=dev
+npm start
+```
+
+If `bcp.package.json` says `lockfile: false`, use the recorded install command instead.
+
+You can also start the bundled entrypoint directly after dependencies are installed:
+
+```bash
+node server/server.mjs
+```
+
+## Docker
+
+The generated package contains a starter `Dockerfile`:
+
+```bash
+docker build -t my-bcp-app .
+docker run --rm -p 3000:3000 my-bcp-app
+```
+
+Pass runtime environment values with the deployment mechanism you normally use. Do not bake secrets into the image.
+
+## Build vs package
+
+Use `bcp build` when you need the framework's raw standalone build output:
+
+```text
+.bcp-framework/build/
+```
+
+Use `bcp package` when you need a deployment-oriented artifact:
+
+```text
+.bcp-framework/package/
+```
+
+In short:
+
+```text
+source application
+    ↓
+bcp build
+    ↓
+standalone build
+    ↓
+bcp package
+    ↓
+deployment package + production metadata
+```
+
+## Determinism
+
+The packaging layer writes sorted dependency metadata and a sorted file inventory. File hashes are calculated from the final package content.
+
+The underlying BCP build currently retains its build identifier/timestamp behavior, so `0.2.4` does not promise byte-for-byte identical packages across independent build invocations. The integrity manifest is intended for verification of a specific produced artifact, not as a claim of fully reproducible builds.
+
+## Validation
+
+Framework release validation includes Application Packaging unit and packed-package smoke coverage.
+
+Recommended project validation is:
+
+```bash
+bcp package
+cd .bcp-framework/package
+npm ci --omit=dev
+npm start
+```
+
+Then exercise representative routes, API endpoints and any optional runtime providers used by the application.