@chidchanun/bcp 0.2.3 → 0.2.4

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.3",
+  "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" }
       ]
@@ -104,7 +105,8 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.3", "source": "releases/0.2.3.md", "version": "0.2.3", "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" },

package/docs/platform-manifest.json

@@ -1,13 +1,14 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "releaseState": "unreleased",
-  "baseline": "database-platform-v2",
+  "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",
@@ -58,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,
@@ -78,7 +86,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.2",
+    "previousBaseline": "0.2.3",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -90,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.3.md"
+    "releaseNotes": "releases/0.2.4.md"
   }
 }

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.3",
+  "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",