@chidchanun/bcp 0.2.17 → 0.2.18

package/docs/deployment-platform-v2.md

@@ -0,0 +1,449 @@
+# Deployment Platform v2
+
+BCP Framework `0.2.18` adds a server-only deployment lifecycle layer through `bcp/deployment` and hardens published production entrypoints so application runtime code does not need to execute framework TypeScript directly.
+
+## Goals
+
+Deployment Platform v2 provides:
+
+- application resource startup ordering;
+- reverse-order graceful shutdown;
+- startup rollback when a later resource fails;
+- readiness checks for orchestrators/load balancers;
+- runtime diagnostics and deployment identity;
+- `SIGTERM` / `SIGINT` integration;
+- integration with the existing BCP shutdown-hook registry;
+- compiled production runtimes for key server entrypoints.
+
+It does not replace Kubernetes, Docker, systemd, PM2 or another process orchestrator. BCP provides lifecycle primitives that those systems can drive.
+
+## Create a deployment runtime
+
+```ts
+import {
+    createDeploymentRuntime,
+} from "bcp/deployment";
+
+export const deployment =
+    createDeploymentRuntime({
+        serviceName: "orders-api",
+        version: "1.4.0",
+    });
+```
+
+Runtime states are:
+
+```text
+idle
+starting
+ready
+draining
+stopped
+failed
+```
+
+## Register resources
+
+Resources are started in registration order and stopped in reverse order.
+
+```ts
+deployment.addResource({
+    name: "database",
+
+    async start() {
+        await db.connect();
+    },
+
+    async ready() {
+        return {
+            ok:
+                db.status ===
+                "ready",
+            detail:
+                db.status,
+        };
+    },
+
+    async stop() {
+        await db.close();
+    },
+
+    diagnostics() {
+        return {
+            provider:
+                "postgresql",
+        };
+    },
+});
+```
+
+Then register dependent services later:
+
+```ts
+deployment.addResource({
+    name: "jobs",
+
+    async start() {
+        workers.start();
+    },
+
+    async stop() {
+        await workers.stop();
+    },
+});
+```
+
+Starting:
+
+```ts
+await deployment.start();
+```
+
+produces:
+
+```text
+database.start()
+    ↓
+jobs.start()
+    ↓
+state = ready
+```
+
+Shutdown reverses the order:
+
+```text
+jobs.stop()
+    ↓
+database.stop()
+    ↓
+state = stopped
+```
+
+## Startup rollback
+
+If a resource fails during startup, already-started resources are stopped in reverse order.
+
+```text
+database.start() ✅
+jobs.start()     ✅
+realtime.start() ❌
+
+rollback:
+
+jobs.stop()
+database.stop()
+```
+
+The runtime moves to `failed` and `start()` rejects.
+
+## Resource context
+
+Lifecycle callbacks receive:
+
+```ts
+{
+    metadata,
+    signal,
+}
+```
+
+`signal` is aborted when shutdown begins. Long-running BCP/application components can use it to stop accepting new work or cancel background loops.
+
+## Readiness
+
+```ts
+const report =
+    await deployment.readiness();
+```
+
+A runtime is ready only when:
+
+1. runtime state is `ready`;
+2. all registered resources are in the started state;
+3. every resource readiness function reports success.
+
+Create an HTTP response directly:
+
+```ts
+import {
+    createDeploymentReadinessResponse,
+} from "bcp/deployment";
+
+export function GET() {
+    return createDeploymentReadinessResponse(
+        deployment
+    );
+}
+```
+
+Successful readiness returns HTTP `200`. A non-ready runtime returns `503`.
+
+The response uses:
+
+```text
+Cache-Control: no-store
+```
+
+Recommended route:
+
+```text
+/api/ready
+```
+
+Do not place authentication/user data in this endpoint when it is consumed by infrastructure health probes.
+
+## Diagnostics
+
+```ts
+const diagnostics =
+    await deployment.diagnostics();
+```
+
+The report includes:
+
+- service/deployment identity;
+- process ID;
+- Node version;
+- platform/architecture;
+- runtime state;
+- uptime;
+- lifecycle state for each registered resource;
+- optional resource-specific diagnostic metadata.
+
+An HTTP response helper is available:
+
+```ts
+import {
+    createDeploymentDiagnosticsResponse,
+} from "bcp/deployment";
+
+export function GET() {
+    return createDeploymentDiagnosticsResponse(
+        deployment
+    );
+}
+```
+
+Diagnostics can reveal infrastructure details. Protect the route when exposing it outside a trusted operations network.
+
+## Deployment metadata
+
+The runtime accepts explicit identifiers:
+
+```ts
+createDeploymentRuntime({
+    serviceName:
+        "orders-api",
+    deploymentId:
+        "deploy-20260831-01",
+    instanceId:
+        "orders-api-7f5d9",
+    release:
+        "2026.08.31",
+    environmentName:
+        "production",
+});
+```
+
+Or resolve them from runtime environment variables:
+
+```text
+BCP_DEPLOYMENT_ID
+BCP_INSTANCE_ID
+BCP_RELEASE
+NODE_ENV
+```
+
+If `BCP_DEPLOYMENT_ID` is not supplied, BCP generates a UUID for the process.
+
+## Shutdown timeout
+
+Default shutdown timeout:
+
+```text
+10 seconds
+```
+
+Configure it explicitly:
+
+```ts
+createDeploymentRuntime({
+    serviceName: "orders-api",
+    shutdownTimeoutMs:
+        30_000,
+});
+```
+
+or through:
+
+```dotenv
+BCP_SHUTDOWN_TIMEOUT_MS=30000
+```
+
+The timeout is shared by reverse-order resource shutdown. If a resource does not finish before the remaining deadline, shutdown records the failure and eventually rejects with `AggregateError`.
+
+## Signal handling
+
+Install handlers:
+
+```ts
+const removeSignals =
+    deployment.installSignalHandlers();
+```
+
+Default signals:
+
+```text
+SIGTERM
+SIGINT
+```
+
+The handlers start graceful shutdown and set `process.exitCode` rather than immediately calling `process.exit()`. This allows pending cleanup/microtasks to finish.
+
+Remove handlers when ownership moves elsewhere:
+
+```ts
+removeSignals();
+```
+
+Custom signal set:
+
+```ts
+deployment.installSignalHandlers({
+    signals: [
+        "SIGTERM",
+    ],
+});
+```
+
+## Existing BCP shutdown hooks
+
+Deployment runtime can participate in the existing production-hardening shutdown registry:
+
+```ts
+const unregister =
+    deployment.registerShutdownHook();
+```
+
+When the framework executes registered shutdown hooks, the deployment runtime drains its resources.
+
+Use either direct signal ownership or integrate with an application-level signal coordinator. Avoid installing multiple independent handlers that all own the same resource lifecycle.
+
+## Recommended topology
+
+```text
+Load balancer / orchestrator
+          │
+          ├── readiness probe
+          │       ↓
+          │   bcp/deployment
+          │
+          └── SIGTERM
+                  ↓
+          state = draining
+                  ↓
+        stop inbound/realtime
+                  ↓
+          stop workers/jobs
+                  ↓
+          close database
+                  ↓
+          state = stopped
+```
+
+## Jobs and workflow workers
+
+Register workers as resources so they stop before shared dependencies such as Redis or SQL connections:
+
+```ts
+deployment.addResource({
+    name: "workers",
+
+    start() {
+        worker =
+            jobs.startWorker();
+    },
+
+    async stop() {
+        await worker.stop();
+    },
+});
+```
+
+Register database/cache connections before workers. Reverse-order shutdown then naturally stops workers before closing their dependencies.
+
+## Realtime
+
+For realtime transports, mark the system not-ready before closing shared storage/transport resources. Runtime state changes to `draining` before resource stop hooks run, so readiness probes begin returning `503` while shutdown is in progress.
+
+## Observability
+
+Deployment metadata can be attached to logs/traces:
+
+```ts
+const metadata =
+    deployment.metadata;
+
+logger.info(
+    "runtime ready",
+    {
+        deploymentId:
+            metadata.deploymentId,
+        instanceId:
+            metadata.instanceId,
+        release:
+            metadata.release,
+    }
+);
+```
+
+Use `bcp/observability` for trace/span correlation and `bcp/deployment` for process/deployment identity and lifecycle state.
+
+## Compiled server runtimes
+
+Prepared `bcp` packages now compile these production entrypoints:
+
+```text
+bcp/cache          -> cache.mjs
+bcp/config         -> config.mjs
+bcp/database       -> database.mjs
+bcp/auth           -> auth.mjs
+bcp/jobs           -> jobs.mjs
+bcp/workflow       -> workflow.mjs
+bcp/events         -> events.mjs
+bcp/realtime       -> realtime.mjs
+bcp/testing        -> testing.mjs
+bcp/plugins        -> plugins.mjs
+bcp/observability  -> observability.mjs
+bcp/deployment     -> deployment.mjs
+bcp/server         -> server.mjs
+bcp/middleware     -> middleware.mjs
+```
+
+Type declarations/source types remain available from the TypeScript source entrypoint while runtime resolution points to compiled ESM in prepared npm packages.
+
+This reduces reliance on Node TypeScript stripping for server framework runtime entrypoints and provides a more deterministic production package.
+
+## Compatibility
+
+`0.2.18` is intended to be backward compatible with `0.2.17`.
+
+Existing:
+
+```text
+bcp build
+bcp package
+npm start
+registerShutdownHook()
+```
+
+remain available. `bcp/deployment` is additive.
+
+## Related guides
+
+- [Application Packaging](application-packaging.md)
+- [Deployment](deployment.md)
+- [Production Hardening](production-hardening.md)
+- [Observability Platform v3](observability-v3.md)
+- [Background Jobs](background-jobs.md)
+- [Realtime Platform](realtime-platform.md)

package/docs/docs-web-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "versionTarget": "0.2.17",
+  "versionTarget": "0.2.18",
   "releaseState": "unreleased",
   "sections": [
     {
@@ -58,13 +58,14 @@
     {
       "id": "runtime",
       "title": "Runtime & Infrastructure",
-      "description": "Middleware, jobs, scheduling, workflows, event delivery, realtime channels, observability, distributed caching, security and production hardening.",
+      "description": "Middleware, jobs, scheduling, workflows, event delivery, realtime channels, observability, deployment lifecycle, distributed caching, security and production hardening.",
       "pages": [
         { "route": "/docs/middleware", "source": "middleware.md", "title": "Middleware" },
         { "route": "/docs/hydration", "source": "hydration.md", "title": "Hydration" },
         { "route": "/docs/development-logging", "source": "development-logging.md", "title": "Logging" },
         { "route": "/docs/observability", "source": "observability.md", "title": "Observability Platform v2" },
         { "route": "/docs/observability-v3", "source": "observability-v3.md", "title": "Observability Platform v3" },
+        { "route": "/docs/deployment-platform-v2", "source": "deployment-platform-v2.md", "title": "Deployment Platform v2" },
         { "route": "/docs/background-jobs", "source": "background-jobs.md", "title": "Background Jobs Platform" },
         { "route": "/docs/job-scheduling", "source": "job-scheduling.md", "title": "Job Scheduling Platform" },
         { "route": "/docs/durable-jobs", "source": "durable-jobs.md", "title": "Durable Jobs Platform" },
@@ -118,7 +119,8 @@
     }
   ],
   "releases": [
-    { "route": "/releases/0.2.17", "source": "releases/0.2.17.md", "version": "0.2.17", "state": "unreleased" },
+    { "route": "/releases/0.2.18", "source": "releases/0.2.18.md", "version": "0.2.18", "state": "unreleased" },
+    { "route": "/releases/0.2.17", "source": "releases/0.2.17.md", "version": "0.2.17" },
     { "route": "/releases/0.2.16", "source": "releases/0.2.16.md", "version": "0.2.16" },
     { "route": "/releases/0.2.15", "source": "releases/0.2.15.md", "version": "0.2.15" },
     { "route": "/releases/0.2.14", "source": "releases/0.2.14.md", "version": "0.2.14" },

package/docs/platform-manifest.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "framework": "bcp",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "releaseState": "unreleased",
-  "baseline": "observability-platform-v3",
+  "baseline": "deployment-platform-v2",
   "runtime": {
     "node": ">=24.11.0",
     "react": "19",
@@ -26,6 +26,7 @@
     "bcp/testing",
     "bcp/plugins",
     "bcp/observability",
+    "bcp/deployment",
     "bcp/server",
     "bcp/server-only",
     "bcp/middleware"
@@ -82,6 +83,18 @@
     "traceMetricsExporter": true,
     "traceLogFields": true,
     "compiledObservabilityRuntime": true,
+    "deploymentPlatformV2": true,
+    "deploymentRuntimeLifecycle": true,
+    "deploymentResourceRegistry": true,
+    "deploymentReadiness": true,
+    "deploymentDiagnostics": true,
+    "deploymentSignalHandling": true,
+    "deploymentShutdownHooks": true,
+    "deploymentRuntimeMetadata": true,
+    "compiledConfigRuntime": true,
+    "compiledAuthRuntime": true,
+    "compiledServerRuntime": true,
+    "compiledMiddlewareRuntime": true,
     "backgroundJobsPlatform": true,
     "jobQueueAdapterContract": true,
     "inMemoryJobQueue": true,
@@ -211,7 +224,7 @@
     "s3-compatible"
   ],
   "compatibility": {
-    "previousBaseline": "0.2.16",
+    "previousBaseline": "0.2.17",
     "intentionalBreakingChangesFromPreviousBaseline": false,
     "migrationGuide": "migration-0.2.md"
   },
@@ -229,6 +242,7 @@
     "authorizationSecurity": "authorization-security.md",
     "observability": "observability.md",
     "observabilityV3": "observability-v3.md",
+    "deploymentPlatformV2": "deployment-platform-v2.md",
     "backgroundJobs": "background-jobs.md",
     "jobScheduling": "job-scheduling.md",
     "durableJobs": "durable-jobs.md",
@@ -239,6 +253,6 @@
     "pluginModulePlatform": "plugin-module-platform.md",
     "cachePlatformV2": "cache-platform-v2.md",
     "migrationGuide": "migration-0.2.md",
-    "releaseNotes": "releases/0.2.17.md"
+    "releaseNotes": "releases/0.2.18.md"
   }
 }

package/docs/releases/0.2.18.md

@@ -0,0 +1,136 @@
+# BCP Framework 0.2.18 — Deployment Platform v2
+
+Status: **unreleased**
+
+`0.2.18` adds a framework-native deployment lifecycle and hardens prepared npm runtime entrypoints for standalone Node production use.
+
+## Highlights
+
+### New `bcp/deployment` entrypoint
+
+```ts
+import {
+    createDeploymentRuntime,
+} from "bcp/deployment";
+```
+
+Deployment runtime provides:
+
+- ordered resource startup;
+- reverse-order graceful shutdown;
+- startup rollback;
+- readiness checks;
+- deployment/process diagnostics;
+- deployment/instance/release metadata;
+- `SIGTERM` / `SIGINT` handling;
+- integration with existing BCP shutdown hooks.
+
+### Readiness endpoints
+
+```ts
+return createDeploymentReadinessResponse(
+    deployment
+);
+```
+
+Ready runtime returns `200`; non-ready/draining/failed runtime returns `503`.
+
+### Diagnostics
+
+```ts
+return createDeploymentDiagnosticsResponse(
+    deployment
+);
+```
+
+Diagnostics include process/runtime identity, uptime and resource lifecycle state plus optional resource diagnostics.
+
+### Runtime identity
+
+Supported runtime environment values:
+
+```text
+BCP_DEPLOYMENT_ID
+BCP_INSTANCE_ID
+BCP_RELEASE
+NODE_ENV
+BCP_SHUTDOWN_TIMEOUT_MS
+```
+
+### Compiled production entrypoints
+
+Prepared framework packages now use compiled ESM runtime files for additional server-side entrypoints:
+
+```text
+bcp/config       -> config.mjs
+bcp/auth         -> auth.mjs
+bcp/deployment   -> deployment.mjs
+bcp/server       -> server.mjs
+bcp/middleware   -> middleware.mjs
+```
+
+Existing compiled server runtimes such as cache/database/jobs/workflow/events/realtime/testing/plugins/observability remain compiled as before.
+
+This closes a packaging gap where several server entrypoints still resolved directly to TypeScript in the published package.
+
+## Public API additions
+
+```text
+createDeploymentRuntime
+createDeploymentReadinessResponse
+createDeploymentDiagnosticsResponse
+
+DeploymentRuntime
+DeploymentRuntimeOptions
+DeploymentRuntimeState
+DeploymentResource
+DeploymentResourceContext
+DeploymentResourceStatus
+DeploymentReadinessResult
+DeploymentReadinessReport
+DeploymentDiagnosticsReport
+DeploymentMetadata
+DeploymentSignalOptions
+DeploymentShutdownOptions
+```
+
+## Lifecycle model
+
+```text
+idle
+  ↓
+starting
+  ↓
+ready
+  ↓
+draining
+  ↓
+stopped
+```
+
+Failures move the runtime to `failed`.
+
+## Compatibility
+
+There are no intentional breaking changes from `0.2.17`.
+
+Existing production hardening APIs, shutdown hooks, `bcp build`, `bcp package` and application package manifests remain supported.
+
+`bcp/deployment` is additive.
+
+## Validation
+
+Before tagging/publishing:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+The `0.2.18` package smoke validates the compiled deployment runtime plus compiled config/auth/server/middleware entrypoints from the prepared `.package/bcp` staging directory.
+
+Do not tag/publish until the final commit passes the complete RC sequence.