@chidchanun/bcp 0.2.3 → 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.3 — Database Platform v2`
+> **Development target:** `0.2.4 — Application Packaging`
 >
-> `0.2.3` 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, `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.
+`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:
 
@@ -43,7 +43,7 @@ docs/api-manifest.json
 | 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
@@ -80,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:
 
@@ -91,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
@@ -125,114 +112,23 @@ 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:
+Validate configuration and declared environment values with:
 
 ```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.
+Variables beginning with `BCP_PUBLIC_` may be embedded in browser output. Never expose application secrets through public-prefixed variables.
 
-`secret: true` is tooling metadata; it does not encrypt environment values.
+Read more:
 
-Read more: [Environment Validation](docs/environment-validation.md)
+- [Configuration](docs/configuration.md)
+- [Environment Validation](docs/environment-validation.md)
 
 ## Database Platform v2 — 0.2.3
 
-Application code uses the same server-only entrypoint across supported SQL providers:
+Application code uses one server-only database entrypoint across supported SQL providers:
 
 ```ts
 import {
@@ -241,7 +137,7 @@ import {
 } from "bcp/database";
 ```
 
-Built-in providers:
+Built-in SQL providers:
 
 ```text
 mysql
@@ -249,7 +145,7 @@ postgresql
 sqlite
 ```
 
-Connections remain lazy, while explicit lifecycle control is available when needed:
+Lifecycle control:
 
 ```ts
 await db.connect();
@@ -261,7 +157,7 @@ await db.disconnect();
 
 `db.close()` remains available for backward-compatible shutdown handling.
 
-Database migrations use the same CLI across providers:
+Migration CLI:
 
 ```bash
 bcp db create create_users
@@ -270,13 +166,71 @@ bcp db status
 bcp db rollback
 ```
 
-BCP makes its internal migration bookkeeping provider-aware. Application SQL itself is not automatically translated between SQL dialects.
+BCP makes framework migration bookkeeping provider-aware. Application migration SQL itself is not automatically translated between SQL dialects.
 
 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
+```
+
+Framework-repository development can also run:
+
+```bash
+npm run package
+```
+
+Output:
+
+```text
+.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
+```
+
+The package layer:
+
+- 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.
+
+The current package target is:
+
+```text
+standalone-node
+```
+
+Native executable, desktop, Android and iOS packaging remain later roadmap work.
+
+Read more:
+
+- [Application Packaging](docs/application-packaging.md)
+- [Deployment](docs/deployment.md)
+
 ## Public entrypoints
 
 The current `0.2.x` platform contract recognizes:
@@ -310,6 +264,7 @@ Core commands:
 ```bash
 bcp dev
 bcp build
+bcp package
 bcp start
 bcp routes
 bcp update
@@ -375,12 +330,14 @@ app/
 
 ## Production build
 
+Raw standalone build:
+
 ```bash
 npm run build
 npm run start
 ```
 
-Standalone output:
+Output:
 
 ```text
 .bcp-framework/build/
@@ -390,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
 
@@ -420,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
 
@@ -436,7 +389,7 @@ npm run test:e2e
 npm run rc:check
 ```
 
-`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.
+`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.
 
@@ -454,12 +407,13 @@ Do not tag or publish until the final release commit passes the complete RC sequ
 | `0.2.1` | Documentation Platform |
 | `0.2.2` | Configuration & Environment v2 |
 | `0.2.3` | Database Platform v2 |
+| `0.2.4` | Application Packaging |
 
 ## Roadmap
 
-`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.
+`0.2.4 — Application Packaging` establishes the deployment artifact contract for the existing standalone Node.js runtime.
 
-The next planned `0.2.x` focus is application packaging. Native `.exe`, desktop and mobile compilation remain later 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.3",
+  "version": "0.2.4",
   "releaseState": "unreleased",
   "coverage": "public-entrypoints",
   "entrypoints": [

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.