@chidchanun/bcp 0.2.2 → 0.2.4

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.

package/docs/database.md

@@ -1,18 +1,24 @@
 # Database
 
-BCP `0.1.14` adds the first framework-native database API through the server-only `bcp/database` entrypoint.
+BCP `0.2.3` completes Database Platform v2 behind the server-only `bcp/database` entrypoint.
 
-The initial adapter targets MySQL. Additional adapters can be added in later releases without changing the page, loader, guard or action APIs that consume the database layer.
+The public database facade is provider-neutral and currently includes built-in adapters for:
 
-## Create an app with MySQL
+- MySQL,
+- PostgreSQL,
+- SQLite.
+
+Applications can keep the same `db.query()`, `db.execute()`, `db.transaction()` and lifecycle API while selecting the provider through environment or explicit options.
+
+## MySQL
+
+Install the optional driver:
 
 ```bash
-npx create-bcp-app my-app
+npm install mysql2
 ```
 
-Choose **MySQL** during interactive setup. The generated project installs `mysql2`, writes the database environment variables and creates `lib/database.ts` as a thin wrapper around `bcp/database`.
-
-## Environment
+Environment:
 
 ```env
 DB_DRIVER=mysql
@@ -22,20 +28,105 @@ DB_USER=root
 DB_PASSWORD=
 DB_NAME=bcp_app
 DB_CONNECTION_LIMIT=10
-DB_WAIT_FOR_CONNECTIONS=1
-DB_QUEUE_LIMIT=0
-DB_CHARSET=utf8mb4
 ```
 
-Only `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD` and `DB_NAME` are required for the standard generated preset. The remaining values have safe framework defaults.
+MySQL remains the default when no provider can be inferred.
 
-## Query
+Parameterized query:
 
 ```ts
 import {
     db,
 } from "bcp/database";
 
+const users =
+    await db.query(
+        "SELECT id, email FROM users WHERE active = ?",
+        [
+            1,
+        ]
+    );
+```
+
+## PostgreSQL
+
+Install the optional driver:
+
+```bash
+npm install pg
+```
+
+BCP can infer PostgreSQL from a connection URL:
+
+```env
+DATABASE_URL=postgresql://postgres:password@localhost:5432/bcp_app
+```
+
+or use explicit fields:
+
+```env
+DB_DRIVER=postgresql
+DB_HOST=localhost
+DB_PORT=5432
+DB_USER=postgres
+DB_PASSWORD=password
+DB_NAME=bcp_app
+```
+
+PostgreSQL parameters use `$1`, `$2`, and later placeholders:
+
+```ts
+const users =
+    await db.query(
+        "SELECT id, email FROM users WHERE active = $1",
+        [
+            true,
+        ]
+    );
+```
+
+`postgres` and `pg` are accepted as environment aliases for the PostgreSQL driver and are normalized to `postgresql`.
+
+## SQLite
+
+Install the optional driver:
+
+```bash
+npm install better-sqlite3
+```
+
+Recommended environment:
+
+```env
+DB_DRIVER=sqlite
+DATABASE_URL=./data/bcp.sqlite
+```
+
+BCP also recognizes `:memory:`, `sqlite:` / `file:` URLs and common `.sqlite`, `.sqlite3`, and `.db` file names.
+
+Example:
+
+```ts
+import {
+    createDatabase,
+} from "bcp/database";
+
+const database =
+    createDatabase({
+        driver:
+            "sqlite",
+        database:
+            "./data/app.sqlite",
+    });
+```
+
+SQLite operations are serialized by the built-in adapter so async transaction callbacks cannot interleave unrelated queries on the same native connection.
+
+## Query and execute
+
+`query<T>()` is intended for row-returning statements:
+
+```ts
 interface UserRow {
     id: number;
     email: string;
@@ -43,28 +134,27 @@ interface UserRow {
 
 const users =
     await db.query<UserRow[]>(
-        "SELECT id, email FROM users WHERE active = ?",
-        [
-            1,
-        ]
+        "SELECT id, email FROM users"
     );
 ```
 
-## Execute
+`execute<T>()` is intended for mutations and DDL:
 
 ```ts
 const result =
     await db.execute(
-        "INSERT INTO users (email) VALUES (?)",
+        "DELETE FROM sessions WHERE expired_at < ?",
         [
-            "user@example.com",
+            new Date(),
         ]
     );
 ```
 
-Use placeholders and parameter arrays instead of concatenating untrusted values into SQL strings.
+Use the placeholder syntax of the active database provider. BCP does not rewrite application SQL between dialects.
 
-## Transaction
+## Transactions
+
+The transaction callback receives a provider-scoped `TransactionDatabase`:
 
 ```ts
 await db.transaction(
@@ -88,7 +178,33 @@ await db.transaction(
 );
 ```
 
-BCP commits the transaction when the callback resolves and rolls it back when the callback throws.
+The example above uses MySQL/SQLite placeholders. PostgreSQL migrations and application statements should use `$1`, `$2`, and so on.
+
+BCP commits when the callback resolves and rolls back when it throws.
+
+## Connection lifecycle
+
+Database instances remain lazy by default. Importing `bcp/database` does not connect to a provider.
+
+BCP `0.2.3` adds explicit lifecycle methods:
+
+```ts
+await db.connect();
+
+// application work
+
+await db.disconnect();
+```
+
+`close()` remains available as the backward-compatible shutdown method and is equivalent to `disconnect()`:
+
+```ts
+await db.close();
+```
+
+After disconnecting, the next operation or `connect()` call creates a fresh adapter connection/pool.
+
+If adapter initialization fails, BCP resets the pending lifecycle state so a later attempt can retry cleanly. Calling `close()` after a failed initialization is safe.
 
 ## Custom database instance
 
@@ -99,6 +215,8 @@ import {
 
 export const reportingDb =
     createDatabase({
+        driver:
+            "postgresql",
         host:
             "reporting-db.internal",
         database:
@@ -110,18 +228,69 @@ export const reportingDb =
 
 Explicit options override environment values for that database instance.
 
-## Lifecycle
+## Database adapter contract
 
-Connections are lazy. Importing `bcp/database` does not open a MySQL connection. The pool is created on the first `query`, `execute` or `transaction` call.
+Provider implementations use the shared adapter contract:
+
+```ts
+import type {
+    DatabaseAdapter,
+    TransactionDatabase,
+} from "bcp/database";
 
-For custom shutdown handling, close the pool with:
+const adapter: DatabaseAdapter = {
+    driver: "custom",
+
+    async connect() {},
+
+    async query<T>(sql, parameters) {
+        throw new Error("Not implemented");
+    },
+
+    async execute<T>(sql, parameters) {
+        throw new Error("Not implemented");
+    },
+
+    async transaction<T>(
+        callback: (
+            database: TransactionDatabase
+        ) => Promise<T>
+    ) {
+        throw new Error("Not implemented");
+    },
+
+    async disconnect() {},
+};
+```
+
+Inject an adapter directly or through a lazy factory:
 
 ```ts
-await db.close();
+export const customDb =
+    createDatabase({
+        adapter: () => adapter,
+    });
+```
+
+The contract lets future providers integrate without changing application-facing database calls.
+
+## Migrations
+
+Framework migration bookkeeping supports MySQL, PostgreSQL and SQLite in `0.2.3`.
+
+```bash
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
 ```
 
+BCP selects the internal migration-table dialect from the same active database environment. Migration files themselves remain normal provider SQL and are not automatically translated between SQL dialects.
+
+Read more: [Database Migrations](database-migrations.md)
+
 ## Server-only boundary
 
-`bcp/database` is a server-only package export. Importing it into a browser bundle is blocked by the framework's browser export boundary.
+`bcp/database` is a server-only package export. Importing it into a browser bundle is blocked by the framework browser export boundary.
 
-The MySQL adapter loads `mysql2/promise` only when a connection is first needed. Projects that do not use MySQL do not need to install the driver.
+Provider drivers are optional and loaded lazily. Projects only need to install the driver they actually use.

package/docs/deployment.md

@@ -6,7 +6,7 @@
 npm run build
 ```
 
-BCP writes the production artifact to `.bcp-framework/build`.
+BCP writes the raw production artifact to `.bcp-framework/build`.
 
 ```text
 .bcp-framework/build/
@@ -20,18 +20,79 @@ BCP writes the production artifact to `.bcp-framework/build`.
    └─ config.json
 ```
 
+Use the build directory when the deployment system already manages the application's production dependencies and artifact layout.
+
+## Application package — 0.2.4
+
+For a deployment-oriented directory, run:
+
+```bash
+bcp package
+```
+
+or from the framework repository/example script surface:
+
+```bash
+npm run package
+```
+
+`bcp package` runs a fresh production build and creates:
+
+```text
+.bcp-framework/package/
+├─ client/
+├─ server/
+│  └─ server.mjs
+├─ public/                 # when present
+├─ manifest.json
+├─ package.json
+├─ package-lock.json       # when a safe production lock can be derived
+├─ bcp.package.json
+├─ bcp.deployment.json
+├─ bcp.env.json
+├─ Dockerfile
+├─ .dockerignore
+└─ README.md
+```
+
+The package manifest excludes development dependencies. With a safely pruned npm v3 lockfile, install runtime dependencies with:
+
+```bash
+npm ci --omit=dev
+```
+
+If no package lock is included, follow the install command recorded in `bcp.package.json`/`bcp.deployment.json`.
+
+BCP does not copy `.env` files into the package. Provide environment values and secrets at deployment/runtime.
+
+See [Application Packaging](application-packaging.md) for the full packaging contract.
+
 ## Start
 
+For the raw build:
+
 ```bash
 npm start
 ```
 
-Or run the standalone bundle directly:
+or:
 
 ```bash
 node .bcp-framework/build/server/server.mjs
 ```
 
+Inside `.bcp-framework/package`, after production dependencies are installed:
+
+```bash
+npm start
+```
+
+which runs:
+
+```bash
+node server/server.mjs
+```
+
 ## Runtime server overrides
 
 The build retains the configured server defaults. Deployment can override the public bind address with supported runtime variables:
@@ -41,22 +102,34 @@ BCP_PORT
 BCP_HOSTNAME
 ```
 
-The CLI also supports:
+The CLI also supports the raw build runtime flow:
 
 ```bash
 bcp start --port 8080 --hostname 0.0.0.0
 ```
 
+For a packaged application, provide `BCP_PORT` and `BCP_HOSTNAME` through the runtime environment.
+
 ## Containers
 
-A minimal deployment image needs the standalone build plus the runtime dependencies required by the generated server bundle, including React/React DOM when they remain external to the bundle.
+`bcp package` generates a starter Dockerfile in `.bcp-framework/package`.
+
+```bash
+cd .bcp-framework/package
+docker build -t my-bcp-app .
+docker run --rm -p 3000:3000 my-bcp-app
+```
+
+Pass credentials and environment-specific settings through the container/orchestrator environment rather than baking them into the image.
 
-A typical application image can install production dependencies, copy `.bcp-framework/build`, expose the runtime port and execute `npm start` or `node .bcp-framework/build/server/server.mjs`.
+If you deploy the raw `.bcp-framework/build` directory instead, the image must separately include the runtime dependencies required by the generated server bundle, including React/React DOM when they remain external to the bundle.
 
 ## Reverse proxies
 
 BCP can run behind a reverse proxy or tunnel. Forward the original host correctly when application middleware or absolute URL construction depends on host information.
 
+Only enable trusted-proxy handling when the application process is actually isolated behind a trusted proxy/load balancer.
+
 ## Multiple instances
 
 The current response/data cache is process-local. If multiple containers or Node.js processes serve the application, each maintains independent cache entries and invalidation state.
@@ -68,7 +141,21 @@ Before deployment:
 ```bash
 npm run typecheck
 npm test
-npm run build
+bcp package
+```
+
+Then validate the deployment package:
+
+```bash
+cd .bcp-framework/package
+npm ci --omit=dev
+npm start
 ```
 
-For framework releases themselves, use `npm run release:check` in the framework repository.
+If `bcp.package.json` reports `lockfile: false`, use its recorded install command instead of `npm ci`.
+
+For framework releases themselves, use:
+
+```bash
+npm run rc:check
+```

package/docs/docs-web-manifest.json

@@ -1,19 +1,20 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.2",
+  "versionTarget": "0.2.4",
   "releaseState": "unreleased",
   "sections": [
     {
       "id": "getting-started",
       "title": "Getting Started",
-      "description": "Create, configure, deploy and update BCP applications.",
+      "description": "Create, configure, package, deploy and update BCP applications.",
       "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/application-packaging", "source": "application-packaging.md", "title": "Application Packaging" },
         { "route": "/docs/deployment", "source": "deployment.md", "title": "Deployment" },
         { "route": "/docs/updating", "source": "updating.md", "title": "Updating BCP" }
       ]
@@ -45,7 +46,7 @@
     {
       "id": "database",
       "title": "Database",
-      "description": "Database primitives, transactions and migration workflows.",
+      "description": "Provider-neutral MySQL, PostgreSQL and SQLite primitives, lifecycle and migrations.",
       "pages": [
         { "route": "/docs/database", "source": "database.md", "title": "Database" },
         { "route": "/docs/database-migrations", "source": "database-migrations.md", "title": "Database Migrations" }
@@ -104,7 +105,9 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.2", "source": "releases/0.2.2.md", "version": "0.2.2", "state": "unreleased" },
+    { "route": "/releases/0.2.4", "source": "releases/0.2.4.md", "version": "0.2.4", "state": "unreleased" },
+    { "route": "/releases/0.2.3", "source": "releases/0.2.3.md", "version": "0.2.3" },
+    { "route": "/releases/0.2.2", "source": "releases/0.2.2.md", "version": "0.2.2" },
     { "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" },