@chidchanun/bcp 0.2.2 → 0.2.4

package/docs/platform-manifest.json

@@ -1,13 +1,14 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "releaseState": "unreleased",
-  "baseline": "framework-platform",
+  "baseline": "application-packaging",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
-    "buildTarget": "standalone-node"
+    "buildTarget": "standalone-node",
+    "packageTarget": "standalone-node"
   },
   "publicEntrypoints": [
     "bcp",
@@ -25,6 +26,7 @@
   "cliCommands": [
     "dev",
     "build",
+    "package",
     "start",
     "routes",
     "update",
@@ -46,6 +48,11 @@
     "middlewareV2": true,
     "jwtCookieSessions": true,
     "databaseMigrations": true,
+    "databaseAdapterContract": true,
+    "databasePostgresql": true,
+    "databaseSqlite": true,
+    "databaseLifecycleV2": true,
+    "databaseMigrationProviderConsistency": true,
     "validation": true,
     "structuredErrors": true,
     "logging": true,
@@ -53,6 +60,12 @@
     "streamingUploads": true,
     "storageEcosystem": true,
     "productionHardening": true,
+    "applicationPackaging": true,
+    "productionDependencyPruning": true,
+    "deploymentManifest": true,
+    "environmentPackagingManifest": true,
+    "packageIntegrityManifest": true,
+    "dockerPackageStarter": true,
     "projectGenerators": true,
     "projectDiagnostics": true,
     "documentationPlatform": true,
@@ -61,6 +74,11 @@
     "configurationDiagnostics": true,
     "configCheckCli": true
   },
+  "databaseProviders": [
+    "mysql",
+    "postgresql",
+    "sqlite"
+  ],
   "storageProviders": [
     "local",
     "amazon-s3",
@@ -68,7 +86,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.1",
+    "previousBaseline": "0.2.3",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -80,7 +98,8 @@
     "documentationPlatform": "documentation-platform.md",
     "apiReference": "api-reference.md",
     "environmentValidation": "environment-validation.md",
+    "applicationPackaging": "application-packaging.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.2.md"
+    "releaseNotes": "releases/0.2.4.md"
   }
 }

package/docs/releases/0.2.3.md

@@ -0,0 +1,77 @@
+# BCP Framework 0.2.3
+
+## Database Platform v2
+
+BCP `0.2.3` turns the framework database layer into a provider-neutral SQL platform while preserving the existing `bcp/database` application API.
+
+### Database adapter contract
+
+- `BcpDatabase` delegates connection, query, execute, transaction and disconnect behavior through `DatabaseAdapter`.
+- Custom adapters can be injected directly or through lazy factories.
+- Provider implementations are separated into MySQL, PostgreSQL and SQLite runtime modules.
+- Provider drivers remain optional dependencies and are loaded lazily.
+
+### PostgreSQL
+
+- Added built-in PostgreSQL support through `pg`.
+- `DATABASE_URL=postgresql://...` selects PostgreSQL automatically.
+- `DB_DRIVER=postgresql`, `postgres` and `pg` are supported provider names.
+- Query parameters use PostgreSQL `$1`, `$2`, ... placeholders.
+- Transactions use dedicated pool clients with `BEGIN`, `COMMIT`, `ROLLBACK` and guaranteed client release.
+
+### SQLite
+
+- Added built-in SQLite support through `better-sqlite3`.
+- Supports file paths, `:memory:`, `sqlite:` and `file:` database locations.
+- Common `.sqlite`, `.sqlite3` and `.db` `DATABASE_URL` values infer SQLite automatically.
+- File-backed databases create missing parent directories before opening the native database.
+- Adapter operations are serialized so async transaction callbacks do not interleave unrelated operations on one SQLite connection.
+
+### Connection lifecycle
+
+- Added explicit `database.connect()`.
+- Added explicit `database.disconnect()`.
+- Existing `database.close()` remains backward compatible and aliases the disconnect lifecycle.
+- Disconnecting resets the facade so a later operation can initialize a fresh provider connection.
+- Failed adapter initialization resets cleanly and can be retried.
+- `close()` is safe after failed adapter initialization.
+
+### Migration consistency
+
+The existing CLI remains unchanged:
+
+```bash
+bcp db create create_users
+bcp db migrate
+bcp db status
+bcp db rollback
+```
+
+Migration bookkeeping now selects its internal SQL dialect from the active database provider:
+
+- MySQL uses `AUTO_INCREMENT` and `?` placeholders.
+- PostgreSQL uses `BIGSERIAL` and `$1`, `$2` placeholders.
+- SQLite uses `INTEGER PRIMARY KEY AUTOINCREMENT` and `?` placeholders.
+
+BCP only makes the internal `_bcp_migrations` bookkeeping provider-aware. Application migration SQL is intentionally not translated between SQL dialects.
+
+### Packaging and validation
+
+- Added Database Platform v2 package smoke coverage.
+- Packed framework validation checks provider modules, bundled optional-driver references, lifecycle APIs and migration dialect support.
+- Added unit coverage for SQLite option resolution, provider inference, lifecycle reconnect behavior, failed adapter initialization and migration dialects.
+
+## Compatibility
+
+`0.2.3` does not intentionally remove public application entrypoints from the `0.2.2` baseline.
+
+Existing MySQL applications can continue using:
+
+```ts
+import {
+    db,
+    createDatabase,
+} from "bcp/database";
+```
+
+without changing their application-facing database calls.

package/docs/releases/0.2.4.md

@@ -0,0 +1,152 @@
+# BCP Framework 0.2.4 — Application Packaging
+
+> **Release state:** unreleased development target until validation, RC checks, tagging and npm publication complete.
+
+BCP Framework `0.2.4` adds a deployment-oriented application packaging layer on top of the existing standalone Node.js production build.
+
+## Highlights
+
+- new `bcp package` CLI command
+- every package starts from a fresh production build
+- deployment output under `.bcp-framework/package/`
+- production-only `package.json`
+- npm v3 production lockfile pruning when it can be performed safely
+- `npm ci --omit=dev` deployment contract when a production lock is available
+- safe `npm install --omit=dev` fallback when a lock cannot be derived
+- `bcp.package.json` artifact/integrity manifest
+- `bcp.deployment.json` runtime/deployment contract
+- `bcp.env.json` environment metadata without secret values
+- generated Dockerfile and `.dockerignore`
+- SHA-256 inventory for packaged files
+- unit and prepared-package smoke coverage
+
+## Command
+
+```bash
+bcp package
+```
+
+The command performs:
+
+```text
+production environment/config validation
+    ↓
+fresh bcp build
+    ↓
+standalone-node packaging
+    ↓
+production dependency metadata
+    ↓
+deployment + environment manifests
+    ↓
+file integrity inventory
+```
+
+## Output
+
+```text
+.bcp-framework/package/
+├── client/
+├── server/
+│   └── server.mjs
+├── public/                 # when present
+├── manifest.json
+├── package.json
+├── package-lock.json       # when safely derivable
+├── bcp.package.json
+├── bcp.deployment.json
+├── bcp.env.json
+├── Dockerfile
+├── .dockerignore
+└── README.md
+```
+
+The current package target remains:
+
+```text
+standalone-node
+```
+
+## Production dependency pruning
+
+Application source `devDependencies` are not copied to the package manifest.
+
+When an npm lockfile v3 can be reduced safely to the production dependency graph, BCP writes the reduced lockfile and deployment uses:
+
+```bash
+npm ci --omit=dev
+```
+
+If the lockfile contains unsupported metadata such as unsafe workspace links, BCP leaves it out and explicitly records the fallback:
+
+```bash
+npm install --omit=dev
+```
+
+## Secret safety
+
+Application packaging never copies `.env` files into the deployment artifact.
+
+`bcp.env.json` records declared environment variable names discovered from example files only. It explicitly records that environment values and environment files are not embedded.
+
+Provide credentials, database URLs, session secrets and storage keys through the deployment environment or a secret manager.
+
+## Container starter
+
+The package includes a Node 24 Alpine Dockerfile. A basic flow is:
+
+```bash
+cd .bcp-framework/package
+docker build -t my-bcp-app .
+docker run --rm -p 3000:3000 my-bcp-app
+```
+
+## Compatibility
+
+`0.2.4` does not intentionally remove or rename the `0.2.3` public package entrypoints.
+
+Existing applications may continue using:
+
+```bash
+bcp build
+bcp start
+```
+
+`bcp package` is additive and is intended for deployment artifact creation.
+
+## Reproducibility scope
+
+The packaging layer normalizes production dependency metadata and writes sorted file inventories with SHA-256 digests.
+
+The existing production build still contains build-time identity/timestamp metadata, so `0.2.4` does not claim byte-for-byte reproducible artifacts across separate build invocations.
+
+## Validation
+
+Before publication run:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+For an application-level packaging smoke test:
+
+```bash
+bcp package
+cd .bcp-framework/package
+npm ci --omit=dev
+npm start
+```
+
+If `bcp.package.json` reports that no lockfile was included, use the install command recorded in that manifest.
+
+## Related documentation
+
+- [Application Packaging](../application-packaging.md)
+- [Deployment](../deployment.md)
+- [Production Hardening](../production-hardening.md)
+- [Configuration](../configuration.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",